@ai-matrx/content-ir 0.9.0 → 0.10.0

package/dist/session.js

@@ -0,0 +1,2047 @@
+// core/kind-schema.types.ts
+var KIND_KEY = "__kind";
+function readObjectKind(value) {
+  const kind = value[KIND_KEY];
+  return typeof kind === "string" ? kind : null;
+}
+function isScalarArrayType(type) {
+  return type === "string[]" || type === "number[]" || type === "boolean[]";
+}
+function scalarArrayItemType(type) {
+  if (type === "number[]") return "number";
+  if (type === "boolean[]") return "boolean";
+  return "string";
+}
+function isJsonAnyField(field) {
+  return field.type === "json" || field.type === "json[]";
+}
+
+// core/discriminator.ts
+var JSON_DISCRIMINATOR = {
+  format: "json",
+  key: KIND_KEY
+};
+
+// core/ir-types.ts
+var IR_VERSION = 1;
+function irPathKey(path) {
+  return path.map((segment) => String(segment)).join(".");
+}
+function isEmptyResidue(residue) {
+  return (residue.extra === null || Object.keys(residue.extra).length === 0) && (residue.optionalMissing === null || residue.optionalMissing.length === 0) && (residue.notices === null || residue.notices.length === 0);
+}
+
+// core/ir-tree.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeWithoutLoss(prior, incoming) {
+  if (!isRecord(prior)) return { value: incoming, rescued: [] };
+  if (!isRecord(incoming)) {
+    if (incoming !== null && incoming !== void 0) {
+      return { value: incoming, rescued: [] };
+    }
+    return { value: prior, rescued: Object.keys(prior) };
+  }
+  const rescued = Object.keys(prior).filter((key) => !(key in incoming));
+  if (rescued.length === 0) return { value: incoming, rescued };
+  return { value: { ...prior, ...incoming }, rescued };
+}
+var IrTree = class {
+  nodes = /* @__PURE__ */ new Map();
+  rawPaths = /* @__PURE__ */ new Map();
+  // pathKey → reason
+  dirty = /* @__PURE__ */ new Set();
+  /**
+   * KIND PRESERVATION (streaming db/cloud kinds): pathKey → identified kind
+   * for nodes whose kind is KNOWN (kind_identified / pending_schema) but that
+   * have no snapshot node yet because the schema is still cold-fetching.
+   * Without this, the envelope reports `kind: ""` for the whole pending
+   * window and the render seam can only show raw JSON.
+   */
+  identifiedKinds = /* @__PURE__ */ new Map();
+  /** pathKeys currently waiting on a schema cold fetch. */
+  pendingSchemaPaths = /* @__PURE__ */ new Set();
+  /**
+   * Early top-level scalar fields (title, loading_message, …) captured for
+   * identified-but-schema-pending nodes — the loading-component fuel. Scalars
+   * only (no live parser references can escape through here). Superseded the
+   * moment a real snapshot node exists.
+   */
+  earlyFields = /* @__PURE__ */ new Map();
+  /**
+   * pathKey → identified kind preserved through a raw fallback (parser stamped
+   * `kind` on the raw_object event) — schema-availability degrades and, since
+   * 2026-08-29, structural ones too. Only a node nothing ever identified (no
+   * `__kind` at all) is absent here.
+   */
+  rawKinds = /* @__PURE__ */ new Map();
+  /**
+   * pathKey → WHY the node degraded. `"unverified"` means no schema was
+   * available and nothing was ever checked; `"invalid"` means a check ran and
+   * failed. THE RENDER ROUTE BRANCHES ON THIS — see `IrKindState`. Absent =
+   * `"invalid"`, so a parser that predates the `cause` field (or any consumer
+   * hand-building events) keeps the strict, safe reading.
+   */
+  rawCauses = /* @__PURE__ */ new Map();
+  regionStatus = "streaming";
+  errorReason = null;
+  rootRawValue = null;
+  /** Notices for degrades that tried to erase already-published data. */
+  rescueNotices = [];
+  completedKind = "";
+  get status() {
+    return this.regionStatus;
+  }
+  applyEvent(event) {
+    switch (event.type) {
+      case "kind_identified": {
+        this.identifiedKinds.set(irPathKey(event.path), event.kind);
+        this.dirty.add(irPathKey(event.path));
+        return;
+      }
+      case "pending_schema": {
+        const pathKey = irPathKey(event.path);
+        this.identifiedKinds.set(pathKey, event.kind);
+        this.pendingSchemaPaths.add(pathKey);
+        this.dirty.add(pathKey);
+        return;
+      }
+      case "field": {
+        const parentKey = irPathKey(event.path.slice(0, -1));
+        if (this.nodes.has(parentKey)) return;
+        if (!this.identifiedKinds.has(parentKey)) return;
+        const v = event.value;
+        if (v !== null && typeof v === "object") return;
+        const bucket = this.earlyFields.get(parentKey) ?? {};
+        bucket[event.key] = v;
+        this.earlyFields.set(parentKey, bucket);
+        this.dirty.add(parentKey);
+        return;
+      }
+      case "block_snapshot": {
+        const pathKey = irPathKey(event.path);
+        this.pendingSchemaPaths.delete(pathKey);
+        this.earlyFields.delete(pathKey);
+        this.upsertNode(event.path, {
+          kind: event.kind,
+          value: event.value,
+          residue: event.residue,
+          complete: event.complete
+        });
+        return;
+      }
+      case "raw_object": {
+        const pathKey = irPathKey(event.path);
+        this.pendingSchemaPaths.delete(pathKey);
+        this.earlyFields.delete(pathKey);
+        if (event.kind) this.rawKinds.set(pathKey, event.kind);
+        this.rawCauses.set(pathKey, event.cause ?? "invalid");
+        this.markRaw(event.path, event.reason, event.value);
+        return;
+      }
+      case "complete": {
+        this.regionStatus = this.errorReason ? "error" : "complete";
+        this.completedKind = event.kind;
+        if (this.rawPaths.has("") && isRecord(event.value)) {
+          const merged = mergeWithoutLoss(this.rootRawValue, event.value);
+          this.recordRescue("", "complete", merged.rescued);
+          if (isRecord(merged.value)) this.rootRawValue = merged.value;
+        }
+        this.dirty.add("");
+        return;
+      }
+      case "error": {
+        this.errorReason = event.reason;
+        this.regionStatus = "error";
+        this.dirty.add("");
+        return;
+      }
+      default:
+        return;
+    }
+  }
+  getNode(pathKey) {
+    return this.nodes.get(pathKey) ?? null;
+  }
+  listNodes() {
+    return [...this.nodes.values()];
+  }
+  isRawPath(pathKey) {
+    return this.rawPaths.has(pathKey);
+  }
+  /** Dirty pathKeys since the last drain — the flush/notify unit. */
+  drainDirty() {
+    const drained = [...this.dirty];
+    this.dirty.clear();
+    return drained;
+  }
+  hasDirty() {
+    return this.dirty.size > 0;
+  }
+  // -------------------------------------------------------------------------
+  upsertNode(path, payload) {
+    const pathKey = irPathKey(path);
+    if (this.rawPaths.has(pathKey)) return;
+    const stabilized = this.stabilizeValue(
+      payload.value,
+      path,
+      pathKey
+    );
+    const prior = this.nodes.get(pathKey);
+    const node = {
+      kind: payload.kind,
+      kindState: payload.complete ? "resolved" : prior?.kindState ?? "resolved",
+      path,
+      pathKey,
+      value: stabilized,
+      residue: payload.residue,
+      complete: payload.complete,
+      version: (prior?.version ?? 0) + 1
+    };
+    this.nodes.set(pathKey, node);
+    this.dirty.add(pathKey);
+    this.propagateToAncestors(path, node.value);
+  }
+  /**
+   * Substitute kind-node children with their current tree values so sibling
+   * identities are stable; deep-copy everything else so no live parser
+   * reference ever escapes.
+   */
+  stabilizeValue(value, path, applyingPathKey) {
+    if (Array.isArray(value)) {
+      return value.map(
+        (item, index) => this.stabilizeValue(item, [...path, index], applyingPathKey)
+      );
+    }
+    if (isRecord(value)) {
+      const pathKey = irPathKey(path);
+      if (pathKey !== applyingPathKey) {
+        const childNode = this.nodes.get(pathKey);
+        if (childNode) return childNode.value;
+      }
+      const out = {};
+      for (const [key, child] of Object.entries(value)) {
+        out[key] = this.stabilizeValue(child, [...path, key], applyingPathKey);
+      }
+      return out;
+    }
+    return value;
+  }
+  /**
+   * COW spine rebuild: replace the child's slot in each ancestor kind-node's
+   * value, shallow-copying only the containers along the way. Siblings keep
+   * identity; every ancestor gets a new value identity + version bump.
+   */
+  propagateToAncestors(childPath, childValue) {
+    let currentPath = childPath;
+    let currentValue = childValue;
+    while (currentPath.length > 0) {
+      const ancestor = this.findNearestAncestorNode(currentPath);
+      if (!ancestor) return;
+      const relative = currentPath.slice(ancestor.path.length);
+      const rebuilt = this.cloneAlong(ancestor.value, relative, currentValue);
+      if (rebuilt === ancestor.value) return;
+      const updated = {
+        ...ancestor,
+        value: rebuilt,
+        version: ancestor.version + 1
+      };
+      this.nodes.set(ancestor.pathKey, updated);
+      this.dirty.add(ancestor.pathKey);
+      currentPath = ancestor.path;
+      currentValue = updated.value;
+    }
+  }
+  findNearestAncestorNode(path) {
+    for (let len = path.length - 1; len >= 0; len--) {
+      const node = this.nodes.get(irPathKey(path.slice(0, len)));
+      if (node) return node;
+    }
+    return null;
+  }
+  cloneAlong(container, relative, leaf) {
+    if (relative.length === 0) return leaf;
+    const [head, ...rest] = relative;
+    if (Array.isArray(container)) {
+      const index = typeof head === "number" ? head : Number(head);
+      const copy = container.slice();
+      while (copy.length <= index) copy.push(void 0);
+      copy[index] = this.cloneAlong(container[index], rest, leaf);
+      return copy;
+    }
+    if (isRecord(container)) {
+      const key = String(head);
+      return {
+        ...container,
+        [key]: this.cloneAlong(container[key], rest, leaf)
+      };
+    }
+    const built = typeof head === "number" ? this.cloneAlong([], relative, leaf) : this.cloneAlong({}, relative, leaf);
+    return built;
+  }
+  markRaw(path, reason, value) {
+    const pathKey = irPathKey(path);
+    const prior = path.length === 0 ? this.nodes.get("")?.value ?? this.rootRawValue : this.nodes.get(pathKey)?.value;
+    const merged = mergeWithoutLoss(prior, value);
+    this.recordRescue(pathKey, reason, merged.rescued);
+    this.rawPaths.set(pathKey, reason);
+    this.nodes.delete(pathKey);
+    this.dirty.add(pathKey);
+    if (path.length === 0) {
+      if (isRecord(merged.value)) this.rootRawValue = merged.value;
+      return;
+    }
+    this.propagateToAncestors(path, merged.value);
+  }
+  /**
+   * A rescue means a degrade tried to erase data a user could already see —
+   * an upstream defect. It rides the envelope as a notice so it surfaces in the
+   * Error Inspector instead of being silently absorbed (`core/` is a pure
+   * kernel: no console, no capture — the notice IS the alarm).
+   */
+  recordRescue(pathKey, reason, rescued) {
+    if (rescued.length === 0) return;
+    this.rescueNotices.push({
+      code: "degrade_data_rescued",
+      message: `degrade (${reason}) at path "${pathKey || "<root>"}" would have dropped: ${rescued.join(", ")}`
+    });
+  }
+  /**
+   * Assemble the canonical envelope. ONE code path for stream + one-shot.
+   * Callers supply the fingerprint (one-shot hashes the source; live sessions
+   * keep an incremental hasher so no per-flush re-hash happens).
+   */
+  buildEnvelope(fingerprint) {
+    const rootNode = this.nodes.get("");
+    const rootRawReason = this.rawPaths.get("") ?? null;
+    const notices = [];
+    if (this.errorReason) {
+      notices.push({ code: "parse_error", message: this.errorReason });
+    }
+    if (rootRawReason) {
+      notices.push({ code: "raw_fallback", message: rootRawReason });
+    }
+    notices.push(...this.rescueNotices);
+    const baseResidue = rootNode?.residue ?? null;
+    let residue = baseResidue;
+    if (notices.length > 0) {
+      residue = {
+        extra: baseResidue?.extra ?? null,
+        optionalMissing: baseResidue?.optionalMissing ?? null,
+        notices: [...baseResidue?.notices ?? [], ...notices]
+      };
+    }
+    const isRaw = rootRawReason !== null;
+    const identifiedKind = this.identifiedKinds.get("") ?? "";
+    const rootKind = isRaw ? this.rawKinds.get("") ?? "" : rootNode?.kind ?? (this.completedKind || identifiedKind);
+    const rootRawState = this.rawCauses.get("") === "unverified" ? "unverified" : "raw";
+    const root = {
+      role: "structured",
+      kind: rootKind,
+      kindState: isRaw ? rootRawState : rootNode ? rootNode.kindState : this.pendingSchemaPaths.has("") ? "pending_schema" : this.regionStatus === "streaming" ? identifiedKind ? "pending_schema" : "pending_kind" : "raw",
+      discriminator: JSON_DISCRIMINATOR,
+      path: [],
+      status: this.regionStatus,
+      value: rootNode?.value ?? this.rootRawValue ?? // Copy: the early-fields bucket keeps mutating as fields arrive; the
+      // envelope must be freezable (Redux dev-mode immutability).
+      (this.earlyFields.has("") ? { ...this.earlyFields.get("") } : {}),
+      residue
+    };
+    const nodeIndex = {};
+    for (const node of this.nodes.values()) {
+      if (node.pathKey === "") continue;
+      nodeIndex[node.pathKey] = {
+        kind: node.kind,
+        kindState: node.kindState,
+        status: node.complete ? "complete" : "streaming",
+        ...node.residue ? { residue: node.residue } : {}
+      };
+    }
+    for (const [pathKey] of this.rawPaths) {
+      if (pathKey === "") continue;
+      nodeIndex[pathKey] = {
+        kind: this.rawKinds.get(pathKey) ?? "",
+        kindState: this.rawCauses.get(pathKey) === "unverified" ? "unverified" : "raw",
+        status: "complete"
+      };
+    }
+    return {
+      v: IR_VERSION,
+      engine: "fe-kind-parser",
+      fingerprint,
+      root,
+      ...Object.keys(nodeIndex).length > 0 ? { nodeIndex } : {}
+    };
+  }
+};
+
+// core/fingerprint.ts
+var SEED_A = 2166136261;
+var SEED_B = 16777619;
+function fnv1aStep(hash, input) {
+  let h = hash >>> 0;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+  }
+  return h >>> 0;
+}
+function createFingerprinter() {
+  let a = SEED_A;
+  let b = SEED_B;
+  let length = 0;
+  return {
+    push(chunk) {
+      a = fnv1aStep(a, chunk);
+      b = fnv1aStep(b, chunk);
+      length += chunk.length;
+    },
+    current() {
+      return `${length.toString(36)}-${a.toString(36)}${b.toString(36)}`;
+    }
+  };
+}
+
+// core/json-tokenizer.ts
+var JsonStreamTokenizer = class {
+  mode = "normal";
+  pos = 0;
+  stringBuffer = "";
+  primitiveBuffer = "";
+  unicodeBuffer = "";
+  tokenStart = 0;
+  onToken;
+  // Explicit field rather than a parameter property: consumers compile this
+  // source directly, and a strict host (the dashboard) sets
+  // `erasableSyntaxOnly`, under which parameter properties are a hard error.
+  constructor(onToken) {
+    this.onToken = onToken;
+  }
+  get position() {
+    return this.pos;
+  }
+  push(chunk) {
+    for (let i = 0; i < chunk.length; i++) {
+      const ch = chunk[i];
+      const at = this.pos;
+      this.pos += 1;
+      if (ch === void 0) continue;
+      if (this.mode === "primitive") {
+        if (this.isDelimiter(ch)) {
+          this.emitPrimitive();
+          this.handleNormalChar(ch, at);
+        } else {
+          this.primitiveBuffer += ch;
+        }
+        continue;
+      }
+      if (this.mode === "string") {
+        if (ch === '"') {
+          this.onToken({
+            type: "string",
+            value: this.stringBuffer,
+            at: this.tokenStart
+          });
+          this.stringBuffer = "";
+          this.mode = "normal";
+          continue;
+        }
+        if (ch === "\\") {
+          this.mode = "escape";
+          continue;
+        }
+        if (ch === "\n" || ch === "\r") {
+          throw new Error(`Invalid unescaped newline in JSON string at ${at}`);
+        }
+        this.stringBuffer += ch;
+        continue;
+      }
+      if (this.mode === "escape") {
+        if (ch === "u") {
+          this.unicodeBuffer = "";
+          this.mode = "unicode";
+          continue;
+        }
+        const escaped = {
+          '"': '"',
+          "\\": "\\",
+          "/": "/",
+          b: "\b",
+          f: "\f",
+          n: "\n",
+          r: "\r",
+          t: "	"
+        };
+        if (!(ch in escaped)) {
+          throw new Error(`Invalid JSON escape sequence at ${at}`);
+        }
+        this.stringBuffer += escaped[ch];
+        this.mode = "string";
+        continue;
+      }
+      if (this.mode === "unicode") {
+        if (!/[0-9a-fA-F]/.test(ch)) {
+          throw new Error(`Invalid unicode escape at ${at}`);
+        }
+        this.unicodeBuffer += ch;
+        if (this.unicodeBuffer.length === 4) {
+          this.stringBuffer += String.fromCharCode(
+            parseInt(this.unicodeBuffer, 16)
+          );
+          this.unicodeBuffer = "";
+          this.mode = "string";
+        }
+        continue;
+      }
+      this.handleNormalChar(ch, at);
+    }
+  }
+  end() {
+    if (this.mode === "primitive") {
+      this.emitPrimitive();
+      return;
+    }
+    if (this.mode !== "normal") {
+      throw new Error(
+        `Stream ended while parsing JSON ${this.mode} at ${this.pos}`
+      );
+    }
+  }
+  handleNormalChar(ch, at) {
+    if (/\s/.test(ch)) return;
+    if (ch === "{" || ch === "}" || ch === "[" || ch === "]" || ch === ":" || ch === ",") {
+      this.onToken({ type: "punct", value: ch, at });
+      return;
+    }
+    if (ch === '"') {
+      this.mode = "string";
+      this.stringBuffer = "";
+      this.tokenStart = at;
+      return;
+    }
+    if (/[-0-9tfn]/.test(ch)) {
+      this.mode = "primitive";
+      this.primitiveBuffer = ch;
+      this.tokenStart = at;
+      return;
+    }
+    throw new Error(`Unexpected character "${ch}" at ${at}`);
+  }
+  emitPrimitive() {
+    const raw = this.primitiveBuffer;
+    const at = this.tokenStart;
+    this.primitiveBuffer = "";
+    this.mode = "normal";
+    let value;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      throw new Error(`Invalid JSON primitive "${raw}" at ${at}`);
+    }
+    if (typeof value === "number") {
+      this.onToken({ type: "number", value, at });
+      return;
+    }
+    if (typeof value === "boolean") {
+      this.onToken({ type: "boolean", value, at });
+      return;
+    }
+    if (value === null) {
+      this.onToken({ type: "null", value, at });
+      return;
+    }
+    throw new Error(`Unsupported JSON primitive "${raw}" at ${at}`);
+  }
+  isDelimiter(ch) {
+    return /\s/.test(ch) || ch === "{" || ch === "}" || ch === "[" || ch === "]" || ch === ":" || ch === ",";
+  }
+};
+
+// core/kind-snapshot.ts
+function emptyValueForFieldSchema(field) {
+  if (field.nullable) return null;
+  switch (field.type) {
+    case "string":
+      return "";
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "json":
+      return null;
+    case "string[]":
+    case "number[]":
+    case "boolean[]":
+    case "json[]":
+    case "array":
+      return [];
+    case "object":
+    case "inline_object":
+    case "record":
+      return {};
+    case "enum":
+      return "";
+    case "union":
+      if (field.scalars.includes("string")) return "";
+      if (field.scalars.includes("number")) return 0;
+      if (field.scalars.includes("boolean")) return false;
+      return {};
+    default:
+      return null;
+  }
+}
+function buildCompliantKindSnapshot(schema, partial) {
+  const value = {
+    [KIND_KEY]: schema.kind
+  };
+  const optionalMissing = [];
+  for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+    if (fieldName in partial && partial[fieldName] !== void 0) {
+      value[fieldName] = partial[fieldName];
+    } else if (fieldSchema.required) {
+      value[fieldName] = emptyValueForFieldSchema(fieldSchema);
+    } else {
+      optionalMissing.push(fieldName);
+    }
+  }
+  let extra = null;
+  for (const [fieldName, fieldValue] of Object.entries(partial)) {
+    if (fieldName === KIND_KEY) continue;
+    if (fieldName in schema.fields) continue;
+    if (extra === null) extra = {};
+    extra[fieldName] = fieldValue;
+  }
+  const residue = {
+    extra,
+    optionalMissing: optionalMissing.length > 0 ? optionalMissing : null,
+    notices: null
+  };
+  return { value, residue: isEmptyResidue(residue) ? null : residue };
+}
+
+// core/kind-parser.ts
+var jsonRootKeyLookup = null;
+function isSchemaResolver(source) {
+  return typeof source.get === "function";
+}
+function safeCopy(value) {
+  try {
+    return structuredClone(value);
+  } catch {
+    return value;
+  }
+}
+var KindStreamParser = class {
+  resolver;
+  stack = [];
+  objectKinds = /* @__PURE__ */ new Map();
+  inlineSchemas = /* @__PURE__ */ new Map();
+  recordSchemas = /* @__PURE__ */ new Map();
+  rawObjectPaths = /* @__PURE__ */ new Set();
+  /**
+   * Subtrees whose value domain is "any JSON" by schema (`json` / `json[]`
+   * fields, `record` with `values:"json"` members). OPAQUE by contract: no
+   * kind identification, no pending_kind, no raw_object degradation — unknown
+   * structure here is the declared shape, not a failure. Propagates to every
+   * descendant compound.
+   */
+  opaquePaths = /* @__PURE__ */ new Set();
+  deferredFields = /* @__PURE__ */ new Map();
+  awaitingKindPaths = /* @__PURE__ */ new Set();
+  /** Paths whose kind came from parent-schema prediction, unconfirmed so far. */
+  speculativeKinds = /* @__PURE__ */ new Set();
+  /**
+   * Kind named by the root object's FIRST key through the `json_root_key`
+   * surface registry — a candidate, adopted only at root finalize.
+   */
+  rootSurfaceKind = null;
+  /** kind → paths (by key) waiting for the resolver's cold fetch. */
+  pendingSchemaPaths = /* @__PURE__ */ new Map();
+  /** Pending-schema paths whose object already closed. */
+  closedPendingPaths = /* @__PURE__ */ new Set();
+  /** Schemas delivered via notifySchemaArrived (overlay over the resolver). */
+  arrivedSchemas = /* @__PURE__ */ new Map();
+  tokenizer;
+  root;
+  rootKind = "";
+  rootDone = false;
+  failed = false;
+  options;
+  // Explicit field, not a parameter property — see the note in
+  // `json-tokenizer.ts`: `erasableSyntaxOnly` hosts compile this source.
+  constructor(options) {
+    this.options = options;
+    this.resolver = isSchemaResolver(options.schemas) ? options.schemas : {
+      get: (kind) => options.schemas[kind]
+    };
+    this.tokenizer = new JsonStreamTokenizer(
+      (token) => this.handleToken(token)
+    );
+  }
+  push(chunk) {
+    if (this.failed || this.rootDone) return;
+    try {
+      this.tokenizer.push(chunk);
+    } catch (error) {
+      this.fail(
+        error instanceof Error ? error.message : String(error),
+        this.tokenizer.position
+      );
+    }
+  }
+  end() {
+    if (this.failed) return;
+    try {
+      this.tokenizer.end();
+    } catch (error) {
+      this.fail(
+        error instanceof Error ? error.message : String(error),
+        this.tokenizer.position
+      );
+      return;
+    }
+    this.resolvePendingSchemasAsRaw();
+    if (!this.rootDone) {
+      this.fail(
+        "Stream ended before the root JSON object was complete.",
+        this.tokenizer.position
+      );
+    }
+  }
+  resolvePendingSchemasAsRaw() {
+    const at = this.tokenizer.position;
+    for (const [kind, paths] of [...this.pendingSchemaPaths]) {
+      this.pendingSchemaPaths.delete(kind);
+      for (const [pathKey, path] of paths) {
+        this.closedPendingPaths.delete(pathKey);
+        if (this.rawObjectPaths.has(pathKey)) continue;
+        const value = this.getLiveObjectValue(path) ?? this.getFinalizedObjectValue(path) ?? {};
+        this.emitRawObject(
+          path,
+          safeCopy(value),
+          `No block schema registered for "${kind}".`,
+          at,
+          kind,
+          "unverified"
+        );
+      }
+    }
+  }
+  /** True once the root value has closed — the region is fully consumed. */
+  get isComplete() {
+    return this.rootDone;
+  }
+  get hasFailed() {
+    return this.failed;
+  }
+  /**
+   * Upgrade-in-place: the registry's cold fetch answered. Pending nodes for
+   * this kind validate and complete (closed nodes retroactively); a null
+   * schema (fetch miss) drops them to raw. Safe to call after end().
+   */
+  notifySchemaArrived(kind, schema) {
+    const waiting = this.pendingSchemaPaths.get(kind);
+    if (!waiting) return;
+    this.pendingSchemaPaths.delete(kind);
+    if (schema) {
+      this.arrivedSchemas.set(kind, schema);
+    }
+    const at = this.tokenizer.position;
+    for (const [pathKey, path] of waiting) {
+      if (this.rawObjectPaths.has(pathKey)) continue;
+      const value = this.getLiveObjectValue(path) ?? this.getFinalizedObjectValue(path);
+      if (!schema) {
+        this.emitRawObject(
+          path,
+          safeCopy(value ?? {}),
+          `No block schema registered for "${kind}".`,
+          at,
+          kind,
+          "unverified"
+        );
+        this.closedPendingPaths.delete(pathKey);
+        continue;
+      }
+      if (this.closedPendingPaths.has(pathKey)) {
+        this.closedPendingPaths.delete(pathKey);
+        if (value) {
+          this.finalizeTypedObject(path, value, at);
+        }
+      } else {
+        this.emitBlockSnapshotForObject(path, at);
+      }
+    }
+  }
+  handleToken(token) {
+    if (this.failed) return;
+    if (this.rootDone) {
+      this.fail("Unexpected token after complete JSON object.", token.at);
+      return;
+    }
+    if (token.type === "punct") {
+      this.handlePunctuation(token);
+      return;
+    }
+    if (token.type === "string") {
+      this.handleString(token);
+      return;
+    }
+    this.beginScalar(token.value, token.at);
+  }
+  handleString(token) {
+    const frame = this.currentFrame();
+    if (frame?.kind === "object" && (frame.expecting === "keyOrEnd" || frame.expecting === "key")) {
+      this.acceptObjectKey(frame, token.value, token.at);
+      return;
+    }
+    this.beginScalar(token.value, token.at);
+  }
+  handlePunctuation(token) {
+    switch (token.value) {
+      case "{":
+        this.beginCompound("object", token.at);
+        return;
+      case "[":
+        this.beginCompound("array", token.at);
+        return;
+      case "}":
+        this.closeCompound("object", token.at);
+        return;
+      case "]":
+        this.closeCompound("array", token.at);
+        return;
+      case ":":
+        this.acceptColon(token.at);
+        return;
+      case ",":
+        this.acceptComma(token.at);
+        return;
+    }
+  }
+  beginCompound(kind, at) {
+    const value = kind === "object" ? {} : [];
+    const container = this.currentFrame();
+    const path = this.placeValue(value, kind, at, false);
+    if (!path || this.failed) return;
+    const opaque = container !== void 0 && this.opaquePaths.has(this.pathKey(container.path)) || this.isJsonAnyPlacement(path);
+    if (opaque) this.opaquePaths.add(this.pathKey(path));
+    if (kind === "object") {
+      this.emit({ type: "object_start", path, at });
+      if (opaque) {
+        this.stack.push({
+          kind: "object",
+          path,
+          value,
+          expecting: "keyOrEnd",
+          keyCount: 0
+        });
+        return;
+      }
+      this.registerObjectContext(path);
+      const pathKey = this.pathKey(path);
+      this.stack.push({
+        kind: "object",
+        path,
+        value,
+        expecting: "keyOrEnd",
+        keyCount: 0
+      });
+      if (this.inlineSchemas.has(pathKey) || this.recordSchemas.has(pathKey)) {
+        return;
+      }
+      const speculated = this.resolveSpeculativeKind(path);
+      if (speculated) {
+        this.objectKinds.set(pathKey, speculated);
+        this.speculativeKinds.add(pathKey);
+        if (path.length === 0) {
+          this.rootKind = speculated;
+        }
+        this.emit({
+          type: "kind_identified",
+          kind: speculated,
+          path,
+          speculative: true,
+          at
+        });
+        this.emitBlockSnapshotForObject(path, at);
+        return;
+      }
+      this.awaitingKindPaths.add(pathKey);
+      this.emit({ type: "pending_kind", path, at });
+      return;
+    }
+    const parentField = this.parentFieldName(path);
+    if (parentField) {
+      this.emit({ type: "array_start", path, field: parentField, at });
+    }
+    this.stack.push({
+      kind: "array",
+      path,
+      value,
+      expecting: "valueOrEnd",
+      nextIndex: 0
+    });
+  }
+  /**
+   * THE JSON-ROOT-KEY SURFACE — `content_ir.kind_surface` rows of type
+   * `json_root_key`, live at last (they were inert phantom rows until
+   * 2026-08-20).
+   *
+   * A legacy payload such as `{"quiz_title": ...}` carries no `__kind`, but
+   * the ONE surface registry knows exactly which kind that root key names —
+   * the same lookup the SERVER performs before adapting the payload
+   * (`aidream .../processing/blocks/envelope.py`). Consulting it HERE, in the
+   * shared parser core, is what makes one place decide it: both hosts — the
+   * one-shot `normalizeJsonRegion` (DB reload / reconcile) and the live
+   * `openParseSession` (streaming) — build their parser through
+   * `createKindStreamParser`, so neither passes an option and neither can
+   * drift from the other.
+   *
+   * Recorded at the first root key; ADOPTED only when the root object closes
+   * (`completeTypedObject`). That is the surface registry's complete-only
+   * convergence law, and every json_root_key row is `streaming:false` — these
+   * legacy shapes are recognized by their whole payload, so speculating
+   * mid-stream would flash a kind component over an object that may never
+   * satisfy the schema. An explicit `expectedRootKind` (an agent's declared
+   * output schema) is stronger context and always wins; an actual `__kind`
+   * still wins over both.
+   */
+  noteRootSurfaceKind(key) {
+    if (key === KIND_KEY) return;
+    if (this.options.expectedRootKind) return;
+    if (this.rootKind || this.objectKinds.has(this.pathKey([]))) return;
+    const kind = this.resolver.kindForJsonRootKey?.(key) ?? jsonRootKeyLookup?.(key);
+    if (!kind) return;
+    this.rootSurfaceKind = kind;
+    if (!this.lookupSchema(kind)) {
+      this.resolver.request?.(kind);
+    }
+  }
+  /**
+   * Prediction from the parent schema: object field → declared kind; array
+   * item → sole itemKind; root → expectedRootKind. Only when the schema is
+   * actually resolvable (a prediction we can't validate against is not a
+   * commitment worth making).
+   */
+  resolveSpeculativeKind(path) {
+    if (path.length === 0) {
+      const expected = this.options.expectedRootKind;
+      return expected && this.lookupObjectSchema(expected) ? expected : null;
+    }
+    const last = path[path.length - 1];
+    if (typeof last === "string") {
+      const fieldSchema2 = this.resolveParentFieldSchema(path);
+      if (fieldSchema2?.type === "object" && this.lookupObjectSchema(fieldSchema2.kind)) {
+        return fieldSchema2.kind;
+      }
+      return null;
+    }
+    const fieldName = this.parentFieldName(path);
+    if (!fieldName) return null;
+    const ownerPath = path.slice(0, -2);
+    const ownerKind = this.getObjectKindForPath(ownerPath);
+    if (!ownerKind) return null;
+    const fieldSchema = this.lookupSchema(ownerKind)?.fields[fieldName];
+    const soleItemKind = fieldSchema?.type === "array" && fieldSchema.itemKinds.length === 1 ? fieldSchema.itemKinds[0] : void 0;
+    if (soleItemKind !== void 0 && this.lookupObjectSchema(soleItemKind)) {
+      return soleItemKind;
+    }
+    return null;
+  }
+  /**
+   * A schema usable for OBJECT speculation/snapshots — root-form kinds
+   * (non-object data-only shapes) are never a valid object commitment.
+   */
+  lookupObjectSchema(kind) {
+    const schema = this.lookupSchema(kind);
+    return schema && !schema.root ? schema : void 0;
+  }
+  beginScalar(value, at) {
+    this.placeValue(value, "scalar", at, true);
+  }
+  placeValue(value, valueKind, at, finalizedImmediately) {
+    if (this.root === void 0) {
+      if (valueKind !== "object") {
+        this.fail("Root value must be a JSON object.", at);
+        return null;
+      }
+      this.root = value;
+      return [];
+    }
+    const parent = this.currentFrame();
+    if (!parent) {
+      this.fail("Unexpected value after root object.", at);
+      return null;
+    }
+    let path;
+    let fieldKey;
+    if (parent.kind === "object") {
+      if (parent.expecting !== "value") {
+        this.fail(
+          `Unexpected value inside object. Expected ${parent.expecting}.`,
+          at
+        );
+        return null;
+      }
+      if (parent.currentKey === void 0) {
+        this.fail("Internal parser error: missing object key.", at);
+        return null;
+      }
+      fieldKey = parent.currentKey;
+      path = [...parent.path, fieldKey];
+      const placementError = this.validateFieldPlacement(
+        parent,
+        fieldKey,
+        valueKind,
+        value
+      );
+      if (placementError) {
+        this.markNodeRaw(parent.path, parent.value, placementError, at);
+      }
+      parent.value[fieldKey] = value;
+      parent.currentKey = void 0;
+      parent.expecting = "commaOrEnd";
+    } else {
+      if (parent.expecting !== "valueOrEnd" && parent.expecting !== "value") {
+        this.fail(
+          `Unexpected value inside array. Expected ${parent.expecting}.`,
+          at
+        );
+        return null;
+      }
+      const index = parent.nextIndex;
+      path = [...parent.path, index];
+      fieldKey = this.parentFieldName(path);
+      parent.value.push(value);
+      parent.nextIndex += 1;
+      parent.expecting = "commaOrEnd";
+    }
+    if (finalizedImmediately) {
+      this.onValueFinalized(path, value, at);
+    }
+    return path;
+  }
+  acceptObjectKey(frame, key, at) {
+    if (frame.expecting !== "keyOrEnd" && frame.expecting !== "key") {
+      this.fail(`Unexpected object key "${key}".`, at);
+      return;
+    }
+    if (Object.prototype.hasOwnProperty.call(frame.value, key)) {
+      this.markNodeRaw(
+        frame.path,
+        frame.value,
+        `Duplicate key "${key}".`,
+        at
+      );
+    }
+    if (frame.path.length === 0 && frame.keyCount === 0) {
+      this.noteRootSurfaceKind(key);
+    }
+    frame.currentKey = key;
+    frame.keyCount += 1;
+    frame.expecting = "colon";
+  }
+  acceptColon(at) {
+    const frame = this.currentFrame();
+    if (!frame || frame.kind !== "object" || frame.expecting !== "colon") {
+      this.fail("Unexpected colon.", at);
+      return;
+    }
+    frame.expecting = "value";
+  }
+  acceptComma(at) {
+    const frame = this.currentFrame();
+    if (!frame || frame.expecting !== "commaOrEnd") {
+      this.fail("Unexpected comma.", at);
+      return;
+    }
+    if (frame.kind === "object") {
+      frame.expecting = "key";
+    } else {
+      frame.expecting = "value";
+    }
+  }
+  closeCompound(kind, at) {
+    const frame = this.currentFrame();
+    if (!frame || frame.kind !== kind) {
+      this.fail(
+        `Unexpected closing ${kind === "object" ? "brace" : "bracket"}.`,
+        at
+      );
+      return;
+    }
+    if (frame.kind === "object") {
+      if (frame.expecting !== "keyOrEnd" && frame.expecting !== "commaOrEnd") {
+        this.fail(`Object closed too early. Expected ${frame.expecting}.`, at);
+        return;
+      }
+    } else if (frame.expecting !== "valueOrEnd" && frame.expecting !== "commaOrEnd") {
+      this.fail(`Array closed too early. Expected ${frame.expecting}.`, at);
+      return;
+    }
+    this.stack.pop();
+    if (this.stack.length === 0) {
+      this.rootDone = true;
+    }
+    this.onValueFinalized(frame.path, frame.value, at);
+  }
+  /**
+   * True when a value placed at `path` sits directly under a json-any
+   * placement: a `json`/`json[]` FIELD, or a member of a `record` whose
+   * values are `"json"`. (Deeper descendants inherit via `opaquePaths`.)
+   */
+  isJsonAnyPlacement(path) {
+    const fieldSchema = this.resolveParentFieldSchema(path);
+    if (fieldSchema && isJsonAnyField(fieldSchema)) return true;
+    const last = path[path.length - 1];
+    if (typeof last === "string") {
+      const parentKey = this.pathKey(path.slice(0, -1));
+      if (this.recordSchemas.get(parentKey) === "json") return true;
+    }
+    return false;
+  }
+  onValueFinalized(path, value, at) {
+    if (this.failed) return;
+    const pathKey = this.pathKey(path);
+    const parentIsOpaque = path.length > 0 && this.opaquePaths.has(this.pathKey(path.slice(0, -1)));
+    if (this.opaquePaths.has(pathKey)) {
+      if (!parentIsOpaque) this.emitFieldIfReady(path, value, at);
+      return;
+    }
+    if (parentIsOpaque) return;
+    if (this.isKindFieldPath(path)) {
+      if (typeof value !== "string") {
+        return;
+      }
+      this.onKindDiscriminatorArrived(path.slice(0, -1), value, at);
+      return;
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const objectValue = value;
+      const inlineFields = this.inlineSchemas.get(pathKey);
+      if (inlineFields) {
+        const inlineError = this.validateObjectAgainstFields(
+          objectValue,
+          inlineFields
+        );
+        if (inlineError.error) {
+          this.emitRawObject(path, objectValue, inlineError.error, at);
+          return;
+        }
+        this.inlineSchemas.delete(pathKey);
+        this.emitSchemaNotices(path, "inline_object", inlineError, at);
+        this.emit({
+          type: "object_complete",
+          kind: "inline_object",
+          path,
+          value: objectValue,
+          at
+        });
+      } else {
+        const recordValueType = this.recordSchemas.get(pathKey);
+        if (recordValueType) {
+          const recordError = this.validateRecordObject(
+            objectValue,
+            recordValueType
+          );
+          if (recordError) {
+            this.emitRawObject(path, objectValue, recordError, at);
+            return;
+          }
+          this.recordSchemas.delete(pathKey);
+          this.emit({
+            type: "object_complete",
+            kind: "record",
+            path,
+            value: objectValue,
+            at
+          });
+        } else {
+          this.completeTypedObject(path, objectValue, at);
+        }
+      }
+    }
+    this.emitFieldIfReady(path, value, at);
+    if (path.length === 0) {
+      this.completeRoot(value, at);
+    }
+  }
+  /** __kind arrived for an object — confirm speculation, identify, or backtrack. */
+  onKindDiscriminatorArrived(objectPath, kind, at) {
+    const objectPathKey = this.pathKey(objectPath);
+    if (this.rawObjectPaths.has(objectPathKey)) return;
+    const prior = this.objectKinds.get(objectPathKey);
+    const wasSpeculative = this.speculativeKinds.has(objectPathKey);
+    if (prior !== void 0 && wasSpeculative) {
+      this.speculativeKinds.delete(objectPathKey);
+      if (prior === kind) {
+        this.emitBlockSnapshotForObject(objectPath, at);
+        return;
+      }
+      if (this.lookupSchema(kind) && this.validateArrayItemKind(objectPath, kind) === null && this.speculativeRetagAllowed(objectPath, kind)) {
+        this.objectKinds.set(objectPathKey, kind);
+        if (objectPath.length === 0) {
+          this.rootKind = kind;
+        }
+        this.emit({ type: "kind_identified", kind, path: objectPath, at });
+        this.emitBlockSnapshotForObject(objectPath, at);
+        return;
+      }
+      const live = this.getLiveObjectValue(objectPath);
+      this.objectKinds.delete(objectPathKey);
+      if (objectPath.length === 0) {
+        this.rootKind = "";
+      }
+      this.emitRawObject(
+        objectPath,
+        safeCopy(live ?? {}),
+        `Speculated kind "${prior}" contradicted by ${KIND_KEY} "${kind}".`,
+        at
+      );
+      return;
+    }
+    this.objectKinds.set(objectPathKey, kind);
+    this.emit({
+      type: "kind_identified",
+      kind,
+      path: objectPath,
+      at
+    });
+    this.clearKindWait(objectPath, "identified", at, kind);
+    if (objectPath.length === 0) {
+      this.rootKind = kind;
+    }
+    if (!this.lookupSchema(kind) && this.resolver.request) {
+      this.addPendingSchemaPath(kind, objectPath);
+      this.emit({ type: "pending_schema", kind, path: objectPath, at });
+      this.resolver.request(kind);
+      return;
+    }
+    this.flushDeferredFields(objectPath, kind, at);
+    this.emitBlockSnapshotForObject(objectPath, at);
+  }
+  /** A contradicted speculation may re-tag only where the new kind is legal. */
+  speculativeRetagAllowed(path, kind) {
+    if (path.length === 0) {
+      return true;
+    }
+    const last = path[path.length - 1];
+    if (typeof last === "number") {
+      const fieldName = this.parentFieldName(path);
+      const ownerKind = this.getObjectKindForPath(path.slice(0, -2));
+      if (!fieldName || !ownerKind) return false;
+      const fieldSchema = this.lookupSchema(ownerKind)?.fields[fieldName];
+      return fieldSchema?.type === "array" && fieldSchema.itemKinds.includes(kind);
+    }
+    return false;
+  }
+  addPendingSchemaPath(kind, path) {
+    const pathKey = this.pathKey(path);
+    const existing = this.pendingSchemaPaths.get(kind) ?? /* @__PURE__ */ new Map();
+    existing.set(pathKey, path);
+    this.pendingSchemaPaths.set(kind, existing);
+  }
+  completeTypedObject(path, objectValue, at) {
+    const pathKey = this.pathKey(path);
+    if (this.rawObjectPaths.has(pathKey)) return;
+    const declaredKind = readObjectKind(objectValue);
+    const committedKind = this.objectKinds.get(pathKey);
+    if (committedKind && this.pendingSchemaPaths.get(committedKind)?.has(pathKey)) {
+      this.closedPendingPaths.add(pathKey);
+      return;
+    }
+    if (!declaredKind && committedKind && this.speculativeKinds.has(pathKey)) {
+      this.speculativeKinds.delete(pathKey);
+      this.finalizeSpeculatedObject(path, objectValue, committedKind, at);
+      return;
+    }
+    if (path.length === 0 && !declaredKind && !committedKind && this.rootSurfaceKind) {
+      const surfaceKind = this.rootSurfaceKind;
+      this.rootSurfaceKind = null;
+      this.objectKinds.set(pathKey, surfaceKind);
+      this.rootKind = surfaceKind;
+      this.emit({
+        type: "kind_identified",
+        kind: surfaceKind,
+        path,
+        speculative: true,
+        at
+      });
+      this.clearKindWait(path, "identified", at, surfaceKind);
+      this.finalizeSpeculatedObject(path, objectValue, surfaceKind, at);
+      return;
+    }
+    if (!declaredKind) {
+      this.emitRawObject(
+        path,
+        objectValue,
+        `Object is missing "${KIND_KEY}".`,
+        at
+      );
+      return;
+    }
+    this.speculativeKinds.delete(pathKey);
+    this.finalizeTypedObject(path, objectValue, at);
+  }
+  /** Validate + complete an object whose value carries __kind. */
+  finalizeTypedObject(path, objectValue, at) {
+    const pathKey = this.pathKey(path);
+    const kind = readObjectKind(objectValue);
+    if (!kind) {
+      this.emitRawObject(
+        path,
+        objectValue,
+        `Object is missing "${KIND_KEY}".`,
+        at
+      );
+      return;
+    }
+    const schema = this.lookupSchema(kind);
+    if (!schema) {
+      this.emitRawObject(
+        path,
+        objectValue,
+        `No block schema registered for "${kind}".`,
+        at,
+        kind,
+        "unverified"
+      );
+      return;
+    }
+    const arrayItemError = this.validateArrayItemKind(path, kind);
+    if (arrayItemError) {
+      this.emitRawObject(path, objectValue, arrayItemError, at, kind);
+      return;
+    }
+    const outcome = this.validateObjectAgainstSchema(objectValue, schema);
+    if (outcome.error) {
+      this.emitRawObject(path, objectValue, outcome.error, at, kind);
+      return;
+    }
+    this.objectKinds.set(pathKey, kind);
+    this.emitSchemaNotices(path, kind, outcome, at);
+    this.emitBlockSnapshotForObject(path, at, true);
+    this.emit({
+      type: "object_complete",
+      kind,
+      path,
+      value: objectValue,
+      at
+    });
+  }
+  /** Validate + complete an object typed purely by parent prediction. */
+  finalizeSpeculatedObject(path, objectValue, kind, at) {
+    const schema = this.lookupSchema(kind);
+    if (!schema) {
+      this.emitRawObject(
+        path,
+        objectValue,
+        `No block schema registered for "${kind}".`,
+        at,
+        kind,
+        "unverified"
+      );
+      return;
+    }
+    const outcome = this.validateObjectAgainstSchema(
+      { ...objectValue, [KIND_KEY]: kind },
+      schema
+    );
+    if (outcome.error) {
+      this.emitRawObject(path, objectValue, outcome.error, at, kind);
+      return;
+    }
+    this.emitSchemaNotices(path, kind, outcome, at);
+    this.emitBlockSnapshotForObject(path, at, true);
+    this.emit({
+      type: "object_complete",
+      kind,
+      path,
+      value: objectValue,
+      at
+    });
+  }
+  validateArrayItemKind(path, kind) {
+    const last = path[path.length - 1];
+    if (typeof last !== "number") return null;
+    const fieldName = this.parentFieldName(path);
+    if (!fieldName) return null;
+    const ownerObjectPath = path.slice(0, -2);
+    const parentKind = this.getObjectKindForPath(ownerObjectPath);
+    if (!parentKind) return null;
+    const fieldSchema = this.lookupSchema(parentKind)?.fields[fieldName];
+    if (!fieldSchema || fieldSchema.type !== "array") return null;
+    if (!fieldSchema.itemKinds.includes(kind)) {
+      return `Kind "${kind}" is not allowed in "${fieldName}" on "${parentKind}" (expected one of: ${fieldSchema.itemKinds.join(", ")}).`;
+    }
+    return null;
+  }
+  completeRoot(rootObject, at) {
+    const pathKey = this.pathKey([]);
+    if (this.rawObjectPaths.has(pathKey)) {
+      this.emit({
+        type: "complete",
+        kind: readObjectKind(rootObject) ?? "",
+        value: rootObject,
+        at
+      });
+      return;
+    }
+    const committedKind = this.objectKinds.get(pathKey);
+    if (committedKind && this.pendingSchemaPaths.get(committedKind)?.has(pathKey)) {
+      this.emit({
+        type: "complete",
+        kind: committedKind,
+        value: rootObject,
+        at
+      });
+      return;
+    }
+    this.emit({
+      type: "complete",
+      kind: this.objectKinds.get(pathKey) ?? readObjectKind(rootObject) ?? "",
+      value: rootObject,
+      at
+    });
+  }
+  /** Mark a node raw (node-scoped failure) without killing the stream. */
+  markNodeRaw(path, liveValue, reason, at) {
+    const pathKey = this.pathKey(path);
+    if (this.rawObjectPaths.has(pathKey)) return;
+    const identifiedKind = this.objectKinds.get(pathKey) ?? (typeof liveValue === "object" && liveValue !== null && !Array.isArray(liveValue) ? readObjectKind(liveValue) ?? void 0 : void 0);
+    this.speculativeKinds.delete(pathKey);
+    this.emitRawObject(path, safeCopy(liveValue), reason, at, identifiedKind);
+  }
+  /**
+   * Degrade ONE node off the resolved path.
+   *
+   * `cause` defaults to `"invalid"` deliberately: every call site that omits
+   * it is a real failure (validation, duplicate key, placement, contradicted
+   * speculation). ONLY the "no schema registered" sites pass `"unverified"`,
+   * and they are the reason the parameter exists — see `IrKindState`.
+   */
+  emitRawObject(path, value, reason, at, identifiedKind, cause = "invalid") {
+    const pathKey = this.pathKey(path);
+    if (this.rawObjectPaths.has(pathKey)) return;
+    this.rawObjectPaths.add(pathKey);
+    this.clearKindWait(path, "raw_fallback", at, void 0, reason);
+    this.emit({
+      type: "raw_object",
+      path,
+      value,
+      reason,
+      ...identifiedKind !== void 0 && { kind: identifiedKind },
+      cause,
+      at
+    });
+  }
+  clearKindWait(path, outcome, at, kind, reason) {
+    const pathKey = this.pathKey(path);
+    if (!this.awaitingKindPaths.has(pathKey)) return;
+    this.awaitingKindPaths.delete(pathKey);
+    this.emit({
+      type: "kind_wait_end",
+      path,
+      outcome,
+      ...kind !== void 0 && { kind },
+      ...reason !== void 0 && { reason },
+      at
+    });
+  }
+  emitFieldIfReady(path, value, at) {
+    const fieldKey = this.fieldKeyFromPath(path);
+    if (!fieldKey || fieldKey === KIND_KEY) return;
+    const parentPath = path.slice(0, -1);
+    const objectKind = this.getDirectObjectKind(parentPath);
+    if (!objectKind) {
+      const parentPathKey = this.pathKey(parentPath);
+      const deferred = this.deferredFields.get(parentPathKey) ?? [];
+      deferred.push({ key: fieldKey, value, at });
+      this.deferredFields.set(parentPathKey, deferred);
+      return;
+    }
+    const schemaResolved = this.lookupSchema(objectKind) !== void 0;
+    if (schemaResolved && !this.isAllowedSchemaField(parentPath, fieldKey, objectKind)) {
+      return;
+    }
+    this.emit({
+      type: "field",
+      kind: objectKind,
+      path,
+      key: fieldKey,
+      value,
+      at
+    });
+    this.emitBlockSnapshotForObject(parentPath, at);
+  }
+  flushDeferredFields(objectPath, kind, at) {
+    const pathKey = this.pathKey(objectPath);
+    const deferred = this.deferredFields.get(pathKey);
+    if (!deferred) return;
+    for (const entry of deferred) {
+      if (entry.key === KIND_KEY) continue;
+      if (!this.isAllowedSchemaField(objectPath, entry.key, kind)) continue;
+      this.emit({
+        type: "field",
+        kind,
+        path: [...objectPath, entry.key],
+        key: entry.key,
+        value: entry.value,
+        at: entry.at
+      });
+    }
+    this.deferredFields.delete(pathKey);
+    this.emitBlockSnapshotForObject(objectPath, at);
+  }
+  getLiveObjectValue(path) {
+    const pathKey = this.pathKey(path);
+    for (let i = this.stack.length - 1; i >= 0; i--) {
+      const frame = this.stack[i];
+      if (!frame) continue;
+      if (frame.kind === "object" && this.pathKey(frame.path) === pathKey) {
+        return frame.value;
+      }
+    }
+    return null;
+  }
+  emitBlockSnapshotForObject(objectPath, at, complete = false) {
+    const pathKey = this.pathKey(objectPath);
+    if (this.rawObjectPaths.has(pathKey)) return;
+    const kind = this.getDirectObjectKind(objectPath);
+    if (!kind) return;
+    const schema = this.lookupObjectSchema(kind);
+    if (!schema) return;
+    const partial = complete ? this.getFinalizedObjectValue(objectPath) : this.getLiveObjectValue(objectPath);
+    if (!partial) return;
+    const { value, residue } = buildCompliantKindSnapshot(schema, partial);
+    this.emit({
+      type: "block_snapshot",
+      kind,
+      path: objectPath,
+      value,
+      residue,
+      complete,
+      at
+    });
+  }
+  /**
+   * On `complete` snapshots (and post-close schema upgrades) the frame has
+   * already been popped — the finalized value lives in the root tree.
+   */
+  getFinalizedObjectValue(path) {
+    const live = this.getLiveObjectValue(path);
+    if (live) return live;
+    if (path.length === 0) {
+      return typeof this.root === "object" && this.root !== null && !Array.isArray(this.root) ? this.root : null;
+    }
+    let cursor = this.root;
+    for (const segment of path) {
+      if (cursor === null || typeof cursor !== "object") return null;
+      cursor = cursor[segment];
+    }
+    return typeof cursor === "object" && cursor !== null && !Array.isArray(cursor) ? cursor : null;
+  }
+  validateFieldPlacement(parent, fieldKey, valueKind, value) {
+    const parentPathKey = this.pathKey(parent.path);
+    const inlineFields = this.inlineSchemas.get(parentPathKey);
+    if (inlineFields) {
+      const fieldSchema = inlineFields[fieldKey];
+      if (!fieldSchema) {
+        return null;
+      }
+      return this.validateValueAgainstField(
+        fieldSchema,
+        valueKind,
+        value,
+        fieldKey
+      );
+    }
+    const recordValueType = this.recordSchemas.get(parentPathKey);
+    if (recordValueType) {
+      if (recordValueType === "json") return null;
+      if (valueKind !== "scalar") {
+        return `Record field "${fieldKey}" must be a scalar.`;
+      }
+      return this.validateRecordScalar(recordValueType, value, fieldKey);
+    }
+    return null;
+  }
+  emitSchemaNotices(path, kind, outcome, at) {
+    for (const field of outcome.optionalMissing) {
+      this.emit({
+        type: "optional_field_missing",
+        kind,
+        path,
+        field,
+        at
+      });
+    }
+    for (const field of outcome.extraFields) {
+      this.emit({
+        type: "extra_field",
+        kind,
+        path,
+        field,
+        at
+      });
+    }
+  }
+  validateObjectAgainstSchema(objectValue, schema) {
+    const optionalMissing = [];
+    const extraFields = [];
+    const emptyOutcome = { optionalMissing, extraFields };
+    if (schema.root) {
+      return {
+        error: `Kind "${schema.kind}" has a non-object root form and cannot be a "${KIND_KEY}" object.`,
+        ...emptyOutcome
+      };
+    }
+    const kind = readObjectKind(objectValue);
+    if (kind !== schema.kind) {
+      return {
+        error: `Object "${KIND_KEY}" is "${kind ?? "missing"}", expected "${schema.kind}".`,
+        ...emptyOutcome
+      };
+    }
+    for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+      if (fieldSchema.required) {
+        if (!(fieldName in objectValue)) {
+          return {
+            error: `Kind "${schema.kind}" is missing required field "${fieldName}".`,
+            ...emptyOutcome
+          };
+        }
+        continue;
+      }
+      if (!(fieldName in objectValue)) {
+        optionalMissing.push(fieldName);
+      }
+    }
+    for (const [fieldName, fieldValue] of Object.entries(objectValue)) {
+      if (fieldName === KIND_KEY) continue;
+      const fieldSchema = schema.fields[fieldName];
+      if (!fieldSchema) {
+        extraFields.push(fieldName);
+        continue;
+      }
+      const error = this.validateFinalFieldValue(
+        fieldSchema,
+        fieldValue,
+        fieldName,
+        schema.kind
+      );
+      if (error) {
+        return { error, optionalMissing, extraFields };
+      }
+    }
+    return { error: null, optionalMissing, extraFields };
+  }
+  validateFinalFieldValue(fieldSchema, value, fieldName, objectKind) {
+    if (fieldSchema.type === "json") return null;
+    if (fieldSchema.type === "json[]") {
+      if (value === null) {
+        return fieldSchema.nullable ? null : `Field "${fieldName}" on kind "${objectKind}" cannot be null.`;
+      }
+      if (!Array.isArray(value)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be an array.`;
+      }
+      return null;
+    }
+    if (isScalarArrayType(fieldSchema.type)) {
+      if (!Array.isArray(value)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be an array.`;
+      }
+      const itemType = scalarArrayItemType(fieldSchema.type);
+      if (!value.every((item) => typeof item === itemType)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be an array of ${itemType}s.`;
+      }
+      if (fieldSchema.type === "string[]" && fieldSchema.values !== void 0 && !fieldSchema.open) {
+        const allowed = fieldSchema.values;
+        const bad = value.find(
+          (item) => typeof item === "string" && !allowed.includes(item)
+        );
+        if (bad !== void 0) {
+          return `Field "${fieldName}" on kind "${objectKind}" items must be one of: ${allowed.join(", ")}.`;
+        }
+      }
+      return null;
+    }
+    if (fieldSchema.type === "array") {
+      if (!Array.isArray(value)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be an array.`;
+      }
+      return null;
+    }
+    if (fieldSchema.type === "object") {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be an object.`;
+      }
+      const nestedKind = readObjectKind(value);
+      if (nestedKind !== fieldSchema.kind) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be kind "${fieldSchema.kind}".`;
+      }
+      const nestedSchema = this.lookupSchema(fieldSchema.kind);
+      if (!nestedSchema) {
+        return `Unknown nested kind "${fieldSchema.kind}" on field "${fieldName}".`;
+      }
+      return this.validateObjectAgainstSchema(
+        value,
+        nestedSchema
+      ).error;
+    }
+    if (fieldSchema.type === "inline_object") {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be an inline object.`;
+      }
+      return this.validateObjectAgainstFields(
+        value,
+        fieldSchema.fields
+      ).error;
+    }
+    if (fieldSchema.type === "record") {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return `Field "${fieldName}" on kind "${objectKind}" must be a record object.`;
+      }
+      return this.validateRecordObject(
+        value,
+        fieldSchema.values
+      );
+    }
+    if (fieldSchema.type === "union") {
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const kinds = fieldSchema.kinds ?? [];
+        if (kinds.length === 0) {
+          return `Field "${fieldName}" on kind "${objectKind}" must be ${fieldSchema.scalars.join(" | ")}.`;
+        }
+        const memberKind = readObjectKind(value);
+        if (!memberKind || !kinds.includes(memberKind)) {
+          return `Field "${fieldName}" on kind "${objectKind}" must be one of kinds: ${kinds.join(", ")}.`;
+        }
+        const memberSchema = this.lookupSchema(memberKind);
+        if (!memberSchema) {
+          return `Unknown union member kind "${memberKind}" on field "${fieldName}".`;
+        }
+        return this.validateObjectAgainstSchema(
+          value,
+          memberSchema
+        ).error;
+      }
+      return this.validateScalarField(fieldSchema, value, fieldName);
+    }
+    if (fieldSchema.type === "string" || fieldSchema.type === "number" || fieldSchema.type === "boolean" || fieldSchema.type === "enum") {
+      return this.validateScalarField(fieldSchema, value, fieldName);
+    }
+    return `Unsupported field schema for "${fieldName}".`;
+  }
+  validateValueAgainstField(fieldSchema, valueKind, value, fieldName) {
+    if (fieldSchema.type === "json") {
+      return null;
+    }
+    if (fieldSchema.type === "array" || fieldSchema.type === "json[]") {
+      return valueKind === "array" ? null : `Field "${fieldName}" must be an array.`;
+    }
+    if (fieldSchema.type === "object" || fieldSchema.type === "inline_object") {
+      return valueKind === "object" ? null : `Field "${fieldName}" must be an object.`;
+    }
+    if (fieldSchema.type === "record") {
+      return valueKind === "object" ? null : `Field "${fieldName}" must be a record object.`;
+    }
+    if (isScalarArrayType(fieldSchema.type)) {
+      return valueKind === "array" ? null : `Field "${fieldName}" must be an array.`;
+    }
+    if (fieldSchema.type === "union" && (fieldSchema.kinds?.length ?? 0) > 0) {
+      if (valueKind === "object") return null;
+    }
+    if (valueKind !== "scalar") {
+      return `Field "${fieldName}" must be a scalar.`;
+    }
+    return this.validateScalarField(fieldSchema, value, fieldName);
+  }
+  validateScalarField(fieldSchema, value, fieldName) {
+    if (value === null) {
+      return fieldSchema.nullable ? null : `Field "${fieldName}" cannot be null.`;
+    }
+    if (fieldSchema.type === "enum") {
+      if (typeof value !== "string") {
+        return `Field "${fieldName}" must be a string.`;
+      }
+      if (!fieldSchema.open && !fieldSchema.values.includes(value)) {
+        return `Field "${fieldName}" must be one of: ${fieldSchema.values.join(", ")}.`;
+      }
+      return null;
+    }
+    if (fieldSchema.type === "union") {
+      const valueType = typeof value;
+      if (valueType !== "string" && valueType !== "number" && valueType !== "boolean") {
+        return `Field "${fieldName}" must be ${fieldSchema.scalars.join(" | ")}.`;
+      }
+      if (!fieldSchema.scalars.includes(
+        valueType
+      )) {
+        return `Field "${fieldName}" must be ${fieldSchema.scalars.join(" | ")}.`;
+      }
+      return null;
+    }
+    if (fieldSchema.type === "string" || fieldSchema.type === "number" || fieldSchema.type === "boolean") {
+      if (typeof value !== fieldSchema.type) {
+        return `Field "${fieldName}" must be ${fieldSchema.type}.`;
+      }
+      if (fieldSchema.type === "number" && typeof value === "number") {
+        if (fieldSchema.min !== void 0 && value < fieldSchema.min) {
+          return `Field "${fieldName}" must be >= ${fieldSchema.min}.`;
+        }
+        if (fieldSchema.max !== void 0 && value > fieldSchema.max) {
+          return `Field "${fieldName}" must be <= ${fieldSchema.max}.`;
+        }
+      }
+      return null;
+    }
+    return `Field "${fieldName}" is not a scalar.`;
+  }
+  validateRecordScalar(valueType, value, fieldName) {
+    if (valueType === "json") return null;
+    if (typeof value !== valueType) {
+      return `Record field "${fieldName}" must be ${valueType}.`;
+    }
+    return null;
+  }
+  validateRecordObject(objectValue, valueType) {
+    if (valueType === "json") return null;
+    for (const [key, entry] of Object.entries(objectValue)) {
+      if (typeof entry !== valueType) {
+        return `Record key "${key}" must be ${valueType}.`;
+      }
+    }
+    return null;
+  }
+  validateObjectAgainstFields(objectValue, fields) {
+    const optionalMissing = [];
+    const extraFields = [];
+    const emptyOutcome = { optionalMissing, extraFields };
+    for (const [fieldName, fieldSchema] of Object.entries(fields)) {
+      if (fieldSchema.required) {
+        if (!(fieldName in objectValue)) {
+          return {
+            error: `Inline object is missing required field "${fieldName}".`,
+            ...emptyOutcome
+          };
+        }
+        continue;
+      }
+      if (!(fieldName in objectValue)) {
+        optionalMissing.push(fieldName);
+      }
+    }
+    for (const [fieldName, fieldValue] of Object.entries(objectValue)) {
+      const fieldSchema = fields[fieldName];
+      if (!fieldSchema) {
+        extraFields.push(fieldName);
+        continue;
+      }
+      const error = this.validateFinalFieldValue(
+        fieldSchema,
+        fieldValue,
+        fieldName,
+        "inline_object"
+      );
+      if (error) {
+        return { error, optionalMissing, extraFields };
+      }
+    }
+    return { error: null, optionalMissing, extraFields };
+  }
+  registerObjectContext(path) {
+    const fieldSchema = this.resolveParentFieldSchema(path);
+    if (!fieldSchema) return;
+    const pathKey = this.pathKey(path);
+    if (fieldSchema.type === "inline_object") {
+      this.inlineSchemas.set(pathKey, fieldSchema.fields);
+    }
+    if (fieldSchema.type === "record") {
+      this.recordSchemas.set(pathKey, fieldSchema.values);
+    }
+  }
+  resolveParentFieldSchema(path) {
+    const fieldKey = this.fieldKeyFromPath(path);
+    if (!fieldKey) return void 0;
+    const parentPath = path.slice(0, -1);
+    const parentKind = this.getObjectKindForPath(parentPath);
+    if (!parentKind) return void 0;
+    return this.lookupSchema(parentKind)?.fields[fieldKey];
+  }
+  getObjectKindForPath(path) {
+    return this.objectKinds.get(this.pathKey(path)) ?? (path.length === 0 ? this.rootKind || null : null);
+  }
+  getDirectObjectKind(objectPath) {
+    if (objectPath.length === 0) {
+      return this.rootKind || null;
+    }
+    return this.objectKinds.get(this.pathKey(objectPath)) ?? null;
+  }
+  isAllowedSchemaField(objectPath, fieldKey, objectKind) {
+    const pathKey = this.pathKey(objectPath);
+    const inlineFields = this.inlineSchemas.get(pathKey);
+    if (inlineFields) {
+      return fieldKey in inlineFields;
+    }
+    if (this.recordSchemas.has(pathKey)) {
+      return true;
+    }
+    const schema = this.lookupSchema(objectKind);
+    return !!schema?.fields[fieldKey];
+  }
+  parentFieldName(path) {
+    if (path.length === 0) return void 0;
+    const parent = path[path.length - 2];
+    return typeof parent === "string" ? parent : void 0;
+  }
+  fieldKeyFromPath(path) {
+    const last = path[path.length - 1];
+    return typeof last === "string" ? last : null;
+  }
+  isKindFieldPath(path) {
+    return path[path.length - 1] === KIND_KEY;
+  }
+  pathKey(path) {
+    return path.map((segment) => String(segment)).join(".");
+  }
+  lookupSchema(kind) {
+    return this.resolver.get(kind) ?? this.arrivedSchemas.get(kind);
+  }
+  fail(reason, at) {
+    if (this.failed) return;
+    this.failed = true;
+    this.emit({ type: "error", reason, at });
+  }
+  emit(event) {
+    this.options.onEvent(event);
+  }
+  currentFrame() {
+    return this.stack[this.stack.length - 1];
+  }
+};
+function createKindStreamParser(options) {
+  return new KindStreamParser(options);
+}
+
+// session/parse-session.ts
+var ParseSession = class {
+  identity;
+  parser;
+  tree = new IrTree();
+  listeners = /* @__PURE__ */ new Map();
+  anyListeners = /* @__PURE__ */ new Set();
+  unsubscribeSchemaArrivals;
+  fingerprinter = createFingerprinter();
+  ended = false;
+  constructor(options) {
+    this.identity = options.identity;
+    this.parser = createKindStreamParser({
+      schemas: options.schemas,
+      ...options.expectedRootKind !== void 0 && {
+        expectedRootKind: options.expectedRootKind
+      },
+      onEvent: (event) => {
+        this.tree.applyEvent(event);
+        options.onEvent?.(event);
+      }
+    });
+    this.unsubscribeSchemaArrivals = options.onSchemaArrived?.((kind, schema) => {
+      this.parser.notifySchemaArrived(kind, schema);
+      this.flushNotify();
+    }) ?? null;
+  }
+  /** The single writer's input. Does NOT notify — host flushes on its cadence. */
+  write(chunk) {
+    this.fingerprinter.push(chunk);
+    this.parser.push(chunk);
+  }
+  end() {
+    if (this.ended) return;
+    this.ended = true;
+    this.parser.end();
+  }
+  get isEnded() {
+    return this.ended;
+  }
+  get status() {
+    return this.tree.status;
+  }
+  getNode(pathKey) {
+    return this.tree.getNode(pathKey);
+  }
+  listNodes() {
+    return this.tree.listNodes();
+  }
+  isRawPath(pathKey) {
+    return this.tree.isRawPath(pathKey);
+  }
+  subscribe(pathKey, listener) {
+    const set = this.listeners.get(pathKey) ?? /* @__PURE__ */ new Set();
+    set.add(listener);
+    this.listeners.set(pathKey, set);
+    return () => {
+      set.delete(listener);
+      if (set.size === 0) this.listeners.delete(pathKey);
+    };
+  }
+  /** Structural subscription: fires when ANY node changes (mount lists). */
+  subscribeAny(listener) {
+    this.anyListeners.add(listener);
+    return () => {
+      this.anyListeners.delete(listener);
+    };
+  }
+  /** Publish dirty paths to their readers. Host-cadence, coalesced. */
+  flushNotify() {
+    if (!this.tree.hasDirty()) return;
+    const dirty = this.tree.drainDirty();
+    for (const pathKey of dirty) {
+      const set = this.listeners.get(pathKey);
+      if (!set) continue;
+      for (const listener of set) listener();
+    }
+    if (this.anyListeners.size > 0) {
+      for (const listener of this.anyListeners) listener();
+    }
+  }
+  buildEnvelope() {
+    return this.tree.buildEnvelope(this.fingerprinter.current());
+  }
+  dispose() {
+    this.unsubscribeSchemaArrivals?.();
+    this.listeners.clear();
+    this.anyListeners.clear();
+  }
+};
+
+// session/session-manager.ts
+var SESSIONS_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.content-ir.parse-sessions");
+var slotHolder = globalThis;
+var sessions = slotHolder[SESSIONS_SLOT] ??= /* @__PURE__ */ new Map();
+function openParseSession(options) {
+  const existing = sessions.get(options.identity);
+  if (existing && !existing.isEnded) {
+    throw new Error(
+      `content-ir: a writer is already open for identity "${options.identity}". One writer per stream identity \u2014 everyone else reads.`
+    );
+  }
+  existing?.dispose();
+  const session = new ParseSession(options);
+  sessions.set(options.identity, session);
+  return session;
+}
+function getParseSession(identity) {
+  return sessions.get(identity) ?? null;
+}
+function disposeParseSession(identity) {
+  const session = sessions.get(identity);
+  if (!session) return;
+  session.dispose();
+  sessions.delete(identity);
+}
+
+export { ParseSession, disposeParseSession, getParseSession, openParseSession };
+//# sourceMappingURL=session.js.map
+//# sourceMappingURL=session.js.map