@ai-matrx/content-ir 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -392,7 +392,6 @@ type KindStreamParserOptions = {
     expectedRootKind?: string;
 };
 declare class KindStreamParser {
-    private readonly options;
     private readonly resolver;
     private readonly stack;
     private readonly objectKinds;
@@ -427,6 +426,7 @@ declare class KindStreamParser {
     private rootKind;
     private rootDone;
     private failed;
+    private readonly options;
     constructor(options: KindStreamParserOptions);
     push(chunk: string): void;
     end(): void;
@@ -677,13 +677,13 @@ type JsonToken = {
     at: number;
 };
 declare class JsonStreamTokenizer {
-    private readonly onToken;
     private mode;
     private pos;
     private stringBuffer;
     private primitiveBuffer;
     private unicodeBuffer;
     private tokenStart;
+    private readonly onToken;
     constructor(onToken: (token: JsonToken) => void);
     get position(): number;
     push(chunk: string): void;
@@ -950,7 +950,18 @@ declare function sanitizeInboundEnvelopeMetadata(metadata: Record<string, unknow
  * a schema knew about it.
  */
 declare function reconstructRegionValue(envelope: CanonicalBlockIR): Record<string, unknown>;
-/** Deep-remove the __kind discriminator (the parser injects it into snapshots). */
+/**
+ * Deep-remove the `__kind` discriminator.
+ *
+ * 🚨 NOT A TRANSFORM FOR PLATFORM DATA. `__kind` is part of the data
+ * (KINDS_EVERYWHERE_PLAN §4.2) and stripping it from anything stored, passed or
+ * rendered was annihilated on 2026-08-23. This helper survives for exactly two
+ * shapes of caller, both of which are guarded:
+ *   - a SYMMETRIC COMPARISON that reduces both sides and returns a boolean;
+ *   - legacy validation TOLERANCE against a pre-2026-08-23 schema version.
+ * Guards: aidream `scripts/check_kind_marker_law.py`,
+ * matrx-frontend `pnpm check:kind-marker-law`.
+ */
 declare function stripKindDeep(value: unknown): unknown;
 
 /**
@@ -1406,8 +1417,8 @@ interface DualGateResult {
 /**
  * The structural leg, exported on its own so the shape doctor
  * (`shape-doctor.ts`) RECOMPUTES gate validation with the exact same ajv
- * config + `__kind`-stripping semantics as activation — never a parallel
- * validator. `sample` is `unknown` (not `Record`) because kind examples may
+ * config + marker semantics as activation (verbatim first, marker-free retry
+ * second) — never a parallel validator. `sample` is `unknown` (not `Record`) because kind examples may
  * legitimately be scalars/arrays (workflow I/O kinds like `text`/`number`).
  */
 declare function validateStructuralLeg(sample: unknown, emittedJsonSchema: unknown): LegResult;

package/dist/index.d.ts

@@ -392,7 +392,6 @@ type KindStreamParserOptions = {
     expectedRootKind?: string;
 };
 declare class KindStreamParser {
-    private readonly options;
     private readonly resolver;
     private readonly stack;
     private readonly objectKinds;
@@ -427,6 +426,7 @@ declare class KindStreamParser {
     private rootKind;
     private rootDone;
     private failed;
+    private readonly options;
     constructor(options: KindStreamParserOptions);
     push(chunk: string): void;
     end(): void;
@@ -677,13 +677,13 @@ type JsonToken = {
     at: number;
 };
 declare class JsonStreamTokenizer {
-    private readonly onToken;
     private mode;
     private pos;
     private stringBuffer;
     private primitiveBuffer;
     private unicodeBuffer;
     private tokenStart;
+    private readonly onToken;
     constructor(onToken: (token: JsonToken) => void);
     get position(): number;
     push(chunk: string): void;
@@ -950,7 +950,18 @@ declare function sanitizeInboundEnvelopeMetadata(metadata: Record<string, unknow
  * a schema knew about it.
  */
 declare function reconstructRegionValue(envelope: CanonicalBlockIR): Record<string, unknown>;
-/** Deep-remove the __kind discriminator (the parser injects it into snapshots). */
+/**
+ * Deep-remove the `__kind` discriminator.
+ *
+ * 🚨 NOT A TRANSFORM FOR PLATFORM DATA. `__kind` is part of the data
+ * (KINDS_EVERYWHERE_PLAN §4.2) and stripping it from anything stored, passed or
+ * rendered was annihilated on 2026-08-23. This helper survives for exactly two
+ * shapes of caller, both of which are guarded:
+ *   - a SYMMETRIC COMPARISON that reduces both sides and returns a boolean;
+ *   - legacy validation TOLERANCE against a pre-2026-08-23 schema version.
+ * Guards: aidream `scripts/check_kind_marker_law.py`,
+ * matrx-frontend `pnpm check:kind-marker-law`.
+ */
 declare function stripKindDeep(value: unknown): unknown;
 
 /**
@@ -1406,8 +1417,8 @@ interface DualGateResult {
 /**
  * The structural leg, exported on its own so the shape doctor
  * (`shape-doctor.ts`) RECOMPUTES gate validation with the exact same ajv
- * config + `__kind`-stripping semantics as activation — never a parallel
- * validator. `sample` is `unknown` (not `Record`) because kind examples may
+ * config + marker semantics as activation (verbatim first, marker-free retry
+ * second) — never a parallel validator. `sample` is `unknown` (not `Record`) because kind examples may
  * legitimately be scalars/arrays (workflow I/O kinds like `text`/`number`).
  */
 declare function validateStructuralLeg(sample: unknown, emittedJsonSchema: unknown): LegResult;

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`
@@ -4347,7 +4370,7 @@ function rehydrateRunResult(raw, frame) {
   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) : [];
+  const outputs = Array.isArray(raw.outputs) ? raw.outputs.map((child) => rehydrateNodeOutcome(child, frame)).filter((child) => child !== null) : [];
   return readRunResultValue({
     ...raw,
     ...resolved === void 0 ? {} : { output: resolved },