From docs/design-review-2026-08.md §B5.
Problem
The commons' mechanism is "apps must register commons types exactly as written" — enforced today by copy-pasting TypeScript out of markdown. The first drift the drift-guard catches in the wild will be a typo'd hand-copy of a commons schema. The planned @haverstack/commons package is already specified in the commons README and makes drift structurally impossible rather than socially discouraged; it should exist before the first external app does.
Work items
Cross-refs: #63, commons README §Planned tooling, design-review-2026-08 §B5.
From
docs/design-review-2026-08.md§B5.Problem
The commons' mechanism is "apps must register commons types exactly as written" — enforced today by copy-pasting TypeScript out of markdown. The first drift the drift-guard catches in the wild will be a typo'd hand-copy of a commons schema. The planned
@haverstack/commonspackage is already specified in the commons README and makes drift structurally impossible rather than socially discouraged; it should exist before the first external app does.Work items
@haverstack/commons: canonical schemas as exported constants +defineCommonsTypes(stack, [...])helper, per the commons README's own plan; Draft-status types only (Proposed stay docs-only until they graduate)docs/commons/:photois still "Staged — pending file-ref field kind: content-held file references are invisible to the reference checks the spec says exist #63" andembedawaits "oncefile-reffields (file-ref field kind: content-held file references are invisible to the reference checks the spec says exist #63) land," but file-ref field kind: content-held file references are invisible to the reference checks the spec says exist #63 landed (file-refis a shipped, indexed kind). Graduatephotoper its own criterion and record it in the changelog; revisit theembedfollow-up noteCross-refs: #63, commons README §Planned tooling, design-review-2026-08 §B5.