feat(auth): activate prepared guide source ingest

[Abiorh001]

Workstream PR Trust Bundle

Chunk

WS-XINT-002-04A - Activate prepared guide-source ingest authorization

Goal

Activate only artifact.guide_source.ingest for a covered Project Manager through the shared opaque, transaction-bound PREP protocol.

Intent And Planning Context

• Intent: authorize guide ZIP ingestion without creating an ART-local authority path.
• Chunk contract: .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/chunks/WS-XINT-002-04A-guide-ingest-activation.md
• Planning correction: PR docs(xint): correct guide ingest activation contract #217, merged to main.

What Changed

• Added the existing ingest permission only to Project Manager policy.
• Activated only artifact.guide_source.ingest under WS-XINT-002-04A custody.
• Added typed guide-ingest resource facts and human PREP preparation/consumption.
• Added ART locking for project, draft guide, snapshot, and source item.
• Bound server-computed digest, size, media type, request digest, actor, identity link, and matched grant.
• Added strict denial, transaction, replay, lineage, custody, audit, and coverage tests.
• Corrected CodeRabbit findings for ART custodian and artifact inventory counts.

Why It Changed

ART-03A installed the opaque authorization seam but intentionally kept ingestion unavailable. This chunk installs the exact AUTH adapter and fail-closed policy required to expose that flow safely.

Design Chosen

Prepare Project Manager authority before reading bytes. During the caller-owned root transaction, lock the final ART lineage, compute server-owned byte facts, consume the same opaque capability, persist authorization evidence with admission, commit once, and only then permit provider I/O.

Alternatives Rejected

• Raw AuthorizationContext as mutation authority.
• An ART-local authorization protocol.
• Consuming before final lineage and byte facts exist.
• Generic guide download or broader artifact activation.
• Lowering coverage or CI thresholds.

Scope Control

Allowed Files Changed

All changed files are listed in the approved 04A chunk contract, including the canonical custody ledger, authorization and artifact modules, focused tests, service specifications, and review records.

Files Outside Stated Scope

• None.

Product Behavior

• No Workstream product behavior changed.
• Product behavior changed and is explained here: covered Project Managers may ingest guide-source bytes through the prepared authorization path; guide read and binding remain unavailable.

Evidence

Commands Run

• Ruff across backend app/tests/scripts.
• Focused guide artifact, audit, authorization, and admission tests.
• Stale authorization documentation check.
• Stale artifact contract check.
• Markdown link check.
• Git diff check.
• GitHub Backend full-suite and coverage workflow.
• GitHub Agent Gates.

Result Summary

Local focused checks pass. All required internal implementation reviewers passed. GitHub Agent Gates pass. A fresh exact-head Backend run and CodeRabbit incremental review are running after the external-review correction.

Acceptance Criteria Proof

• Active covered Project Manager grant is required before byte intake.
• Final consume binds actor, link, grant, project, draft guide, snapshot/item, operation, request digest, and server byte facts.
• Consume occurs before capacity, put intent, commit, and provider I/O.
• Copied, replayed, cross-boundary, revoked, stale, and mismatched authority denies safely.
• Only artifact.guide_source.ingest is active; guide read and binding remain planned.

Test Delta

Tests Added

• Exact PM policy and catalogue ownership.
• Opaque handle forgery, mismatch, reuse, and consume-failure closure.
• Root transaction commit, rollback, and nested-transaction denial.
• Real PostgreSQL wrong-project, revoked-link, revoked-grant, successful admission, and zero denied side effects.
• Project/draft-guide/snapshot/item lock and stale-lineage behavior.

Tests Modified

• Active audit-action equality.
• ART custody owner cardinalities and catalogue totals.

Tests Removed Or Skipped

• None.

Internal Reviewer Results

Reviewed implementation SHA: 9a3e674

Reviewer	Result	Blocking Findings	Notes
Senior engineering	PASS WITH LOW RISKS	None	Transaction ownership and cleanup verified
QA/test	PASS	None	Acceptance and exactness coverage verified
Security/auth	PASS	None	Fail-closed PREP binding verified
Product/ops	PASS	None	Project Manager scope behavior verified
Architecture	PASS	None	One shared PREP boundary retained
CI integrity	PASS	None	Thresholds and workflows unchanged
Docs	PASS	None	Counts, custody, PREP narrative, links verified
Reuse/dedup	PASS WITH LOW RISKS	None	Shared PREP and repository paths reused
Test delta	PASS	None	No skipped, removed, or weakened tests

External Review

Source	Status	Notes
CodeRabbit	IN PROGRESS	Two valid documentation findings fixed in 36556c7
GitHub checks	IN PROGRESS	Agent Gates passed; exact-head Backend running

CI And Gate Integrity

• No workflow weakening.
• No lint/test/docstring gate weakening.
• No coverage threshold weakening.
• No package script weakening.
• No unpinned new GitHub Action.
• Checkout credential persistence disabled where checkout is used.

Remaining Risks

The hosted database and coverage result must pass on the final exact head. CodeRabbit must finish its incremental review with no unresolved actionable comments.

Follow-Up Work

After merge, record 04A completion and proceed only to the next approved chunk. Guide read and binding remain owned by WS-XINT-002-04B.

Human Review Focus

Please inspect:

• Project Manager-only policy and canonical system/project grant coverage.
• Pre-byte preparation and final locked lineage/byte-fact consumption.
• Single-use capability binding and denial atomicity.
• Ingest-only activation.

Human Merge Ownership

• I can explain what changed.
• I can explain why it changed.
• I know what could break.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

[coderabbitai]

Warning

Review limit reached

@Abiorh001, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f99c725f-85e3-46c6-b735-6c86c0302c0b

📥 Commits

Reviewing files that changed from the base of the PR and between 36e49e9 and 36556c7.

📒 Files selected for processing (5)

• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-external-review-response.md
• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-pr-trust-bundle.md
• backend/tests/test_authorization.py
• docs/operations_authorization_service.md
• docs/spec_authorization_service.md

📝 Walkthrough

Walkthrough

Activates artifact.guide_source.ingest for covered Project Managers through prepared authorization, project-scoped grant checks, locked draft lineage, request-fact binding, and transactional admission. Catalogue, custody documentation, specifications, and tests are updated accordingly.

Changes

Guide ingest authorization activation

Layer / File(s)	Summary
Authorization contract and enforcement backend/app/modules/authorization/*	Adds the guide-ingest resource context, Project Manager permission, active catalogue ownership, project-scoped preparation, grant validation, and resource-context digest evidence.
Artifact preparation and locked lineage backend/app/modules/artifacts/*	Replaces deny-only guide authorization with prepared transaction-bound state and requires locked draft project-guide lineage during consumption.
Authorization and admission validation backend/tests/*	Covers exact project/grant binding, denial atomicity, transaction behavior, lineage locks, digest matching, handle closure, and reuse rejection.
Activation and review documentation .agent-loop/..., docs/*	Updates custody ownership, active/planned counts, PREP scope, draft-state requirements, specifications, and review evidence.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• Flow-Research/workstream#162 — Introduced the prepared/prelocked authorization paths extended here.
• Flow-Research/workstream#215 — Added the guide-source ingest prepared-authorization plumbing replaced here.
• Flow-Research/workstream#217 — Defined the planning and custody split for the guide-ingest activation.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.17% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title concisely summarizes the main change: activating prepared guide-source ingest authorization.
Description check	✅ Passed	The PR description matches the trust-bundle template and includes nearly all required sections, with only some reviewer metadata left incomplete.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-xint-002-04a-guide-ingest-activation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/operations_authorization_service.md`:
- Around line 711-716: Update the ART custodian cardinality in the
reconciliation documentation from nine to ten, reflecting the ten owners in
expected_owner_counts. Also update the related substring assertion so both the
documented count and invariant check remain consistent.

In `@docs/spec_authorization_service.md`:
- Line 257: Update the artifact action inventory wording in the referenced
documentation from 18 to 19 for the planned artifact actions, while preserving
the separate “18 ART actions remain planned” note at the location identified in
the review.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c07e5da-163d-4083-ba79-eaca347cb4c8

📥 Commits

Reviewing files that changed from the base of the PR and between 1f962be and 76bf46e.

📒 Files selected for processing (17)

• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/ACTIVATION_CUSTODY.md
• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-internal-review.md
• .agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/reviews/WS-XINT-002-04A-pr-trust-bundle.md
• backend/app/modules/artifacts/authorization.py
• backend/app/modules/artifacts/repository.py
• backend/app/modules/authorization/catalogue.py
• backend/app/modules/authorization/kernel.py
• backend/app/modules/authorization/policy.py
• backend/app/modules/authorization/prepared.py
• backend/app/modules/authorization/runtime.py
• backend/tests/test_artifact_admission.py
• backend/tests/test_audit.py
• backend/tests/test_authorization.py
• backend/tests/test_guide_artifacts.py
• docs/operations_authorization_service.md
• docs/spec_artifact_storage_service.md
• docs/spec_authorization_service.md

[Abiorh001]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.