# Offline permitted-observation assembler Version 1.0. **Development tooling; defaults are unfrozen.** Tests use temporary artificial formatting fixtures, not task answers, model completions, or actual study inputs. No model or experiment is run. Existing prompts, archival/packet tools, accounting, assessment, and analysis remain unchanged. This supplies the explicit assembly step for [protocol §5](../03-experimental-protocol.md). It renders the complete, unchanged [matched treatment reference](../treatment-ablations/treatment-reference.txt) into one planner request. Inspection found no existing compatible renderer; the existing placeholder, artifact/directive, typed-memory, and history conventions are reused. This version assembles the reference treatment only, not the ablations or baseline optimizers, and does not validate a future planner response or deliver a follow-up to a worker. ## Local use Python 3.9+ and the standard library are sufficient. Copy [manifest.template.json](manifest.template.json), fill the explicit inputs, and select two **new, disjoint directories with existing parents**: ```sh python3 -B assemble_observation.py --manifest /coordinator/observation.json \ --model-dir /staging/new-planner-input \ --provenance-dir /coordinator/new-observation-record ``` Only `new-planner-input/planner-input.txt` is model-facing. The separate `assembly-record.json` contains source paths/hashes, manifest hash, chronology, bounds, token-count attestation, and rendered-input hash. Do not attach it, the input manifest, prior planner responses, or a directory listing to the model request. Exit 0 reports the two paths and output hash. Exit 2 emits an error on stderr. No input file is modified. Existing destinations, including empty directories and symlinks, are refused; outputs are created exclusively. Validation failures create no output directories. An I/O failure can leave partial new outputs; use only after successful exit and a complete matching provenance record, and retry with fresh paths. Directory separation is organizational, not confidentiality enforcement. ## Manifest contract The root has exactly `manifest_version` (`"1.0"`), `assembly_id`, `template`, `task_packet`, `current_artifact`, `earlier_artifacts`, `previous_instructions`, `memory`, and `bounds`. `assembly_id` is coordinator-only and never rendered. Unknown fields, including assessor/ratings/report/trace/resource channels, are rejected. Paths resolve relative to the manifest, or may be absolute. Every declared file descriptor requires its expected lowercase SHA-256. Data files must be UTF-8; the tool reads bytes and decodes without newline conversion, Unicode normalization, summarization, or factual rewriting. | Input | Exact descriptor fields | |---|---| | `template` | `path`, `sha256`; the hash is pinned to the existing treatment-reference bytes | | `task_packet` | `task_id`, `path`, `sha256`; the whole immutable public packet, including authorized sources | | `current_artifact` | `artifact_id`, `sequence`, `path`, `sha256`; required, explicitly designated by the coordinator | | Each `earlier_artifacts` entry | Same artifact fields, in explicit chronological order | | Each `previous_instructions` entry | `instruction_id`, `sequence`, `path`, `sha256`; the exact submitted worker **directive text only** | | `memory` | `path`, `sha256`, `token_attestation`; file contains the live typed memory array, not a whole previous planner response | Artifact sequences are positive integers; earlier entries must strictly increase and precede the current sequence. Submitted-directive sequences strictly increase and cannot exceed the current worker-turn sequence. No sorting, recency inference, directory discovery, or automatic selection of prior snapshots occurs. The coordinator must supply the intended most recent bounded history. Distinct artifact identities cannot alias the same resolved source path. Identical text in separately identified artifacts is allowed. Repeated directive text can legitimately use the same source file with distinct instruction IDs/sequences. Task, public requirement/source, artifact, instruction, and memory IDs must remain unambiguous and unique in their respective supplied context. The public packet uses the completed tasks' Markdown convention: `# TASK_ID…`, requirement definitions `- **R1:** …`, and authorized source headings `### S1 …`. The assembler extracts defined IDs from that single supplied file; it reads no task registry, assessor guide, answer key, or reference file mentioned inside the packet. Duplicate definitions or missing requirement/source definitions are rejected. All twelve existing packets use this convention. A different packet format needs a separately versioned adapter, not inferred parsing of arbitrary reports. Use empty arrays for absent earlier artifacts or instructions, and a declared memory JSON file containing `[]` for empty memory. On the first planning step the current artifact is still required; history and memory can be empty. There is no implicit chat state, fabricated initial observation, or null current artifact. Normal matched-history collection should retain the actual submitted initial directive when applicable; the assembler cannot discover omitted submissions. It neither creates memory nor carries it between calls. ## Typed memory, evidence, and limits Memory must be an array within the declared entry/byte bounds. Every entry has exactly `id`, `kind`, `statement`, `evidence`, and `status`. Kinds are `observation` or `provisional_tactic`; statuses are `current`, `unresolved`, or `superseded`. Statements are nonempty strings. Each nonempty evidence array contains objects with **exactly one** of `artifact_id`, `source_id`, or `requirement_id`, plus a nonempty `location` string. The identifier must occur in the current/earlier supplied artifacts or in the public packet's defined requirement/source IDs. Other fields, multiple identifier fields per reference, and unknown identifiers are rejected. This is identifier membership and location-string validation, not verification that a quoted location exists, that an observation follows from it, or that a previous defect persists. Historical artifact references outside the supplied window fail validation; the tool never silently deletes, repairs, or relinks memory entries. A future caller must resolve that input/policy mismatch explicitly under its frozen memory/observation procedure, retaining superseded state in the offline audit rather than importing extra artifact history. All bounds are explicit in the manifest. The blank template supplies **reversible development defaults**: at most two earlier artifacts, twelve prior directives, 32 memory entries, and a maximum declared memory allowance of 1,200 tokens. Caller limits can be smaller; they cannot exceed the matched two-artifact/twelve-directive/1,200-token limits. Byte defaults are 256 KiB per task or artifact, 32 KiB per directive or raw/serialized memory value, and 2 MiB for the rendered request. These engineering bounds are not a model-context guarantee, token estimate, or registered study configuration. Excess input is rejected, never silently truncated or padded. The template's 800-token follow-up and 1,200-token memory **output** caps remain verbatim; smaller input bounds do not rewrite them. ## Token-count attestation and deterministic rendering The standard library supplies no model tokenizer. For **nonempty memory**, require `token_attestation` with exactly `tokenizer` (a nonempty declared identifier), `serialized_sha256`, and `token_count` (positive integer within the caller's memory token cap). The count must refer to the canonical serialized JSON **value**, including array/record syntax, not the raw file's indentation. Canonicalization is `json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False)`; SHA-256 covers its UTF-8 bytes. The module's `canonical` and `sha` helpers expose that exact representation. Count it with the intended tokenizer outside this tool, without model execution, and bind the result to its hash. The tool checks hash binding and the declared count's type/cap; it **cannot independently verify the count or tokenizer claim**. Provenance records say so. Empty `[]` memory may use null attestation; no exact token-count claim is then made even for its JSON syntax. Byte/entry caps remain enforced. Do not present this structural check as proof of tokenizer-level budget compliance. All five placeholders are replaced once using canonical JSON values. Only the public packet string, `{artifact_id,text}` objects, `{instruction_id,text}` objects, and the typed memory array enter the template. File paths, sequences, bounds, hashes, assembly IDs, and attestations remain outside the model-facing payload. JSON escaping preserves supplied text after decoding, including CRLF, quotes, tabs, and non-ASCII characters. Rendering is deterministic for the same template/input values. Any surviving `{{…}}` marker, including a literal marker in supplied text, is rejected rather than recursively expanded or removed. The reference template is hash-pinned; changing its principles, scaffold, or output contract requires an explicit new adapter version, not an override flag. ## Information-boundary limits and checks The tool reads only the manifest and its declared template/task/artifact/directive/memory files. It does not follow links in text, scan directories, discover history, inspect archival manifests, import assessment utilities/data, or open undeclared operational files. Known `assessor-only`/`resource-accounting` input paths and recognizable rating/key/inventory filenames are blocked as accidental boundary violations; these pathname guards are not a semantic detector. The coordinator remains responsible for designating a genuinely public immutable packet, exported deliverables, submitted directives without recursively appended old packets, and permitted memory. Structural schemas, matching hashes, IDs, and chronology **cannot establish semantic provenance or detect restricted content copied/renamed and mislabeled as an artifact, instruction, source, or memory statement**. They cannot prove that instructions were submitted, that the packet was unchanged historically, that the current artifact is latest, or that no report/score was embedded in ordinary text. A successful assembly is not evidence that the observation boundary was substantively respected. Audit those questions independently; do not add a hidden semantic evaluator during strict adaptation. ```sh python3 -B -m unittest -v test_assemble_observation.py ``` Tests use temporary artificial files for deterministic rendering, exact decoded text, empty initial state, typed references, excessive history/bytes, token-attestation binding, chronology/identity errors, excluded metadata, UTF-8/hash failures, unresolved markers, unchanged template instructions, explicit read sets, and output collision refusal. No task answers, actual study inputs, model calls, experiments, API spending, production changes, or submissions are generated.