Add artifact admission and prepared put attempts

[Abiorh001]

PR Trust Bundle: WS-ART-001-02C1

Chunk And Intent

WS-ART-001-02C1 - Admission And Put-Attempt Foundation

Reviewed implementation SHA: 535069cfb1a7312d731bb14a6023ceb0894402e9

Trusted base: 8d5eb15b384fd75787ce98a099400a1d335d2560

Merge intent: .agent-loop/merge-intents/WS-ART-001-02C1.json

Create the durable PostgreSQL admission and prepared-attempt transaction that
must commit before provider I/O while keeping execution and product cutover
inactive.

Design And Scope

• Workstream derives deployment, project, producer, and applicable task scopes.
• Unique provisional/completed charges count once per scope and exact content;
  released charges may be reacquired only under locked capacity checks.
• Actors owns exact profile/link locking and returns frozen primitive proof in
  the caller's admission transaction; ART makes no AUTH permission decision.
• One namespace claim, complete charge set, and prepared attempt commit
  atomically. Prepared scheduling/execution fields remain inactive and null.
• No provider write/observation, verification, publication, recovery, Celery
  execution, route, product cutover, task claim, reviewer lease, R2, or Flow
  Node path is included.

Acceptance Proof

• Callers cannot supply, omit, or weaken admission scopes or limits.
• Exact actor/link and canonical product relationships are locked and
  revalidated without crossing actor persistence ownership.
• Same content is charged once per applicable scope under real concurrent
  ledger contention.
• Concurrent distinct content cannot oversubscribe a shared scope.
• Reservation failure leaves no partial charge, attempt, receipt, audit
  success, or provider call.
• A committed prepared attempt is required before any later provider work.
• Prepared next_run_at, executor, lease, terminal, replica, and receipt
  fields are null and execution generation is zero.
• Exactly one schema-v2 merge intent names only inactive successor 02C2
  and requires a separate explicit start.

Tests And Checks

371 focused tests PASS in 757.38s
Scoped changed-subsystem coverage 94.02% (required 90%)
Alembic head 0028_artifact_admission
Ruff PASS
Configured docstring coverage PASS at 90.5%
Stale artifact contract scan PASS
88 agent-gate tests PASS
Markdown links PASS
Schema-v2 merge-intent validation PASS
git diff --check PASS

GitHub Backend remains authoritative for the full isolated repository suite and
78-percent repository coverage floor.

Internal Review

All nine required tracks reviewed exact SHA 535069cf...: senior engineering,
architecture, QA/test, security/auth, product/ops, reuse/dedup, CI integrity,
test delta, and docs. QA's initial High concurrency-proof finding was repaired
and passed on rerun. Docs' stale-evidence finding was repaired by regenerating
the exact-SHA evidence, this bundle, external status, and initiative state. No
blocking finding remains and every reviewer session is closed.

External Review

Source	Status	Notes
GitHub Agent Gates	PASS	Passed on final PR head c93f1a24.
GitHub Backend	PASS	Full suite, scoped gates, and 78-percent floor passed on c93f1a24.
CodeRabbit	PASS	Current-head review completed with no actionable comments.
Human review	PASS	GitHub review decision is APPROVED; merge remains a separate explicit action.

Remaining Risks

• Admission is intentionally not connected to provider execution or product
  submission routes.
• Native AWS remains unavailable until its separately owned live proof.
• All required automated external checks passed on final PR head c93f1a24.

Human Review Focus

• Can a producer omit a scope, weaken capacity, or substitute identity/context?
• Does every success commit the complete ledger and exactly one prepared
  attempt before provider side effects?
• Do rollback, replay, release/reacquisition, and concurrent contention preserve
  exact accounting?
• Are provider execution, verification, recovery, and product routes absent?

Human Merge Ownership

• I can explain what changed and why.
• I know what could break.
• I accept the remaining risks.
• GitHub CI and external review pass on the final head.
• The user explicitly approved PR Add artifact admission and prepared put attempts #154 for merge.

[coderabbitai]

📝 Walkthrough

Walkthrough

WS-ART-001-02C1 adds PostgreSQL-backed artifact admission scopes, charges, and prepared put attempts. It introduces locked admission validation, replay and capacity handling, migration safeguards, required byte-limit configuration, architecture checks, integration tests, documentation, and updated workflow and initiative gates.

Changes

Artifact admission foundation

Layer / File(s)	Summary
02C1 governance and review contracts .agent-loop/*, .agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/*, .agent-loop/merge-intents/*	Marks 02C1 active, records its review evidence and trust bundle, defines its merge metadata, and requires explicit progression to 02C2.
Durable admission data contracts backend/alembic/versions/0027_artifact_admission.py, backend/app/modules/artifacts/{models.py,schemas.py}, backend/app/core/config.py, backend/app/interfaces/artifacts.py, backend/app/adapters/artifacts/*	Adds admission tables and constraints, ORM models, immutable request/result contracts, required durable-byte limits, and canonical provider-reference helpers.
Repository and admission service flow backend/app/modules/artifacts/{repository.py,service.py}	Loads locked admission facts, reserves deduplicated charges, validates replay and capacity conditions, and persists prepared ArtifactPutAttempt records before provider I/O.
Admission behavior verification backend/tests/test_artifact_admission.py, backend/tests/artifact_store_helpers.py	Tests relationship validation, row locking, replay, charge reacquisition, deduplication, concurrency limits, rollback, checker identity, and migration downgrade protection.
Architecture, configuration, and storage wiring backend/tests/*, .github/workflows/backend.yml	Updates test settings, namespace checks, adapter-import and provider-execution guards, and adds a 90% audit coverage gate.
Specification and gate alignment docs/spec_artifact_storage_service.md, scripts/test_agent_gates.py	Documents step-3-only prepared admission behavior and aligns trusted-main and active-chunk assertions with 02C1.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Producer
  participant ArtifactAdmissionService
  participant ArtifactRepository
  participant PostgreSQL
  Producer->>ArtifactAdmissionService: submit admission request
  ArtifactAdmissionService->>ArtifactRepository: resolve and lock source facts
  ArtifactRepository->>PostgreSQL: lock canonical rows and admission scopes
  ArtifactAdmissionService->>ArtifactRepository: reserve charges
  ArtifactRepository->>PostgreSQL: persist charges and counters
  ArtifactAdmissionService->>ArtifactRepository: create prepared put attempt
  ArtifactRepository->>PostgreSQL: persist attempt and charge links
  ArtifactAdmissionService-->>Producer: return admission result

Loading

Possibly related PRs

• Flow-Research/workstream#101: Introduced the artifact domain that this admission foundation extends.
• Flow-Research/workstream#141: Established the byte-oriented ArtifactStore v2 contracts used by this work.
• Flow-Research/workstream#151: Provides the preceding artifact-storage progression and provider-reference context.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.37% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description covers the chunk intent, acceptance proof, tests, reviews, and risks, but it omits several required template sections like Scope Control, CI, and Test Delta.	Add the missing template sections: What Changed, Why It Changed, Scope Control, Evidence, Test Delta, CI And Gate Integrity, and explicit Allowed Files/Outside Contract entries.

✅ Passed checks (3 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 matches the main change: adding artifact admission flow and prepared put attempts.

✨ Finishing Touches

📝 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-art-001-02c1-admission-put-attempt

---

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.}

[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.