docs(spec): the AI slot answers 501, not 404, when no AI service is mounted

[os-bill]

Fixes #17847

Clause-②: no

packages/spec/src/api/protocol.zod.ts's AI Operations note said this repo's dispatcher "404s AI service is not configured" when nothing serves the AI slot. It has answered 501 since the shared capabilityUnavailable exit landed, and the quoted body is no longer a local string either. This PR corrects that prose and nothing else — no runtime file is in the diff, and no status code, schema key or export moves.

Attribution for this run, in prose so it survives any body rewrite: produced by Claude Code, session session_01JbZnqu8bt6YqfJsr9vaFb3, https://claude.ai/code/session_01JbZnqu8bt6YqfJsr9vaFb3

The premise, re-measured — located by TEXT, not by line number

The card warns its line numbers rotted three times in one day, so the sentence was re-located by its text against origin/main e0d05538c0 (unmoved for the life of this branch):

$ grep -c '404s' packages/spec/src/api/protocol.zod.ts
1
$ grep -n '404s' packages/spec/src/api/protocol.zod.ts
2791:// `buildAIRoutes()` mounted, or 404s "AI service is not configured". So these

Counter-side, read the same round: packages/runtime/src/domains/ai.ts reaches capabilityUnavailable(deps, 'ai'), and packages/runtime/src/domains/unavailable.ts returns deps.error(serviceUnavailableMessage(slot), 501) under a docblock that states 501 Not Implemented in words. The defect stands, and the premise is live.

One extra reading the card did not carry: the literal string AI service is not configured survives nowhere in the tree except that stale comment (grep over packages/, content/, examples/, scripts/ — one hit, the comment itself). So the sentence was stale in both halves: the status AND the body it quoted.

Every arm was measured, not copied

The card hands over its behaviour table explicitly unverified, and an unqualified "/ai/* answers 501" would manufacture a second inaccurate sentence. Each arm is pinned by packages/runtime/src/domains/ai-anonymous-deny-ordering.test.ts, run on this tree:

pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 --reporter=verbose \
  src/domains/ai-anonymous-deny-ordering.test.ts
 Test Files  1 passed (1)
      Tests  13 passed (13)

arm	the case that pins it	answer
anonymous	GET /ai/models → 401, not the 501 remedy sentence · GET /ai/agents → 401, not the 200 empty-list courtesy	401 first (ANONYMOUS_DENY_STATUS = 401, pinned in core/src/security/anonymous-deny.test.ts)
GET /ai/agents	serves /ai/agents as the declared envelope with the payload relocated under data	200, { success: true, data: { agents: [] } }
every other /ai/*	501s /ai/models, /conversations, /usage and /chat with the remedy sentence	501
the body	keeps the 501 body string-identical to /discovery's services.ai message	shared serviceUnavailableMessage

⚠️ One condition deliberately not claimed in the new prose: a serveable service whose route table has not been published yet answers 503 AI service routes not yet initialized. That is a different premise from "no AI service is mounted", the sentence's own scope, and the three sibling sites do not state it either. Naming it here would widen the sentence back into the tour the card forbids.

The replacement

The same three-arm text the other three live sites carry after #16211 / PR #17844 (packages/client/src/index.ts, packages/runtime/src/route-ledger.ts, packages/runtime/src/domains/ai.ts), condensed to the block-comment voice this file already uses. 12 lines replace 2.

Changeset: owed, and measured rather than assumed

skip-changeset is not owed. packages/spec's files[] carries src/**/*.zod.ts, and npm pack --dry-run --json lists src/api/protocol.zod.ts among the tarball's 2016 entries (positive control: README.md present; negative control: zero *.test.ts). The sentence an upgrading author reads is a published byte, so it takes a patch. Not major, and Clause-②: no — check:api-surface and check:authorable-surface both green prove no export and no authorable key moved.

Gates

Derived off the merge base by the repo's own deriver, never by a hand-written diff:

node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands   # 77 commands
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RANFILE
✓ dispatch-gates --ran: 77 derived famil(ies) accounted for — 75 run, 2 NOT-MEASURED
  (2 DERIVED from a recorded exit 3)

Every exit code was landed to a file before being read — never through a pipe.

• 74 of 75 exit 0. Plus the 6 artifact-roster families the deriver flags because their roster sits under one of my paths (check-changeset-fixed, check:meta-url-spelling, check:spec-changes, check:authz-resolver, check:error-code-casing, check:filter-alias-parity) — read rather than assumed passed, all exit 0.
• pnpm check:cross-package-test-inputs exits 1 — the known signature (packages/cli descends packages/spec/dist/), red on a tree where packages/spec has been built, green where it has not. Already filed as [finding] check:cross-package-test-inputs passes in CI and fails on a built tree — its verdict is a function of gitignored build state #18353 / [finding] check:cross-package-test-inputs answers 1 or 0 depending on whether packages/spec has been BUILT — the author who follows AGENTS.md is the only one who sees the red, and CI never does #18440; ⛔ not filed again and not caused by this diff.
• 2 NOT-MEASURED, exit 3 = PREREQUISITE NOT MET: check:dual-build-cjs-loads and check:lean-entry-closure both read built output across the whole workspace and refuse on an unbuilt package. Neither a pass nor a finding; they belong to CI's whole-tree build.
• pnpm --filter @objectstack/spec check:generated — all 15 generated artifacts up to date, check:docs included. The block is a bare // comment, not a .describe(), so it feeds no content/docs/references/** page: grep buildAIRoutes content/docs/references/ is empty while the positive control (a .describe() string from this same file) does land in content/docs/references/api/protocol.mdx. ⇒ nothing to regenerate, and nothing hand-edited under a generated tree.
• Three spec gates first answered exit 1 as a stale-dist refusal (check:api-surface, check:browser-reachable-entries, check:dual-source-exports) — my src edit moved the build-input hash. All three exit 0 after pnpm --filter @objectstack/spec build, which is the documented caveat working, not a finding.

Tests

pnpm --filter @objectstack/spec test        Test Files  483 passed (483) · Tests  13781 passed (13781)
pnpm --filter @objectstack/spec typecheck   exit 0 (incl. check:test-typecheck, 144 pinned signatures held)

Dependency-closure build (step ①) is a no-op by construction: packages/spec declares no workspace dependencies, so packages/spec^... is empty. The package itself was built, because the dist-reading gates above require it.

Lint, as a declared narrowing rather than a repo sweep. pnpm exec eslint --no-inline-config --format json packages/spec/src/api/protocol.zod.ts → 1 file, 0 errors, 0 warnings, file count read from eslint's own JSON output. The checked population comes from eslint.config.mjs itself: every block matches **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} or a narrower glob, so the .changeset/*.md half of this diff is outside the linted set entirely and one file is the whole of it. Invariance for untouched files: this repo runs one eslint.config.mjs and it never enables type-aware linting — zero occurrences of projectService, and the only mention of parserOptions.project in the file is the comment stating it is absent — so no verdict on a file this diff did not touch can move because of this diff. The repo-wide pnpm lint stays CI's run.

No ablation and no reverse-verification run is reported, and that is a statement rather than an omission: this diff adds no guard that could be ablated and changes no type that could be made to fail. The claim the prose makes is carried by an existing pin test, which is why it was run rather than read.

Acceptance notes

• content/docs/api/plugin-endpoints.mdx (hand-written) discusses the AI routes and does not repeat the false 404 claim — it simply says nothing about what an unmounted slot answers. An absence, not a wrong statement, so it is not one of the three fileable classes. noted, not filed; successor: none known — no queued PR touches that page's AI section.
• The 503 AI service routes not yet initialized exit noted above is correct as it stands and is deliberately left out of the corrected sentence. Recorded as a scope boundary, not a finding.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/spec/src/api/protocol.zod.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

• 1 changed file(s) yielded no anchor (packages/spec/src/api/protocol.zod.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.

Coarse fallback — 136 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 e0d05538c0d0275728d25acfafbab259e23d0710 → packageMentionDocs.