From fcee5ffe358b05faf8b3857c1400d05ec36d0196 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 3 Oct 2026 02:32:08 +0000 Subject: [PATCH 1/2] docs(metadata-core): re-anchor the dead tracker citations to the commits and ADR that decided them Stage 9 of the domain:engine dead-citation lane: 30 comment and docblock sites on 29 lines in 14 files of packages/metadata-core that cited tracker numbers now answering 404 cite an object this repository controls instead (ruling C+D, form C): 10 numbers by commit, #16864 by ADR-0087, and the objectui pair respelled objectui#6110 + objectui#6111. Comments only; every file keeps its line count. Claude-Session: https://claude.ai/code/session_01DDZNkDVwPQnevTFcYE47H3 Co-authored-by: Claude --- .../src/artifact-forward-conversion.test.ts | 2 +- .../metadata-core/src/artifact-forward-conversion.ts | 2 +- packages/metadata-core/src/code-artifact-provenance.ts | 2 +- packages/metadata-core/src/contract-suite.ts | 2 +- .../src/form-predicate-root-policy.test.ts | 8 ++++---- .../metadata-core/src/form-predicate-root-policy.ts | 10 +++++----- packages/metadata-core/src/index.ts | 4 ++-- .../metadata-core/src/meta-write-capability.test.ts | 2 +- packages/metadata-core/src/meta-write-capability.ts | 4 ++-- .../metadata-core/src/meta-write-org-scope.test.ts | 6 +++--- packages/metadata-core/src/meta-write-org-scope.ts | 4 ++-- packages/metadata-core/src/record-organization.ts | 6 +++--- packages/metadata-core/src/repository.ts | 4 ++-- packages/metadata-core/tsup.config.ts | 2 +- 14 files changed, 29 insertions(+), 29 deletions(-) diff --git a/packages/metadata-core/src/artifact-forward-conversion.test.ts b/packages/metadata-core/src/artifact-forward-conversion.test.ts index 5e7e0f0205c..5c27f58f8fd 100644 --- a/packages/metadata-core/src/artifact-forward-conversion.test.ts +++ b/packages/metadata-core/src/artifact-forward-conversion.test.ts @@ -357,7 +357,7 @@ describe('the artifact door never stamps a column constraint (ADR-0113, #16693)' * the defect is WHO writes `_unpublished`). * * The entry is `retiredFromLoadPath: true`, which does NOT hold it back here — - * that flag's jurisdiction is the authoring funnel and nothing else (#16864's + * that flag's jurisdiction is the authoring funnel and nothing else (ADR-0087's recorded * determination, landed). So before this fix an artifact declaring * `engines.protocol: ^17.0.0` — the range `create-objectstack` stamps — had * every `defineApp({ hidden: true })` in it registered as an unpublished app, diff --git a/packages/metadata-core/src/artifact-forward-conversion.ts b/packages/metadata-core/src/artifact-forward-conversion.ts index bd42214b795..9c3a61cae19 100644 --- a/packages/metadata-core/src/artifact-forward-conversion.ts +++ b/packages/metadata-core/src/artifact-forward-conversion.ts @@ -98,7 +98,7 @@ * for `field-required-notnull-explicit`, #16693; measured again for * `app-hidden-to-unpublished`, #17885). Retirement does not hold those back * either: `retiredFromLoadPath`'s jurisdiction is the AUTHORING funnel and - * nothing else (#16864's determination, and the flag's own docblock now says + * nothing else (ADR-0087's recorded determination, and the flag's own docblock now says * so) — which is exactly why the window has to name them here. * * ⇒ {@link DEFAULT_FLIPS_NOT_REPLAYED_HERE} lists them, and the door refuses diff --git a/packages/metadata-core/src/code-artifact-provenance.ts b/packages/metadata-core/src/code-artifact-provenance.ts index 9309ee14b6c..82a5166acfc 100644 --- a/packages/metadata-core/src/code-artifact-provenance.ts +++ b/packages/metadata-core/src/code-artifact-provenance.ts @@ -3,7 +3,7 @@ /** * "Does a code package ship this name?" — the ADR-0029 D9.6 provenance test. * - * [#10062] Sunk here from `@objectstack/objectql`'s registry by the same + * [commit fa5d137ab] Sunk here from `@objectstack/objectql`'s registry by the same * criterion as the write-verb dispatch predicates and the audit governance * table above it in `index.ts`: a second layer needs the answer, and the * reverse import would either close a cycle or make the consumer depend on the diff --git a/packages/metadata-core/src/contract-suite.ts b/packages/metadata-core/src/contract-suite.ts index e4e878b39c7..cc43d4b043b 100644 --- a/packages/metadata-core/src/contract-suite.ts +++ b/packages/metadata-core/src/contract-suite.ts @@ -87,7 +87,7 @@ export interface DeclaredDivergences { * for it is a MAY. That sentence used to be unwritten, and this member's * own doc used to name the no-`since` case as part of the divergence. * - * Value is the tracking issue, e.g. `'#10842'`. **No declaration today:** + * Value is the tracking issue, e.g. the one commit f334d662e closed. **No declaration today:** * `SysMetadataRepository`, the only one there has ever been, was fixed and * deleted its line — the pin below is what told it to. An empty ledger is * the mechanism at rest, not dead code; the shrink-only direction is the diff --git a/packages/metadata-core/src/form-predicate-root-policy.test.ts b/packages/metadata-core/src/form-predicate-root-policy.test.ts index 60dbab60399..ef592f0df9a 100644 --- a/packages/metadata-core/src/form-predicate-root-policy.test.ts +++ b/packages/metadata-core/src/form-predicate-root-policy.test.ts @@ -105,7 +105,7 @@ describe('the bound vocabulary is checked against the LIVE contract, not a copy * metadata forms. No `current_user` at section level — it is unbound * here and the predicate would fault open." * - * #12914 replaced that sentence — objectui#6110 threads the host scope into + * Commit f887e5249 replaced that sentence — objectui#6110 threads the host scope into * `isSectionVisible`, objectui#6111 evaluates the section predicate on the * `section-divider` pseudo-field with that scope bound — and the copy above * went stale HERE in total silence, because no gate reads a comment. It is @@ -146,7 +146,7 @@ describe('the bound vocabulary is checked against the LIVE contract, not a copy // ⚠️ INVERTED IN PLACE. Was "judges the SAME predicate differently per // surface — the whole point of the split", expecting `['current_user']` // from the section vocabulary. The section binds the root since - // objectui#6110 + #6111 (contract landed by #12914), so the section answer + // objectui#6110 + objectui#6111 (contract landed by commit f887e5249), so the section answer // is now `[]` too, and a finding there would be a boot notice about a // predicate that resolves. const source = 'current_user.id == record.owner'; @@ -255,7 +255,7 @@ describe('detectUnboundFormViewPredicateRoots — traversal', () => { it('stays SILENT on a current_user-family predicate on EITHER surface', () => { // Both regressions in one loop. Each of these resolves at FIELD level - // (objectui#6010) and at SECTION level (objectui#6110 + #6111), so + // (objectui#6010) and at SECTION level (objectui#6110 + objectui#6111), so // flagging one is crying wolf on a legitimate, correctly-authored // predicate — the failure the module doc forbids, once per surface. for (const root of CURRENT_USER_FAMILY_ROOTS) { @@ -276,7 +276,7 @@ describe('detectUnboundFormViewPredicateRoots — traversal', () => { it('says NOTHING about the same root at SECTION level either — it binds there now', () => { // ⚠️ INVERTED IN PLACE. This case asserted exactly ONE finding — the // section slot — "where the contract says it is unbound", while the - // identical field predicate stayed silent. #12914 replaced that contract + // identical field predicate stayed silent. Commit f887e5249 replaced that contract // sentence, so the two slots now answer alike and the artifact below is // healthy on both. A finding here would be a boot notice about a predicate // that resolves, which the module doc names as worse than no notice. diff --git a/packages/metadata-core/src/form-predicate-root-policy.ts b/packages/metadata-core/src/form-predicate-root-policy.ts index 596ed4d6cc0..ce90e5aab5f 100644 --- a/packages/metadata-core/src/form-predicate-root-policy.ts +++ b/packages/metadata-core/src/form-predicate-root-policy.ts @@ -11,7 +11,7 @@ * forms, and `data` — the row under edit, at every depth, repeater rows * included — in metadata-editing forms. BOTH predicate surfaces additionally * bind `current_user` and its ADR-0068 aliases — a FIELD since objectui#6010, - * a SECTION since objectui#6110 + #6111. The contract states the failure mode + * a SECTION since objectui#6110 + objectui#6111. The contract states the failure mode * beside the vocabulary (`packages/spec/src/ui/view.zod.ts`, * `FormFieldSchema.visibleWhen` / `FormSectionSchema.visibleWhen`): **a bare * identifier is UNBOUND, the predicate faults, and `visibleWhen`'s fault @@ -111,14 +111,14 @@ * 1. **FIELD.** The first version omitted `current_user`, quoting * `FormFieldSchema.visibleWhen` faithfully — the root genuinely had been * unbound there (#6146). objectui#6010 had already bound it and the prose - * had not caught up; #12930 re-measured the prose, and this module needed a + * had not caught up; commit b5a239815 re-measured the prose, and this module needed a * same-day correction. * 2. **SECTION.** That correction then split the vocabulary and justified the * section half by quoting `FormSectionSchema.visibleWhen` — *"`current_user` * is absent here and that is CORRECT for a section: the section docblock * states it is unbound at that level and the predicate faults open."* - * Faithful again, and stale again: objectui#6110 + #6111 had bound it, and - * #12914 re-measured the prose. This list is that second correction. + * Faithful again, and stale again: objectui#6110 + objectui#6111 had bound it, and + * commit f887e5249 re-measured the prose. This list is that second correction. * * The prose is a transcription of a renderer, so it can only ever LAG one. * Membership here is therefore decided by the mechanism, stated so a reader can @@ -202,7 +202,7 @@ export const BOUND_FORM_VIEW_PREDICATE_ROOTS: readonly string[] = [ * that the QUESTION is still per surface: "what does a FIELD predicate bind?" * and "what does a SECTION predicate bind?" are two questions with one answer * today, and that answer rests on two different renderers (objectui#6010 versus - * objectui#6110 + #6111). Either can move without the other; when one does, + * objectui#6110 + objectui#6111). Either can move without the other; when one does, * this is where the divergence goes, and the live-contract assertion in this * module's test is what makes the day it happens findable. */ diff --git a/packages/metadata-core/src/index.ts b/packages/metadata-core/src/index.ts index 3d8b0bb2090..441cddc7b89 100644 --- a/packages/metadata-core/src/index.ts +++ b/packages/metadata-core/src/index.ts @@ -54,7 +54,7 @@ export * from './engine-findone-predicate.js'; // reporting two. export * from './audit-field-governance.js'; -// [#10062] The ADR-0029 D9.6 provenance pair, sunk here from +// [commit fa5d137ab] The ADR-0029 D9.6 provenance pair, sunk here from // `@objectstack/objectql`'s registry by the same criterion as everything above: // `@objectstack/service-automation` needs the same "does a code package ship // this name?" answer for ADR-0048 flow precedence, and was reaching it by @@ -117,7 +117,7 @@ export * from './meta-write-org-scope.js'; // (through `declaresOrgOverride`) so a second copy is forbidden drift. export * from './meta-write-capability.js'; -// [#8707 / #10101] The shared platform-row organization resolver — sunk here +// [commit 1408fe385 / #10101] The shared platform-row organization resolver — sunk here // from `@objectstack/plugin-audit` per the maintainer ruling recorded on // cloud#1395 ("promoted to a shared resolver used by all three platform-row // writers"). The three sanctioned consumers — audit stamping, the approval-row diff --git a/packages/metadata-core/src/meta-write-capability.test.ts b/packages/metadata-core/src/meta-write-capability.test.ts index bde6fc7149d..9f1e606ee9d 100644 --- a/packages/metadata-core/src/meta-write-capability.test.ts +++ b/packages/metadata-core/src/meta-write-capability.test.ts @@ -121,7 +121,7 @@ describe('#12702 — org-scoped tier-A admission, derived from the registry', () it('the boundary fold composes: a URL-only spelling folded through canonicalMetaUrlType is admitted', () => { // `email_templates` is a URL-only spelling (`SINGULAR_TO_PLURAL` has no - // manifest key for it — the #10340 measurement). The doors fold BEFORE + // manifest key for it — the measurement commit 26f3588fb wrote). The doors fold BEFORE // asking; this case pins that the folded spelling answers tier-A. expect(canonicalMetaUrlType('email_templates')).toBe('email_template'); const out = verdict({ diff --git a/packages/metadata-core/src/meta-write-capability.ts b/packages/metadata-core/src/meta-write-capability.ts index 31ee77eefda..7bc1a4abfab 100644 --- a/packages/metadata-core/src/meta-write-capability.ts +++ b/packages/metadata-core/src/meta-write-capability.ts @@ -113,13 +113,13 @@ export type MetaWriteCapabilityVerdict = * * `canonicalType` MUST be the URL segment folded through * `canonicalMetaUrlType` — the boundary folds, the layers below read the - * canonical singular (`metadata-url-spelling.ts`; the #10340 measurement in + * canonical singular (`metadata-url-spelling.ts`; the measurement commit 26f3588fb wrote in * `meta-write-org-scope.ts` is why this is not optional). * * `activeOrganizationId` MUST be the same value the door threads into * {@link organizationIdForMetaWrite} (REST `ctx.tenantId`, dispatcher * `resolveActiveOrganizationId`) — one resolution feeding authorization AND - * scope, the single-resolution shape the REST doors already carry (#8919). + * scope, the single-resolution shape the REST doors already carry (commit b5378550e). */ export function metaWriteCapabilityVerdict(input: { isSystem?: boolean; diff --git a/packages/metadata-core/src/meta-write-org-scope.test.ts b/packages/metadata-core/src/meta-write-org-scope.test.ts index baf9a2cee3c..4c3bee812f3 100644 --- a/packages/metadata-core/src/meta-write-org-scope.test.ts +++ b/packages/metadata-core/src/meta-write-org-scope.test.ts @@ -1,6 +1,6 @@ // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. // -// #10340 — `declaresOrgOverride` and the boundary fold, pinned as ONE +// Commit 26f3588fb — `declaresOrgOverride` and the boundary fold, pinned as ONE // composed contract. // // The predicate tolerates the MANIFEST-collection spellings only; the URL @@ -19,7 +19,7 @@ // `metadata-url-spelling.ts` forbids ("nothing here should ever be // consulted by a predicate one layer down"). If a future change widens // the predicate, this pin turns red so the widening is argued against -// #10340 / #7894 rather than slipped in as a convenience. +// commit 26f3588fb / #7894 rather than slipped in as a convenience. import { describe, it, expect } from 'vitest'; import { DEFAULT_METADATA_TYPE_REGISTRY } from '@objectstack/spec/kernel'; @@ -38,7 +38,7 @@ const REGISTRY_FLAG = new Map( describe('#10340 org scope composed with the boundary fold', () => { it('fold → predicate answers the registry flag for EVERY spelling in the URL map', () => { - // The contract every REST door relies on after #10340: whatever the + // The contract every REST door relies on after commit 26f3588fb: whatever the // caller spelled, folding first yields the canonical type's own // declaration. Quantified over the whole map so a new spelling limb // arrives already covered. diff --git a/packages/metadata-core/src/meta-write-org-scope.ts b/packages/metadata-core/src/meta-write-org-scope.ts index 8755dc3f63a..3c739d5c5bf 100644 --- a/packages/metadata-core/src/meta-write-org-scope.ts +++ b/packages/metadata-core/src/meta-write-org-scope.ts @@ -74,7 +74,7 @@ import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from '@objectstack/spec/shared * Metadata types whose registry entry declares `allowOrgOverride: true`, * augmented with each one's MANIFEST plural spelling (`SINGULAR_TO_PLURAL`). * - * ⚠️ [#10340] That augmentation is NOT the protocol's URL fold, and the doc + * ⚠️ [commit 26f3588fb] That augmentation is NOT the protocol's URL fold, and the doc * that used to stand here — "judged identically to the singular form — the * same normalization the protocol's own allow-list does" — was measured * false. The protocol folds through `META_URL_TO_SINGULAR`, the COMPLETE @@ -109,7 +109,7 @@ const ORG_OVERRIDABLE_TYPES: ReadonlySet = (() => { * * Expects the CANONICAL singular type. It additionally tolerates the * manifest-collection spellings (`views`, `emailTemplates`, …) — kept for the - * dispatcher-era callers — but ⚠️ [#10340] that tolerance is NOT the URL + * dispatcher-era callers — but ⚠️ [commit 26f3588fb] that tolerance is NOT the URL * fold: URL-only spellings (`translations`, `email_templates`) answer * `false` here. A caller holding a raw `/meta/:type` segment must fold it * through `canonicalMetaUrlType` BEFORE asking, as the REST doors do; see diff --git a/packages/metadata-core/src/record-organization.ts b/packages/metadata-core/src/record-organization.ts index ad1daa4564a..08097c0bc83 100644 --- a/packages/metadata-core/src/record-organization.ts +++ b/packages/metadata-core/src/record-organization.ts @@ -1,7 +1,7 @@ // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. /** - * [#8707 / #10101] The shared platform-row organization resolver — "which + * [commit 1408fe385 / #10101] The shared platform-row organization resolver — "which * column carries THIS object's own organization?", resolved from the object's * REGISTERED schema, never hard-coded to one spelling. * @@ -16,7 +16,7 @@ * * ## The ruling this promotion implements (maintainer, 2026-08-17, cloud#1395) * - * > Ruled: Option A — extend the #8778 ruling: `resolveRecordOrganizationField` + * > Ruled: Option A — extend the [commit 7901b2dd2] ruling: `resolveRecordOrganizationField` * > is promoted to a shared resolver used by all three platform-row writers * > (approvals, automation runs, audit). A platform row's organization is the * > SUBJECT record's organization; actor context is the fallback, never the @@ -174,7 +174,7 @@ export function createFieldPresenceProbe( } /** - * [#8707] "Which column carries THIS object's own organization?" — resolved + * [commit 1408fe385] "Which column carries THIS object's own organization?" — resolved * from the object's REGISTERED schema, never hard-coded to one spelling. * * ## Precedence — deliberately the platform's own, not a second opinion diff --git a/packages/metadata-core/src/repository.ts b/packages/metadata-core/src/repository.ts index df709477cff..1f325a6d8e9 100644 --- a/packages/metadata-core/src/repository.ts +++ b/packages/metadata-core/src/repository.ts @@ -60,7 +60,7 @@ * moment MAY be dropped, on both paths alike. * * **Shutdown MUST NOT be delivered AS an event.** Written as a MUST NOT - * because it was tried, and both of its halves were measured (#11021). A + * because it was tried, and both of its halves were measured (commit 7d81c889f). A * synthetic "we are closing" event is subject to the very filters `watch()` * applies to real ones, so the subscriptions that most need draining are * exactly the ones that drop it: any non-empty `filter` rejects a ref @@ -75,7 +75,7 @@ * Stated conditionally because `close()` is not on the interface below; * it is offered by some implementations and not others. Where it is * offered, this is what it owes. Measured across today's three, and there - * are **no declared exceptions**: `SysMetadataRepository` conforms (#11021); + * are **no declared exceptions**: `SysMetadataRepository` conforms (commit 7d81c889f); * `FileSystemRepository` conforms (#11127 — its `close()` used to retire * the filesystem watcher and the resync sweep without ever reaching its * event broker, leaving a parked iterator parked for every subscription diff --git a/packages/metadata-core/tsup.config.ts b/packages/metadata-core/tsup.config.ts index 2bb2e612c60..23fa6b1bd3a 100644 --- a/packages/metadata-core/tsup.config.ts +++ b/packages/metadata-core/tsup.config.ts @@ -40,7 +40,7 @@ const shared: Options = { // file and resolve the SAME `@objectstack/spec/package.json`. // // Same line, same reason, same measurement as - // `packages/metadata-protocol/tsup.config.ts` (#11235) and + // `packages/metadata-protocol/tsup.config.ts` (commit 376c70f98) and // `packages/runtime/tsup.config.ts` (#10993) — read either for the sibling // history. `pnpm check:dual-build-cjs-loads` holds the class: it // `require()`s every dual-built package's CJS entry point and reds on this From b926d1e35cf85475a076d5e462d48c6c6c26372b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 3 Oct 2026 02:39:56 +0000 Subject: [PATCH 2/2] chore(changeset): metadata-core provenance anchors reach the published declaration files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clause-②: no Claude-Session: https://claude.ai/code/session_01DDZNkDVwPQnevTFcYE47H3 Co-authored-by: Claude --- .../20595-metadata-core-provenance-anchors.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .changeset/20595-metadata-core-provenance-anchors.md diff --git a/.changeset/20595-metadata-core-provenance-anchors.md b/.changeset/20595-metadata-core-provenance-anchors.md new file mode 100644 index 00000000000..f26bf487af1 --- /dev/null +++ b/.changeset/20595-metadata-core-provenance-anchors.md @@ -0,0 +1,20 @@ +--- +'@objectstack/metadata-core': patch +--- + +Provenance comments in `@objectstack/metadata-core` cite the commits that decided them, not tracker numbers that no longer resolve + +Clause-②: no + +Docblocks and comments across the package cited issue-tracker numbers that now answer 404 on GitHub. +Each now cites the commit in this repository's history that made the decision it describes, with two +exceptions: two comments on `retiredFromLoadPath`'s jurisdiction (in `artifact-forward-conversion.ts` +and its test) cite ADR-0087, which records that determination, and five comments that meant an +objectui issue now spell it `objectui#6111`, as they already spelled `objectui#6110` beside it. One +commit citation sits inside a maintainer ruling quoted in `record-organization.ts`: the number there +became the bracketed editorial substitution `[commit 7901b2dd2]`, the commit that landed the ruling it +names, and the rest of the quotation is unchanged. Some of these docblocks sit on exported members, so +the reworded text appears in the published declaration files (`index.d.ts` / `index.d.cts`, +`testing.d.ts` and a shared declaration chunk); the JavaScript output and its sourcemaps do not change. + +Comment only: no export, type, error code, status, message text or runtime behaviour changes.