WS-ART-001-03B4: continue verified guide sufficiency

.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/AUTH_HANDOFF.md

@@ -28,6 +28,43 @@ activation custody, and availability.
    permission or inherit Project Manager authority.
 6. ART-03C performs the legacy clean cut. No ART chunk writes availability.
 
+### Exact AUTH-04B Activation Manifest
+
+AUTH-04B may activate only these two existing planned actions after every
+split-03B merge is present:
+
+- `artifact.guide_source.binding.create`, mapped only to existing permission
+  `artifact.binding.create` and fixed service identity
+  `workstream.artifact.binding`. Its transaction-bound facts are exactly:
+  `project_id`, `guide_id`, `guide_source_snapshot_id`,
+  `guide_source_item_id`, `project_setup_run_id`, `setup_generation`,
+  `content_id`, `verified_replica_id`, `sha256`, `byte_count`, and the fixed
+  `logical_role=guide_source_original`.
+- `artifact.guide_source.read`, mapped only to its existing read permission and
+  fixed service identity `workstream.artifact.guide_reader`. Its fresh
+  transaction-bound facts are exactly: `project_id`, `guide_id`,
+  `guide_source_snapshot_id`, `guide_source_item_id`, `project_setup_run_id`,
+  `setup_generation`, `binding_id`, `content_id`, `verified_replica_id`,
+  `storage_namespace_id`, `namespace_fingerprint`, `verification_receipt_id`,
+  `verification_generation`, `sha256`, `byte_count`, and `media_type`.
+
+Both consumers lock and revalidate the draft guide, latest snapshot, exact
+source item, current setup run/generation, verified content, replica, and
+receipt lineage before consuming the opaque prepared handle and before any
+protected mutation or provider read. Prepared handles are process-local,
+single-use, action/session/transaction/resource bound, and never enter Celery.
+Wrong service, action, session, transaction, generation, project, guide,
+snapshot, item, binding, content, replica, receipt, digest, size, media type,
+replay, copied handle, replacement, or stale lineage denies before provider I/O
+or mutation.
+
+ART-03B4 adds no new AUTH action. The sufficiency continuation receives only
+project, guide, snapshot, setup-run, and setup-generation identifiers, reloads canonical
+rows, and consumes only complete policy-current extraction usages. Both actions
+must remain planned and unavailable until AUTH-04B merges. They are never
+granted to a Project Manager, never inherit uploader authority, and do not
+create generic artifact-download authority.
+
 ## Submission Bundle Sequence
 
 Before ART-04A starts, AUTH must merge a separately reviewed registration

.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md

@@ -28,7 +28,7 @@ Each chunk is one PR. No later chunk starts automatically.
 | `WS-ART-001-03B3B3C` | Add bounded PPTX extraction on the approved OOXML capability. | L1 | Proposed after 03B3B3A |
 | `WS-ART-001-03B3B3D` | Add bounded XLSX extraction on the approved OOXML capability. | L1 | Proposed after 03B3B3A |
 | `WS-ART-001-03B3B4` | Install only the approved image dependency and add PNG/JPEG/WebP structural metadata extraction. | L1 | Proposed after 03B3B1 approval |
-| `WS-ART-001-03B4` | Feed only complete same-generation canonical extracted material into the existing Celery sufficiency pipeline. | L1 | Proposed after 03B3B2, 03B3B3B, 03B3B3C, 03B3B3D, and 03B3B4 |
+| `WS-ART-001-03B4` | Feed only complete same-generation canonical extracted material into the existing Celery sufficiency pipeline. | L1 | Active; all prerequisites through 03B3B4 merged |
 | `WS-ART-001-03C` | Remove legacy guide-source identity and add exact same-generation setup continuation. | L1 | Proposed after 03B1-03B4 and AUTH-04B |
 | `WS-ART-001-04A` | Accept one outer ZIP in bounded scratch, safely inspect its tree, normalize executable intent, produce canonical identities, and reject unchanged work before provider I/O. | L1 | Proposed after 03C and AUTH planned action registration |
 | `WS-ART-001-04B` | Run mandatory platform and locked Project Guide pre-submit checks against the same scratch-bound tree and executable semantics without durable storage. | L1 | Proposed after 04A |

.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md

@@ -58,8 +58,11 @@ the guide-content boundary is being corrected explicitly: verified binding,
 full-read materialization, format classification, isolated extraction,
 canonical extraction provenance, incremental complex-format support, and
 same-generation sufficiency continuation are separate PR-sized contracts.
-`WS-ART-001-03B1` is the first proposed
-implementation successor; this planning change contains no implementation.
+`WS-ART-001-03B4` is active: its reviewed contract fixes the artifact-owned
+material port, all-items-required semantics, deterministic 12 MiB assembly,
+normalized report-to-extraction provenance, and the hidden pre-submit
+identifier/generation continuation. AUTH binding/read actions remain planned
+and unavailable; ART-03C remains blocked on AUTH-04B.
 
 After 03B3A merged, the original complex-format chunk was found too broad for
 one dependency and parser-security review. It is replaced by 03B3B1 dependency
@@ -82,8 +85,9 @@ wheel and adds the shared bounded OPC/OOXML container security capability.
 03B3B3B merged through PR #234. It adds bounded DOCX extraction and durable
 omission facts on the shared OOXML boundary. 03B3B3C merged through PR #235 and
 adds bounded PPTX slide/notes extraction. 03B3B3D merged through PR #238 and
-adds bounded XLSX cell extraction. 03B3B4 is the active successor and adds only
-bounded PNG/JPEG/WebP structural metadata. AUTH and sufficiency work remain
+adds bounded XLSX cell extraction. 03B3B4 merged through PR #239 and adds only
+bounded PNG/JPEG/WebP structural metadata. 03B4 is now the active hidden
+same-generation sufficiency continuation. AUTH binding/read actions remain
 inactive.
 
 AUTH `WS-XINT-002-04B` follows the complete hidden split-03B series and

.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/chunks/WS-ART-001-03B4-guide-sufficiency-continuation.md

@@ -1,7 +1,9 @@
 # Chunk Contract: WS-ART-001-03B4 — Guide Sufficiency Continuation
 
-Initiative: `WS-ART-001` | Risk: L1 | Status: Proposed after 03B3B2,
-03B3B3B, 03B3B3C, 03B3B3D, and 03B3B4
+Initiative: `WS-ART-001` | Risk: L1 | Status: Approved for implementation
+
+Merged prerequisites: 03B1, 03B2, 03B3A, 03B3B1, 03B3B2, 03B3B3A,
+03B3B3B, 03B3B3C, 03B3B3D, and 03B3B4.
 
 ## Goal
 
@@ -10,15 +12,37 @@ same-generation canonical guide material and exact persisted provenance.
 
 ## Allowed Files
 
-- existing project-setup Celery task/queue and setup-run generation fields;
-- project service/repository and agent input schemas consuming typed canonical
-  extraction records;
-- in-place evolution or replacement of existing `GuideSourceMaterial` and
-  `GuideSourceItemMaterial`; no parallel sufficiency-material model;
-- sufficiency-report usage provenance; extraction models/migration remain owned
-  by 03B3A and complex adapter provenance remains owned by 03B3B2-03B3B4;
-- focused stale-delivery, completeness, incident, unsupported, broker replay,
-  agent-input, persistence, cancellation, and coverage tests; related docs.
+- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/PLAN.md`
+- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/DECISIONS.md`
+- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/RISKS.md`
+- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md`
+- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/AUTH_HANDOFF.md`
+- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/CHUNK_MAP.md`
+- this chunk contract and its review/trust-bundle files;
+- `docs/spec_artifact_storage_service.md`;
+- `docs/architecture_data_model.md`;
+- `backend/app/interfaces/project_agents.py` and
+  `backend/app/interfaces/artifact_operations.py`;
+- `backend/app/modules/artifacts/guide_sufficiency_material.py` (new narrow
+  artifact-owned query/validation adapter);
+- `backend/app/modules/artifacts/models.py` only for the exact extraction-usage
+  composite uniqueness needed by provenance foreign keys;
+- `backend/app/modules/projects/models.py`, `repository.py`, `schemas.py`, and
+  `service.py` for setup orchestration and report provenance;
+- `backend/app/modules/projects/setup_queue.py` and the existing Celery
+  project-setup execution module for the pre-submit identifier payload;
+- `backend/app/modules/projects/guide_mutation_router.py` to dispatch that exact
+  committed generation;
+- `backend/app/modules/projects/guide_mutation_service.py` to carry the exact
+  generation across the post-commit dispatch boundary;
+- `backend/app/adapters/project_agents/openai_agent_sdk.py` so the runtime sends
+  the same canonical bytes that setup hashes and caps;
+- one new Alembic revision after `0045_guide_source_metadata_authority.py`;
+- `backend/tests/test_projects.py`, `backend/tests/test_guide_bindings.py`,
+  `backend/tests/test_artifact_architecture.py`, and `backend/tests/conftest.py`
+  for the canonical isolated-database table inventory;
+- `backend/scripts/run_test_lanes.py` only if the new focused test selection must
+  be registered without weakening an existing lane.
 
 ## Not Allowed
 
@@ -27,10 +51,54 @@ same-generation canonical guide material and exact persisted provenance.
   as authoritative input; policy derivation after incomplete extraction;
   legacy-field removal; AUTH availability edits.
 
+The existing post-submit continuation is outside this payload change and keeps
+its effective-policy and checker-policy identifiers. This chunk changes only
+the pre-submit guide-sufficiency Celery message. The legacy source-material
+path remains available for the existing live setup flow until 03C; it must not
+be used by the new hidden verified continuation.
+
+## Locked Design
+
+- Every item in the immutable source snapshot is required in v0.1. There is no
+  optional-item flag. Every item needs one current-generation binding and one
+  successful, policy-current extraction usage.
+- Text-family, PDF, DOCX, PPTX, CSV, XLSX, Markdown, plain-text, and JSON outputs
+  enter the bounded textual material. PNG/JPEG/WebP output enters only as typed
+  structural metadata and cannot satisfy textual semantics. No legacy durable
+  ref, CID, caller excerpt, or raw binary enters authoritative material.
+- An artifact-owned `GuideSufficiencyMaterialPort` performs all joins over ART
+  binding, content, classification, attempt, extracted-content, and usage rows.
+  Project services consume only its immutable DTO and never import or query ART
+  persistence models.
+- Each item DTO contains source item id/order/kind, binding id, original content
+  id/hash/byte count, classification id/format, extraction attempt/usage/content
+  ids, extractor name/version, extraction-policy version, canonical-output hash,
+  omission facts, and exactly one of canonical text or typed structural metadata.
+- Canonical agent bytes are the exact compact sorted-key UTF-8 JSON prompt sent
+  by the runtime. Every ordered item contains the fixed
+  `UNTRUSTED_GUIDE_SOURCE_DATA` label; no caller-selectable delimiter is used.
+  The 12 MiB limit counts the complete prompt, including trusted guide context,
+  labels, JSON punctuation, escaping, and separators. `12 * 1024 * 1024` bytes
+  passes; one byte more fails before agent invocation.
+- Agent-created sufficiency provenance is normalized. The report stores setup
+  run id, setup generation, assembled-material SHA-256, and byte count. A child
+  usage row per item stores report id, item order, source item id, binding id,
+  original content id, extraction usage/attempt/content ids, and canonical-output
+  SHA-256. Composite foreign keys bind each child to one exact ART usage lineage;
+  report/item order and report/extraction usage are unique.
+- Immediately before agent invocation, the adapter locks and validates the exact
+  draft guide, latest snapshot, setup run/generation, every snapshot item, and
+  every ART lineage row. Immediately before report commit the same facts are
+  locked and revalidated and the material digest must match. Report, provenance
+  children, and setup-run output reference commit once or all roll back.
+- The new verified continuation is hidden and callable only with bounded test
+  authority until AUTH-04B. It does not silently replace the live legacy setup
+  continuation in this chunk. 03C owns that cutover.
+
 ## Acceptance Criteria
 
-- project-setup Celery payload is exactly project, guide, snapshot, setup run, and
-  setup generation identifiers;
+- the pre-submit project-setup Celery payload is exactly project, guide,
+  snapshot, setup run, and setup generation identifiers;
 - the project-setup executor reloads and revalidates current
   project/guide/snapshot/run/generation,
   complete bindings, content, and extraction provenance before agent invocation
@@ -60,9 +128,9 @@ same-generation canonical guide material and exact persisted provenance.
 
 ```bash
 (cd backend && .venv/bin/python -m ruff check app tests scripts)
-(cd backend && WORKSTREAM_TEST_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream_test .venv/bin/pytest tests/test_project_setup.py tests/test_guide_artifacts.py tests/test_guide_extraction.py tests/test_project_agents.py -q --cov=app --cov-report=term-missing --cov-fail-under=0)
+(cd backend && .venv/bin/python scripts/run_isolated_tests.py --metadata-json /tmp/ws-art-03b4.json --timeout-seconds 900 -- .venv/bin/python -m pytest tests/test_projects.py tests/test_guide_bindings.py tests/test_artifact_architecture.py -q --cov=app --cov-report=term-missing --cov-fail-under=0)
 (cd backend && .venv/bin/coverage report --precision=2 --fail-under=78)
-(cd backend && .venv/bin/coverage report --include='app/modules/projects/*,app/*ers/project_setup.py' --precision=2 --fail-under=90)
+(cd backend && .venv/bin/coverage report --include='app/modules/projects/*,app/modules/artifacts/guide_sufficiency_material.py,app/*ers/project_setup.py' --precision=2 --fail-under=90)
 python3 scripts/check_stale_artifact_contracts.py
 python3 scripts/check_markdown_links.py
 python3 scripts/test_agent_gates.py

.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/reviews/WS-ART-001-03B4-external-review-response.md

@@ -0,0 +1,66 @@
+# WS-ART-001-03B4 External Review Response
+
+## Comments addressed
+
+- Fixed the Backend semantic-lane interruption by adding the exact
+  `setup_generation` keyword to the remaining enqueue-failure test stub.
+- Moved generation-invariant validation before the guide transaction commit.
+- Moved the latest-generation read behind the locked guide/setup header and
+  reject stale generations from that locked transaction.
+- Require image structural extraction output to decode to a JSON object.
+- Preserve distinct conflict, unavailable, stale, artifact, and sanitized
+  unexpected-failure setup codes.
+- Added report provenance shape, digest, size, and generation constraints plus
+  the child canonical-output digest constraint in ORM and migration.
+- Wrapped non-finite and unsupported-value prompt serialization as the
+  port-owned runtime error.
+- Added missing queue/task argument docs and corrected captured-payload typing.
+- Strengthened tests for obsolete extraction exclusion, exact prompt byte count,
+  atomic setup-run output linkage, migration restoration, constraints, and
+  absolute/relative persistence-import boundary detection.
+- Added the ART material adapter to the focused 90 percent coverage command.
+- Reconciled the closed artifact-interface export assertion with the three
+  canonical guide-sufficiency value types exposed by that interface.
+- Recreated the async database engine after the migration downgrade/upgrade
+  boundary. The round-trip test owns table and column restoration; the shared
+  clean-schema fingerprint gate remains the single canonical assertion for the
+  complete constraint catalogue, avoiding duplicate order-sensitive schema
+  custody inside an ordinary semantic lane.
+- Advanced the canonical Alembic test head from the merged `0045` revision to
+  this chunk's `0046_guide_sufficiency` revision so every downgrade guard
+  restores and asserts the actual repository head.
+- Added the generic stale `ProjectServiceError` worker outcome to the focused
+  failure matrix, closing the remaining worker coverage gap without changing
+  production behavior.
+
+## Comments deferred
+
+- Legacy four-argument Celery compatibility is intentionally not added. This
+  hidden continuation has never been activated in production, so no legitimate
+  deployed messages exist; deriving a missing generation would weaken the exact
+  generation fence required by the approved contract.
+- The per-item locked ART query remains because v0.1 source item counts are
+  bounded and the explicit per-item completeness check is easier to audit. A
+  set-based optimization has no correctness benefit in this chunk.
+- The long verified continuation is not refactored during review repair. Named
+  helper extraction would be behavior-neutral but adds unnecessary churn across
+  a transaction-sensitive method after correctness review.
+
+## Human decisions needed
+
+None. Deferred suggestions do not change the approved product or security
+boundary.
+
+## Commands rerun
+
+- Ruff over backend application, tests, and scripts.
+- Focused architecture, queue failure, router, prompt, migration, exact material,
+  provenance/replay, stale-contract, authorization-doc, and Markdown-link checks.
+- Hosted Agent Gates on the repaired PR head; Backend is rerun after each exact
+  semantic-lane repair.
+
+## Remaining risks
+
+The hidden verified continuation remains unavailable until AUTH-04B. ART-03C
+still owns live legacy cutover; no compatibility fallback may bypass the exact
+setup-generation identity.