Shared Contracts
The main source of avoidable complexity was duplicated truth.
1. Contracts Must Have One Owner
The main source of avoidable complexity was duplicated truth.
The fix is simple:
- one owner for routing
- one owner for page metadata
- one owner for CSP
- one owner for shared shell and spacing
- one owner for brand assets
If two sibling files carry the same contract, drift has already started.
2. Shared UI Must Live Once
Landing pages, manuals, and workers may extend the same visual system, but they must not fork it casually.
The reusable contract now lives in shared UI primitives:
- tokens
- styles
- shared assets
- shared shell components
That is the only reliable way to keep typography, spacing, colors, SVGs, and framing identical across surfaces.
3. Generated Output Is Not Source
Several earlier problems came from fixing generated files instead of the real source that produces them.
The stable rule is:
- edit source under versioned repo paths
- regenerate the built site
- never treat
site/output as hand-authored logic
4. Surface Splits Beat Monoliths
The code became cleaner only after splitting by runtime surface:
- shared core
- manual surface
- root landing surface
That split is leaner than one giant file because each surface can import the contracts it actually uses.
5. Security Must Be Shared, But Tight
Security headers must be shared from one contract, not repeated across build scripts and workers.
At the same time, permissions should stay narrow:
- pin external browser scripts with the real runtime primitive, which is SRI in the HTML tag
- let CSP allow the trusted origin instead of pretending the CSP hash is the execution pin
- derive font CSP origins from the same source as font preconnect links
- keep SVG asset CSP stricter than page CSP
- fail unknown routes with
404
6. Equivalent Paths Need Equivalent Validation
Several real bugs came from validating one case but not its sibling:
- relative asset links were checked while absolute asset links were trusted
- registry SVGs received sandbox CSP while copied SVGs did not
- generated page contracts were validated more strictly than hardcoded root contracts
That is now a named bug class in the platform.