@ai-matrx/content-ir

The framework-independent Content IR kernel used by AI Matrx applications. It parses streamed or complete structured content into canonical envelopes, manages incremental parse sessions, converts kind schemas, and performs structural validation.

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 |

import { createKindStreamParser, envelopeFromCompleteValue } from "@ai-matrx/content-ir/core";
import { validateStructuralLeg } from "@ai-matrx/content-ir/registry";
import {
  readPartialKindEvent,
  makePartialKindStalenessGate,
  rehydrateNodeOutcome,
  rehydrateRunResult,
  withRootKind,
} 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

pnpm --filter @ai-matrx/content-ir typecheck
pnpm --filter @ai-matrx/content-ir test
pnpm --filter @ai-matrx/content-ir check:package

The gate runs the parser's shared fixtures and parity vectors, validates the packed declarations and exports, installs the tarball in an empty project, and imports the public API.