#!/usr/bin/env tsx /** * Docs generator — derives every STRUCTURAL page of `docs/reference/` from the * repository itself, so the map can never drift from the territory. * * Why this exists: * The hand-written structure map in `AGENTS.md` listed 9 packages that no * longer existed (`kernel`, `core`, `addon-detection-pipeline`, …) and 8 of * its 24 file references were dead. Nothing failed, because nothing checked. * The fix is not "be more disciplined": it is to stop writing by hand what * can be read from the workspace. * * What is generated (never edit these by hand — the pre-commit hook and CI * both overwrite them): * docs/reference/packages.md every workspace package + its role * docs/reference/addons.md every addon manifest entry * docs/reference/capabilities.md every `*.cap.ts` + who provides it * docs/reference/guards.md every `scripts/check-*` guard + is CI running it * docs/reference/subsystems.md the curated chapters × what claims them * docs/reference/coverage.md the same join, pivoted by unit of code * docs/decisions/index.md the ADR log, from each ADR's own frontmatter * * What is NOT generated: intent. Architecture explanations, decisions (ADRs) * are human/agent prose, guarded separately by * `check-docs-drift.ts` (dead-path + staleness checks). * * Usage: * npm run docs:generate — write the files * npm run docs:generate -- --check — fail if what is on disk differs * (CI drift guard; used by docs:check) */ import * as fs from 'node:fs' import * as path from 'node:path' import { HISTORY_CATALOG, HISTORY_ITEM_CATALOG, HISTORY_NONE_CAPS, } from '../packages/types/src/generated/history-catalog.js' import { type CapInfo, parseAllCaps } from './lib/parse-cap.js' import { buildDurableCatalogue, buildStorageMap, type DurableAnnotation, type StorageMap, } from './lib/parse-storage.js' import { renderCoveragePage, renderSubsystemsPage } from './lib/subsystem-map.js' import { loadSubsystemMap } from './lib/subsystem-map-repo.js' const ROOT = path.resolve(import.meta.dirname, '..') const CAPS_DIR = path.join(ROOT, 'packages', 'types', 'src', 'capabilities') const OUT_DIR = path.join(ROOT, 'docs', 'reference') const SCRIPTS_DIR = path.join(ROOT, 'scripts') const DECISIONS_DIR = path.join(ROOT, 'docs', 'decisions') /** * The workflows a guard can be enforced by: `ci.yml` (automatic, build + test) * and `checks.yml` (on demand — guards, ratchet, docs, e2e; D704). */ const CI_WORKFLOWS: readonly string[] = [ path.join(ROOT, '.github', 'workflows', 'ci.yml'), path.join(ROOT, '.github', 'workflows', 'checks.yml'), ] const SETTINGS_BACKEND = path.join( ROOT, 'packages/system/src/builtins/sqlite-storage/sqlite-settings-backend.ts', ) const BANNER = [ '', '', ].join('\n') // ── Workspace model ──────────────────────────────────────────────────────── /** One addon declared inside a package manifest's `camstack.addons[]`. */ interface AddonManifest { readonly id: string readonly category: string readonly placement: string readonly group: string | null readonly instanceMode: string | null readonly capabilities: readonly string[] /** `@camstack/server/system` builtin that opted out of running in hub-main. */ readonly isolate: boolean /** The package the manifest came from — decides in-process vs own runner. */ readonly packageName: string } /** A workspace package as the docs care about it. */ interface PackageInfo { readonly dir: string readonly name: string readonly version: string readonly private: boolean /** `camstack.system: true` — host-provided, cannot be uninstalled. */ readonly system: boolean readonly description: string readonly addons: readonly AddonManifest[] } type PackageRole = 'framework' | 'addon' | 'tooling' | 'app' function readJson(file: string): Record { const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8')) return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record) : {} } function asString(value: unknown, fallback: string): string { return typeof value === 'string' ? value : fallback } function asRecord(value: unknown): Record | null { return value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record) : null } function parseAddonManifests( camstack: Record | null, packageName: string, ): AddonManifest[] { if (!camstack) return [] const raw = camstack['addons'] if (!Array.isArray(raw)) return [] const out: AddonManifest[] = [] for (const entry of raw) { const addon = asRecord(entry) if (!addon) continue const execution = asRecord(addon['execution']) const capsRaw = addon['capabilities'] const capabilities: string[] = [] if (Array.isArray(capsRaw)) { for (const cap of capsRaw) { const capRecord = asRecord(cap) if (capRecord && typeof capRecord['name'] === 'string') capabilities.push(capRecord['name']) } } out.push({ id: asString(addon['id'], '(unnamed)'), category: asString(addon['category'], '—'), placement: execution ? asString(execution['placement'], 'any-node') : 'any-node', group: execution && typeof execution['group'] === 'string' ? execution['group'] : null, instanceMode: typeof addon['instanceMode'] === 'string' ? addon['instanceMode'] : null, capabilities: capabilities.toSorted(), isolate: execution?.['isolate'] === true, packageName, }) } return out } /** Every workspace package under `packages/` + `server/`, flat one level. */ function collectPackages(): PackageInfo[] { const out: PackageInfo[] = [] for (const root of ['packages', 'server']) { const rootDir = path.join(ROOT, root) if (!fs.existsSync(rootDir)) continue for (const entry of fs.readdirSync(rootDir, { withFileTypes: true }).toSorted()) { if (!entry.isDirectory()) continue const pkgJson = path.join(rootDir, entry.name, 'package.json') if (!fs.existsSync(pkgJson)) continue const pkg = readJson(pkgJson) const camstack = asRecord(pkg['camstack']) out.push({ dir: `${root}/${entry.name}`, name: asString(pkg['name'], `${root}/${entry.name}`), version: asString(pkg['version'], '—'), private: pkg['private'] === true, system: camstack !== null && camstack['system'] === true, description: asString(pkg['description'], ''), addons: parseAddonManifests(camstack, asString(pkg['name'], `${root}/${entry.name}`)), }) } } return out } /** `@camstack/*` dependencies of the root package = the shipped closure. */ function rootClosureDeps(): ReadonlySet { const pkg = readJson(path.join(ROOT, 'server', 'backend', 'package.json')) const deps = asRecord(pkg['dependencies']) ?? {} return new Set(Object.keys(deps).filter((d) => d.startsWith('@camstack/'))) } /** * Role classification, DERIVED — no hand-kept list to rot. * * Deliberately keyed off the root package's dependency closure rather than the * `camstack.system` manifest flag, because the two disagree: `types` and `sdk` * declare `camstack.system: false` yet are framework by every * operational measure (the image's own seed script excludes exactly * `system,types,sdk,ui-library` from the addon seed — Dockerfile:76). * The flag means "surface it in the Admin UI's un-uninstallable section"; the * closure means "this is how the code reaches a node". Roles follow the latter. * * Order matters: `system` itself is in the closure AND declares 19 addon * manifests (the builtins), so the framework test has to win first. */ function roleOf(pkg: PackageInfo, closure: ReadonlySet): PackageRole { if (pkg.dir.startsWith('server/')) return 'app' const inClosure = closure.has(pkg.name) if (inClosure && (pkg.system || pkg.addons.length === 0)) return 'framework' if (pkg.addons.length > 0) return 'addon' return 'tooling' } /** * How a package's code actually reaches a running node — the distinction that * decides whether `Update all` (a root-package install) picks a change up, or * whether it needs `camstack deploy`. */ function shipsVia(pkg: PackageInfo, role: PackageRole, closure: ReadonlySet): string { if (role === 'app') return 'the update itself' if (role === 'framework') return '`@camstack/server` closure' // The Publish Packages workflow skips exactly `private: true` packages, so the // manifest alone says whether a tool is on npm — no registry call in a generator. if (role === 'tooling') return pkg.private ? 'not published (private)' : 'npm, standalone tool' return closure.has(pkg.name) ? 'addons dir (image-seeded)' : 'addons dir' } // ── Renderers ────────────────────────────────────────────────────────────── function mdTable(headers: readonly string[], rows: readonly (readonly string[])[]): string { const head = `| ${headers.join(' | ')} |` const sep = `| ${headers.map(() => '---').join(' | ')} |` const body = rows.map((r) => `| ${r.join(' | ')} |`).join('\n') return [head, sep, body].join('\n') } function code(value: string): string { return value.length > 0 ? `\`${value}\`` : '—' } function renderPackages(pkgs: readonly PackageInfo[]): string { const closure = rootClosureDeps() const byRole = (role: PackageRole): PackageInfo[] => pkgs.filter((p) => roleOf(p, closure) === role) const section = (title: string, note: string, rows: readonly PackageInfo[]): string => [ `## ${title} (${rows.length})`, '', note, '', mdTable( ['Package', 'Directory', 'Version', 'Reaches a node via', 'What it is'], rows.map((p) => [ code(p.name), code(p.dir), p.private ? '_private_' : p.version, shipsVia(p, roleOf(p, closure), closure), p.description.length > 0 ? p.description.replaceAll('|', '\\|') : '—', ]), ), '', ].join('\n') return [ BANNER, '# Packages', '', `${pkgs.length} workspace packages. Roles are derived: \`camstack.system: true\` →`, 'framework; a `camstack.addons[]` entry → addon; `server/*` → the root app;', 'everything else → tooling.', '', section( 'App', 'The single root package every node boots. Hub vs agent is `CAMSTACK_ROLE`, not a different package.', byRole('app'), ), section( 'Framework', [ 'Host-provided: addons do NOT bundle these, they resolve them from the running', 'closure. Consequence worth knowing: a framework change reaches a node ONLY', 'through a root-package install (`applyServerUpdate` / "Update all"), pinned to', 'the exact version the published `@camstack/server` carries. `camstack deploy`', 'cannot ship it.', ].join(' '), byRole('framework'), ), section( 'Addons', [ 'Each declares one or more `camstack.addons[]` entries and lives in', '`/addons/`. Updated with `camstack deploy` (or the Addons page) —', 'NOT by a root-package update. The ones marked _image-seeded_ are also', 'dependencies of the root package: the image copies them into the addons dir on', 'first boot, after which the addons-dir copy is what loads and the closure copy', 'is inert.', ].join(' '), byRole('addon'), ), section('Tooling', 'Build, dev and CLI packages. Not loaded at runtime.', byRole('tooling')), ].join('\n') } /** * Where the addon's code actually executes. A `@camstack/server/system` builtin is * in-process on hub-main by default; `execution.isolate` opts it out. */ function addonProcess(addon: AddonManifest): string { if (addon.packageName !== '@camstack/server') return 'own runner' return addon.isolate ? 'own runner (`isolate`)' : 'hub-main' } function renderAddons(pkgs: readonly PackageInfo[]): string { interface Row { readonly addon: AddonManifest readonly pkg: PackageInfo } const rows: Row[] = [] for (const pkg of pkgs) for (const addon of pkg.addons) rows.push({ addon, pkg }) rows.sort((a, b) => a.addon.id.localeCompare(b.addon.id)) const categories = [...new Set(rows.map((r) => r.addon.category))].toSorted() return [ BANNER, '# Addons', '', `${rows.length} addon manifests across ${new Set(rows.map((r) => r.pkg.name)).size} packages.`, '', 'One addon = one `addon-runner` process by default. A shared `execution.group`', 'collapses its members into ONE process so their cap calls resolve in-process', '— that is the only reason to use it.', '', '`Process` says WHERE the addon actually runs. `@camstack/server` builtins are', 'resident in hub-main — they hold the storage/settings/logging every runner', 'depends on — unless the manifest declares `execution.isolate`, which forks the', 'builtin like any other addon. Reading "system package" as "in hub-main" is what', 'this column exists to stop.', '', mdTable( [ 'Addon id', 'Package', 'Category', 'Process', 'Placement', 'Group', 'Instances', 'Capabilities', ], rows.map((r) => [ code(r.addon.id), code(r.pkg.name), r.addon.category, addonProcess(r.addon), code(r.addon.placement), r.addon.group === null ? '—' : code(r.addon.group), r.addon.instanceMode ?? '—', r.addon.capabilities.length > 0 ? r.addon.capabilities.map((c) => `\`${c}\``).join(' ') : '—', ]), ), '', '## Categories', '', categories .map((c) => `- \`${c}\` — ${rows.filter((r) => r.addon.category === c).length}`) .join('\n'), '', ].join('\n') } /** The History column: series count from the generated catalog, `none`, or absent. */ function historyCell(capName: string): string { const fields = HISTORY_CATALOG[capName] const items = HISTORY_ITEM_CATALOG[capName] const parts = [ ...(fields !== undefined ? [`${Object.keys(fields).length} series`] : []), ...(items !== undefined ? [`${Object.keys(items.fields).length} per item`] : []), ] if (parts.length > 0) return parts.join(' + ') return HISTORY_NONE_CAPS.includes(capName) ? 'none' : '—' } function renderCapabilities(caps: readonly CapInfo[], pkgs: readonly PackageInfo[]): string { /** cap name → addon ids that declare it in their manifest. */ const providers = new Map() for (const pkg of pkgs) { for (const addon of pkg.addons) { for (const capName of addon.capabilities) { const list = providers.get(capName) ?? [] list.push(addon.id) providers.set(capName, list) } } } const sorted = [...caps].toSorted((a, b) => a.capName.localeCompare(b.capName)) const deviceCaps = sorted.filter((c) => c.scope === 'device') const systemCaps = sorted.filter((c) => c.scope === 'system') const row = (c: CapInfo): readonly string[] => [ code(c.capName), c.methods.length.toString(), c.hasStatus ? '✓' : '—', c.hasRuntimeState ? '✓' : '—', historyCell(c.capName), c.internal ? '✓' : '—', (providers.get(c.capName) ?? []).map((a) => `\`${a}\``).join(' ') || '—', ] const headers = [ 'Capability', 'Methods', 'status', 'runtimeState', 'History', 'internal', 'Declared by', ] return [ BANNER, '# Capabilities', '', `${sorted.length} capability definitions in \`packages/types/src/capabilities/\`.`, 'The `.cap.ts` file is the single source of truth: codegen derives the tRPC', 'routers, the status-type map and the `DeviceProxy` facade from it. Touching a', 'cap without `npm run codegen` = silent drift.', '', "`History` is the cap's `history` block (D850): the number of `runtimeState` fields", 'recorded as long-term series, `none` when the cap answered so explicitly, `—` when it', 'has no `runtimeState`.', '', '`Declared by` lists the addons whose manifest declares the cap. Empty means no', 'installed addon declares it — either it is server-provided, or the cap is', 'registered at runtime only (`registerNativeCap` from a `BaseDevice`).', '', `## Device-scoped (${deviceCaps.length})`, '', 'Resolved per device via `CapabilityRegistry.getProviderForDevice(cap, deviceId)`.', '', mdTable(headers, deviceCaps.map(row)), '', `## System-scoped (${systemCaps.length})`, '', 'Singleton or collection providers, addressed without a device.', '', mdTable(headers, systemCaps.map(row)), '', ].join('\n') } // ── Guards ───────────────────────────────────────────────────────────────── interface GuardInfo { readonly file: string readonly summary: string /** * `ci`: named by a step in ci.yml. `package`: lives as a spec inside the * package it judges and runs with that package's `test` target — on every * push that affects the package, and always on the nightly (D548). * `unwired`: exists in `scripts/` and nothing runs it. */ readonly home: 'ci' | 'package' | 'unwired' } /** * Guards that moved INTO the package they judge (D548): a `*.guard.ts` under * `src/__tests__/guards/`, with a sibling spec that asserts the checked-out * package passes and that the violation the guard was written for still * fails. They do not appear in ci.yml by name; `nx affected -t test` runs * them. Without this collector the reference page would report every moved * guard as gone — a page that under-reports enforcement reads as verification. */ function packageGuards(): GuardInfo[] { const out: GuardInfo[] = [] for (const group of ['packages', 'server']) { const groupDir = path.join(ROOT, group) if (!fs.existsSync(groupDir)) continue for (const pkg of fs.readdirSync(groupDir).toSorted()) { const dir = path.join(groupDir, pkg, 'src', '__tests__', 'guards') if (!fs.existsSync(dir)) continue for (const entry of fs.readdirSync(dir).toSorted()) { if (!entry.endsWith('.guard.ts')) continue const rel = `${group}/${pkg}/src/__tests__/guards/${entry}` const source = fs.readFileSync(path.join(ROOT, rel), 'utf-8') out.push({ file: rel, summary: docblockSummary(source), home: 'package' }) } } } return out } /** * First sentence of a script's leading docblock — the one line that says what it * refuses to let you commit. Taken from the source rather than a hand-kept list * so a new guard documents itself the moment it lands. */ function docblockSummary(source: string): string { // NOT anchored to position 0: these files open with a `#!/usr/bin/env tsx` // shebang, so the docblock is never the first thing in the file. const block = /\/\*\*([\s\S]*?)\*\//.exec(source) if (!block) return '—' const lines = block[1] .split('\n') .map((l) => l.replace(/^\s*\*\s?/, '').trim()) .filter((l) => l.length > 0) if (lines.length === 0) return '—' // Join until the first sentence end, so a wrapped opening line stays whole. let text = '' for (const line of lines) { text = text.length === 0 ? line : `${text} ${line}` if (/[.!?]$/.test(text)) break } // Drop the `name — ` prefix convention; the table already has the filename. const summary = text.replace(/^[\w.\-/]+\s+[—-]\s+/, '').replaceAll('|', '\\|') return summary.length > 240 ? `${summary.slice(0, 237)}…` : summary } /** * `ci.yml` with every YAML comment removed. * * The enforcement check below is a substring match, and `ci.yml` carries a * comment saying `scripts/lint-double-cast.sh` is deliberately NOT run — which * made the generated table list it under "Enforced by CI". A page that promises * a guard nobody runs is worse than no page: it reads as verification. Comments * describe intent, only steps enforce it, so only steps are searched. * * Naive, not a YAML parser: a `#` inside a quoted string would be cut too. That * direction is safe — it can only UNDER-report enforcement, never invent it. */ function ciWorkflowSteps(): string { return CI_WORKFLOWS.filter((file) => fs.existsSync(file)) .map((file) => fs .readFileSync(file, 'utf-8') .split('\n') .map((line) => line.replace(/#.*$/, '')) .join('\n'), ) .join('\n') } /** * A guard counts as CI-enforced if `ci.yml` names the file directly OR runs an * npm script whose command does. Without the second hop every guard invoked as * `npm run check-deps` would be mis-reported as unwired. * * A guard run INDIRECTLY — `lint-double-cast.sh`, which `check-ci-baselines.ts` * shells out to — is named in the step's `name:` so this still sees it. Chasing * script-to-script references instead was tried and reported five guards as * enforced because `codegen.ts` merely mentions them. */ function ciEnforcedGuards(): ReadonlySet { const ci = ciWorkflowSteps() const scripts = asRecord(readJson(path.join(ROOT, 'package.json'))['scripts']) ?? {} const reachable: string[] = [] for (const [name, command] of Object.entries(scripts)) { if (typeof command !== 'string') continue if (ci.includes(`npm run ${name}`)) reachable.push(command) } const haystack = [ci, ...reachable].join('\n') const out = new Set() for (const entry of fs.readdirSync(SCRIPTS_DIR)) { if (haystack.includes(entry)) out.add(entry) } return out } function collectGuards(): GuardInfo[] { const enforced = ciEnforcedGuards() const out: GuardInfo[] = [] for (const entry of fs.readdirSync(SCRIPTS_DIR).toSorted()) { const isGuard = (entry.startsWith('check-') || entry.startsWith('lint-')) && /\.(ts|sh)$/.test(entry) && !entry.includes('.spec.') if (!isGuard) continue const source = fs.readFileSync(path.join(SCRIPTS_DIR, entry), 'utf-8') out.push({ file: `scripts/${entry}`, summary: docblockSummary(source), home: enforced.has(entry) ? 'ci' : 'unwired', }) } return [...out, ...packageGuards()] } function renderGuards(guards: readonly GuardInfo[]): string { const enforced = guards.filter((g) => g.home === 'ci') const inPackage = guards.filter((g) => g.home === 'package') const local = guards.filter((g) => g.home === 'unwired') return [ BANNER, '# Guards', '', `${guards.length} repository guards: ${String(enforced.length + local.length)} in \`scripts/\`,`, `${String(inPackage.length)} as tests inside the package they judge. A guard is the only`, 'durable form of a convention: a rule nothing checks is a rule that has already', 'been broken somewhere. Prefer adding one over adding a paragraph.', '', `## Enforced by CI checks (${enforced.length})`, '', 'Referenced by name in `.github/workflows/checks.yml` (on demand, D704) or `ci.yml`.', '', mdTable( ['Guard', 'Refuses'], enforced.map((g) => [code(g.file), g.summary]), ), '', `## Enforced as package tests (${inPackage.length})`, '', 'A guard that reads ONE package lives in it, as `src/__tests__/guards/*.guard.ts`', 'with a spec beside it (D548). `nx affected -t test` runs it on every push that', 'touches the package; the nightly runs it always. Its spec must carry the', 'violation the guard was written for, so a broken guard cannot pass in silence.', '', mdTable( ['Guard', 'Refuses'], inPackage.map((g) => [code(g.file), g.summary]), ), '', `## Available but not wired into CI (${local.length})`, '', 'Run manually, from a hook, or via another script. If one of these encodes a', 'rule that matters, wiring it into `checks.yml` is a one-line change.', '', mdTable( ['Guard', 'Refuses'], local.map((g) => [code(g.file), g.summary]), ), '', ].join('\n') } // ── Decision log ─────────────────────────────────────────────────────────── interface AdrInfo { readonly file: string readonly id: string readonly title: string readonly status: string readonly date: string readonly supersedes: string } /** Minimal frontmatter read — the 5 keys the ADR template declares. */ function adrFrontmatter(body: string): Record { if (!body.startsWith('---\n')) return {} const end = body.indexOf('\n---', 4) if (end === -1) return {} const out: Record = {} for (const line of body.slice(4, end).split('\n')) { const kv = /^([\w-]+):\s*(.*)$/.exec(line) if (kv) out[kv[1]] = kv[2].trim().replaceAll(/^['"]|['"]$/g, '') } return out } function collectAdrs(): AdrInfo[] { if (!fs.existsSync(DECISIONS_DIR)) return [] const out: AdrInfo[] = [] for (const entry of fs.readdirSync(DECISIONS_DIR).toSorted()) { // `index.md` is this function's own output; `conventions.md` explains the log // and `template.md` is the blank — none of the three is a decision. (The // conventions page is NOT called README.md because MkDocs treats a directory's // README as its index, which would collide with the generated index.) const notADecision = new Set(['index.md', 'conventions.md', 'template.md']) if (!entry.endsWith('.md') || notADecision.has(entry)) continue const fm = adrFrontmatter(fs.readFileSync(path.join(DECISIONS_DIR, entry), 'utf-8')) out.push({ file: entry, id: fm['id'] ?? entry.split('-')[0], title: fm['title'] ?? entry.replace(/\.md$/, ''), status: fm['status'] ?? 'unknown', date: fm['date'] ?? '—', supersedes: fm['supersedes'] ?? '', }) } return out } function renderDecisionIndex(adrs: readonly AdrInfo[]): string { const statusIcon = (status: string): string => status === 'accepted' ? '✅ accepted' : status === 'superseded' ? '↩︎ superseded' : status === 'proposed' ? '💭 proposed' : status return [ BANNER, '# Decisions', '', `${adrs.length} architecture decision records. One file per decision, never`, 'edited after acceptance — a decision that turned out wrong gets a NEW record', 'that supersedes it, because the reasoning that led there is the part worth', 'keeping.', '', 'The `id` matches the invariant number used in code comments and `AGENTS.md`', '(`(D9)` → `adr-0009`), so a comment can point at its rationale without a link', 'that rots.', '', mdTable( ['#', 'Decision', 'Status', 'Date'], adrs.map((a) => [ a.id, `[${a.title}](${a.file})`, statusIcon(a.status) + (a.supersedes.length > 0 ? ` (supersedes ${a.supersedes})` : ''), a.date, ]), ), '', 'Conventions, and why the numbering looks the way it does:', '[conventions.md](conventions.md). Adding one: copy `template.md`, take the next', 'free number, keep it short. The table above is generated — you never edit it.', '', ].join('\n') } // ── Entry ────────────────────────────────────────────────────────────────── interface GeneratedFile { readonly file: string readonly content: string } function renderStorage(map: StorageMap, durable: ReadonlyMap): string { const lines: string[] = [BANNER, '# Storage map', ''] lines.push( 'Every SQLite table CamStack creates, and the file that owns it. There is no', 'schema file to read — tables come into existence five different ways, so a', 'map showing only one of them would be worse than none.', '', '**Columns are deliberately not listed here.** They live in the owning file,', 'which this table points at; duplicating them is how a reference rots. The', 'pointer stays true through any rename the compiler accepts.', '', '## 1. Canonical key-value collections', '', 'A fixed list in `SqliteSettingsBackend`, each `(id TEXT PRIMARY KEY, data TEXT', 'NOT NULL)` — the whole record is JSON in `data`.', '', ) lines.push( mdTable( ['Collection'], map.canonical.map((c) => [code(c)]), ), ) lines.push( '', '## 2. Per-addon scoped variants', '', 'Any addon writing through `ctx.settings` gets `:` — for', 'example `pipeline-analytics:addon-devices`. These are created ON DEMAND at the', 'first write and are declared nowhere, so **a live hub holds tables that appear', 'in no source file**. Only the rule is derivable; the list is not. To see the', 'real set, read `sqlite_master` on the running node.', '', '> This is also the trap behind "the setting saved but the addon never saw it":', "> two different tables, both plausible. See the repo's per-device-store note.", '', '## 3. Declared collections', '', 'An addon calls `declareCollection` (directly or over tRPC) with its own', 'columns and indexes. These are the typed, domain-owned tables.', '', ) lines.push( mdTable( ['Collection', 'Owned by'], map.declared.map((d) => [code(d.name), code(d.file)]), ), ) lines.push( '', '### 3a. Semantic class — what losing a table would cost', '', 'A name says nothing about whether losing a table is a bug. The classes are:', '', mdTable( ['Class', 'Means', 'Rule'], [ [ '`ledger`', 'a fact only this component ever held — "the last observation I ACCEPTED"', 'must be durable; must not be pruned against a fallible read', ], [ '`mirror`', 'a derived copy of an authority that lives elsewhere', 'rehydrated from the authority; a persisted copy may only prevent a cold window', ], ['`ephemeral`', 'correct to lose', 'must not be persisted'], ['`config`', 'operator intent', 'already durable everywhere'], ['`audit`', 'written for a human, never read back by the system', 'bounded, never a gate'], ], ), '', 'Declared in a `@durable` annotation on the collection-name constant, which', 'is the only authority for it — see `scripts/lib/parse-storage.ts`. Any', 'declared collection without one fails', '`scripts/check-durable-state-declared.ts`.', '', "That guard's shrink-only backlog reached **zero on 2026-08-14** — the 44", 'collections that predated the annotation are all classified, so the table', 'below is the WHOLE declared surface rather than the part somebody got to.', 'An unclassified collection can no longer appear here, because it cannot be', 'committed.', '', ) const classified = [...durable.values()].toSorted((a, b) => a.collection.localeCompare(b.collection), ) lines.push( mdTable( ['Collection', 'Class', 'Owner', 'Write trigger', 'Retention'], classified.map((d) => [ code(d.collection), code(d.semanticClass), code(d.owner), d.writeTrigger, d.retention, ]), ), ) lines.push('', '## 4. Not statically knowable', '') if (map.unresolved.length === 0) { lines.push('None — every call site resolves to a literal name.') } else { lines.push( 'Call sites whose table name is an expression. Listed rather than dropped:', 'a map that silently omits what it could not parse reads as "that is all', 'there is".', '', ) lines.push( mdTable( ['Expression', 'File'], map.unresolved.map((u) => [code(u.name), code(u.file)]), ), ) } return lines.join('\n') } /** * `--only a,b` restricts generation to those output basenames. * * It exists for the pre-commit hook, and the reason is measured: the storage map * costs 45 of this script's 60 seconds (it parses the whole workspace twice), * while the subsystem join costs 0.7. The hook must regenerate the subsystem * pages whenever a source file is ADDED or DELETED or a document's frontmatter * changes — which is far more commits than a manifest change — and a hook that * adds a minute to those commits is a hook people learn to bypass with `-n`. */ function onlyFilter(): ReadonlySet | null { const index = process.argv.indexOf('--only') if (index < 0) return null const raw = process.argv[index + 1] if (raw === undefined) { console.error('✘ --only needs a comma-separated list of output basenames') process.exit(2) } return new Set(raw.split(',').map((s) => s.trim())) } function build(): GeneratedFile[] { const only = onlyFilter() const wanted = (name: string): boolean => only === null || only.has(name) const files: GeneratedFile[] = [] if (wanted('packages.md') || wanted('addons.md') || wanted('capabilities.md')) { const pkgs = collectPackages() if (wanted('packages.md')) { files.push({ file: path.join(OUT_DIR, 'packages.md'), content: renderPackages(pkgs) }) } if (wanted('addons.md')) { files.push({ file: path.join(OUT_DIR, 'addons.md'), content: renderAddons(pkgs) }) } if (wanted('capabilities.md')) { files.push({ file: path.join(OUT_DIR, 'capabilities.md'), content: renderCapabilities(parseAllCaps(CAPS_DIR), pkgs), }) } } if (wanted('guards.md')) { files.push({ file: path.join(OUT_DIR, 'guards.md'), content: renderGuards(collectGuards()) }) } if (wanted('storage.md')) { files.push({ file: path.join(OUT_DIR, 'storage.md'), content: renderStorage(buildStorageMap(ROOT, SETTINGS_BACKEND), buildDurableCatalogue(ROOT)), }) } // The subsystem index. Its ONE hand-written input is `docs/subsystems.yaml`; // both pages below are joins over it, the workspace and doc frontmatter. // // The file universe is the CACHED one (`git ls-files --cached`), never the // working tree. `--check` runs in CI against a fresh clone where nothing is // untracked, so a page counting the author's un-added scratch files could // never match and the docs job would be red on every machine but one. At // pre-commit time `--cached` is also exactly right: it is what the commit will // contain. if (wanted('subsystems.md') || wanted('coverage.md')) { const subsystems = loadSubsystemMap(ROOT, true) if (wanted('subsystems.md')) { files.push({ file: path.join(OUT_DIR, 'subsystems.md'), content: renderSubsystemsPage(subsystems, BANNER), }) } if (wanted('coverage.md')) { files.push({ file: path.join(OUT_DIR, 'coverage.md'), content: renderCoveragePage(subsystems, BANNER), }) } } // The decision index only exists once there are decisions to index. const adrs = wanted('index.md') ? collectAdrs() : [] if (adrs.length > 0) { files.push({ file: path.join(DECISIONS_DIR, 'index.md'), content: renderDecisionIndex(adrs), }) } return files } function main(): void { const checkMode = process.argv.includes('--check') const files = build() fs.mkdirSync(OUT_DIR, { recursive: true }) if (!checkMode) { for (const { file, content } of files) { fs.writeFileSync(file, `${content.trimEnd()}\n`, 'utf-8') console.log(` ✔ ${path.relative(ROOT, file)}`) } return } const drifted: string[] = [] for (const { file, content } of files) { const expected = `${content.trimEnd()}\n` const actual = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '' if (actual !== expected) drifted.push(path.relative(ROOT, file)) } if (drifted.length > 0) { console.error('\x1b[31m✘ generated docs are stale\x1b[0m — run `npm run docs:generate`:') for (const f of drifted) console.error(` ${f}`) process.exit(1) } console.log(' ✔ generated docs are in sync') } main()