WS-ARCH-001-02B: expose PROJECT locked-policy API - #315
Merged
Conversation
📝 WalkthroughWalkthroughThe PR adds a public PROJECT locked-policy API, an exact historical-lineage repository, PostgreSQL validation and concurrency tests, architecture checks, ownership registration, test-lane updates, and supporting project records. ChangesPROJECT locked-policy context
Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related issues
Possibly related PRs
Sequence Diagram(s)sequenceDiagram
participant Caller
participant ProjectLockedPolicyRepository
participant PostgreSQL
participant CanonicalJsonObject
Caller->>ProjectLockedPolicyRepository: Submit ProjectLockedPolicyContextRequest
ProjectLockedPolicyRepository->>PostgreSQL: Lock exact project and policy lineage rows
PostgreSQL-->>ProjectLockedPolicyRepository: Return current or superseded historical rows
ProjectLockedPolicyRepository->>CanonicalJsonObject: Validate and hash policy mappings
CanonicalJsonObject-->>ProjectLockedPolicyRepository: Return immutable canonical values
ProjectLockedPolicyRepository-->>Caller: Return ProjectLockedPolicyContextFacts or failure
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
backend/tests/projects/test_locked_policy_context.py (1)
300-322: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winBound the lock wait by time, not by iteration count.
The loop runs up to 5000 iterations with
asyncio.sleep(0). Each iteration issues onepg_stat_activityquery. The effective timeout therefore depends on database round-trip latency, so the test is non-deterministic across environments. A slow CI database can also receive thousands of queries in a short window.Use a wall-clock deadline and a small sleep interval.
♻️ Proposed deadline-based wait
engine = create_async_engine(database_url) try: async with engine.connect() as connection: - for _ in range(5000): + deadline = asyncio.get_running_loop().time() + 30.0 + while asyncio.get_running_loop().time() < deadline: waiting = await connection.scalar( text( "select exists(select 1 from pg_stat_activity where " "application_name = :application_name " "and wait_event_type = 'Lock')" ), {"application_name": application_name}, ) if waiting: return - await asyncio.sleep(0) + await asyncio.sleep(0.01) finally: await engine.dispose()🤖 Prompt for 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. In `@backend/tests/projects/test_locked_policy_context.py` around lines 300 - 322, Update _wait_for_project_database_lock to use a wall-clock deadline instead of the fixed 5000-iteration loop: compute an end time, poll pg_stat_activity until that deadline, and await a small positive sleep interval between checks. Preserve the immediate return when the lock is observed and raise the existing AssertionError after the deadline expires.
🤖 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
@.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-02B-project-locked-policy-api.md:
- Around line 90-94: Update the verification pytest command’s coverage options
to include app.modules.projects.repository alongside app.modules.projects.api,
so ProjectRepository.lock_locked_policy_context is measured by the existing 90%
coverage gate.
In `@backend/scripts/behavior_ownership.py`:
- Around line 77-81: Update the _validate_additive_partition_transition
docstring to describe MODULE_PUBLIC_API_FOUNDATION_TARGETS as the module
public-API foundation allowlist, replacing the stale “AUTH boundary-foundation
additions” terminology while preserving the validator’s behavior.
---
Nitpick comments:
In `@backend/tests/projects/test_locked_policy_context.py`:
- Around line 300-322: Update _wait_for_project_database_lock to use a
wall-clock deadline instead of the fixed 5000-iteration loop: compute an end
time, poll pg_stat_activity until that deadline, and await a small positive
sleep interval between checks. Preserve the immediate return when the lock is
observed and raise the existing AssertionError after the deadline expires.
🪄 Autofix
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: 7c97416c-339f-4c76-9b56-08148cbbd9de
📒 Files selected for processing (11)
.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-02B-project-locked-policy-api.md.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/evidence/WS-ARCH-001-02B-project-manifest.md.ci/behavior-ownership/partition.v1.jsonbackend/app/modules/projects/api/__init__.pybackend/app/modules/projects/api/locked_policy.pybackend/app/modules/projects/repository.pybackend/scripts/behavior_ownership.pybackend/scripts/run_test_lanes.pybackend/tests/architecture/test_module_boundaries.pybackend/tests/projects/test_locked_policy_context.pydocs/architecture_lockdown.md
…-project-policy-api # Conflicts: # .ci/behavior-ownership/partition.v1.json
abiorh-claw
self-requested a review
August 11, 2026 14:22
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-02B-external-review-response.md (1)
21-28: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRecord exact verification commands and outcomes.
This section lists validation categories but not executable commands, exit status, coverage results, or the hosted
project_lifecyclerun result. Add those details, or reference the exact CI run. Keep the local checks separate from the delegated PostgreSQL checks.🤖 Prompt for 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. In @.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-02B-external-review-response.md around lines 21 - 28, Update the “Commands rerun” section to record the exact executable local verification commands, each outcome or exit status, and coverage results, while keeping local checks separate from delegated PostgreSQL validation. Also include the hosted project_lifecycle run result or an exact CI run reference.
🤖 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
@.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-02B-external-review-response.md:
- Around line 7-9: Update the summary sentence referencing
ProjectLockedPolicyRepository to replace “exact locked-policy persistence” with
lineage-resolution terminology such as “exact historical-lineage resolution” or
“exact locked-policy context resolution,” consistent with the project glossary
and architecture documentation.
---
Nitpick comments:
In
@.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-02B-external-review-response.md:
- Around line 21-28: Update the “Commands rerun” section to record the exact
executable local verification commands, each outcome or exit status, and
coverage results, while keeping local checks separate from delegated PostgreSQL
validation. Also include the hosted project_lifecycle run result or an exact CI
run reference.
🪄 Autofix
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: 56df527d-d927-4200-a643-341a9076c472
📒 Files selected for processing (7)
.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-02B-project-locked-policy-api.md.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/evidence/WS-ARCH-001-02B-project-manifest.md.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/reviews/WS-ARCH-001-02B-external-review-response.md.ci/behavior-ownership/partition.v1.jsonbackend/app/modules/projects/locked_policy_repository.pybackend/scripts/behavior_ownership.pybackend/tests/projects/test_locked_policy_context.py
🚧 Files skipped from review as they are similar to previous changes (5)
- .ci/behavior-ownership/partition.v1.json
- .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/evidence/WS-ARCH-001-02B-project-manifest.md
- backend/tests/projects/test_locked_policy_context.py
- .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-02B-project-locked-policy-api.md
- backend/scripts/behavior_ownership.py
abiorh-claw
approved these changes
Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Chunk
WS-ARCH-001-02B — PROJECT Locked Policy Public API
Goal
Expose dependency-free immutable PROJECT locked-policy facts without leaking PROJECT persistence into TASK, ART, or CHECKER.
Human-approved intent
Preserve exact historical guide, snapshot, effective-policy, and pre-submit-policy lineage, including valid superseded rows, without substituting successors.
What changed
app.modules.projects.apicontracts.ProjectLockedPolicyRepositoryhistorical-lineage resolution.lock_locked_policy_contextfrom the generalProjectRepositorywith no alias, forwarding method, fallback, or duplicate.Why it changed
TASK needs exact PROJECT facts without importing PROJECT ORM models, repositories, or sessions. The focused repository also provides a truthful bounded coverage gate.
Design chosen
A PROJECT-owned concrete repository structurally implements
ProjectLockedPolicyContextPort. Only dependency-safe requests, immutable facts, and the bounded failure cross the public API.Alternatives rejected
Scope control
No routes, authorization availability, policy compilation, task preparation, artifact behavior, checker behavior, ORM schema, or migrations changed. No cross-module private import was added.
Product behavior
Exact current and valid historical superseded lineage resolves under row locks. Missing, drifted, cross-project, pending, malformed, successor-substituted, or non-canonical context fails closed with the existing bounded error.
Acceptance criteria proof
ProjectRepository.lock_locked_policy_contextreference remains.FOR UPDATEwith preserved lock order.Tests and checks run
a58118fc.Test delta
No skips or xfails were added. Exact facts, failure, successor, and contention assertions remain. Both bounded repository exception paths are covered.
CI integrity
No threshold reduction, exclusion, continue-on-error, lane removal, or assertion weakening. The focused repository is registered in the existing project lifecycle lane and ownership partition.
Reviewer results
Architecture, security, product/ops, QA, senior engineering, CI integrity, docs, reuse/dedup, and test-delta reviews pass. Valid findings were addressed.
External review
All valid CodeRabbit findings were fixed: focused resolver coverage, exact module public-API foundation wording, bounded lock polling, and historical-lineage terminology. All review threads are resolved.
Remaining risks
None identified for this bounded chunk. Live consumer composition remains intentionally deferred.
Follow-up work
WS-ARCH-001-02C owns later composition and caller cutover under its own contract.
Human review focus
Exact historical lineage, clean removal from the general repository, immutable output, lock ordering, successor non-substitution, and absence of cross-module leakage.
Human merge ownership
The PR is ready for human review. Only the user may approve and merge it.