Build And Contract Mechanics

If a route shape, manifest shape, or output contract is invalid, the build must stop before it writes any staged files.

14. Invariants Must Fail Before Writes

If a route shape, manifest shape, or output contract is invalid, the build must stop before it writes any staged files.

Do not hide invariant checks inside late render helpers after the filesystem work has already started.

15. Timing Dependencies Must Be Encoded

If code depends on defer, DOMContentLoaded, or worker isolate reuse, that dependency must be encoded in the implementation or removed.

Do not rely on “this file is always loaded that way” as an invisible contract.

16. Shared Assets Must Be Registered Once

If two surfaces use the same stylesheet or SVG, register it once in the shared asset contract.

Two identical registrations with separate cache rules are already one drift away from a bug.

17. Manifests Need Lightweight Validation

If a JSON file drives routing or public output, validate:

• required fields
• types
• duplicates
• extension or path shape

That check should run at build start, not after a broken page has already been emitted.

18. Feature Detection Must Traverse The Real Tree

When build behavior depends on a token or node type, scan the full tree.

Do not assume the relevant token will always sit at the top level.

Nested lists, quotes, and wrapper nodes are part of the real input shape.

19. Renderer And Runtime Must Share The Same DOM Contract

If the renderer emits selectors that a runtime script consumes later, those selectors must live in one exported contract.

Do not let:

• the renderer invent class names
• the runtime rediscover them separately

That is the same drift class as duplicated CSS or duplicated routes.

20. Names Must Match Real Semantics

If two cache policies, route helpers, or status constants have the same value and the same real behavior, they should not keep separate historical names.

Misleading names create fake complexity and invite incorrect future edits.

21. CSS Selectors Are Contracts Too

If HTML emits a class that CSS depends on later, that class belongs in a shared contract just as much as a route or a CSP literal.

Do not leave renderer class names as free strings in one file and stylesheet selectors as free strings in another.

22. Runtime Caching Should Match Runtime Cost

Do not add runtime caches just because a worker isolate can keep them alive.

Cache derived state only when it materially reduces cost and does not add more contract surface than it removes.

For tiny pure renders, recomputation is often leaner than cache invalidation logic.

23. Template Injection Must Fail Loud

If build code injects config into a runtime source file through placeholders, assert that every placeholder exists exactly once.

Silent replacement misses are just broken runtime code with worse debugging.

24. CSP Must Match Real Browser Behavior

A CSP is not correct because it looks strict on paper.

It must also match what the real browser runtime actually does:

• external script origins
• inline style emission
• dynamically injected runtime behavior

25. Mermaid Source Stays Text-Only

Public Mermaid diagrams must stay plain text.

Do not rely on embedded HTML such as <br/> to shape labels.

If a diagram needs line breaks, use Mermaid-native multiline text instead of raw HTML.

26. Generated Route Collisions Must Fail Loud

If two pages or aliases produce the same emitted pathname or header target, the build must stop immediately.

Do not silently skip the second writer.