coulomb-social/docs/release/corpus-import-inspection-2026-10-31.md

Inspecting uncertain corpus imports

CSOC-WP-0014-T07 preparation. The receipt-backed importer now reserves the new Space UUID in its durable started checkpoint before import writes. Its SQL operation creates that exact UUID exclusively. A competing row at the slug or reserved UUID refuses instead of being updated or receiving imported grants. The committed return must still have the reserved identity before completion. Ordinary imports without receipt mode retain their existing behavior.

This closes an identity gap in the earlier checkpoint implementation: a started receipt previously named no intended SQL identity, and the underlying generic importer could update an existing same-tenant row when its content tree was absent. Legacy completed checkpoints remain usable. Legacy started checkpoints remain uncertain and are reported as identity-unbound; no identity is invented for them.

Read-only inspection

The new management command is:

python manage.py inspect_content_corpus /private/reviewed/manifest.json \
  --receipt-dir /private/import-attempt

It requires the original manifest/source/mapping/destination binding and an existing checkpoint and lock files. It does not create missing directories or locks. It takes the existing importer/content locks without invoking content recovery, then reads SQL in one transaction. PostgreSQL uses REPEATABLE READ, READ ONLY. It compares destination and checkpoint bookends and rechecks source hashes before reporting. These cooperating locks are not proof of an external writer fence; the report explicitly records that limit.

Output contains unit indexes, classifications, counts and hashes, without source bodies, identity names or SQL rows. It binds the checkpoint bytes and observed SQL, grants and files. Classifications distinguish:

• A reserved identity whose current source-derived metadata, mapped grants and complete source file hashes match.
• A reserved identity with differences, including later content, metadata, grant or original-date changes.
• Foreign/replacement identities, files without SQL, or SQL without files.
• No SQL row or published tree, which does not establish absence of staging.
• Older started receipts without a reserved identity.
• Pending destinations and the continued presence of completed identities.

Original space dates are compared when supplied by the source index; absence is reported. Insertion/update timestamps that cannot be derived from source are fingerprinted, not fabricated. A matching result does not prove that no intervening edit ever occurred. Synthesized indexes or omitted extra source files cannot be called byte-exact by the whole-tree comparison. Completed units may have later edits; their original receipt remains historical evidence, not an overwrite target. Unattributed .import-* entries are counted, never assigned to an attempt or removed.

Every result explicitly says that no checkpoint was completed, no retry was authorized and no data was restored. The inspector does not convert started to completed or pending. The deployment owner must still reconcile the specific uncertain state with its retained backup, writer fence and reviewed operation. Do not remove the checkpoint or use replacement import to bypass uncertainty.

The subsequent matching-commit procedure adds a separate, explicit checkpoint operation for one exactly matching reserved commit. Inspection itself remains read-only. Partial, changed, unbound and unattributed-staging states still require owner reconciliation.

Verification and release boundary

Fifteen new cases cover matching committed state without receipt, partial stores, legacy/unrelated identities, later edits/grants, original dates, active locks, missing paths, changing observations and occupied-slug refusal. The existing real process-exit tests now inspect both the pre-write and committed-without-receipt states while proving unchanged checkpoints. A row inserted after corpus preflight is retained without imported grants or destination files.

Full make check: 629 passed, 69 existing warnings, zero failures/errors/skips in 71.11s, including the required browser journeys. Ruff and whitespace checks pass. Log: /tmp/csoc-import-inspection-check-20261031.log.

scripts/rehearse-import-inspection.py also runs the corpus, receipt and inspection tests against disposable PostgreSQL 16.14 on an internal Docker network with no published ports. It passed 60 checks of actual inspection transactions' read-only and repeatable-read modes. Current source and locked development dependencies are explicit read-only overlays on the cached application image; this is not packaged-candidate or production proof. Its containers, anonymous test volumes and network were removed. Source-bound receipt: corpus-import-inspection-postgres-2026-10-31.json.

No live cohort, grant, deployment, release pin or previously reviewed executor changed. T07 remains in progress: source/identity/grant reconciliation, a concrete owner procedure for uncertain imports, supervised executor integration, release, fresh backup/fencing, native postflight and productive acceptance remain required.