@ai-matrx/content-ir 0.1.2 → 0.2.1

package/dist/index.js

@@ -398,16 +398,19 @@ var IrTree = class {
 
 // core/json-tokenizer.ts
 var JsonStreamTokenizer = class {
-  constructor(onToken) {
-    this.onToken = onToken;
-  }
-  onToken;
   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;
   }
@@ -630,16 +633,6 @@ function safeCopy(value) {
   }
 }
 var KindStreamParser = class {
-  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)
-    );
-  }
-  options;
   resolver;
   stack = [];
   objectKinds = /* @__PURE__ */ new Map();
@@ -674,6 +667,18 @@ var KindStreamParser = class {
   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 {
@@ -2767,6 +2772,12 @@ function storageToKindSchema(kind, shape) {
   }
   return { kind, fields };
 }
+var GENERIC_FALLBACK_COMPONENT_KEY = "generic_structured";
+function satisfies(resolved) {
+  return Boolean(
+    resolved?.isActive && resolved.componentKey !== GENERIC_FALLBACK_COMPONENT_KEY
+  );
+}
 var ajv = new Ajv({ allErrors: true, strict: false });
 function stripKind(value) {
   if (Array.isArray(value)) return value.map(stripKind);
@@ -2780,6 +2791,14 @@ function stripKind(value) {
   }
   return value;
 }
+function describeAjvErrors(errors) {
+  return (errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim()).slice(0, 8);
+}
+function schemaDeclaresKind(emittedJsonSchema) {
+  if (!emittedJsonSchema || typeof emittedJsonSchema !== "object") return false;
+  const properties = emittedJsonSchema.properties;
+  return !!properties && typeof properties === "object" && KIND_KEY in properties;
+}
 function validateStructuralLeg(sample, emittedJsonSchema) {
   let validate;
   try {
@@ -2790,9 +2809,11 @@ function validateStructuralLeg(sample, emittedJsonSchema) {
       detail: `emitted_json_schema failed to compile: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const ok = validate(stripKind(sample));
-  if (ok) return { ok: true };
-  const errors = (validate.errors ?? []).map((e) => `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim()).slice(0, 8);
+  if (validate(sample)) return { ok: true };
+  const markedErrors = describeAjvErrors(validate.errors);
+  if (validate(stripKind(sample))) return { ok: true };
+  const strippedErrors = describeAjvErrors(validate.errors);
+  const errors = schemaDeclaresKind(emittedJsonSchema) ? markedErrors : strippedErrors;
   return { ok: false, detail: `sample failed schema: ${errors.join("; ")}` };
 }
 var SERVER_DATA_ANNOTATION_KEYS = /* @__PURE__ */ new Set(["language"]);
@@ -2842,16 +2863,18 @@ function validateRender(kind, sample, definition, resolvedComponent, dataOnly) {
       detail: "data-only contract kind \u2014 render leg is structurally inapplicable (n/a)"
     };
   }
-  if (!definition && !resolvedComponent?.isActive) {
+  const onlyFallback = resolvedComponent?.isActive && resolvedComponent.componentKey === GENERIC_FALLBACK_COMPONENT_KEY;
+  const noComponentDetail = onlyFallback ? `the only active role='output' component for kind "${kind}" is '${GENERIC_FALLBACK_COMPONENT_KEY}' \u2014 that IS the generic viewer, i.e. no component. A reader would get a key/value dump. Author a real source='db' component (or register a compiled one), then retire the generic row.` : null;
+  if (!definition && !satisfies(resolvedComponent)) {
     return {
       ok: false,
-      detail: `kind "${kind}" has no component (not in the compiled registry, and no active role='output' kind_component row) \u2014 nothing to render`
+      detail: noComponentDetail ?? `kind "${kind}" has no component (not in the compiled registry, and no active role='output' kind_component row) \u2014 nothing to render`
     };
   }
-  if (definition && !definition.legacyBlockType && !definition.component && !definition.toLegacyServerData && !resolvedComponent?.isActive) {
+  if (definition && !definition.legacyBlockType && !definition.component && !definition.toLegacyServerData && !satisfies(resolvedComponent)) {
     return {
       ok: false,
-      detail: `kind "${kind}" has no component (no compiled legacyBlockType/component facet, and no active role='output' kind_component row) \u2014 nothing to render`
+      detail: noComponentDetail ?? `kind "${kind}" has no component (no compiled legacyBlockType/component facet, and no active role='output' kind_component row) \u2014 nothing to render`
     };
   }
   if (definition?.toLegacyServerData) {
@@ -2875,7 +2898,7 @@ function validateRender(kind, sample, definition, resolvedComponent, dataOnly) {
     }
     return { ok: true };
   }
-  const satisfier = definition?.legacyBlockType ? `compiled component "${definition.legacyBlockType}"` : definition?.component ? "compiled component facet" : resolvedComponent ? `resolved ${resolvedComponent.source} component "${resolvedComponent.componentKey}"` : "component";
+  const satisfier = definition?.legacyBlockType ? `compiled component "${definition.legacyBlockType}"` : definition?.component ? "compiled component facet" : satisfies(resolvedComponent) && resolvedComponent ? `resolved ${resolvedComponent.source} component "${resolvedComponent.componentKey}"` : "component";
   return {
     ok: true,
     detail: `bridgeless kind \u2014 ${satisfier} parses content itself; full DOM render check deferred to an RTL harness`
@@ -4111,6 +4134,288 @@ function kindSchemaToJsonSchema(kind, resolve, options = {}) {
   return { name: kind, schema: { ...rootNode, $defs: defs }, strict, unresolved };
 }
 
-export { IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, ParseSession, ROOT_STORAGE_NAME, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isScalarArrayType, kindSchemaToJsonSchema, kindSchemaToStorage, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readObjectKind, reconstructRegionValue, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, xmlDiscriminator };
+// 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```";
+}
+
+export { IR_ENVELOPE_CACHE_VERSION, IR_ENVELOPE_KEY, IR_PARTIAL_KEY, IR_VERSION, IrTree, JSON_DISCRIMINATOR, JsonStreamTokenizer, KIND_KEY, KindStorageError, KindStreamParser, NODE_OUTCOME_KIND, ParseSession, ROOT_STORAGE_NAME, RUN_RESULT_KIND, advancePartialKind, buildAgentSchemaWithRenderBlockSupport, buildCompliantKindSnapshot, classifyInboundEnvelopeMetadata, collectReferencedKinds, collectSchemaReferencedKinds, compareWithExistingKindSchema, convertAiSchemaToBlockFields, createFingerprinter, createKindStreamParser, describeDualGateFailure, disposeParseSession, emitPayloadFence, emitPayloadJson, emptyValueForFieldSchema, envelopeCacheFromEnvelopes, envelopeFromCompleteValue, fenceDiscriminator, fieldsToDbPayload, fingerprintText, formatBlockLabel, getParseSession, injectKindIntoObjectSchema, irPathIsUnderOrEqual, irPathKey, irPathLabel, irPathsEqual, isCanonicalBlockIR, isDuplicateBlockSlug, isEmptyResidue, isIrEnvelopeCache, isJsonAnyField, isProvisionalKind, isScalarArrayType, isTerminalKindEvent, kindSchemaToJsonSchema, kindSchemaToStorage, kindVerdictOf, makePartialKindStalenessGate, mergeResidueIntoValue, normalizeAiSchemaInput, normalizeJsonRegion, openParseSession, readEnvelope, readNodeOutcomeValue, readObjectKind, readOutputRef, readPartialKindEvent, readRunResultValue, reconstructRegionValue, rehydrateNodeOutcome, rehydrateRunResult, reuseEnvelopeIfCurrent, runKindDualGate, runSchemaConversion, sanitizeInboundEnvelopeMetadata, sanitizeInboundPartialKindMetadata, scalarArrayItemType, schemaLayoutMode, schemaStructureDepth, setJsonRootKeyLookup, storageToKindSchema, stripKindDeep, validateBlockSchemaSavePlan, validateStructuralLeg, withRootKind, xmlDiscriminator };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map