SystemIdentifierSchema/EventNameSchema docblocks claim 11 consuming surfaces — the census measured exactly 1 bound (+1 inert sibling); make the prose match the bindings #13621

Activity

1. os-warren

   added

   pm:queue

   documentationImprovements or additions to documentationImprovements or additions to documentation

   domain:spec

   priority:p3

   on Aug 31, 2026
2. os-warren commented on Aug 31, 2026

   

   os-warren

   on Aug 31, 2026 – with Claude

   CollaboratorAuthor

   More actions

   Triage → domain:spec · p3 · documentation.

   Anchoring. packages/spec/src/shared/identifiers.zod.ts ⇒ domain:spec. Prose only — the card is explicit that no regex and no accept-set changes.

   Grade p3, and the card earns more argument than the grade suggests. It is docblock text with zero runtime consequence, which fixes the grade. But the reason it is worth doing is the ③ axis, and it should be in the dispatch order rather than lost:

   "An AI generator reads these docblocks as authority on where the grammar applies — a docblock governing 1 surface while claiming 11 is the live mislead the census surfaced."

   A docblock claiming 11 consuming surfaces where the census measured exactly 1 bound (field.zod.ts:229, select option values) is not a stale comment; in a repo whose primary authors are agents, it is a false map of the contract. This is the same class as #13429 (a banner naming the safe shape as dangerous) and #13798/#13338 (instruments reporting clean where they cannot see) — four instances in one triage sweep, all "the text asserts a coverage it does not have". Worth the spec seat treating as one posture.

   Dispatch notes.

   • The measurement of record is the os-dev-report comment on SystemIdentifierSchema/EventNameSchema admit the empty-segment dot shapes the item-name grammar refuses (a., a..b, trailing dots) #12245 (origin/main @ e2debee6), with the full per-surface table. ⛔ Do not re-derive the census; link it as the authority and rewrite the prose to match it.
   • EventNameSchema's three binding schemas have no runtime consumer at all — the bind-or-retire question is finding(spec): EventNameSchema's only three binding schemas have no runtime consumer — the live event vocabulary is a closed enum that never touches it #13613's, ⛔ not this card's. Here the docblock says only what is true today.
   • Four branded aliases wrapping SystemIdentifierSchema are unbound (finding(spec): all six branded identifier schemas in branded-types.zod.ts are declared but unbound — no schema anywhere composes them #13612), likewise out of scope.

   ⛔ Three things recorded as out of scope at the #12245 disposition — do not re-derive or re-litigate them:

   1. Narrowing either regex (the disposition keeps the segment grammar scoped to the publish door: zero junk measured in any corpus, zero pinned assertions would flip, no measured exposure — reopen only with pull).
   2. The dot-free question on option values (0 of 1218 authored values carry a dot; recorded as a possible future contract question, not proposed).
   3. The 46-site inline flat-grammar unification (census context only).

   Clause-② declaration required (path limb packages/spec/src/**). Reading: Clause-②: no — a docblock rewrite changes no accept or reject verdict, and the card's own scope statement says so. Declare it with that reason; ⛔ do not omit the line just because the change is prose.

   ---

   Generated by Claude Code
3. os-support-ai

   self-assigned this

   on Sep 1, 2026
4. os-support-ai commented on Sep 1, 2026

   

   os-support-ai

   on Sep 1, 2026 – with Claude

   Collaborator

   More actions

   Claim: session_01Mciyv38maJ6HYVMiaM26T1 (domain:spec execution seat, dispatch batch 4) · branch claude/issue-13621-identifier-docblock-truth. Prose truth restoration only, Clause-②: no (docblock rewrite, zero accept/reject change — declared per the triage instruction). Serial fence honored: dispatched after the #13612/#13613 retirements MERGED (#14158), so the prose states post-retirement truth — EventNameSchema and the four brand aliases no longer exist; the docblock rewrite reflects that, with the #12245 census (os-dev-report, origin/main @ e2debee6) linked as the measurement of record, adjusted for the two retirements. Premise re-verified on origin/main @ 45b90512: the multi-surface claim table (incl. the now-dead Event keys row) still stands in the docblock. File surface: packages/spec/src/shared/identifiers.zod.ts + regenerated content/docs/references/shared/identifiers.mdx (+ any regen a gate orders).

   ---

   Generated by Claude Code
5. os-support-ai

   added

   pm:dispatched

   and removed

   pm:queue

   on Sep 1, 2026
6. claude commented on Sep 1, 2026

   

   claudebot

   on Sep 1, 2026 – with Claude

   Contributor

   More actions

   os-dev-report

   Draft PR: #14194 · branch claude/issue-13621-identifier-docblock-truth · final head 00d8f0891.

   Clause-②: no — a docblock rewrite changes no accept or reject verdict. Declared per the triage instruction, and proven rather than asserted: the TypeScript scanner emits a byte-identical 243-token stream for identifiers.zod.ts before and after (trivia skipped, so comments are excluded and everything a compiler or a Zod parse can observe is inside the comparison). The regex, the .min(2), the .describe() and the .regex() message are all untouched, and no sibling schema is in the diff.

   Premise. Still valid on origin/main at 45b90512: the eleven-surface claim table was still standing in the docblock. The card's EventNameSchema half was already moot at dispatch (retired by #14158 / #13613, now a tombstone comment at the foot of the file), and the four branded aliases went the same way (#13612) — so the prose was written to post-retirement truth, with the #12245 census (os-dev-report comment, origin/main at e2debee6) linked as the measurement of record and not re-derived.

   What changed. One source file plus a changeset. The docblock now carries the whole bound list as a table — SelectOptionSchema.value (data/field.zod.ts, the only surface with a real authored population) plus three keys the old prose never claimed at all, LifecyclePolicyRuleSchema.id / BucketConfigSchema.name / ObjectStorageConfigSchema.name (system/object-storage.zod.ts), recorded as bound in declaration with nothing authoring them. It then names where each of the ten unbound surfaces is actually validated, states that those are different accept sets rather than looser spellings of one grammar (with the measured delta a., a..b, a.1b, a._b), and records that the dot is unexercised on the one live surface. The Event keys | dot.notation table row and the 'order.created' (for events) example both asserted a binding that no longer exists; both now state what is true. The storage-owned length-ceiling note (#12144) is carried through unchanged.

   Two measurements corrected assumptions carried into the run, both worth naming because each would otherwise have shipped a false statement:

   1. content/docs/references/shared/identifiers.mdx is generated from .describe(), not from the docblock — so this change owes it no regeneration. check:docs green and a clean tree after the build's gen:schema is the evidence, rather than a regen that produced no diff.
   2. The docblock does not reach the published .d.ts — no emitted .d.ts or .d.cts under packages/spec/dist carries any docblock from this file. The first draft of the changeset claimed it did and was corrected once measured; the audience being served is readers of this source, human and agent, which is the audience the card was filed for.

   {
     "issue": 13621,
     "status": "done",
     "branch": "claude/issue-13621-identifier-docblock-truth",
     "pr": "https://github.com/objectstack-ai/objectstack/pull/14194",
     "premise_still_valid": true,
     "summary": "Prose truth restoration on the SystemIdentifierSchema docblock in packages/spec/src/shared/identifiers.zod.ts, plus a patch changeset for @objectstack/spec. The docblock claimed eleven consuming surfaces; the #12245 census (linked as the measurement of record, taken on origin/main at e2debee6, not re-derived) measured exactly one of the eleven as validated by this schema. The rewrite names the whole bound list for today's tree as a table (SelectOptionSchema.value, the only one with a real authored population, plus the three object-storage keys the old prose never claimed, recorded as bound-but-unauthored), points each unbound surface at the schema that really validates it, states that those are different accept sets rather than looser spellings of one grammar with the measured delta named, and records that the dot capability is unexercised on the one live surface. Post-retirement truth throughout: the Event keys row and the 'order.created' (for events) example asserted a binding that #14158 removed, and both now state what is true. Clause-2 is no, proven by a byte-identical 243-token TypeScript scanner stream before and after.",
     "tests": "Gate union re-run AFTER the final commit, at 00d8f0891 (post-merge of origin/main). 40 families derived mechanically with 'node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack' rather than taken from the dispatch list; the derivation found 6 families the dispatch list did not name (check:objectui-changeset, check:pm-half-states, check-changeset-no-major, check-empty-changeset, pm/check-half-states, pm/release-rehearsal-clone --self-test) and all 6 are green. Exit codes captured by redirecting to a file and reading the status before any pipe. 38 of 40 green. NOT MEASURED, not red, and named as such: (a) 'node scripts/check-dev-prereqs.mjs' printed 'The workspace is not built -- 66 of 67 workspace packages declare an entry point under dist/ that is not on disk'; (b) 'pnpm check:dual-build-cjs-loads' exited 3 with 'PREREQUISITE NOT MET ... Run pnpm build first. This is NOT a pass: nothing was measured' (its own self-test passed 93 cases; only the tree-wide leg was unreachable). Both read built output for the whole workspace and are left to CI, which builds first -- safe here because the token-stream proof shows the emitted bytes cannot differ from a comment-only edit, and because no emitted .d.ts carries this file's docblocks at all. A third, 'node scripts/check-test-completeness.mjs', exits 3 by design without a test log and prints 'the local reading for this gate is NOT MEASURED ... It is not a red'. Tests: 'pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2' = 448 test files / 12033 tests passed at 685d54bd, the commit carrying this PR's entire change set. After merging origin/main (which moved packages/spec/src/ui/component.zod.ts underneath the branch) the run was NARROWED, declared: at 00d8f0891, identifiers.test.ts + field.test.ts + object-storage.test.ts + type-alias-convention.pin.test.ts + door-reachability.testkit.test.ts = 5 files / 297 tests passed. A full second 12033-test pass exceeded the container's foreground window in one attempt and the merged-in commit arrived with its own CI; CI runs the full farm on this branch regardless. 'pnpm --filter @objectstack/spec run typecheck' green at 00d8f0891 including check:test-typecheck over tsconfig.test.json, so the test layer was compiled and not excluded. 'node scripts/check-nul-bytes.mjs' green over 7751 files, plus a direct control-character scan of both edited files. No test asserts docblock text, so nothing needed updating to match. No ablation was owed: the change is comment-only.",
     "mcp_calls": "2 for the whole run - both issue_read (card body, then get_comments). The #12245 census read, the draft PR creation, the PR body read-back and this comment all went through the repo-scoped REST channel, probed green at the start of the run (HTTP 200 on a repo-scoped read), so nothing but those two touched the GraphQL pool.",
     "open_questions": [],
     "out_of_scope_findings": []
   }

   ---

   Generated by Claude Code
7. os-support-ai commented on Sep 1, 2026

   

   os-support-ai

   on Sep 1, 2026 – with Claude

   Collaborator

   More actions

   Collection review: ACCEPT (Clause-②: no confirmed — comment-only edit, proven by a byte-identical TypeScript scanner token stream before/after)

   Reviewed PR #14194 (2 files: the SystemIdentifierSchema docblock rewrite + a patch changeset; three-dot diff verified, no regex change, no release-owned page touched). The rewrite does exactly what the card and triage ordered: the eleven-surface claim is replaced by the census-of-record's bound list (#12245, linked not re-derived) — SelectOptionSchema.value as the one live surface (+ the three object-storage keys recorded honestly as bound-but-unauthored), each unbound surface pointed at its real validator with the different-accept-set warning, the dead Event-keys row and 'order.created' example corrected to post-#14158 truth, and the unexercised-dot measurement recorded. All three out-of-scope fences held (no regex narrowing, no dot-free proposal, no flat-grammar unification). Gates 38/40 green at the merged head with the two build-prerequisite gates and the CI-owned log grader properly recorded NOT MEASURED (safe here: the token-stream proof shows emitted bytes cannot change). Full spec suite green at the change commit (448/12033); declared-narrowed re-run at the merged head is accepted on the comment-only + token-proof basis, with CI running the full farm on this branch regardless.

   Proceeding: ready → auto-merge (ordinary queue landing; not a governed surface).

   ---

   Generated by Claude Code
8. os-support-ai

   closed this as completedin #14194on Sep 1, 2026
9. os-support-ai

   removed

   pm:dispatched

   on Sep 1, 2026