docs: reconcile design document with contracts

[hpmaxi]

Summary

Closes #112

Reconciles discrepancies between the product and architecture design document (docs/strata-product-and-architecture.md), AGENTS.md, and the contract implementation across 21 audit points.

Two categories of discrepancies were separated during review:

1. False statements about intended architecture (corrected directly in place): pause scope (guardian-only, does not pause custodian transfers), unpause administrative override (unpause does not require a fresh oracle price), redemption admission limit (per-epoch controller constraint), entrypoint names (request_deposit, cancel_deposit, claim_deposit, etc.), cancellation window (only open prior to priceable timestamp), and covered claims always paying.
2. Planned future behavior that code has not yet grown into (explicitly marked with target issues): lazy mint/burn at claim time vs pricing (Separate pricing from payment #73), request-time KYC allowlist verification vs claim-time (Gate entry with an allowlist and keep exits open #21), and SEP-40 oracle adapter integration in Tranche 3 (Support flexible pricing schemes via pricing trait #72).

Changes

• Correct unpause behavior in §8.2 to match contracts: unpause does not call the oracle or require a fresh attestation.
• Clarify pause scope in §8.2: guardian-only action; pauses investor requests, not custodian operations or claim fulfillment.
• Align redemption admission constraints in §8.2 with contract state (one active request per controller per epoch).
• Correct entrypoint naming across §8.2 and §8.5 to match implementation (request_*, cancel_*, claim_*).
• Document claim-time share minting and burning as current architecture, noting lazy vs priced targets (Separate pricing from payment #73).
• Clarify subscription allowlist checks at claim time vs request-time admission (Gate entry with an allowlist and keep exits open #21).
• Note that nav_per_share() is consumed directly today with SEP-40 adapter scheduled for Tranche 3 (Support flexible pricing schemes via pricing trait #72).
• Align AGENTS.md and architecture document on post-KYC allowlist and exit-only cash path.

Acceptance criteria

• Each of the twenty-one statements is either corrected, or marked as a target with its issue.
• The statements that are false about the intended design are corrected, not marked.
• AGENTS.md and docs/architecture.md do not contradict each other.
• A short note records how the two kinds were told apart, so the next sweep is cheaper.

Test plan

Automated tests

None (documentation only).

Manual verification

1. Review diff against origin/main to verify accuracy against contract implementation and design consensus.

Breaking changes

None.

Checklist

• Self-reviewed my own diff
• Tests added or updated
• Docs updated (if applicable)
• No unrelated changes bundled in

Screenshots

None.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
strata-vault-kit-app	Ready	Preview	Sep 25, 2026 6:21pm UTC

[pragalli]

Oracle roles don't match what the doc describes

The doc says "Four authorities reside on the vault and one (attestation) on the oracle," which reads as if the oracle only adds a single new role on top of the vault's four.

In code, the oracle actually defines three distinct roles — admin, attester, and guardian (contracts/nav-oracle/src/lib.rs) — not one. Nothing in the constructor ties these to the vault's governance/guardian addresses, so they're independent role slots that happen to share a name with their vault counterparts. Whether a deployment reuses the same multisig across both contracts is a configuration choice, not something the code enforces.

Could we reword this to reflect the oracle's own role surface? Something like: "the vault holds four authorities; the oracle holds its own separate set (admin, attester, guardian), with no code-level requirement that they match the vault's."

[hpmaxi]

Right: the oracle has its own admin, attester and guardian, set in its own constructor, and only deploy.ts gives them the governance and guardian accounts. The vault doesn't hold compliance either; it only checks that compliance differs from governance and treasury. Reworded §5 and the §8.3 row in 92e2f1f: each contract grants its own roles, and no code ties the oracle's roles to the vault's.