Research quarantine promotion

Research Quarantine Promotion

Close the trust boundary between downloaded quarantine bytes and a content-aware research tool. Version 1.0.5 implements only the conservative strict-json-b0-v1 structure gate: it never copies the payload or emits source keys, strings, URLs, excerpts, or semantic fields.

Read the contract

Read references/contract.md before authoring a binding or invoking the CLI. Use these offline schemas for authoring and review:

• promotion-binding-v1.schema.json
• source-verification-receipt-v1.schema.json
• assessment-report-v1.schema.json
• assessment-event-v1.schema.json

The Python CLI is authoritative. It uses exact-field validation and does not load a remote schema or follow $ref, @context, URL, file path, or payload instruction.

Preserve the boundary

• Start only from one successful research-source-acquisition run whose manifest, rights, events, payload identity, and exact file set have been preregistered.
• Require a new, exclusive source-verification receipt produced by the pinned source-acquisition implementation through the binding's dedicated research-run-ledger after the checkpoint. A historical exit code, hand-written JSON, or receipt without matching stdout/output evidence is not a substitute.
• Keep the original payload in quarantine. Never move, chmod, rename, delete, overwrite, copy, normalize, or publish it.
• Require binding schema 1.1 identity guards and the metadata-only publish boundary to pass before any assessment artifact, including an error artifact, may be created. A receipt, execution ledger, log directory, or attempt inside the acquisition run—or any overlap among those four roles—must return without writing. Existing components are compared by descriptor-backed device/inode ancestry; unresolved components are conservatively compared after Unicode normalization and case folding. At command start, the acquisition run, receipt parent, run-ledger parent, and log directory are opened as one identity-checked descriptor group and kept alive until preflight returns, assessment publication finishes, or producer verification returns. Every acquisition metadata, receipt, run-ledger, log, and payload read is relative to those retained descriptors. Their current pathnames are rebound to the retained device/inode identities before the first attempt write, between writes, and after final fsync; the payload directory entry must also retain the exact source-execution/scanned inode. A late failure removes the still-pinned incomplete attempt instead of leaving pass/block artifacts.
• Run preflight before any payload access. Stop unless it reports payload_opened: false.
• Let the binding select the only run, payload identity, profile, provenance material, implementation bytes, receipt path, and output attempt. Do not add ad hoc CLI overrides.
• Treat evidence, rights, receipt, path, hash, race, and ledger failures as error/invalid, not as JSON content negatives.
• Treat only strict JSON syntax or fixed resource-profile failures as block.
• Treat pass-candidate as strict-json-structure-check-passed / internal-research-only. It does not establish content truth, IIIF semantics, carrier/locator admission, D2/D3 rights, trusted-human review, L2/L4, ResearchCase SRC, academic evidence, or public release.
• Preserve every pass, block, error, stdout, stderr, report, event chain, and independent review. Never widen the profile and retry under the same promotion ID.

Prepare the binding

Create one strict JSON binding from the schema and contract. Freeze it before the source receipt or purpose-specific B0 payload access. It must bind:

1. the preregistration path, SHA-256, and size;
2. the acquisition run and all five fixed file identities;
3. the future receipt path, its bound parent device/inode, and pinned source verifier;
4. a dedicated future run-ledger manifest, its bound parent device/inode, a pre-created empty 0700 artifact directory with bound device/inode, run ID, current Python executable, pinned run-ledger implementation and repo cwd;
5. the three-layer rights statuses without upgrading them;
6. the entire current provenance ledger, head, material registration, and latest verification;
7. this script, contract, and four schemas by exact path/hash/size;
8. one new attempt directory whose basename is the promotion ID and whose existing parent device/inode is bound;
9. the acquisition run's current device/inode, current-user ownership and exact 0700 mode.

Do not derive the profile, rights, output path, limits, or allowed capabilities from the payload. Keep the receipt, run-ledger manifest/log directory and attempt outside the acquisition run and outside one another.

Preflight without opening the payload

python3 scripts/quarantine_promotion.py preflight \
  --binding /absolute/promotion-binding.json

Preflight reads only metadata and performs lstat-level payload checks. It may run before the future receipt exists. Require exit 0, status: ready, and both payload-open fields to be false. Record the command with research-run-ledger; a preflight PASS is only permission to complete the checkpoint and later source verification.

Produce a fresh source receipt

After the preregistration, implementation, tests, independent audit, binding, preflight evidence, and Git checkpoint are frozen, invoke the pinned source verifier through the dedicated research-run-ledger command frozen in the binding. Its child argv is:

python3 ../research-source-acquisition/scripts/source_acquisition.py verify \
  --run-directory /absolute/quarantine/acquisition-run \
  --run-directory-identity DEVICE:INODE \
  --receipt /absolute/new/source-verification-receipt.json \
  --receipt-parent-identity DEVICE:INODE

Declare the pinned Python executable, run-ledger script, source-verifier script and all five acquisition files as exact inputs, and the new receipt as the only snapshot output. Invoke run-ledger with the binding's manifest-parent and artifact-directory identity guards, and require its publication_boundaries evidence to equal the binding. Require research-run-ledger 1.1.3: every declared input must carry its device/inode identity before and after the child, and the runner must reserve capacity for the complete start/finish pair before launch. Promotion reconstructs those identities from current files; for the payload it uses only descriptor-relative stat, so an identity replacement fails before payload bytes are opened. Continue only when the two-event ledger verifies with unchanged input bytes and identities, exit 0, empty stderr, stdout bytes exactly equal the receipt, ok: true, status: verified, and no mismatches. Preserve a non-passing receipt as a negative result and stop.

Assess once

python3 scripts/quarantine_promotion.py assess \
  --binding /absolute/promotion-binding.json

Assessment verifies the receipt, its dedicated execution ledger and metadata, opens only the manifest-derived payload relative to the retained bound acquisition-run descriptor with no-follow/single-link controls, requires that inode to equal the source-execution identity, hashes and parses the same bounded buffer with an incremental, no-AST scanner, and keeps all four source directory pins through a new two-file attempt. The writer pins both the attempt parent and the newly created attempt directory through the complete exclusive-write, exact-file-set, fsync, and failure-cleanup transaction. The expected attempt-parent identity is carried from the publish boundary into the descriptor-relative create, so a pathname replacement between validation and publication fails before mkdir.

Expected exits:

• 0: pass-candidate;
• 5: content block;
• 3: integrity error;
• 2: invocation error before a safe attempt can be established.

The report contains only identities, gate states, schema-fixed numeric structure counters and limits, capability denials, zero content-exposure counters, and the proof boundary. There is no canonical derivative in B0.

Verify the producer artifact

python3 scripts/quarantine_promotion.py verify \
  --attempt-directory /absolute/PROMOTION-ID

Verification reopens the current source and recomputes the complete binding, receipt, metadata, rights, provenance, structure, report, exact two-file set, and event chain while retaining the same four bound directory descriptors. It performs one final pathname and payload-inode rebind immediately before return. It returns the same status class as the assessment when the artifact remains reproducible; any tamper or drift returns integrity exit 3.

Afterward, verify the outer run ledger with --check-files and obtain an independent no-content-leak/outcome audit.

Stop after B0

Whether the result is pass, block, or error, stop this cycle after producer, run-ledger, and independent verification. Canonical materialization, IIIF field extraction, canvas/frame selection, locator construction, per-frame rights, OCR, evidence-card creation, and knowledge-network work require new Skills or profiles with new preregistration and review. B0 is not an adapter that bypasses those gates.