docs(kernel): move plugin manifest dependency examples off ^2.0.0 and record what the kernel actually reads - #18415

Part of #18188 — the PM decides closure.

1. The load-bearing reading: does the kernel resolve a manifest dependencies entry at plugin load?

No. The kernel never parses the version range. Measured two ways, call site first (read-only, as the card's acceptance prefers), then executed.

1a. Call sites — every consumer of manifest.dependencies in this repo

ManifestSchema.dependencies (packages/spec/src/kernel/manifest.zod.ts:439) is z.record(z.string(), z.string()) — a map of package id to version range, where the value is typed only as "some string".

It has two consumers outside tests, and both read Object.keys(...) only:

Neither ever reads a value. artifact-packages.ts says so in its own header (lines 105–124): "Why declared dependencies enter as optionalDependencies" — an id that names a package inside the artifact is a real edge, one that does not is simply not an edge here, "hoisted ahead when composed, silently skipped when absent".

The machinery the page's Version Constraints section describes — SemanticVersionManager.satisfies() and DependencyResolver.detectConflicts() in packages/core/src/dependency-resolver.ts — has no production call site at all:

SUBJECT       grep -rn 'dependency-resolver\.js' --include=*.ts packages/ apps/
              -> packages/core/src/index.ts:126          (barrel re-export)
              -> packages/core/src/dependency-resolver.test.ts:2   (its own unit test)
              = 0 production importers

FIRING CTRL   grep -rn 'plugin-order\.js'      (same directory, same barrel, same export form)
              -> index.ts:12, kernel-base.ts:11, artifact-packages.ts:132, kernel.ts:15, plugin-registration.ts:41
              = 4 production importers  -> the instrument fires

DARK CTRL     grep -rn 'dependency-resolver-NOSUCH\.js'
              = 0                                        -> the instrument is not just printing hits

The kernel's own load-order surface is a different field: OrderablePlugin.dependencies (packages/core/src/plugin-order.ts:50) is string[] — plugin names, no version ranges in it at all.

1b. Executed, with a firing control on the value and one on the key

Ran against the built @objectstack/core (packages/core/dist/index.js), calling resolveArtifactPackageOrder directly:

S1  caret ^2.0.0  on @objectstack/core            -> OK   [com.acme.a]
S2  caret ^17.0.0 on @objectstack/core            -> OK   [com.acme.a]
C-VALUE  'NOT-A-VERSION-RANGE-@@@' on the same key -> OK   [com.acme.a]
C-KEY    the SAME garbage value, but the key names
         a sibling package IN the artifact         -> OK   [com.acme.b, com.acme.a]   (declared order was a, b)
C-DARK   no `dependencies` at all                  -> OK   [com.acme.a, com.acme.b]   (declared order preserved)

• C-VALUE is the firing control on the value: a string that is not a version range in any grammar resolves exactly like ^2.0.0 does. Nothing parses the value.
• C-KEY is the firing control on the key, and it discriminates: the same unparseable value on a key that is in the artifact flips the order from the declared [a, b] to [b, a]. So the probe can observe dependencies having an effect — it has one, through its keys, and none through its values.
• C-DARK confirms the flip in C-KEY came from the dependency edge and not from something else in the call.

Also already pinned in the existing suite: packages/objectql/src/artifact-load-path.test.ts:235 — "leaves a dependency on a package OUTSIDE the artifact to the installer" — which declares '@steedos/plugin-auth': '^2.0.0' and asserts the artifact resolves. Run: pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2 src/artifact-load-path.test.ts :: exit 0, 14/14 passed.

1c. What that means for the card's grading

⇒ This is an inert wrong number, not a load-time failure. Copying the example does not fail at plugin load. It is a documentation-accuracy defect, not class (a). The card's own text says exactly this branch belongs "in a PR's acceptance notes rather than in a card" — that judgment is the PM's, not mine; the reading is recorded here either way.

2. Every number changed, and the reading behind it

⚠️ Because the kernel accepts any string here, the kernel reading cannot justify a particular number. The justifying reading for the numbers is the npm registry plus this checkout, and the page now says which of the two governs.

Registry control: the same two-legged query returned a full packument for @objectstack/core (firing) and Not found for @objectstack/ui (see §4) — the probe discriminates.

3. What I decided about line 942, and why

Changed the number, kept the argument, and added one paragraph so the reason is one the runtime actually delivers.

The section is Best Practices → 3. Pin Core Dependencies. Its argument is exact pin beats caret range; the number is the vehicle, not the point. Changing '2.0.0' to '17.4.0' and the comment // Not '^2.0.0' to // Not '^17.0.0' preserves that argument form for form — an exact version on the left, the caret form named in the comment as the thing not to write — while removing the fifteen-major-stale number a reader would copy. Acceptance criterion 3 holds: the prose still argues "pin exactly", and the demonstration still demonstrates an exact pin against a caret.

But the old reason — "to avoid surprises" — is one §1 shows the kernel does not deliver: the range is never checked at load, so pinning it prevents no surprise there. Leaving that sentence untouched would have left the page advertising an enforcement that does not exist (AGENTS.md Prime Directive #10's corollary). So the reason now points where it is true: the installer, and the same dependency in package.json, which npm really does resolve.

The added paragraph and the new Callout under Version Constraints are the same idiom the page already uses five times over (optionalDependencies / peerDependencies are "proposal-only"; there is no definePlugin(); no onBoot, onUpgrade or onUninstall hook). Nothing was invented for this PR.

4. The @objectstack/ui sites at :71 and :462 — unchanged, and here is what I found

Both sit in peerDependencies, which this page's own callout at :425-429 already declares proposal-only: "the schema declares neither, so nothing resolves them."

Two readings on the package itself:

• Not in this checkout. No package.json under packages/, apps/ declares the name @objectstack/ui. Firing control: the identical query for @objectstack/core returns packages/core/package.json. Dark control: a nonsense name returns 0.
• Not on npm. GET https://registry.npmjs.org/@objectstack%2fui -> {"error":"Not found"}. Firing control on the same endpoint: @objectstack/core -> latest: 17.4.0, 157 versions.

So ^2.0.0 for @objectstack/ui is a range on a package that exists neither here nor on the public registry, in a block the page itself says nothing resolves. There is no reading that says what the right number would be, so per the dispatch fence I changed nothing and report it instead. It is a live question for whoever owns that name.

5. Changeset: skip-changeset, measured against files[]

Diff is one file: content/docs/protocol/kernel/plugin-spec.mdx.

package.json scanned:                                  77
non-private (publishable):                             70
publishable packages with NO files[] field:             0   (so npm's ship-everything default is nowhere in play)
SUBJECT   files[] arrays mentioning "content":          0
FIRING CONTROL  files[] arrays mentioning "dist":      70   (70/70 -> the reader is reading the arrays)

content/docs/** is rendered by apps/docs, whose package.json is "private": true and declares no files[] — it publishes nothing. Zero published bytes move. Asserted from the files[] readings above, not from the path name.

6. Gates

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack content/docs/protocol/kernel/plugin-spec.mdx from this worktree. 39 derived, 39 run, 0 NOT-MEASURED, 0 UNRUN, reconciled with --ran carrying every exit code:

✓ dispatch-gates --ran: 39 derived famil(ies) accounted for — 39 run,
  0 NOT-MEASURED (a DERIVED zero — all 39 recorded an exit code and none of them is 3).

38 of 39 exit 0. Repo-wide pnpm lint (eslint . --no-inline-config, no narrowing) :: exit 0 at 7cbd43373, whose tree bf6b9c0f5c708647871a55046be254192c1a8b8d is byte-identical to this PR's head d4f2919c2 (the amend was message-only).

The one red, and why it is not this diff

pnpm check:cross-package-test-inputs :: exit 1, flagging packages/cli/test/init-created-files-summary.e2e.test.ts descending into packages/spec/dist/. Neither path is in this diff. Proven by ablation, not by argument:

1. git checkout 7358c1c5b -- content/docs/protocol/kernel/plugin-spec.mdx — ablation verified on disk: the added marker went to 0 occurrences and the base '@objectstack/core': '^2.0.0', came back to 2.
2. Re-ran the gate with the diff removed :: exit 1, same FAIL: line. The red survives the ablation ⇒ it is not caused by this change.
3. Restored with git checkout HEAD -- …, verified two ways: git diff HEAD empty for that path, and git hash-object = f948028b39a1dd0e1f3959bf1c1c628674f3c8ae = the HEAD blob.

CI corroborates: "Lint & Repo Gates" completed success on 7358c1c5b, this branch's merge base. The red is a property of a locally-built tree (the gate walks packages/spec/dist/, which only exists here because I built it for the §1b probe), not of main.

pnpm --filter @objectstack/spec run check:skill-examples first exited 1 with a PREREQUISITE NOT MET refusal — packages/client-react/dist held no declarations. That is not a verdict. After pnpm --filter '@objectstack/client-react...' build it exits 0: 258 prose examples type-check across 3 surfaces.

Acceptance notes (⛔ not filed, noted here)

• content/docs/protocol/kernel/plugin-spec.mdx:470-471 still introduces the version-constraint grammar through SemanticVersionManager.satisfies(), a function with no production call site. The new callout directly above it now says so, so the page no longer misleads — but the sentence itself is a candidate for a rewrite that stops leading with a dead symbol. Successor: whoever next edits this page's Dependency Management section.
• pnpm check:cross-package-test-inputs reds on any tree where packages/spec/dist/ is built. Green on CI at the same commit, so this is a local-run-only asymmetry, not a defect in the code. Successor: any developer who builds packages/spec and then runs the derived gate list locally — which is every dev on a docs card like this one.

🤖 Generated with Claude Code

https://claude.ai/code/session_017ef78bLdybu3AffehKkhfk

Generated by Claude Code