Skip to content

Commit d2ca707

Browse files
docs(gates): take the re-typed counts out of the docs and retire the two gates that only held them (#26511)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi95YovdFSHTxz132KjPG4TAa)_ Fixes #26441 Part of #26431 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:文档里五处手抄的数字删掉了,句子改成不写数也成立的说法。lockstep「110 packages」和 quick-reference「(N of M schemas)」各自的门禁连同别名和 lint 步骤一起退役。overlay-whitelist 只删第 3 腿。docs-spec-enumerations 留着,因为它守的三处名单本身就是事实。route-ledger-census 也留着:实测有 3 行删掉后,只有它会红。 - 为什么改:#26441 要求删掉这些手抄数字,或者改成生成的;没有数字的句子不会漂移,只守这个数字的门禁也就可以退了。分诊行 6434325953 要求不削弱检查本身证明的东西,所以下面逐个写了真正的不变量由谁守,并演示了它对原缺陷仍会红。 - 风险与回滚:退掉的两个门禁只读文字,不读代码。真正的不变量(lockstep 成员、白名单完整性、命名空间名单)仍由 `check-changeset-fixed`、overlay 第 1 和第 2 腿、`check-docs-spec-enumerations` 守着。回滚就是 revert。 - 先看:`quick-reference.mdx` 的新导语、`metadata-lifecycle.mdx` 第 123 行、`check-docs-spec-enumerations.mjs` 的 `SECTIONS_HEADING`(数字变成可选),以及下面 route-ledger 的删行实测。 - 两分钟验证:`node scripts/check-overlay-whitelist-table.mjs --self-test`、`node scripts/check-docs-spec-enumerations.mjs --self-test`、`node scripts/check-changeset-fixed.mjs`,都是 exit 0。 - 需要你做的:Tier H(改了 `.github/workflows/lint.yml`),要 GOVERNED_APPROVERS(os-zhuang 或 hotlong)批准。 ## What changes | Holder | What the prose says now | Gate | Who holds the real invariant | |---|---|---|---| | `check-lockstep-package-count` | "one `major` would promote every published package"; "every package published from this repository belongs to a single Changesets `fixed` group"; `publish-smoke-pack.mjs` header: "enumerates the same names" | **retired** (script, `check:lockstep-package-count`, lint step) | `check-changeset-fixed` (membership of the `fixed` group against the public workspace, on PRs from `validate-deps` and in both release lanes) | | `check-quick-reference-counts` | the 13 headings read `## <Name> Protocol`. The intro says each table is curated and points at the generated [reference index](/docs/references) for the full set. The "Categories Without a Section" table loses its `Pages` column | **retired** (script, `check:quick-reference-counts`, lint step) | the page states no count, so #6319 and #6530 have nothing left to drift. What it still states is links: Check Documentation Links (lychee) and `check-doc-anchors` hold those | | `check-overlay-whitelist-table`, leg 3 | "The types in the ✅ row are the **complete** `allowEnvironmentOverlay: true` set: every other type in `DEFAULT_METADATA_TYPE_REGISTRY` is `false`." | **leg 3 removed**: the prose-count reader, `parseCountToken`, `compareProse`, batteries 13a–13g, roster floor 19 → 12. Legs 1–2 untouched | leg 2 (every `true` type has a row) and leg 1 (every row's ✅/❌ matches the registry). Together they make the "complete" sentence true | | `check-docs-spec-enumerations` | the glossary drops "15" from three sentences and the `## The 15 Protocol Namespaces` heading | **kept**. The lists it holds are facts, not counts, and cannot be derived into hand-written prose. The required count floor is gone, and `SECTIONS_HEADING` takes the heading with or without a number. The sweep stays, so a count written back in anywhere is still held to the exports map | itself | | `check-route-ledger-census` | unchanged | **kept**, per the seat's measure-first ruling (below) | itself | **Route-ledger, measured before deciding.** On `c91544a4`, rows were deleted from `ROUTE_LEDGER` (105 rows) and the three suites that read the ledger were run, restoring the file after each run: | Ablation | `runtime` route-ledger.conformance | `client` client-url-conformance | `qa/dogfood` live-mount parity | `check-route-ledger-census` | |---|---|---|---|---| | 26 contiguous rows (`/approvals/act` … `/actions/_activation`) | red (whole domains lost) | — | — | red | | 26 non-last rows, every domain keeps one | **6/6 green** | red (8 SDK URLs) | — | red | | 28 non-sdk non-last rows | **6/6 green** | **3/3 green** | red (26 mounts unledgered, 2 stale pins) | red | | 3 rows: `GET /meta/types`, `POST /actions/global/:action`, `POST /actions/_activation/:object/:action` | **6/6 green** | **3/3 green** | **8/8 green** | **red** | The last row is the #16758 shape: the rows are absorbed by another ledger in the union, or they are `servedBy` specializations whose pattern nothing registers. Nothing but the census sees them go, so it stays. The real fix is a route-granularity reverse check in the runtime suite, which is #17041's open question. It is reported to the seat as an out-of-scope finding, not built here. **Prose made false by the retirement, and only that:** - the `PRIVATE_FIXED_MEMBERS` docblock in `check-changeset-fixed.mjs`, which named the retired reader; - the census header in `check-route-ledger-census.mjs`, which credited its shape to the retired script; - the overlay gate's header line about "all 27 types"; - the spec-enumerations lint comment, which said "16 … and the 15 of those". The real numbers are 18 and 15. Historical mentions of the retired scripts are left as they are: the `docs/audits/*` census tables, the `scripts/ui-import/README.md` cutover log, the #16325 list in `check-docs-spec-enumerations.mjs`'s header, and a quoted principle in `packages/spec/scripts/check-llms-txt.ts`. ## Tests - **Every guardian still reds on the defect, shown on this tree with the change reverted after each run:** - `check-changeset-fixed`: `@objectstack/client` removed from `.changeset/config.json` `fixed[0]` → exit 1, `Public packages missing from "fixed" … @objectstack/client`. - Overlay leg 2: `action` flipped to `allowEnvironmentOverlay: true` in the registry → exit 1, `[missing-row] \`action\` is \`allowEnvironmentOverlay: true\` … and is named nowhere in the table`. - `check-docs-spec-enumerations`: `## The 14 Protocol Namespaces` written back into the glossary → exit 1, `[count-drift] the glossary claims 14 protocol namespace(s); the exports map publishes 15`. - `check-route-ledger-census`: the 3-row ablation above → exit 1, every other suite green. - **Self-tests.** - `check-overlay-whitelist-table --self-test`: the 12 remaining batteries hold, and the positive control still reproduces the 4 known divergences. - `check-docs-spec-enumerations --self-test`: 79 cases over 10 batteries. Two new cases in battery 7: a count-free glossary is green with its sections still read. The drain-refusal case in battery 8 goes, since the floor it tested is gone. - **Card acceptance.** - `grep -rnE "110 (published )?packages|\*\*110\*\*|of [0-9]+ schemas?\)|[0-9]+ types in .DEFAULT_METADATA|Those five are|[0-9]+ protocol namespaces|The [0-9]+ (Protocol )?[Nn]amespaces" content/docs` (outside `releases/`) prints nothing. - `check:lockstep-package-count` and `check:quick-reference-counts` are gone from `package.json` and `lint.yml`. The overlay alias stays, because only its leg went. - `check:doc-anchors` exit 0 (598 fragments). `check:docs-audit-scope` exit 0. - **Gate run, standard order.** - `dispatch-gates --commands` derived 105 commands on `5f82434c`, and all 105 exit 0. `dispatch-gates --ran` reports 0 NOT-MEASURED and 0 UNRUN. - `@objectstack/spec`'s `check:docs` and `check:skill-examples` first refused on an unbuilt `json-schema/` and `dist/` (exit 1 and 3, prerequisites, not findings). Both exit 0 after `pnpm --filter @objectstack/spec build`. - After merging `main` (`fffcf347`) the derivation is the same 105, and the gates that read `package.json` (`check-self-test-wired`, `check:aggregator-roster`, `check:ci-filter-parity`, `check-self-test-workflow-commands`, `check:select-gate-families`) exit 0 again. <details><summary>Gate log (105 commands: exit code, seconds, command)</summary> ``` 0 0s node scripts/check-adr-links.mjs 0 0s node scripts/check-adr-links.mjs --self-test 0 3s node scripts/check-closing-keyword-parity.mjs 0 5s node scripts/check-closing-keyword-parity.mjs --self-test 0 184s node scripts/check-comment-mask-corpus.mjs 0 0s node scripts/check-declaration-mirrors.mjs 0 0s node scripts/check-declaration-mirrors.mjs --self-test 0 0s node scripts/check-doc-route-spelling.mjs --advisory 0 0s node scripts/check-doc-route-spelling.mjs --self-test 0 0s node scripts/check-docs-section-name.mjs 0 0s node scripts/check-docs-section-name.mjs --self-test 0 1s node scripts/check-dts-emitted.mjs --self-test 0 0s node scripts/check-merged-branch-reaper-outcome.mjs 0 0s node scripts/check-merged-branch-reaper-outcome.mjs --self-test 0 0s node scripts/check-osv-exemptions.mjs 0 0s node scripts/check-osv-exemptions.mjs --self-test 0 0s node scripts/check-section-landing-index.mjs 0 0s node scripts/check-section-landing-index.mjs --self-test 0 2s node scripts/check-self-test-wired.mjs 0 5s node scripts/check-self-test-wired.mjs --self-test 0 115s node scripts/check-self-test-workflow-commands.mjs 0 4s node scripts/check-self-test-workflow-commands.mjs --self-test 0 0s node scripts/check-step-collectors.mjs 0 4s node scripts/check-step-collectors.mjs --self-test 0 2s node scripts/check-whole-set-label-write.mjs 0 0s node scripts/check-whole-set-label-write.mjs --self-test 0 1s node scripts/ci/assert-turbo-remote-cache.mjs --self-test 0 0s node scripts/ci/plan-test-core-shards.mjs --self-test 0 0s node scripts/ci/prune-turbo-cache.mjs --self-test 0 0s node scripts/ci/scheduled-full-run.mjs --self-test 0 1s node scripts/docs-audit/check-drift-comment.mjs 0 0s node scripts/osv-base-relative.mjs --self-test 0 28s node scripts/pm/bare-root-worklist.mjs --self-test 0 0s node scripts/pm/ci-failure.mjs --self-test 0 8s pnpm --filter @objectstack/lint run check:doc-formula-expressions 0 3s pnpm --filter @objectstack/lint run check:doc-security-posture 0 2s(rerun after spec build) pnpm --filter @objectstack/spec run check:docs 0 2s pnpm --filter @objectstack/spec run check:empty-state 0 3s pnpm --filter @objectstack/spec run check:liveness 0 4s(rerun after spec build) pnpm --filter @objectstack/spec run check:skill-examples 0 4s pnpm --filter @objectstack/spec run check:strictness-ledger 0 4s pnpm --filter @objectstack/spec run check:variant-docs 0 6s pnpm --filter @objectstack/spec run check:yaml-examples 0 3s pnpm check:agent-test-spelling 0 2s pnpm check:aggregator-roster 0 2s pnpm check:bash32-floor 0 1s pnpm check:changeset-fixed 0 2s pnpm check:ci-filter-parity 0 17s pnpm check:cli-command-ids 0 4s pnpm check:closed-ceremony-text 0 1s pnpm check:corpus-claim-drift 0 35s pnpm check:cross-package-test-inputs 0 39s pnpm check:declared-population-live 0 2s pnpm check:doc-anchors 0 8s pnpm check:doc-authoring 0 1s pnpm check:doc-frontmatter 0 5s pnpm check:docs-audit-scope 0 1s pnpm check:docs-redirects 0 1s pnpm check:docs-single-h1 0 2s pnpm check:docs-spec-enumerations 0 1s pnpm check:docs-transcript-drift 0 5s pnpm check:driver-memory-census 0 1s pnpm check:dts-closure 0 23s pnpm check:dual-build-cjs-loads 0 38s pnpm check:entry-guard 0 2s pnpm check:gitlink-declared 0 2s pnpm check:lean-entry-closure 0 1s pnpm check:manifest-repository-directory 0 23s pnpm check:merge-driver 0 1s pnpm check:node-version 0 5s pnpm check:nul-bytes 0 1s pnpm check:overlay-whitelist-table 0 2s pnpm check:override-consistency 0 3s pnpm check:parse-guard 0 387s pnpm check:pm-dispatch-gates 0 6s pnpm check:pm-expected-skips 0 9s pnpm check:pm-governed-merges 0 1s pnpm check:pm-post-stamped 0 4s pnpm check:pm-record-recognisers 0 1s pnpm check:pnpm-acquisition 0 3s pnpm check:pnpm-filter-targets 0 6s pnpm check:pnpm-flag-spellings 0 0s pnpm check:publish-smoke-pin 0 2s pnpm check:published-readme-links 0 4s pnpm check:ratchet-remedy-authority 0 1s pnpm check:react-page-adapter-contract 0 24s pnpm check:refd-timer-probe 0 4s pnpm check:required-contexts 0 2s pnpm check:role-word 0 1s pnpm check:route-ledger-census 0 7s pnpm check:scripts-symbol-anchors 0 5s pnpm check:select-gate-families 0 3s pnpm check:shard-attestation 0 12s pnpm check:skill-identifier-liveness 0 1s pnpm check:sourcemap-no-sources-content 0 2s pnpm check:stall-guard-budget 0 3s pnpm check:stall-guard-headroom 0 1s pnpm check:turbo-task-graph 0 5s pnpm check:type-check-coverage 0 387s pnpm check:type-check-debt 0 21s pnpm check:vendor-export-contract-resolve 0 11s pnpm check:vendor-version-stamps 0 7s pnpm check:watch-hint-literal 0 1s pnpm check:workflow-status-functions 0 1s pnpm check:workflow-step-name-quoting ``` </details> ## Acceptance notes - Two of the five `check:*` keys stay, both inside the dispatch's own exception. `check-docs-spec-enumerations` holds lists that are facts, and `check-route-ledger-census` holds a number that is the guard itself, as the ablation shows. Both decisions were put to the seat before the work, and the seat ruled the second one measure-first. - Size: +80/−1822, of which 1356 lines are the two deleted scripts. The hand-edited diff is about 550 lines, so it stays one PR rather than a chain. - `ci.yml` is not touched, and no `ui/` path is touched. Docs and repo tooling only, so `skip-changeset`. ## Verification ```sh node scripts/check-overlay-whitelist-table.mjs --self-test && node scripts/check-overlay-whitelist-table.mjs node scripts/check-docs-spec-enumerations.mjs --self-test && node scripts/check-docs-spec-enumerations.mjs node scripts/check-changeset-fixed.mjs --self-test && node scripts/check-changeset-fixed.mjs node scripts/check-route-ledger-census.mjs ``` Tier H (`.github/workflows/lint.yml`): draft until a GOVERNED_APPROVERS approval (os-zhuang, hotlong). --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmQq9EYQdTQwmRutQTS)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01ADHkmQq9EYQdTQwmRutQTS Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3fcafcd commit d2ca707

13 files changed

Lines changed: 80 additions & 1822 deletions

‎.github/workflows/lint.yml‎

Lines changed: 2 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2265,23 +2265,6 @@ jobs:
22652265
continue-on-error: true
22662266
run: pnpm check:i18n-stale-fill
22672267

2268-
# #6319: content/docs/getting-started/quick-reference.mdx is the protocol
2269-
# index, and each "## <Name> Protocol (N schemas)" heading is a DECLARATION
2270-
# about the table under it. The page is hand-written (build-docs.ts writes
2271-
# only content/docs/references/), so the two drift one edit at a time —
2272-
# #6319 found Kernel claiming 17 over a 15-row table because two kernel
2273-
# rows had migrated into the Cloud section and only Cloud's heading was
2274-
# updated. Nothing breaks at runtime; the cost is that content/docs/ is the
2275-
# corpus humans and AIs copy from, so a miscounted index is read as a fact
2276-
# about the schema catalog. Declared = enforced.
2277-
# It lives in this job with the other docs guards: the change that breaks
2278-
# the count is a docs edit, so a packages/** paths filter would blind it to
2279-
# its own failure mode.
2280-
- name: Quick-reference section counts match their tables
2281-
id: quick-reference-section-counts-match
2282-
continue-on-error: true
2283-
run: pnpm check:quick-reference-counts
2284-
22852268
# #17388: three hand-written pages enumerate @objectstack/spec's importable
22862269
# subpaths or its protocol namespaces, and nothing read any of them. When
22872270
# #16325 step 3 deleted the ./cloud exports entry and added ./marketplace,
@@ -2291,8 +2274,8 @@ jobs:
22912274
# kept advertising cloud and never listed marketplace, until a human swept
22922275
# for them. Step 2 of that same chain was FAILed in review by exactly this
22932276
# class of unlisted counter.
2294-
# It holds TWO derived sets, not one: the exports map's 16 bare ./<name>
2295-
# entries, and the 15 of those whose declared CATEGORY_TITLES title ends in
2277+
# It holds TWO derived sets, not one: the exports map's bare ./<name>
2278+
# entries, and those of them whose declared CATEGORY_TITLES title ends in
22962279
# " Protocol" (meta-spelling is a subpath and is titled "Vocabulary", not a
22972280
# protocol). Display names come from that same declaration, so the #5853
22982281
# "Qa Protocol" class of wrong-but-stable spelling is a finding here too.
@@ -2998,22 +2981,6 @@ jobs:
29982981
- name: Setup workspace
29992982
uses: ./.github/actions/setup-workspace
30002983

3001-
# Lockstep package-count guard (#17039). `.changeset/config.json`'s
3002-
# `fixed` array is the one true count of packages one stray `major`
3003-
# promotes; check-changeset-fixed.mjs (release/RC workflows) already
3004-
# gates that array against the real workspace. Nothing gated the THREE
3005-
# prose restatements of the array's length — two sentences in
3006-
# content/docs/protocol/backward-compatibility.mdx and one header
3007-
# comment in scripts/publish-smoke-pack.mjs — so all three drifted
3008-
# silently (69 written, 70 true) the day a package joined the group.
3009-
# Full-repo state, not diff-shaped, so — unlike the changeset-family
3010-
# self-tests (`lint-docs-code`) —
3011-
# this runs its real check every time, unconditionally.
3012-
- name: Lockstep package-count guard
3013-
id: lockstep-package-count-guard
3014-
continue-on-error: true
3015-
run: pnpm check:lockstep-package-count
3016-
30172984
# Route-ledger census guard (#16758). `packages/runtime/src/route-ledger.ts`
30182985
# is census-shaped: its value is the completeness of a list, and nothing in
30192986
# this tree read its row COUNT. An index-slice edit meant to add two rows

‎content/docs/concepts/metadata-lifecycle.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ later ships. See [ADR-0070](https://github.com/objectstack-ai/objectstack/blob/m
120120
| `job` | ❌ | **Also `allowRuntimeCreate: false` since protocol 17** (#4509). `JobSchema.handler` names a function in the compiled bundle's function table, which a runtime writer has no way to reach — so a job created in Studio or through `PUT /meta` parsed, saved, reported success and was never scheduled. The door is closed rather than bridged: `job` stays first-class through `*.job.ts` / `defineStack({ jobs, functions })`, where every schedule shape, `retryPolicy` and `timeout` does reach the scheduler. Existing rows are untouched — they were never scheduled — and `migrateStoredMetadata` reports them `skipped`. |
121121
| `sharing_rule` | ❌ | **Also `allowRuntimeCreate: false` since protocol 18** (ADR-0131 D6, regime C). A sharing rule has two sources: a package declares it (the stack's `sharingRules`, switched off through the activation ledger), or an organization authors its own through `POST /api/v1/sharing/rules`, behind the same-name guard and the organization wall. A runtime `sys_metadata` item was a third source that bypassed both, so `PUT /meta/sharing_rule/:name` now answers `403 NOT_CREATABLE` (`NOT_OVERRIDABLE` over a declared rule) and names the two sanctioned paths: author an organization rule, or clone the declared one and switch it off. Items stored before the change are still served until deleted. |
122122

123-
Those five are the **complete** `allowEnvironmentOverlay: true` set: of the 29 types in `DEFAULT_METADATA_TYPE_REGISTRY`, every other one is `false`. The ❌ rows above are the `false` types whose *second* tier (`allowRuntimeCreate`) is worth calling out; any type not listed is `allowEnvironmentOverlay: false`.
123+
The types in the ✅ row are the **complete** `allowEnvironmentOverlay: true` set: every other type in `DEFAULT_METADATA_TYPE_REGISTRY` is `false`. The ❌ rows above are the `false` types whose *second* tier (`allowRuntimeCreate`) is worth calling out; any type not listed is `allowEnvironmentOverlay: false`.
124124

125125
There is no `workflow` metadata type (per [ADR-0020](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0020-state-machine-converge-and-enforce.md), record state machines are a `state_machine` validation). Nor is there a standalone `validation` type any more — it was retired in protocol 17 under [ADR-0088](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0088-metadata-kind-admission-and-retirement.md) because `ValidationRuleSchema` carries no object-binding key, so a rule authored through that door could never say what it protected; author rules in the object's own `validations[]` instead. The runtime gate is implemented in `OVERLAY_ALLOWED_TYPES` (derived from the registry) and enforced by `SysMetadataRepository.put()`.
126126

‎content/docs/getting-started/glossary.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,16 @@ To navigate the ObjectStack ecosystem effectively, it is helpful to understand t
99
## The Ecosystem
1010

1111
### ObjectStack
12-
The umbrella term for the entire suite of protocols and reference implementations. It is organized into **15 protocol namespaces** grouped into three architectural layers.
12+
The umbrella term for the entire suite of protocols and reference implementations. It is organized into **protocol namespaces** grouped into three architectural layers.
1313

1414
### Protocol Namespace
15-
A logical grouping of related schemas and types defined with Zod. ObjectStack has 15 protocol namespaces: Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Marketplace, QA, Contracts, Integration, Studio, and Shared.
15+
A logical grouping of related schemas and types defined with Zod. ObjectStack has these protocol namespaces: Data, UI, System, Automation, AI, API, Identity, Security, Kernel, Marketplace, QA, Contracts, Integration, Studio, and Shared.
1616

1717
---
1818

1919
## The Three Architectural Layers
2020

21-
The 15 namespaces collapse into three top-level layers:
21+
The namespaces collapse into three top-level layers:
2222

2323
| Layer | Also called | Namespaces it includes | Purpose |
2424
| :--- | :--- | :--- | :--- |
@@ -30,7 +30,7 @@ Older docs and talks used **ObjectOS** as the name of this control layer. That n
3030

3131
---
3232

33-
## The 15 Protocol Namespaces
33+
## The Protocol Namespaces
3434

3535
### Data Protocol
3636
Defines the core business data model. Includes Object schema, Field types, Validation rules, Query AST, and Filter conditions. This is the foundation of ObjectQL.

‎content/docs/getting-started/quick-reference.mdx‎

Lines changed: 23 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,15 @@ Fast lookup for the ObjectStack protocols organized by category.
1111
Click on any protocol name to view its complete API reference.
1212
</Callout>
1313

14-
**Reading the counts.** Every heading below says `(N of M schemas)`. **N** is how many
15-
protocols this table lists; **M** is how many reference pages the matching
16-
`content/docs/references/<category>/` directory publishes. These tables are a *curated*
17-
fast lookup, not a mirror of the reference tree — `N < M` is normal and intended. Both
18-
numbers are checked by `pnpm check:quick-reference-counts`, so a category that gains or
19-
loses a page shows up here instead of drifting unnoticed. A row marked ↗ links outside
20-
its category's reference tree: it is one of the N rows, but it is not one of the M pages.
21-
Categories that have no section here at all are named under
14+
**Reading the tables.** Each table below is a *curated* fast lookup, not a mirror of the
15+
reference tree: it lists the protocols a beginner reaches for first, and a category usually
16+
publishes more reference pages than its table shows. The complete set for every category is on
17+
the [reference index](/docs/references). A row marked ↗ links outside its category's reference
18+
tree. Categories that have no section here at all are named under
2219
[Categories Without a Section](#categories-without-a-section) — that curation is stated,
2320
not left implicit.
2421

25-
## Data Protocol (15 of 31 schemas)
22+
## Data Protocol
2623

2724
Core business logic and data modeling schemas.
2825

@@ -44,7 +41,7 @@ Core business logic and data modeling schemas.
4441
| **[Postgres Driver](/docs/references/data/driver-postgres)** | `driver/postgres.zod.ts` | PostgresConfig | PostgreSQL configuration |
4542
| **[Mongo Driver](/docs/references/data/driver-mongo)** | `driver/mongo.zod.ts` | MongoConfig | MongoDB configuration |
4643

47-
## UI Protocol (10 of 16 schemas)
44+
## UI Protocol
4845

4946
Presentation layer - views, forms, dashboards, and app branding.
5047

@@ -61,7 +58,7 @@ Presentation layer - views, forms, dashboards, and app branding.
6158
| **[Chart](/docs/references/ui/chart)** | `chart.zod.ts` | Chart, ChartType | Chart definitions |
6259
| **[Widget Contract](/docs/protocol/objectui/widget-contract)** ↗ | `widget.zod.ts` | FieldWidgetProps | Props a custom field widget receives — the contract is documented with ObjectUI, outside `references/ui/` |
6360

64-
## Kernel Protocol (17 of 29 schemas)
61+
## Kernel Protocol
6562

6663
Plugin architecture, manifests, and kernel runtime.
6764

@@ -85,7 +82,7 @@ Plugin architecture, manifests, and kernel runtime.
8582
| **[Metadata Loader](/docs/references/kernel/metadata-loader)** | `metadata-loader.zod.ts` | MetadataLoaderContract | Metadata loading |
8683
| **[Package Registry](/docs/references/kernel/package-registry)** | `package-registry.zod.ts` | InstalledPackage, InstallPackageRequest | Package resolution |
8784

88-
## System Protocol (16 of 37 schemas)
85+
## System Protocol
8986

9087
Runtime environment, logging, jobs, caching, and observability.
9188

@@ -108,7 +105,7 @@ Runtime environment, logging, jobs, caching, and observability.
108105
| **[Translation](/docs/references/system/translation)** | `translation.zod.ts` | Translation | i18n support |
109106
| **[Worker](/docs/references/system/worker)** | `worker.zod.ts` | Worker | Background workers |
110107

111-
## AI Protocol (11 of 12 schemas)
108+
## AI Protocol
112109

113110
AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking.
114111

@@ -126,7 +123,7 @@ AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking
126123
| **[Usage](/docs/references/ai/usage)** | `usage.zod.ts` | AIUsageRecord, TokenUsage | AI usage and cost tracking |
127124
| **[Solution Blueprint](/docs/references/ai/solution-blueprint)** | `solution-blueprint.zod.ts` | BlueprintObject, BlueprintApp | Blueprint format for AI app generation |
128125

129-
## API Protocol (17 of 32 schemas)
126+
## API Protocol
130127

131128
REST endpoints, real-time subscriptions, and discovery.
132129

@@ -150,7 +147,7 @@ REST endpoints, real-time subscriptions, and discovery.
150147
| **[Metadata](/docs/references/api/metadata)** | `metadata.zod.ts` | Metadata | API metadata endpoints |
151148
| **[Storage](/docs/references/api/storage)** | `storage.zod.ts` | Storage | API storage operations |
152149

153-
## Automation Protocol (3 of 14 schemas)
150+
## Automation Protocol
154151

155152
Flows, approvals, and integrations. A record's lifecycle transitions are a `state_machine` validation rule on the object (see [State Machine](/docs/protocol/objectql/state-machine)).
156153

@@ -160,7 +157,7 @@ Flows, approvals, and integrations. A record's lifecycle transitions are a `stat
160157
| **[Approval](/docs/references/automation/approval)** | `approval.zod.ts` | ApprovalNodeConfig | Flow approval-node config |
161158
| **[Webhook](/docs/references/automation/webhook)** | `webhook.zod.ts` | Webhook | Outbound webhooks |
162159

163-
## Security Protocol (3 of 5 schemas)
160+
## Security Protocol
164161

165162
Access control, permissions, and row-level security.
166163

@@ -170,7 +167,7 @@ Access control, permissions, and row-level security.
170167
| **[RLS](/docs/references/security/rls)** | `rls.zod.ts` | RowLevelSecurityPolicy | Row-level security filters |
171168
| **[Sharing](/docs/references/security/sharing)** | `sharing.zod.ts` | SharingRule | Record sharing rules |
172169

173-
## Identity Protocol (4 of 5 schemas)
170+
## Identity Protocol
174171

175172
User identity, organizations, and position management.
176173

@@ -181,7 +178,7 @@ User identity, organizations, and position management.
181178
| **[Position](/docs/references/identity/position)** | `position.zod.ts` | Position | Permission-set distribution (岗位, ADR-0090) |
182179
| **[SCIM](/docs/references/identity/scim)** | `scim.zod.ts` | SCIMUser, SCIMGroup | SCIM 2.0 provisioning |
183180

184-
## Marketplace Protocol (2 of 4 schemas)
181+
## Marketplace Protocol
185182

186183
The package & marketplace format — what a package author publishes and what the
187184
marketplace answers with. (The cloud control plane's own contracts — environments,
@@ -194,7 +191,7 @@ cloud repo beside their producer.)
194191
| **[Package](/docs/references/marketplace/package)** | `package.zod.ts` | Package, CreatePackageRequest, PackageTranslations | Package identity and listing text |
195192
| **[Marketplace](/docs/references/marketplace/marketplace)** | `marketplace.zod.ts` | MarketplaceListing, PackageSubmission | Plugin marketplace |
196193

197-
## Integration Protocol (1 of 1 schema)
194+
## Integration Protocol
198195

199196
External system connectors — one protocol (ADR-0097): a connector entry is
200197
either a catalog descriptor or a provider-bound instance that a generic
@@ -207,7 +204,7 @@ from the provider itself, not from hand-written spec files.
207204
|:---------|:-----------|:------------|:--------|
208205
| **[Connector](/docs/references/integration/connector)** | `connector.zod.ts` | Connector | The connector protocol — auth, sync, webhooks, rate limiting |
209206

210-
## Shared Protocol (5 of 10 schemas)
207+
## Shared Protocol
211208

212209
Common utilities used across all protocols.
213210

@@ -219,7 +216,7 @@ Common utilities used across all protocols.
219216
| **[Mapping](/docs/references/shared/mapping)** | `mapping.zod.ts` | FieldMapping | Field mapping utilities |
220217
| **[Connector Auth](/docs/references/integration/connector)** ↗ | `connector-auth.zod.ts` | ConnectorInstanceAuth | Declarative connector auth (ADR-0097). The file sits in `src/shared/` but `@objectstack/spec/shared` does not publish it — it reaches consumers through `@objectstack/spec/integration`, so it is documented on the Connector page |
221218

222-
## QA Protocol (1 of 1 schema)
219+
## QA Protocol
223220

224221
Testing and quality assurance.
225222

@@ -229,14 +226,13 @@ Testing and quality assurance.
229226

230227
## Categories Without a Section
231228

232-
`content/docs/references/` holds one more category directory that deliberately gets no
229+
These category directories under `content/docs/references/` deliberately get no
233230
section above. Curation happens at the category level as well as inside each table, and
234-
this is where it is stated. The same gate reads this table, so a new category directory —
235-
or a page landing in this one — goes red until this page is updated.
231+
this is where it is stated.
236232

237-
| Category directory | Pages | Why it has no section |
238-
|:---|---:|:---|
239-
| [`studio`](/docs/references/studio) | 3 | Designer-facing metadata (`flow-builder`, `object-designer`, `plugin`) — Studio's own authoring surfaces, not protocols an app declares. Reach them from the [reference index](/docs/references). |
233+
| Category directory | Why it has no section |
234+
|:---|:---|
235+
| [`studio`](/docs/references/studio) | Designer-facing metadata (`flow-builder`, `object-designer`, `plugin`) — Studio's own authoring surfaces, not protocols an app declares. Reach them from the [reference index](/docs/references). |
240236

241237
---
242238

‎content/docs/protocol/backward-compatibility.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ Read the **Breaking?** column, not the version number: in the 17.x minors every
116116
1. **RFC (Request for Comments)** — Breaking changes are proposed as GitHub issues with the `protocol:breaking` label.
117117
2. **Deprecation** — The old behavior is deprecated in a MINOR release (see timeline above).
118118
3. **Migration Guide** — A detailed migration guide is published before the removal lands, in the release notes for the version that carries it.
119-
4. **Release** — In the 17.x minors the breaking change shipped in the next **MINOR** version, carrying a changeset entry marked `**BREAKING**`, and `scripts/check-changeset-no-major.mjs` failed a pull request that declared a `major` bump, because under lockstep one `major` would promote all 110 published packages. During the v18 prerelease it shipped in the next `18.0.0-next.N`, because the guard stood aside in pre mode and a pull request could declare a major bump. Changesets has exited pre mode, so the guard fails a `major` bump again. See [how a breaking stage lands on the v18 line](/docs/releases/v18#how-a-breaking-stage-lands-on-this-line).
119+
4. **Release** — In the 17.x minors the breaking change shipped in the next **MINOR** version, carrying a changeset entry marked `**BREAKING**`, and `scripts/check-changeset-no-major.mjs` failed a pull request that declared a `major` bump, because under lockstep one `major` would promote every published package. During the v18 prerelease it shipped in the next `18.0.0-next.N`, because the guard stood aside in pre mode and a pull request could declare a major bump. Changesets has exited pre mode, so the guard fails a `major` bump again. See [how a breaking stage lands on the v18 line](/docs/releases/v18#how-a-breaking-stage-lands-on-this-line).
120120

121121
---
122122

@@ -196,7 +196,7 @@ The `@objectstack/spec` package provides additional stability guarantees:
196196

197197
### Which surfaces this covers
198198

199-
**All of them.** It was not scoped to an experimental corner or a pre-release channel: all **110** packages published from this repository belong to a single Changesets `fixed` group, so they share one version number and one policy. No published surface was exempt.
199+
**All of them.** It was not scoped to an experimental corner or a pre-release channel: every package published from this repository belongs to a single Changesets `fixed` group, so they all share one version number and one policy. No published surface was exempt.
200200

201201
The convention was enforced rather than informal — `scripts/check-changeset-no-major.mjs` failed a pull request that introduced a `major` bump, because under lockstep a single `major` on one package would promote the entire stack. During the v18 prerelease Changesets was in pre mode with the tag `next` and the guard stood aside, so a pull request on the v18 line could declare a major bump. Changesets has exited pre mode, and the guard fails a `major` bump again.
202202

0 commit comments

Comments
 (0)