@cotal-ai/core 0.12.0 → 0.13.0

package/dist/canonical.d.ts

@@ -0,0 +1,24 @@
+/** Digest identity form used everywhere a contract artifact is referenced: `sha256:<hex>`. */
+export declare const DIGEST_PREFIX: "sha256:";
+/** True iff `s` is a well-formed `sha256:<hex>` artifact digest. */
+export declare function isContractDigest(s: string): boolean;
+/** True iff the string is well-formed UTF-16 (no unpaired surrogate). A lone surrogate has NO
+ *  UTF-8 byte encoding — encoders silently substitute U+FFFD, so two distinct malformed strings
+ *  can collapse to one byte sequence; anything digest- or wire-bound must refuse them. */
+export declare function isWellFormedUnicode(s: string): boolean;
+/** RFC 8785 canonical JSON text of a value (strict: I-JSON enforced, no undefined→null). */
+export declare function canonicalJson(value: unknown): string;
+/** Content address of a contract artifact: `sha256:<hex>` over its RFC 8785 form (SPEC §13.7). */
+export declare function contractDigest(value: unknown): string;
+/** `sha256:<hex>` over RAW bytes (a string digests as its UTF-8 encoding), NEVER re-canonicalized:
+ *  the digest form for artifacts carried as opaque bytes — the §13.3 `auth` slot (`authDigest`,
+ *  digested exactly as carried) and the §13.4 raw stored submission bytes (`submissionDigest`).
+ *  A string input MUST be well-formed UTF-16: a lone surrogate has no UTF-8 encoding, the
+ *  encoder would substitute U+FFFD, and two DISTINCT carried values would silently share one
+ *  digest — the opposite of "exactly as carried". Throws instead. */
+export declare function rawDigest(data: Uint8Array | string): string;
+/** Verify fetched artifact BYTES against their advertised digest (verify-on-read, SPEC §13.7):
+ *  content addressing, not store ACLs, is the tamper boundary. The bytes must parse as JSON and
+ *  re-canonicalize to the digest; anything else throws. Returns the parsed artifact. */
+export declare function verifyArtifact(bytes: Uint8Array, digest: string): unknown;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAYA,8FAA8F;AAC9F,eAAO,MAAM,aAAa,EAAG,SAAkB,CAAC;AAGhD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;0FAE0F;AAC1F,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtD;AAsFD,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGpD;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAED;;;;;qEAKqE;AACrE,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAS3D;AAED;;wFAEwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAWzE"}

package/dist/canonical.js

@@ -0,0 +1,159 @@
+/**
+ * RFC 8785 canonical JSON and content addressing (SPEC §13.7, D28).
+ *
+ * Contract identity is the SHA-256 digest of the RFC 8785 canonicalization of a JSON value,
+ * over I-JSON: lone surrogates are rejected loudly (never escaped through), because a digest
+ * over non-interchangeable text is not an identity. The strict `canonicalizeEx` path is pinned
+ * (`undefinedInArrayToNull: false`): an `undefined` anywhere in the value is a programming
+ * error, not data, and MUST NOT silently become `null`.
+ */
+import { createHash } from "node:crypto";
+import { canonicalizeEx } from "json-canonicalize";
+/** Digest identity form used everywhere a contract artifact is referenced: `sha256:<hex>`. */
+export const DIGEST_PREFIX = "sha256:";
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+/** True iff `s` is a well-formed `sha256:<hex>` artifact digest. */
+export function isContractDigest(s) {
+    return DIGEST_RE.test(s);
+}
+/** True iff the string is well-formed UTF-16 (no unpaired surrogate). A lone surrogate has NO
+ *  UTF-8 byte encoding — encoders silently substitute U+FFFD, so two distinct malformed strings
+ *  can collapse to one byte sequence; anything digest- or wire-bound must refuse them. */
+export function isWellFormedUnicode(s) {
+    return !hasLoneSurrogate(s);
+}
+/** True iff the string contains an unpaired UTF-16 surrogate (not well-formed / I-JSON
+ *  violation). Manual scan: the repo's TS lib target predates `String#isWellFormed`. */
+function hasLoneSurrogate(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const n = s.charCodeAt(i + 1);
+            if (!(n >= 0xdc00 && n <= 0xdfff))
+                return true;
+            i++; // well-formed pair; skip the low half
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff) {
+            return true; // low surrogate with no preceding high half
+        }
+    }
+    return false;
+}
+/** Walk a JSON value and throw on anything that cannot canonicalize EXACTLY (D28: verification
+ *  and digesting must never run over a normalizing projection):
+ *   - strings that are not well-formed UTF-16 (a lone surrogate violates I-JSON; canonicalizing
+ *     it would mint a digest for text that cannot interchange), in values AND keys;
+ *   - `undefined` anywhere and non-finite numbers (RFC 8785 cannot represent them);
+ *   - NON-PLAIN-DATA graphs. `Object.entries` sees only enumerable string-keyed own data props,
+ *     and the canonicalizer applies `toJSON`, so a symbol-keyed or non-enumerable own property,
+ *     an accessor, or a class/exotic instance (Date → ISO string, Map → `{}`) would be SILENTLY
+ *     projected away or rewritten — the exact field-dropping class D28 forbids (an artifact
+ *     carrying state its signature never covered must refuse, not launder through the
+ *     projection). Objects must be ordinary with a `null`/`Object.prototype` prototype and only
+ *     enumerable string-keyed own DATA properties; arrays must be ordinary `Array.prototype`
+ *     arrays with no holes and no extra own properties. */
+function assertInterchangeable(v, path) {
+    if (v === null)
+        return;
+    switch (typeof v) {
+        case "string":
+            if (hasLoneSurrogate(v))
+                throw new Error(`canonicalJson: lone surrogate in string at ${path} (I-JSON violation)`);
+            return;
+        case "number":
+            if (!Number.isFinite(v))
+                throw new Error(`canonicalJson: non-finite number at ${path}`);
+            return;
+        case "boolean":
+            return;
+        case "undefined":
+            throw new Error(`canonicalJson: undefined at ${path} (strict mode never coerces to null)`);
+        case "object": {
+            if (Array.isArray(v)) {
+                if (Object.getPrototypeOf(v) !== Array.prototype)
+                    throw new Error(`canonicalJson: non-ordinary array at ${path} (a subclassed/exotic array canonicalizes through projections)`);
+                for (const k of Reflect.ownKeys(v)) {
+                    if (typeof k !== "string")
+                        throw new Error(`canonicalJson: symbol-keyed own property on array at ${path} (invisible to canonicalization; refusing the projection)`);
+                    if (k === "length")
+                        continue;
+                    if (!/^(0|[1-9][0-9]*)$/.test(k) || Number(k) >= v.length)
+                        throw new Error(`canonicalJson: non-index own property "${k}" on array at ${path} (invisible to canonicalization; refusing the projection)`);
+                }
+                for (let i = 0; i < v.length; i++) {
+                    const d = Object.getOwnPropertyDescriptor(v, i);
+                    if (d === undefined)
+                        throw new Error(`canonicalJson: hole at ${path}[${i}] (a hole would be coerced to null; refusing the projection)`);
+                    if (!d.enumerable || d.get !== undefined || d.set !== undefined)
+                        throw new Error(`canonicalJson: non-enumerable or accessor element at ${path}[${i}] (refusing the projection)`);
+                    assertInterchangeable(v[i], `${path}[${i}]`);
+                }
+                return;
+            }
+            const proto = Object.getPrototypeOf(v);
+            if (proto !== Object.prototype && proto !== null)
+                throw new Error(`canonicalJson: non-plain object at ${path} (a class/exotic instance canonicalizes through projections like toJSON; only plain data objects are interchangeable)`);
+            for (const k of Reflect.ownKeys(v)) {
+                if (typeof k !== "string")
+                    throw new Error(`canonicalJson: symbol-keyed own property at ${path} (invisible to canonicalization; refusing the projection)`);
+                if (hasLoneSurrogate(k))
+                    throw new Error(`canonicalJson: lone surrogate in key at ${path}.${k}`);
+                const d = Object.getOwnPropertyDescriptor(v, k);
+                if (!d.enumerable)
+                    throw new Error(`canonicalJson: non-enumerable own property "${k}" at ${path} (invisible to canonicalization; refusing the projection)`);
+                if (d.get !== undefined || d.set !== undefined)
+                    throw new Error(`canonicalJson: accessor property "${k}" at ${path} (a getter is code, not data; refusing the projection)`);
+                assertInterchangeable(v[k], `${path}.${k}`);
+            }
+            return;
+        }
+        default:
+            throw new Error(`canonicalJson: unsupported ${typeof v} at ${path}`);
+    }
+}
+/** RFC 8785 canonical JSON text of a value (strict: I-JSON enforced, no undefined→null). */
+export function canonicalJson(value) {
+    assertInterchangeable(value, "$");
+    return canonicalizeEx(value, { undefinedInArrayToNull: false });
+}
+/** Content address of a contract artifact: `sha256:<hex>` over its RFC 8785 form (SPEC §13.7). */
+export function contractDigest(value) {
+    return DIGEST_PREFIX + createHash("sha256").update(canonicalJson(value), "utf8").digest("hex");
+}
+/** `sha256:<hex>` over RAW bytes (a string digests as its UTF-8 encoding), NEVER re-canonicalized:
+ *  the digest form for artifacts carried as opaque bytes — the §13.3 `auth` slot (`authDigest`,
+ *  digested exactly as carried) and the §13.4 raw stored submission bytes (`submissionDigest`).
+ *  A string input MUST be well-formed UTF-16: a lone surrogate has no UTF-8 encoding, the
+ *  encoder would substitute U+FFFD, and two DISTINCT carried values would silently share one
+ *  digest — the opposite of "exactly as carried". Throws instead. */
+export function rawDigest(data) {
+    const h = createHash("sha256");
+    if (typeof data === "string") {
+        if (hasLoneSurrogate(data))
+            throw new Error("rawDigest: lone surrogate in string input; no UTF-8 encoding exists, the digest would not be over the carried value");
+        h.update(data, "utf8");
+    }
+    else {
+        h.update(data);
+    }
+    return DIGEST_PREFIX + h.digest("hex");
+}
+/** Verify fetched artifact BYTES against their advertised digest (verify-on-read, SPEC §13.7):
+ *  content addressing, not store ACLs, is the tamper boundary. The bytes must parse as JSON and
+ *  re-canonicalize to the digest; anything else throws. Returns the parsed artifact. */
+export function verifyArtifact(bytes, digest) {
+    if (!isContractDigest(digest))
+        throw new Error(`verifyArtifact: malformed digest ${JSON.stringify(digest)}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch (e) {
+        throw new Error(`verifyArtifact: artifact for ${digest} is not valid UTF-8 JSON: ${e.message}`);
+    }
+    const actual = contractDigest(parsed);
+    if (actual !== digest)
+        throw new Error(`verifyArtifact: digest mismatch; advertised ${digest}, content is ${actual}`);
+    return parsed;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

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

package/dist/connector.d.ts

@@ -23,6 +23,10 @@ export interface LaunchOpts {
         sentinelCredsPath: string;
         bearerCmd: string[];
     };
+    /** The incarnation's lifecycle UID (SPEC §13.1), minted by the launcher at spawn. The connector
+     *  forwards it (`COTAL_LIFECYCLE_UID`) so the session's endpoint binds its lifecycle-keyed
+     *  dm/dlv/chathist durables — the same exact names its credential pins. */
+    lifecycleUid?: string;
     servers?: string;
     /** The agent's resolved access policy — the SAME read/post set the manager mints the agent's
      *  creds from. The connector forwards it (`COTAL_SUBSCRIBE` / `COTAL_ALLOW_SUBSCRIBE` /

package/dist/connector.d.ts.map

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

package/dist/endpoint-action.d.ts

@@ -0,0 +1,424 @@
+/**
+ * The ACTION composite (SPEC §13.6): a long-running command as a pattern over the journal +
+ * records + events — zero new transport. `action` is a command MARKER, never a class: an
+ * action's submissions are `class: journal`, its accept/reject is the durable decision fact
+ * (§13.4), and there is no reply-rail answer to recover.
+ *
+ * THE RESULT FACT IS THE SINGLE TERMINAL ARBITER; THE STATUS ONLY EVER FOLLOWS IT, and every
+ * authority coordinate is bound to the PERSISTED accepted goal, never a caller claim. The
+ * pieces, each owned by the §13.9 principal named on its row:
+ *  - the GOAL BIND (canonicalizer): a create-only CAS on
+ *    `epf.<e>.goal.<caller triple>.<goalId>.bind` carrying the accepted fingerprint, BEFORE
+ *    acceptance — the bind keys on `goalId` and stops a second distinct submission before
+ *    acceptance and effect. A bind whose winner crashed BEFORE acceptance (no goal record) is
+ *    ORPHANED, and a same-fingerprint resubmission ADOPTS it ({@link resolveGoalSubmission}).
+ *  - the GOAL RECORD (commit path): `goal.<e>.<caller triple>.<goalId>` spec (the accepted
+ *    definition — the trusted source every later seam validates against) + status (the CURRENT
+ *    state projection). The status vocabulary is `accepted → running ⇄ waiting → terminal`,
+ *    `cancelling` between a cancel and its terminal. A TERMINAL status exists ONLY as the
+ *    projection of the committed result fact ({@link projectGoalTerminal}); {@link
+ *    transitionGoal} refuses terminal targets, so the status never leads the journal. Every
+ *    EXECUTOR-authored transition on a TARGET-PINNED goal proves the executor's fresh
+ *    lifecycle/epoch currency (§13.6 item 7: a superseded epoch cannot commit transitions).
+ *  - the TERMINAL RESULT (commit path): a create-only CAS on
+ *    `epf.<e>.goal.<caller triple>.<goalId>.result` — the ONE commit point where completion,
+ *    cancel, expiry-deny, and the readiness `uncertain` settle race, first terminal fact wins
+ *    uniformly. The raw CAS is PRIVATE; the public commit takes a CLOSED CAUSE whose
+ *    authoritative predicate is verified INSIDE the boundary (a `complete` proves executor
+ *    currency, a `cancel` proves the goal is `cancelling`, a `readiness` proves the deadline
+ *    passed) and DERIVES the terminal state from the cause — a raw state is never accepted.
+ *  - the TOMBSTONE (§13.6 item 5): the summary lives INSIDE the one immutable result fact;
+ *    retaining the fact the full idempotency horizon satisfies both retention minimums, and
+ *    early payload eviction is a serving-layer policy answered with {@link goalTombstone}.
+ *  - PROGRESS rides per-goal events, read-scoped to the caller at mint time.
+ *
+ * Every seam takes a BRANDED {@link ActionContext} bonding the record store + fact stream +
+ * space, so a composition mixup cannot read an accepted spec from space A and project through
+ * space B. Clocks are inputs everywhere (`now`, `acceptedAt`): the owner's clock decides.
+ */
+import type { KV } from "@nats-io/kv";
+import { type JetStreamClient, type JetStreamManager } from "@nats-io/jetstream";
+import { type NatsConnection } from "@nats-io/transport-node";
+import { EpEnvelopeError } from "./endpoint-envelope.js";
+import { type EpCaller, type ParsedEpRequest } from "./endpoint-subjects.js";
+import { type Receipt, type ReceiptStoreContext } from "./endpoint-receipt.js";
+/** A trusted, space-bonded action context: the KV + JS + JSM all DERIVE from one binding-layer
+ *  connection and one space by the constructor (never injected independently — a branded bundle
+ *  of split resources would still split accepted state from terminal authority), so a
+ *  composition mixup can never read an accepted spec through one broker and commit its terminal
+ *  through another. BRANDED: a hand-assembled structural look-alike is rejected at every seam,
+ *  not just discouraged. */
+export interface ActionContext {
+    kv: KV;
+    js: JetStreamClient;
+    jsm: JetStreamManager;
+    space: string;
+}
+export declare function actionContext(nc: NatsConnection, space: string): Promise<ActionContext>;
+/** A CONSTRUCTION-BOUND owner-authority proof: minted only from the branded context by the
+ *  commit principal itself, and accepted only against THAT context. This replaces a raw
+ *  `ownerAuthored` boolean — a flag any caller could set by typo or confusion — with a value
+ *  that cannot be hand-assembled and cannot leak across contexts: owner authority over a
+ *  target-pinned goal's pause/deny is proven by construction, never asserted (SPEC 13.6). */
+export interface OwnerCommitProof {
+    readonly space: string;
+}
+export declare function ownerCommitProof(ctx: ActionContext): OwnerCommitProof;
+/** A GATE-MINTED clearance: the only key that opens a GUARDED goal's edge into `running`
+ *  (SPEC 13.6: a guarded command MUST NOT effect until the guard answered allow, and `running`
+ *  IS effecting). The mint lives behind a ONE-SHOT claim that THE guard gate module takes at
+ *  load, so no other holder of an action context can mint gate passage - an owner proof
+ *  deliberately does NOT satisfy this edge (any context holder mints owner proofs; only the
+ *  gate, whose allow/release/reconcile arms verified the guard's answer, mints clearance). */
+export interface GuardClearance {
+    readonly goalId: string;
+}
+/** ONE-SHOT handoff of the clearance mint to THE gate (endpoint-guard claims it at module
+ *  load; the package always loads it). Every later call is a loud refusal: there is exactly
+ *  one gate, so a second claimant is by definition not it (SPEC 13.6). */
+export declare function claimGuardClearanceMint(): (ctx: ActionContext, goalId: string) => GuardClearance;
+/** A goal's coordinates: the owning endpoint + the caller triple + the client-chosen goalId. */
+export interface GoalRef {
+    endpoint: string;
+    caller: EpCaller;
+    goalId: string;
+}
+/** Snapshot a caller-supplied ref to a validated DETACHED copy at seam entry, BEFORE the first
+ *  await: a shared mutable ref can otherwise split one operation's identity across its reads,
+ *  its CAS, and its terminal publish. Exported for the guard seams, which detach the goal they
+ *  bind, resume, and project against the same discipline. */
+export declare function snapshotRef(ref: GoalRef): GoalRef;
+/** Derive a goal ref STRUCTURALLY from the broker-authenticated request (§13.6): the caller
+ *  triple comes from the subject the broker admitted, DETACHED so a later mutation of the parsed
+ *  request cannot retarget it, never from body fields — a seam taking this ref addresses only
+ *  the authenticated caller's own goals. */
+export declare function goalRefOf(request: ParsedEpRequest, goalId: string): GoalRef;
+/** The goal's terminal-result fact subject (`epf.<e>.goal.<triple>.<goalId>.result`, §13.2). */
+export declare function goalResultSubject(space: string, ref: GoalRef): string;
+/** The per-goal progress EVENT topic tail (§13.2 reserved topics). */
+export declare function goalProgressTopic(ref: GoalRef): string[];
+/** The bind fact: the goalId's accepted fingerprint, immutable for the goal's lifetime. */
+export interface GoalBindFact {
+    v: 1;
+    goalId: string;
+    fingerprint: string;
+}
+/** Bind a goal to its accepted fingerprint BEFORE acceptance (the canonicalizer's seam): a
+ *  create-only CAS per goalId. The winner proceeds; a loser reads the recorded bind and decides
+ *  (same fingerprint = retry, different = `conflict` before acceptance and effect). The subject
+ *  derives from the goal ref — ONE entry-derived identity (a caller derives it from the
+ *  broker-authenticated request via {@link goalRefOf} exactly once), never body fields. */
+export declare function bindGoal(ctx: ActionContext, ref: GoalRef, fingerprint: string): Promise<{
+    bound: true;
+} | {
+    bound: false;
+    existing: GoalBindFact;
+}>;
+/** The submission-vs-bind verdict (§13.6 item 5 + orphan recovery). */
+export type GoalSubmissionVerdict = {
+    kind: "new";
+} | {
+    kind: "cached";
+    bind: GoalBindFact;
+    result?: GoalResultFact;
+} | {
+    kind: "adopted";
+    bind: GoalBindFact;
+} | {
+    kind: "conflict";
+    bind: GoalBindFact;
+};
+/** Resolve a goal submission against the bind rail (the canonicalizer's composed seam): NEW
+ *  work (bind won); the caller's retry serving the CACHED decision/outcome (same fingerprint +
+ *  a persisted goal whose spec AGREES with the bind); orphan ADOPTION (same fingerprint, no goal
+ *  record — the bind winner crashed pre-acceptance); or `conflict` (different fingerprint). A
+ *  persisted spec whose fingerprint disagrees with the bind is a loud `internal` (garbled
+ *  authority chain), never a silent cached serve. */
+export declare function resolveGoalSubmission(ctx: ActionContext, request: ParsedEpRequest, goalId: string, fingerprint: string): Promise<GoalSubmissionVerdict>;
+/** The §13.6 single status vocabulary for every long-running surface. */
+export declare const GOAL_STATES: readonly ["accepted", "running", "waiting", "cancelling", "succeeded", "failed", "cancelled", "expired", "uncertain"];
+export type GoalState = (typeof GOAL_STATES)[number];
+/** All five are TERMINAL and immutable; first-terminal-fact-wins applies uniformly. */
+export declare const GOAL_TERMINAL_STATES: readonly GoalState[];
+/** The legal §13.6 transitions: `accepted → running ⇄ waiting`, `cancelling` between a cancel
+ *  and its terminal, every non-terminal may project a terminal, a terminal absorbs. */
+export declare function isLegalGoalTransition(from: GoalState, to: GoalState): boolean;
+/** The goal SPEC (written once at acceptance): the accepted definition every later seam
+ *  validates against — the terminal commit stamps ITS fingerprint from here, the readiness
+ *  settle reads ITS bound from here, and a target-pinned goal fences on ITS target lifecycle. */
+export interface GoalSpecValue {
+    v: 1;
+    goalId: string;
+    fingerprint: string;
+    command: string;
+    caller: {
+        id: string;
+        lifecycleUid: string;
+    };
+    target?: {
+        owner: string;
+        actor: string;
+        lifecycleUid: string;
+        mappingRevision: number;
+    };
+    /** The accepted submission's request id — the goal's ADDRESS for its durable acceptance fact
+     *  (`epf.<e>.dec.<triple>.<id>`), written at acceptance when it is known. The raw submission
+     *  (EPJ) is age-evicted, so receipt reconstruction after a crash reads the acceptance THROUGH
+     *  this address and proves the chain (id + sourceSeq + fingerprint) before minting (§13.10). */
+    requestId: string;
+    /** The guard endpoint named by the command's VERIFIED `ai.cotal.guarded` trait value,
+     *  recorded at acceptance. Its PRESENCE is what {@link transitionGoal} enforces: a guarded
+     *  goal's edge into `running` opens only with THE gate's {@link GuardClearance} - an
+     *  unrecorded guard binding is unenforceable, so the acceptance path MUST record it
+     *  (SPEC 13.6/13.7). */
+    guard?: string;
+    sourceSeq: number;
+    acceptedAt: number;
+    readinessDeadlineMs?: number;
+}
+/** Read the persisted accepted goal (`undefined` = never accepted). A DEL marker refuses. */
+export declare function readGoalSpec(ctx: ActionContext, ref: GoalRef): Promise<{
+    value: GoalSpecValue;
+    revision: number;
+} | undefined>;
+/** The goal STATUS value: the current state projection. State-dependent fields are CLOSED. */
+export interface GoalStatusValue extends Record<string, unknown> {
+    state: GoalState;
+    checkpoint?: {
+        token: string;
+        deadlineGeneration: number;
+    };
+    cancelMode?: "graceful" | "terminate";
+    observedSpecRevision: number;
+}
+/** Create the goal record at acceptance, IDEMPOTENTLY (spec create-only, then the `accepted`
+ *  status): a crash between the two writes (or an adopted-retry replay) re-reads the spec,
+ *  requires it CONTENT-IDENTICAL, and ensures the status — no stranded spec-only goal. */
+export declare function createGoal(ctx: ActionContext, ref: GoalRef, spec: Omit<GoalSpecValue, "v" | "goalId">): Promise<{
+    specRevision: number;
+}>;
+/** Read the goal's current status projection (`undefined` = unknown goal). */
+export declare function readGoalStatus(ctx: ActionContext, ref: GoalRef): Promise<{
+    value: GoalStatusValue;
+    revision: number;
+} | undefined>;
+/** Leader-read a goal's status projection by ref ALONE (no {@link ActionContext}) — a fencing read
+ *  for a caller OUTSIDE the action module. The retirement drain uses it to decide whether an
+ *  accepted ACTION goal is still `accepted` (never entered `running`, the guard/currency-fenced
+ *  effecting edge, so provably never effected) before it may create-only cancel it: a `cancelled`
+ *  terminal must mean the effect did NOT run (SPEC 13.6). `undefined` = no goal record at all
+ *  (never created ⇒ never ran). Leader-served (read-your-writes), so a running executor's
+ *  transition is never missed as a stale absence and a mis-read never authorizes a false cancel. */
+export declare function readGoalStatusByRefLeader(jsm: JetStreamManager, space: string, ref: GoalRef): Promise<GoalStatusValue | undefined>;
+/** The executor's authenticated identity (subject/creds, never a body claim), required when a
+ *  goal's spec pins a target lifecycle (§13.6 item 7). */
+export interface GoalExecutor {
+    lifecycleUid: string;
+    epoch: number;
+}
+/** CAS the goal's status through the NON-TERMINAL machine. A TERMINAL target is REFUSED (a
+ *  terminal status exists only as {@link projectGoalTerminal}). An EXECUTOR-authored PROGRESS
+ *  transition (`running`/`waiting`) on a TARGET-PINNED goal MUST prove the executor's fresh
+ *  currency; a `cancelling` transition is owner/caller-authored (its authority is the cancel's
+ *  broker-authenticated caller, {@link requestGoalCancel}) and takes no executor; an OWNER pause
+ *  (guard hold → `waiting`) may declare `ownerAuthored`. A target-pinned progress transition
+ *  with neither executor nor `ownerAuthored` is refused. */
+export declare function transitionGoal(ctx: ActionContext, ref: GoalRef, to: GoalState, opts?: {
+    fields?: Partial<Pick<GoalStatusValue, "checkpoint" | "cancelMode">>;
+    executor?: GoalExecutor;
+    resolveCurrentEpoch?: (target: {
+        owner: string;
+        actor: string;
+        lifecycleUid: string;
+    }) => Promise<number | null> | number | null;
+    epochResolveBudgetMs?: number;
+    /** The owner's own commit principal drives this (guard-hold pause/release): a
+     *  CONSTRUCTION-BOUND {@link ownerCommitProof} from THIS context, never a raw flag. */
+    owner?: OwnerCommitProof;
+    /** THE gate's construction-bound {@link GuardClearance} - REQUIRED on a GUARDED goal's
+     *  edge into `running` (SPEC 13.6 MUST-NOT-effect-until-allow; an owner proof does NOT
+     *  satisfy this edge, since any context holder mints owner proofs). */
+    clearance?: GuardClearance;
+}): Promise<GoalStatusValue>;
+/** Project the WINNING terminal fact onto the status — the ONLY path a status reaches a terminal
+ *  state, and the crash reconciler for a commit that fenced the fact but died before projecting.
+ *  Cross-checks the fact's fingerprint against the persisted spec (a terminal fact whose
+ *  fingerprint disagrees with the accepted goal is a garbled authority chain). */
+export declare function projectGoalTerminal(ctx: ActionContext, ref: GoalRef): Promise<GoalStatusValue>;
+export type GoalOutcomeState = "succeeded" | "failed" | "cancelled" | "expired" | "uncertain";
+/** The goal's terminal fact + the §13.6 item-5 tombstone summary in one immutable artifact. */
+export interface GoalResultFact {
+    v: 1;
+    goalId: string;
+    fingerprint: string;
+    state: GoalOutcomeState;
+    outcomeDigest: string;
+    data?: unknown;
+    ts: number;
+}
+/** Build the retirement-cancelled goal terminal (§13.8 option (i)): the FIRST-CLASS `cancelled`
+ *  outcome state the goal union ALREADY carries — no new wire shape — bound to the acceptance's
+ *  fingerprint, with the retirement attribution riding the digest-bound payload
+ *  (`data.cancelledBy = { opId, target }`). Published create-only on the goal's result subject,
+ *  so a racing real commit wins by landing first (first-terminal-wins, §13.8). A retirement
+ *  cancels only ITS OWN target's accepted goals. */
+export declare function goalCancelledResultOf(acceptance: {
+    fingerprint: string;
+    request: Record<string, unknown>;
+    target?: {
+        owner: string;
+        actor: string;
+        lifecycleUid: string;
+    };
+}, cancelled: {
+    opId: string;
+    target: {
+        owner: string;
+        actor: string;
+        lifecycleUid: string;
+    };
+}, ts: number): GoalResultFact;
+/** The §13.6 item-5 tombstone serving form for a payload-evicted retry. */
+export declare function goalTombstone(fact: GoalResultFact): GoalResultFact;
+/** Closed validation, IDENTITY-BOUND to the ref, with the tombstone digest RE-VERIFIED. */
+export declare function parseGoalResultFact(raw: unknown, subject: string, ref: GoalRef): GoalResultFact;
+/** Read the goal's cached terminal outcome (`undefined` = not terminal yet). */
+export declare function readGoalResult(ctx: ActionContext, ref: GoalRef): Promise<GoalResultFact | undefined>;
+/** What receipt emission needs beyond the action context: the receipt store bonded to the SAME
+ *  space AND the same connection, the EMITTING instance recorded as EVIDENCE (who produced this
+ *  attestation - after a crash the reconciling instance records ITSELF here, so this is never
+ *  proof of who EXECUTED the goal, and never redemption authority; the executed outcome's
+ *  authority is the committed terminal fact alone), and the receipts-scoped signer + key. */
+export interface ReceiptEmissionWiring {
+    store: ReceiptStoreContext;
+    instance: {
+        id: string;
+        instanceId: string;
+        epoch: number;
+    };
+    signer: {
+        keyId: string;
+    };
+    keyPair: {
+        sign(input: Uint8Array): Uint8Array;
+    };
+}
+/** One emission attempt's outcome: `emitted` (this attempt's receipt won the create-only CAS)
+ *  or `converged` (a receipt already attests these facts — an earlier attempt's or a racing
+ *  emitter's, ADOPTED only after it proves agreement with the facts). A recorded receipt that
+ *  DISAGREES with the committed facts is a loud `conflict`, never adopted. */
+export type ReceiptEmissionResult = {
+    outcome: "emitted" | "converged";
+    receipt: Receipt;
+};
+/** The durable backstop for the §13.10 MUST-emit guarantee: re-derive and publish the receipt
+ *  for a goal whose terminal committed but whose emission was omitted (a crash between the
+ *  terminal CAS and the publish, or a commit made without emission wiring). Reads the persisted
+ *  spec and the committed terminal FRESH, then runs the SAME emission seam the inline path uses.
+ *  `no-terminal` = nothing to attest yet (the goal simply is not terminal — never an error). */
+export declare function reconcileReceiptEmission(ctx: ActionContext, wiring: ReceiptEmissionWiring, args: {
+    ref: GoalRef;
+    now: number;
+}): Promise<ReceiptEmissionResult | {
+    outcome: "no-terminal";
+}>;
+/** A deny's AUTHORITATIVE PREDICATE (§13.6): a bare `deny` proves nothing, so the commit
+ *  boundary requires and VERIFIES one of:
+ *   - `hold-expired`: the named checkpoint's recorded spec must BIND this exact goal and its
+ *     recorded one-use settlement must be `expired` (the arbiter's own fact — a live or resumed
+ *     hold never denies);
+ *   - `owner`: the owner's construction-bound {@link ownerCommitProof} from THIS context (a
+ *     guard-verdict deny the owner itself is committing). */
+export type GoalDenial = {
+    kind: "hold-expired";
+    token: string;
+} | {
+    kind: "owner";
+    owner: OwnerCommitProof;
+};
+/** The closed terminal CAUSE (§13.6): the public commit accepts ONLY these, each with its own
+ *  authoritative predicate verified inside the boundary; the terminal state is DERIVED, never a
+ *  raw caller value.
+ *   - `complete`: the executor's own outcome (`succeeded`|`failed`), proving fresh currency for
+ *     a target-pinned goal;
+ *   - `cancel`: `cancelled`, requiring the goal to be `cancelling` (a cancel was requested);
+ *   - `deny`: `failed`, requiring the verified {@link GoalDenial} predicate (a bare deny cause
+ *     is refused — any commit-seam holder could otherwise fail any accepted goal);
+ *   - `readiness`: `uncertain`, the OWNER's deadline settlement, requiring `now` past the
+ *     persisted acceptance-relative readiness deadline (no executor — a target-pinned goal's
+ *     owner deadline is reachable). */
+export type GoalCommitCause = {
+    cause: "complete";
+    state: "succeeded" | "failed";
+    data?: unknown;
+    executor?: GoalExecutor;
+    resolveCurrentEpoch?: (target: {
+        owner: string;
+        actor: string;
+        lifecycleUid: string;
+    }) => Promise<number | null> | number | null;
+    epochResolveBudgetMs?: number;
+} | {
+    cause: "cancel";
+    data?: unknown;
+} | {
+    cause: "deny";
+    denial: GoalDenial;
+    data?: unknown;
+} | {
+    cause: "readiness";
+};
+/** Commit the goal's terminal state at the ONE mediated commit point, BOUND to the persisted
+ *  accepted goal and its CAUSE (see {@link GoalCommitCause}). First terminal fact wins uniformly
+ *  (completion, cancel, deny, and readiness race here); a loser observes the winner and its
+ *  projection converges. Every operation input detaches at ENTRY (single-read, before the first
+ *  await): a caller mutating cause/state/data/executor across the spec read changes nothing.
+ *
+ *  RECEIPT EMISSION (§13.10): with `receipts` wired, the commit emits the terminal's receipt
+ *  INLINE, best-effort, for the WINNING fact (won or lost — the terminal is committed either
+ *  way and emission is idempotent). Invalid wiring refuses at ENTRY, before any terminal
+ *  commits; a RUNTIME emission failure after the irreversible commit surfaces as
+ *  `receiptEmission: { outcome: "failed" }` — it never masks the committed terminal, and
+ *  {@link reconcileReceiptEmission} is the durable backstop that converges it. */
+export declare function commitGoalResult(ctx: ActionContext, args: {
+    ref: GoalRef;
+    now: number;
+    receipts?: ReceiptEmissionWiring;
+} & GoalCommitCause): Promise<{
+    won: boolean;
+    fact: GoalResultFact;
+    status: GoalStatusValue;
+    receiptEmission?: ReceiptEmissionResult | {
+        outcome: "failed";
+        error: EpEnvelopeError;
+    };
+}>;
+/** The reverse-DNS detail kind carrying a goal's cached terminal fact on an error (§13.3). */
+export declare const GOAL_TERMINAL_DETAIL_KIND = "ai.cotal.goal.terminal";
+/** The reserved `cancel` command's handler seam. The goal ref derives STRUCTURALLY from the
+ *  broker-authenticated request (a caller cancels only its own goals). Unknown = failed-
+ *  precondition; terminal = failed-precondition with the cached outcome on error.details;
+ *  otherwise the status transitions to `cancelling` (owner/caller-authored — no executor) and
+ *  the owner later commits the `cancel` cause. A completion that landed during the transition is
+ *  observed AFTER it and converges the projection. */
+export declare function requestGoalCancel(ctx: ActionContext, args: {
+    request: ParsedEpRequest;
+    goalId: string;
+    mode: "graceful" | "terminate";
+}): Promise<GoalStatusValue>;
+/** Settle a goal `uncertain` at its persisted acceptance-relative readiness deadline (the
+ *  `readiness` cause). The bound is read from the PERSISTED spec; a target-pinned goal is
+ *  REACHABLE (readiness is the owner's deadline, not an executor completion, so no executor is
+ *  required). A racing late success that committed first wins and this returns the winner. */
+export declare function settleGoalUncertain(ctx: ActionContext, args: {
+    ref: GoalRef;
+    now: number;
+}): Promise<{
+    won: boolean;
+    fact: GoalResultFact;
+    status: GoalStatusValue;
+}>;
+/** Classify a resubmission against the recorded bind: same fingerprint = retry (cached), else
+ *  `conflict`. {@link resolveGoalSubmission} composes this with the orphaned-bind recovery. */
+export declare function classifyGoalReuse(existing: GoalBindFact, submittedFingerprint: string): "cached" | "conflict";
+//# sourceMappingURL=endpoint-action.d.ts.map