cartethyia 2.7.9 → 2.8.0

package/src/observability/telemetry-buffer.ts

@@ -6,7 +6,7 @@ import { DEFAULT_BOUNDS } from "../config/network";
 import { type SourceSurface, type UsageRecord } from "../protocol/canonical-model";
 import { log } from "./logger";
 import { scrubSecrets } from "./redaction";
-import { clientNameFromUserAgent } from "./client-name";
+import { telemetryInsertRow, tokenCountToInt, type TelemetryInsertRowSource } from "./telemetry-row";
 
 
 /**
@@ -73,10 +73,6 @@ export interface TelemetryEventInput {
   readonly degenerateStop?: boolean;
 }
 
-function tokenCountToInt(value: number | "unavailable" | undefined): number | undefined {
-  return typeof value === "number" ? Math.round(value) : undefined;
-}
-
 /** Conservative byte estimate for queue accounting.
  *  Telemetry events contain only bounded scalar metadata; serializing every
  *  event just to measure queue size added a JSON allocation on every request.
@@ -104,23 +100,19 @@ function estimateTelemetryEventBytes(event: TelemetryEventInput): number {
 }
 
 /** Maps a durable event to its `telemetry_events` insert row for the
- * batched multi-row writer (`TelemetryBatchBuffer.drain`). */
+ * batched multi-row writer (`TelemetryBatchBuffer.drain`). Normalizes the
+ * `TelemetryEventInput` shape (nested `usage`, token-count coercion) into the
+ * shared record shape; the column spelling itself lives in
+ * {@link telemetryInsertRow}, which the reconciliation backfill shares. */
 function telemetryEventRow(event: TelemetryEventInput) {
-  // Every column below has a live producer: `accountId`/`networkPoolId` flow
-  // `ttfbMs` is measured by the model-probe path, and `usage` (including
-  // `cachedInputTokens` stays — `health` aggregates it into the Overview
-  // cache-hit rate.
-  return {
-    // Stable identity: the request's own id. Retries reuse the materialized
-    // row (the buffer retries the same rows across its five attempts), and
-    // the (tenant_id, request_id) unique boundary makes a re-drain or a
-    // cross-process race converge to one row via ON CONFLICT DO NOTHING
-    // instead of double-charging.
+  // Only the normalization lives here: collapse the nested `usage` record onto
+  // the flat shared shape, and coerce token counts to the integers the schema
+  // columns store. Every field below has a live producer; the column spelling
+  // and the client-name derivation are `telemetryInsertRow`'s.
+  const source: TelemetryInsertRowSource = {
     id: event.requestId,
     tenantId: event.tenantId,
     requestId: event.requestId,
-    // Stamped here, not by the reader. A row without it has no real time, and a
-    // reader that invented one made every such row look like it happened just now.
     createdAt: new Date(),
     sourceSurface: event.sourceSurface,
     requestedModel: event.requestedModel,
@@ -129,8 +121,6 @@ function telemetryEventRow(event: TelemetryEventInput) {
     endpoint: event.endpoint ?? null,
     apiKeyId: event.apiKeyId ?? null,
     userAgent: event.userAgent ?? null,
-    // Canonical client grouping, stamped once so SQL breakdowns group by it.
-    clientName: clientNameFromUserAgent(event.userAgent),
     clientIp: event.clientIp ?? null,
     providerId: event.providerId ?? null,
     accountId: event.accountId ?? null,
@@ -152,18 +142,18 @@ function telemetryEventRow(event: TelemetryEventInput) {
     estimatedCostUsd:
       event.usage?.estimated_cost === null || event.usage === undefined
         ? null
-        : String(event.usage.estimated_cost),
+        : event.usage.estimated_cost,
     // Provider-billed credit (Tencent buddy-meter `credit`, Qoder `credits`);
     // NULL when the upstream reported no credit field.
-    // Numeric columns are string-typed in Drizzle, like `estimatedCostUsd`.
-    creditUsed: event.usage?.credit_used != null ? String(event.usage.credit_used) : null,
+    creditUsed: event.usage?.credit_used ?? null,
     resolveMs: event.resolveMs ?? null,
-    tokensPerSec: event.tokensPerSec != null ? String(event.tokensPerSec) : null,
+    tokensPerSec: event.tokensPerSec ?? null,
     firstContentDeltaAtMs: event.firstContentDeltaAtMs ?? null,
     lastEventAtMs: event.lastEventAtMs ?? null,
     payloadCaptureState: event.payloadCaptureState ?? null,
-    degenerateStop: event.degenerateStop ?? null,
+    ...(event.degenerateStop !== undefined ? { degenerateStop: event.degenerateStop } : {}),
   };
+  return telemetryInsertRow(source);
 }
 
 interface TelemetryBatchBufferOptions {

package/src/observability/telemetry-reconciliation.ts

@@ -33,7 +33,7 @@ import { join } from "node:path";
 import type { CartethyiaDatabase } from "../persistence/db-handle";
 import { telemetryEvents, telemetryReconciliationState } from "../persistence/schema";
 import { TELEMETRY_EVENT_DIR } from "./event-log";
-import { clientNameFromUserAgent } from "./client-name";
+import { telemetryInsertRow } from "./telemetry-row";
 import type { TelemetryEventRecord } from "./event-log";
 import { hourStamp } from "../shared/time";
 
@@ -143,43 +143,15 @@ function parseChunk(text: string): { readonly events: TelemetryEventRecord[]; re
   return { events, carry };
 }
 
-/** The columns the backfill inserts. Mirrors `telemetryEventRow` on the write path. */
+/** The columns the backfill inserts. Shared with the write path via
+ * {@link telemetryInsertRow}, so a recovered row carries exactly the columns
+ * the request path persists — including creditUsed, resolveMs, tokensPerSec,
+ * firstContentDeltaAtMs, lastEventAtMs, payloadCaptureState, and degenerateStop,
+ * which a hand-maintained mirror used to drop. */
 function toRow(event: TelemetryEventRecord): typeof telemetryEvents.$inferInsert {
-  return {
-    // `id = requestId` is what makes the unique index a working idempotency
-    // boundary: a retry of the same request carries the same id.
-    id: event.requestId,
-    tenantId: event.tenantId!,
-    requestId: event.requestId,
-    sourceSurface: event.sourceSurface as typeof telemetryEvents.$inferInsert.sourceSurface,
-    requestedModel: event.requestedModel,
-    reportedModel: event.reportedModel,
-    requestedEffort: event.requestedEffort,
-    providerId: event.providerId,
-    accountId: event.accountId,
-    networkPoolId: event.networkPoolId,
-    endpoint: event.endpoint,
-    apiKeyId: event.apiKeyId,
-    userAgent: event.userAgent,
-    // Derived the same way ingestion derives it, so a backfilled row groups
-    // with the rows the request path wrote instead of forming its own bucket.
-    clientName: clientNameFromUserAgent(event.userAgent),
-    clientIp: event.clientIp,
-    latencyMs: event.latencyMs,
-    ttfbMs: event.ttfbMs,
-    stream: event.stream,
-    httpStatus: event.httpStatus,
-    status: event.status as typeof telemetryEvents.$inferInsert.status,
-    errorCategory: event.errorCategory,
-    errorOrigin: event.errorOrigin,
-    inputTokens: event.inputTokens,
-    cachedInputTokens: event.cachedInputTokens,
-    outputTokens: event.outputTokens,
-    reasoningTokens: event.reasoningTokens,
-    estimatedCostUsd:
-      event.estimatedCostUsd === null ? null : String(event.estimatedCostUsd),
-    createdAt: new Date(event.createdAt),
-  };
+  // `parseChunk` guarantees `tenantId` is a string before a record reaches
+  // here; the type keeps it optional because the raw shape predates that gate.
+  return telemetryInsertRow({ ...event, tenantId: event.tenantId! });
 }
 
 /**

package/src/observability/telemetry-row.ts

@@ -0,0 +1,125 @@
+// Shared telemetry insert-row mapping: the single column spelling for both the
+// write path (telemetry-buffer.ts) and the reconciliation backfill
+// (telemetry-reconciliation.ts). Before this module existed the two paths kept
+// hand-maintained mirrors that drifted — the backfill dropped creditUsed,
+// resolveMs, tokensPerSec, firstContentDeltaAtMs, lastEventAtMs,
+// payloadCaptureState, and degenerateStop, so a recovered row read as if those
+// events never happened. One mapper means a column change lands in both paths.
+import { telemetryEvents } from "../persistence/schema";
+import { clientNameFromUserAgent } from "./client-name";
+
+/**
+ * A normalized telemetry event, shaped like the raw `TelemetryEventRecord` the
+ * reconciliation job parses off disk. The write path normalizes its
+ * `TelemetryEventInput` (nested `usage`, token-count coercion) into this shape
+ * before calling {@link telemetryInsertRow}; the reconciliation path passes its
+ * parsed record directly.
+ */
+export interface TelemetryInsertRowSource {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly requestId: string;
+  readonly createdAt: Date | string;
+  readonly sourceSurface: string | null;
+  readonly requestedModel: string | null;
+  readonly reportedModel: string | null;
+  readonly requestedEffort: string | null;
+  readonly providerId: string | null;
+  readonly accountId: string | null;
+  readonly networkPoolId: string | null;
+  readonly endpoint: string | null;
+  readonly apiKeyId: string | null;
+  readonly userAgent: string | null;
+  readonly clientIp: string | null;
+  readonly latencyMs: number | null;
+  readonly ttfbMs: number | null;
+  readonly stream: boolean | null;
+  readonly status: string | null;
+  readonly httpStatus: number | null;
+  readonly errorOrigin: string | null;
+  readonly errorCategory: string | null;
+  readonly inputTokens: number | null;
+  readonly cachedInputTokens: number | null;
+  readonly outputTokens: number | null;
+  readonly reasoningTokens: number | null;
+  readonly estimatedCostUsd: number | null;
+  readonly creditUsed: number | null;
+  readonly resolveMs: number | null;
+  readonly tokensPerSec: number | null;
+  readonly firstContentDeltaAtMs: number | null;
+  readonly lastEventAtMs: number | null;
+  /** Why the drawer payloads are empty, or `captured`; absent when unrecorded. */
+  readonly payloadCaptureState?: string | null;
+  /** `true` for a degenerate-stop request; absent/null for everything else. */
+  readonly degenerateStop?: boolean;
+}
+
+/** Coerces a token count to the integer the schema columns store; `undefined` for an unavailable count. */
+export function tokenCountToInt(value: number | "unavailable" | undefined): number | undefined {
+  return typeof value === "number" ? Math.round(value) : undefined;
+}
+
+/**
+ * Maps a normalized event to its `telemetry_events` insert row.
+ *
+ * Every column below has a live producer on the write path, and the
+ * reconciliation backfill relies on this exact spelling to recover the same
+ * columns from a raw line. Contract details that are load-bearing:
+ *
+ * - `id = requestId` is what makes the unique index a working idempotency
+ *   boundary: a retry of the same request carries the same id.
+ * - `estimatedCostUsd` persists NULL when the route is unpriced, never the
+ *   text `"null"` — the analytics `partial` flag counts completed rows with no
+ *   persisted cost.
+ * - `creditUsed`/`tokensPerSec` use `!= null` so a measured zero is preserved
+ *   (numeric columns are string-typed in Drizzle).
+ * - `clientName` is derived here, once, via `clientNameFromUserAgent`, so the
+ *   write path and the backfill group the same client the same way.
+ */
+export function telemetryInsertRow(event: TelemetryInsertRowSource): typeof telemetryEvents.$inferInsert {
+  return {
+    id: event.requestId,
+    tenantId: event.tenantId,
+    requestId: event.requestId,
+    // Stamped here, not by the reader. A row without it has no real time, and a
+    // reader that invented one made every such row look like it happened just now.
+    createdAt: new Date(event.createdAt),
+    sourceSurface: event.sourceSurface as typeof telemetryEvents.$inferInsert.sourceSurface,
+    requestedModel: event.requestedModel,
+    reportedModel: event.reportedModel,
+    requestedEffort: event.requestedEffort,
+    endpoint: event.endpoint,
+    apiKeyId: event.apiKeyId,
+    userAgent: event.userAgent,
+    // Canonical client grouping, stamped once so SQL breakdowns group by it.
+    clientName: clientNameFromUserAgent(event.userAgent),
+    clientIp: event.clientIp,
+    providerId: event.providerId,
+    accountId: event.accountId,
+    networkPoolId: event.networkPoolId,
+    latencyMs: event.latencyMs,
+    ttfbMs: event.ttfbMs,
+    stream: event.stream,
+    httpStatus: event.httpStatus,
+    status: event.status as typeof telemetryEvents.$inferInsert.status,
+    errorCategory: event.errorCategory,
+    errorOrigin: event.errorOrigin,
+    inputTokens: event.inputTokens,
+    cachedInputTokens: event.cachedInputTokens,
+    outputTokens: event.outputTokens,
+    reasoningTokens: event.reasoningTokens,
+    // `estimated_cost` is `null` when the route is unpriced; persist NULL so
+    // the analytics `partial` flag can count it. `String(null)` would store the
+    // text "null", which the numeric column rejects.
+    estimatedCostUsd: event.estimatedCostUsd === null ? null : String(event.estimatedCostUsd),
+    // Provider-billed credit (Tencent buddy-meter `credit`, Qoder `credits`);
+    // NULL when the upstream reported no credit field.
+    creditUsed: event.creditUsed != null ? String(event.creditUsed) : null,
+    resolveMs: event.resolveMs,
+    tokensPerSec: event.tokensPerSec != null ? String(event.tokensPerSec) : null,
+    firstContentDeltaAtMs: event.firstContentDeltaAtMs,
+    lastEventAtMs: event.lastEventAtMs,
+    payloadCaptureState: event.payloadCaptureState ?? null,
+    degenerateStop: event.degenerateStop ?? null,
+  };
+}

package/src/persistence/db-mode.ts

@@ -48,7 +48,10 @@ export function resolveDbMode(env: NodeJS.ProcessEnv = process.env): DbMode {
  */
 export function resolveDataDir(env: NodeJS.ProcessEnv = process.env): string {
   const override = env.CARTETHYIA_DATA_DIR?.trim();
-  if (override) return override;
+  // Guard against a literal `"undefined"` value: a launcher that stringifies
+  // a missing env var (`String(undefined)`) would otherwise make the gateway
+  // write its state into a folder named `undefined/` in the CWD.
+  if (override && override !== "undefined") return override;
   if (process.platform === "win32") {
     const roaming = env.APPDATA?.trim();
     if (roaming) return join(roaming, "Cartethyia");

package/src/persistence/dialect.ts

@@ -16,6 +16,7 @@
 import { sql, type SQL } from "drizzle-orm";
 import { SQLiteBunSession } from "drizzle-orm/bun-sqlite";
 import { resolveDbMode } from "./db-mode";
+import { providerAccounts } from "./schema";
 
 /** True when the running backend is the embedded SQLite database. */
 export function sqliteDialect(): boolean {
@@ -67,6 +68,23 @@ export function isSqliteDatabase(database: unknown): boolean {
   return hasSqliteDialect(database);
 }
 
+/**
+ * The `EXISTS` subquery for "the column's cooldown object has an entry whose
+ * ISO deadline is still in the future". The JSON check is dialect-specific:
+ * PostgreSQL uses `jsonb_each_text` (with a shape guard), SQLite `json_each`
+ * on its `text` column (D07). Timestamps are stored as ISO strings on both
+ * backends, so the lexical comparison against `nowIso` is stable.
+ *
+ * Callers keep their own scoping around this fragment — a tenant path must
+ * never touch `tenant_id IS NULL` rows, and the global path must only touch
+ * them — so only the shared JSON subquery lives here.
+ */
+export function liveModelCooldownExistsSql(database: unknown, nowIso: string): SQL {
+  return isSqliteDatabase(database)
+    ? sql`EXISTS (SELECT 1 FROM json_each(${providerAccounts.modelCooldowns}) AS entry WHERE json_valid(${providerAccounts.modelCooldowns}) AND json_type(${providerAccounts.modelCooldowns}) = 'object' AND entry.value > ${nowIso})`
+    : sql`EXISTS (SELECT 1 FROM jsonb_each_text(${providerAccounts.modelCooldowns}) AS entry WHERE jsonb_typeof(${providerAccounts.modelCooldowns}) = 'object' AND entry.value > ${nowIso})`;
+}
+
 /**
  * The per-model cooldown object with every entry whose timestamp has passed
  * removed, or `'{}'` when nothing remains.

package/src/persistence/migrate.ts

@@ -25,11 +25,14 @@ export function resolveMigrationsFolder(): string {
   return folder;
 }
 
-export function migrationFiles(folder: string): readonly string[] {
+export function migrationFileIds(folder: string): readonly string[] {
   return readdirSync(folder)
     .filter((file) => /^\d{4}_.+\.sql$/.test(file))
-    .sort()
-    .map((file) => resolve(folder, file));
+    .sort();
+}
+
+export function migrationFiles(folder: string): readonly string[] {
+  return migrationFileIds(folder).map((file) => resolve(folder, file));
 }
 
 export function migrationIdFor(file: string): string {

package/src/persistence/schema.ts

@@ -309,6 +309,14 @@ export const providerAccounts = pgTable("provider_accounts", {
    * to an account that may well be refused.
    */
   quotaPlan: text("quota_plan"),
+  /**
+   * When `quota_plan` was last written by a successful quota read.
+   *
+   * The plan column is a bare string with no timestamp, so routing cannot tell
+   * a fresh plan from one recorded weeks ago. With the freshness horizon, a
+   * stale plan is downgraded to `unknown` instead of being trusted blindly.
+   */
+  quotaPlanFetchedAt: timestamp("quota_plan_fetched_at", { withTimezone: true }),
   /**
    * The last successful quota read for this account, as a JSON snapshot.
    *

package/src/persistence/ttl-cache.ts

@@ -11,6 +11,12 @@ interface TtlCacheOptions {
   readonly ttlMs?: number;
   readonly maxEntries?: number;
   readonly now?: () => number;
+  /**
+   * LRU eviction order. When set, re-setting an existing key moves it to the
+   * newest position (delete-then-set), so oldest-first eviction becomes
+   * least-recently-used-first. Off by default: plain FIFO insertion order.
+   */
+  readonly lru?: boolean;
 }
 
 interface TtlCacheEntry<T> {
@@ -27,11 +33,13 @@ export class TtlCache<T> {
   private readonly ttlMs: number;
   private readonly maxEntries: number;
   private readonly now: () => number;
+  private readonly lru: boolean;
 
   constructor(opts: TtlCacheOptions = {}) {
     this.ttlMs = opts.ttlMs ?? 5_000;
     this.maxEntries = opts.maxEntries ?? 128;
     this.now = opts.now ?? Date.now;
+    this.lru = opts.lru ?? false;
   }
 
   /**
@@ -54,10 +62,21 @@ export class TtlCache<T> {
    */
   set(key: string, value: T): void {
     const now = this.now();
+    if (this.lru) this.cache.delete(key); // move to newest position
     this.cache.set(key, { value, at: now });
     this.evictIfNeeded(now);
   }
 
+  /**
+   * Peek at a stored value without checking the TTL or deleting on expiry.
+   * Returns only undefined when the key is absent. Callers that need the
+   * possibly-expired value (e.g. a stale fallback after a failed refetch)
+   * must read it before `get`, which removes expired entries.
+   */
+  peek(key: string): T | undefined {
+    return this.cache.get(key)?.value;
+  }
+
   /**
    * Delete a specific key.
    */
@@ -144,8 +163,7 @@ interface TtlCacheFamilyOptions {
 /**
  * A set of {@link TtlCache} instances keyed by TTL, created on first use.
  *
- * Two provider-side caches (`operations/provider-version-cache.ts` and
- * `operations/model-discovery-cache.ts`) had each hand-rolled the same
+ * Two provider-side caches in `operations/provider-caches.ts` had each hand-rolled the same
  * `Map<number, TtlCache<T>>` + `cacheFor(ttlMs)` memo plus the same
  * `for (const cache of caches.values()) cache.clear()` reset. Tests pass
  * `ttlMs: 0` to force a reload, which is why the per-TTL split exists at all —

package/src/protocol/codecs.ts

@@ -14,7 +14,7 @@ import type { CanonicalStopReason, CanonicalTerminalEvent, UsageRecord } from ".
 import { type WireFamily } from "./canonical-model";
 import type { GenerationControls } from "./canonical-model";
 import { BASE_PROTECTED_HEADERS, HEADER_CONTROL, HEADER_TOKEN } from "../security/outbound-headers";
-import { unwrapProviderToken } from "../providers/provider-credential-envelope";
+import { unwrapProviderToken } from "../providers/provider-credentials";
 
 const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder();

package/src/protocol/dsml.ts

@@ -8,6 +8,7 @@
  * - CodeBuddy emits strict blocks (`<｜DSML｜ calls>…</｜DSML｜ calls>`)
  *   that must be parsed exactly, with declared-tool allowlisting.
  */
+import { MarkupStreamParser } from "./markup-stream-parser";
 export interface DsmlToolCall {
   readonly id: string;
   readonly name: string;
@@ -74,102 +75,49 @@ interface DsmlParseResult {
  * With no allowlist the generic name rule applies; with one, undeclared names
  * reject the whole block. The caller feeds chunks with `push` and drains the
  * tail with `flush`.
+ *
+ * The stateful prefix-buffer loop is the shared {@link MarkupStreamParser}
+ * scaffold; this class supplies the DSML grammar as a thin configuration.
  */
 export class DsmlStreamParser {
-  readonly #separators: readonly string[];
-  readonly #blockNames: readonly string[];
-  readonly #openers: readonly string[];
-  readonly #allowedNames: ReadonlySet<string>;
-  readonly #params: "json" | "string";
-  readonly #sortKeys: boolean;
-  readonly #maxBlockBytes: number;
-  readonly #id: (call: { readonly name: string }, index: number, seq: number) => string;
-  #pending = "";
-  #callSequence = 0;
+  readonly #parser: MarkupStreamParser<DsmlToolCall>;
 
   constructor(options: DsmlParseOptions = {}) {
-    this.#separators = options.separators ?? DEFAULT_SEPARATORS;
-    this.#blockNames = options.blockNames ?? DEFAULT_BLOCK_NAMES;
-    this.#openers = openers(this.#separators, this.#blockNames);
-    this.#allowedNames = options.allowedNames ?? new Set();
-    this.#params = options.params ?? "json";
-    this.#sortKeys = options.sortKeys ?? true;
-    this.#maxBlockBytes = options.maxBlockBytes ?? DEFAULT_MAX_BLOCK_BYTES;
-    this.#id = options.id ?? sequentialId;
+    const separators = options.separators ?? DEFAULT_SEPARATORS;
+    const blockNames = options.blockNames ?? DEFAULT_BLOCK_NAMES;
+    const allowedNames = options.allowedNames ?? new Set();
+    const params = options.params ?? "json";
+    const sortKeys = options.sortKeys ?? true;
+    const maxBlockBytes = options.maxBlockBytes ?? DEFAULT_MAX_BLOCK_BYTES;
+    const id = options.id ?? sequentialId;
+    this.#parser = new MarkupStreamParser<DsmlToolCall>({
+      openers: openers(separators, blockNames),
+      classifyOpener: (_pending, _index, opener) => {
+        const separator = separators.find((value) => opener.startsWith(`<${value}DSML`));
+        const blockName = blockNames.find((value) => opener.endsWith(` ${value}>`));
+        if (separator === undefined || blockName === undefined) return { kind: "literal" };
+        const close = `</${separator}DSML${separator} ${blockName}>`;
+        return {
+          kind: "found",
+          closer: close,
+          parse: (block) =>
+            parseStrictBlock(block, opener, close, separator, allowedNames, params, sortKeys),
+          callId: (call, index, seq) => ({ ...call, id: id(call, index, seq) }),
+        };
+      },
+      onUnclosed: (pending, openIndex) =>
+        pending.length - openIndex > maxBlockBytes
+          ? { kind: "passThrough" }
+          : "hold",
+    });
   }
 
   push(chunk: string): DsmlParseResult {
-    this.#pending += chunk;
-    let cursor = 0;
-    let visible = "";
-    const calls: DsmlToolCall[] = [];
-    for (;;) {
-      let openIndex = -1;
-      let opener = "";
-      for (const candidate of this.#openers) {
-        const index = this.#pending.indexOf(candidate, cursor);
-        if (index >= 0 && (openIndex < 0 || index < openIndex)) {
-          openIndex = index;
-          opener = candidate;
-        }
-      }
-      if (openIndex < 0) {
-        const safeEnd = this.#settledEnd(cursor);
-        visible += this.#pending.slice(cursor, safeEnd);
-        cursor = safeEnd;
-        break;
-      }
-      visible += this.#pending.slice(cursor, openIndex);
-      const separator = this.#separators.find((value) => opener.startsWith(`<${value}DSML`));
-      const blockName = this.#blockNames.find((value) => opener.endsWith(` ${value}>`));
-      if (separator === undefined || blockName === undefined) {
-        visible += "<";
-        cursor = openIndex + 1;
-        continue;
-      }
-      const close = `</${separator}DSML${separator} ${blockName}>`;
-      const closeIndex = this.#pending.indexOf(close, openIndex + opener.length);
-      if (closeIndex < 0) {
-        // An unclosed block past the cap is not markup — pass it through as
-        // text instead of buffering it indefinitely. Same fail-open as
-        // `feed()` in the reference bridge's `MAX_BLOCK_BYTES` guard.
-        if (this.#pending.length - openIndex > this.#maxBlockBytes) {
-          visible += this.#pending.slice(openIndex);
-          cursor = this.#pending.length;
-          break;
-        }
-        cursor = openIndex;
-        break;
-      }
-      const end = closeIndex + close.length;
-      const block = this.#pending.slice(openIndex, end);
-      const parsed = parseStrictBlock(block, opener, close, separator, this.#allowedNames, this.#params, this.#sortKeys);
-      if (parsed === undefined) visible += block;
-      else {
-        parsed.forEach((call, index) => {
-          calls.push({ ...call, id: this.#id(call, index, this.#callSequence++) });
-        });
-      }
-      cursor = end;
-    }
-    this.#pending = this.#pending.slice(cursor);
-    return { text: visible, calls };
+    return this.#parser.push(chunk);
   }
 
   flush(): DsmlParseResult {
-    const text = this.#pending;
-    this.#pending = "";
-    return { text, calls: [] };
-  }
-
-  #settledEnd(start: number): number {
-    const remaining = this.#pending.slice(start);
-    const maxOpener = this.#openers.reduce((max, opener) => Math.max(max, opener.length - 1), 0);
-    for (let length = Math.min(maxOpener, remaining.length); length > 0; length -= 1) {
-      const suffix = remaining.slice(-length);
-      if (this.#openers.some((opener) => opener.startsWith(suffix))) return this.#pending.length - length;
-    }
-    return this.#pending.length;
+    return this.#parser.flush();
   }
 }