Skip to content

docs(spec): describe the shared-chunk bundle layout in three source comments - #25975

Merged
objectstack-fleet[bot] merged 3 commits into
mainfrom
claude/project-thread-mybepv
Oct 26, 2026
Merged

docs(spec): describe the shared-chunk bundle layout in three source comments#25975
objectstack-fleet[bot] merged 3 commits into
mainfrom
claude/project-thread-mybepv

Conversation

@objectstack-fleet

@objectstack-fleet objectstack-fleet Bot commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

Fixes #25811

Clause-②: no
Metadata-protocol: none

What changed

Three source comments in @objectstack/spec still described the per-entry, self-contained bundle layout that the one-module-graph build replaced. They now describe the shared-chunk layout stated in packages/spec/README.md (Export surfaces) and the oneModuleGraph docblock in packages/spec/tsup.config.ts: a module two entries reach ships once, in a shared chunk, and an entry links every chunk its own module graph touches.

  • packages/spec/src/index.ts: the standing-principle paragraph no longer says "self-contained bundle"; it keeps the cost rule and dates the +60.1 KB /shared measurement to the former per-entry bundles.
  • packages/spec/src/conversions/registry.ts: only the @__PURE__ note (the sentence that cited splitting: false). The PURE-annotation reasoning is unchanged and still holds per chunk.
  • packages/spec/src/api/package-api-assembled.zod.ts: the module TSDoc.
  • content/docs/references/api/package-api-assembled.mdx: regenerated with the spec package's gen:docs script, never hand-edited; the diff is the same sentence, two lines.

Landing point matches the claimed file surface exactly; the real producer of all four lines was in those files (measured on origin/main, grep for the three stale phrases found them only there).

Not changed

No code, key, export or behaviour. Hunks elsewhere in registry.ts belong to other in-flight cards and were not touched.

Changeset rule

A changeset is included (patch, @objectstack/spec). The os-dev fast lane lists comments as not publishing, but the measured criterion is what files[] ships: after a build, the new sentences are present in packages/spec/dist/index.d.ts and dist/api-assembled/index.d.ts (TSDoc rides in the declaration files), so the published content moved and skip-changeset does not apply.

Verification

  • pnpm --filter @objectstack/spec build exit 0, then gen:docs exit 0: 229 files generated, exactly one tracked file changed.
  • Local gate list from dispatch-gates.mjs --commands (108 families): 105 run, all exit 0. Three are NOT MEASURED, reason: check:dual-build-cjs-loads and check:lean-entry-closure exit 3 (PREREQUISITE NOT MET, they read built dist of packages this card does not touch), check-plugin-teardown-shape --self-test needs an unshallowed clone. CI runs the full farm.

Acceptance notes

The branch is claude/project-thread-mybepv, a platform-assigned branch (this session can push only that one), not the usual issue-named branch.

claude added 3 commits October 26, 2026 07:04
@claude
docs(spec): describe the shared-chunk bundle layout in three source c…
3f4619a 
…omments

index.ts, conversions/registry.ts and api/package-api-assembled.zod.ts still
described the per-entry, self-contained bundle layout that the one-module-graph
build replaced. Comment-only; no code, key or behaviour change. The generated
reference page follows in the next commit.

Claude-Session: https://claude.ai/code/session_01RyMY3prh9GRva1Tt37Di3i
Co-authored-by: Claude <noreply@anthropic.com>
@claude
docs(spec): regenerate the package-api-assembled reference page
2a178d1 
gen:docs output for the reworded module comment; no hand edit.

Claude-Session: https://claude.ai/code/session_01RyMY3prh9GRva1Tt37Di3i
Co-authored-by: Claude <noreply@anthropic.com>
@claude
chore(changeset): patch entry for the shared-chunk comment rewording
1a17dab 
Claude-Session: https://claude.ai/code/session_01RyMY3prh9GRva1Tt37Di3i
Co-authored-by: Claude <noreply@anthropic.com>
@github-actions github-actions Bot added size/s documentation Improvements or additions to documentation tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Oct 26, 2026
@github-actions

github-actions Bot commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

⚠️ 3 changed file(s) yielded no anchor (packages/spec/src/api/package-api-assembled.zod.ts, packages/spec/src/conversions/registry.ts, packages/spec/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see
  • 3 changed file(s) yielded no anchor (packages/spec/src/api/package-api-assembled.zod.ts, packages/spec/src/conversions/registry.ts, packages/spec/src/index.ts) — pages documenting those are invisible to this run
  • 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.
  • a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 144 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 cdd4eea93811522cca145a0f24858def51443671 → packageMentionDocs.

@objectstack-fleet

objectstack-fleet Bot commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 1a17dab74385301324e630336650ddcf888d429f
Local-runs: none
Scope: packages/spec/src/api/package-api-assembled.zod.ts, packages/spec/src/conversions/registry.ts, packages/spec/src/index.ts + packages/spec/tsup.config.ts, packages/spec/README.md, content/docs/references/api/package-api-assembled.mdx, .changeset/25811-spec-shared-chunk-comments.md

Inputs read: card 25811 (body and all four comments: 6399839445, 6409955774, 6410056101, 6410580800); PR 25975 body, file list and the net diff against main (compare main...1a17dab: 3 commits, 5 files, +26/-11, mergeable clean); the 48 check-runs on the head: 41 success, 7 skipped (path-filtered or opt-in), 0 failure. Of the eight required contexts, seven conclude success and Lint UI concludes skipped, which is its path filter on a diff that touches no ui/ path. The rest of the diff (the generated page and the changeset) is the lane seat's ACCEPT at TIER_DEFAULT; both are read here anyway because the three hunks make claims about them.

① Derived judgments

  1. Accept-set: unchanged — right. The three hunks are comment text only: the file-header docblock of index.ts, the TSDoc on the exported CONVERSIONS_BY_MAJOR table in registry.ts, and the module docblock of package-api-assembled.zod.ts. No Zod schema, key, accepted value, export or conversion entry moves; the registry.ts hunk touches none of the MAJOR_18_CONVERSIONS or CONVERSIONS_BY_MAJOR entries around it. check:api-surface, check:authorable-surface (inside the green TypeScript Type Check job) and Spec property liveness are green on the head.
  2. The new sentences are true of the cited code — right. The published JS is jsConfig in packages/spec/tsup.config.ts (splitting: true, esbuildPlugins: [oneModuleGraph, pureSchemaConstruction]), and the oneModuleGraph docblock states the exact mechanism the hunks now cite: esbuild assigns a module to a chunk by file-level reachability, so an entry links every chunk its import graph touches, used or not. packages/spec/README.md (Export surfaces) says the same in the same words. The splitting: false that survives at tsup.config.ts:472 belongs to mainConfig, the DTS pass and the single-entry test config, never the shipped JS, so the registry.ts hunk's new citation (tsup.config.ts, oneModuleGraph) is the right one and the old (splitting: false) was the wrong one.
  3. The PURE-annotation reasoning in registry.ts still holds under the new wording — right. The unchanged consequence sentence (unmarked, the two initializers kept the whole table in every bundle of every entry whose graph reaches this module) is layout-independent: a consumer's bundle links the chunk whether it is shared or inlined, and pure-schema-construction.test.ts still pins the effect on the built ./shared entry.
  4. index.ts now dates the +60.1 KB /shared reading to the former per-entry bundles — right. The tsup docblock records the per-entry layout as the one measured on @objectstack/spec@18.0.0, which is after the @objectstack/spec/shared costs a consumer 60.1 KB gzipped to import one string fold — the /meta spelling contract has no fine-grained export #10096 ruling the reading came from; the standing-principle quotation itself is reproduced unchanged.
  5. Generated page: content/docs/references/api/package-api-assembled.mdx differs by exactly the two regenerated lines of the TSDoc hunk and nothing else — right; check:docs runs inside the green TypeScript Type Check job, and the Docs Drift Check bot note on the PR (no anchor for the three source files) is about its own blind spot, not a drift.
  6. Stale-phrase closure: on origin/main the grep hits for "self-contained bundle", "one flat file" and the comment-level "splitting: false" under packages/spec/src, README.md and tsup.config.ts are exactly the three lines the diff replaces (plus the mainConfig setting in item 2). The two comments the dev noted out of scope (packages/plugins/plugin-auth/tsup.config.ts:29, packages/types/tsup.config.ts:14) describe builds that still set splitting: false (lines 46 and 24 of those files), so they are accurate and not a finding.
  7. Governed surfaces: none of the five paths is a register row and Governed Surface Queue Guard is green. The schema face (packages/spec/src/**) is what sets this review's tier, and this record is that review of record.

② Semver level

.changeset/25811-spec-shared-chunk-comments.md: '@objectstack/spec': patch; its body carries Clause-②: no and Metadata-protocol: none, matching the PR body's two line-initial declarations; no widening or narrowing arm, no BREAKING banner, so no ADR-0087 disposition marker is owed. patch is the right level: Metadata-protocol: none takes patch by the rule, and skip-changeset is reserved for a diff that publishes nothing from a released package. All three rewritten blocks are declaration-bearing doc comments (a file-header docblock, the docblock on an exported const, a module docblock), which the DTS pass carries into the shipped files[]; the dev's post-build grep of dist/index.d.ts and dist/api-assembled/index.d.ts is the measured criterion the os-dev changeset rule names, and it outranks the fast-lane word for comments. Check Changeset is green. Clause-②: no is correct: nothing an author or consumer writes is accepted more or less widely than before.

③ Boundary flags

open_questions: none declared, none found.

Deviations, each answered:

  1. Commit trailers: all three commits end with the model-free pair (Claude-Session: plus Co-authored-by: Claude), which AGENTS.md requires over the dispatch order's model-named trailer — correct, no action.
  2. Branch claude/project-thread-mybepv instead of an issue-named branch: Claim comment 6410056101 names this branch and the platform reason, and the check-runs The card this PR closes must claim this branch and No other open PR may claim the same issue are green — accepted as recorded.
  3. One pnpm install --frozen-lockfile ran in the shared seat checkout: it touched only gitignored node_modules, no file was edited there and nothing of it is in the diff — noted, no action.
  4. No skip-changeset label: correct per ② above.
  5. Three local gate families NOT MEASURED: check:dual-build-cjs-loads and check:lean-entry-closure run in ci.yml under the green Build Core lane, and check-plugin-teardown-shape (self-test and run) runs in lint.yml under the green Lint & Repo Gates, so the head's check-runs answer all three — no gap.

Out-of-scope finding (two tsup comments, carrier none): judged accurate in ① item 6; no card owed.

Implemented-by: claude/project-thread-mybepv
Reviewed-by: session_01RyMY3prh9GRva1Tt37Di3i

VERDICT: PASS

@objectstack-fleet

objectstack-fleet Bot commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

席位核对

ACCEPT · domain:spec seat 2 · 2026-10-26T08:03Z · head 1a17dab74385301324e630336650ddcf888d429f

  1. Shape. Draft, base main, first line Fixes #25811 (the PR closes the whole card). Five files, +26/−11. check-governed-merges --pr 25975: NOT governed.
  2. Premise and stop conditions. The premise held with one corrected line number (comment 6409955774). The landing point equals the claimed surface. The .mdx is regenerated by gen:docs and was not hand-edited; its hunk equals the .zod.ts docblock hunk.
  3. Gates (check-runs pinned to this head). 48 runs: 41 success and 7 skipped. check-expected-skips --pr 25975: OK, every skip is in main's roster.
  4. Contract review. PASS at CONTRACT_REVIEW_TIER on this head, comment 6411128515. It covers the three packages/spec/src/** hunks.
    • Remainder read here at TIER_DEFAULT, sentence by sentence: the changeset (patch, Clause-②: no, Metadata-protocol: none, "What to do: nothing.") and the regenerated content/docs/references/api/package-api-assembled.mdx sentence "because the entry links every chunk its module graph touches".
  5. Accepted deviations.
    • Commit trailers are model-free, as the repo's pre-push check:commit-card-trailers requires.
    • The branch is the seat session's platform branch, as the Claim states.
    • One stray pnpm install touched only the gitignored node_modules of the seat checkout.
    • 3 of 108 local gate families are NOT MEASURED locally; CI ran them green.
  6. Out of scope. The plugin-auth and types tsup comments still set splitting: false, so they are accurate. Nothing to file.
  7. Landing. Ready plus auto-merge.

@objectstack-fleet
objectstack-fleet Bot marked this pull request as ready for review October 26, 2026 08:05
@objectstack-fleet
objectstack-fleet Bot enabled auto-merge October 26, 2026 08:05
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 26, 2026
Closed
@objectstack-fleet
objectstack-fleet Bot added this pull request to the merge queue Oct 26, 2026
Merged via the queue into main with commit f0b33ee Oct 26, 2026
49 checks passed
@objectstack-fleet
objectstack-fleet Bot deleted the claude/project-thread-mybepv branch October 26, 2026 08:35
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 27, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@zhuangjianguo zhuangjianguo

Labels

documentation Improvements or additions to documentation size/s tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

spec: three source comments still describe the per-entry, self-contained bundle layout that #25748 replaced with shared chunks

2 participants

@zhuangjianguo @claude