STD-A — The Architecture Standard

Subordinate to Codex 1 and the Codices named in §1. See 00-index.md for authority, normative vocabulary, citation format, and waiver rules, which this Standard does not restate.

1. Purpose

1.1 This Standard makes the system-design and engine-boundary doctrine of Codex 0 chapters 05, 07, 10, 17, 18, and Codex 7, checkable. It states what a reviewer who did not do the work must be able to verify before a system, service, or boundary change ships.

1.2 It governs the decision to build something new, the boundaries between things already built, the direction dependencies may run, the layering within an implementation, the obligations an API contract carries, the runtime constraints of the edge worker, and what must be proven before something is allowed to grow.

2. Scope and non-scope

2.1 In scope: engines (ENG-), API boundaries (API-), internal tools (TOOL-), and any new service, module, or route added to the codebase; the criteria for creating a new one instead of extending an existing one; dependency direction; layering; contract stability and versioning; idempotency and failure semantics; edge-runtime constraints; server/client boundary rules; observability and audit hooks at the architecture level; scale-readiness obligations; documentation obligations.

2.2 Out of scope: the shape and lifecycle of data itself (STD-D), access control and secrets handling in depth (STD-S), the visual and interaction language of a surface (STD-X), and the specific content of AI agent scope (STD-I). Where architecture intersects these, this Standard names the intersection and defers the detail.

2.3 This Standard binds new work and materially restructured existing work. It does not retroactively fail code merged before its adoption; a pattern found non-conformant during unrelated review is logged as named debt (Codex 7, "Technical debt"), not silently ignored and not required to be fixed as a side effect of unrelated work.

3. Normative clauses

3.1 When a new system or engine is justified

3.1.1 A new engine, service, or top-level module must not be created unless the proposer has stated, in writing, in the Registry entry: (a) which existing engine or module was considered as the home for the responsibility, and (b) the specific clause of that engine's declared purpose, inputs, or outputs that the new responsibility would violate if absorbed there. A proposal lacking both (a) and (b) must not be approved. (Codex 0 §05.4.1–05.4.2)

3.1.2 A reviewer verifies 3.1.1 by reading the Registry entry and confirming the named existing system's purpose statement actually excludes the new responsibility — not merely that the proposer asserts it does.

3.1.3 A responsibility that is genuinely shared across divisions must not be split into two division-owned systems; it must be assigned to Technology (DIV-05) or absorbed into an existing Technology-owned engine. A reviewer verifies this by checking that no two Registry entries with different owning divisions claim overlapping input/output responsibility. (Codex 0 §05.4.4, §18.11.5)

3.1.4 A new engine must be assigned a permanent Registry ID before any code implementing it exists. A pull request introducing a new engine's implementation without a corresponding, pre-existing Registry ID must be rejected in review. (Codex 0 §05.4.3)

3.1.5 A decision to extend an existing system rather than create a new one is not exempt from documentation: the Registry entry for the extended system must record the new capability in its inputs/outputs list at the time it ships.

3.2 Engine boundary rules and ownership

3.2.1 Every engine, service, or boundary must have exactly one owning division recorded in the Registry. A reviewer verifies this by confirming the Registry entry names one division, not "shared" or a list. (Codex 0 §05.2.4)

3.2.2 An engine's internal storage (tables, materialized views, caches) must not be read or written by any other engine, division, dashboard, tool, or agent except through the owning engine's declared interface. A reviewer verifies this by searching the calling code for direct table or ORM-model references crossing an engine boundary; any such reference not proxied through the interface is a defect, without exception for "read-only" or "internal-only" access. (Codex 0 §05.2.2, §05.3.3, Codex 0 §17.3.4)

3.2.3 A dependency between two engines must be declared, one-directional, and recorded in the Registry entry's "how it connects" field. A reviewer verifies this by checking that every cross-engine call site has a matching declared dependency; an undeclared dependency is a doctrine violation, not a style note. (Codex 0 §05.3.2, §17.15.2)

3.2.4 A circular dependency between two engines must not exist. Where review finds two engines each declaring the other as a dependency, the change is rejected until the shared responsibility is factored into a third engine or the knowledge graph. (Codex 0 §05.3.2)

3.2.5 No division may fork CapabilityOS, an engine, or any of its private state to produce a division-local copy for convenience. A reviewer verifies this by confirming no new schema, service, or module duplicates the field set or responsibility of an existing engine already in the Registry; a duplicate found in review blocks the merge and is resolved by consuming the existing engine's interface instead. (Codex 0 §18.7.5, §18.11.5, Codex 7 Principle 5)

3.3 Dependency direction

3.3.1 The Knowledge Graph (ENG-01) must not declare a dependency on any other engine; every other engine that needs graph data must depend on it, never the reverse. A reviewer verifies this by checking ENG-01's Registry entry lists no "engines consumed." (Codex 0 §05.6.1)

3.3.2 The presentation layer must not import from the data layer directly, in any file. A reviewer verifies this with a static import check: no component-layer file imports a database client, ORM model, or query builder. (Codex 0 §17.2.6, §17.16.1)

3.3.3 A public route or server function must not import another engine's private module path (anything not exported through that engine's declared interface file). A reviewer verifies this by confirming the import resolves only to the interface's published export surface.

3.3.4 Where an engine needs data owned by a non-engine division (for example, financial ledger data), the dependency must be expressed as a call to a declared API boundary, never a direct table reference across division lines. A reviewer verifies this by confirming no cross-division database credential is used outside the owning boundary's implementation. (Codex 0 §05.3.5)

3.4 Layering

3.4.1 Every implemented system must separate into four layers: surface (presentation), boundary (API/server function edge), domain, and persistence. A reviewer verifies this by confirming each file's primary responsibility maps to exactly one layer; a file mixing rendering and query execution is non-conformant. (Codex 0 §17.2.1)

3.4.2 The surface layer must not contain a business rule, an authorization decision, or a call to persistence. A reviewer verifies this by searching component code for conditional logic that determines what a person may see or do based on role or entity state; such logic found only in the surface layer, without a server-side equivalent, is a defect regardless of whether the UI also hides the affected element. (Codex 0 §17.2.2, §17.2.6, §17.16.1)

3.4.3 The boundary layer must validate shape and business-state constraints before calling domain logic, and must not itself hold business rules beyond that validation. A reviewer verifies this by confirming the boundary function delegates the actual decision to a named domain function rather than inlining it.

3.4.4 The domain layer must be callable and testable without a network connection, a database, or a rendered page. A reviewer verifies this by running the domain layer's unit tests with the database connection removed; a failure to run is a layering defect. (Codex 0 §17.2.4, §17.13.4)

3.4.5 Only the persistence layer may open a database connection or issue a query. A reviewer verifies this with a static check that createServerFn handlers and domain modules call a persistence-layer function rather than a query client directly, except within the persistence layer's own files.

3.4.6 A change confined to one layer must not require a change to another layer's code to remain correct. Where review finds such a required paired change, the boundary is judged mis-drawn and is corrected before merge, not worked around with a comment. (Codex 0 §17.2.7)

3.5 API contract obligations, stability, and versioning

3.5.1 Every API boundary and public route must declare a stability class — experimental, stable, or permanent — recorded in its Registry entry. A reviewer verifies this by confirming the class is present and matches the actual caller population (internal-only implies experimental, at minimum). (Codex 0 §10.3)

3.5.2 Promotion of a boundary from experimental to stable must be backed by a decision record naming the owner and the first external or cross-division consumer requiring it. A reviewer verifies this by locating the cited decision record before approving the stability-class change. (Codex 0 §10.3.2)

3.5.3 A breaking change to a stable boundary must ship with: a new version published alongside the old one, a decision record, and a migration window no shorter than ninety days during which both versions serve traffic. A reviewer verifies all three are present before approving the change; any one missing blocks the merge. (Codex 0 §10.4.2–10.4.4)

3.5.4 A permanent boundary must never receive a breaking change. A reviewer verifies a proposed change to a permanent boundary is purely additive (new optional field, new optional endpoint) by diffing the contract; any removal or redefinition of an existing field blocks the merge outright, with no waiver available (this Standard mirrors STD-Q's must not rule: must not clauses cannot be waived). (Codex 0 §10.3.3, §10.4.5)

3.5.5 Every boundary's contract must be published in a machine-readable schema checked into the repository alongside its implementation. A reviewer verifies the schema file exists, is current, and is not only described in prose. (Codex 0 §10.13.1)

3.5.6 A boundary must not be retired while any caller is recorded as depending on it in the Registry's "future dependents" field. A reviewer verifies this field is empty before approving a retirement. (Codex 0 §10.4.6)

3.6 Idempotency and failure semantics

3.6.1 Every write operation that creates a canonical entity carrying institutional consequence (enrolment, credential, investment, audit record, or equivalent) must accept and enforce an idempotency key at the boundary. A reviewer verifies this by confirming the handler rejects or deduplicates a repeated call with the same key before it reaches persistence. (Codex 0 §10.6.1–10.6.3)

3.6.2 A boundary must not be marked stable while any of its consequential writes lack idempotency enforcement. A reviewer checks this as a precondition to any stability-class promotion. (Codex 0 §10.15.1)

3.6.3 Every error response must carry a machine-readable code, a display-safe human-readable message, and, where applicable, the specific field or constraint violated, classified as one of: validation, authorization, state, not_found, rate_limited, unavailable, internal. A reviewer verifies this against a sample of error paths for the changed boundary. (Codex 0 §10.7.1–10.7.2)

3.6.4 An error response must not include a stack trace, table name, query text, or other implementation detail. A reviewer verifies this by inspecting the actual error payload returned to the client, not only the code that produces it. (Codex 0 §10.7.1, §10.15.5)

3.6.5 A caller must be able to determine retry-safety from the error classification alone (unavailable and rate_limited are retryable; the rest are not). A reviewer verifies the classification used matches this table for each new error path introduced. (Codex 0 §10.7.3)

3.6.6 The failure of a peripheral engine or integration must not take down the core path (identity, authentication, and the minimum path a person needs to reach their own record). A reviewer verifies this by confirming the call to the peripheral dependency is wrapped so its failure produces a named degraded state rather than an unhandled exception propagating to the core request. (Codex 0 §05.5.1, §17.10.1)

3.6.7 A degraded state must name what could not be loaded and must not fabricate a success it did not achieve. A reviewer verifies the actual UI or response text names the missing capability rather than silently omitting it or showing stale data unmarked as stale. (Codex 0 §05.5.3, §17.10.2–17.10.3)

3.7 Edge-runtime constraints of record

3.7.1 Server code must not shell out to a compiled binary or spawn a child process. A reviewer verifies this with a search for child_process, spawn, exec, or equivalent in server-executed code paths; any match blocks the merge. (Codex 0 §17.4.2–17.4.3)

3.7.2 Server code must not read or write the OS filesystem as a means of persistence or interchange between invocations. A reviewer verifies this by searching for filesystem write calls in handler code outside of build-time tooling. (Codex 0 §17.4.4)

3.7.3 Server code must not resolve or require a module path computed at runtime (dynamic require/import built from a variable rather than a static literal). A reviewer verifies this by searching for dynamic import expressions in server code; a static, literal import is conformant, a runtime-constructed path is not.

3.7.4 Environment values must be read inside the request handler, never at module scope. A reviewer verifies this by confirming no process.env or platform-equivalent access appears outside a function body in server files. (Codex 0 §17.4.5, §17.17.3)

3.7.5 A pattern that works only because a developer's local machine has capabilities the edge runtime lacks must not be merged. A reviewer verifies this by asking, for any new server-side capability, whether it would function identically on the deployed edge runtime; if the answer requires a native binary, subprocess, or filesystem persistence, it is rejected regardless of local test results. (Codex 0 §17.4.6)

3.8 Server/client boundary rules

3.8.1 App-internal server logic must be implemented as a createServerFn and must not be exposed as a public HTTP route without also acquiring the caller-verification obligation of 3.8.2. A reviewer verifies this by confirming a server function newly reachable from outside the application's own router has caller verification added in the same change. (Codex 0 §17.5.2–17.5.4)

3.8.2 A public route must verify its caller on every invocation and must not trust a session established elsewhere, a header, a referer, or an origin as proof of identity. A reviewer verifies this by locating the explicit authentication check inside the route handler itself, not assumed from middleware alone without confirmation it runs on this route. (Codex 0 §17.5.3)

3.8.3 No third-party integration may receive direct database access or a private path bypassing a declared boundary. A reviewer verifies this by confirming any new external integration calls a named API- boundary rather than a database credential issued directly to the partner. (Codex 0 §17.5.5, §10.11.3)

3.8.4 Internal tooling must call the same boundaries external surfaces call; there is no privileged internal-only bypass around a boundary. A reviewer verifies this by confirming an internal tool needing new data extends the relevant boundary (even as experimental) rather than querying the underlying table directly. (Codex 0 §10.11.1, §10.11.3)

3.8.5 The route tree (TanStack Router) must be generated and must not be hand-edited; a diff touching the generated route tree file directly, outside the generator's own output, is rejected in review. (Codex 7, "Platform constraints of record")

3.9 Observability and audit obligations

3.9.1 Every consequential action — one that changes a person's standing, grants or revokes access, issues or revokes a credential, or alters a financial record — must produce an immutable audit record carrying actor, subject, timestamp, and reason, written through API-11 or its equivalent, not by direct table write. A reviewer verifies this by tracing the code path for each newly introduced consequential action to a call that produces the record. (Codex 0 §17.9.3, §10.12.11)

3.9.2 Logs must be structured and must never contain a secret, credential, password, token, or full identity document. A reviewer verifies this by inspecting the actual log statements added in the change, not only the logging library's configuration. (Codex 0 §17.9.1–17.9.2)

3.9.3 An elevated read of member content must be logged with a stated reason and must produce an audit record. A reviewer verifies this by confirming the elevated-access code path calls the audit-logging function before or alongside returning data. (Codex 0 §17.6.4)

3.10 Scale obligations

3.10.1 A list-returning endpoint must be paginated by default; an unbounded "return everything" mode must not be reachable without explicit, logged, elevated access. A reviewer verifies this by confirming the endpoint's default query includes a page-size limit and that any bypass requires a role check plus an audit record. (Codex 0 §10.8.1, §17.11.4)

3.10.2 A collection that can grow without bound or that changes while being paged must use cursor-based pagination, not offset-based. A reviewer verifies the pagination mechanism matches the collection's growth profile before approving a new list endpoint. (Codex 0 §10.8.2)

3.10.3 Before a feature that introduces unbounded growth (new event stream, new per-person record type, new list surface) ships, the change description must state which of the thresholds named in Codex 0 chapter 18 apply and what happens at the next order-of-magnitude increase. A reviewer verifies this statement is present and specific, not a generic assertion that "it will scale." (Codex 0 §18.0.3, §18.1.3)

3.10.4 A cache introduced for performance must state its invalidation rule explicitly at the point it is introduced. A reviewer verifies a cache without a stated invalidation condition is rejected rather than shipped. (Codex 0 §17.11.3)

3.10.5 A query serving a route must be declared at the route level (loader) rather than fetched ad hoc inside a component after render. A reviewer verifies this by confirming data dependencies appear in the route's loader, not in a component-level effect. (Codex 0 §17.11.2)

3.11 Documentation obligations

3.11.1 Every new engine, boundary, or tool must have a Registry entry completed before implementation begins, carrying the eight fields required by Codex 0 §0.6, including named dependencies and the clause citations that justify its creation under 3.1. A reviewer verifies the entry exists and is complete before approving the first implementing pull request. (Codex 0 §16, this Standard §3.1)

3.11.2 A structural or architectural change must cite the specific governing Codex or Standard clause it satisfies in its review description, not merely reference the chapter. A reviewer verifies the citation resolves to an actual clause supporting the specific claim made.

3.11.3 Named technical debt taken to ship an architectural shortcut must be recorded both adjacent to the code and, where the tradeoff is architectural, in a decision record, stating the constraint, the capability given up, and the repayment condition. A reviewer verifies both locations exist before approving debt as "named" rather than treating it as an unnamed defect. (Codex 0 §17.14.2, Codex 7 "Technical debt")

4. Governing Codex clauses

Codex 0 chapter 05 (CapabilityOS, engine model); chapter 06 (Knowledge Graph, as the paradigm engine with no upstream dependency); chapter 07 (data model, referenced for entity-boundary interaction); chapter 10 (API boundaries, stability, and contract rules); chapter 17 (platform architecture and engineering); chapter 18 (scale and expansion); Codex 5 (shared data model and API boundaries); Codex 7 (engineering doctrine).

5. Conformance checklist

1. 1Does the Registry entry name the existing system considered and rejected as the home for this responsibility, or is this an extension of an existing system? — yes / no / not-applicable-because
2. 2Does the new or changed system have exactly one owning division recorded? — yes / no / not-applicable-because
3. 3Does any code cross an engine boundary by reading or writing another engine's storage directly? — yes / no / not-applicable-because
4. 4Is every cross-engine or cross-boundary dependency declared in the Registry's "how it connects" field? — yes / no / not-applicable-because
5. 5Does the change introduce or preserve a circular dependency between two engines? — yes / no / not-applicable-because
6. 6Does the surface layer contain a business rule, authorization decision, or direct persistence call? — yes / no / not-applicable-because
7. 7Can the domain layer be tested without network, database, or render? — yes / no / not-applicable-because
8. 8Does the boundary declare a stability class matching its actual caller population? — yes / no / not-applicable-because
9. 9Does every consequential write on this boundary enforce an idempotency key? — yes / no / not-applicable-because
10. 10Does every error response classify correctly and omit implementation detail? — yes / no / not-applicable-because
11. 11Does server code avoid child processes, native binaries, filesystem persistence, and runtime module resolution? — yes / no / not-applicable-because
12. 12Are environment values read only inside handlers? — yes / no / not-applicable-because
13. 13Does every public route verify its caller on every invocation? — yes / no / not-applicable-because
14. 14Does every consequential action produce an audit record through the audit boundary? — yes / no / not-applicable-because
15. 15Is every list endpoint paginated with a mechanism matching its growth profile? — yes / no / not-applicable-because
16. 16Does the change state the applicable scale threshold and next-order-of-magnitude behavior, where growth is unbounded? — yes / no / not-applicable-because
17. 17Is the Registry entry complete and does named debt, if any, appear in both required locations? — yes / no / not-applicable-because

6. Interfaces to other Standards

6.1 STD-D governs the shape, identifiers, and migrations of the persistence layer this Standard's layering rule (§3.4) constrains access to; a schema change follows STD-D even where it is triggered by an architectural decision made here.

6.2 STD-S governs the depth of access control, secrets handling, and incident response that this Standard's server/client boundary rules (§3.8) and observability rules (§3.9) reference at the architecture level only.

6.3 STD-I governs what an AI agent may call across these boundaries and the human checkpoints required; this Standard governs only that the boundary itself is sound regardless of caller.

6.4 STD-Q is the final gate; a change conformant to this Standard still requires STD-Q sign-off before it ships.

7. Open questions

7.1 The machine-readable schema format for boundary contracts (OpenAPI, GraphQL SDL, or equivalent) is not yet chosen institution-wide; §3.5.5 is enforced against whatever format a decision record eventually fixes.

7.2 The ninety-day minimum migration window (§3.5.3) has not been tested against a real breaking change and may be revised by decision record after the first case.

7.3 The mechanism for out-of-band jobs that cannot run inside the edge worker's request lifecycle (relevant to §3.7) is reserved; no such job exists yet, and this Standard will be amended when the first case arises.

7.4 Whether a lighter-weight architecture review path is warranted for genuinely small, single-file additions is undecided; today this Standard applies the same procedure regardless of size, per Codex 0 §05.4.5's "no abbreviated path" rule.

8. Status

8.1 This Standard is an internal engineering instrument. It is not a compliance certification and must not be quoted as one (Codex 0, Standards index §8).

8.2 A waiver against a must clause in this Standard follows the waiver procedure of the Standards index §4 in full, including a named owner and expiry; a must not clause here — engine forking, direct table access across a boundary, breaking a permanent contract, filesystem persistence, module-scope environment reads — carries no waiver path.

9. Amendment

9.1 A clause in this Standard is amended only by a decision record naming the clause, the reasoning, and what it supersedes, per Standards index §7. A struck clause number is never reused.