@cotal-ai/core 0.23.0 → 0.25.0

package/dist/run-notice.js

@@ -0,0 +1,212 @@
+/**
+ * The RUN NOTICE record: a bounded decision a workflow told an agent about, written onto the run.
+ *
+ * **A record and not a channel post.** `notify` is the only primitive that moves program-authored
+ * bytes toward an agent's context, and a post would put the program into the conversation as a
+ * participant — the one thing this plane's first non-negotiable forbids. So a notice is filed here,
+ * addressed to one agent, and rendered as a fixed key→value table ahead of that agent's next turn.
+ *
+ * **Keyed by a DERIVED addressee id.** An agent's name is dotted and a dot is the records-key
+ * separator, so a raw name in the key would silently re-tokenize it into a key of another shape —
+ * and a name is not an id token in the first place. The id is a digest of the name; a reader holding
+ * the handle re-derives it, so enumerating one agent's notices is still a single prefix scan.
+ *
+ * **The spec is create-only; the status is the consumption.** A notice is something the program
+ * decided, so its content is immutable — a retry after a crash re-derives the same id and lands on
+ * its own record rather than filing a second one. Whether it has been CONSUMED is a fact somebody
+ * else establishes later, which is why it lives in the status half: the migrate rule refuses to
+ * move a run whose notice has not yet been consumed by its addressee's next turn, and that rule
+ * needs something to read.
+ */
+import { createHash } from "node:crypto";
+import { EpEnvelopeError } from "./endpoint-envelope.js";
+import { assertIdToken } from "./endpoint-subjects.js";
+import { RECORD_KINDS, createRecordEntry, readRecord, recordSpecKey, recordStatusKey, assertStatusValue, } from "./endpoint-records.js";
+import { canonicalJson } from "./canonical.js";
+const SPEC_KEYS = ["v", "run", "step", "addressee", "fact", "at"];
+const STATUS_KEYS = ["v", "consumedAt", "by", "observedSpecRevision"];
+function qualifiers(endpoint, runId, addresseeId, noticeId) {
+    return [endpoint, runId, addresseeId, noticeId];
+}
+/** base64url of the sha256, truncated to 43 characters — the same shape and alphabet as a run's
+ *  request ids and a checkpoint answer id, so a derived id is an `<id-token>` by construction. */
+function digestId(canonical) {
+    return createHash("sha256").update(canonical, "utf8").digest("base64url").slice(0, 43);
+}
+/** The key token standing for an agent. Derived from the name, never the name itself. */
+export function noticeAddresseeId(agent) {
+    if (agent.length === 0)
+        throw new EpEnvelopeError("failed-precondition", `a notice addressee is an agent name; the empty string names nobody`);
+    return digestId(canonicalJson({ agent }));
+}
+/**
+ * The id one notice is filed under.
+ *
+ * Derived from the step's own request id and the addressee, so the same `notify` call re-run after
+ * a crash re-derives exactly the same ids and its create-only writes land on their own records. One
+ * call to N agents writes N notices, and the addressee is what separates them.
+ */
+export function runNoticeId(requestId, addressee) {
+    return digestId(canonicalJson({ requestId, addressee }));
+}
+function parseSpec(raw, key) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new EpEnvelopeError("internal", `notice ${key} is not an object; garbled state never authorizes`);
+    const o = raw;
+    for (const k of Object.keys(o))
+        if (!SPEC_KEYS.includes(k))
+            throw new EpEnvelopeError("internal", `notice ${key} carries the unknown field "${k}"; record schemas are closed`);
+    if (o.v !== 1 || typeof o.run !== "string" || typeof o.step !== "string"
+        || typeof o.addressee !== "string" || o.addressee.length === 0
+        || typeof o.at !== "number" || !Number.isSafeInteger(o.at) || o.at < 0)
+        throw new EpEnvelopeError("internal", `notice ${key} is malformed; garbled state never authorizes`);
+    const fact = o.fact;
+    if (fact === null || fact === undefined || typeof fact !== "object" || Array.isArray(fact)
+        || typeof fact.decision !== "string" || typeof fact.outcome !== "string")
+        throw new EpEnvelopeError("internal", `notice ${key} carries no decision fact; garbled state never authorizes`);
+    return {
+        v: 1,
+        run: o.run,
+        step: o.step,
+        addressee: o.addressee,
+        fact: fact,
+        at: o.at,
+    };
+}
+function parseStatus(raw, key) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new EpEnvelopeError("internal", `notice status ${key} is not an object; garbled state never authorizes`);
+    const o = raw;
+    for (const k of Object.keys(o))
+        if (!STATUS_KEYS.includes(k))
+            throw new EpEnvelopeError("internal", `notice status ${key} carries the unknown field "${k}"; record schemas are closed`);
+    if (o.v !== 1 || typeof o.consumedAt !== "number" || !Number.isSafeInteger(o.consumedAt) || o.consumedAt < 0
+        || typeof o.by !== "string" || o.by.length === 0)
+        throw new EpEnvelopeError("internal", `notice status ${key} is malformed; garbled state never authorizes`);
+    return {
+        v: 1,
+        consumedAt: o.consumedAt,
+        by: o.by,
+        observedSpecRevision: o.observedSpecRevision,
+    };
+}
+/**
+ * File one notice, create-only.
+ *
+ * A retry of the same notice is not a conflict: the id is derived from the step's request id and
+ * the addressee, so an existing record with identical bytes is this run's own earlier attempt.
+ * Different bytes under the same id would mean two different decisions claiming one identity, which
+ * is refused rather than overwritten — a notice that could be rewritten would be a message.
+ */
+export async function writeRunNotice(kv, endpoint, noticeId, value) {
+    assertIdToken(noticeId, "noticeId");
+    const addresseeId = noticeAddresseeId(value.addressee);
+    const key = recordSpecKey(RECORD_KINDS.notice, qualifiers(endpoint, value.run, addresseeId, noticeId));
+    try {
+        await createRecordEntry(kv, key, value);
+        return { key, created: true };
+    }
+    catch (e) {
+        if (!(e instanceof EpEnvelopeError && e.code === "conflict"))
+            throw e;
+        const existing = await kv.get(key);
+        if (!existing || existing.operation !== "PUT")
+            throw new EpEnvelopeError("internal", `notice ${key} lost its create CAS but is not readable; reconcile the store`);
+        const parsed = parseSpec(JSON.parse(new TextDecoder().decode(existing.value)), key);
+        if (canonicalJson(parsed) !== canonicalJson(value))
+            throw new EpEnvelopeError("conflict", `notice ${key} already exists with a different decision; a notice id is derived from the step that decided it, so a differing one under the same id is never overwritten`);
+        return { key, created: false };
+    }
+}
+/** Read one notice with its consumption, or `undefined` when nothing was filed under this id. */
+export async function readRunNotice(kv, endpoint, runId, addressee, noticeId) {
+    return await readByQualifiers(kv, qualifiers(endpoint, runId, noticeAddresseeId(addressee), noticeId), noticeId);
+}
+/** The same read from the KEY's own tokens, for a caller enumerating a run rather than an agent. */
+async function readByQualifiers(kv, q, noticeId) {
+    const merged = await readRecord(kv, RECORD_KINDS.notice, q);
+    if (merged === undefined)
+        return undefined;
+    const spec = parseSpec(merged.spec.value, recordSpecKey(RECORD_KINDS.notice, q));
+    const status = merged.status === undefined
+        ? undefined
+        : parseStatus(merged.status.value, recordStatusKey(RECORD_KINDS.notice, q));
+    return {
+        noticeId,
+        spec,
+        specRevision: merged.spec.revision,
+        ...(status !== undefined ? { consumed: status } : {}),
+    };
+}
+/**
+ * Every notice addressed to one agent on one run, oldest first.
+ *
+ * ORDER IS PART OF THE CONTRACT, because the render is a table a person or an agent reads top to
+ * bottom: `at` first, then the notice id, so two notices filed in the same millisecond still come
+ * back in one fixed order rather than in whatever order the store enumerated its keys.
+ */
+export async function listRunNotices(kv, endpoint, runId, addressee) {
+    const addresseeId = noticeAddresseeId(addressee);
+    const prefix = recordSpecKey(RECORD_KINDS.notice, qualifiers(endpoint, runId, addresseeId, "x")).slice(0, -"x.spec".length);
+    // ONE wildcard token, because the addressee is fixed and only the notice id varies.
+    return await scan(kv, `${prefix}*.spec`);
+}
+/**
+ * Every notice filed on one RUN, whoever it was addressed to, oldest first.
+ *
+ * The migrate rule asks a question the journal cannot answer on its own: a `notify` entry
+ * records an input HASH, not the agents it addressed, so "has this orphaned notify been consumed?"
+ * cannot be asked per addressee. It is asked per RUN, and each notice's own `step` says which entry
+ * it came from — which is why the step is in the value rather than only in the key.
+ */
+export async function listRunNoticesForRun(kv, endpoint, runId) {
+    const prefix = recordSpecKey(RECORD_KINDS.notice, qualifiers(endpoint, runId, "a", "n")).slice(0, -"a.n.spec".length);
+    // TWO, because both the addressee and the notice id vary — a KV filter's `*` is one token, and a
+    // single wildcard here would match a key shape that does not exist and return nothing at all.
+    return await scan(kv, `${prefix}*.*.spec`);
+}
+/** Read every notice a KV key filter matches. The filter is the caller's: `*` is one token. */
+async function scan(kv, filter) {
+    const found = [];
+    const seen = await kv.keys(filter);
+    const qs = [];
+    for await (const key of seen) {
+        // The key is `notice.<endpoint>.<runId>.<addresseeId>.<noticeId>.spec` and every qualifier is
+        // an id token, so the four the read wants are the four before `spec`. Taken from the KEY and
+        // not re-derived: an enumeration holds the addressee's digest, never the name it came from.
+        const parts = key.split(".");
+        qs.push(parts.slice(parts.length - 5, parts.length - 1));
+    }
+    for (const q of qs) {
+        const one = await readByQualifiers(kv, q, q[q.length - 1]);
+        if (one !== undefined)
+            found.push(one);
+    }
+    found.sort((a, b) => (a.spec.at - b.spec.at) || (a.noticeId < b.noticeId ? -1 : a.noticeId > b.noticeId ? 1 : 0));
+    return found;
+}
+/**
+ * Record that a turn carried this notice.
+ *
+ * **The create-only CAS is the arbiter, and it is the only one.** Two turns racing to claim one
+ * notice both read no status and both write; the store decides, and the loser gets a loud conflict.
+ * A "has it been consumed already?" check before the write would be a fast path that lies under
+ * exactly the race it looks like it is preventing, so there is one gate rather than two — which
+ * turn delivered a notice is a fact about something that happened once.
+ */
+export async function markRunNoticeConsumed(kv, endpoint, runId, addressee, noticeId, by, at) {
+    const q = qualifiers(endpoint, runId, noticeAddresseeId(addressee), noticeId);
+    const specKey = recordSpecKey(RECORD_KINDS.notice, q);
+    const statusKey = recordStatusKey(RECORD_KINDS.notice, q);
+    const merged = await readRecord(kv, RECORD_KINDS.notice, q);
+    if (merged === undefined)
+        throw new EpEnvelopeError("failed-precondition", `no notice is filed at ${specKey}; a consumption names the notice it consumed`);
+    const value = assertStatusValue({
+        v: 1,
+        consumedAt: at,
+        by,
+        observedSpecRevision: merged.spec.revision,
+    });
+    await createRecordEntry(kv, statusKey, value);
+}
+//# sourceMappingURL=run-notice.js.map

package/dist/run-notice.js.map

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

package/dist/run-record.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The run record: what a workflow run IS, beside the journal that says what it DID.
+ *
+ * The journal on WFJ is append-only and authoritative about events. This is last-value-wins and
+ * authoritative about state — who holds the run, what state it is in, and the PIN SET resolved once
+ * at start. Two runs of one program under different pins are two different runs, so a resume reads
+ * the pins back rather than re-deriving them: "the default" is a property of the interpreter, and
+ * the interpreter is the thing that may have changed between attempts.
+ *
+ * It also carries the one fact the journal cannot hold about itself: **how far the journal has
+ * got**. A record deleted from the TAIL of a run's subject leaves the survivors contiguous — the
+ * ordinal chain sees nothing missing, because the missing part is the part it would have compared
+ * against — and the per-subject head is recalculated backwards, so the fence accepts an append at a
+ * head the run already moved past. Measured end to end: the run replays SHORT and intact, a
+ * successor activates on it, and it resumes from a prefix that is missing work the run really did.
+ * No anchor inside the journal can detect that. `journalHigh` is the anchor OUTSIDE it.
+ *
+ * What that anchor does and does not cover, stated plainly because a guard believed to be wider
+ * than it is is worse than none: it is written at each ACTIVATION, so it detects truncation back
+ * past the last takeover. Steps appended since that activation are not covered — writing the record
+ * per append would double every step's cost, and the journal's own ordinal chain already covers
+ * every interior loss.
+ */
+import type { KV } from "@nats-io/kv";
+import { type MergedRecord } from "./endpoint-records.js";
+/**
+ * The pins, resolved. Structurally the language's `RunPins` — `@cotal-ai/core` does not depend on
+ * `@cotal-ai/lang`, and the wire shape is the contract between them rather than a shared type.
+ */
+export interface RunPinsValue {
+    readonly seed: string;
+    /** The run's logical epoch. `now()` derives from THIS, never from the resuming host's clock. */
+    readonly startedAt: number;
+    readonly yieldEvery: number;
+    readonly stepBudget: number;
+    readonly effectCeiling: number;
+    readonly languageVersion: string;
+}
+/**
+ * The immutable half: what this run IS, decided once and never re-decided.
+ *
+ * Deliberately NOT carrying a program hash yet. The interpreter reports one, but only after a run,
+ * and a hash computed here from the source would be a different function's answer wearing the same
+ * name — the divergence check that matters is per-step and the language already makes it from the
+ * recorded input hashes. A source-identity pin is its own item, not a field filled with a guess.
+ */
+export interface RunSpecValue {
+    readonly v: 1;
+    readonly run: string;
+    readonly pins: RunPinsValue;
+    readonly createdAt: number;
+}
+/**
+ * What a run is doing now.
+ *
+ * `released` and `failed` are not the same thing and the distinction is the point: a program that
+ * failed has a result and the journal has it, while a released run has no result at all — its
+ * driver stopped holding it. Recording one as the other would write down a conclusion about work
+ * nobody observed.
+ */
+export type RunState = "running" | "released" | "completed" | "failed";
+export interface RunStatusValue {
+    readonly v: 1;
+    readonly observedSpecRevision: number;
+    readonly state: RunState;
+    readonly holder: string;
+    readonly epoch: number;
+    readonly fencingToken: number;
+    /**
+     * The highest journal ordinal this run is KNOWN to have reached, written at each activation.
+     * A replay whose last ordinal is BELOW this has lost records from its tail.
+     */
+    readonly journalHigh: number;
+    readonly at: number;
+}
+/** A run's journal is missing records from its END — which nothing inside the journal can see. */
+export declare class RunJournalTailTruncated extends Error {
+    readonly run: string;
+    readonly recordedHigh: number;
+    readonly replayedHigh: number;
+    constructor(run: string, recordedHigh: number, replayedHigh: number);
+}
+/** Read a run's record. `undefined` = this run has never been started. */
+export declare function readRunRecord(kv: KV, endpoint: string, runId: string): Promise<MergedRecord<RunSpecValue, RunStatusValue> | undefined>;
+/**
+ * Create a run's spec. Create-only: a spec that already exists means this run was started before,
+ * and starting it again under a fresh set of pins would be a different run wearing the same id.
+ */
+export declare function createRunSpec(kv: KV, endpoint: string, runId: string, value: Omit<RunSpecValue, "v" | "run">): Promise<number>;
+/**
+ * Write a run's status. `expectedRevision` is `undefined` for the first write and the last read
+ * revision thereafter — the CAS is what keeps two drivers from taking turns overwriting each
+ * other's view of who holds the run.
+ */
+export declare function writeRunStatus(kv: KV, endpoint: string, runId: string, value: Omit<RunStatusValue, "v">, expectedRevision?: number): Promise<number>;
+/**
+ * The tail check, run BETWEEN the replay and the activation.
+ *
+ * Before, and not after, because an activation appended over a rolled-back head is itself a record
+ * written into a journal we already know is wrong — and it would be written at an ordinal the
+ * deleted records already used, which is a hole the chain would then blame on someone else.
+ */
+export declare function assertJournalTailIntact(runId: string, recorded: RunStatusValue | undefined, replayedHigh: number): void;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/run-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../src/run-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAQL,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,kGAAkG;AAClG,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,YAAY,EAAE,MAAM;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM;gBAFpB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM;CAUhC;AAED,0EAA0E;AAC1E,wBAAsB,aAAa,CACjC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,cAAc,CAAC,GAAG,SAAS,CAAC,CAEjE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,GAAG,GAAG,KAAK,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,GAAG,CAAC,EAChC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,YAAY,EAAE,MAAM,GACnB,IAAI,CAKN"}

package/dist/run-record.js

@@ -0,0 +1,58 @@
+import { RECORD_KINDS, createRecordEntry, updateRecordEntry, readRecord, recordSpecKey, recordStatusKey, assertStatusValue, } from "./endpoint-records.js";
+/** A run's journal is missing records from its END — which nothing inside the journal can see. */
+export class RunJournalTailTruncated extends Error {
+    run;
+    recordedHigh;
+    replayedHigh;
+    constructor(run, recordedHigh, replayedHigh) {
+        super(`run ${run}: the journal replayed to ordinal ${replayedHigh}, but this run is recorded as having reached ${recordedHigh}. ` +
+            `Records are missing from the END of the subject: the surviving prefix is contiguous, so the ordinal chain cannot see it, ` +
+            `and the subject's head has rolled back with them. Resuming here would repeat work the run already did. ` +
+            `Recover the missing records or retire the run; do not drive it.`);
+        this.run = run;
+        this.recordedHigh = recordedHigh;
+        this.replayedHigh = replayedHigh;
+        this.name = "RunJournalTailTruncated";
+    }
+}
+/** Read a run's record. `undefined` = this run has never been started. */
+export async function readRunRecord(kv, endpoint, runId) {
+    return await readRecord(kv, RECORD_KINDS.run, [endpoint, runId]);
+}
+/**
+ * Create a run's spec. Create-only: a spec that already exists means this run was started before,
+ * and starting it again under a fresh set of pins would be a different run wearing the same id.
+ */
+export async function createRunSpec(kv, endpoint, runId, value) {
+    const spec = { v: 1, run: runId, ...value };
+    return await createRecordEntry(kv, recordSpecKey(RECORD_KINDS.run, [endpoint, runId]), spec);
+}
+/**
+ * Write a run's status. `expectedRevision` is `undefined` for the first write and the last read
+ * revision thereafter — the CAS is what keeps two drivers from taking turns overwriting each
+ * other's view of who holds the run.
+ */
+export async function writeRunStatus(kv, endpoint, runId, value, expectedRevision) {
+    const status = assertStatusValue({ v: 1, ...value });
+    // Through the key BUILDER, never a join of our own: it is what asserts the endpoint and the run
+    // id are grammatical tokens, and a run id that tokenized loose would write into another run's key.
+    const key = recordStatusKey(RECORD_KINDS.run, [endpoint, runId]);
+    return expectedRevision === undefined
+        ? await createRecordEntry(kv, key, status)
+        : await updateRecordEntry(kv, key, status, expectedRevision);
+}
+/**
+ * The tail check, run BETWEEN the replay and the activation.
+ *
+ * Before, and not after, because an activation appended over a rolled-back head is itself a record
+ * written into a journal we already know is wrong — and it would be written at an ordinal the
+ * deleted records already used, which is a hole the chain would then blame on someone else.
+ */
+export function assertJournalTailIntact(runId, recorded, replayedHigh) {
+    if (recorded === undefined)
+        return;
+    if (replayedHigh < recorded.journalHigh) {
+        throw new RunJournalTailTruncated(runId, recorded.journalHigh, replayedHigh);
+    }
+}
+//# sourceMappingURL=run-record.js.map

package/dist/run-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.js","sourceRoot":"","sources":["../src/run-record.ts"],"names":[],"mappings":"AAwBA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,GAElB,MAAM,uBAAuB,CAAC;AAwD/B,kGAAkG;AAClG,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAErC;IACA;IACA;IAHX,YACW,GAAW,EACX,YAAoB,EACpB,YAAoB;QAE7B,KAAK,CACH,OAAO,GAAG,qCAAqC,YAAY,gDAAgD,YAAY,IAAI;YACzH,2HAA2H;YAC3H,yGAAyG;YACzG,iEAAiE,CACpE,CAAC;QATO,QAAG,GAAH,GAAG,CAAQ;QACX,iBAAY,GAAZ,YAAY,CAAQ;QACpB,iBAAY,GAAZ,YAAY,CAAQ;QAQ7B,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAM,EACN,QAAgB,EAChB,KAAa;IAEb,OAAO,MAAM,UAAU,CAA+B,EAAE,EAAE,YAAY,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AACjG,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAM,EACN,QAAgB,EAChB,KAAa,EACb,KAAsC;IAEtC,MAAM,IAAI,GAAiB,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC;IAC1D,OAAO,MAAM,iBAAiB,CAAC,EAAE,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAC/F,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAM,EACN,QAAgB,EAChB,KAAa,EACb,KAAgC,EAChC,gBAAyB;IAEzB,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,CAAC,EAAE,CAAU,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC9D,gGAAgG;IAChG,mGAAmG;IACnG,MAAM,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IACjE,OAAO,gBAAgB,KAAK,SAAS;QACnC,CAAC,CAAC,MAAM,iBAAiB,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC;QAC1C,CAAC,CAAC,MAAM,iBAAiB,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAa,EACb,QAAoC,EACpC,YAAoB;IAEpB,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACnC,IAAI,YAAY,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,IAAI,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/core",
   "description": "The Cotal protocol: endpoint, subjects, message types, the NATS client layer, and the extension contracts.",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "license": "Apache-2.0",
   "keywords": [
     "cotal",