@ai-matrx/content-ir 0.8.0 → 0.10.0

package/dist/core.cjs

@@ -0,0 +1,2493 @@
+'use strict';
+
+// core/ir-types.ts
+var IR_VERSION = 1;
+var IR_ENVELOPE_KEY = "__ir";
+function irPathKey(path) {
+  return path.map((segment) => String(segment)).join(".");
+}
+function irPathsEqual(left, right) {
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i++) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+function irPathIsUnderOrEqual(path, prefix) {
+  if (path.length < prefix.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (path[i] !== prefix[i]) return false;
+  }
+  return true;
+}
+function irPathLabel(path) {
+  if (path.length === 0) return "root";
+  const parts = [];
+  for (const segment of path) {
+    if (typeof segment === "number") {
+      parts[parts.length - 1] += `[${segment}]`;
+    } else {
+      parts.push(String(segment));
+    }
+  }
+  return parts.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/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
+};
+function xmlDiscriminator(tag) {
+  return { format: "xml", tag };
+}
+function fenceDiscriminator(language) {
+  return { format: "fence", language };
+}
+
+// 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/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 };
+}
+function mergeResidueIntoValue(value, residue) {
+  if (!residue?.extra) return value;
+  return { ...value, ...residue.extra };
+}
+
+// core/kind-parser.ts
+var jsonRootKeyLookup = null;
+function setJsonRootKeyLookup(lookup) {
+  jsonRootKeyLookup = lookup;
+}
+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);
+}
+
+// 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)}`;
+    }
+  };
+}
+function fingerprintText(source) {
+  const hasher = createFingerprinter();
+  hasher.push(source);
+  return hasher.current();
+}
+
+// core/normalize.ts
+function isCanonicalBlockIR(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return candidate.v === IR_VERSION && typeof candidate.fingerprint === "string" && typeof candidate.engine === "string" && typeof candidate.root === "object" && candidate.root !== null && candidate.root.role === "structured";
+}
+function reuseEnvelopeIfCurrent(source, candidate) {
+  if (!isCanonicalBlockIR(candidate)) return null;
+  return candidate.fingerprint === fingerprintText(source) ? candidate : null;
+}
+function envelopeFromCompleteValue(value, kind, options) {
+  return {
+    v: IR_VERSION,
+    engine: "fe-kind-parser",
+    fingerprint: fingerprintText(JSON.stringify(value)),
+    root: {
+      role: "structured",
+      kind,
+      kindState: "resolved",
+      discriminator: options?.discriminator ?? { format: "json", key: KIND_KEY },
+      path: [],
+      status: "complete",
+      value,
+      residue: null
+    }
+  };
+}
+function normalizeJsonRegion(source, options) {
+  const reused = reuseEnvelopeIfCurrent(source, options.existing);
+  if (reused) return reused;
+  const tree = new IrTree();
+  const parser = createKindStreamParser({
+    schemas: options.schemas,
+    ...options.expectedRootKind !== void 0 && {
+      expectedRootKind: options.expectedRootKind
+    },
+    onEvent(event) {
+      tree.applyEvent(event);
+    }
+  });
+  parser.push(source);
+  parser.end();
+  return tree.buildEnvelope(fingerprintText(source));
+}
+
+// core/envelope-cache.ts
+var IR_ENVELOPE_CACHE_VERSION = 1;
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isIrEnvelopeCache(value) {
+  if (!isRecord2(value)) return false;
+  if (value.v !== IR_ENVELOPE_CACHE_VERSION) return false;
+  if (!isRecord2(value.blocks)) return false;
+  const entries = Object.entries(value.blocks);
+  if (entries.length === 0) return false;
+  for (const [fingerprint, envelope] of entries) {
+    if (!isCanonicalBlockIR(envelope)) return false;
+    if (envelope.fingerprint !== fingerprint) return false;
+    if (envelope.root.status !== "complete") return false;
+  }
+  return true;
+}
+function envelopeCacheFromEnvelopes(envelopes) {
+  let blocks = null;
+  for (const envelope of envelopes) {
+    if (!isCanonicalBlockIR(envelope)) continue;
+    if (envelope.root.status !== "complete") continue;
+    (blocks ??= {})[envelope.fingerprint] = envelope;
+  }
+  return blocks ? { v: IR_ENVELOPE_CACHE_VERSION, blocks } : null;
+}
+
+// core/envelope-read.ts
+function readEnvelope(metadata) {
+  const candidate = metadata?.[IR_ENVELOPE_KEY];
+  return isCanonicalBlockIR(candidate) ? candidate : null;
+}
+function classifyInboundEnvelopeMetadata(metadata) {
+  if (!metadata || !(IR_ENVELOPE_KEY in metadata)) {
+    return { outcome: "absent", metadata: metadata ?? void 0 };
+  }
+  const candidate = metadata[IR_ENVELOPE_KEY];
+  if (isCanonicalBlockIR(candidate)) {
+    return { outcome: "valid", metadata, envelope: candidate };
+  }
+  const engine = typeof candidate === "object" && candidate !== null && typeof candidate.engine === "string" ? candidate.engine : "unknown";
+  const { [IR_ENVELOPE_KEY]: _dropped, ...rest } = metadata;
+  return { outcome: "malformed", metadata: rest, engine, raw: candidate };
+}
+function sanitizeInboundEnvelopeMetadata(metadata, context, hooks = {}) {
+  const verdict = classifyInboundEnvelopeMetadata(metadata);
+  if (verdict.outcome === "valid") {
+    hooks.seedEnvelope?.(verdict.envelope);
+    return verdict.metadata;
+  }
+  if (verdict.outcome === "malformed") {
+    hooks.reportMalformed?.({
+      blockId: context.blockId,
+      engine: verdict.engine,
+      raw: verdict.raw
+    });
+    return verdict.metadata;
+  }
+  return verdict.metadata;
+}
+
+// core/envelope-value.ts
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reconstructRegionValue(envelope) {
+  const cloned = structuredClone(envelope.root.value);
+  const applyExtras = (target, extras) => {
+    if (!extras) return;
+    for (const [key, value] of Object.entries(extras)) {
+      target[key] = structuredClone(value);
+    }
+  };
+  applyExtras(cloned, envelope.root.residue?.extra);
+  for (const [pathKey, meta] of Object.entries(envelope.nodeIndex ?? {})) {
+    const residue = meta.residue;
+    if (!residue || isEmptyResidue(residue) || !residue.extra) continue;
+    const segments = pathKey.split(".");
+    let cursor = cloned;
+    for (const segment of segments) {
+      if (Array.isArray(cursor)) {
+        cursor = cursor[Number(segment)];
+      } else if (isRecord3(cursor)) {
+        cursor = cursor[segment];
+      } else {
+        cursor = void 0;
+        break;
+      }
+    }
+    if (isRecord3(cursor)) {
+      applyExtras(cursor, residue.extra);
+    }
+  }
+  return cloned;
+}
+function stripKindDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(stripKindDeep);
+  }
+  if (isRecord3(value)) {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (key === KIND_KEY) continue;
+      out[key] = stripKindDeep(child);
+    }
+    return out;
+  }
+  return value;
+}
+
+// utils/text-case-converter.ts
+var DEFAULT_WORD_REPLACEMENTS = {
+  // Acronyms & initialisms
+  "api": "API",
+  "apis": "APIs",
+  "ui": "UI",
+  "ux": "UX",
+  "id": "ID",
+  "ids": "IDs",
+  "qr": "QR",
+  "ssr": "SSR",
+  "csr": "CSR",
+  "ssg": "SSG",
+  "isr": "ISR",
+  "spa": "SPA",
+  "pwa": "PWA",
+  "sdk": "SDK",
+  "sdks": "SDKs",
+  "cli": "CLI",
+  "tty": "TTY",
+  "repl": "REPL",
+  "ci": "CI",
+  "cd": "CD",
+  "cpu": "CPU",
+  "cpus": "CPUs",
+  "gpu": "GPU",
+  "gpus": "GPUs",
+  "ram": "RAM",
+  "rom": "ROM",
+  "ssd": "SSD",
+  "ssds": "SSDs",
+  "hdd": "HDD",
+  "hdds": "HDDs",
+  "kpi": "KPI",
+  "kpis": "KPIs",
+  "sla": "SLA",
+  "slas": "SLAs",
+  "slo": "SLO",
+  "slos": "SLOs",
+  "sli": "SLI",
+  "slis": "SLIs",
+  "dom": "DOM",
+  // Web, formats, protocols
+  "url": "URL",
+  "urls": "URLs",
+  "uri": "URI",
+  "uris": "URIs",
+  "http": "HTTP",
+  "https": "HTTPS",
+  "html": "HTML",
+  "css": "CSS",
+  "json": "JSON",
+  "yaml": "YAML",
+  "yml": "YML",
+  "toml": "TOML",
+  "csv": "CSV",
+  "pdf": "PDF",
+  "tsv": "TSV",
+  "jpg": "JPG",
+  "jpeg": "JPEG",
+  "png": "PNG",
+  "gif": "GIF",
+  "webp": "WebP",
+  "heic": "HEIC",
+  "heif": "HEIF",
+  "bmp": "BMP",
+  "tiff": "TIFF",
+  "ico": "ICO",
+  "xml": "XML",
+  "sql": "SQL",
+  "db": "DB",
+  "dbs": "DBs",
+  "nosql": "NoSQL",
+  "graphql": "GraphQL",
+  "grpc": "gRPC",
+  "rest": "REST",
+  "restful": "RESTful",
+  "websocket": "WebSocket",
+  "websockets": "WebSockets",
+  "webrtc": "WebRTC",
+  // Networking
+  "ip": "IP",
+  "ipv4": "IPv4",
+  "ipv6": "IPv6",
+  "dns": "DNS",
+  "dhcp": "DHCP",
+  "nat": "NAT",
+  "tcp": "TCP",
+  "udp": "UDP",
+  "icmp": "ICMP",
+  "ttl": "TTL",
+  "lan": "LAN",
+  "wan": "WAN",
+  "vlan": "VLAN",
+  "cdn": "CDN",
+  "ftp": "FTP",
+  "ssh": "SSH",
+  "tls": "TLS",
+  "ssl": "SSL",
+  // Security & crypto
+  "jwt": "JWT",
+  "jws": "JWS",
+  "jwe": "JWE",
+  "hmac": "HMAC",
+  "rsa": "RSA",
+  "ecdsa": "ECDSA",
+  "aes": "AES",
+  "pbkdf2": "PBKDF2",
+  "argon2": "Argon2",
+  "scrypt": "scrypt",
+  "totp": "TOTP",
+  "hotp": "HOTP",
+  "mfa": "MFA",
+  "2fa": "2FA",
+  "csrf": "CSRF",
+  "xss": "XSS",
+  "ssrf": "SSRF",
+  "rce": "RCE",
+  "dos": "DoS",
+  "ddos": "DDoS",
+  "mitm": "MITM",
+  "csp": "CSP",
+  "cors": "CORS",
+  "pii": "PII",
+  "phi": "PHI",
+  "gdpr": "GDPR",
+  "ccpa": "CCPA",
+  "hipaa": "HIPAA",
+  "rfc": "RFC",
+  // Platforms, langs, tools (single-token)
+  "javascript": "JavaScript",
+  "typescript": "TypeScript",
+  "jsx": "JSX",
+  "tsx": "TSX",
+  "node": "Node",
+  // (used when tokenized alone)
+  "deno": "Deno",
+  "bun": "Bun",
+  "react": "React",
+  "nextjs": "Next.js",
+  // if your tokenizer drops dots, keep this
+  "nodejs": "Node.js",
+  "postgresql": "PostgreSQL",
+  "postgres": "Postgres",
+  "mysql": "MySQL",
+  "sqlite": "SQLite",
+  "redis": "Redis",
+  "supabase": "Supabase",
+  "docker": "Docker",
+  "kubernetes": "Kubernetes",
+  "k8s": "Kubernetes",
+  "helm": "Helm",
+  "npm": "npm",
+  "pnpm": "pnpm",
+  "yarn": "Yarn",
+  "eslint": "ESLint",
+  "prettier": "Prettier",
+  "vite": "Vite",
+  "webpack": "Webpack",
+  "babel": "Babel",
+  // OS & vendors
+  "macos": "macOS",
+  "ios": "iOS",
+  "ipados": "iPadOS",
+  "watchos": "watchOS",
+  "tvos": "tvOS",
+  "windows": "Windows",
+  "linux": "Linux",
+  "ubuntu": "Ubuntu",
+  "github": "GitHub",
+  "gitlab": "GitLab",
+  "bitbucket": "Bitbucket",
+  // Data & analytics
+  "etl": "ETL",
+  "elt": "ELT",
+  "olap": "OLAP",
+  "oltp": "OLTP",
+  "bi": "BI",
+  // Time & locales
+  "utc": "UTC",
+  "gmt": "GMT",
+  "pst": "PST",
+  "pdt": "PDT",
+  "pt": "PT",
+  // Common “small words” to keep lowercase (unless first/last word)
+  "or": "or",
+  "and": "and",
+  "the": "the",
+  "of": "of",
+  "in": "in",
+  "to": "to",
+  "with": "with",
+  "as": "as",
+  "by": "by",
+  "for": "for",
+  "on": "on",
+  "at": "at",
+  "up": "up",
+  "a": "a",
+  "an": "an",
+  "is": "is",
+  "are": "are",
+  "was": "was",
+  "were": "were",
+  "be": "be",
+  "but": "but",
+  "nor": "nor",
+  "so": "so",
+  "yet": "yet",
+  "per": "per",
+  "via": "via",
+  // Latin abbreviations (tokenized as words in some pipelines)
+  "eg": "e.g.",
+  "ie": "i.e.",
+  "etc": "etc.",
+  "aka": "aka",
+  "vs": "vs.",
+  "v": "v.",
+  // Client abbreviations
+  "CIC": "CIC",
+  "AGR": "AGR",
+  "AGER": "AGER",
+  "DD": "DD",
+  "TS": "TS",
+  "TM": "TM",
+  "arman": "Arman"
+};
+var DEFAULT_OPTIONS = {
+  textCase: "title",
+  wordReplacements: DEFAULT_WORD_REPLACEMENTS,
+  trim: true
+};
+function formatText(text, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  if (!text) return "";
+  let normalized = text.replace(/_/g, " ").replace(/-/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\s+/g, " ");
+  if (opts.trim) {
+    normalized = normalized.trim();
+  }
+  let caseTransformed = normalized;
+  switch (opts.textCase) {
+    case "title":
+      caseTransformed = normalized.replace(
+        /\w\S*/g,
+        (word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+      );
+      break;
+    case "sentence":
+      if (normalized.length > 0) {
+        caseTransformed = normalized.charAt(0).toUpperCase() + normalized.slice(1).toLowerCase();
+      }
+      break;
+    case "lower":
+      caseTransformed = normalized.toLowerCase();
+      break;
+    case "upper":
+      caseTransformed = normalized.toUpperCase();
+      break;
+  }
+  let result = caseTransformed;
+  if (opts.wordReplacements) {
+    Object.entries(opts.wordReplacements).forEach(([key, value]) => {
+      const regex = new RegExp(`\\b${key}\\b`, "gi");
+      result = result.replace(regex, value);
+    });
+  }
+  return result;
+}
+
+// core/schema-structure.ts
+function formatBlockLabel(key) {
+  return formatText(key, { textCase: "title" });
+}
+function schemaStructureDepth(schema, allSchemas, visiting = /* @__PURE__ */ new Set()) {
+  if (visiting.has(schema.kind)) return 0;
+  visiting.add(schema.kind);
+  let max = 0;
+  for (const field of Object.values(schema.fields)) {
+    max = Math.max(max, fieldStructureDepth(field, allSchemas, visiting));
+  }
+  visiting.delete(schema.kind);
+  return max;
+}
+function fieldStructureDepth(field, allSchemas, visiting) {
+  switch (field.type) {
+    case "array": {
+      let itemMax = 0;
+      for (const itemKind of field.itemKinds) {
+        const itemSchema = allSchemas[itemKind];
+        itemMax = Math.max(
+          itemMax,
+          itemSchema ? 1 + schemaStructureDepth(itemSchema, allSchemas, visiting) : 1
+        );
+      }
+      return itemMax;
+    }
+    case "object": {
+      const ref = allSchemas[field.kind];
+      return ref ? 1 + schemaStructureDepth(ref, allSchemas, visiting) : 1;
+    }
+    case "inline_object": {
+      let nested = 0;
+      for (const child of Object.values(field.fields)) {
+        nested = Math.max(
+          nested,
+          fieldStructureDepth(child, allSchemas, visiting)
+        );
+      }
+      return nested > 0 ? 1 + nested : 1;
+    }
+    default:
+      return 0;
+  }
+}
+function schemaLayoutMode(schema, allSchemas) {
+  const depth = schemaStructureDepth(schema, allSchemas);
+  if (depth <= 0) return "flat";
+  if (depth === 1) return "grid";
+  return "nested";
+}
+
+exports.IR_ENVELOPE_CACHE_VERSION = IR_ENVELOPE_CACHE_VERSION;
+exports.IR_ENVELOPE_KEY = IR_ENVELOPE_KEY;
+exports.IR_VERSION = IR_VERSION;
+exports.IrTree = IrTree;
+exports.JSON_DISCRIMINATOR = JSON_DISCRIMINATOR;
+exports.JsonStreamTokenizer = JsonStreamTokenizer;
+exports.KIND_KEY = KIND_KEY;
+exports.KindStreamParser = KindStreamParser;
+exports.buildCompliantKindSnapshot = buildCompliantKindSnapshot;
+exports.classifyInboundEnvelopeMetadata = classifyInboundEnvelopeMetadata;
+exports.createFingerprinter = createFingerprinter;
+exports.createKindStreamParser = createKindStreamParser;
+exports.emptyValueForFieldSchema = emptyValueForFieldSchema;
+exports.envelopeCacheFromEnvelopes = envelopeCacheFromEnvelopes;
+exports.envelopeFromCompleteValue = envelopeFromCompleteValue;
+exports.fenceDiscriminator = fenceDiscriminator;
+exports.fingerprintText = fingerprintText;
+exports.formatBlockLabel = formatBlockLabel;
+exports.irPathIsUnderOrEqual = irPathIsUnderOrEqual;
+exports.irPathKey = irPathKey;
+exports.irPathLabel = irPathLabel;
+exports.irPathsEqual = irPathsEqual;
+exports.isCanonicalBlockIR = isCanonicalBlockIR;
+exports.isEmptyResidue = isEmptyResidue;
+exports.isIrEnvelopeCache = isIrEnvelopeCache;
+exports.isJsonAnyField = isJsonAnyField;
+exports.isScalarArrayType = isScalarArrayType;
+exports.mergeResidueIntoValue = mergeResidueIntoValue;
+exports.normalizeJsonRegion = normalizeJsonRegion;
+exports.readEnvelope = readEnvelope;
+exports.readObjectKind = readObjectKind;
+exports.reconstructRegionValue = reconstructRegionValue;
+exports.reuseEnvelopeIfCurrent = reuseEnvelopeIfCurrent;
+exports.sanitizeInboundEnvelopeMetadata = sanitizeInboundEnvelopeMetadata;
+exports.scalarArrayItemType = scalarArrayItemType;
+exports.schemaLayoutMode = schemaLayoutMode;
+exports.schemaStructureDepth = schemaStructureDepth;
+exports.setJsonRootKeyLookup = setJsonRootKeyLookup;
+exports.stripKindDeep = stripKindDeep;
+exports.xmlDiscriminator = xmlDiscriminator;
+//# sourceMappingURL=core.cjs.map
+//# sourceMappingURL=core.cjs.map