test(client,runtime): the last wildcard was wrong evidence, not weak — AI ratchet 3 → 0 (#3718) (#3727)

* test(client,runtime): the last wildcard was wrong evidence, not weak — AI ratchet 3 → 0 (#3718)

The capstone (#3642) ratcheted "matched only by a `**` family" as WEAKER
evidence, to be driven down by enumerating each dynamic family. 60 → 3 after
#3656. The last 3 were `ai.nlq` / `ai.suggest` / `ai.insights` on `* /ai/**`.

Enumerating that family — in `cloud`, where service-ai lives — answered the
question the ratchet was really asking. `buildAIRoutes()` mounts 12 routes
(chat, chat/stream, complete, models, status, effective-model, six
conversations) and NONE is `/nlq`, `/suggest` or `/insights`.

  client.ai methods:              3    answered by any repo:  0
  real AI routes:                12    expressed by the SDK:  0

The two sets are disjoint. So the wildcard was not weak evidence, it was WRONG
evidence: it certified three URLs nothing anywhere serves. Its note even
asserted the client "expresses nlq/suggest/insights against the REST AI
routes" — never verified, and false. `DEFAULT_AI_ROUTES` declares all three but
has no runtime consumer (only the spec's own test reads it), and
`aiNlq?`/`aiSuggest?`/`aiInsights?` are optional protocol methods nothing
implements. Declared, never built (#3718) — instances 7-9 of the
`the method exists != the method can be called` class.

`/api/v1/ai/` becomes a bounded prefix exemption alongside the control plane:
two cross-repo surfaces, both ledgered in `cloud`. Only `ai.*` may use it, and
the namespace must still be reaching it, so the hole cannot widen.

The wildcard assertion becomes `toBe(0)`, not a ratchet. Zero is the point:
every matched call now rests on an exact enumerated route, and reintroducing a
`**` match reintroduces the one kind of evidence this audit family has caught
being wrong.

Mutation-checked both ways: removing the exemption re-exposes exactly the three
methods, and running the PRE-change capstone with the bound at 0 confirms the
old wildcard set was exactly `ai.insights`, `ai.nlq`, `ai.suggest` and nothing
else.

Adds audit §14 with the lesson worth carrying out of §1-§14: a claim about a
family is not a claim about a member. Wildcards, prefixes and "the service
handles that" all read as coverage in a green suite, and every one this audit
opened was hiding something.

Test-and-comment changes only; no runtime behaviour is affected.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(api): the published AI surface was inverted — correct it (#3718)

The docs-drift advisory on this PR prompted a check of whether any published
doc advertises the three dead `ai.*` methods. It does, and the AI docs turn out
to be backwards in both directions at once:

  - `plugin-endpoints.mdx` tabled `/ai/nlq`, `/ai/suggest`, `/ai/insights` as
    the AI plugin's endpoints. None of the three is mounted by anything.
  - The same section's callout stated "There is no `/ai/chat` route".
    `/api/v1/ai/chat` IS mounted, along with `/chat/stream`, `/complete`,
    `/models` and six `/conversations` routes.

So the documentation named the three routes that do not exist and explicitly
denied the one that does — while `client-sdk.mdx` carried three
copy-pasteable examples that 404 on every call. That is Prime Directive #10 in
the literal sense: advertising a capability the runtime does not deliver.

Corrected:
  - `client-sdk.mdx` — the three examples are marked declared-but-unimplemented
    with the reason, and the chat note now says the chat endpoint exists and it
    is the SDK that lacks a method for it.
  - `plugin-endpoints.mdx` — status column on the three, plus the real 12-route
    table and a pointer to cloud's ai-route-ledger.ts. The callout's surviving
    point (use `useChat()` directly) is kept; only its false premise is fixed.
  - `services-checklist.mdx` — notes that all three are optional protocol
    methods nothing implements.

Deliberately does NOT decide #3718 (implement vs remove vs express the real
surface). Every edit here states what is true today and stays true whichever
way that lands.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/ai-wildcard-to-zero.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/runtime": patch
+---
+
+test(client,runtime): the last wildcard was wrong evidence, not weak — AI ratchet 3 → 0 (#3718)
+
+The capstone (#3642) ratcheted "matched only by a `**` family" as weaker
+evidence, to be driven down by enumerating each dynamic family. 60 → 3 after
+#3656. The last 3 were `ai.nlq` / `ai.suggest` / `ai.insights` on `* /ai/**`.
+
+Enumerating that family (in `cloud`, where `service-ai` lives) showed the
+wildcard had not been weak evidence but **wrong** evidence. `buildAIRoutes()`
+mounts 12 routes — `chat`, `chat/stream`, `complete`, `models`, `status`,
+`effective-model`, six `conversations` — and **none** is `/nlq`, `/suggest` or
+`/insights`. The SDK's entire AI namespace is dead, the entire real AI surface
+is unexpressed by the SDK, and the two sets are disjoint (#3718).
+
+The old row's note even claimed the client "expresses nlq/suggest/insights
+against the REST AI routes". That was never verified and is false:
+`DEFAULT_AI_ROUTES` declares them but has no runtime consumer (only the spec's
+own test reads it), and `aiNlq?`/`aiSuggest?`/`aiInsights?` are optional
+protocol methods nothing implements.
+
+`/api/v1/ai/` becomes a bounded prefix exemption alongside the control plane —
+two cross-repo surfaces, both ledgered in `cloud` — and the wildcard-only
+assertion becomes `toBe(0)`, not a ratchet: every matched call now rests on an
+exact enumerated route. Mutation-checked in both directions (removing the
+exemption re-exposes exactly the 3, and the pre-change count was verified to be
+exactly those 3 and nothing else).
+
+Test-and-comment changes only; no runtime behaviour is affected.

content/docs/api/client-sdk.mdx

@@ -312,12 +312,18 @@ await client.notifications.markAllRead();
 // through sys_inbox_message and tracks read-state in sys_notification_receipt.
 // These helpers will be repointed during the objectui bell cut-over.
 
-// AI — AI-powered features
+// AI — DECLARED BUT NOT IMPLEMENTED (#3718). These three methods build
+// /api/v1/ai/{nlq,suggest,insights}, and no server in any repo mounts those
+// paths, so every call 404s. They are typed and shipped, which is why they
+// look usable; they are not. Do not build on them until #3718 resolves.
 await client.ai.nlq({ query: 'Show me all active accounts' });
 await client.ai.suggest({ object: 'account', field: 'industry' });
 await client.ai.insights({ object: 'sales', recordId: dealId });
-// Note: conversational chat is no longer on the client — use the Vercel AI SDK
-// (`useChat()` from `@ai-sdk/react`) directly against your chat endpoint.
+// Conversational chat is not on the client — use the Vercel AI SDK
+// (`useChat()` from `@ai-sdk/react`) directly against the chat endpoint.
+// That endpoint DOES exist (POST /api/v1/ai/chat, plus /chat/stream,
+// /complete, /models and six /conversations routes, all served by service-ai);
+// the SDK simply has no method for any of them.
 
 // i18n — Internationalization
 await client.i18n.getLocales();

content/docs/api/plugin-endpoints.mdx

@@ -95,14 +95,37 @@ The core dispatcher implements only the list / read / read-all routes above. Dev
 
 ### AI (`/ai`) — Plugin Required
 
-| Method | Endpoint | Description |
-|:-------|:---------|:------------|
-| POST | `/ai/nlq` | Natural language → query |
-| POST | `/ai/suggest` | Get value suggestions |
-| POST | `/ai/insights` | Get data insights |
+| Method | Endpoint | Description | Status |
+|:-------|:---------|:------------|:-------|
+| POST | `/ai/nlq` | Natural language → query | **Not implemented** |
+| POST | `/ai/suggest` | Get value suggestions | **Not implemented** |
+| POST | `/ai/insights` | Get data insights | **Not implemented** |
 
-<Callout type="info">
-There is no `/ai/chat` route — the AI chat route was removed so the wire protocol aligns with the Vercel AI SDK. Use `useChat()` (`@ai-sdk/react`) directly against the streaming chat endpoint rather than the client SDK's `ai` namespace, which intentionally does not expose a `chat` method.
+<Callout type="warn">
+**This table was inverted, and is corrected here (#3718).** The three routes
+above are declared in `DEFAULT_AI_ROUTES` and called by
+`client.ai.nlq/suggest/insights`, but **no plugin in any repo mounts them** —
+every call 404s. Conversely, this callout used to state "there is no
+`/ai/chat` route", which was wrong: `/ai/chat` is mounted.
+
+What the AI plugin (`service-ai`) actually serves is a different set of
+**12** routes:
+
+| Method | Endpoint |
+|:-------|:---------|
+| POST | `/ai/chat`, `/ai/chat/stream`, `/ai/complete` |
+| GET | `/ai/models`, `/ai/status`, `/ai/effective-model` |
+| POST / GET | `/ai/conversations` |
+| GET / PATCH / DELETE | `/ai/conversations/:id` |
+| POST | `/ai/conversations/:id/messages` |
+
+None of those has a client-SDK method — the SDK's `ai` namespace and the real
+AI surface do not overlap at all. Reviewed dispositions for all 12 live in the
+`cloud` repo, `packages/service-ai/src/ai-route-ledger.ts`.
+
+The original point stands on its own terms: use `useChat()` (`@ai-sdk/react`)
+directly against the streaming chat endpoint, because the client SDK exposes no
+`chat` method.
 </Callout>
 
 ### i18n (`/i18n`) — Plugin Required

content/docs/kernel/services-checklist.mdx

@@ -251,6 +251,14 @@ Trigger engine, event triggers from ObjectQL hooks, flow executor, scheduled tri
 ### 10. ai — 3 methods
 `aiNlq`, `aiSuggest`, `aiInsights`
 
+<Callout type="warn">
+Declared only. All three are **optional** protocol methods (`aiNlq?` …) and no
+service in any repo implements them, so the `/ai/{nlq,suggest,insights}` routes
+they back are mounted by nothing and the matching `client.ai.*` calls 404
+(#3718). The AI service that does exist (`service-ai`) serves a different set
+— chat, complete, models, conversations — through none of these methods.
+</Callout>
+
 ### 11. i18n — 3 methods
 `getLocales`, `getTranslations`, `getFieldLabels`
 

docs/audits/2026-07-dispatcher-client-route-coverage.md

@@ -355,6 +355,50 @@ against the framework revision cloud builds and ships against. That is the
 right revision to check — but it means a `projects.*` change landing here is
 not verified against the control plane until that pin moves.
 
+## 14. The last wildcard, and what it was actually worth (#3718)
+
+§10's capstone ratcheted "matched only by a `**` family" as *weaker* evidence,
+to be driven down by enumerating each dynamic family. 60 → 3 after #3656. The
+last 3 were `ai.nlq` / `ai.suggest` / `ai.insights` on `* /ai/**`.
+
+Enumerating that family answered the question the ratchet was really asking.
+`service-ai` lives in the `cloud` repo (Cloud/EE), so this repo could never see
+its table — the dispatcher just proxies to whatever `buildAIRoutes()` returned.
+That table is **12 routes**: `chat`, `chat/stream`, `complete`, `models`,
+`status`, `effective-model`, and six `conversations` routes.
+
+**None of them is `/nlq`, `/suggest` or `/insights`.**
+
+| | |
+|---|---|
+| `client.ai` methods | 3 — `nlq`, `suggest`, `insights` |
+| …that any repo mounts | **0** |
+| Real AI routes | 12 |
+| …expressed by the SDK | **0** |
+
+The two sets are disjoint. So the wildcard was not weak evidence — it was
+**wrong** evidence, certifying three URLs nothing serves, and its note even
+asserted the client "expresses nlq/suggest/insights against the REST AI routes"
+(never verified, false). `DEFAULT_AI_ROUTES` in `plugin-rest-api.zod.ts`
+declares all three, but has **no runtime consumer** — only the spec's own test
+reads it — and `aiNlq?` / `aiSuggest?` / `aiInsights?` are optional protocol
+methods nothing implements. Declared, never built (#3718). Instances 7–9 of the
+`the method exists ≠ the method can be called` class.
+
+`/api/v1/ai/` is now a bounded prefix exemption alongside the control plane —
+two cross-repo surfaces, both ledgered in `cloud`
+(`packages/service-ai/src/ai-route-ledger.ts`, 10 `gap` / 2 `server-only`,
+enumerated straight off the array `buildAIRoutes()` returns). **The
+wildcard-only bound is 0**, and the assertion is `toBe(0)` rather than a
+ratchet: every matched call now rests on an exact enumerated route, and
+reintroducing a `**` match reintroduces the one kind of evidence this audit
+family has caught being wrong.
+
+The generalisable lesson, and the one worth carrying out of §1–§14: **a claim
+about a family is not a claim about a member.** Wildcards, prefixes and "the
+service handles that" all read as coverage in a green suite. Every one of them
+this audit opened turned out to be hiding something.
+
 ## Follow-up slicing (proposed)
 
 1. **`client.actions.invoke(...)`** — closes the largest hole (3 routes).
@@ -370,7 +414,8 @@ not verified against the control plane until that pin moves.
 11. **Control-plane surface** (§10) — done in #3655; the ledger lives in `cloud`
     (§13), which is the only repo where both halves are in scope.
 12. **Enumerate `/auth/**`** (§11) — done in #3656; wildcard ratchet 60 → 3.
-13. **Enumerate `/ai/**`** — the last dynamic family, 3 SDK methods.
+13. **Enumerate `/ai/**`** — done (§14). The wildcard ratchet is now **0**; the
+    3 SDK methods turned out to be dead (#3718).
 14. **Response-shape conformance** (§12) — error path done in #3675 for both
     services; the storage **success** bodies (three shapes, none carrying
     `success: true`) and the dispatcher's numeric `error.code` remain.

packages/client/src/client-url-conformance.test.ts

@@ -148,6 +148,29 @@ function matches(verb: string, path: string): Pattern | undefined {
 const CONTROL_PLANE = '/api/v1/cloud/';
 const CONTROL_PLANE_NAMESPACE = 'projects.';
 
+/**
+ * The AI surface — the SECOND cross-repo prefix, and exempt for the same
+ * reason as the control plane rather than a different one.
+ *
+ * `/api/v1/ai/*` routes are built by `service-ai`'s `buildAIRoutes()` at plugin
+ * start, and `service-ai` is a Cloud/EE package living in the `cloud` repo.
+ * This repo's dispatcher only proxies to whatever that table contains (or 404s
+ * "AI service is not configured" when it is absent), so no ledger here can
+ * enumerate them — the same boundary `projects.*` sits behind.
+ *
+ * It used to be handled as a `* /ai/**` WILDCARD match instead, which was
+ * strictly worse: a wildcard says the family is claimed, so all three `ai.*`
+ * methods counted as matched. #3718 enumerated the real table in `cloud` and
+ * found the SDK's three URLs are not in it — `/nlq`, `/suggest` and
+ * `/insights` are mounted by nothing, in any repo (#3718). The wildcard was
+ * not weak evidence, it was wrong evidence, which is exactly why the ratchet
+ * below treats `**` matches as something to drive to zero rather than tolerate.
+ *
+ * Bounded the same way as the control plane: only `ai.*` may use the prefix.
+ */
+const AI_PLANE = '/api/v1/ai/';
+const AI_NAMESPACE = 'ai.';
+
 // ---------------------------------------------------------------------------
 // 2. The recorder
 // ---------------------------------------------------------------------------
@@ -326,6 +349,7 @@ describe('client URL conformance ↔ the union of all four route ledgers (#3642)
     const silent: string[] = [];
     const malformed: string[] = [];
     const controlPlane: string[] = [];
+    const aiPlane: string[] = [];
     const wildcardOnly: string[] = [];
 
     for (const name of METHODS) {
@@ -347,6 +371,7 @@ describe('client URL conformance ↔ the union of all four route ledgers (#3642)
         }
         const path = new URL(call.url, BASE).pathname;
         if (path.startsWith(CONTROL_PLANE)) { controlPlane.push(`${name} → ${call.verb} ${path}`); continue; }
+        if (path.startsWith(AI_PLANE)) { aiPlane.push(`${name} → ${call.verb} ${path}`); continue; }
         const hit = matches(call.verb, path);
         if (!hit) { unmatched.push(`${name} → ${call.verb} ${path}`); continue; }
         if (hit.route.includes('**')) wildcardOnly.push(`${name} → ${call.verb} ${path} (via ${hit.route})`);
@@ -381,18 +406,35 @@ describe('client URL conformance ↔ the union of all four route ledgers (#3642)
     ).toEqual([]);
     expect(controlPlane.length, 'the projects namespace should still be reaching the control plane').toBeGreaterThan(0);
 
+    // Same bounding for the AI prefix. `ai.*` is the ONLY namespace allowed to
+    // use it; anything else reaching /api/v1/ai/ is a method that has wandered
+    // into a surface no in-repo ledger can vouch for.
+    const aiTrespassers = aiPlane.filter((e) => !e.startsWith(AI_NAMESPACE));
+    expect(
+      aiTrespassers,
+      `non-ai methods targeting the AI plane, which service-ai owns in the cloud repo:\n${aiTrespassers.join('\n')}`,
+    ).toEqual([]);
+    expect(aiPlane.length, 'the ai namespace should still be reaching the AI plane').toBeGreaterThan(0);
+
     // HOW STRONG IS THIS GUARD, HONESTLY. A `**` row asserts only that a prefix
     // family is CLAIMED, not that the specific URL resolves. That was this
     // guard's biggest weakness at #3642: 60 of ~196 matched calls rested on
     // nothing better, 54 of them on `* /auth/**`. #3656 enumerated better-auth's
     // real route table, so those now match exact rows and the bound fell 60 → 3.
-    // What remains is `* /ai/**`, whose routes service-ai builds at plugin start.
-    // Ratcheted: enumerating that family lowers it; nothing raises it without a
-    // deliberate decision.
+    // The last 3 were `ai.nlq/suggest/insights` on `* /ai/**`, and enumerating
+    // THAT family (#3718, in `cloud`, where service-ai lives) showed the
+    // wildcard had not been weak evidence but WRONG evidence: none of the three
+    // URLs is in the real table, and nothing in any repo mounts them (#3718).
+    // They are now handled by the AI_PLANE exemption above and pinned as dead
+    // on the cloud side, so this bound is 0.
+    //
+    // ZERO IS THE POINT: every remaining matched call rests on an exact route
+    // some ledger enumerated. Raising this bound reintroduces the one kind of
+    // evidence this audit family has caught being wrong.
     expect(
       wildcardOnly.length,
       'methods matched only by a wildcard `**` family — weaker evidence than an exact ' +
-        `route. Enumerate a dynamic family to lower this bound; do not raise it:\n${wildcardOnly.join('\n')}`,
-    ).toBeLessThanOrEqual(3);
+        `route, and demonstrably able to be wrong (#3718). Enumerate the family instead:\n${wildcardOnly.join('\n')}`,
+    ).toBe(0);
   });
 });

packages/runtime/src/route-ledger.ts

@@ -36,7 +36,17 @@
  * not a resolvable route. `* /auth/**` was the worst of it — 54 SDK methods
  * resting on a prefix claim — until #3656 enumerated better-auth's real table
  * into `plugin-auth/src/auth-route-ledger.ts`, dropping the guard's
- * wildcard-only count 60 → 3. The `* /ai/**` row below is what remains.
+ * wildcard-only count 60 → 3.
+ *
+ * The last 3 were the `ai.*` methods on `* /ai/**`, and enumerating THAT
+ * family settled the question of how much a `**` row is worth: not "weaker
+ * evidence" but, in this case, WRONG evidence. `service-ai` (a Cloud/EE
+ * package in the `cloud` repo) mounts 12 routes and not one of them is the
+ * `/nlq` `/suggest` `/insights` the SDK calls — the wildcard had been
+ * certifying three URLs that nothing anywhere serves (#3718). The capstone now
+ * exempts `/api/v1/ai/` by prefix like the control plane, the real table is
+ * ledgered in `cloud`, and the wildcard-only bound is **0**: every matched call
+ * rests on an exact enumerated route.
  *
  * This module is runtime-internal (not exported from the package index): it is
  * the guard's data, not public API. Promotion to `@objectstack/spec` is a
@@ -180,9 +190,9 @@ export const ROUTE_LEDGER: readonly RouteLedgerEntry[] = [
   { route: '* /auth/**', domain: '/auth', disposition: 'sdk', client: 'auth.me',
     note: 'wholesale delegate to the auth service. Not enumerable route-by-route HERE, but no longer unenumerated: since #3656 plugin-auth/src/auth-route-ledger.ts carries the 55 SDK-reached routes plus the full mounted inventory, read off better-auth\'s live auth.api table' },
 
-  // ── ai (dynamic route table) ──────────────────────────────────────────────
+  // ── ai (dynamic route table, owned by another repo) ───────────────────────
   { route: '* /ai/**', domain: '/ai', disposition: 'dynamic',
-    note: 'routes come from service-ai buildAIRoutes() at plugin start; client expresses nlq/suggest/insights against the REST AI routes' },
+    note: 'routes come from service-ai buildAIRoutes() at plugin start — service-ai is a Cloud/EE package in the `cloud` repo, so this repo cannot enumerate them and the dispatcher only proxies (or 404s "AI service is not configured"). Enumerated on the other side of that boundary since #3718: cloud packages/service-ai/src/ai-route-ledger.ts. The previous note here claimed the client "expresses nlq/suggest/insights against the REST AI routes"; that was never verified and is FALSE — nothing mounts those three paths (#3718)' },
 
   // ── meta (legacy chain) ───────────────────────────────────────────────────
   { route: 'GET /meta', domain: '/meta', disposition: 'sdk', client: 'meta.getTypes' },