docs(spec,metadata): point the four stale cluster-semantics.mdx citations at the live page by os-bill · Pull Request #17554 · objectstack-ai/objectstack

os-bill · 2026-09-10T22:02:37Z

Four in-source citations named content/docs/concepts/cluster-semantics.mdx, a page that is no longer in the tree. apps/docs/redirects.mjs:98 redirects /docs/concepts/cluster-semantics to /docs/kernel/cluster, so a reader following a link was fine; what was broken is retrieval by filename, which finds nothing.

The two halves get different spellings, on purpose

Site	New citation	Why
`packages/spec/src/kernel/events/core.zod.ts` `.describe()`	`/docs/kernel/cluster` §4	site URL
`packages/spec/src/kernel/service-registry.zod.ts` `.describe()`	`/docs/kernel/cluster` §5	site URL
`packages/metadata/src/metadata-manager.ts` (x2)	`content/docs/kernel/cluster.mdx` §6.2, lane 1	house style

The .describe() half is the one that matters. gen:docs copies those strings into published reference pages, and they also ship as JSON Schema description values and as string literals in the package tarball — so a repo path there would tell a docs-site reader to open a content/docs/... file they do not have. That is the same class of unfollowable reference as #15150, pointed the other way. The site URL is additionally redirect-independent: it is the redirect's target, so the reference survives the redirect being retired.

There is no in-repo precedent for a docs-citing .describe() — these two are the only ones in all of packages/spec/src — so the source-comment convention was deliberately not carried over to them.

The card's §5 is wrong for the two metadata comments — they are §6.2 lane 1

Measured per-site against content/docs/kernel/cluster.mdx, the four sites are not one answer:

## 4. Event scope and delivery semantics   (:96)   <- the two .describe() strings   card correct
## 5. Service scope and leader election    (:216)  <- service-registry.zod.ts        card correct
### 6.2 The cluster-invalidation family    (:325)  <- the two metadata comments      card says 5

Both metadata comments are about metadata.changed / ClusterMetadataChangedPayload / cache invalidation. The §6.2 lane-1 row at cluster.mdx:334 names exactly those three: metadata.changed · ClusterMetadataChangedPayload · @objectstack/metadata · converges MetadataManager's registry/list caches. §5 is service registration and leader election, unrelated.

Corroboration, verified rather than assumed: PR #15139 already corrected a fifth pointer in this same file, at metadata-manager.ts:235, and it cites `content/docs/kernel/cluster.mdx` §6.2, lane 1. Following the card would have contradicted an already-merged correction a few hundred lines above.

Four more sites exist repo-wide and are deliberately untouched

apps/docs/redirects.mjs:98 — the redirect itself. It stays; deleting it is the opposite of this change.
content/docs/references/kernel/events-core.mdx (x2) and service-registry.mdx — gen:docs output, converged by regeneration, never hand-edited.

Regeneration was part of the change: pnpm --filter @objectstack/spec build then check:generated --fix. It rewrote exactly those three rows in those two pages and nothing else. After the change, the only remaining cluster-semantics string repo-wide is the redirect.

Changeset: MEASURED, and one is owed

The claim comment deliberately did not assert this. Measured against the published files[] rosters, with a positive control on every reading:

@objectstack/spec — publishes the change, so a changeset is owed. Its files[] is ["dist","json-schema","liveness","prompts","llms.txt","README.md","src/**/*.zod.ts","CHANGELOG.md","api-surface","spec-changes.json"]. Both edited files match the src/**/*.zod.ts entry and ship verbatim in the tarball. The new string is also present in 4 shipped bundles under packages/spec/dist/ and as a description in 6 files under the shipped packages/spec/json-schema/ tree.
@objectstack/metadata — publishes nothing here, so it is not in the changeset. Its files[] is ["dist","README.md","CHANGELOG.md"]; the comment text has zero hits in packages/metadata/dist/, while two positive controls from the same source file (CLUSTER_CHANNEL, metadata.changed) are lit in 4-6 dist files each. Comments are stripped by the build.

One reading correction worth recording, because it is the reason the controls exist: the first grep of packages/spec/dist/ for the new string returned zero — a false zero. The build emits § as an escaped \xA7, so the literal did not match. The positive control was lit, which is what prompted the re-grep that found it. A zero is not an absence.

Changeset: @objectstack/spec: patch.

Contract review scope

Clause-②: no

Re-derived from what shipped, not inherited. No accept set moves in either direction, no authorable key is added or removed, no closed-set member or published export changes. The diff is two .describe() description strings, two source comments, three regenerated table rows and a changeset. The .describe() strings are published prose, not a published contract — parse behaviour and exported types are byte-identical.

Verification

All at final head bf55c7a9e9.

Gate families derived, not hand-listed. node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, re-derived after the changeset existed (it grew from 96 to 101 commands — the changeset families apply only once the file exists). All 101 run; reconciled with --ran: 101 derived, 101 run, 0 NOT-MEASURED, 0 UNRUN.
98 green. 3 not green, none of them red:
- check:skill-examples exited 1 with packages/client-react/dist holds no .d.ts declarations — the package is not built. That is a gate refusing its own prerequisite, not a verdict. It type-checks spec source TSDoc, which this diff edits, so the prerequisite was built and it was re-run: green, 258 prose examples across 3 surfaces.
- check:dual-build-cjs-loads and check:lean-entry-closure exited 3 with PREREQUISITE NOT MET; both need a whole-repo build (58+ packages with no dist/). NOT MEASURED — neither a pass nor a failure. Left to CI, which builds the tree. This diff moves no entry point or export, so neither gate has a path to move.
check:docs green — the gate this change is measured by: 222 generated files in sync with packages/spec. check:generated, check:docs-redirects, check:nul-bytes, check:published-files also green at final head.
Tests: pnpm --filter @objectstack/spec --filter @objectstack/metadata test — spec Test Files 472 passed (472) / Tests 13368 passed (13368); metadata Test Files 53 passed (53) / Tests 788 passed (788). (The metadata log contains ERROR lines by design — a test drives a loader outage.)
Typecheck: same filter, exit 0, with both script names echoed (packages/spec typecheck$ tsc --noEmit && ..., packages/metadata typecheck$ tsc --noEmit) so this is not a zero-script no-op.
Lint: the whole population, not a narrowing. eslint . --no-inline-config --format json completed in budget at bf55c7a9e9: 6588 files, 0 errors, 0 warnings. The file count is read from eslint's own JSON output, and the population is eslint's own config resolution rather than a hand-built path list, so no narrowing claim is needed here.
No pin was added or adjusted, so there is nothing to ablate.

验收备注

noted, not filed — packages/services/service-cluster/src/cluster.ts:78 throws a runtime error whose text ends See content/docs/kernel/cluster.mdx §6. That is a repo path handed to an application developer consuming the published @objectstack/service-cluster package, who does not have the repo — arguably the same unfollowable-reference class this PR removes from the two .describe() strings. Not filed: it meets none of the three filing classes (it is not a reproducible defect, breaches no declared contract, and is not a trap producing metadata the runtime refuses). It is also outside this card's scope and outside the claim's declared file face. Successor: none known — no in-flight PR or queued card that I can name touches this file.

Generated by Claude Code

…ions at the live page `content/docs/concepts/cluster-semantics.mdx` is no longer in the tree; `apps/docs/redirects.mjs` redirects `/docs/concepts/cluster-semantics` to `/docs/kernel/cluster`. Four in-source citations still named the dead file, so retrieval by filename found nothing even though following a link worked. The two halves get different spellings on purpose: - `packages/spec/src/kernel/events/core.zod.ts` and `service-registry.zod.ts` `.describe()` strings -> the SITE URL `/docs/kernel/cluster` (§4 / §5). `gen:docs` copies these into published reference pages and they also ship in `json-schema/` and `dist/`, so a repo path would send a site reader to a file they do not have. - `packages/metadata/src/metadata-manager.ts` source comments -> house style `` `content/docs/kernel/cluster.mdx` §6.2, lane 1 ``, matching the correction already merged a few hundred lines above in the same file. Both metadata comments are about `metadata.changed` / `ClusterMetadataChangedPayload` / cache invalidation, which is the §6.2 lane-1 row, not §5 (service registration and leader election). `apps/docs/redirects.mjs` is deliberately untouched, and the two reference pages under `content/docs/references/kernel/` are regenerated output (`build` then `check:generated --fix`), not hand edits. Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH Co-authored-by: Claude <noreply@anthropic.com>

github-actions · 2026-09-10T22:03:18Z

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata, @objectstack/spec, touching 4 documentable anchor(s).

4 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

content/docs/concepts/metadata-lifecycle.mdx (via MetadataManager (symbol, a top-level class))
content/docs/kernel/cluster.mdx (via EventMetadataSchema (symbol, a top-level const), MetadataManager (symbol, a top-level class), ServiceMetadataSchema (symbol, a top-level const), notifyWatchers (symbol, a method of class MetadataManager))
content/docs/plugins/adding-a-metadata-type.mdx (via MetadataManager (symbol, a top-level class))
content/docs/protocol/kernel/metadata-service.mdx (via MetadataManager (symbol, a top-level class))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

content/docs/releases/implementation-status.mdx (via MetadataManager (symbol, a top-level class))
content/docs/releases/v17/17-0.mdx (via MetadataManager (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 138 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json ad715aca57b44bbe745a20cf20f339cd5195df14 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 64af6b859c5a5b010ab2c98d1db35f64d40e8d1f — the merge of head bf55c7a9e96283f11de509485dd96205f4308ea8 into base ad715aca57b44bbe745a20cf20f339cd5195df14, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 64af6b859c5a5b010ab2c98d1db35f64d40e8d1f && git checkout 64af6b859c5a5b010ab2c98d1db35f64d40e8d1f
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ad715aca57b44bbe745a20cf20f339cd5195df14 bf55c7a9e96283f11de509485dd96205f4308ea8 && git checkout -B drift-repro ad715aca57b44bbe745a20cf20f339cd5195df14 && git merge --no-ff bf55c7a9e96283f11de509485dd96205f4308ea8

node scripts/docs-audit/affected-docs.mjs --json ad715aca57b44bbe745a20cf20f339cd5195df14

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs ad715aca57b44bbe745a20cf20f339cd5195df14 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

github-actions Bot added the size/s label Sep 10, 2026

github-actions Bot added documentation Improvements or additions to documentation tooling labels Sep 10, 2026

os-bill mentioned this pull request Sep 10, 2026

[finding] The os-dev dispatch template's {decision_frame} slot is optional and unconditioned, so it is omitted exactly on the rounds that return needs_decision — two independent rounds hit it the same day #17520

Closed

os-bill marked this pull request as ready for review September 10, 2026 22:28

os-bill added this pull request to the merge queue Sep 10, 2026

Merged via the queue into main with commit 245f360 Sep 10, 2026
41 of 42 checks passed

os-bill deleted the claude/issue-15141-cluster-doc-pointers branch September 10, 2026 22:56

os-warren mentioned this pull request Sep 16, 2026

finding(spec): zod z.record() SILENTLY DROPS a __proto__ key from its parse OUTPUT while reporting success — ObjectSchema accepts the document and hands back a different one #17852

Open

Navigation Menu

Uh oh!

docs(spec,metadata): point the four stale cluster-semantics.mdx citations at the live page - #17554

docs(spec,metadata): point the four stale cluster-semantics.mdx citations at the live page#17554
os-bill merged 1 commit into
mainfrom
claude/issue-15141-cluster-doc-pointers

os-bill commented Sep 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

os-bill commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The two halves get different spellings, on purpose

The card's §5 is wrong for the two metadata comments — they are §6.2 lane 1

Four more sites exist repo-wide and are deliberately untouched

Changeset: MEASURED, and one is owed

Contract review scope

Verification

验收备注

Uh oh!

github-actions Bot commented Sep 10, 2026

📓 Docs Drift Check

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

os-bill commented Sep 10, 2026 •

edited

Loading