@ai-matrx/content-ir 0.9.0 → 0.10.0

package/dist/core.d.cts

@@ -0,0 +1,370 @@
+import { g as IrResidue, d as IrDiscriminator, C as CanonicalBlockIR } from './ir-types-95bA2cXH.cjs';
+export { a as CanonicalContent, b as CanonicalSegment, I as IR_ENVELOPE_KEY, c as IR_VERSION, e as IrKindState, f as IrPath, h as IrStructuredNode, i as irPathIsUnderOrEqual, j as irPathKey, k as irPathLabel, l as irPathsEqual, m as isEmptyResidue } from './ir-types-95bA2cXH.cjs';
+import { S as SchemaResolver } from './ir-tree-DbLVxbf1.cjs';
+export { I as IrTree, a as IrTreeNode, J as JsonPath, K as KindStreamEvent, b as KindStreamParser, c as KindStreamParserOptions, R as RawObjectCause, d as createKindStreamParser, s as setJsonRootKeyLookup } from './ir-tree-DbLVxbf1.cjs';
+import { a as KindSchema, F as FieldSchema } from './kind-schema.types-CwncWj9U.cjs';
+export { A as ArrayItemScalarType, K as KIND_KEY, R as RecordValueType, S as ScalarFieldType, i as isJsonAnyField, b as isScalarArrayType, r as readObjectKind, s as scalarArrayItemType } from './kind-schema.types-CwncWj9U.cjs';
+
+/**
+ * Character-level incremental JSON tokenizer. Survives chunk boundaries
+ * mid-token (strings, escapes, unicode sequences, primitives). Pure — no
+ * React, no Redux, no IO.
+ *
+ * Moved from app/(dev)/demos/json-block-detector/reusable-logic.ts (the demo
+ * is now a consumer of this library).
+ */
+type Punct = "{" | "}" | "[" | "]" | ":" | ",";
+type JsonToken = {
+    type: "punct";
+    value: Punct;
+    at: number;
+} | {
+    type: "string";
+    value: string;
+    at: number;
+} | {
+    type: "number";
+    value: number;
+    at: number;
+} | {
+    type: "boolean";
+    value: boolean;
+    at: number;
+} | {
+    type: "null";
+    value: null;
+    at: number;
+};
+declare class JsonStreamTokenizer {
+    private mode;
+    private pos;
+    private stringBuffer;
+    private primitiveBuffer;
+    private unicodeBuffer;
+    private tokenStart;
+    private readonly onToken;
+    constructor(onToken: (token: JsonToken) => void);
+    get position(): number;
+    push(chunk: string): void;
+    end(): void;
+    private handleNormalChar;
+    private emitPrimitive;
+    private isDelimiter;
+}
+
+/**
+ * Compliant snapshot builder — the guarantee that a renderer always receives
+ * a well-formed, schema-shaped object even mid-stream.
+ *
+ * ZERO DATA LOSS: unknown keys are NOT merged into the snapshot value (they
+ * would be indistinguishable from schema fields). They are returned on the
+ * residue channel and re-merged only at wire-serialization time via
+ * `mergeResidueIntoValue`.
+ */
+
+/** Placeholder for a required field not yet received during streaming. */
+declare function emptyValueForFieldSchema(field: FieldSchema): unknown;
+interface CompliantKindSnapshot {
+    /** Schema fields + __kind only. Required-but-missing fields hold typed placeholders. */
+    value: Record<string, unknown>;
+    /** Unknown keys + missing optionals. Null when both channels are empty. */
+    residue: IrResidue | null;
+}
+declare function buildCompliantKindSnapshot(schema: KindSchema, partial: Record<string, unknown>): CompliantKindSnapshot;
+/**
+ * Wire/round-trip form: schema fields + unknown keys back together, exactly
+ * as the source carried them. `residue.extra` wins nothing — snapshot value
+ * and extras are disjoint by construction.
+ */
+declare function mergeResidueIntoValue(value: Record<string, unknown>, residue: IrResidue | null): Record<string, unknown>;
+
+/**
+ * Idempotent normalizer — the "recognizes its own work" property.
+ *
+ * THE LAW: anything already carrying a current CanonicalBlockIR envelope is
+ * returned BY REFERENCE — zero reprocessing, reference equality holds, React
+ * bails out. Only raw text (a detected region's source) is ever parsed, and
+ * it is parsed exactly once per fingerprint.
+ *
+ * `normalizeJsonRegion` is the one-shot mode: the same KindStreamParser that
+ * powers live streams, run over a complete region string (DB reloads,
+ * reconcile passes), assembled through the same IrTree the live session uses
+ * — stream and static output are structurally identical by construction.
+ */
+
+declare function isCanonicalBlockIR(value: unknown): value is CanonicalBlockIR;
+/**
+ * The idempotence fast path: return the existing envelope by reference when
+ * it still describes this source text; null means "parse needed".
+ */
+declare function reuseEnvelopeIfCurrent(source: string, candidate: unknown): CanonicalBlockIR | null;
+interface NormalizeJsonRegionOptions {
+    schemas: Record<string, KindSchema> | SchemaResolver;
+    /** Known-context root prediction (agent output schema, fence hint). */
+    expectedRootKind?: string;
+    /**
+     * Pass a previously persisted envelope (message metadata, artifact row);
+     * when its fingerprint matches, it is returned as-is and nothing parses.
+     */
+    existing?: unknown;
+}
+interface CompleteValueEnvelopeOptions {
+    /**
+     * Wire discriminator recorded on the root node — which syntax established
+     * the kind. Defaults to the JSON `__kind` key; XML surfaces converging at
+     * region finalize pass `xmlDiscriminator(tag)` so round-trip serializers
+     * know the original arrival format.
+     */
+    discriminator?: IrDiscriminator;
+}
+/**
+ * Build a resolved, complete envelope directly from an already-structured
+ * value (a persisted artifact's `content.data` object, or a completed XML
+ * region's strategy output). This is the zero-reprocessing rehydration path:
+ * the value IS the reconstructed region value (schema fields + residue extras
+ * merged at persist time), so no tokenizer/parser run is needed — the
+ * envelope wraps it verbatim. The fingerprint hashes the canonical value
+ * serialization, so any two paths producing the same value produce the SAME
+ * envelope (stream ≡ static by construction).
+ */
+declare function envelopeFromCompleteValue(value: Record<string, unknown>, kind: string, options?: CompleteValueEnvelopeOptions): CanonicalBlockIR;
+/** One-shot: complete region text in → canonical envelope out. */
+declare function normalizeJsonRegion(source: string, options: NormalizeJsonRegionOptions): CanonicalBlockIR;
+
+/**
+ * Stable, fast content fingerprint for IR envelopes.
+ *
+ * Used as the idempotence / cache key: a persisted CanonicalBlockIR is only
+ * reused when its fingerprint matches the region source text it claims to
+ * represent. Not cryptographic — collision resistance at the "same message,
+ * same block" scale is all that's required, and it must be synchronous and
+ * dependency-free (runs per region on the hot streaming path).
+ *
+ * FNV-1a 32-bit, applied twice with different seeds and concatenated, so a
+ * single 32-bit collision doesn't alias two regions.
+ *
+ * `createFingerprinter` is the incremental form for live streams: feeding
+ * chunks one at a time yields EXACTLY the same fingerprint as
+ * `fingerprintText` over the concatenation — sessions never re-hash the
+ * whole source per flush.
+ */
+interface Fingerprinter {
+    push(chunk: string): void;
+    /** Fingerprint of everything pushed so far. */
+    current(): string;
+}
+declare function createFingerprinter(): Fingerprinter;
+declare function fingerprintText(source: string): string;
+
+/**
+ * Discriminator abstraction — how a node's kind is established from the wire.
+ *
+ * The parser never hardcodes "kind comes from a JSON key". JSON resolves via
+ * the `__kind` field (implemented today); XML resolves via tag → registry
+ * alias (Phase 6 — contract only). `IrStructuredNode.discriminator` records
+ * which resolver produced each node so renderers and round-trip serializers
+ * can reconstruct the original wire format per node.
+ */
+
+declare const JSON_DISCRIMINATOR: IrDiscriminator;
+declare function xmlDiscriminator(tag: string): IrDiscriminator;
+declare function fenceDiscriminator(language: string): IrDiscriminator;
+/** What a resolver can say about an opening compound value. */
+type KindResolution = {
+    outcome: "kind";
+    kind: string;
+} | {
+    outcome: "pending";
+} | {
+    outcome: "raw";
+    reason: string;
+};
+
+/**
+ * IrEnvelopeCache — the persisted envelope cache carried on MESSAGE PARTS.
+ *
+ * Phase 5 (reload without re-parse): at stream end, `assembleMessageParts`
+ * stamps every completed JSON region's CanonicalBlockIR onto the committed
+ * `CxTextContent.metadata.__ir` as this cache — keyed by fingerprint, because
+ * one text part can embed several regions. On reload the splitter's envelope
+ * memo consults the seeded cache (`registry/region-envelope-memo.ts`) and
+ * reuses the persisted envelope BY REFERENCE via `reuseEnvelopeIfCurrent`
+ * (exact fingerprint match of the detected region source) — zero re-parse.
+ *
+ * Shape discipline: the SAME `__ir` metadata key carries two shapes at two
+ * levels, disambiguated by validators that reject each other —
+ *   - render block metadata → a single CanonicalBlockIR (`isCanonicalBlockIR`)
+ *   - message part metadata → this cache (`isIrEnvelopeCache`)
+ *
+ * Pure kernel module: types + validators only. No React/Redux/Supabase.
+ */
+
+/** Cache version. Bump = migration point for persisted part caches. */
+declare const IR_ENVELOPE_CACHE_VERSION: 1;
+/**
+ * The envelope cache persisted on a message part's `metadata.__ir`.
+ * `blocks` maps each region-source fingerprint to its complete envelope.
+ */
+interface IrEnvelopeCache {
+    v: typeof IR_ENVELOPE_CACHE_VERSION;
+    blocks: Record<string, CanonicalBlockIR>;
+}
+/**
+ * Strict whole-cache validation: every entry must be a complete
+ * CanonicalBlockIR keyed by its OWN fingerprint. A cache failing this guard
+ * came from a buggy or foreign writer — callers surface that loudly and seed
+ * nothing (a half-trusted cache is how poisoned envelopes reach renderers).
+ */
+declare function isIrEnvelopeCache(value: unknown): value is IrEnvelopeCache;
+/**
+ * Build the persistable cache from a run's collected envelopes. Only
+ * complete envelopes are cacheable (a streaming/error envelope can never be
+ * reused — its fingerprint doesn't describe a finished region). Duplicate
+ * regions (same fingerprint) collapse to one entry. Engine-agnostic by
+ * design: an aidream-built `engine: "py-block-detector"` envelope is cached
+ * identically to an FE-parsed one. Returns null when nothing qualifies so
+ * callers skip the metadata stamp entirely.
+ */
+declare function envelopeCacheFromEnvelopes(envelopes: readonly CanonicalBlockIR[]): IrEnvelopeCache | null;
+
+/**
+ * PURE envelope ingestion — reading `metadata.__ir` off a block's metadata
+ * and gating SERVER-BUILT envelopes at the wire boundary. Twin-safe: no
+ * React / Redux / Supabase / host diagnostics — side effects (seeding the
+ * region-envelope memo, screaming to the Error Inspector) are injected by
+ * the host through `InboundEnvelopeHooks`.
+ *
+ * The frontend host shell is `redux/render-block-envelope.ts` (binds the
+ * hooks to `seedEnvelope` + `captureError`); aidream's Workflow Studio binds
+ * its own. Contract: /Users/armanisadeghi/code/common-docs/systems/content-ir-system/PYTHON_ENVELOPE_CONTRACT.md.
+ */
+
+/** Read a CanonicalBlockIR envelope off a block's metadata (or anything). */
+declare function readEnvelope(metadata: Record<string, unknown> | null | undefined): CanonicalBlockIR | null;
+/** Pure classification of inbound metadata carrying (or not) an envelope. */
+type InboundEnvelopeVerdict = {
+    /** No `__ir` key — zero-touch pass, same reference back. */
+    outcome: "absent";
+    metadata: Record<string, unknown> | undefined;
+} | {
+    /** Valid CanonicalBlockIR — same reference back (idempotence law). */
+    outcome: "valid";
+    metadata: Record<string, unknown>;
+    envelope: CanonicalBlockIR;
+} | {
+    /** Malformed/foreign `__ir` — a COPY with `__ir` stripped. */
+    outcome: "malformed";
+    metadata: Record<string, unknown>;
+    engine: string;
+    raw: unknown;
+};
+declare function classifyInboundEnvelopeMetadata(metadata: Record<string, unknown> | null | undefined): InboundEnvelopeVerdict;
+/** Host-injected side effects for the inbound gate. */
+interface InboundEnvelopeHooks {
+    /** Called with every VALID envelope so later re-splits reuse it by reference. */
+    seedEnvelope?: (envelope: CanonicalBlockIR) => void;
+    /** Called LOUDLY for every malformed envelope — a bad envelope is a defect. */
+    reportMalformed?: (info: {
+        blockId: string;
+        engine: string;
+        raw: unknown;
+    }) => void;
+}
+/**
+ * Ingest guard for SERVER-BUILT envelopes riding `metadata.__ir` on a
+ * `render_block` event.
+ *
+ * - No `__ir` key → the SAME metadata reference back (zero-touch pass).
+ * - Valid CanonicalBlockIR → the SAME metadata reference back (reuse-by-
+ *   reference — the idempotence law) AND `hooks.seedEnvelope` fires so any
+ *   later re-split of the same region source reuses it instead of parsing.
+ * - Malformed/foreign `__ir` → a COPY with `__ir` stripped, plus a loud
+ *   `hooks.reportMalformed`. A bad envelope must never poison kind routing
+ *   or the persistence cache; dropping it degrades that block to the
+ *   ordinary content-driven path, nothing more.
+ */
+declare function sanitizeInboundEnvelopeMetadata(metadata: Record<string, unknown> | null | undefined, context: {
+    blockId: string;
+}, hooks?: InboundEnvelopeHooks): Record<string, unknown> | undefined;
+
+/**
+ * Pure envelope→value functions (the zero-data-loss wire round-trip).
+ *
+ * These live in core/ (the pure kernel) because every layer needs them —
+ * including kinds/legacy-bridge-utils, whose bridges are built at MODULE
+ * SCOPE inside kinds/<slug>.ts files that system-kinds.ts imports. When these
+ * functions lived in redux/render-block-envelope.ts, that file's memo/capture
+ * imports closed a module cycle (kinds → bridge-utils → render-block-envelope
+ * → region-envelope-memo → kind-registry → system-kinds → kinds), which made
+ * SYSTEM_KIND_DEFINITIONS entry-point-fragile (undefined defs when a kinds
+ * module was the import entry). Keeping them here makes every kinds module
+ * cycle-free BY CONSTRUCTION. redux/render-block-envelope re-exports them for
+ * its existing consumers.
+ */
+
+/**
+ * Rebuild the region's full data: walk the root value and merge each node's
+ * residue extras back in (root residue + nodeIndex residues). This is the
+ * zero-data-loss read: nothing the model emitted is missing, whether or not
+ * a schema knew about it.
+ */
+declare function reconstructRegionValue(envelope: CanonicalBlockIR): Record<string, unknown>;
+/**
+ * Deep-remove the `__kind` discriminator.
+ *
+ * 🚨 NOT A TRANSFORM FOR PLATFORM DATA. `__kind` is part of the data
+ * (KINDS_EVERYWHERE_PLAN §4.2) and stripping it from anything stored, passed or
+ * rendered was annihilated on 2026-08-23. This helper survives for exactly two
+ * shapes of caller, both of which are guarded:
+ *   - a SYMMETRIC COMPARISON that reduces both sides and returns a boolean;
+ *   - legacy validation TOLERANCE against a pre-2026-08-23 schema version.
+ * Guards: aidream `scripts/check_kind_marker_law.py`,
+ * matrx-frontend `pnpm check:kind-marker-law`.
+ */
+declare function stripKindDeep(value: unknown): unknown;
+
+/**
+ * ContentRegion — the handshake between a host detector and this library.
+ *
+ * Boundary rule (the answer to the single-root problem): the HOST detector
+ * (StreamBlockAccumulator on streams, content-splitter-v2 on DB loads) finds
+ * where a structured region begins and ends inside prose; the kind parser
+ * owns everything INSIDE the region. A fresh parser is created per region, so
+ * "one root object" is true within a region by construction, and multiple
+ * blocks per message are just multiple regions.
+ *
+ * Through Phase 6 the host's fence-close / brace-count logic remains the
+ * region-end oracle (bit-level parity with today). In Phase 7 the parser's
+ * own frame stack becomes the oracle and the mirrored counters are deleted.
+ */
+type RegionFormat = "json";
+type RegionSourceKind = "fence" | "bare";
+interface ContentRegionInit {
+    regionId: string;
+    format: RegionFormat;
+    sourceKind: RegionSourceKind;
+}
+/** How a region ended. Truncation is a normal outcome, never stream-fatal. */
+type RegionEndReason = "closed" | "truncated" | "aborted";
+
+/**
+ * Schema-shape helpers — structural depth and layout hints derived from a
+ * KindSchema. Drives the generic renderer's flat / grid / nested layout and
+ * human labels for slugs.
+ *
+ * Moved from app/(dev)/demos/json-block-detector/schema-structure.ts.
+ */
+
+/** Human label from a slug or field key (snake_case → Title Case + acronym fixes). */
+declare function formatBlockLabel(key: string): string;
+/**
+ * Structural nesting depth of a kind schema — drives generic renderer layout.
+ * 0 = flat card (scalars only)
+ * 1 = grid (one array/object nesting level)
+ * 2+ = expandable grid (parent → child → grandchild)
+ */
+declare function schemaStructureDepth(schema: KindSchema, allSchemas: Record<string, KindSchema>, visiting?: Set<string>): number;
+type SchemaLayoutMode = "flat" | "grid" | "nested";
+declare function schemaLayoutMode(schema: KindSchema, allSchemas: Record<string, KindSchema>): SchemaLayoutMode;
+
+export { CanonicalBlockIR, type CompleteValueEnvelopeOptions, type CompliantKindSnapshot, type ContentRegionInit, FieldSchema, type Fingerprinter, IR_ENVELOPE_CACHE_VERSION, type InboundEnvelopeHooks, type InboundEnvelopeVerdict, IrDiscriminator, type IrEnvelopeCache, IrResidue, JSON_DISCRIMINATOR, JsonStreamTokenizer, type JsonToken, type KindResolution, KindSchema, type NormalizeJsonRegionOptions, type Punct, type RegionEndReason, type RegionFormat, type RegionSourceKind, type SchemaLayoutMode, SchemaResolver, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, createFingerprinter, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fingerprintText, formatBlockLabel, isCanonicalBlockIR, isIrEnvelopeCache, mergeResidueIntoValue, normalizeJsonRegion, readEnvelope, reconstructRegionValue, reuseEnvelopeIfCurrent, sanitizeInboundEnvelopeMetadata, schemaLayoutMode, schemaStructureDepth, stripKindDeep, xmlDiscriminator };