stitchkit 0.98.2 → 0.99.0

package/CHANGELOG.md

@@ -15,6 +15,25 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.99.0] — 2026-09-27
+
+### ⚠️ Breaking changes
+
+- `stitchkit/tools` — `flattenUnionInput` preserves object properties and typed
+  array items when discriminated-union variants share a field with different
+  structures. Flat mode no longer guarantees the absence of nested `anyOf`.
+  Before: a collided object/array field was `{ type: ['object', 'array'] }`.
+  After: `{ anyOf: [{ type: 'object', properties: ... }, { type: 'array', items: ... }] }`.
+  The containing union stays an object and the original contract still validates
+  execution. Schema consumers must traverse these nested alternatives; no
+  contract changes or global flatten opt-out are needed. This avoids provider
+  rejection of array schemas with missing `items`. See
+  [ADR 0205](docs/decisions/0205-flat-tool-collisions-retain-structural-alternatives.md).
+
+**Who must act:** users of `flattenUnionInput: true` whose schema walkers,
+snapshots or provider restrictions assume no nested `anyOf`. Other consumers
+only update the dependency; runtime input validation is unchanged.
+
 ## [0.98.2] — 2026-09-27
 
 ### Fixed

package/dist/entrypoints/agent-runtime/coding-tools.js

@@ -3,11 +3,11 @@ import {
   AgentCodingToolLimitsSchema,
   AgentCodingToolPathAuthorizationSchema,
   createAgentCodingTools
-} from "../../index-het2he5g.js";
+} from "../../index-e4hkgm5t.js";
 import"../../index-px2gm2jp.js";
 import"../../index-qmy6zq75.js";
-import"../../index-xw3s75nj.js";
-import"../../index-np4m8hd3.js";
+import"../../index-d8m8zpd8.js";
+import"../../index-0r0fbk7z.js";
 import"../../index-eqqvgdb3.js";
 import"../../index-znfs20ss.js";
 import"../../index-p5r7qpdd.js";

package/dist/entrypoints/agent-runtime/harness.js

@@ -6,7 +6,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "../../index-nts4a2br.js";
+} from "../../index-jhx828hc.js";
 import"../../index-83bdg97s.js";
 import"../../index-y64k3s0h.js";
 import {
@@ -19,15 +19,15 @@ import {
 import"../../index-gxrt5h6v.js";
 import"../../index-gtj3zc53.js";
 import"../../index-79z7m7dt.js";
-import"../../index-55hkhm67.js";
+import"../../index-8qt2m66q.js";
 import"../../index-zfrhfn82.js";
 import"../../index-35mh5bhj.js";
 import"../../index-zcgf3gqf.js";
 import"../../index-1zbbzgfh.js";
 import {
   defineRuntimeTool
-} from "../../index-xw3s75nj.js";
-import"../../index-np4m8hd3.js";
+} from "../../index-d8m8zpd8.js";
+import"../../index-0r0fbk7z.js";
 import"../../index-eqqvgdb3.js";
 import"../../index-znfs20ss.js";
 import"../../index-p5r7qpdd.js";

package/dist/entrypoints/agent-runtime/sandbox.js

@@ -1,14 +1,14 @@
 import {
   createAgentCodingTools
-} from "../../index-het2he5g.js";
+} from "../../index-e4hkgm5t.js";
 import"../../index-px2gm2jp.js";
 import {
   codingRefusal,
   missingSandboxRestrictions,
   probeAgentProcessSandbox
 } from "../../index-qmy6zq75.js";
-import"../../index-xw3s75nj.js";
-import"../../index-np4m8hd3.js";
+import"../../index-d8m8zpd8.js";
+import"../../index-0r0fbk7z.js";
 import"../../index-eqqvgdb3.js";
 import"../../index-znfs20ss.js";
 import"../../index-p5r7qpdd.js";

package/dist/entrypoints/agent-runtime.js

@@ -24,7 +24,7 @@ import {
   renderAgentStateSlots,
   repairedSearchCall,
   selectAgentHistory
-} from "../index-nts4a2br.js";
+} from "../index-jhx828hc.js";
 import"../index-83bdg97s.js";
 import {
   AgentAdmissionEventSchema,
@@ -164,7 +164,7 @@ import {
 import {
   buildToolManifest,
   mountAgent
-} from "../index-863ea9jb.js";
+} from "../index-sh3s86na.js";
 import {
   DURABILITY_STEP_EVENT_KIND,
   ParkAbortedError,
@@ -173,9 +173,9 @@ import {
   StepResultDecodeError,
   StepResultNotSerializableError
 } from "../index-79z7m7dt.js";
-import"../index-hmp4800j.js";
-import"../index-khtgb21r.js";
-import"../index-55hkhm67.js";
+import"../index-9t3dffv2.js";
+import"../index-bm5rx7n6.js";
+import"../index-8qt2m66q.js";
 import"../index-zfrhfn82.js";
 import"../index-35mh5bhj.js";
 import {
@@ -186,8 +186,8 @@ import"../index-1zbbzgfh.js";
 import {
   defineRuntimeTool,
   executableAgentRuntimeTools
-} from "../index-xw3s75nj.js";
-import"../index-np4m8hd3.js";
+} from "../index-d8m8zpd8.js";
+import"../index-0r0fbk7z.js";
 import"../index-eqqvgdb3.js";
 import"../index-znfs20ss.js";
 import"../index-p5r7qpdd.js";

package/dist/entrypoints/cli.js

@@ -18,22 +18,22 @@ import {
   readCapped,
   renderCliView,
   routeCliArgv
-} from "../index-f1nb70ae.js";
+} from "../index-r066jx76.js";
 import"../index-sbdmyz75.js";
-import"../index-hmp4800j.js";
+import"../index-9t3dffv2.js";
 import {
   argumentsDigest
 } from "../index-0b1ess5e.js";
-import"../index-khtgb21r.js";
-import"../index-55hkhm67.js";
+import"../index-bm5rx7n6.js";
+import"../index-8qt2m66q.js";
 import"../index-zfrhfn82.js";
 import"../index-35mh5bhj.js";
 import"../index-zcgf3gqf.js";
 import {
   coerceJsonArgs
 } from "../index-1zbbzgfh.js";
-import"../index-xw3s75nj.js";
-import"../index-np4m8hd3.js";
+import"../index-d8m8zpd8.js";
+import"../index-0r0fbk7z.js";
 import"../index-eqqvgdb3.js";
 import"../index-znfs20ss.js";
 import"../index-p5r7qpdd.js";

package/dist/entrypoints/testing.js

@@ -34,7 +34,7 @@ import {
   prepareProjectedMcpTools,
   projectToolSurface,
   staticInputRounds
-} from "../index-np4m8hd3.js";
+} from "../index-0r0fbk7z.js";
 import {
   toJsonSchema
 } from "../index-eqqvgdb3.js";

package/dist/entrypoints/tools/connections.js

@@ -1,10 +1,10 @@
 import {
   defineRuntimeTool
-} from "../../index-xw3s75nj.js";
+} from "../../index-d8m8zpd8.js";
 import {
   declaresDraft07,
   withDefsDialect
-} from "../../index-np4m8hd3.js";
+} from "../../index-0r0fbk7z.js";
 import"../../index-eqqvgdb3.js";
 import"../../index-znfs20ss.js";
 import"../../index-p5r7qpdd.js";

package/dist/entrypoints/tools/invoker.js

@@ -1,13 +1,13 @@
 import {
   createToolInvoker
-} from "../../index-p9sh0xx4.js";
-import"../../index-khtgb21r.js";
-import"../../index-55hkhm67.js";
+} from "../../index-5p2m7we1.js";
+import"../../index-bm5rx7n6.js";
+import"../../index-8qt2m66q.js";
 import"../../index-zfrhfn82.js";
 import"../../index-35mh5bhj.js";
 import"../../index-zcgf3gqf.js";
 import"../../index-1zbbzgfh.js";
-import"../../index-np4m8hd3.js";
+import"../../index-0r0fbk7z.js";
 import"../../index-eqqvgdb3.js";
 import"../../index-znfs20ss.js";
 import"../../index-p5r7qpdd.js";

package/dist/entrypoints/tools.js

@@ -23,7 +23,7 @@ import {
   buildToolManifest,
   describeToolCatalog,
   mountAgent
-} from "../index-863ea9jb.js";
+} from "../index-sh3s86na.js";
 import {
   AgentToolError,
   EffectUnresolvedError,
@@ -52,7 +52,7 @@ import {
 } from "../index-m9zn6cpq.js";
 import {
   createToolInvoker
-} from "../index-p9sh0xx4.js";
+} from "../index-5p2m7we1.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -60,11 +60,11 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "../index-f1nb70ae.js";
+} from "../index-r066jx76.js";
 import"../index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "../index-hmp4800j.js";
+} from "../index-9t3dffv2.js";
 import {
   argumentsDigest
 } from "../index-0b1ess5e.js";
@@ -72,13 +72,13 @@ import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "../index-khtgb21r.js";
+} from "../index-bm5rx7n6.js";
 import {
   ToolExecutionControlError,
   isToolExecutionControlError,
   parseToolCallArguments,
   toolResultFromError
-} from "../index-55hkhm67.js";
+} from "../index-8qt2m66q.js";
 import {
   getRequestContext,
   getTraceId,
@@ -94,7 +94,7 @@ import {
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
-} from "../index-xw3s75nj.js";
+} from "../index-d8m8zpd8.js";
 import {
   PORTABLE_JSON_SCHEMA_FORMATS,
   assertToolName,
@@ -108,7 +108,7 @@ import {
   toolSurfaceOutputSchema,
   validateMcpRoundPolicy,
   validateResolvedInputRounds
-} from "../index-np4m8hd3.js";
+} from "../index-0r0fbk7z.js";
 import {
   toJsonSchema
 } from "../index-eqqvgdb3.js";

package/dist/{index-np4m8hd3.js → index-0r0fbk7z.js}

@@ -271,12 +271,7 @@ function typeNames(schema) {
   return combinedBranchTypes(schema);
 }
 function typeSchema(type, nullable) {
-  const schema = { type: nullable ? [type, "null"] : type };
-  if (type === "array")
-    schema.items = {};
-  if (type === "object")
-    schema.additionalProperties = {};
-  return schema;
+  return { type: nullable ? [type, "null"] : type };
 }
 function commonBaseType(schemas) {
   const names = schemas.map(typeNames);
@@ -296,6 +291,13 @@ function commonBaseType(schemas) {
   }
   if (bases.size === 0)
     return nullable ? { type: "null" } : {};
+  if (bases.has("array") || bases.has("object")) {
+    const alternatives = new Map;
+    for (const schema of schemas)
+      alternatives.set(serializeCanonicalJson(schema), schema);
+    const ordered = [...alternatives].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([, schema]) => schema);
+    return { anyOf: structuredClone(ordered) };
+  }
   if (bases.size === 1) {
     const [only] = bases;
     return only ? typeSchema(only, nullable) : {};
@@ -316,7 +318,7 @@ function mergePropertySchemas(properties) {
   } else {
     const values = schemas.map(stringValues);
     const allStrings = values.every((value) => value !== null);
-    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))] } : commonBaseType(schemas);
+    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))] } : commonBaseType(structural);
   }
   const descriptions = [
     ...new Set(schemas.map((schema) => schema.description).filter((value) => typeof value === "string"))

package/dist/{index-p9sh0xx4.js → index-5p2m7we1.js}

@@ -1,13 +1,13 @@
 import {
   collectTools,
   createToolRunner
-} from "./index-khtgb21r.js";
+} from "./index-bm5rx7n6.js";
 import {
   toolErrorFromResult
-} from "./index-55hkhm67.js";
+} from "./index-8qt2m66q.js";
 import {
   assertUniqueToolName
-} from "./index-np4m8hd3.js";
+} from "./index-0r0fbk7z.js";
 import {
   AppError
 } from "./index-2vtcmrj9.js";

package/dist/{index-55hkhm67.js → index-8qt2m66q.js}

@@ -9,7 +9,7 @@ import {
   applyToolViewDefaults,
   objectShapeKeys,
   projectToolView
-} from "./index-np4m8hd3.js";
+} from "./index-0r0fbk7z.js";
 import {
   normalizeError,
   validateDeclaredOutput

package/dist/{index-hmp4800j.js → index-9t3dffv2.js}

@@ -1,12 +1,12 @@
 import {
   contractToolMountable
-} from "./index-khtgb21r.js";
+} from "./index-bm5rx7n6.js";
 import {
   runtimeToolMountable
-} from "./index-xw3s75nj.js";
+} from "./index-d8m8zpd8.js";
 import {
   projectToolSurface
-} from "./index-np4m8hd3.js";
+} from "./index-0r0fbk7z.js";
 
 // src/tools/surface.ts
 function collectToolSurface({

package/dist/{index-khtgb21r.js → index-bm5rx7n6.js}

@@ -1,13 +1,13 @@
 import {
   executeToolMethod,
   toolErrorFromResult
-} from "./index-55hkhm67.js";
+} from "./index-8qt2m66q.js";
 import {
   assertToolExtensionCompatible,
   mergeSchemas,
   projectToolSurface,
   rebuildObject
-} from "./index-np4m8hd3.js";
+} from "./index-0r0fbk7z.js";
 import {
   isRetryableStatus
 } from "./index-2vtcmrj9.js";

package/dist/{index-xw3s75nj.js → index-d8m8zpd8.js}

@@ -1,6 +1,6 @@
 import {
   projectRuntimeTool
-} from "./index-np4m8hd3.js";
+} from "./index-0r0fbk7z.js";
 
 // src/tools/runtime-tool.ts
 function defineRuntimeTool(definition) {

package/dist/{index-het2he5g.js → index-e4hkgm5t.js}

@@ -22,7 +22,7 @@ import {
 } from "./index-qmy6zq75.js";
 import {
   defineRuntimeTool
-} from "./index-xw3s75nj.js";
+} from "./index-d8m8zpd8.js";
 import {
   conflict,
   forbidden

package/dist/{index-nts4a2br.js → index-jhx828hc.js}

@@ -37,7 +37,7 @@ import {
 import {
   ToolExecutionControlError,
   isToolExecutionControlError
-} from "./index-55hkhm67.js";
+} from "./index-8qt2m66q.js";
 import {
   isRecord,
   transportResult

package/dist/{index-f1nb70ae.js → index-r066jx76.js}

@@ -3,15 +3,15 @@ import {
 } from "./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-hmp4800j.js";
+} from "./index-9t3dffv2.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-khtgb21r.js";
+} from "./index-bm5rx7n6.js";
 import {
   toolErrorFromResult,
   toolResultFromError
-} from "./index-55hkhm67.js";
+} from "./index-8qt2m66q.js";
 import {
   coerceJsonArgs
 } from "./index-1zbbzgfh.js";
@@ -19,7 +19,7 @@ import {
   assertUniqueToolName,
   buildToolPresentationSchema,
   objectShapeKeys
-} from "./index-np4m8hd3.js";
+} from "./index-0r0fbk7z.js";
 import {
   jsonSchemaFields
 } from "./index-eqqvgdb3.js";

package/dist/{index-863ea9jb.js → index-sh3s86na.js}

@@ -4,16 +4,16 @@ import {
 } from "./index-79z7m7dt.js";
 import {
   collectToolSurface
-} from "./index-hmp4800j.js";
+} from "./index-9t3dffv2.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-khtgb21r.js";
+} from "./index-bm5rx7n6.js";
 import {
   isToolExecutionControlError,
   toolCauseFromResult,
   toolResultFromError
-} from "./index-55hkhm67.js";
+} from "./index-8qt2m66q.js";
 import {
   isRecord
 } from "./index-hffjpmq9.js";

package/dist/tools/schema/flatten-join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten-join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,GAAG,IAAI,CAK5E;AA+HD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,sBAAsB,CA4B1F"}
+{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten-join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,GAAG,IAAI,CAK5E;AAuID,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,sBAAsB,CA4B1F"}

package/llms/stitchkit.txt

@@ -77,11 +77,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 43 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 44 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 43 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 44 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -91,7 +91,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 43 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 44 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/tools.txt

@@ -722,14 +722,15 @@ as one thing. Where they agree, that is what you get; where they disagree — a
 `.refine()` only one of them carries, two different bounds on the same number, an
 enum against a free string — the *constraint* is dropped and the **type** is not.
 A field that is a number in every variant is advertised as a number, not as a
-bare description. When the kinds genuinely differ, the flat projection keeps
-every provable kind in a deterministic JSON Schema type array — for example
-`type: ['string', 'array']` — while dropping constraints that are not sound for
-all branches. Nested `oneOf` / `anyOf` values still contribute their provable
-base kinds without reintroducing union keywords. Only a branch whose kind is
+bare description. Scalar collisions keep every provable kind in a deterministic
+JSON Schema type array. If any alternative is an object or array, the property
+retains distinct structural alternatives in `anyOf`: object properties, typed
+array items, bounds and nullable values remain available to the model. The
+containing discriminated union still becomes one object; flat mode does not
+promise to remove every nested union keyword. Only a branch whose kind is
 actually unknowable, such as a free-form schema or unresolved reference, leaves
 the collision unconstrained. → ADRs [0044](../decisions/0044-a-collided-field-keeps-its-type.md)
-and [0065](../decisions/0065-flat-collisions-preserve-every-known-kind.md)
+and [0205](../decisions/0205-flat-tool-collisions-retain-structural-alternatives.md).
 
 It is **deep** because the projection walks the generated JSON Schema document,
 including objects, arrays, tuples and schema-definition nodes. Structurally
@@ -738,8 +739,8 @@ Plain unions and unions hidden behind unresolved external references remain
 unions because Stitchkit cannot soundly invent a discriminator.
 
 Use the default `flattenUnionInput: false` when the model must see the exact
-relationship between a discriminator and each branch. The flat type array is a
-sound set of possible JSON kinds, not a reconstruction of those correlations.
+relationship between a discriminator and each branch. Joined property schemas
+describe allowed values without reconstructing those correlations.
 
 The flattened form is **lossy but never executable**. Per-variant refinements
 and incompatible constraints are widened in the presentation document; the

package/llms/{upgrading-0.72.0-0.98.0.txt → upgrading-0.72.0-0.99.0.txt}

@@ -1,14 +1,43 @@
-# Upgrading 0.72.0 → 0.98.0 — stitchkit docs slice
+# Upgrading 0.72.0 → 0.99.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.72.0 → 0.98.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.72.0 → 0.99.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.72.0 → 0.98.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.72.0 → 0.99.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.99.0
+
+### structural alternatives in flattened tool schemas
+
+**Who must act:** applications using `flattenUnionInput: true` with schema
+walkers, snapshots or provider restrictions that assume there is no nested
+`anyOf`. Applications without that assumption need only update the dependency.
+
+Colliding object/array fields retain their complete structural alternatives:
+
+```ts
+// Before: loses both field vocabulary and array items.
+{ type: ['object', 'array'] }
+// After: structural alternatives live inside the property schema.
+{ anyOf: [
+  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  { type: 'array', items: {
+    type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
+  } },
+] }
+```
+
+Traverse each nested alternative when inspecting schemas and regenerate schema
+snapshots. Verify the actual manifest with the chosen provider. Keep flatten
+enabled when a top-level discriminated union needs to be advertised as an
+object; do not erase `items` or introduce consumer-specific schema patches.
+The root object, discriminator enum, requiredness hints and strict runtime
+contract validation are unchanged. See ADR 0205.
+
 ## Released migration: 0.98.0
 
 ### automatic stdin availability

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.72.0 → 0.98.0: `llms/upgrading-0.72.0-0.98.0.txt`
+- 0.72.0 → 0.99.0: `llms/upgrading-0.72.0-0.99.0.txt`
 - 0.59.0 → 0.71.0: `llms/upgrading-0.59.0-0.71.0.txt`
 - 0.37.0 → 0.58.0: `llms/upgrading-0.37.0-0.58.0.txt`
 

package/llms-full.txt

@@ -68,11 +68,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 43 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 44 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 43 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 44 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -82,7 +82,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 43 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 44 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -3959,14 +3959,15 @@ as one thing. Where they agree, that is what you get; where they disagree — a
 `.refine()` only one of them carries, two different bounds on the same number, an
 enum against a free string — the *constraint* is dropped and the **type** is not.
 A field that is a number in every variant is advertised as a number, not as a
-bare description. When the kinds genuinely differ, the flat projection keeps
-every provable kind in a deterministic JSON Schema type array — for example
-`type: ['string', 'array']` — while dropping constraints that are not sound for
-all branches. Nested `oneOf` / `anyOf` values still contribute their provable
-base kinds without reintroducing union keywords. Only a branch whose kind is
+bare description. Scalar collisions keep every provable kind in a deterministic
+JSON Schema type array. If any alternative is an object or array, the property
+retains distinct structural alternatives in `anyOf`: object properties, typed
+array items, bounds and nullable values remain available to the model. The
+containing discriminated union still becomes one object; flat mode does not
+promise to remove every nested union keyword. Only a branch whose kind is
 actually unknowable, such as a free-form schema or unresolved reference, leaves
 the collision unconstrained. → ADRs [0044](../decisions/0044-a-collided-field-keeps-its-type.md)
-and [0065](../decisions/0065-flat-collisions-preserve-every-known-kind.md)
+and [0205](../decisions/0205-flat-tool-collisions-retain-structural-alternatives.md).
 
 It is **deep** because the projection walks the generated JSON Schema document,
 including objects, arrays, tuples and schema-definition nodes. Structurally
@@ -3975,8 +3976,8 @@ Plain unions and unions hidden behind unresolved external references remain
 unions because Stitchkit cannot soundly invent a discriminator.
 
 Use the default `flattenUnionInput: false` when the model must see the exact
-relationship between a discriminator and each branch. The flat type array is a
-sound set of possible JSON kinds, not a reconstruction of those correlations.
+relationship between a discriminator and each branch. Joined property schemas
+describe allowed values without reconstructing those correlations.
 
 The flattened form is **lossy but never executable**. Per-variant refinements
 and incompatible constraints are widened in the presentation document; the
@@ -13034,6 +13035,35 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.99.0
+
+### structural alternatives in flattened tool schemas
+
+**Who must act:** applications using `flattenUnionInput: true` with schema
+walkers, snapshots or provider restrictions that assume there is no nested
+`anyOf`. Applications without that assumption need only update the dependency.
+
+Colliding object/array fields retain their complete structural alternatives:
+
+```ts
+// Before: loses both field vocabulary and array items.
+{ type: ['object', 'array'] }
+// After: structural alternatives live inside the property schema.
+{ anyOf: [
+  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  { type: 'array', items: {
+    type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
+  } },
+] }
+```
+
+Traverse each nested alternative when inspecting schemas and regenerate schema
+snapshots. Verify the actual manifest with the chosen provider. Keep flatten
+enabled when a top-level discriminated union needs to be advertised as an
+object; do not erase `items` or introduce consumer-specific schema patches.
+The root object, discriminator enum, requiredness hints and strict runtime
+contract validation are unchanged. See ADR 0205.
+
 ## Released migration: 0.98.0
 
 ### automatic stdin availability

package/llms.txt

@@ -12,7 +12,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 44.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.1 KB
@@ -52,7 +52,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.72.0 → 0.98.0**: [llms/upgrading-0.72.0-0.98.0.txt](llms/upgrading-0.72.0-0.98.0.txt) 44.8 KB
+- **Upgrading 0.72.0 → 0.99.0**: [llms/upgrading-0.72.0-0.99.0.txt](llms/upgrading-0.72.0-0.99.0.txt) 46.0 KB
 - **Upgrading 0.59.0 → 0.71.0**: [llms/upgrading-0.59.0-0.71.0.txt](llms/upgrading-0.59.0-0.71.0.txt) 45.6 KB
 - **Upgrading 0.37.0 → 0.58.0**: [llms/upgrading-0.37.0-0.58.0.txt](llms/upgrading-0.37.0-0.58.0.txt) 40.0 KB
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.98.2",
+  "version": "0.99.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",