@plurnk/plurnk-service 1.0.0

package/dist/core/SchemeRegistry.js

@@ -0,0 +1,205 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import Plurnk from "../schemes/Plurnk.js";
+import Log from "../schemes/Log.js";
+import Exec from "../schemes/Exec.js";
+import Known from "../schemes/Known.js";
+import Unknown from "../schemes/Unknown.js";
+import Skill from "../schemes/Skill.js";
+import File from "../schemes/File.js";
+import Run from "../schemes/Run.js";
+import ResolveForLoop from "./resolveForLoop.js";
+import { SchemeDiscovery } from "@plurnk/plurnk-schemes";
+import PluginAttribution from "./plugin-attribution.js";
+import ExecOutputScheme from "../schemes/ExecOutputScheme.js";
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import Paths from "../Paths.js";
+import { teachingLine, docsExcludeSet } from "./teaching.js";
+// The in-tree CORE-scheme depth (run/known/unknown/log) lives in the docs corpus (docs/)
+// (Paths.schemeDocs), NOT inline — the docs agent owns the prose; loaded once at module eval.
+// teach()/docs() prefer this over a manifest's inline `documentation` (the path that stays for
+// stubs + daughter schemes). Absent dir → empty map.
+const SCHEME_DOCS = await (async () => {
+    try {
+        const files = (await readdir(Paths.schemeDocs)).filter((f) => f.endsWith(".md"));
+        const loaded = await Promise.all(files.map(async (f) => [f.slice(0, -3), await readFile(resolve(Paths.schemeDocs, f), "utf8")]));
+        return new Map(loaded);
+    }
+    catch {
+        return new Map();
+    }
+})();
+export default class SchemeRegistry {
+    // Heterogeneous handler store — in-tree schemes take PlurnkSchemeContext, external
+    // siblings the DB-free SchemeCtx of the imported SchemeHandler; the common supertype
+    // is `object`. Dispatch (Dispatcher.#run) borrows SchemeHandler's op-key set, not its ctx.
+    #handlers = new Map();
+    #external = new Set();
+    #attributions = []; // #249 — declared attribution tags of discovered external schemes
+    // §exec — runtime-tag schemes (sh/node/…) that ALIAS the exec handler for output-entry
+    // addressing (sh:///l/t/s). Routable via get(), but NOT separately taught or doc-materialized
+    // (exec is taught once); else the catalog + docs bloat by one redundant line/entry per tag.
+    #runtimeSchemes = new Set();
+    // #240 — built-in scheme names (captured at construction), reserved namespace-wide.
+    #reserved = new Set();
+    constructor() {
+        this.register("plurnk", new Plurnk());
+        this.register("log", new Log());
+        this.register("exec", new Exec());
+        this.register("known", new Known());
+        this.register("unknown", new Unknown());
+        this.register("skill", new Skill());
+        this.register("file", new File());
+        this.register("run", new Run());
+        // #240 — the in-tree names are RESERVED across the whole scheme namespace: a
+        // discovered executor or external scheme claiming one fails the boot hard, never
+        // silently shadowed. (exec stays poisoned-but-registered — the EXEC op + kill state.)
+        this.#reserved = new Set(this.#handlers.keys());
+    }
+    register(name, handler) {
+        if (this.#handlers.has(name))
+            throw new Error(`scheme '${name}' is already registered`);
+        this.#handlers.set(name, handler);
+    }
+    // §exec / #240 — exec OUTPUT entries address by their runtime TAG as authority
+    // (sh:///l/t/s). Register each discovered executor as its OWN per-tag scheme face
+    // (ExecOutputScheme): READ/FIND tag-scoped via the executor's manifest, process-KILL
+    // delegated to the shared Exec handler. Minted from the boot ExecutorRegistry; in-tree
+    // names take precedence (a tag shadowing a built-in is skipped, never overrides it).
+    registerRuntimeSchemes(executors) {
+        for (const tag of executors.availableRuntimes()) {
+            const entry = executors.entry(tag);
+            if (entry === undefined)
+                continue;
+            this.registerRuntimeScheme(tag, entry.executor);
+        }
+    }
+    // Register ONE executor tag's scheme face (the boot loop above + the #289 runtime hotload:
+    // an MCP server connected live becomes EXEC[<server>]). The reserved/cross-family arbitration
+    // lives HERE so both paths share it — one name, one owner across the exec/scheme families (#240):
+    // idempotent on a tag that already has its own runtime scheme (a boot re-scan), fail-hard on a
+    // collision with a reserved built-in or a DIFFERENT already-claimed scheme.
+    registerRuntimeScheme(tag, executor) {
+        const exec = this.#handlers.get("exec");
+        if (!(exec instanceof Exec))
+            throw new Error("registerRuntimeScheme: the exec handler is not registered");
+        if (this.#reserved.has(tag))
+            throw new Error(`executor tag '${tag}' collides with a reserved built-in scheme — fail-hard (#240)`);
+        if (this.#runtimeSchemes.has(tag))
+            return; // idempotent — already this tag's own runtime scheme
+        if (this.#handlers.has(tag))
+            throw new Error(`executor tag '${tag}' collides with an already-claimed scheme '${tag}' — one name, one owner across the exec/scheme families (#240)`);
+        this.register(tag, new ExecOutputScheme(executor, exec));
+        this.#runtimeSchemes.add(tag);
+    }
+    get(name) { return this.#handlers.get(name); }
+    has(name) { return this.#handlers.has(name); }
+    // True for schemes registered via discoverExternal — they receive the
+    // DB-free SchemeCtx (caps), not the in-tree PlurnkSchemeContext.
+    isExternal(name) { return this.#external.has(name); }
+    list() { return [...this.#handlers.keys()].toSorted(); }
+    // A scheme's default channel (manifest.defaultChannel) — the channel a fragment-less
+    // address targets. Drives the manifest's address-keyed channels (note 4); null → file (body).
+    defaultChannelFor(scheme) {
+        if (scheme === null)
+            return "body";
+        const manifest = this.#handlers.get(scheme)?.constructor?.manifest;
+        return manifest?.defaultChannel ?? "body";
+    }
+    // The scheme directory — the `schemes` packet section (below tools). grammar
+    // 0.49+ teaches grammar/dialects only, not the scheme set (grammar#239), so the
+    // service advertises what schemes exist at packet-time. Each handler that ships a
+    // `manifest.example` contributes ONE terse line — its canonical usage — plus a
+    // doc-link when it ships `manifest.documentation` (materialized at
+    // plurnk://docs/<name>.md by loop_run, READ on demand). The verbose semantics live
+    // in that pull doc, not here: terse pushes, depth pulls — exactly the exec tools
+    // sheet's shape (#collectTools). Insertion order; a scheme with no example
+    // (provisional, e.g. skill) is omitted. The doc's token cost rides its manifest entry.
+    teach() {
+        const lines = [];
+        const excluded = docsExcludeSet();
+        for (const [name, handler] of this.#handlers) {
+            if (this.#runtimeSchemes.has(name))
+                continue; // §exec — runtime aliases route, but exec is taught once
+            if (excluded.has(name))
+                continue; // #240 — PLURNK_SERVICE_DOCS_EXCLUDE drops the oneliner + the doc
+            const manifest = handler.constructor.manifest;
+            const example = manifest?.example;
+            if (typeof example !== "string" || example.length === 0)
+                continue;
+            lines.push(teachingLine(example)); // doc links removed (#270) — docs are FIND(plurnk://docs/**)-discovered
+        }
+        return lines.join("\n");
+    }
+    // #note12 — schemes that ship a `documentation` string, for materialization at
+    // plurnk:///docs/<name>.md. Optional + currently none in-tree; future-proofs the link.
+    docs() {
+        const out = [];
+        const excluded = docsExcludeSet();
+        for (const [name, handler] of this.#handlers) {
+            if (this.#runtimeSchemes.has(name))
+                continue; // §exec — runtime aliases share exec's doc, not their own
+            if (excluded.has(name))
+                continue; // #240 — PLURNK_SERVICE_DOCS_EXCLUDE drops the doc
+            const inline = handler.constructor.manifest?.documentation;
+            const content = SCHEME_DOCS.get(name) ?? (typeof inline === "string" && inline.length > 0 ? inline : undefined);
+            if (content !== undefined && content.length > 0)
+                out.push({ name, content });
+        }
+        return out;
+    }
+    // Plugin packet control (§packet-assembly): pipe the engine's default
+    // section list through every registered scheme that implements
+    // transformSections, in registration order. A scheme returns whatever list it
+    // wants — add, remove, reorder. The trusted in-process seam; the client wire
+    // never touches the packet. In-tree + external handlers both, duck-typed.
+    async transformSections(sections) {
+        let current = sections;
+        for (const handler of this.#handlers.values()) {
+            const transform = handler.transformSections;
+            if (typeof transform === "function")
+                current = await transform.call(handler, current);
+        }
+        return current;
+    }
+    // Discover external scheme siblings — delegated to the framework's SchemeDiscovery
+    // (schemes 0.9+): the scope-agnostic node_modules scan for plurnk.kind:"scheme" +
+    // plurnk.name AND the PLURNK_PLUGINS_TRUSTED_ONLY trust gate (untrusted → `skipped`,
+    // never crashed) both live there now, single-sourced across the plugin families
+    // (the "delegate upstream" rule — execs/mimetypes/providers already ship discover()).
+    // The service keeps only consumer policy: in-tree precedence (a name a built-in owns
+    // is left as-is) and importing + registering the trusted descriptors. A sibling reaches
+    // the substrate only through the DB-free SchemeCtx the engine wraps for isExternal() schemes.
+    async discoverExternal(cwd = process.cwd()) {
+        const { schemes, skipped } = await SchemeDiscovery.discover({ cwd });
+        for (const name of skipped) {
+            console.warn(`scheme discovery: '${name}' is discovered but untrusted (PLURNK_PLUGINS_TRUSTED_ONLY); not registered`);
+        }
+        for (const { name, packageName } of schemes) {
+            if (this.#reserved.has(name))
+                throw new Error(`external scheme '${name}' (${packageName}) collides with a reserved built-in — boot fail-hard (#240)`);
+            if (this.has(name))
+                continue; // idempotent re-scan
+            const mod = await import(__rewriteRelativeImportExtension(packageName));
+            this.register(name, new mod.default());
+            this.#external.add(name);
+            this.#attributions.push(...PluginAttribution.read(packageName)); // #249 — fail-hard if it claims @plurnk/
+        }
+    }
+    // #249 — declared attribution tags of the discovered external schemes (opaque; the
+    // engine unions these across plugin families onto the generate() `attributions` wire).
+    attributions() { return [...this.#attributions]; }
+    // Active set under the given loop flags (SPEC §engine-rails). Delegates to
+    // the in-tree ResolveForLoop utility.
+    resolveForLoop(flags) {
+        return ResolveForLoop.resolveForLoop(this.#handlers, flags);
+    }
+}
+//# sourceMappingURL=SchemeRegistry.js.map

package/dist/core/SchemeRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemeRegistry.js","sourceRoot":"","sources":["../../src/core/SchemeRegistry.ts"],"names":[],"mappings":"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"}

package/dist/core/StrikeRail.d.ts

@@ -0,0 +1,28 @@
+import type { PlurnkStatement } from "@plurnk/plurnk-grammar";
+export default class StrikeRail {
+    #private;
+    static fingerprintTurn(ops: ReadonlyArray<PlurnkStatement>): string;
+    static detectCycle(history: ReadonlyArray<string>, minCycles: number, maxCyclePeriod: number): {
+        detected: false;
+    } | {
+        detected: true;
+        period: number;
+        cycles: number;
+    };
+    streak(loopId: number): number;
+    assess(loopId: number, turn: {
+        fingerprint: string;
+        statuses: ReadonlyArray<number>;
+        noOps: boolean;
+        budgetStruck: boolean;
+        steerStruck: boolean;
+        minCycles: number;
+        maxCyclePeriod: number;
+        maxStrikes: number;
+    }): {
+        cycleDetected: boolean;
+        thresholdCrossed: boolean;
+    };
+    delete(loopId: number): void;
+}
+//# sourceMappingURL=StrikeRail.d.ts.map

package/dist/core/StrikeRail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StrikeRail.d.ts","sourceRoot":"","sources":["../../src/core/StrikeRail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,wBAAwB,CAAC;AA8E1E,MAAM,CAAC,OAAO,OAAO,UAAU;;IAG3B,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,MAAM,CAElE;IAMD,MAAM,CAAC,WAAW,CACd,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACvB;QAAE,QAAQ,EAAE,KAAK,CAAA;KAAE,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAe1E;IAYD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7B;IAUD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QACzB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,KAAK,EAAE,OAAO,CAAC;QACf,YAAY,EAAE,OAAO,CAAC;QACtB,WAAW,EAAE,OAAO,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;KACtB,GAAG;QAAE,aAAa,EAAE,OAAO,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAA;KAAE,CA4BxD;IAED,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3B;CACJ"}

package/dist/core/StrikeRail.js

@@ -0,0 +1,165 @@
+// Rail #38: action-entry statuses that DON'T accumulate strikes. Model adapted
+// to a finding (not_found, op_not_supported); no penalty. Rummy parallel:
+// SOFT_FAILURE_OUTCOMES = {"not_found", "unparsed"}.
+// Exploratory misses are not failures: probing a path that doesn't exist (404), a line
+// range that doesn't exist (416), or a capability a scheme lacks (501) is how discovery
+// works — striking them prices caution into the motions we most want (range-reads ARE
+// the surgical behavior under budget pressure). One simple set, evenly applied.
+// 409 (premature-terminate refusal) is SOFT here: whether it strikes is decided by steerStruck
+// (Engine sets it true for a stream/child refusal — discarding live work IS serious — and false
+// for a retrievals-only refusal, which teaches without striking, §send-premature-terminate/#346).
+// Counting the raw 409 status ALSO would double-strike the stream/child case and WRONGLY strike
+// the retrieval-only case (a cloud atomic-turn model repeating read+conclude struck out 500 on
+// firefast despite the ruling). The cycle detector remains the backstop for a genuinely-spinning
+// model (508 loop-detected — the honest signal, not a 500 failure).
+const SOFT_FAILURE_STATUSES = new Set([404, 409, 416, 501]);
+// Per-op fingerprint: op verb + target URI, plus an op-specific discriminator
+// where the activity isn't fully captured by target alone:
+//   - EDIT/COPY/MOVE: body excluded — re-writing the same target with varied
+//     content IS cycling (the model is producing different versions of the
+//     same artifact instead of progressing).
+//   - FIND/READ/OPEN/FOLD: body IS the search/selection pattern; varied
+//     matchers on the same target ARE different activities (the model is
+//     exploring different queries, not repeating one).
+const fingerprintOp = (stmt) => {
+    const path = stmt.target;
+    const matcherDiscriminator = () => {
+        // For matcher-bearing ops, the body's `raw` (matcher source) plus
+        // any lineMarker forms the activity discriminator.
+        const parts = [];
+        const body = stmt.body;
+        if (body !== null && typeof body === "object" && typeof body.raw === "string") {
+            parts.push(`body:${body.raw.slice(0, 64)}`);
+        }
+        const lm = stmt.lineMarker;
+        if (lm !== null && lm !== undefined)
+            parts.push(`L:${lm.marks.join(",")}`);
+        return parts.length > 0 ? `|${parts.join("|")}` : "";
+    };
+    if (path === null) {
+        // Path-less ops need an activity-defining discriminator other
+        // than `target`. Picked per op so the cycle detector reflects
+        // intent rather than syntax:
+        //   - EXEC: the command body IS the activity. Without a body
+        //     digest, varied shell commands (find / ls / wc) collapse to
+        //     one fingerprint and the detector mislabels exploration
+        //     as a loop.
+        //   - SEND: the status code (signal) IS the activity. Different
+        //     SEND[X] are different intentions; same SEND[X] with
+        //     different message bodies is the same termination signal.
+        if (stmt.op === "EXEC") {
+            const body = typeof stmt.body === "string" ? stmt.body : "";
+            return `EXEC|(no-path)${body.length > 0 ? `|body:${body.slice(0, 64)}` : ""}`;
+        }
+        if (stmt.op === "SEND") {
+            const signal = typeof stmt.signal === "number" ? stmt.signal : "";
+            return `SEND|(no-path)|signal:${signal}`;
+        }
+        return `${stmt.op}|(no-path)`;
+    }
+    const base = path.kind === "url"
+        ? `${stmt.op}|${path.scheme}://${path.pathname}`
+        : `${stmt.op}|local:${path.raw}`;
+    if (stmt.op === "FIND" || stmt.op === "READ" || stmt.op === "OPEN" || stmt.op === "FOLD") {
+        return `${base}${matcherDiscriminator()}`;
+    }
+    return base;
+};
+// Rails #38 (strikes) + #39 (cycle detection): the per-loop failure-streak
+// accounting that decides abandonment. Strike accounting is engine-internal
+// bookkeeping. Per rummy precedent (plugins/error/error.js#verdict) and SPEC
+// §telemetry policy: model sees errors that happened (parse_error,
+// action_failure), never the engine's accounting about them (strike counts,
+// cycle detection, sudden-death threshold). Surfacing internal state to the
+// model creates a gamification surface — model optimizes for engine metrics
+// rather than task progress.
+export default class StrikeRail {
+    // Per-turn fingerprint: sorted set of per-op fingerprints, joined. Order
+    // within a turn doesn't matter — we want the SET of activities.
+    static fingerprintTurn(ops) {
+        return ops.map(fingerprintOp).toSorted().join(",");
+    }
+    // Rail #39 cycle detector. For each candidate period k in [1, maxCyclePeriod],
+    // check whether the last k*minCycles entries form minCycles repetitions of the
+    // same length-k pattern. O(maxCyclePeriod × minCycles × max k) ≈ tiny. Rummy
+    // parallel: src/plugins/error/error.js detectCycle.
+    static detectCycle(history, minCycles, maxCyclePeriod) {
+        for (let k = 1; k <= maxCyclePeriod; k++) {
+            const needed = k * minCycles;
+            if (history.length < needed)
+                continue;
+            const tail = history.slice(-needed);
+            const cycle = tail.slice(0, k);
+            let match = true;
+            outer: for (let rep = 0; rep < minCycles; rep++) {
+                for (let j = 0; j < k; j++) {
+                    if (tail[rep * k + j] !== cycle[j]) {
+                        match = false;
+                        break outer;
+                    }
+                }
+            }
+            if (match)
+                return { detected: true, period: k, cycles: minCycles };
+        }
+        return { detected: false };
+    }
+    // Rail #38 strike state per loop. `streak` = consecutive struck turns;
+    // resets on a clean turn. `turnErrors` is bumped by per-turn rails (cycle
+    // detection #39, grinder, steer) — read and reset at end of each turn.
+    // `history` holds per-turn fingerprints for rail #39 cycle detection.
+    #state = new Map();
+    // The loop's CURRENT strike streak — the same figure the 500-threshold compares. Rides
+    // generate({strikes}) as first-party outbound metadata (Plurnk-Strikes, #313): the hosted
+    // router's escalation signal. NEVER model-facing (§engine-rails — a surfaced count is a
+    // metric to game); the packet does not carry it.
+    streak(loopId) {
+        return this.#state.get(loopId)?.streak ?? 0;
+    }
+    // Per-turn strike accounting, run by runLoop after every turn. Three
+    // sources strike a turn:
+    //  1. recordedFailed — any action-entry at hard failure status
+    //     (>= 400 and not in SOFT_FAILURE_STATUSES).
+    //  2. noOps — the turn emitted no ops at all (per #41).
+    //  3. turnErrors — bumped by per-turn rails (#39 cycle, grinder, steer).
+    // Struck → streak++; clean → streak = 0. Threshold → thresholdCrossed,
+    // and runLoop owns the abandonment.
+    assess(loopId, turn) {
+        // Rail #39: cycle detection. Push this turn's fingerprint to
+        // history, scan for repetition patterns. Detection bumps
+        // turnErrors so the strike system handles abandonment
+        // naturally — same internal-only role rummy gave it
+        // (plugins/error/error.js#verdict). Intentionally NOT a
+        // model-facing telemetry kind: model sees the strike pile-up
+        // (which IS the actionable signal); cycle is the engine's
+        // reason for treating the turn as a failure, not its own alert.
+        const state = this.#state.get(loopId) ?? { streak: 0, turnErrors: 0, history: [] };
+        state.history.push(turn.fingerprint);
+        const cycle = StrikeRail.detectCycle(state.history, turn.minCycles, turn.maxCyclePeriod);
+        if (cycle.detected)
+            state.turnErrors++;
+        // SPEC §grinder: a non-soft grinder fire counts toward the strike streak.
+        if (turn.budgetStruck)
+            state.turnErrors++; // a grinder fire bumps the strike streak — §grinder-strike-coupling
+        if (turn.steerStruck)
+            state.turnErrors++; // idle / premature-terminate steer struck — §send the terminal contract
+        const recordedFailed = turn.statuses.some((s) => s >= 400 && !SOFT_FAILURE_STATUSES.has(s));
+        const struck = turn.noOps || recordedFailed || state.turnErrors > 0;
+        let thresholdCrossed = false;
+        if (struck) {
+            state.streak++;
+            if (state.streak >= turn.maxStrikes)
+                thresholdCrossed = true;
+        }
+        else {
+            state.streak = 0;
+        }
+        state.turnErrors = 0;
+        this.#state.set(loopId, state);
+        return { cycleDetected: cycle.detected, thresholdCrossed };
+    }
+    delete(loopId) {
+        this.#state.delete(loopId);
+    }
+}
+//# sourceMappingURL=StrikeRail.js.map

package/dist/core/StrikeRail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StrikeRail.js","sourceRoot":"","sources":["../../src/core/StrikeRail.ts"],"names":[],"mappings":"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"}

package/dist/core/TelemetryChannel.d.ts

@@ -0,0 +1,37 @@
+import type { TelemetryEvent } from "@plurnk/plurnk-grammar";
+import type { Db } from "./Db.ts";
+import type { TelemetryEventNotify } from "./ChannelWrite.ts";
+declare const ENGINE_ERRORS: Readonly<{
+    readonly budget_overflow: {
+        readonly status: 413;
+        readonly term: "Budget Overflow: newest log items automatically FOLDed — a retrieval larger than Tokens Free arrives folded; FOLD older items first, then fetch within the room made";
+    };
+    readonly max_commands_exceeded: {
+        readonly status: 429;
+        readonly term: "Max Commands Exceeded";
+    };
+    readonly idle_turn: {
+        readonly status: 409;
+        readonly term: "Idle Turn — this turn delivered no new work; act on something pending, deliver a result, or conclude ([200]) / abandon ([499])";
+    };
+}>;
+export type EngineErrorKind = keyof typeof ENGINE_ERRORS;
+export default class TelemetryChannel {
+    #private;
+    constructor({ db, notify }: {
+        db: Db;
+        notify?: TelemetryEventNotify;
+    });
+    push(sessionId: number, loopId: number, event: TelemetryEvent): void;
+    notify(sessionId: number, loopId: number, event: TelemetryEvent): void;
+    drain(loopId: number): object[];
+    delete(loopId: number): void;
+    mintEngineError(kind: EngineErrorKind, { runId, loopId, turnId, sequence }: {
+        runId: number;
+        loopId: number;
+        turnId: number;
+        sequence: number;
+    }): Promise<void>;
+}
+export {};
+//# sourceMappingURL=TelemetryChannel.d.ts.map

package/dist/core/TelemetryChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryChannel.d.ts","sourceRoot":"","sources":["../../src/core/TelemetryChannel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAM9D,QAAA,MAAM,aAAa;;iBACI,MAAM,EAAE,GAAG;iBAAE,IAAI,EAAE,sKAAsK;;;iBACnL,MAAM,EAAE,GAAG;iBAAE,IAAI,EAAE,uBAAuB;;;iBAItD,MAAM,EAAE,GAAG;iBAAE,IAAI,EAAE,gIAAgI;;EACzJ,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,aAAa,CAAC;AAKzD,MAAM,CAAC,OAAO,OAAO,gBAAgB;;IAajC,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE;QAAE,EAAE,EAAE,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,oBAAoB,CAAA;KAAE,EAGpE;IAED,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAQnE;IAID,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAErE;IAGD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK9B;IAED,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3B;IAMK,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAYpK;CACJ"}

package/dist/core/TelemetryChannel.js

@@ -0,0 +1,77 @@
+// §telemetry — the uniform error channel. Every engine failure is a terse op='error'
+// log row: a status code + the canonical term, no prose (the packet teaches recovery).
+// Each surfaces as a LogCoordinate TelemetryEvent derived from log≥400 — one channel,
+// no per-kind handling. {§telemetry-uniform-error-channel}
+const ENGINE_ERRORS = Object.freeze({
+    budget_overflow: { status: 413, term: "Budget Overflow: newest log items automatically FOLDed — a retrieval larger than Tokens Free arrives folded; FOLD older items first, then fetch within the room made" },
+    max_commands_exceeded: { status: 429, term: "Max Commands Exceeded" },
+    // premature-terminate is NOT a terse engine-error: it's a SEND op-result (409 + an actionable
+    // outcome, §send-premature-terminate) — the SEND row records the [200] attempt faithfully and
+    // auto-surfaces (status≥400) like any op failure, never an erasure to 102.
+    idle_turn: { status: 409, term: "Idle Turn — this turn delivered no new work; act on something pending, deliver a result, or conclude ([200]) / abandon ([499])" },
+});
+// The model-facing alert channel: a per-loop transient buffer of actionless failures
+// pending surface in the NEXT packet's user.telemetry.errors[], plus the live client
+// fan-out and the uniform op='error' log-row mint. SPEC §telemetry.
+export default class TelemetryChannel {
+    #db;
+    // Per-loop transient buffer of actionless failures pending surface in the
+    // NEXT packet's user.telemetry.errors[]. Drained by PacketBuilder.buildTelemetryErrors.
+    // Map<loopId, TelemetryError[]>. SPEC §telemetry.
+    #buffer = new Map();
+    // Telemetry event fan-out: every TelemetryEvent pushed to the loop's
+    // buffer is also broadcast live to the connected client(s) on the
+    // session. Without this, the client sees `loop/terminated` with a
+    // status code but has no way to surface why the loop degraded.
+    // Per-grammar 0.17.0 protocol — see SPEC §telemetry.
+    #notify;
+    constructor({ db, notify }) {
+        this.#db = db;
+        this.#notify = notify;
+    }
+    push(sessionId, loopId, event) {
+        const existing = this.#buffer.get(loopId);
+        if (existing === undefined)
+            this.#buffer.set(loopId, [event]);
+        else
+            existing.push(event);
+        // Live fan-out: client sees the event the moment it lands in the
+        // model's buffer (not at the next packet build). Same envelope on
+        // both sides per the grammar 0.17.0 TelemetryEvent protocol.
+        this.#notify?.(sessionId, { loopId, event });
+    }
+    // Live fan-out ONLY, never buffered — for work with no loop to drain the
+    // buffer (e.g. session-scope derivation warming, loopId 0).
+    notify(sessionId, loopId, event) {
+        this.#notify?.(sessionId, { loopId, event });
+    }
+    // Telemetry drains as it's read into the packet — each event surfaces once. §telemetry-drain-on-read
+    drain(loopId) {
+        const buf = this.#buffer.get(loopId);
+        if (buf === undefined)
+            return [];
+        this.#buffer.delete(loopId);
+        return buf;
+    }
+    delete(loopId) {
+        this.#buffer.delete(loopId);
+    }
+    // Mint an engine failure as a uniform op='error' log row (§telemetry-uniform-error-channel):
+    // a terse status + canonical term keyed by `kind` (the packet teaches recovery, not the row),
+    // origin engine:rail. The errors section derives its LogCoordinate pointer from log≥400 — one
+    // channel, no per-kind handling.
+    async mintEngineError(kind, { runId, loopId, turnId, sequence }) {
+        const { status, term } = ENGINE_ERRORS[kind];
+        await this.#db.engine_insert_log_entry.get({
+            run_id: runId, loop_id: loopId, turn_id: turnId, sequence,
+            origin: "plurnk", source: "rail", op: "error", suffix: "", signal: null,
+            scheme: null, username: null, password: null, hostname: null, port: null,
+            pathname: null, params: null, fragment: null, lineMarker: null,
+            tx: "", mimetype_tx: "text/plain",
+            rx: JSON.stringify({ kind, message: term }),
+            mimetype_rx: "application/json",
+            status_rx: status, tokens: 0, state: "resolved", outcome: null, attrs: "{}",
+        });
+    }
+}
+//# sourceMappingURL=TelemetryChannel.js.map

package/dist/core/TelemetryChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryChannel.js","sourceRoot":"","sources":["../../src/core/TelemetryChannel.ts"],"names":[],"mappings":"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"}

package/dist/core/TokenGauge.d.ts

@@ -0,0 +1,16 @@
+import type { Mimetypes } from "@plurnk/plurnk-mimetypes";
+import type { Provider } from "@plurnk/plurnk-providers";
+import type { Db } from "./Db.ts";
+import type { TelemetryEvent } from "@plurnk/plurnk-grammar";
+export interface GaugeResolution {
+    tokenizerId: string;
+    exact: boolean;
+    count: (text: string) => Promise<number>;
+}
+export default class TokenGauge {
+    #private;
+    static contentHash(content: string): string;
+    static resolve(mimetypes: Mimetypes | undefined, provider: Provider, pushTelemetry?: (e: TelemetryEvent) => void): Promise<GaugeResolution>;
+    static tokensFor(db: Db, gauge: GaugeResolution, contentHash: string, content: string): Promise<number>;
+}
+//# sourceMappingURL=TokenGauge.d.ts.map

package/dist/core/TokenGauge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenGauge.d.ts","sourceRoot":"","sources":["../../src/core/TokenGauge.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,CAAC,OAAO,OAAO,UAAU;;IAI3B,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1C;IAQD,OAAa,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBhJ;IAID,OAAa,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5G;CACJ"}