docs(runtime): correct the publish-drafts app-read comment the meta read gate falsified

[os-trump]

Fixes #14771

One comment. No behaviour change: git diff origin/main...HEAD is 19 insertions / 3 deletions in a single // block, and the file's token stream is byte-identical across the change (proof below).

What was wrong

packages/runtime/src/domains/packages.ts justified the publish-drafts app-list read with:

// The READ above is left org-aware on purpose — a layered read is a superset,
// never a loss.

That was true when written. It is not true now. getMetaItems resolves the read scope itself:

packages/metadata-protocol/src/protocol.ts:6842
  const orgId = organizationIdForMetaRead(request.type, request.organizationId);

and organizationIdForMetaRead (packages/metadata-core/src/meta-write-org-scope.ts:184) returns undefined for any type the registry declares non-overridable. app is one:

packages/spec/src/kernel/metadata-plugin.zod.ts:846
  { type: 'app', ..., supportsOverlay: true, allowOrgOverride: false, ... }

So the organizationId this route still hands the call is dropped at that gate, and the read is env-wide — not org-aware, and not a superset of anything.

Why the comment was repaired and the code was not

The behaviour is correct. An org-scoped app row is an unhydratable phantom: loadMetaFromDb walks past it and reportUnhydratableOrgScopedRows exists to say so. Reading org-scoped here would resurrect rows that vanish at the next restart, and flip _unpublished on them instead of on the row cold boot actually hydrates — the resurrection #14683 closed, arriving from the read side.

The danger was the justification, not the code: a reader who trusts "left org-aware on purpose" concludes the gate above them is a bug and restores the organization. The replacement states the mechanism, names the registry flag, and says plainly that dropping the organization is the repair.

⛔ Untouched, deliberately: the read itself, the gate, and organizationIdForMetaWrite. My reading of the code found nothing wrong with any of them.

Changeset fork: none, skip-changeset instead

Measured from the package's own manifest rather than assumed:

packages/runtime/package.json → files: ["dist","README.md","CHANGELOG.md"]

@objectstack/runtime publishes, but src/** is not in its tarball, and the edited bytes live inside a // comment in a function body, so they reach neither dist nor the emitted .d.ts. This PR therefore declares no release of its own and carries skip-changeset, which is exactly the label's stated criterion in pr-automation.yml.

Verification

Exit codes captured before any pipe, never through one. Two shas are named because two things were measured at two points, and saying so is cheaper than a claim that will not hold up.

At the final HEAD 686b6c0b21 (git rev-parse --short HEAD, after merging origin/main) — the gate union:

Derived, not recalled: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack gives 27 families (21 by path, 1 by change kind, 5 declared whole-tree). Re-derived after the merge and byte-identical to the pre-merge derivation, and re-run in full there.

• 25 of 27 green (exit 0), including the two comment-parsing families this diff most implicates, check:comment-mask-adoption and check:comment-mask-corpus, plus check:nul-bytes, check:route-envelope, check:doc-authoring, check:type-source-resolution, check:published-files.
• 2 of 27 NOT MEASURED (exit 3, PREREQUISITE NOT MET — neither a pass nor a red):
  • check:dual-build-cjs-loads — "PREREQUISITE NOT MET ... some package has no dist/", naming 8 packages plus "29 more". It needs a whole-workspace pnpm build; CI's Build Core job owns that run, and the gate's own text says "This is NOT a pass: nothing was measured."
  • check-test-completeness.mjs with no argument — structurally unmeasurable locally by the gate's own text ("There is no local log to hand it, so the local reading for this gate is NOT MEASURED").

At b6423975f9 (the same one-file diff, one commit earlier, before origin/main was merged in) — the package scripts, by name, all through bash scripts/pm/os-verify-lock.sh -c ... and read from the wrapper's own VERDICT line:

• pnpm --workspace-concurrency=2 --filter '@objectstack/runtime^...' build → exit 0
• pnpm --filter @objectstack/runtime typecheck → exit 0 (tsc --noEmit, then check:test-typecheck: OK — 27 file(s) / 191 error(s) / 69 pinned signature(s) held)
• pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 over the five src/domains/packages-*.test.ts suites → Test Files 5 passed (5) · Tests 111 passed (111)

Declared narrowing: re-running those three at the merged HEAD is NOT MEASURED. Five attempts on the shared verify lock over roughly 45 minutes produced three queue timeouts (exit 99, "never acquired") and two container foreground-cap kills mid-build (exit 143), against holders that were other seats' @objectstack/cli closure builds and issue-14704 verification scripts. Recorded as NOT MEASURED rather than as a pass, and not as a red either. What backs the narrowing: the merge moved packages/runtime only through PR #15018 on action-execution.ts, a file this diff does not touch, and the token proof below makes it structurally impossible for these bytes to change any build, typecheck or test outcome at any base. CI's Type Check and Test Core jobs run the real thing on this PR.

Token-identity proof. Scanning both revisions of the edited file with the repo's own TypeScript scanner (trivia skipped) gives 1895 tokens on each side and the same sha256 486a535c75603b833018aab0c2916254434e066d1cc6d105f430d4cadaf7b433, with a positive control — the same comparison against the token list minus its last element — correctly reporting a mismatch. So the diff is comment-only at the token level, not merely by inspection.

Bounding the class, without widening the diff

Asked as a side question and answered by measurement, not fixed here. Method: enumerate every non-test metadata read call site in packages/runtime/src/** (a git grep -n -E over getMetaItems|getMetaItem|getMetaItemLayered|listMetaItems|getMetaDiagnostics|findReferencesToMeta with an explicit :(glob)packages/runtime/src/**/*.ts pathspec — 9 sites, and the same pathspec returns more when test files are included, so it is live and not silently matching zero), then read the comment attached to each.

Two comments in that package state the pre-gate rule. One is the sentence this PR repairs. The other:

packages/runtime/src/domains/packages.ts:1245
  // Read the just-published seed body. Try the active org first, then
  // fall back to an env-wide read ...

seed is allowOrgOverride: false (metadata-plugin.zod.ts:808), so both attempts in that ladder now resolve to the identical env-wide read and "try the active org first" describes a scope step that no longer exists. Same class, same file, ⛔ deliberately not touched here — it is a card, not a rider.

Not members, checked and distinguished: the readMergedSkillRows docblock in domains/mcp.ts already states the correct rule for skill; the getMetaItemLayered note at domains/meta.ts:334 describes a primitive the read gate does not reach; and the four domains/meta.ts read sites carry comments about masking and draft preview, asserting nothing about org scope.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 24 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 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from b9659417663ec5813e576689eeb5160dafb8539b — the merge of head 686b6c0b21da755058ed1170d792f26aff36a3e3 into base 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832, 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 b9659417663ec5813e576689eeb5160dafb8539b && git checkout b9659417663ec5813e576689eeb5160dafb8539b
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 686b6c0b21da755058ed1170d792f26aff36a3e3 && git checkout -B drift-repro 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832 && git merge --no-ff 686b6c0b21da755058ed1170d792f26aff36a3e3

node scripts/docs-audit/affected-docs.mjs --json 101ad2cc13fafd8a3879ffc4a6ce6133c02ed832

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