Inventory Ledger Contract Review
Local technical review, corrected planning gaps, and the approved expiry-validation API action.
Date: 2026-10-11
Current Disposition
The user accepted all retained recommendations on 2026-10-11. The Inventory developer guide records their delivery status and the later Unit 1 code-review fixes. Inventory U1-U6 are now committed and tested locally. They remain undeployed. Source permissions, commands, APIs, opening import, and reconciliation are implemented. Full CI, operator acceptance, and Hospital integration remain open. The sections below preserve the earlier document review. Statements about no application code or tests describe that review, not the later implementation.
Scope And Status
This review covers the ledger API contract and the six-unit source plan. The boundary ADR records accepted product decisions. Inventory remains a reusable backend domain, not a separate MFA app.
Six document corrections and one user-approved API action are applied to the documents. No Inventory application code, migration, endpoint, or test is delivered by this review. No application test, build, CI, or deployment was run. Hospital integration, pharmacy readiness, and billing remain separate work. Origin U9 acceptance and D1 delivery remain open.
Applied Corrections
Separate Shell Grant Areas
One area with all write keys at Manage would grant stock adjustments together with consumption. Use three areas: Inventory, Inventory consumption, and Inventory adjustments. Keep View and stock management in Inventory. Put each other mutation key in its own area. Keep the four accepted keys, owner/admin defaults, and the separate View requirement. Add role and member-dialog tests for consumption access without receipt or adjustment access.
Evidence: the server expands an area level to all keys at or below it in backend/domains/reference/services/access_table.rb.
Both backend/domains/identity/services/permission_management/apply_access_levels.rb and apply_member_access_levels.rb use that expansion.
The Shell dialogs submit area/level changes. They do not provide individual-key editing.
This correction implements the accepted separation of stock management, consumption, and adjustments without a new RBAC UI.
Enforce One Physical Unit Per Serial
One unit per bucket does not prevent the same serial from appearing in two locations. Require total on-hand per serial to be zero or one across all locations and conditions. Add a database guard for one positive-stock bucket per serial and serial locks during commands. Test distinct-key receipts, positive corrections, reversals, and valid transfers.
Evidence: the contract permits receipt with an existing serial and defines bucket identity by location and condition. Its original per-command quantity-of-one rule did not limit aggregate live stock for that serial. This correction implements the accepted serial-tracking model, not a new stock operation.
Preserve Issue Lineage
A combined OT bucket cannot prove which of two issues still has unused material. Track remaining custody stock by original issue line. Consumption, return, transfer, write-off, and compensation update that lineage with the stock effect. Test mixed issues and concurrent returns; later stock must not make an earlier consumed issue returnable.
Evidence: the contract requires an original issue reference and excludes consumed quantities from unused return. Its previous model tracked reservation allocations but no remaining custody quantities for unreserved issues. This correction implements the accepted distinction between issue, actual consumption, and unused return.
Preserve Unknown Commit Outcomes
A lost connection during commit does not prove that stock stayed unchanged. Report no effect only after a verified rollback. Otherwise preserve an unknown outcome and the original operation key. An unavailable or initially empty lookup must not cause a new key while the original command can still commit. Add lost-commit-response and same-key retry scenarios.
Evidence: the contract required original-key recovery but also said a final retryable failure confirmed no success. The corrected failure rule agrees with its existing once-only retry contract.
Provision The Inventory Test Schema
The non-bypass test-role provisioner uses an explicit schema list that does not contain Inventory. Add Inventory there and provision each test database before RLS proofs. Do not count absent schema grants as tenant-isolation evidence.
Evidence: backend/lib/tasks/db_rls_test_role.rake names its schemas explicitly.
The source plan now includes that file and setup requirement in local Unit 1.
This correction implements the existing enforced-role RLS acceptance requirement.
Keep Quarantine And Write-Off Available
The statement that expired stock was unavailable for every new operation contradicted the required quarantine return and write-off commands. Clarify that expired stock cannot be allocated, issued for use, or consumed. Audited release, quarantine return, and write-off remain available. This correction follows the contract's more specific command rules and the accepted return controls.
Accepted Fix: Lot Expiry Validation
The review found no action to validate an existing unresolved-expiry lot that remained physically recorded. Receipt must not silently rewrite its expiry, and repeated receipt would change stock incorrectly.
The contract and source plan now include a versioned validate_lot_expiry command through the existing operations API.
It validates an unresolved lot or corrects a prior expiry validation without a quantity movement.
Preserve source-label precision, approved interpretation rule/version and approval evidence, evaluated timezone, cutoff, actor, reason, and prior revision.
The server validates the approval evidence and derives the cutoff from the approved interpretation; a browser-supplied approval flag or cutoff is not authority.
Initial validation requires View and stock management. Correction of a prior validated cutoff also requires adjustment permission.
Use the existing operation-key, expected-version, facility-authorization, transaction, and audit rules.
Preserve receipt and movement history. Current eligibility uses the current validated revision.
Local Units 1, 3, and 5 now specify source model, command, request, retry, and manual QA coverage. Unit 2 covers permissions; Unit 4 covers corrected-cutoff eligibility.
The user approved this action on 2026-10-11. The later U3 and U5 implementation delivers it through source commands and HTTP APIs. It does not select a shelf-life policy or replace facility pharmacy/inventory approval before pilot use.
Coverage
All lenses ran sequentially in the main thread. They are not independent reviews. Counts below assign each retained finding to one primary lens; they do not imply separate agents.
| Lens | Status | Applied | Proposed |
|---|---|---|---|
| Coherence | Completed locally | 2 | 0 |
| Feasibility | Completed locally | 3 | 0 |
| Security | Completed locally | 1 | 0 |
| Adversarial | Completed locally | 1 | 0 |
| Scope | Completed locally | 0 | 0 |
| Product | Completed locally | 0 | 0 |
| Design and UI handoff | Completed locally | 0 | 0 |
The six corrections have direct document or repository evidence. The expiry action resolves the identified recovery gap. Its added API behavior and authorization mapping have user approval. All seven retained findings are addressed in the documents. This does not establish implementation or final contract acceptance. The Compound Pack resolver returned no roots, warnings, or errors. The cross-model pass did not run. No external-provider dispatch was approved for this updated plan.
Document Checks
git diff --checkpassed.- Eighteen changed or new documents have 78 valid local links and anchors.
- YAML frontmatter parsed for the contract, ADR, source plan, origin plan, and this review.
- The source plan still has six implementation units, named tests, and six unit-end manual QA checks.
- The tracked issue remains open. Its labels, assignees, and historical snapshot were preserved.
- Application code, tests, builds, migrations, and CI were not run or changed during this review.
Next Step At Review Completion
The approved lot-expiry action is now in the contract and source plan. Confirm final technical contract acceptance and authorize source implementation. Local Unit 1 starts with domain schema, stock identities, test-role grants, and enforced-role RLS tests. Do not mark any unit complete until its code, automated checks, and manual QA evidence exist.