Skip to content

docs(arch): tighten the architecture diagram prose and guard - #1126

Merged
mforce merged 1 commit into
mainfrom
docs/architecture-deslop
Oct 7, 2026
Merged

mforce merged 1 commit into
mainfrom
docs/architecture-deslop

Conversation

@mforce

@mforce mforce commented Oct 7, 2026

Copy link
Copy Markdown
Owner

Rewrites prose in docs/architecture.md that read as padding or jargon, and removes counts copied from code that had gone stale. Every diagram is unchanged, and so is the guard CouplingMatrixRealTreeTests.RealTree_FeatureModuleDiagramNamesExactlyTheLedgerOwners.

Follows #1098, whose code and prose were never cleaned up.

What changed

  • Request pipeline intro. The old text said the full list "runs to 30 entries (22 Use* registrations, seven terminal/map registrations, and app.Run())". Program.cs on main has 22 app.Use* calls but far more than seven map lines. The new text says the diagram shows only the steps whose order matters and points to Program.cs for the full list.
  • Lock sweep cutoff. The prose named the constant LockAfterDays in place of a copied "7". The diagram label still reads "7 days", because the diagrams are unchanged.
  • Wording. I replaced em-dash asides, parentheses, "load-bearing", "decisions, not accidents", "in its own right", "is real — but" and "The mechanism is ready; the writer is not" with plain sentences. I also moved passive phrasings ("are drawn", "are refused by the browser", "is covered by") to the active voice.
  • Feature modules. "(Farm also declares a small seam)" is now its own sentence: other modules, never endpoints, may also use Farm's seam.

Untouched: the four diagrams; the two table rows changed in #1124; the guard, which deslop found clean.

Claims checked against code

Claim kept Where
Lock cutoff is a named constant DailyEntryLockSweep.LockAfterDays = 7
Flock scope skips a /error re-execution FlockScopeResolutionMiddleware.cs, IExceptionHandlerFeature check
No production path writes RestrictedUntil SetWithdrawalRestriction is called only from tests
The simulation seeder asserts Shipped and Invoiced stay zero SimulationDataSeeder.cs, two Check(... == 0) lines

Proof

  • Guard still fails. I deleted the Finance node from the feature-modules diagram, and the guard turned red: Assert.Equal() Failure: Collections differ, with "Finance" expected but missing. I restored the file before committing.
  • Doc guards at the head. CouplingMatrixRealTreeTests and TenancyDocsFreshnessTests pass 4/4. The SchemaDocsTests image-pin guards pass 2/2.

Plain wording throughout docs/architecture.md, and no hand-copied counts
that a code change can falsify. Diagrams and the guard are unchanged.

Refs #1098
@mforce
mforce merged commit 53b3e3b into main Oct 7, 2026
14 checks passed
@mforce
mforce deleted the docs/architecture-deslop branch October 7, 2026 00:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant