46 lines
6.2 KiB
Markdown
46 lines
6.2 KiB
Markdown
# Architecture review and revision record
|
||
|
||
13 October 2026. Artifact: proposed GEWU architecture and engineering handbook, originally drafted under the SKB working name. Repository remains `D:/01_GIT/SKB`. This report covers document-level corrections, not implemented security or runtime acceptance.
|
||
|
||
## Frozen review inputs
|
||
|
||
An independent, read-only reviewer inspected the initial proposal, the actual docs-only repository, GOAL and PRD. The initial architecture and acceptance-contract digests were verified before review:
|
||
|
||
| Artifact | SHA-256 of v0.1 |
|
||
| --- | --- |
|
||
| `docs/architecture/ARCHITECTURE.md` | `353023F13730692C841C6541D4C64BFE6CD206F1D06A17C951638F20FD89083E` |
|
||
| `docs/architecture/ACCEPTANCE_CONTRACT.md` | `EA07DEFA57FCB8333CE46E663D13F24FBC636A46D7FA11E3DDA51CFA0EDF5021` |
|
||
|
||
The review classified the draft as mixed: product scope and most failure boundaries were concrete, but owner authentication, live receipt recovery, API parity and extraction persistence required further decisions. The findings below describe that frozen draft. Linked documents now contain the revised proposal.
|
||
|
||
## Findings and corrections
|
||
|
||
| ID / severity | Original gap | Correction in v0.2 |
|
||
| --- | --- | --- |
|
||
| B1 / blocker before protected-action implementation | Owner MCP authentication had no credential, transport or replay-state contract. Original architecture lines 122–126 and acceptance contract lines 86–95. | [Owner profile](../architecture/ACCEPTANCE_CONTRACT.md#proposed-owner-authentication-profile): controlled HTTPS CLI, separate human reauthentication, short-lived challenge-bound token, owner-only operations, durable decisions and single-use publication binding. This is a custom-client profile with explicit limits. |
|
||
| M1 / major | A committed proposal could have no receipt during a live retry; recovery blocked only the same identity. Original acceptance contract lines 47–78. | [Publication/recovery](../architecture/ACCEPTANCE_CONTRACT.md#publication-and-crash-recovery): deterministic committed manifest, publication journal, immutable receipt, separate dynamic index status, status/retry reconciliation before restart and global publication freeze while required reconciliation fails. |
|
||
| M2 / major | HTTP reads were drawn/described around browser sessions even though the PRD includes agent HTTP retrieval. Original architecture lines 40–56 and 122. | [Public transport contract](../architecture/ACCEPTANCE_CONTRACT.md#public-transport-contract): agent keys may authenticate read HTTP, which shares MCP scope, budgets, revision/error envelopes and cursor semantics. Proposals/owner decisions remain unavailable through the read API. |
|
||
| M3 / major | Extraction blocks/maps and a rebuild watermark were not specified sufficiently to preserve old citations. Original architecture lines 89–106 and acceptance contract lines 105–107. | [Extraction and rebuild](../architecture/ACCEPTANCE_CONTRACT.md#immutable-extraction-format-and-rebuild-procedure): immutable content-addressed block artifacts, code-point maps, exact cited extraction IDs, snapshot head, inventory/profile watermark and isolated generation publication. |
|
||
|
||
The review preserved the one-writer/CAS topology, manifest-in-commit recovery principle, atomic cross-policy bundles, source/assessment/decision separation, scope rechecks and the editorial visual direction. No evidence warranted adding a graph database, embedded reasoning agent or distributed service architecture.
|
||
|
||
A bounded independent recheck found B1 and M1–M3 substantively resolved at the design level. It identified one remaining recovery detail: the owner-login seed-encryption key needed its own protected recovery backup. The contract now specifies that backup, restore verification and a disabled-until-re-enrolled fallback when the key is unavailable. Runtime verification remains required.
|
||
|
||
Primary technical references checked during review: [MCP HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) defines a standards-based OAuth profile; our custom controlled-client profile does not claim that interoperability. [Git update-ref](https://git-scm.com/docs/git-update-ref.html) supports publication conditioned on the expected previous object ID. These sources support mechanisms, not the correctness of an unimplemented service.
|
||
|
||
## Promoted baseline
|
||
|
||
The revised [architecture](../architecture/ARCHITECTURE.md) retains Python/FastAPI, React/TypeScript/Vite, private Git-backed canonical records, private source artifacts and derived SQLite retrieval. Engineering protocols remain in [development](../development/DEVELOPMENT_PROTOCOL.md), [visual design](../development/VISUAL_DESIGN_PROTOCOL.md), [agent/security](../development/AGENT_SECURITY_PROTOCOL.md) and [operations](../development/OPERATIONS_PROTOCOL.md).
|
||
|
||
The changes concentrate detail at four implementation boundaries. They do not settle production auto-acceptance policy, name owners, choose sampling thresholds, supply the evaluation corpus or invent hosting capacity. Those remain explicitly open in the architecture. Exact dependency locks, machine-readable schemas and executable acceptance cases are M0 work.
|
||
|
||
## Verification scope
|
||
|
||
Final documentation checks passed across nine files: 38 local links, including four heading anchors, resolved; fenced blocks were balanced and no trailing whitespace was found. `git diff --check` passed, with existing GOAL/PRD line-ending notices. A 76-pattern plain-language scan returned no matches. These are documentation checks, not runtime tests.
|
||
|
||
The proposed palette was checked numerically against canvas, paper and subtle backgrounds. Text colors had a minimum contrast of 5.17:1; the separate control-boundary color had a minimum of 3.41:1 and is not a text color. These calculations do not establish rendered accessibility, focus behavior or browser layout. No visual page has been implemented or rendered.
|
||
|
||
Manual prose review preserved technical lists and distinctions rather than removing necessary specification detail.
|
||
|
||
Existing GOAL/PRD and prior review edits were preserved. Concurrent GEWU naming/intro edits were retained. No commit, dependency installation, source-service implementation, deployment or live harness acceptance is part of this change.
|