@ai-matrx/content-ir 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.10.0 — 2026-08-30
+
+**Non-breaking.** Every existing `@ai-matrx/content-ir` import keeps working
+unchanged — the root export is still the FULL surface. What is new is that the
+package's four clean internal areas are now addressable directly.
+
+- **Five new subpath exports — `/core`, `/session`, `/registry`, `/convert`,
+  `/wire`.** Each is a real build entry (dual ESM + CJS with matching
+  `.d.ts`/`.d.cts`), so a consumer that only reads wire contracts no longer
+  pulls the streaming parser — or `ajv`, which rides `/registry` and
+  `/convert` — into its graph. `.` re-exports all five, so nothing that
+  imports the root changes.
+
+  | Subpath | What it holds |
+  |---|---|
+  | `/core` | IR types + tree, JSON tokenizer, kind parser, snapshots, normalize, fingerprint, discriminator, envelope read/value/cache, region, schema structure |
+  | `/session` | `ParseSession`, `openParseSession` / `getParseSession` / `disposeParseSession` |
+  | `/registry` | kind registry types, storage transform, the dual gate |
+  | `/convert` | kind ⇄ JSON Schema, the OpenAI structured-output converter |
+  | `/wire` | partial-kind events, runtime wrapper readers, emit payload |
+
+- **Fixed: the parse-session registry could silently SPLIT across module
+  graphs.** `session/session-manager.ts` held its `Map` in a module-level
+  variable. The package builds `splitting: false` in dual ESM/CJS format, so
+  that module is duplicated into every bundle that reaches it — and with the
+  new `/session` subpath, a host importing the root and the subpath would have
+  gotten TWO registries: "one writer per stream identity" would stop being
+  enforced across them and a second writer would open cleanly onto a live
+  stream. The registry now lives on `globalThis` under
+  `Symbol.for("ai-matrx.content-ir.parse-sessions")`. The tarball canary
+  proves the slot across BOTH loaders by opening a session through `/session`
+  and resolving it through the root; the guard was verified failing against
+  the old module-level form before this release.
+
+- **Contract locked: `expectedRootKind` is a PREDICTION, never a free pass.**
+  Three new tests pin the behavior that was already correct but untested —
+  a payload predicted into a kind whose required field is missing degrades to
+  `kindState: "raw"` carrying a `raw_fallback` notice naming the field; a
+  valid payload still promotes to `resolved`. No behavior changed.
+
+### Consumer action (C28)
+
+Nothing is required — this release is non-breaking and the root export is
+unchanged. Two things are worth doing at your next working session:
+
+1. **Prefer the area subpath over the root for new and touched imports**
+   (`@ai-matrx/content-ir/wire` instead of `@ai-matrx/content-ir` when you
+   only read wire contracts, and so on). Root stays supported indefinitely;
+   the subpaths are the preferred imports because they keep the parser and
+   `ajv` out of graphs that do not need them.
+
+2. **🚨 Audit every place you gate a typed path on `envelope.root.kind`.**
+   `kind` is PRESERVED on failure by design (KIND PRESERVATION, 0.x
+   2026-08-29): a payload that fails its schema stays a *broken*
+   `flashcard_set` rather than becoming an anonymous object. `status` says
+   only that parsing finished. **`kindState` is the validity signal** —
+   `"resolved"` is the only state a typed consumer may act on
+   (`"unverified"` means no schema existed and still routes to a component;
+   `"raw"` means checked and failed). A guard written as
+   `if (root.kind !== "x" || root.status !== "complete") return null` reads a
+   degraded root as a good one. Found in matrx-frontend's
+   `generatedSetFromEnvelope` and fixed in the same session as this release.
+
 ## 0.9.0 — 2026-08-29
 
 - **A nested `__kind` object now registers the CHILD's schema, not just a ref

package/README.md

@@ -6,20 +6,39 @@ The framework-independent Content IR kernel used by AI Matrx applications. It pa
 pnpm add @ai-matrx/content-ir
 ```
 
+## Entry points
+
+The root export is the full surface and always will be. Since 0.10.0 each internal area is also addressable on its own — prefer these, so a consumer that only reads wire contracts never pulls the parser (or `ajv`) into its graph.
+
+| Import | What it holds |
+|---|---|
+| `@ai-matrx/content-ir` | everything below |
+| `@ai-matrx/content-ir/core` | IR types + tree, JSON tokenizer, kind parser, snapshots, normalize, fingerprint, discriminator, envelope read/value/cache, region, schema structure |
+| `@ai-matrx/content-ir/session` | `ParseSession` and the one-writer-per-identity registry |
+| `@ai-matrx/content-ir/registry` | kind registry types, storage transform, the dual gate |
+| `@ai-matrx/content-ir/convert` | kind ⇄ JSON Schema, the OpenAI structured-output converter |
+| `@ai-matrx/content-ir/wire` | partial-kind events, runtime wrapper readers, emit payload |
+
 ```ts
+import { createKindStreamParser, envelopeFromCompleteValue } from "@ai-matrx/content-ir/core";
+import { validateStructuralLeg } from "@ai-matrx/content-ir/registry";
 import {
-  createKindStreamParser,
-  envelopeFromCompleteValue,
-  validateStructuralLeg,
-  // wire layer (0.2.0): streaming partial kinds + runtime wrappers + emit payload
   readPartialKindEvent,
   makePartialKindStalenessGate,
   rehydrateNodeOutcome,
   rehydrateRunResult,
   withRootKind,
-} from "@ai-matrx/content-ir";
+} from "@ai-matrx/content-ir/wire";
 ```
 
+## Reading an envelope: `kindState`, never `kind` alone
+
+`root.kind` is **preserved** when a payload fails its schema — a broken `flashcard_set` stays a `flashcard_set` so you can say what broke. `root.status` reports only that parsing finished. The validity signal is `root.kindState`:
+
+- `"resolved"` — the only state a typed consumer may act on.
+- `"unverified"` — the kind has no registered schema, so nothing was ever checked; it still routes to its component.
+- `"raw"` / `"pending_*"` / `"speculative"` — do not consume as typed data.
+
 The package has no browser, React runtime, application store, database client, routing, or renderer dependency. `ajv` is its only runtime dependency. Host-specific registry fetching, component compilation, rendering, and error capture remain adapters around this kernel.
 
 ## Release gate