From 0ed15f4fa62d595d16b809b27a6ace6a5f0a055c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 05:47:55 +0000 Subject: [PATCH 1/3] docs(spec): re-anchor the dead tracker citations in the packages/spec/src remainder to the commits and ADRs that decided them (stage 6) Comment and docblock lines only, 66 out and 66 in across 21 files; no code token, string literal or describe() text moves. Each dead number is replaced by the commit on main that decided what its line describes, or by the ADR that records the ruling (ADR-0029 D9.2a). Two dead sites stay byte-identical because a test reads them by literal: api-derivation.ts:163's [#6259] marker, and identity.zod.ts:230, whose deciding commit now sits on the next line. Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude --- packages/spec/src/ai/index.ts | 2 +- packages/spec/src/api/rest-server.zod.ts | 24 ++++++++-------- .../spec/src/automation/control-flow.zod.ts | 2 +- packages/spec/src/automation/execution.zod.ts | 2 +- packages/spec/src/automation/index.ts | 2 +- .../automation/schedule-organization.zod.ts | 4 +-- packages/spec/src/conversions/walk.ts | 2 +- packages/spec/src/data/driver/turso.zod.ts | 4 +-- packages/spec/src/identity/identity.zod.ts | 2 +- packages/spec/src/index.ts | 14 +++++----- .../meta-spelling/metadata-url-spelling.ts | 4 +-- packages/spec/src/security/explain.zod.ts | 2 +- packages/spec/src/security/public-form.ts | 2 +- packages/spec/src/shared/identifiers.zod.ts | 16 +++++------ .../src/shared/metadata-collection.zod.ts | 2 +- packages/spec/src/system/core-services.zod.ts | 2 +- packages/spec/src/system/dev-login.zod.ts | 2 +- .../src/system/environment-artifact.zod.ts | 4 +-- packages/spec/src/system/i18n-resolver.ts | 28 +++++++++---------- packages/spec/src/system/operation-message.ts | 8 +++--- packages/spec/src/system/translation.zod.ts | 4 +-- 21 files changed, 66 insertions(+), 66 deletions(-) diff --git a/packages/spec/src/ai/index.ts b/packages/spec/src/ai/index.ts index 12f67b2da75..9101b5cfd1a 100644 --- a/packages/spec/src/ai/index.ts +++ b/packages/spec/src/ai/index.ts @@ -41,7 +41,7 @@ export * from './build-progress.zod'; // [#12414] entry-nameability: these factories' return types expand to mention // `/data`'s `FilterCondition` and `/automation`'s `StateNodeConfig` — both // public on their own subpaths but not nameable from `/ai`. Same invariant -// (maintainer ruling recorded on #11350), same repair: re-export from the +// (maintainer ruling recorded in commit ece4dad31), same repair: re-export from the // declaring module. export type { FilterCondition } from '../data/filter.zod'; export type { StateNodeConfig } from '../automation/state-machine.zod'; diff --git a/packages/spec/src/api/rest-server.zod.ts b/packages/spec/src/api/rest-server.zod.ts index e69191ec8f6..1a2fe82c75a 100644 --- a/packages/spec/src/api/rest-server.zod.ts +++ b/packages/spec/src/api/rest-server.zod.ts @@ -325,11 +325,11 @@ export const CrudOperation = z.enum([ export type CrudOperation = z.input; -// `CrudEndpointPatternSchema` — REMOVED (#14691) +// `CrudEndpointPatternSchema` — REMOVED (commit b3a63d32c) // // The per-operation `{ method, path, summary, description }` pattern shape was // the value type of `crud.patterns`, retired below under ADR-0049 -// enforce-or-remove (the #14369 liveness census: every CRUD route is mounted +// enforce-or-remove (the liveness census commit a3d5724c8 recorded: every CRUD route is mounted // from fixed method/path pairs in `packages/rest`'s `registerCrudEndpoints`, // so a custom pattern was validated and never read). With its carrier key // tombstoned the def had no consumer left, and an exported schema nothing @@ -362,7 +362,7 @@ export const CrudEndpointsConfigSchema = lazySchema(() => z.object({ }).optional().describe('Enable/disable operations'), /** - * [REMOVED in #14691] Per-operation custom URL patterns. Tombstoned rather + * [REMOVED in commit b3a63d32c] Per-operation custom URL patterns. Tombstoned rather * than deleted: this schema is not `.strict()`, so a plain deletion would * silently strip the key and an author would keep a config that "customizes" * routes the server mounts from fixed pairs (ADR-0104, #3733). The mounted @@ -386,7 +386,7 @@ export const CrudEndpointsConfigSchema = lazySchema(() => z.object({ dataPrefix: z.string().default('/data').describe('URL prefix for data endpoints'), /** - * [REMOVED in #14691] The object-name parameter style. Every CRUD route takes + * [REMOVED in commit b3a63d32c] The object-name parameter style. Every CRUD route takes * the object name as a PATH segment; `'query'` was validated against the enum * and mounted exactly what `'path'` mounts. Tombstoned, not deleted — the * schema is not `.strict()` (see `patterns` above). @@ -445,7 +445,7 @@ export const MetadataEndpointsConfigSchema = lazySchema(() => z.object({ enableCache: z.boolean().default(true).describe('Enable HTTP cache headers (ETag, Last-Modified)'), /** - * [REMOVED in #14691] The metadata cache TTL. `enableCache` selects the + * [REMOVED in commit b3a63d32c] The metadata cache TTL. `enableCache` selects the * protocol's `getMetaItemCached` read path, which takes no TTL, and no * `Cache-Control` / `ETag` / `Last-Modified` header was ever built from this * value — `cacheTtl: 60` changed no header and no cache lifetime (and, having @@ -541,7 +541,7 @@ export const MetadataEndpointsConfigSchema = lazySchema(() => z.object({ + '`GET /meta/_drafts` and the `POST /meta/_migrate-stored` write door', ), /** - * [REMOVED in #14691] Gated a route that does not exist: the REST server + * [REMOVED in commit b3a63d32c] Gated a route that does not exist: the REST server * mounts no `GET /meta/:type/:name/schema`, so `false` removed nothing and * `true` added nothing. Its three siblings each gate a real mount. */ @@ -604,7 +604,7 @@ export const BatchEndpointsConfigSchema = lazySchema(() => z.object({ updateMany: z.boolean().default(true).describe('Enable POST /data/:object/updateMany'), deleteMany: z.boolean().default(true).describe('Enable POST /data/:object/deleteMany'), /** - * [REMOVED in #14691] Gated a route that was never built: there is no + * [REMOVED in commit b3a63d32c] Gated a route that was never built: there is no * `POST /data/:object/upsertMany` and no protocol member behind it (the * protocol carries `createManyData` / `updateManyData` / `deleteManyData` * and no upsert counterpart). Upsert is an operation TYPE of the generic @@ -621,7 +621,7 @@ export const BatchEndpointsConfigSchema = lazySchema(() => z.object({ }).optional().describe('Enable/disable specific batch operations'), /** - * [REMOVED in #14691] A server-side default for batch atomicity. No batch + * [REMOVED in commit b3a63d32c] A server-side default for batch atomicity. No batch * handler ever consulted it: atomicity is decided per request by * `options.atomic` in the batch body (`BatchOptionsSchema`, ADR-0119 D4 — * opt-in, default `false`, aligned to what every caller already gets). A @@ -649,8 +649,8 @@ export type BatchEndpointsConfigParsed = z.infer z.object({ /** diff --git a/packages/spec/src/automation/control-flow.zod.ts b/packages/spec/src/automation/control-flow.zod.ts index 38cf36cb5fd..35d0c265d21 100644 --- a/packages/spec/src/automation/control-flow.zod.ts +++ b/packages/spec/src/automation/control-flow.zod.ts @@ -348,7 +348,7 @@ export type TryCatchConfigParsed = z.infer; * try/catch outside any loop binds neither, so their absence means "not in a * loop", never "row unknown". * - * `code` (#14419 / #14954) is the platform-classified error code (ADR-0112) + * `code` (commit c5a7448d5 / #14954) is the platform-classified error code (ADR-0112) * the failing node's own result carried — `create_record`'s `DUPLICATE_RECORD` * is the founding case — bound so a catch region can tell "the row is already * there" from "the store is down" by branching on `$error.code` instead of diff --git a/packages/spec/src/automation/execution.zod.ts b/packages/spec/src/automation/execution.zod.ts index aa8b154b2c6..ded97f9f4f8 100644 --- a/packages/spec/src/automation/execution.zod.ts +++ b/packages/spec/src/automation/execution.zod.ts @@ -91,7 +91,7 @@ export type ExecutionStatus = z.input; * parent answers "what did this run cause", and until this slot existed the * failure count did not: a parent whose child lost a row read `failed: 0`, * which is the misreading the run-level `failed` was added to prevent - * (#13681), one level up. The slot carries a COMPLETED child's + * (commit 18d816a50), one level up. The slot carries a COMPLETED child's * `summary.failed` and folds into the delegating node's `failures` — the same * fold shape `acted` has, so `failed = Σ nodes[].failures` keeps holding with * the child counted in. It is NOT the same rule as `acted` at the failed-child diff --git a/packages/spec/src/automation/index.ts b/packages/spec/src/automation/index.ts index 034230b13d3..24654f33ce8 100644 --- a/packages/spec/src/automation/index.ts +++ b/packages/spec/src/automation/index.ts @@ -43,7 +43,7 @@ export * from './time-relative-trigger.zod'; export * from './flow-trigger-kind'; // The acting-organization declaration a time-triggered flow carries, and the // one refusal sentence the schedule trigger and the time-relative sweep both -// say it with (#16659). ⛔ `FlowSchema` does NOT emit that sentence: the key is +// say it with (commit ecdfc9411). ⛔ `FlowSchema` does NOT emit that sentence: the key is // enforced at BIND, not at parse, because the start node's `config` is an open // record and a parse-time requirement would make every package-shipped // scheduled flow unparseable. Named beside `flow-trigger-kind` because the two diff --git a/packages/spec/src/automation/schedule-organization.zod.ts b/packages/spec/src/automation/schedule-organization.zod.ts index 191a0194571..e3f39e7ce14 100644 --- a/packages/spec/src/automation/schedule-organization.zod.ts +++ b/packages/spec/src/automation/schedule-organization.zod.ts @@ -78,8 +78,8 @@ import { z } from 'zod'; * history row was stamped from the record while the inbox and delivery rows * followed an acting context that could not exist there, so they were refused. * Filling the acting context from the record makes one run carry ONE - * organization's opinion about who it belonged to — which is the defect #16659 - * opened on, read from the other side. + * organization's opinion about who it belonged to — which is the defect commit + * ecdfc9411 fixed, read from the other side. * * ⚠️ With ONE stated exception, so the sentence above is not read as a promise * it cannot keep. The two halves ask different questions and are answered by diff --git a/packages/spec/src/conversions/walk.ts b/packages/spec/src/conversions/walk.ts index 2ef64a2cb16..7370b28b03f 100644 --- a/packages/spec/src/conversions/walk.ts +++ b/packages/spec/src/conversions/walk.ts @@ -517,7 +517,7 @@ const VIEW_CONTAINER_SLOTS = [ * is copied only when a descendant actually changed: {@link mapCollection}'s * contract, one level further in. * - * **Why this is centralized (#13031).** `ViewMetadataSchema` accepts three body + * **Why this is centralized (commit b799ac553).** `ViewMetadataSchema` accepts three body * shapes and all three land in `sys_metadata` rows, but every view-family * conversion was written against the container alone — so for a stored ViewItem * record or a flattened overlay the whole chain was a no-op, while diff --git a/packages/spec/src/data/driver/turso.zod.ts b/packages/spec/src/data/driver/turso.zod.ts index fdfb4a6ff45..5b90891a02d 100644 --- a/packages/spec/src/data/driver/turso.zod.ts +++ b/packages/spec/src/data/driver/turso.zod.ts @@ -33,7 +33,7 @@ import { * then connect unauthenticated, which is precisely the failure #4410 exists to * end, surviving in the one driver #4410 could not see. * - * The maintainer's #6345 ruling closes it by making turso a complete builtin + * The maintainer's ruling (commit e2798fab7) closes it by making turso a complete builtin * rather than a permanent exception. Optionality of the PACKAGE is orthogonal to * existence of the CONTRACT — `mongodb` and `sqlite-wasm` are optional installs * too, and both have had a contract since #4410. @@ -354,7 +354,7 @@ export const TursoConfigSchema = lazySchema(() => strictObject( * The libSQL endpoint or local file. REQUIRED — there is no default: this * is the single fact that makes `hasLocalDefault: false` true for turso, * and the reason both boot hosts refuse a driver selection with no URL - * rather than guessing one (#6345 fork 2). + * rather than guessing one (commit e2798fab7's fork 2). * * Credential-free by contract since #8082: a `user:password@` userinfo is * refused at publish exactly like an inline `authToken` (#7990) — bind the diff --git a/packages/spec/src/identity/identity.zod.ts b/packages/spec/src/identity/identity.zod.ts index d428d6e93fb..2102422926e 100644 --- a/packages/spec/src/identity/identity.zod.ts +++ b/packages/spec/src/identity/identity.zod.ts @@ -228,7 +228,7 @@ export type VerificationToken = z.input; /* * `ApiKey` / `ApiKeySchema` / `ApiKeyParsed` are NOT declared here (#8715, - * maintainer-ruled DELETE 2026-08-15; ADR-0049 enforce-or-remove). + * maintainer-ruled DELETE 2026-08-15, commit 2c86fe3ea; ADR-0049 enforce-or-remove). * * The schema that stood here documented better-auth's `apiKey` PLUGIN shape — * a plugin this platform does not load: `start`, `lastRefetchAt`, `enabled` diff --git a/packages/spec/src/index.ts b/packages/spec/src/index.ts index b0967598058..242ace28a0f 100644 --- a/packages/spec/src/index.ts +++ b/packages/spec/src/index.ts @@ -129,8 +129,8 @@ export { defineAgent } from './ai/agent.zod'; export { defineTool } from './ai/tool.zod'; export { defineSkill } from './ai/skill.zod'; -// [#11350] Root-entry nameability of the root's own inferred types. `defineStack` -// returns `ObjectStackDefinition`, which is declared `z.input` — a generic instantiation the declaration // emitter does not preserve as an alias — so an un-annotated // `export default defineStack(...)` is emitted as the STRUCTURAL expansion, @@ -140,12 +140,12 @@ export { defineSkill } from './ai/skill.zod'; // consumer inferring through a root-entry function). All three are already // public on their domain subpaths (`/ui`, `/automation`); this block makes the // root entry self-consistent. Invariant (maintainer ruling 2026-08-23, -// recorded on #11350): a type that appears structurally in an entry's public +// recorded in commit ece4dad31): a type that appears structurally in an entry's public // declarations must be nameable from that same entry. export type { FormFieldInput } from './ui/view.zod'; export type { NavigationItemInput } from './ui/app.zod'; export type { StateNodeConfig } from './automation/state-machine.zod'; -// [#11709] #11350's recorded premise delta, ruled the same way (maintainer +// [#11709] Commit ece4dad31's recorded premise delta, ruled the same way (maintainer // decision 2026-08-25, recorded on #11709): the MINIMAL one-file consumer — // no `/data` subpath import anywhere in its program — leaks two more // structural mentions of `defineStack`'s return type that the three lines @@ -155,9 +155,9 @@ export type { BaseValidationRuleShape } from './data/validation.zod'; export type { FilterCondition } from './data/filter.zod'; // [#12414] The invariant generalized to every public entry, not just the root: // probing every `define*` factory across all 17 subpaths found the class was -// never closed by #11350/#11709 — four more entries leak a structurally- +// never closed by commit ece4dad31 or #11709 — four more entries leak a structurally- // mentioned type through a factory return value. Same invariant (maintainer -// ruling recorded on #11350), same one-line-per-name repair: re-export from +// ruling recorded in commit ece4dad31), same one-line-per-name repair: re-export from // the declaring module. All three are already public on their own subpaths // (`/system`, `/ui`). export type { Book } from './system/book.zod'; @@ -204,7 +204,7 @@ export type { } from './data/authoring-key-lint'; export { defineCube } from './data/analytics.zod'; export { defineMapping } from './data/mapping.zod'; -// `defineTheme` was removed at #10485 with `ui/theme.zod.ts` (ADR-0049) — see +// `defineTheme` was removed by commit 35ad101bc with `ui/theme.zod.ts` (ADR-0049) — see // the block in `./ui/index.ts`; `app.branding` is the one colour surface. export { defineTranslationBundle } from './system/translation.zod'; export { definePage } from './ui/page.zod'; diff --git a/packages/spec/src/meta-spelling/metadata-url-spelling.ts b/packages/spec/src/meta-spelling/metadata-url-spelling.ts index c81d3893ec1..a8f8e676680 100644 --- a/packages/spec/src/meta-spelling/metadata-url-spelling.ts +++ b/packages/spec/src/meta-spelling/metadata-url-spelling.ts @@ -57,7 +57,7 @@ * These are spellings that already worked at the URL boundary, including * the camelCase ones and the five that name PLUGIN-registered kinds with no * static registry entry at all (`webhooks`, `connectors`, … — `themes` was - * one of them until #10485 retired the carrier, and left this limb WITH + * one of them until commit 35ad101bc retired the carrier, and left this limb WITH * the `PLURAL_TO_SINGULAR` row, which is how a retired kind exits the * spelling contract without this module changing). * Keeping this limb whole is what makes the derivation non-breaking: no @@ -263,7 +263,7 @@ export function metaUrlSpellingRefusal( * registry entry. A refusal quantified over the registry alone would refuse * all five, i.e. break `PUT /meta/webhook/stripe`, which is the exact * operation the plugin path exists to serve. (`theme` was the sixth until - * #10485 retired its carrier; dropping the `PLURAL_TO_SINGULAR` row is what + * commit 35ad101bc retired its carrier; dropping the `PLURAL_TO_SINGULAR` row is what * moved `/meta/theme` from this set to `unrecognisedMetaTypeRefusal`'s * verdict.) * diff --git a/packages/spec/src/security/explain.zod.ts b/packages/spec/src/security/explain.zod.ts index dcb2b4c3879..5d08290b0a0 100644 --- a/packages/spec/src/security/explain.zod.ts +++ b/packages/spec/src/security/explain.zod.ts @@ -208,7 +208,7 @@ export const ExplainLayerSchema = lazySchema(() => z.object({ /** * Grant-lifecycle state — ONE shared "held but not resolving, because X" * vocabulary for every lifecycle control that can silently take a held - * grant out of resolution (#8714). Omitted/`active` = contributing + * grant out of resolution (commit 42b05af89). Omitted/`active` = contributing * normally; the other members mean the row EXISTS but contributed * NOTHING, and name why, so "why did access disappear" is self-answering: * diff --git a/packages/spec/src/security/public-form.ts b/packages/spec/src/security/public-form.ts index 63799d9e610..1750ce23cab 100644 --- a/packages/spec/src/security/public-form.ts +++ b/packages/spec/src/security/public-form.ts @@ -25,7 +25,7 @@ * their existing semantics: a non-system insert has its static-`readonly` * columns stripped inside `engine.insert` (the 2026-09-03 ruling, #14147 — * the same `isSystem`-gated strip as UPDATE), so an import seeds read-only - * columns only under a system context (`preserveAudit` is UPDATE-only, #6640); + * columns only under a system context (`preserveAudit` is UPDATE-only, commit 2ab1257c9); * `owner_id` transfers are governed by the transfer grant. */ export const PUBLIC_FORM_SERVER_MANAGED_FIELDS: ReadonlySet = new Set([ diff --git a/packages/spec/src/shared/identifiers.zod.ts b/packages/spec/src/shared/identifiers.zod.ts index 707a054cbe8..b286ebd5d95 100644 --- a/packages/spec/src/shared/identifiers.zod.ts +++ b/packages/spec/src/shared/identifiers.zod.ts @@ -15,8 +15,8 @@ import { z } from 'zod'; * * **Bound surfaces — this is the whole list.** * An earlier revision of this docblock claimed eleven consuming surfaces. The - * per-surface census on #12245 — its `os-dev-report` comment is the - * measurement of record, taken on `origin/main` @ `e2debee6` — measured + * per-surface census that commit c41b42e8d records — the measurement of record, + * taken on `origin/main` @ `e2debee6` — measured * **exactly one** of those eleven as validated by this schema; the other ten * are validated by something else (next block). What composes this schema is: * @@ -66,10 +66,10 @@ import { z } from 'zod'; * | Labels | Any case | `Client Account`, `Submit Form` | * * The dot this grammar accepts is unexercised on the one live surface: 0 of - * the 1218 authored select option values contain one (#12245). Recorded as the + * the 1218 authored select option values contain one (commit c41b42e8d). Recorded as the * measurement it is — dots are accepted, not a convention to write in. * - * **Length ceiling — storage-owned, deliberately not declared here (#12144).** + * **Length ceiling — storage-owned, deliberately not declared here (commit 3a04b0125).** * The identifier schemas in this file declare a floor and a grammar but no * `.max()`: the enforced ceiling on an identifier is the `maxLength` of the * column that stores it (refused at the write seam by ObjectQL's record @@ -125,7 +125,7 @@ export const SystemIdentifierSchema = lazySchema(() => z * * No `.max()` is declared, deliberately — identifier length ceilings are * storage-owned and the storing columns disagree; see the length-ceiling note - * on {@link SystemIdentifierSchema} and issue #12144. + * on {@link SystemIdentifierSchema} and commit 3a04b0125. */ export const SnakeCaseIdentifierSchema = lazySchema(() => z .string() @@ -137,8 +137,8 @@ export const SnakeCaseIdentifierSchema = lazySchema(() => z .describe('Snake case identifier (lowercase with underscores only)')); /** - * Metadata item-name grammar — the ONE segment source (#12194, stage 1 of the - * #12176 maintainer-ruled retirement of compound `
/` addressing, + * Metadata item-name grammar — the ONE segment source (commit 311433f6b, stage 1 of + * the maintainer-ruled retirement of compound `
/` addressing, * 2026-08-25). * * Both patterns below are built from this segment so the item-name grammar has @@ -186,7 +186,7 @@ export const QUALIFIED_ITEM_NAME_PATTERN = new RegExp( * (`crm_lead`, `crm_lead.pipeline`). * * A slash never belongs in an item name: the compound `
/` - * convention is retired (#12176 — sub-resource identity is spelled with a + * convention is retired (commit 7986d973f — sub-resource identity is spelled with a * dot; containment is expressed by structure, never by a separator inside * the identity string). * diff --git a/packages/spec/src/shared/metadata-collection.zod.ts b/packages/spec/src/shared/metadata-collection.zod.ts index f5f0f9d1314..bcb4ef777eb 100644 --- a/packages/spec/src/shared/metadata-collection.zod.ts +++ b/packages/spec/src/shared/metadata-collection.zod.ts @@ -79,7 +79,7 @@ export const MAP_SUPPORTED_FIELDS = [ 'reports', 'datasets', 'actions', - // `themes` left with the retired carrier key (#10485, ADR-0049). + // `themes` left with the retired carrier key (commit 35ad101bc, ADR-0049). 'flows', 'jobs', 'positions', diff --git a/packages/spec/src/system/core-services.zod.ts b/packages/spec/src/system/core-services.zod.ts index ef16568773b..f3a935872ce 100644 --- a/packages/spec/src/system/core-services.zod.ts +++ b/packages/spec/src/system/core-services.zod.ts @@ -268,7 +268,7 @@ export const ServiceRequirementDef = { * and the two are different concepts (a health value vs this `features`-bearing * object). One name for two declarations across two entry points is the * #4411 trap `check:dual-source-exports` guards, so the kernel side carries the - * `Kernel` prefix its sibling `KernelServiceMapSchema` already uses (#6604, + * `Kernel` prefix its sibling `KernelServiceMapSchema` already uses (commit d127ff002, * maintainer ruling 2026-08-08 Option B). */ export const KernelServiceStatusSchema = lazySchema(() => z.object({ diff --git a/packages/spec/src/system/dev-login.zod.ts b/packages/spec/src/system/dev-login.zod.ts index d6b5d27f8e3..4adf4b18ca1 100644 --- a/packages/spec/src/system/dev-login.zod.ts +++ b/packages/spec/src/system/dev-login.zod.ts @@ -7,7 +7,7 @@ import { strictObject } from '../shared/strict-object'; /** * ONE first-run credential an application contributes to the development boot - * banner (#17556 — suggestion 1 of #17081). + * banner (#17556 — commit 24d622b94, suggestion 1 of its parent card). * * ## Why an app has to be the one to say this * diff --git a/packages/spec/src/system/environment-artifact.zod.ts b/packages/spec/src/system/environment-artifact.zod.ts index a04b1379486..7dc1e59127a 100644 --- a/packages/spec/src/system/environment-artifact.zod.ts +++ b/packages/spec/src/system/environment-artifact.zod.ts @@ -133,8 +133,8 @@ export const EnvironmentArtifactSchema = lazySchema(() => z.object({ /** * Install-time GRANTED permission set, per plugin, keyed by the plugin - * manifest `id` (#14865 — the artifact-contract half of #11333 option A - * and the #13457 batch ruling; ADR-0025 §3.5 step 2). + * manifest `id` (#14865, commit e58ea8b38 — the artifact-contract half of the + * option the #13457 batch ruling chose; ADR-0025 §3.5 step 2). * * - **Producer:** the cloud control plane's consent-compile step. The * install-consent flow persists the consented four-class set diff --git a/packages/spec/src/system/i18n-resolver.ts b/packages/spec/src/system/i18n-resolver.ts index 9399cc27286..2da8893f3a8 100644 --- a/packages/spec/src/system/i18n-resolver.ts +++ b/packages/spec/src/system/i18n-resolver.ts @@ -1577,7 +1577,7 @@ function lookupPageAttr( * or omitting one it reads — so there is one list and both sides import it. * `translation.zod.ts` declares the same five; `translation.test.ts` pins the * two in agreement. (`submitLabel` retired with its only declarer, - * `element:form` — #9249 / #10926.) + * `element:form` — #9249 / commit d173125fb.) */ export const PAGE_COMPONENT_COPY_KEYS = [ 'title', 'description', 'label', 'placeholder', 'emptyText', @@ -1616,7 +1616,7 @@ function lookupPageComponentCopy( } /** - * How many levels of composition nesting — `properties.children` (#12961) and + * How many levels of composition nesting — `properties.children` (commit 901355c3b) and * `properties.items[].children` (#16772), each panel costing one level — * {@link walkAddressedPageComponents} descends below root level. * Authored page trees run three or four deep in practice, so the cap is not a @@ -1628,7 +1628,7 @@ function lookupPageComponentCopy( * the cycle guard catches a subtree that contains itself, the cap catches one * that is merely absurd. Still deliberately NOT exported — the NUMBER is a * safety property, not a contract consumers address; what IS exported is the - * walk that encloses it (#13218), so no consumer needs the number to stay in + * walk that encloses it (commit c45d8e6b4), so no consumer needs the number to stay in * step. The pin lives in `i18n-resolver.test.ts`, which restates this literal * so raising it here reds there; the CLI's deep-chain differential * (`platform-page-i18n-parity.test.ts`) holds both consumers of the walk to @@ -1669,7 +1669,7 @@ export interface AddressedPageComponentContext { depth: number; /** * `true` when this component OWNS its id's `pages..components.` - * entry under the ruled collision arbitration (#12961): a root-level + * entry under the ruled collision arbitration (commit 901355c3b): a root-level * component carrying the id wins outright — even over a nested match seen * earlier in document order — and among nested components the depth-first * document-order FIRST sighting takes it. At most one visited component is @@ -1693,11 +1693,11 @@ export type AddressedPageRoots = Pick; * (this package) and the CLI extractor's `collectExpectedEntries` * (`packages/cli`, behind `os i18n extract` / `os i18n coverage`). * - * Exported for the same reason {@link PAGE_COMPONENT_COPY_KEYS} is (#13218, + * Exported for the same reason {@link PAGE_COMPONENT_COPY_KEYS} is (commit c45d8e6b4, * ruled 2026-08-30, completing that precedent): the WALK used to be * hand-mirrored across the two packages, and a mirrored traversal drifts into * the classic pair of failures — the extractor offering an id the resolver - * ignores, or omitting one it reads (#13109 was the second half going live). + * ignores, or omitting one it reads (the second half went live; commit 8b236c826 fixed it). * Five invariants live here and ONLY here: * * - roots: `regions[].components[]` AND `slots.` — a `kind: 'slotted'` @@ -1746,7 +1746,7 @@ export function walkAddressedPageComponents( ? doc.slots : undefined; - // Collision arbitration, pass 1 (#12961): every id carried by a ROOT-LEVEL + // Collision arbitration, pass 1 (commit 901355c3b): every id carried by a ROOT-LEVEL // component — a region's entry or a slot's. The ruling makes root level the // outright winner when an id repeats across levels, so the whole set has to // be known before the descent visits its first nested component — a @@ -1927,7 +1927,7 @@ export function walkAddressedPageComponents( * therefore id-only. * * Components nested in a container's declared `properties.children` array are - * visited too, recursively (#12961, ruled 2026-08-29). This REVERSES the + * visited too, recursively (commit 901355c3b, ruled 2026-08-29). This REVERSES the * region-only boundary that stood here — "components nested inside another * component's `properties` are untyped free-form props" — which had made the * resolver narrower than the face it serves: `pages..components.` @@ -1939,7 +1939,7 @@ export function walkAddressedPageComponents( * * Two composition slots are descended: `children` — the one composition key * (#5775) — and, since #16772, a `page:tabs` / `page:accordion` panel's - * `items[].children`, which sits one level deeper than the slot the #12961 + * `items[].children`, which sits one level deeper than the slot commit 901355c3b's * ruling named and was left for its own contract call; that call is #16772, * measured on a slotted contract page whose seven tab panels held every * related list and the resolver reached none of them. `body` / `footer` stay @@ -1968,7 +1968,7 @@ export function walkAddressedPageComponents( * * The traversal itself — roots, descent key, depth cap, cycle guard, * collision arbitration — is {@link walkAddressedPageComponents}, the ONE - * walk this resolver and the CLI extractor both consume (#13218); this + * walk this resolver and the CLI extractor both consume (commit c45d8e6b4); this * function owns only what happens AT each component it hands back. * * A list page's filter-preset tab bar @@ -1993,14 +1993,14 @@ export function translatePage( const headerSubtitle = lookupPageAttr(bundle, name, 'subtitle', opts); // The traversal — roots, descent, depth cap, cycle guard, collision - // arbitration — is the shared walk (#13218). This visitor owns only the + // arbitration — is the shared walk (commit c45d8e6b4). This visitor owns only the // per-component overlay; the walk re-attaches each node's translated // `children` after the visitor returns, so the overlay never contends with // the descent for a key (`children` is not a copy key). const { regions, slots } = walkAddressedPageComponents(doc, (component, { nested, id, addressed }) => { // Per-component copy (#6080) — addressed by the component's own id, and // applied before the page-name route below. `addressed` carries the ruled - // collision arbitration (#12961), so a looked-up entry is this component's + // collision arbitration (commit 901355c3b), so a looked-up entry is this component's // alone; within one call `lookupPageComponentCopy` is a pure function of // the id (bundle, page name and options are fixed), so the walk's // claim-on-first-sighting selects the same component a @@ -2514,10 +2514,10 @@ function builtinSystemFieldLabel( * exactly the packaged string — is a no-op: the catalog still applies, and * the tenant sees the packaged translation of the word they typed. * - * ## [#8460] Exported, because the SAME question is asked one layer down + * ## [ADR-0029 D9.2a] Exported, because the SAME question is asked one layer down * * The 2026-08-13 ruling settled catalog-vs-explicit-scalar here. The 2026-08-13 - * ruling on #8460 settled extension-vs-tenant-overlay inside the object FOLD — + * ruling (ADR-0029 D9.2a) settled extension-vs-tenant-overlay inside the object FOLD — * `mergeObjectDefinitions` applies an extender's scalar only while the fold's * base still carries the packaged owner's value — and required it be "the same * comparison-based mechanism, one layer down", explicitly not a second diff --git a/packages/spec/src/system/operation-message.ts b/packages/spec/src/system/operation-message.ts index f12174c56b2..bafc0ae099f 100644 --- a/packages/spec/src/system/operation-message.ts +++ b/packages/spec/src/system/operation-message.ts @@ -10,7 +10,7 @@ * three `403 PERMISSION_DENIED` gates in plugin-security — the object CRUD * grant and the capability AND-gate (#7414, #7451), the row-level pre-image * write denial and the row-level CHECK post-image denial (#7451) — and two - * `403 FORBIDDEN` refusals whose keys land ahead of their emitters (#12493): + * `403 FORBIDDEN` refusals whose keys land ahead of their emitters (commit aa5994e17): * the sharing middleware's by-id write denial (`record_write_denied`; emitter * conversion is #12260's half) and plugin-approvals' non-submitter recall * refusal (`approval_recall_not_submitter`; emitter conversion is #11993's @@ -32,7 +32,7 @@ * | `record_write_denied` | they can see this record, but changing or deleting it is beyond their access | ask its owner, or an administrator | * | `approval_recall_not_submitter` | they asked to recall an approval request someone else submitted | ask the submitter, or an administrator | * - * `record_write_denied` (#12493) is NOT `record_access_denied` restated: the + * `record_write_denied` (commit aa5994e17) is NOT `record_access_denied` restated: the * sharing middleware's by-id write gate fires on a row the READ path already * admitted — the user is typically looking at the record it refuses — so * "You do not have access to this record" would be false the moment it @@ -42,7 +42,7 @@ * which verb was refused is a developer fact that stays on * `developerMessage` and the structured `details`. * - * `approval_recall_not_submitter` (#12493) names who CAN act because that is + * `approval_recall_not_submitter` (commit aa5994e17) names who CAN act because that is * the entire content of the refusal: recall belongs to the request's * submitter (a privileged administrator may also recall to release a stuck * record — the #3424 override), so the sentence sends the user to the @@ -189,7 +189,7 @@ export function operationMessageTranslationKey(messageKey: string): string { * predicate is an authored expression over the whole row). Naming the * object without naming the field would send the user hunting. * - * The two #12493 keys take no placeholders either, re-derived per site: + * The two keys commit aa5994e17 added take no placeholders either, re-derived per site: * * - `record_write_denied` — the sharing gate's nameable facts are the * object's API name and the row's opaque id (the raw string interpolated diff --git a/packages/spec/src/system/translation.zod.ts b/packages/spec/src/system/translation.zod.ts index 5796e2cc0d4..fd69ae8f572 100644 --- a/packages/spec/src/system/translation.zod.ts +++ b/packages/spec/src/system/translation.zod.ts @@ -1038,7 +1038,7 @@ const appTranslationDataShape = () => ({ * | `placeholder` | `element:record_picker`, `element:text_input` | * | `emptyText` | `element:record_picker` | * - * `submitLabel` LEFT this face in @objectstack/spec 17 (#10926, ADR-0049): + * `submitLabel` LEFT this face in @objectstack/spec 17 (commit d173125fb, ADR-0049): * its only declarer, `element:form`, retired whole (#9249), which under * this table's own measured-not-mirrored rule left the key with no * declared component to translate. The maintainer ruled retire over @@ -1069,7 +1069,7 @@ const appTranslationDataShape = () => ({ * declared `content: I18nLabelSchema` (`ui/component.zod.ts`), so it is * localizable at its own authoring site, and adding it to this face would * be the face widening the `submitLabel` retirement declined for the - * identical shape (#10926). The inline locale map is the ruled route for + * identical shape (commit d173125fb). The inline locale map is the ruled route for * page prose, not a workaround. That such maps are invisible to * `os i18n extract` and `check:i18n-coverage` is real, and is its own * question about the extractor (#14749) rather than a second key here. From 166439d57b5e277e1327aee07a1c6f0938c94749 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 05:59:30 +0000 Subject: [PATCH 2/3] docs(spec): regenerate the two reference pages the re-anchored docblocks project into check:generated proved exactly one artifact stale (check:docs, content/docs/references/**) and --fix regenerated it: two pages, three lines, each the same substitution as its source docblock line. Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude --- content/docs/references/automation/schedule-organization.mdx | 4 ++-- content/docs/references/data/driver-turso.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/references/automation/schedule-organization.mdx b/content/docs/references/automation/schedule-organization.mdx index 214f0ee2db2..41872e35eb0 100644 --- a/content/docs/references/automation/schedule-organization.mdx +++ b/content/docs/references/automation/schedule-organization.mdx @@ -81,8 +81,8 @@ evidence line). Before this card the two halves disagreed under `group`: the history row was stamped from the record while the inbox and delivery rows followed an acting context that could not exist there, so they were refused. Filling the acting context from the record makes one run carry ONE -organization's opinion about who it belonged to — which is the defect #16659 -opened on, read from the other side. +organization's opinion about who it belonged to — which is the defect commit +ecdfc9411 fixed, read from the other side. ⚠️ With ONE stated exception, so the sentence above is not read as a promise it cannot keep. The two halves ask different questions and are answered by diff --git a/content/docs/references/data/driver-turso.mdx b/content/docs/references/data/driver-turso.mdx index a6a8c86f9a6..4aef77a466e 100644 --- a/content/docs/references/data/driver-turso.mdx +++ b/content/docs/references/data/driver-turso.mdx @@ -21,7 +21,7 @@ hosts dispatched `turso` for real. So a libSQL datasource could carry then connect unauthenticated, which is precisely the failure #4410 exists to end, surviving in the one driver #4410 could not see. -The maintainer's #6345 ruling closes it by making turso a complete builtin +The maintainer's ruling (commit e2798fab7) closes it by making turso a complete builtin rather than a permanent exception. Optionality of the PACKAGE is orthogonal to existence of the CONTRACT — `mongodb` and `sqlite-wasm` are optional installs too, and both have had a contract since #4410. From 9d63cb65484db46a7657a435938b86222693c87e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 06:00:10 +0000 Subject: [PATCH 3/3] chore(spec): patch changeset for the re-anchored provenance comments 13 of the 21 touched sources are src/**/*.zod.ts, which files[] ships verbatim, and the rewritten docblocks reach dist .d.ts and .js, so the change publishes bytes and takes a patch. Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude --- .changeset/spec-remainder-provenance-anchors.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .changeset/spec-remainder-provenance-anchors.md diff --git a/.changeset/spec-remainder-provenance-anchors.md b/.changeset/spec-remainder-provenance-anchors.md new file mode 100644 index 00000000000..87ff5bef46c --- /dev/null +++ b/.changeset/spec-remainder-provenance-anchors.md @@ -0,0 +1,14 @@ +--- +'@objectstack/spec': patch +--- + +Provenance comments in the rest of `src/` were re-anchored + +The remaining comment and docblock lines in 21 files under `src/` (among +them `api/rest-server.zod.ts`, `system/i18n-resolver.ts`, +`system/operation-message.ts`, `shared/identifiers.zod.ts`, the root +`index.ts` and `data/driver/turso.zod.ts`) cited tracker numbers that no +longer resolve on GitHub. They now cite the commit in this repository's +history that decided the matter, or the ADR amendment that records the +ruling, and say in their own words what was decided. Comments only: no type, +schema, export, message-catalog string or runtime behaviour changes.