@ai-matrx/content-ir 0.18.5 → 0.19.0

package/CHANGELOG.md

@@ -1,10 +1,88 @@
 # Changelog
 
+## 0.19.0 — kind validation behind a schema-source port (Matrx Alchemy ALC-13)
+
+`/registry` (and the root) now export `createKindValidator(source, options?)`,
+`SchemaSourcePort`, `SchemaUnavailableReason`, `KindValidationResult`,
+`KindValidator` and `Json`. This is matrx-frontend's `validateAgainstKind`,
+moved into the package with its database read inverted: the host implements
+`SchemaSourcePort.kindSchema(kind, signal)` once and answers `{ schema,
+version }` or `{ unavailable: "kind_not_registered" | "schema_unavailable" |
+"schema_invalid" | "catalog_unreachable" }`. The verdict (`checked`, `ok`,
+`errors`, `degradedReason`) and its messages are unchanged; a source that
+throws reads as `catalog_unreachable`; an uncompilable schema reads as
+`schema_invalid`. The schema cache (30 s default, `invalidate`,
+`cachedSchema`) belongs to each validator instance, never to the module.
+
+### Consumer action
+
+matrx-frontend: implement `SchemaSourcePort` once over
+`content_ir.kind_definition`, build one validator with `createKindValidator`,
+repoint `features/surfaces/runtime/surface-writeback.ts` and
+`build-tool-injection.ts` to it, and delete
+`features/content-ir/registry/validate-against-kind.ts`.
+
+### Also in 0.19.0 — the RC-B3 fix round (RC-B3 lane)
+
+**Carries: RC-B3 fix round (verify-RC-B3 § 0.18.3) and RC-B3r R3 — builder:
+the RC-B3 standard lane.** (aidream 1174edb640 — RC-B10, the print lane —
+shipped in 0.18.3, and 094594d3a1 — the escaped-bracket rule, "Unreleased"
+below — shipped in 0.18.4; both under generic "no source changes" notes.)
+
+**`/source` streaming: settled means settled** (F3/F4). Found with the
+verifier's generator (realistic model fragments, every prefix, with and
+without a final newline), now permanent in `__tests__/source-attack.test.ts`
+(`LLM-fragment documents…`; 12,000 documents in `SOURCE_ATTACK=long`) plus 30
+pinned reproducers. `tokenizeSource(prefix, { streaming: true })` now also
+holds back, as prose or as an open island:
+- lines a box-drawing tree still forming at the end may claim as its root
+  label (the renderer's walk-back), the open last line included;
+- a paragraph cut short by a block that may still dissolve (a `$$` pair
+  closing on the open line, an unbalanced JSON head, any opener still
+  arriving on the open line) — and a footnote before one;
+- a block island ending on the open last line (inlines there are covered by
+  the tree-root hold);
+- a nested-fence closer found only by the strict-CommonMark retry, a tilde
+  fence whose inner block may still grow past it, braces that balance on
+  the open last line;
+- a code span that a blank-so-far or `>`-only open line may still close
+  (`pendingCodeSpanStart`, `source/code-ranges.ts`);
+- a block whose opener is provisional text, and a paragraph break there.
+The two lone-HTML-tag holdbacks (M-N6/N7) collapsed into the open-tail block
+rule. Each holdback turns the attack suite red on its own when removed
+(planted mutations on a scratch copy). The H2 exception is unchanged.
+
+**`/source` one-shot: a mid-line reasoning mention that never closes is prose**
+(RC-B3r R3). `grep -c '<thinking>' log.txt > count.txt` no longer opens an
+`xml_region` to the end of the text (the renderer shows prose). While a stream
+is still arriving it stays an open region (its closer may yet come).
+
+**`isSingleDollarMath` refuses shell and template variable chains** (F5):
+`$USER$HOSTNAME`, `A=$A$B`, `df$col$sub`, `$name.$ext`, `PS1='$USER@$HOST'`,
+`${a}${b}` stay text; `$n$th`, `$x_i$s` stay math. Measured read-only with
+matrx-frontend `scripts/measure-single-dollar-rule.ts` over 85,325 assistant
+messages and 4,317 notes: 0 spans gained, 3 lost (2 shell-variable-chain, 1
+template-literal), each an intended false positive; notes unchanged. New
+export `singleDollarAfter(text, close)` — the `after` argument the rule now
+reads (the following name, `\n` marking the end of text). Shared vectors grew
+(`__tests__/fixtures/single-dollar-vectors.json`, including the trailing-space
+guard case `echo $HOME $PATH`).
+- Consumer action: callers of `isSingleDollarMath` pass
+  `singleDollarAfter(text, close)` instead of `text[close + 1]` (a one-character
+  `after` still works; it just cannot see a variable chain).
+
+## 0.18.6
+
+Automatic republish. Despite the generated note, this version DID carry source
+changes: most of the 0.19.0 work above (through aidream cd35751bea). 0.19.0
+completes it (aidream d6241c5496, f1e9156e82).
+
 ## 0.18.5
 
-Automatic changed-only republish (docs/metadata drift since the last tag — see
-`git diff npm/content-ir-core/v0.18.4..npm/content-ir-core/v0.18.5 -- apps/shared/content-ir-core`).
-No source changes intended and no consumer action required.
+Automatic republish. Despite the generated note, this version DID carry source
+changes: the first half of the 0.19.0 work above (aidream edb3ec222d streaming
+holds, 3a1dae805c + 9a6c8db0b2 variable-chain guard, 60d3f61803
+`singleDollarAfter`). 0.19.0 supersedes it.
 
 ## 0.18.4
 
@@ -12,7 +90,7 @@ Automatic changed-only republish (docs/metadata drift since the last tag — see
 `git diff npm/content-ir-core/v0.18.3..npm/content-ir-core/v0.18.4 -- apps/shared/content-ir-core`).
 No source changes intended and no consumer action required.
 
-## Unreleased
+## Shipped in 0.18.4 (listed here before the release)
 
 **`/source`: THE escaped-bracket rule** (verify-RC-B4 R3-2). `\[ … \]` is a
 display-math island only when its content is real TeX — a command, `^ { } =
@@ -897,3 +975,4 @@ unchanged. Two things are worth doing at your next working session:
 - Promoted the existing verified Content IR twin into an independently installable public package.
 - Added ESM and declaration builds, package linting, packed-artifact analysis, and an isolated consumer canary.
 - Preserved all parser, session, normalization, schema conversion, and structural-validation behavior with the existing shared fixtures and fingerprint vectors.
+

package/README.md

@@ -15,7 +15,7 @@ The root export is the full surface and always will be. Since 0.10.0 each intern
 | `@ai-matrx/content-ir` | everything below |
 | `@ai-matrx/content-ir/core` | IR types + tree, JSON tokenizer, kind parser, snapshots, normalize, fingerprint, discriminator, envelope read/value/cache, region, schema structure |
 | `@ai-matrx/content-ir/session` | `ParseSession` and the one-writer-per-identity registry |
-| `@ai-matrx/content-ir/registry` | kind registry types, storage transform, the dual gate |
+| `@ai-matrx/content-ir/registry` | kind registry types, storage transform, the dual gate, `createKindValidator` over a host `SchemaSourcePort` |
 | `@ai-matrx/content-ir/convert` | kind ⇄ JSON Schema, the OpenAI structured-output converter |
 | `@ai-matrx/content-ir/wire` | partial-kind events, runtime wrapper readers, emit payload |
 | `@ai-matrx/content-ir/directives` | Kind Directives: slug grammar, the ONE decoder |
@@ -48,7 +48,9 @@ The package has no browser, React runtime, application store, database client, r
 `tokenizeSource(text)` reads stored text; `tokenizeSource(prefix, { streaming: true })`
 reads a message still arriving. In streaming mode anything the next bytes could
 still change is held back as plain prose (an open last line, an unclosed code
-span, a `$$` that can still pair, a footnote whose continuation is undecided, …),
+span, a `$$` that can still pair, a footnote whose continuation is undecided,
+lines a box-drawing tree still forming below may claim as its root label, a
+paragraph cut short by a block that may still dissolve, …),
 so **an island reported `complete` is the island the finished text has** — with
 ONE documented exception:
 

package/dist/index.cjs

@@ -2968,6 +2968,93 @@ function describeDualGateFailure(kind, result) {
   return `kind "${kind}" failed the dual gate \u2014 ${parts.join(" | ")}`;
 }
 
+// registry/kind-validator.ts
+var SCHEMA_COMPILE_FAILURE_PREFIX = "emitted_json_schema failed to compile:";
+var DEFAULT_CACHE_TTL_MS = 3e4;
+function unavailableMessage(kind, reason, detail) {
+  switch (reason) {
+    case "kind_not_registered":
+      return `kind "${kind}" is not registered in content_ir.kind_definition`;
+    case "schema_unavailable":
+      return `kind "${kind}" has no emitted_json_schema \u2014 nothing to validate against`;
+    case "schema_invalid":
+      return `kind "${kind}" has an uncompilable emitted_json_schema${detail ? `: ${detail}` : ""}`;
+    case "catalog_unreachable":
+      return `could not read the contract for kind "${kind}"${detail ? `: ${detail}` : ""}`;
+  }
+}
+function degraded(kind, reason, detail) {
+  return {
+    kind,
+    checked: false,
+    ok: false,
+    errors: [unavailableMessage(kind, reason, detail)],
+    degradedReason: reason
+  };
+}
+function createKindValidator(source, options = {}) {
+  const ttl = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  const now = options.now ?? Date.now;
+  const cache = /* @__PURE__ */ new Map();
+  async function fetchSchema(kind, signal) {
+    const cached = cache.get(kind);
+    if (cached && now() - cached.fetchedAt <= ttl) {
+      return { schema: cached.schema, version: cached.version };
+    }
+    let answer;
+    try {
+      answer = await source.kindSchema(kind, signal);
+    } catch (err) {
+      return {
+        unavailable: "catalog_unreachable",
+        detail: err instanceof Error ? err.message : String(err)
+      };
+    }
+    if ("unavailable" in answer) return { unavailable: answer.unavailable };
+    if (answer.schema == null) {
+      return { unavailable: "schema_unavailable" };
+    }
+    cache.set(kind, {
+      schema: answer.schema,
+      version: answer.version,
+      fetchedAt: now()
+    });
+    return answer;
+  }
+  return {
+    async validate(value, kind, signal = new AbortController().signal) {
+      if (!kind || typeof kind !== "string") {
+        throw new TypeError(
+          `validateAgainstKind: "kind" must be a non-empty slug (received ${typeof kind})`
+        );
+      }
+      const fetched = await fetchSchema(kind, signal);
+      if ("unavailable" in fetched) {
+        return degraded(kind, fetched.unavailable, fetched.detail);
+      }
+      const leg = validateStructuralLeg(value, fetched.schema);
+      if (!leg.ok && leg.detail?.startsWith(SCHEMA_COMPILE_FAILURE_PREFIX)) {
+        return degraded(kind, "schema_invalid", leg.detail);
+      }
+      return {
+        kind,
+        checked: true,
+        ok: leg.ok,
+        errors: leg.ok ? [] : [leg.detail ?? "validation failed"],
+        degradedReason: null
+      };
+    },
+    async cachedSchema(kind, signal = new AbortController().signal) {
+      const fetched = await fetchSchema(kind, signal);
+      return "unavailable" in fetched ? null : fetched.schema;
+    },
+    invalidate(kind) {
+      if (kind) cache.delete(kind);
+      else cache.clear();
+    }
+  };
+}
+
 // convert/openai-schema-converter.ts
 function requiredNullableFlags(required, nullable) {
   return {
@@ -5243,12 +5330,6 @@ function fenceOpenerOf(content) {
   return null;
 }
 var FenceReader = class {
-  constructor(opener, options = {}) {
-    this.opener = opener;
-    this.isJson = opener.char === "`" && opener.lang === "json";
-    this.nesting = opener.char === "`" && (options.nesting ?? fenceNestsInnerFences(opener.lang));
-    this.tildeCloser = opener.char === "~" ? new RegExp(`^ {0,3}~{${opener.ticks},}[ \\t]*$`) : null;
-  }
   opener;
   state = { inString: false, escaped: false };
   depth = 0;
@@ -5257,6 +5338,12 @@ var FenceReader = class {
   isJson;
   nesting;
   tildeCloser;
+  constructor(opener, options = {}) {
+    this.opener = opener;
+    this.isJson = opener.char === "`" && opener.lang === "json";
+    this.nesting = opener.char === "`" && (options.nesting ?? fenceNestsInnerFences(opener.lang));
+    this.tildeCloser = opener.char === "~" ? new RegExp(`^ {0,3}~{${opener.ticks},}[ \\t]*$`) : null;
+  }
   /** How many nested fences are open right now. */
   get nestedDepth() {
     return this.depth;
@@ -5874,9 +5961,6 @@ function isEscapedBacktick(line, offset) {
   return slashes % 2 === 1;
 }
 var XmlContainerTracker = class {
-  constructor(rootTag) {
-    this.rootTag = rootTag;
-  }
   rootTag;
   depth = 0;
   inComment = false;
@@ -5884,6 +5968,9 @@ var XmlContainerTracker = class {
   inlineTicks = 0;
   /** The open fence, read by THE one closer (source/code-ranges.ts). */
   fence = null;
+  constructor(rootTag) {
+    this.rootTag = rootTag;
+  }
   consumeLine(line, startOffset = 0) {
     if (this.fence) {
       if (this.fence.feed(line)) this.fence = null;
@@ -6095,6 +6182,23 @@ function isSplitterTreeLine(line) {
 }
 var MEDIA_REF_PREFIXES = ["[Image URL:", "[Video URL:", "[Audio URL:"];
 var Tokenizer = class {
+  text;
+  streaming;
+  meter;
+  n;
+  lineStarts = [];
+  contentEnds = [];
+  lineEnds = [];
+  blocks = [];
+  blockCache = /* @__PURE__ */ new Map();
+  /** Lazily built: for line i, first line j >= i where brace net from i drops to <= 0. */
+  braceStop = null;
+  braceNet = null;
+  /** Every occurrence offset of each needle searched so far (overlapping, like indexOf). */
+  occurrences = /* @__PURE__ */ new Map();
+  /** `$$` opener → closer for the pairs the core renders as math. */
+  mathPairs;
+  finder = (needle, from) => this.next(needle, from);
   constructor(text, streaming = false, meter = void 0) {
     this.text = text;
     this.streaming = streaming;
@@ -6141,23 +6245,6 @@ var Tokenizer = class {
       this.lineEnds.push(text.length);
     }
   }
-  text;
-  streaming;
-  meter;
-  n;
-  lineStarts = [];
-  contentEnds = [];
-  lineEnds = [];
-  blocks = [];
-  blockCache = /* @__PURE__ */ new Map();
-  /** Lazily built: for line i, first line j >= i where brace net from i drops to <= 0. */
-  braceStop = null;
-  braceNet = null;
-  /** Every occurrence offset of each needle searched so far (overlapping, like indexOf). */
-  occurrences = /* @__PURE__ */ new Map();
-  /** `$$` opener → closer for the pairs the core renders as math. */
-  mathPairs;
-  finder = (needle, from) => this.next(needle, from);
   /** Streaming: where provisional text starts (a pending `$$`), or +∞. */
   provisionalFrom = Number.POSITIVE_INFINITY;
   /** Streaming: the text ends in a lone CR whose LF has not arrived yet. */
@@ -6214,10 +6301,13 @@ var Tokenizer = class {
   /**
    * Streaming: an open block that may still turn back into prose — a `$$`
    * pair whose closer is on the open last line (prose after it makes it
-   * inline), or a JSON head whose braces have not balanced (it may never parse).
+   * inline), a JSON head whose braces have not balanced (it may never parse),
+   * or any opener that is itself still arriving on the open last line.
    */
   mayDissolve(block) {
-    return this.streaming && !block.complete && (block.type === "math_block" || block.type === "json");
+    if (!this.streaming || block.complete) return false;
+    if (block.type === "math_block" || block.type === "json") return true;
+    return this.isOpenTail(this.lineOf(block.start));
   }
   /** Streaming: paragraph ends where an undecided, dissolvable block cut them short. */
   undecidedBreaks = /* @__PURE__ */ new Set();
@@ -6238,6 +6328,12 @@ var Tokenizer = class {
     }
     return lo;
   }
+  /** How many whitespace characters open the text at `from` (up to `to`). */
+  leadingSpace(from, to) {
+    let k = from;
+    while (k < to && /\s/.test(this.text[k])) k++;
+    return k - from;
+  }
   isBlank(from, to) {
     return !NOT_WHITESPACE.test(this.text.slice(from, to));
   }
@@ -6262,6 +6358,10 @@ var Tokenizer = class {
         break;
       }
       const island = this.detectBlock(pos, li, true);
+      if (island && pos + this.leadingSpace(pos, this.contentEnds[li]) >= this.provisionalFrom) {
+        this.push({ kind: "prose", start: pos, end: this.n, island: null, inlines: [] });
+        break;
+      }
       if (island) {
         this.push({ kind: "island", start: island.start, end: island.end, island, inlines: [] });
         pos = island.end;
@@ -6291,12 +6391,6 @@ var Tokenizer = class {
     const last = this.lineStarts.length - 1;
     if (last < 0) return;
     if (this.isOpenTail(last)) {
-      const lineStart = this.lineStarts[last];
-      for (const block2 of this.blocks) {
-        if (block2.kind === "prose" && block2.end > lineStart) {
-          block2.inlines = block2.inlines.filter((inline) => inline.end <= lineStart);
-        }
-      }
       let b = this.blocks.length - 1;
       while (b >= 0 && this.blocks[b].kind === "gap") b--;
       const block = this.blocks[b];
@@ -6322,36 +6416,55 @@ var Tokenizer = class {
    * region…) is never a tree line nor a root label, so it stops the walk.
    */
   treeRootHoldFrom() {
-    const claimable = (k2) => {
+    const claimFrom = (k2) => {
+      const lineStart = this.lineStarts[k2];
+      const lineEnd = this.contentEnds[k2];
+      let pos = lineStart;
       for (; ; ) {
-        const block = this.blockAt(this.lineStarts[k2]);
-        if (!block || block.kind !== "island" || block.island?.fromParagraph === true) return true;
-        const opened = this.lineOf(block.start);
-        if (this.lineStarts[opened] === block.start || opened === k2) return false;
-        k2 = opened;
+        const block = this.blockAt(pos);
+        if (!block || block.kind !== "island" || !block.island) return pos;
+        if (block.island.fromParagraph === true || this.mayDissolve(block.island)) return pos;
+        if (block.start < lineStart) {
+          const opened = this.lineOf(block.start);
+          if (this.lineStarts[opened] !== block.start && claimFrom(opened) !== -1) return pos;
+          if (block.end >= lineEnd) return -1;
+          pos = block.end;
+          continue;
+        }
+        if (block.end >= lineEnd) return -1;
+        pos = block.end;
       }
     };
     let k = this.lineCount - 1;
     let start = this.lineCount;
+    let startPos = this.n;
     if (k >= 0 && this.isOpenTail(k)) {
-      if (!claimable(k)) return this.n;
+      const at = claimFrom(k);
+      if (at === -1) return this.n;
       start = k;
+      startPos = at;
       k--;
     }
-    for (; k >= 0 && claimable(k); k--) {
+    for (; k >= 0; k--) {
       this.tick(1);
+      const at = claimFrom(k);
+      if (at === -1) break;
       if (this.lineIsBlank(k)) continue;
       if (!TREE_GLYPHS.test(this.lineText(k))) break;
       start = k;
+      startPos = at;
     }
-    let root = start;
-    for (let j = start - 1; j >= 0 && claimable(j); j--) {
+    let rootPos = startPos;
+    for (let j = start - 1; j >= 0; j--) {
+      const at = claimFrom(j);
+      if (at === -1) break;
       const trimmed = this.lineText(j).trim();
       this.tick(trimmed.length + 1);
       if (!trimmed || isSplitterTreeLine(trimmed) || /^#{1,6}\s/.test(trimmed)) break;
-      root = j;
+      rootPos = at;
+      if (at > this.lineStarts[j]) break;
     }
-    return root < this.lineCount ? this.lineStarts[root] : this.n;
+    return rootPos;
   }
   /** The block (so far) containing offset `pos`, or null. */
   blockAt(pos) {
@@ -6883,7 +6996,9 @@ var Tokenizer = class {
       const block = this.detectBlock(this.lineStarts[k], k, false);
       if (block) {
         breakLine = k;
-        if (this.mayDissolve(block)) this.undecidedBreaks.add(end);
+        if (this.mayDissolve(block) || this.streaming && block.start >= this.provisionalFrom) {
+          this.undecidedBreaks.add(end);
+        }
         break;
       }
       end = this.contentEnds[k];
@@ -7121,6 +7236,10 @@ var Tokenizer = class {
             const closer = `</${name}>`;
             const close = this.next(closer, tagEnd);
             const blockType = isAttr ? "xml_attr" : "xml_region";
+            if (close === -1 && isThinking && !this.streaming) {
+              i = tagEnd;
+              continue;
+            }
             if (close === -1) return stop(this.island(blockType, i, this.n, false, { tag: name }));
             const end = close + closer.length;
             if (end > pe) return stop(this.spill(blockType, i, end, pe, { tag: name }));
@@ -7224,12 +7343,12 @@ function blockAt(blocks, offset) {
 
 // source/splice.ts
 var SourceSpliceError = class extends Error {
+  code;
   constructor(code, message) {
     super(message);
     this.code = code;
     this.name = "SourceSpliceError";
   }
-  code;
 };
 function blockEdit(block, text) {
   return { start: block.start, end: block.end, text };
@@ -7561,6 +7680,7 @@ exports.compareWithExistingKindSchema = compareWithExistingKindSchema;
 exports.convertAiSchemaToBlockFields = convertAiSchemaToBlockFields;
 exports.createFingerprinter = createFingerprinter;
 exports.createKindStreamParser = createKindStreamParser;
+exports.createKindValidator = createKindValidator;
 exports.decodeDirective = decodeDirective;
 exports.describeDualGateFailure = describeDualGateFailure;
 exports.directiveDisplay = directiveDisplay;