@ai-matrx/content-ir 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.0 — 2026-08-23
+
+- Added the `wire/` layer — the server→UI contracts every UI reads the same way:
+  - `wire/partial-kind` — the streaming partial-kinds channel (`__ir_partial`): `readPartialKindEvent`,
+    `sanitizeInboundPartialKindMetadata`, `advancePartialKind`, `makePartialKindStalenessGate`,
+    `isProvisionalKind`, `isTerminalKindEvent`, `IR_PARTIAL_KEY` + the event types.
+  - `wire/runtime-wrapper` — the `node_outcome` / `run_result` runtime-wrapper reader and THE `output_ref`
+    elision gate: `readOutputRef`, `rehydrateNodeOutcome`, `rehydrateRunResult`, `readNodeOutcomeValue`,
+    `readRunResultValue`, `kindVerdictOf`, `NODE_OUTCOME_KIND`, `RUN_RESULT_KIND` + the wrapper types.
+  - `wire/emit-payload` — the emit/render payload composer: `withRootKind`, `emitPayloadJson`, `emitPayloadFence`.
+- Brought the partial-kind suite pinned to the Python producer's generated fixture
+  (`__tests__/partial-kind-events.generated.json`, regenerated by aidream `scripts/generate_partial_kind_fixture.py`
+  and drift-gated by `packages/matrx-ai/tests/parity/test_partial_kind_fixture.py`) plus new pure suites for the
+  runtime-wrapper reader and the emit composer (196 tests).
+- Existing 0.1.x API unchanged.
+
 ## 0.1.2 — 2026-08-22
 
 - Added a CommonJS export condition for Jest and other require-based consumers.

package/README.md

@@ -11,6 +11,12 @@ import {
   createKindStreamParser,
   envelopeFromCompleteValue,
   validateStructuralLeg,
+  // wire layer (0.2.0): streaming partial kinds + runtime wrappers + emit payload
+  readPartialKindEvent,
+  makePartialKindStalenessGate,
+  rehydrateNodeOutcome,
+  rehydrateRunResult,
+  withRootKind,
 } from "@ai-matrx/content-ir";
 ```
 

package/dist/index.cjs

@@ -4117,8 +4117,291 @@ function kindSchemaToJsonSchema(kind, resolve, options = {}) {
   return { name: kind, schema: { ...rootNode, $defs: defs }, strict, unresolved };
 }
 
+// wire/partial-kind.ts
+var IR_PARTIAL_KEY = "__ir_partial";
+var PARTIAL_STATES = [
+  "partial",
+  "superseded",
+  "retracted"
+];
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readPath(value) {
+  if (!Array.isArray(value)) return null;
+  return value.every(
+    (segment) => typeof segment === "string" || typeof segment === "number"
+  ) ? value : null;
+}
+function readDiscriminator(value) {
+  if (!isRecord5(value)) return null;
+  if (value.format === "json" && value.key === "__kind") {
+    return { format: "json", key: "__kind" };
+  }
+  if (value.format === "xml" && typeof value.tag === "string") {
+    return { format: "xml", tag: value.tag };
+  }
+  if (value.format === "fence" && typeof value.language === "string") {
+    return { format: "fence", language: value.language };
+  }
+  return null;
+}
+function readResidue(value) {
+  if (value === null) return null;
+  if (!isRecord5(value)) return void 0;
+  const extra = value.extra;
+  const optionalMissing = value.optionalMissing;
+  const notices = value.notices;
+  if (extra !== null && !isRecord5(extra)) return void 0;
+  if (optionalMissing !== null && (!Array.isArray(optionalMissing) || !optionalMissing.every((item) => typeof item === "string"))) {
+    return void 0;
+  }
+  if (notices !== null && (!Array.isArray(notices) || !notices.every(
+    (notice) => isRecord5(notice) && typeof notice.code === "string" && typeof notice.message === "string" && (notice.at === void 0 || typeof notice.at === "number")
+  ))) {
+    return void 0;
+  }
+  return { extra, optionalMissing, notices };
+}
+function readPartialKindEvent(metadata) {
+  if (!isRecord5(metadata)) return null;
+  const candidate = metadata[IR_PARTIAL_KEY];
+  if (!isRecord5(candidate)) return null;
+  if (candidate.v !== IR_VERSION) return null;
+  if (typeof candidate.engine !== "string") return null;
+  if (typeof candidate.seq !== "number" || !Number.isFinite(candidate.seq)) {
+    return null;
+  }
+  const state = candidate.state;
+  if (typeof state !== "string") return null;
+  if (!PARTIAL_STATES.includes(state)) return null;
+  if (state === "partial") {
+    const root = candidate.root;
+    if (!isRecord5(root)) return null;
+    if (root.role !== "structured") return null;
+    if (root.status !== "streaming") return null;
+    if (root.kindState !== "speculative") return null;
+    if (typeof root.kind !== "string" || !root.kind) return null;
+    if (!isRecord5(root.value)) return null;
+    const discriminator = readDiscriminator(root.discriminator);
+    const path = readPath(root.path);
+    const residue = readResidue(root.residue);
+    if (discriminator === null || path === null || residue === void 0) {
+      return null;
+    }
+    return {
+      v: IR_VERSION,
+      engine: candidate.engine,
+      state: "partial",
+      seq: candidate.seq,
+      fingerprint: typeof candidate.fingerprint === "string" ? candidate.fingerprint : "",
+      root: {
+        role: "structured",
+        kind: root.kind,
+        kindState: "speculative",
+        discriminator,
+        path,
+        status: "streaming",
+        value: root.value,
+        residue
+      }
+    };
+  }
+  if (typeof candidate.kind !== "string" || !candidate.kind) return null;
+  if (state === "superseded") {
+    return {
+      v: IR_VERSION,
+      engine: candidate.engine,
+      state: "superseded",
+      seq: candidate.seq,
+      kind: candidate.kind
+    };
+  }
+  if (typeof candidate.reason !== "string" || !candidate.reason) return null;
+  if (candidate.becameKind !== null && typeof candidate.becameKind !== "string") {
+    return null;
+  }
+  if (candidate.becameBlockType !== null && typeof candidate.becameBlockType !== "string") {
+    return null;
+  }
+  return {
+    v: IR_VERSION,
+    engine: candidate.engine,
+    state: "retracted",
+    seq: candidate.seq,
+    kind: candidate.kind,
+    reason: candidate.reason,
+    becameKind: candidate.becameKind,
+    becameBlockType: candidate.becameBlockType
+  };
+}
+function sanitizeInboundPartialKindMetadata(metadata, context, hooks = {}) {
+  if (!isRecord5(metadata) || !(IR_PARTIAL_KEY in metadata)) {
+    return metadata ?? void 0;
+  }
+  if (readPartialKindEvent(metadata) !== null) return metadata;
+  const { [IR_PARTIAL_KEY]: raw, ...rest } = metadata;
+  hooks.reportMalformed?.({ blockId: context.blockId, raw });
+  return rest;
+}
+function isProvisionalKind(event) {
+  return event !== null && event.state === "partial";
+}
+function isTerminalKindEvent(event) {
+  return event !== null && (event.state === "superseded" || event.state === "retracted");
+}
+function advancePartialKind(seen, blockId, event) {
+  if (event === null) return null;
+  const last = seen[blockId];
+  if (last !== void 0 && event.seq <= last) return null;
+  return event;
+}
+function makePartialKindStalenessGate() {
+  const seen = {};
+  const lastAccepted = {};
+  const terminated = {};
+  return (blockId, metadata) => {
+    if (!isRecord5(metadata)) return metadata;
+    if (!(IR_PARTIAL_KEY in metadata)) {
+      const open = lastAccepted[blockId];
+      if (terminated[blockId] || open === void 0) return metadata;
+      return { ...metadata, [IR_PARTIAL_KEY]: open };
+    }
+    const parsed = readPartialKindEvent(metadata);
+    if (parsed === null) return metadata;
+    if (advancePartialKind(seen, blockId, parsed) !== null) {
+      seen[blockId] = parsed.seq;
+      lastAccepted[blockId] = metadata[IR_PARTIAL_KEY];
+      if (isTerminalKindEvent(parsed)) terminated[blockId] = true;
+      return metadata;
+    }
+    const carried = lastAccepted[blockId];
+    if (carried === void 0 || carried === metadata[IR_PARTIAL_KEY]) {
+      return metadata;
+    }
+    return { ...metadata, [IR_PARTIAL_KEY]: carried };
+  };
+}
+
+// wire/runtime-wrapper.ts
+var NODE_OUTCOME_KIND = "node_outcome";
+var RUN_RESULT_KIND = "run_result";
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(source, key) {
+  const value = source[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function num(source, key) {
+  const value = source[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function bool(source, key) {
+  const value = source[key];
+  return typeof value === "boolean" ? value : null;
+}
+function strings(source, key) {
+  const value = source[key];
+  if (!Array.isArray(value)) return null;
+  const out = value.filter((item) => typeof item === "string");
+  return out.length > 0 ? out : null;
+}
+function readOutputRef(frame, ref) {
+  let cursor = frame;
+  for (const segment of ref.split(".")) {
+    if (!isRecord6(cursor)) return void 0;
+    if (!(segment in cursor)) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function rehydrateNodeOutcome(raw, frame) {
+  if (!isRecord6(raw)) return null;
+  if (raw[KIND_KEY] !== NODE_OUTCOME_KIND) return null;
+  const ref = str(raw, "output_ref");
+  const resolved = ref === null ? void 0 : readOutputRef(frame, ref);
+  return readNodeOutcomeValue(
+    resolved === void 0 ? raw : { ...raw, output: resolved }
+  );
+}
+function readNodeOutcomeValue(raw) {
+  if (!isRecord6(raw)) return null;
+  const runId = str(raw, "run_id");
+  const nodeId = str(raw, "node_id");
+  if (!runId || !nodeId) return null;
+  const output = raw.output ?? null;
+  return {
+    __kind: NODE_OUTCOME_KIND,
+    run_id: runId,
+    node_id: nodeId,
+    workflow_id: str(raw, "workflow_id"),
+    step: num(raw, "step"),
+    attempt: num(raw, "attempt") ?? 1,
+    status: str(raw, "status") ?? "completed",
+    started_at: str(raw, "started_at"),
+    ended_at: str(raw, "ended_at"),
+    duration_ms: num(raw, "duration_ms"),
+    output_kind: str(raw, "output_kind"),
+    output_kind_ok: bool(raw, "output_kind_ok"),
+    output_kind_errors: strings(raw, "output_kind_errors"),
+    output
+  };
+}
+function rehydrateRunResult(raw, frame) {
+  if (!isRecord6(raw)) return null;
+  if (raw[KIND_KEY] !== RUN_RESULT_KIND) return null;
+  const ref = str(raw, "output_ref");
+  const resolved = ref === null ? void 0 : readOutputRef(frame, ref);
+  const outputs = Array.isArray(raw.outputs) ? raw.outputs.map((child) => rehydrateNodeOutcome(child, frame) ?? child) : [];
+  return readRunResultValue({
+    ...raw,
+    ...resolved === void 0 ? {} : { output: resolved },
+    outputs
+  });
+}
+function readRunResultValue(raw) {
+  if (!isRecord6(raw)) return null;
+  const runId = str(raw, "run_id");
+  if (!runId) return null;
+  const output = raw.output ?? null;
+  const outputs = Array.isArray(raw.outputs) ? raw.outputs.map((child) => readNodeOutcomeValue(child)).filter((child) => child !== null) : [];
+  return {
+    __kind: RUN_RESULT_KIND,
+    run_id: runId,
+    workflow_id: str(raw, "workflow_id"),
+    status: str(raw, "status") ?? "completed",
+    started_at: str(raw, "started_at"),
+    ended_at: str(raw, "ended_at"),
+    duration_ms: num(raw, "duration_ms"),
+    output_kind: str(raw, "output_kind"),
+    output,
+    outputs
+  };
+}
+function kindVerdictOf(wrapper) {
+  if (wrapper.output_kind_ok === true) return "passed";
+  if (wrapper.output_kind_ok === false) return "failed";
+  return "unchecked";
+}
+
+// wire/emit-payload.ts
+function withRootKind(kind, value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return { [KIND_KEY]: kind, ...value };
+  }
+  return value;
+}
+function emitPayloadJson(kind, value) {
+  return JSON.stringify(withRootKind(kind, value), null, 2);
+}
+function emitPayloadFence(kind, value) {
+  return "```json\n" + emitPayloadJson(kind, value) + "\n```";
+}
+
 exports.IR_ENVELOPE_CACHE_VERSION = IR_ENVELOPE_CACHE_VERSION;
 exports.IR_ENVELOPE_KEY = IR_ENVELOPE_KEY;
+exports.IR_PARTIAL_KEY = IR_PARTIAL_KEY;
 exports.IR_VERSION = IR_VERSION;
 exports.IrTree = IrTree;
 exports.JSON_DISCRIMINATOR = JSON_DISCRIMINATOR;
@@ -4126,8 +4409,11 @@ exports.JsonStreamTokenizer = JsonStreamTokenizer;
 exports.KIND_KEY = KIND_KEY;
 exports.KindStorageError = KindStorageError;
 exports.KindStreamParser = KindStreamParser;
+exports.NODE_OUTCOME_KIND = NODE_OUTCOME_KIND;
 exports.ParseSession = ParseSession;
 exports.ROOT_STORAGE_NAME = ROOT_STORAGE_NAME;
+exports.RUN_RESULT_KIND = RUN_RESULT_KIND;
+exports.advancePartialKind = advancePartialKind;
 exports.buildAgentSchemaWithRenderBlockSupport = buildAgentSchemaWithRenderBlockSupport;
 exports.buildCompliantKindSnapshot = buildCompliantKindSnapshot;
 exports.classifyInboundEnvelopeMetadata = classifyInboundEnvelopeMetadata;
@@ -4139,6 +4425,8 @@ exports.createFingerprinter = createFingerprinter;
 exports.createKindStreamParser = createKindStreamParser;
 exports.describeDualGateFailure = describeDualGateFailure;
 exports.disposeParseSession = disposeParseSession;
+exports.emitPayloadFence = emitPayloadFence;
+exports.emitPayloadJson = emitPayloadJson;
 exports.emptyValueForFieldSchema = emptyValueForFieldSchema;
 exports.envelopeCacheFromEnvelopes = envelopeCacheFromEnvelopes;
 exports.envelopeFromCompleteValue = envelopeFromCompleteValue;
@@ -4157,20 +4445,31 @@ exports.isDuplicateBlockSlug = isDuplicateBlockSlug;
 exports.isEmptyResidue = isEmptyResidue;
 exports.isIrEnvelopeCache = isIrEnvelopeCache;
 exports.isJsonAnyField = isJsonAnyField;
+exports.isProvisionalKind = isProvisionalKind;
 exports.isScalarArrayType = isScalarArrayType;
+exports.isTerminalKindEvent = isTerminalKindEvent;
 exports.kindSchemaToJsonSchema = kindSchemaToJsonSchema;
 exports.kindSchemaToStorage = kindSchemaToStorage;
+exports.kindVerdictOf = kindVerdictOf;
+exports.makePartialKindStalenessGate = makePartialKindStalenessGate;
 exports.mergeResidueIntoValue = mergeResidueIntoValue;
 exports.normalizeAiSchemaInput = normalizeAiSchemaInput;
 exports.normalizeJsonRegion = normalizeJsonRegion;
 exports.openParseSession = openParseSession;
 exports.readEnvelope = readEnvelope;
+exports.readNodeOutcomeValue = readNodeOutcomeValue;
 exports.readObjectKind = readObjectKind;
+exports.readOutputRef = readOutputRef;
+exports.readPartialKindEvent = readPartialKindEvent;
+exports.readRunResultValue = readRunResultValue;
 exports.reconstructRegionValue = reconstructRegionValue;
+exports.rehydrateNodeOutcome = rehydrateNodeOutcome;
+exports.rehydrateRunResult = rehydrateRunResult;
 exports.reuseEnvelopeIfCurrent = reuseEnvelopeIfCurrent;
 exports.runKindDualGate = runKindDualGate;
 exports.runSchemaConversion = runSchemaConversion;
 exports.sanitizeInboundEnvelopeMetadata = sanitizeInboundEnvelopeMetadata;
+exports.sanitizeInboundPartialKindMetadata = sanitizeInboundPartialKindMetadata;
 exports.scalarArrayItemType = scalarArrayItemType;
 exports.schemaLayoutMode = schemaLayoutMode;
 exports.schemaStructureDepth = schemaStructureDepth;
@@ -4179,6 +4478,7 @@ exports.storageToKindSchema = storageToKindSchema;
 exports.stripKindDeep = stripKindDeep;
 exports.validateBlockSchemaSavePlan = validateBlockSchemaSavePlan;
 exports.validateStructuralLeg = validateStructuralLeg;
+exports.withRootKind = withRootKind;
 exports.xmlDiscriminator = xmlDiscriminator;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map