Repository navigation
docs(types): let package.json own the spec floor, and fold the duplicate Links section - #8608
Merged
os-warren merged 1 commit intoSep 8, 2026
Conversation
…ate Links section (objectui#8037) The architecture diagram named `@objectstack/spec (v15.x)` as the "Highest Law" while `packages/types/package.json` declares `^17.3.0`, so the page told a reader to pin a version this package refuses to install against. The repair does not write `v17.x`: that recreates the identical defect one major later, and the manifest is a moving target by design -- `scripts/check-spec-range-floors.mjs` tightens these floors as symbols land (it is why this one already moved `^17.0.0` -> `^17.3.0` while the card was open). The diagram now names `package.json` as the authority and carries no version of its own, so the next bump cannot silently falsify it. Second repair: the page carried two `## Links` sections separated by `## License`, disagreeing on host -- `https://www.objectui.org/...` against `https://objectui.org/...`. The `www.` form is this package's own stated homepage (`packages/types/package.json` "homepage" is exactly that Documentation URL) and the repo's dominant spelling, so the first section stays and the second is deleted, keeping its one unique entry (the repository root link) as a new bullet. Nothing links to either anchor. Neither item is reachable by a gate: line 32 sits in an unlabelled fenced diagram, which `check-doc-snippet-types.mjs` does not see even though the page has left its `UNGATED_DOCS` ledger, and `check-doc-links.mjs` judges reachability rather than canonicity. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmxdo7bmeqCQHLSfmLVX9w
github-actions
Bot
added
documentation
Contributor
✅ Console Performance Budget
The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it. 📦 Bundle Size Report
Size Limits
|
os-warren
marked this pull request as ready for review
September 8, 2026 16:18
os-warren
deleted the
claude/issue-8037-types-readme-spec-floor-and-links
branch
September 8, 2026 16:35
os-justin
pushed a commit
that referenced
this pull request
Sep 8, 2026
Second sync during the same run: #8601, #8607 and #8608 landed while this branch was being re-verified. None of them touches `packages/types/src/__tests__/zod-mirror-parity.test.ts`, so this merge is clean; #8601 does move a DECLARATION the parity ledger reads (`packages/types/src/record-components.ts`), which is why the branch is re-measured on top of it rather than left behind. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YBWFb5YgMU5dw8p2VKj16S
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #8037
Two repairs in one file,
packages/types/README.md. Triage (comment 5583380673) declined to split them; the whole diff is4 insertions(+), 7 deletions(-).1. The protocol floor now names its authority instead of a number
The "Architecture: The Inheritance Chain" diagram named
@objectstack/spec (v15.x)as the "Highest Law" whilepackages/types/package.jsondeclares"@objectstack/spec": "^17.3.0"— so the page told a reader to pin a version this package refuses to install against.The repair deliberately does not write
v17.x. That recreates the identical defect one major later, and the manifest is a moving target by design:scripts/check-spec-range-floors.mjstightens these floors as symbols land, which is exactly why this range moved from^17.0.0(at filing) to^17.3.0(at triage) while the card sat open. The diagram now namespackage.jsonas the authority and states no version of its own, so the next bump cannot silently falsify it:(The literal arrow glyph is spelled out above only in this PR description; the file itself carries the same arrow character every other row of the diagram uses, and column alignment at char 36 is preserved.)
Re-derived, not taken on trust
main(ce45a03):packages/types/package.jsondependencies->^17.3.0. It has not moved a third time since triage measured it — the PM brief's assumption (a) is falsified, and the range is unchanged from comment 5583380673.@objectstack/spec@17.3.0(the card recorded 17.2.0 at filing).git grep 'Highest Law',grep '^## '), per standing ruling objectui#7853, not by the line numbers in the card. They happen to land on the same:32/:324/:337triage recorded, so assumption (b) is falsified too — but the location method is the content search either way.git grep 'v15.x'finds this spelling in exactly one tracked file, so it was one line and not a population. Widening the sweep to any@objectstack/spec vNNclaim in markdown returns only CHANGELOG / ROADMAP / changeset entries, which are dated historical records rather than current claims. Triage's p2 re-grade trigger therefore does not fire; the grade stays p3.2. One
## Linkssection, on the host this package itself declaresThe page carried two
## Linkssections with## Licensebetween them, disagreeing on host. They are folded into one, in the first position.Which host is canonical was re-derived rather than assumed. The repo states no canonical-host rule anywhere — there is no lychee or site setting for it — so the evidence is:
packages/types/package.json"homepage"https://www.objectui.org/docs/api/schema-reference— this package's own manifest names thewww.form of exactly the Documentation URL the two sections disagreed aboutpackage.json"homepage"https://www.objectui.orghttps://www.objectui.orgagainst 21 withoutwww.So the first section (already
www.) stays and the second is deleted. Its one entry the first section did not already carry — the repository root link — is kept as a new bullet, so the merge loses nothing. Nothing in the tree references either heading anchor (git grep 'types/README.md#'is empty), so deleting the second heading breaks no link.check-doc-links.mjswas green over both spellings because it judges reachability, not canonicity; that is unchanged and not something this PR alters.Verification
Gates derived from the repo's own
package.jsoncheck:*scripts and every.github/workflows/*.ymltrigger block, against the actual changed path. Exit codes captured before any pipe (cmd redirected-to file; EXIT=$?).Which workflows this diff actually reaches.
lint.ymlandci.ymlboth gate their expensive steps on aDecide whether this change needs a full runstep whose diff excludes**/*.md;ci.yml'sdocsjob gates onapps/site/andcontent/only. A README-only PR therefore reports those contexts green having run nothing in them, and the gates that really judge it are the unconditional per-gate workflows.Ran on the final commit
76a9175, all exit 0:check-doc-links,check-doc-fence-languages(+--self-test),check-control-bytes,check-shell-escape-residue,check-changeset-presence,check-action-ref-convention,check-doc-component-types,check-docs-route-eager-closure,check-pre-install-import-graph(+--self-test),check-skill-eval-tokens(+--self-test),check-skills-paths,check-vi-mock-specifiers,check-vi-mock-inherit,check-changeset-fixed,check-doc-expression-carriage, andcheck-governed-queue-guard --test packages/types/README.md(which answersNOT GOVERNED).Declared narrowing — two gates that read package READMEs were not run to a verdict locally, because both need a whole-tree
dist/this container has not built (check-readme-exportswants all 40./packages/*built;check-doc-snippet-typeswants the 34-package closure its--build-filternames). Both are unconditional on this PR, so CI runs them. In their place, three measurements show their input is unchanged rather than assuming it:analyze()fromcheck-doc-snippet-types.mjsreports 244 documents, 240 covered, andpackages/types/README.mdis in the covered set — it has leftUNGATED_DOCS. Its ownscanFences()returns 7 blocks for this file before the edit and 7 after, every onetypescript, at fence lines[58,85,108,219,236,250,271]->[60,87,110,221,238,252,273]. The edited diagram fence is not among them: it carries no language, so the scanner never returns it. That is fence 2 of the triage comment, measured — leaving the ledger did not make line 32 watched.sha256over every language-tagged fenced block of the file:f9f0949bda14ba2e3dbb9067d571d5601da7a3b007d0b69adbf76cc9e02c8128before and after. Block counts 9 total / 8 tagged / 1 untagged, unchanged; the single untagged block contains noimportline.check-readme-exports.mjsrun twice in the same unbuilt state, once with--readmepointing this path at the PRE-EDIT copy (spelled without angle brackets on purpose: GitHub's body sanitizer eats tag-shaped fragments, backticks included), prints a byte-identical census both times —408 fenced block(s) (308 parsed as code, 6 untagged); 751 import binding(s)— and the only difference in the entire run output is the+2line-number shift on the same 19 findings for this file, in the same order, with the same symbols. Both legs share the same pre-existing36 unbuiltprerequisite, which CI's build step satisfies.Also self-scanned for control bytes beyond the gate:
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' packages/types/README.mdreturns nothing (exit 1).Changeset decision: none, deliberately
README.mdis published — it is listed inpackages/types/package.jsonfiles[], so it ships in the tarball. It still owes no changeset, and that is the repo's own rule rather than a judgement call.scripts/check-changeset-presence.mjsis the authority AGENTS.md names, its header subtracts "documentation and licences (*.md,LICENSE*), which do ship in the tarball but are not behaviour", and run against this working tree it prints:Stated plainly so nobody has to re-derive it: this repo does not cut a release for a README-only change, so the corrected page reaches npm with the next release of
@object-ui/typesfor some other reason. Adding an empty-frontmatter changeset would also have breached this dispatch's one-file surface, and empty frontmatter is for declining a release the gate demands — which it does not here.Acceptance notes (out of scope, noted and not filed)
doc-version-claims' scan should reach unlabelled fenced blocks is that gate owner's decision with its own false-positive budget (triage fence 1). Not filed and not ridden in here. Taker: thescripts/__tests__/doc-version-claims.test.tsowner, whenever they next widen that scan.https://objectui.org/...withoutwww.also appears inpackages/app-shell/README.md(1),packages/components/README.md(2),packages/core/README.md(1),packages/react/README.md(2) andapps/console/src/sdui-tiers-preview.tsx(1). Hits inscripts/__tests__/check-doc-links.test.tsandpackages/sdui-parser/src/__tests__/inline-whitespace.test.tsxare deliberate fixtures. This is presentation with every URL resolving, so it is none of the three filing classes; noted rather than filed, and out of this card's one-file surface. Taker: none today.Draft on purpose: not enqueued, no auto-merge, no self-approval.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Jmxdo7bmeqCQHLSfmLVX9w
Generated by Claude Code