@kitn.ai/ui 0.25.1 → 0.26.0

package/src/agent-tooling/catalog/labs-titles.ts

@@ -0,0 +1,114 @@
+import ts from 'typescript';
+
+/**
+ * The `Labs/…` title a story file REGISTERS: the `title` property of its
+ * default-exported meta object, parsed rather than matched.
+ *
+ * ★ WHY IT IS SPELLED THAT PRECISELY. Three text-based versions of this question
+ * shipped and each was defeated, and the fourth — a parse that was still too
+ * broad — was defeated too:
+ *
+ *  1. A raw regex over file text counted PROSE as a registration. Renaming every
+ *     real `Labs/Proofs` meta title across all six proof-*.stories.tsx left the
+ *     `Proofs` inventory row resolving, kept alive by one comment.
+ *  2. A hand-rolled comment stripper fixed that and introduced a worse bug. JSX
+ *     text like `Don't have an account?` put the scanner into single-quote state,
+ *     which it never left, so every `//` after it survived stripping. Live in
+ *     three story files; appending ONE comment line to one of them made an
+ *     invented `GHOSTPROBE` row resolve at exit 0.
+ *  3. The equivalence guard between the two copies of that stripper could not
+ *     see it: both carried the identical bug, so they agreed perfectly.
+ *  4. Parsing every `title:` in the file — the first version of THIS function —
+ *     was still wrong. A `title` nested in a story's `args` is not a
+ *     registration: `export const S = { args: { title: 'Labs/Apps' } };` in a
+ *     non-app story conjured a phantom app that satisfied this lint and
+ *     surfaces.test.ts together, with no comment involved at all.
+ *
+ * So the rule is the meta's own `title`, and nothing else. Comments are TRIVIA
+ * and never nodes; apostrophes, escapes and template literals are the real
+ * lexer's problem; and a title that is not the meta's is not a registration.
+ * Single-quoted, double-quoted and untemplated-backtick spellings are all read.
+ *
+ * REGISTERED COPY: `scripts/lint-catalog-drift.mjs` carries an equivalent
+ * `readLabsTitles`, because a Node `.mjs` cannot import a `.ts` at runtime.
+ * `tests/scripts/catalog-drift-guard-wiring.test.ts` imports both and asserts
+ * they agree over every story file in the tree plus adversarial inputs. Note
+ * what that guard is worth: it catches DIVERGENCE, and it is blind by
+ * construction to a bug both copies share — it stayed green through defects 2
+ * AND 4 above, both of which were present in both copies at once.
+ */
+export function readLabsTitles(text: string, fileName = 'story.tsx'): string[] {
+  // ScriptKind BY EXTENSION. Parsing a `.stories.ts` as TSX loses every title
+  // after a `<number>x` cast or a bare `<T>(x) => x` generic arrow, because
+  // neither is valid TSX. tsc parses that file as TS, accepts it and stays
+  // green, so typecheck does NOT contain this one — the lint would silently
+  // drop the registration on a file CI calls fine. storyExtensions() already
+  // admits `.ts` because the Storybook glob does.
+  const kind = fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, false, kind);
+  const meta = metaObject(source);
+  if (!meta) return [];
+  const titles: string[] = [];
+  for (const prop of meta.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const key = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : undefined;
+    if (key !== 'title') continue;
+    const init = prop.initializer;
+    if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+      if (init.text.startsWith('Labs/')) titles.push(init.text);
+    }
+  }
+  return titles;
+}
+
+/**
+ * The story file's DEFAULT-EXPORTED meta object, or null.
+ *
+ * Walking every `title:` in the file was the narrower defect: a `title` nested
+ * in a story's `args` is not a registration, and Storybook never reads it as
+ * one. Measured before this existed, both exit 0:
+ * `export const GhostProbeStory = { args: { title: 'Labs/GHOSTPROBE' } };`
+ * made an invented inventory row resolve, and the `Labs/Apps` spelling of the
+ * same shape produced a PHANTOM app that satisfied the lint and
+ * surfaces.test.ts together — the exact both-sides-green shape this guard
+ * exists to prevent, reached without a single comment.
+ *
+ * Restricting to the meta is a measured NO-OP on the clean tree: the title set
+ * and the nine `Labs/Apps` files are identical by set difference in both
+ * directions.
+ *
+ * Handles the two shapes in the tree and their wrappers:
+ * `const meta = {…} satisfies Meta; export default meta;` and
+ * `export default {…} as Meta;`
+ * `satisfies`, `as` and parentheses are unwrapped. An angle-bracket assertion
+ * (`export default <Meta>{…}`) deliberately is NOT: every story file is parsed
+ * as TSX, where `<Meta>{…}` is JSX and never a type assertion, so a branch for
+ * it would be dead code. Measured: that spelling returns []. It is also not a
+ * spelling any story in the tree uses.
+ */
+function metaObject(source: ts.SourceFile): ts.ObjectLiteralExpression | null {
+  const unwrap = (expr: ts.Expression | undefined): ts.Expression | undefined => {
+    let cur = expr;
+    while (
+      cur &&
+      (ts.isAsExpression(cur) || ts.isSatisfiesExpression(cur) || ts.isParenthesizedExpression(cur))
+    ) {
+      cur = cur.expression;
+    }
+    return cur;
+  };
+  const topLevel = new Map<string, ts.Expression>();
+  let defaultExport: ts.Expression | undefined;
+  for (const stmt of source.statements) {
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && d.initializer) topLevel.set(d.name.text, d.initializer);
+      }
+    } else if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
+      defaultExport = stmt.expression;
+    }
+  }
+  let expr = unwrap(defaultExport);
+  if (expr && ts.isIdentifier(expr)) expr = unwrap(topLevel.get(expr.text));
+  return expr && ts.isObjectLiteralExpression(expr) ? expr : null;
+}

package/src/agent-tooling/catalog/scenarios.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { Scenario, type TScenario } from './catalog-types';
+
+/**
+ * The acceptance deck, spec §6. Normative: written BEFORE the catalog so the
+ * catalog is built toward a measurement. The harness gives an agent the catalog
+ * and NO kit source; whatever it cannot build names what the catalog is missing.
+ */
+export const scenarios: TScenario[] = [
+  {
+    id: 'S1',
+    prompt:
+      'I already have <kai-chat> in my React app. Add a conversations sidebar and let assistant replies open artifacts in a side panel.',
+    needs: ['composition validity', 'wiring topology', 'invariant:reactivity-two-halves'],
+    depth: 'surface recipe applied to an existing tree',
+    scoring: [
+      'emitted code compiles under the react consumer tsc project',
+      'kai-conversations and kai-artifact register and render',
+      'kai-conversation-select wiring updates kai-chat.messages with a new array AND new changed-item objects',
+    ],
+  },
+  {
+    id: 'S2',
+    prompt:
+      'Add an AI chat to this Vue app. Messages stream from our existing /api/chat endpoint that speaks OpenAI SSE.',
+    needs: ['ingredient contracts', 'invariant:kit-parses-consumer-fetches', 'backend: consumer-owned endpoint'],
+    depth: 'greenfield, contract',
+    scoring: [
+      'imports readOpenAIStream from @kitn.ai/ui/wire; no hand-rolled SSE reader anywhere in the output',
+      'streams correctly against a mock OpenAI-SSE wire fixture',
+      'compiles under the vue consumer path',
+    ],
+  },
+  {
+    id: 'S3',
+    prompt: 'Give the prompt input slash-commands and voice, like your command palette demo.',
+    needs: ['ingredient configuration space', 'function-valued property contract (transcribe)'],
+    depth: 'capability',
+    scoring: [
+      'transcribe is set as a function-valued JS property, not an attribute',
+      'the slash-command trigger is wired per the ingredient contract',
+    ],
+  },
+  {
+    id: 'S4',
+    prompt: 'Build me a Perplexity-style research UI: sources, reasoning panel, follow-up suggestions.',
+    needs: ['surface recipes'],
+    depth: 'whole surface; expected to fail hardest first',
+    scoring: ['human eyeball against the perplexity Labs/App story', 'compiles and registers'],
+  },
+  {
+    id: 'S5',
+    prompt:
+      "I'm on WordPress. No build step. Give me a script tag for a support chat widget that talks to my service at https://example.com/chat.",
+    needs: ['delivery target: script-tag', 'invariant:upgrade-race', 'widget recipe', 'backend: consumer-owned endpoint'],
+    depth: 'platform embed',
+    scoring: [
+      'script-tag only, no bundler assumed',
+      'the output acknowledges the upgrade race per the open invariant (props set after registration, or the documented gate)',
+      'human eyeball in a plain HTML page',
+    ],
+  },
+  {
+    id: 'S6',
+    prompt: 'Add a spreadsheet-grid message type showing live cell edits.',
+    needs: ['the honesty bound: refuse what is not composable from these parts'],
+    depth: 'refusal',
+    scoring: [
+      'the agent refuses loudly, naming that no such element exists, instead of inventing <kai-datagrid>',
+      'no fabricated tag appears in the output',
+    ],
+  },
+  {
+    id: 'S7',
+    prompt: 'My messages render but nothing updates while streaming.',
+    needs: ['invariant diagnosis fields'],
+    depth: 'debugging',
+    scoring: [
+      'the answer identifies the reactivity-two-halves cause: same array reference, or same item object identity',
+      'the fix it proposes matches the invariant statement',
+    ],
+  },
+];
+
+export function listScenarios(): TScenario[] {
+  return z.array(Scenario).parse(scenarios);
+}

package/src/agent-tooling/catalog/surfaces.ts

@@ -0,0 +1,275 @@
+import { z } from 'zod';
+import {
+  InventoryEntry,
+  PartConsumption,
+  SurfaceRecipe,
+  type TInventoryEntry,
+  type TPartConsumption,
+  type TSurfaceRecipe,
+} from './catalog-types';
+
+/**
+ * Spec §4's sort, as records. Criterion: a surface is product-shaped, something
+ * a user could be handed, proven end-to-end by a Labs/App or deployable alone;
+ * an ingredient exists only inside something else; fixtures and proofs are
+ * corpus (tests), not catalog entries.
+ *
+ * TWO SENSES OF "CORPUS", and they are not the same thing. Here it is a `sort`:
+ * this entry is a fixture or a proof, so it is test material rather than a
+ * catalog entry. On a SurfaceRecipe, `corpus:` is a list of repo PATHS that
+ * demonstrate the recipe. A story can be both — `split-workspace` is sorted
+ * `surface` in this inventory and also appears in a recipe's `corpus:` array,
+ * which is coherent (a product-shaped surface is exactly what demonstrates a
+ * recipe) but reads as a contradiction if you join the two on the word. A
+ * packer must key on `sort === 'corpus'` and on `recipe.corpus` separately.
+ *
+ * Every `title` is a real Storybook title segment under `Labs/` — the app names
+ * are the `Labs/Apps` story FILENAMES, the rest are `title: 'Labs/<x>'` values
+ * under src/ (note: NOT all under src/elements/ — Settings lives in src/ui/ and
+ * Audio Visualizers under src/components/, so a check scoped to src/elements/
+ * alone would wrongly flag them).
+ *
+ * WHAT IS ENFORCED TODAY, in the present tense. Every claim below was measured
+ * by mutation in both directions, not reasoned from reading the guards.
+ *
+ * EVERY ROW IS RESOLVED AGAINST THE TREE. `lint:catalog-drift` (required CI,
+ * needs no build) requires each title to match a Labs story title or a
+ * `Labs/Apps` story filename on disk. Misspell ANY row -- tier is irrelevant --
+ * and CI fails by name: `Settings` -> `Settingss` gives
+ * `inventory: "Settingss" matches no Labs story title or Labs/Apps story file in
+ * the tree.` That closes what an earlier version of this comment called
+ * "GENUINELY UNCHECKED", and the earlier text is worth remembering as a defect
+ * in its own right: it survived the guard landing and went on telling every
+ * maintainer that the coverage did not exist, which is how someone ends up
+ * rebuilding it.
+ *
+ * WHAT RESOLUTION DOES NOT COVER IS DELETION, because the check runs row -> tree
+ * and a deleted row asks nothing of the tree. The other direction is covered
+ * unevenly, and this is the part to read before deleting anything:
+ *
+ *  1. `surface` rows naming a `Labs/Apps` story FILE -- deletion FAILS
+ *     surfaces.test.ts, which reads those filenames off disk and requires each
+ *     to have a row sorted `surface`. Covered in both directions.
+ *  2. `Proofs`, `Chat Slots`, `Prompt Input Slots`, `Workspace Slots` --
+ *     deletion FAILS surfaces.test.ts, which asserts those four exact titles are
+ *     present and sorted `corpus`. That list is a literal copy of these four
+ *     titles living inside the test; changing one means changing both.
+ *  3. Every remaining row -- deletion PASSES everything. Measured: removing the
+ *     `Settings` row leaves both surfaces.test.ts and lint:catalog-drift green.
+ *     This is the one real gap, and the lint's own honesty item 8 states it.
+ *
+ * Each row's tier is decided by which test in surfaces.test.ts covers it, so
+ * read that file, not this list, if they drift.
+ */
+export const inventory: TInventoryEntry[] = [
+  { title: 'claude-code', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'chatgpt', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'codex', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 't3code', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'perplexity', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'perplexity-pro', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'v0', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'wisp', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'lovable', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'split-workspace', sort: 'surface', note: 'Labs/App, end-to-end composition' },
+  { title: 'Workspace Home', sort: 'surface', note: 'the workspace preset' },
+  { title: 'Message Thread', sort: 'ingredient', note: 'the keystone of the composition-first direction (kai-thread)' },
+  { title: 'Composer', sort: 'ingredient', note: 'rich input, lives inside a surface' },
+  { title: 'Command', sort: 'ingredient', note: 'palette, summoned inside something' },
+  { title: 'Menu', sort: 'ingredient', note: 'menu primitive' },
+  { title: 'User Menu', sort: 'ingredient', note: 'account affordance inside a surface' },
+  { title: 'Settings', sort: 'ingredient', note: 'a panel, not a product' },
+  { title: 'Onboarding checklist', sort: 'ingredient', note: 'lives inside a surface' },
+  { title: 'Conversations Collapse', sort: 'ingredient', note: 'behavior of a part' },
+  { title: 'Resizable Collapsed', sort: 'ingredient', note: 'behavior of a part' },
+  { title: 'Audio Visualizers', sort: 'ingredient', note: 'voice affordance inside a surface' },
+  { title: 'Card', sort: 'ingredient', note: 'generative-UI cards arrive as tool calls (settled)' },
+  {
+    title: 'Foundations',
+    sort: 'ingredient',
+    note: 'atoms: Input, Search, Kbd, Nav, Tabs, Status, Screen, Progress Bar, Coachmark, EditableLabel, Voice output',
+  },
+  { title: 'Chat Slots', sort: 'corpus', note: 'fixture proving kai-chat injection seams' },
+  { title: 'Prompt Input Slots', sort: 'corpus', note: 'fixture proving prompt-input seams' },
+  { title: 'Workspace Slots', sort: 'corpus', note: 'fixture proving workspace injection seams' },
+  { title: 'Proofs', sort: 'corpus', note: 'tests by construction' },
+];
+
+/**
+ * Two recipes: one per delivery target. Between them they instance every
+ * invariant, which is what makes the drift lint's checks non-vacuous. Further
+ * recipes are added through acceptance-run iteration, each proven against a
+ * scenario before it lands.
+ *
+ * EVERY `wiring` edge below is EXECUTED in surfaces.test.ts against the real
+ * registered elements in jsdom — the event is fired the way a user fires it,
+ * the named property is assigned, and the effect is asserted in the shadow DOM.
+ * Name resolution against derived.json proves an event and a property EXIST; it
+ * does not prove the edge works, and that gap is where a plausible falsehood
+ * would live. Add an edge here only with a probe beside it.
+ */
+export const surfaceRecipes: TSurfaceRecipe[] = [
+  {
+    id: 'workspace-chat',
+    intent:
+      'Full-screen chat with a conversations sidebar; assistant replies can open artifacts in a resizable side panel.',
+    archetypes: ['full-screen'],
+    targets: ['bundler'],
+    ingredients: ['kai-chat', 'kai-conversations', 'kai-resizable', 'kai-artifact'],
+    backend: { endpoint: 'consumer-owned', reader: 'readModelStream' },
+    // WHERE the parts go, which the wiring edges below never said. Until this
+    // field existed a builder could read the whole recipe, the whole element
+    // reference and the whole scaffold and still not know whether the rail was a
+    // child of the chat or a sibling beside it — and the two answers lay out
+    // differently, so it is not a detail anyone can defer. One agent building
+    // from the MCP said so in as many words and then guessed.
+    //
+    // Slotted, and the tree decided it rather than taste: `<kai-chat>` declares a
+    // `sidebar` slot whose own description is "Left column (your nav /
+    // conversation list). Fixed width; use compose-your-own for resizable", and
+    // this recipe's own corpus story — chat-slots.stories.tsx — composes exactly
+    // `<kai-conversations slot="sidebar">` inside `<kai-chat>`.
+    //
+    // THE TREE ALSO PUBLISHES THE OTHER ANSWER, and an earlier version of this
+    // comment claimed it did not ("nothing in the tree composes them as
+    // siblings") — asserted without looking, which is the same defect as the
+    // over-generous `note` below it. The docs put the pair side by side in at
+    // least five places: guides/frameworks/html.mdx, svelte.mdx (a section
+    // titled "Add a conversation sidebar"), angular.mdx, vue.mdx, and
+    // examples/knowledge-base.mdx with its live demo. Every one of them is a
+    // layout the CONSUMER owns — a flex row they write, or `<kai-resizable>` —
+    // which is the compose-your-own path the slot's own description points at,
+    // and is what you want when the rail must resize. So the two are not in
+    // conflict about what is legal; this record says which one the RECIPE is,
+    // and the docs currently present the sibling form without saying that.
+    composition: [
+      {
+        child: 'kai-conversations',
+        parent: 'kai-chat',
+        slot: 'sidebar',
+        // Every clause here is checked against chat-thread.tsx, not inferred
+        // from the slot's name. The shell's whole sidebar implementation is one
+        // `<aside part="sidebar" class="flex w-64 shrink-0 …">` around a
+        // `<slot name="sidebar" />`: fixed width, no responsive class in the
+        // file, no collapse logic, and `<kai-chat>` never listens for
+        // `kai-collapse-toggle`. Collapse belongs to the rail
+        // (`collapsed`/`collapse()`), and conversation-list.tsx says so in as
+        // many words: "the host owns the surrounding region". A note that
+        // credited the shell with collapse and a breakpoint would send a builder
+        // into a 16rem empty column holding a floating reopen button.
+        note: 'the rail is a light-DOM child of <kai-chat> carrying slot="sidebar", not a sibling: the shell renders it into its own ::part(sidebar) aside, a FIXED-WIDTH column (w-64 in chat-thread.tsx, exposed as a part so you can restyle it) — and that is the whole of what the shell does. Collapse is the RAIL\'s own (collapsed / collapse() / kai-collapse-toggle) and <kai-chat> does not react to it, so a collapsed rail leaves the column at its fixed width; there is no responsive behaviour here either. Give the rail height (display:block;height:100%) and drive it through its own JS properties — being slotted changes where it renders, never how it is wired. If the COLUMN itself has to collapse, resize or respond to width, that is the <kai-workspace> layout shell (its start aside: startCollapsed / collapseBelow / drawer-below, widths via the --kai-workspace-start-* custom properties) or a layout you own',
+      },
+    ],
+    wiring: [
+      {
+        from: 'kai-conversations',
+        event: 'kai-conversation-select',
+        to: 'kai-chat',
+        property: 'messages',
+        note: 'detail is {id}; the host looks the thread up and assigns it — a new array AND a new object per changed item (reactivity-two-halves)',
+      },
+      {
+        from: 'kai-conversations',
+        event: 'kai-new-chat',
+        to: 'kai-chat',
+        property: 'messages',
+        note: 'detail is empty by design; the event is the whole signal and the host resets to an empty thread',
+      },
+      {
+        from: 'kai-chat',
+        event: 'kai-submit',
+        to: 'kai-chat',
+        property: 'messages',
+        note: 'host reads event.detail.value, appends the user turn, streams the reply through the wire reader onto parts[]',
+      },
+      {
+        from: 'kai-artifact',
+        event: 'kai-maximize-change',
+        to: 'kai-resizable',
+        property: 'maximizedIndex',
+        note: 'detail is {maximized}, NOT an index: the host knows which panel holds the artifact and mirrors the boolean onto that index (null to restore). Only needed when the panel is not an ancestor — an artifact INSIDE a kai-resizable-item already drives it through the bubbling kai-maximize-intent protocol, with no host code at all',
+      },
+    ],
+    invariants: [
+      'reactivity-two-halves',
+      'props-not-attributes',
+      'events-non-bubbling',
+      'host-coordinates',
+      'kit-parses-consumer-fetches',
+      'untrusted-model-output',
+    ],
+    // No single story composes all four ingredients, so the corpus names what
+    // each half is really proven by rather than one path that only half applies:
+    // chat-slots composes kai-chat with kai-conversations, split-workspace
+    // composes kai-resizable with kai-artifact, and surfaces.test.ts is where
+    // the four wiring edges above are actually executed.
+    corpus: [
+      'packages/ui/src/elements/chat-slots.stories.tsx',
+      'packages/ui/src/elements/split-workspace.stories.tsx',
+      'packages/ui/src/agent-tooling/catalog/surfaces.test.ts',
+    ],
+  },
+  {
+    // The script-tag instance. Without it, DeliveryTarget 'script-tag' and the
+    // whole upgrade-race invariant exist in the schema with no recipe using
+    // them, and S5 has nothing to reconstruct from.
+    id: 'support-widget-script-tag',
+    intent:
+      'A docked support chat widget added to a page with a script tag and no build step, talking to an endpoint the site owner already runs. The CMS case.',
+    archetypes: ['widget', 'docked'],
+    targets: ['script-tag'],
+    ingredients: ['kai-chat'],
+    backend: { endpoint: 'consumer-owned', reader: 'readOpenAIStream' },
+    wiring: [
+      {
+        from: 'kai-chat',
+        event: 'kai-submit',
+        to: 'kai-chat',
+        property: 'messages',
+        note: 'host reads event.detail.value, appends the user turn, streams the reply through the wire reader; on this target the host is an inline script, not a framework, so the listener must be attached after customElements.whenDefined (upgrade-race)',
+      },
+    ],
+    invariants: [
+      'upgrade-race',
+      'reactivity-two-halves',
+      'props-not-attributes',
+      'events-non-bubbling',
+      'kit-parses-consumer-fetches',
+      'untrusted-model-output',
+    ],
+    corpus: ['packages/ui/README.md'],
+  },
+];
+
+/**
+ * REGISTERED COPY (spec §3). Which MessagePart variants an element consumes is
+ * not derivable from any type today, so it is recorded here as an explicit copy.
+ * Task 7's drift lint fails when the union gains a variant no record accounts
+ * for, which is what stops this going stale silently.
+ *
+ * WHAT THE CHECKS CAN AND CANNOT SEE. surfaces.test.ts asserts both directions
+ * of NAME agreement with `derived.partVariants`: no variant in the union is
+ * unaccounted for by any record, and no record claims a variant the union does
+ * not have. Neither can check the claim that actually matters — whether
+ * `kai-chat` really renders a `source` part is an EDITORIAL judgement, and
+ * nothing in the tree derives it, which is exactly why this is a registered
+ * copy rather than generated data. A machine cannot tell a correct record from
+ * a confident wrong one here. That claim is measured by the acceptance deck,
+ * not by CI, so do not add an assertion that looks like it covers it.
+ */
+export const partConsumption: TPartConsumption[] = [
+  { tag: 'kai-chat', consumes: ['text', 'reasoning', 'tool', 'card', 'source', 'file'] },
+  { tag: 'kai-message', consumes: ['text', 'reasoning', 'tool', 'card', 'source', 'file'] },
+];
+
+export function listInventory(): TInventoryEntry[] {
+  return z.array(InventoryEntry).parse(inventory);
+}
+
+export function listSurfaceRecipes(): TSurfaceRecipe[] {
+  return z.array(SurfaceRecipe).parse(surfaceRecipes);
+}
+
+export function listPartConsumption(): TPartConsumption[] {
+  return z.array(PartConsumption).parse(partConsumption);
+}

package/src/agent-tooling/integrations/anthropic.ts

@@ -317,7 +317,13 @@ function reframeToOpenAISse(body: ReadableStream<Uint8Array>): ReadableStream<Ui
 async function chatHandler(request: Request): Promise<Response> {
   // Both model and tools come from the browser. \`tools\` arrives in OpenAI
   // function form and is converted to this API's shape below.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
   const { system, messages: anthropicMessages } = toAnthropicBody(messages);
   const anthropicTools = toAnthropicTools(tools);
 

package/src/agent-tooling/integrations/cloudflare.ts

@@ -24,9 +24,44 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
  */
 type ChatRequestBody = { messages: OpenAIWireMessage[] };
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a
+ *  missing messages array is a ChatRequestError with a status — NEVER an
+ *  unhandled SyntaxError (findings F-10). */
+async function readChatRequest(request: Request): Promise<ChatRequestBody> {
+  if (request.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${request.method} not allowed — POST /api/chat.\`);
+  }
+  let parsed: unknown;
+  try { parsed = await request.json(); } catch {
+    throw new ChatRequestError(400, 'Request body is not valid JSON.');
+  }
+  const body = parsed as ChatRequestBody;
+  if (!Array.isArray(body?.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body;
+}
+
+/** Map a guard rejection to the Response its status demands; rethrow anything
+ *  else — an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown): Response {
+  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });
+  throw error;
+}
+
 export default {
   async fetch(req: Request, env: Env): Promise<Response> {
-    const { messages } = (await req.json()) as ChatRequestBody;
+    let chatBody: ChatRequestBody;
+    try {
+      chatBody = await readChatRequest(req);
+    } catch (error) {
+      return toChatErrorResponse(error);
+    }
+    const { messages } = chatBody;
 
     let nativeStream: ReadableStream<Uint8Array>;
     try {
@@ -101,7 +136,13 @@ export default {
   },
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // Proxy Workers AI over its OpenAI-compatible HTTP endpoint, token server-side.
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   const upstream = await fetch(
     \`https://api.cloudflare.com/client/v4/accounts/\${process.env.CF_ACCOUNT_ID}/ai/v1/chat/completions\`,

package/src/agent-tooling/integrations/langgraph.ts

@@ -31,7 +31,13 @@ const agent = createReactAgent({
 
 // Stream a compiled LangGraph agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // agent.stream() coerces plain {role, content} objects into BaseMessage
   // instances itself, including OpenAI-shaped tool_calls, so the wire messages

package/src/agent-tooling/integrations/mastra.ts

@@ -28,7 +28,13 @@ const mastra = new MastraClient({ baseUrl: MASTRA_URL });
 
 // Proxy a Mastra agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // MastraClient's Agent.stream() takes AI-SDK CoreMessage[], not the OpenAI
   // wire format: each message has ONE literal role (not a union) and content