@nifrajs/coding-agent 3.2.0

package/dist/orchestration/dispatch.js

@@ -0,0 +1,220 @@
+/**
+ * Evidence-only dispatch contracts for at-least-once run execution.
+ *
+ * These values deliberately contain no job payload, tenant state, credentials, retention policy,
+ * error message, or tool/model data. A durable operated adapter may implement the ports, but the
+ * public reference adapters are disposable and keep only identifiers, digests, counters, and
+ * lifecycle evidence. Delivery is at-least-once; callers make effects idempotent with the key
+ * derived below and prove completion before a recovered worker skips the effect.
+ */
+import { sha256HexOf } from "./hash.js";
+export const RUN_DISPATCH_VERSION = 1;
+export const DISPATCH_JOB_NAME = "nifra.agent.run-node";
+export const MAX_DISPATCH_STRING = 256;
+export const MAX_DISPATCH_ATTEMPTS = 16;
+export const systemClock = Object.freeze({ now: () => Date.now() });
+const DIGEST = /^[0-9a-f]{64}$/;
+const TOKEN = /^[A-Za-z0-9._:-]{1,256}$/;
+const FORBIDDEN = new Set([
+    "prompt",
+    "message",
+    "text",
+    "input",
+    "output",
+    "arguments",
+    "body",
+    "response",
+    "secret",
+    "credential",
+    "diagnostic",
+    "stack",
+    "content",
+    "transcript",
+    "artifact",
+]);
+function record(value, where) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError(`${where} must be an object`);
+    return value;
+}
+function rejectKeys(value, allowed, where) {
+    for (const key of Object.keys(value)) {
+        if (FORBIDDEN.has(key.toLowerCase()))
+            throw new TypeError(`${where} contains forbidden field '${key}'`);
+        if (!allowed.has(key))
+            throw new TypeError(`${where} contains unknown field '${key}'`);
+    }
+}
+function boundedString(value, name) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_DISPATCH_STRING)
+        throw new TypeError(`${name} must be a non-empty bounded string`);
+    return value;
+}
+function digest(value, name) {
+    const text = boundedString(value, name);
+    if (!DIGEST.test(text))
+        throw new TypeError(`${name} must be a lowercase sha256 digest`);
+    return text;
+}
+function token(value, name) {
+    const text = boundedString(value, name);
+    if (!TOKEN.test(text))
+        throw new TypeError(`${name} must be an opaque schedule token`);
+    return text;
+}
+function nonNegative(value, name) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    return value;
+}
+function attempts(value) {
+    const result = nonNegative(value, "maxAttempts");
+    if (result < 1 || result > MAX_DISPATCH_ATTEMPTS)
+        throw new RangeError(`maxAttempts must be between 1 and ${MAX_DISPATCH_ATTEMPTS}`);
+    return result;
+}
+const DISPATCH_KEYS = new Set([
+    "version",
+    "dispatchId",
+    "runId",
+    "planDigest",
+    "nodeId",
+    "maxAttempts",
+    "notBefore",
+]);
+/** Parse a dispatch identity and reject content or undeclared fields. */
+export function parseRunDispatch(value) {
+    const input = record(value, "run dispatch");
+    rejectKeys(input, DISPATCH_KEYS, "run dispatch");
+    if (input.version !== RUN_DISPATCH_VERSION)
+        throw new TypeError("run dispatch.version is unsupported");
+    return Object.freeze({
+        version: RUN_DISPATCH_VERSION,
+        dispatchId: token(input.dispatchId, "dispatchId"),
+        runId: token(input.runId, "runId"),
+        planDigest: digest(input.planDigest, "planDigest"),
+        nodeId: token(input.nodeId, "nodeId"),
+        maxAttempts: attempts(input.maxAttempts),
+        notBefore: nonNegative(input.notBefore, "notBefore"),
+    });
+}
+const LEASE_KEYS = new Set([
+    "version",
+    "leaseId",
+    "dispatch",
+    "attempt",
+    "generation",
+    "leasedAt",
+    "leaseUntil",
+    "scheduleToken",
+    "idempotencyKey",
+]);
+export function parseRunLease(value) {
+    const input = record(value, "run lease");
+    rejectKeys(input, LEASE_KEYS, "run lease");
+    if (input.version !== RUN_DISPATCH_VERSION)
+        throw new TypeError("run lease.version is unsupported");
+    const attempt = attempts(input.attempt);
+    const generation = nonNegative(input.generation, "generation");
+    return Object.freeze({
+        version: RUN_DISPATCH_VERSION,
+        leaseId: token(input.leaseId, "leaseId"),
+        dispatch: parseRunDispatch(input.dispatch),
+        attempt,
+        generation,
+        leasedAt: nonNegative(input.leasedAt, "leasedAt"),
+        leaseUntil: nonNegative(input.leaseUntil, "leaseUntil"),
+        scheduleToken: token(input.scheduleToken, "scheduleToken"),
+        idempotencyKey: token(input.idempotencyKey, "idempotencyKey"),
+    });
+}
+const CHECKPOINT_KEYS = new Set([
+    "version",
+    "dispatchId",
+    "runId",
+    "nodeId",
+    "attempt",
+    "generation",
+    "boundary",
+    "idempotencyKey",
+    "at",
+    "scheduleToken",
+]);
+export function parseRunCheckpoint(value) {
+    const input = record(value, "run checkpoint");
+    rejectKeys(input, CHECKPOINT_KEYS, "run checkpoint");
+    if (input.version !== RUN_DISPATCH_VERSION)
+        throw new TypeError("run checkpoint.version is unsupported");
+    const boundary = input.boundary;
+    if (boundary !== "before-effect" && boundary !== "after-effect")
+        throw new TypeError("run checkpoint.boundary is invalid");
+    return Object.freeze({
+        version: RUN_DISPATCH_VERSION,
+        dispatchId: token(input.dispatchId, "dispatchId"),
+        runId: token(input.runId, "runId"),
+        nodeId: token(input.nodeId, "nodeId"),
+        attempt: attempts(input.attempt),
+        generation: nonNegative(input.generation, "generation"),
+        boundary,
+        idempotencyKey: token(input.idempotencyKey, "idempotencyKey"),
+        at: nonNegative(input.at, "at"),
+        scheduleToken: token(input.scheduleToken, "scheduleToken"),
+    });
+}
+const EVIDENCE_KEYS = new Set([
+    "version",
+    "dispatchId",
+    "runId",
+    "nodeId",
+    "state",
+    "attempt",
+    "generation",
+    "at",
+    "scheduleToken",
+    "idempotencyKey",
+    "code",
+]);
+const STATES = new Set([
+    "queued",
+    "leased",
+    "checkpointed",
+    "retrying",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "dead-lettered",
+]);
+export function parseRunDispatchEvidence(value) {
+    const input = record(value, "run dispatch evidence");
+    rejectKeys(input, EVIDENCE_KEYS, "run dispatch evidence");
+    if (input.version !== RUN_DISPATCH_VERSION)
+        throw new TypeError("run dispatch evidence.version is unsupported");
+    if (typeof input.state !== "string" || !STATES.has(input.state))
+        throw new TypeError("run dispatch evidence.state is invalid");
+    return Object.freeze({
+        version: RUN_DISPATCH_VERSION,
+        dispatchId: token(input.dispatchId, "dispatchId"),
+        runId: token(input.runId, "runId"),
+        nodeId: token(input.nodeId, "nodeId"),
+        state: input.state,
+        attempt: attempts(input.attempt),
+        generation: nonNegative(input.generation, "generation"),
+        at: nonNegative(input.at, "at"),
+        scheduleToken: token(input.scheduleToken, "scheduleToken"),
+        idempotencyKey: token(input.idempotencyKey, "idempotencyKey"),
+        ...(input.code === undefined ? {} : { code: token(input.code, "code") }),
+    });
+}
+/** Stable key for one logical node attempt. Duplicate delivery uses the same boundary number. */
+export function deriveRunIdempotencyKey(planDigest, runId, nodeId, logicalAttemptBoundary) {
+    const plan = digest(planDigest, "planDigest");
+    const run = token(runId, "runId");
+    const node = token(nodeId, "nodeId");
+    const attempt = attempts(logicalAttemptBoundary);
+    return sha256HexOf(`${plan}\u0000${run}\u0000${node}\u0000${attempt}`);
+}
+/** Create a parsed dispatch identity before handing it to any adapter. */
+export function createRunDispatch(input) {
+    return parseRunDispatch({ version: RUN_DISPATCH_VERSION, ...input });
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/orchestration/dispatch.js.map

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

package/dist/orchestration/durable-jobs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Adapter from the dependency-free jobs lease contract to run-node dispatch.
+ *
+ * The supplied JobStore should be dedicated to this adapter (JobStore has no claim-by-name
+ * operation). Its persisted payload is the parsed, content-free RunDispatch identity. The adapter
+ * adds lease generations and rejects stale completions in-process; a durable operated implementation
+ * must enforce the same compare-and-commit rule in its data layer.
+ */
+import type { JobStore } from "@nifrajs/jobs";
+import { type RunDispatchEvidence, type RunDispatchStore } from "./dispatch.js";
+export interface DurableJobsStoreOptions {
+    /** A dedicated at-least-once JobStore. Defaults to disposable in-memory storage. */
+    readonly store?: JobStore;
+    /** Injected time source used for lease and cancellation decisions. */
+    readonly now?: () => number;
+}
+/**
+ * Create an at-least-once run dispatch store over an existing JobStore.
+ *
+ * JobStore's `attempt` increments only when a caller explicitly retries; an expired lease is
+ * redelivered at the same logical attempt, which is what makes the idempotency key stable across a
+ * duplicate delivery. A retry intentionally advances the logical attempt and gets a new key.
+ */
+export declare function createDurableJobsStore(options?: DurableJobsStoreOptions): RunDispatchStore & {
+    readonly jobs: JobStore;
+    deadLetters(): readonly RunDispatchEvidence[];
+};
+/** Disposable local reference adapter; it makes no durability or exactly-once guarantee. */
+export declare function createMemoryRunDispatchStore(options?: {
+    readonly now?: () => number;
+}): RunDispatchStore & {
+    readonly jobs: JobStore;
+    deadLetters(): readonly RunDispatchEvidence[];
+};
+//# sourceMappingURL=durable-jobs.d.ts.map

package/dist/orchestration/durable-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-jobs.d.ts","sourceRoot":"","sources":["../../src/orchestration/durable-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAa,MAAM,eAAe,CAAA;AAExD,OAAO,EAcL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAEtB,MAAM,eAAe,CAAA;AAEtB,MAAM,WAAW,uBAAuB;IACtC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AA+ED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,GAAG;IAChG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,WAAW,IAAI,SAAS,mBAAmB,EAAE,CAAA;CAC9C,CA+OA;AAED,4FAA4F;AAC5F,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAC5C,gBAAgB,GAAG;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,WAAW,IAAI,SAAS,mBAAmB,EAAE,CAAA;CAC9C,CAEA"}

package/dist/orchestration/durable-jobs.js

@@ -0,0 +1,273 @@
+/**
+ * Adapter from the dependency-free jobs lease contract to run-node dispatch.
+ *
+ * The supplied JobStore should be dedicated to this adapter (JobStore has no claim-by-name
+ * operation). Its persisted payload is the parsed, content-free RunDispatch identity. The adapter
+ * adds lease generations and rejects stale completions in-process; a durable operated implementation
+ * must enforce the same compare-and-commit rule in its data layer.
+ */
+import { MemoryJobStore } from "@nifrajs/jobs";
+import { DISPATCH_JOB_NAME, deriveRunIdempotencyKey, parseRunCheckpoint, parseRunDispatch, parseRunDispatchEvidence, parseRunLease, RUN_DISPATCH_VERSION, } from "./dispatch.js";
+function code(value) {
+    if (!/^[A-Za-z0-9_.:-]{1,256}$/.test(value))
+        throw new TypeError("dispatch code must be a stable token");
+    return value;
+}
+function result(codeValue) {
+    return { ok: codeValue === "accepted", code: codeValue };
+}
+function leaseMatches(entry, lease) {
+    return (entry !== undefined &&
+        entry.leaseId === lease.leaseId &&
+        entry.generation === lease.generation &&
+        entry.attempt === lease.attempt &&
+        entry.dispatch.dispatchId === lease.dispatch.dispatchId &&
+        entry.dispatch.planDigest === lease.dispatch.planDigest &&
+        entry.dispatch.nodeId === lease.dispatch.nodeId &&
+        entry.lease?.idempotencyKey === lease.idempotencyKey);
+}
+function isTerminal(state) {
+    return (state === "succeeded" ||
+        state === "failed" ||
+        state === "cancelled" ||
+        state === "dead-lettered");
+}
+function evidenceFor(entry, state, at, scheduleToken, idempotencyKey, codeValue) {
+    return parseRunDispatchEvidence({
+        version: RUN_DISPATCH_VERSION,
+        dispatchId: entry.dispatch.dispatchId,
+        runId: entry.dispatch.runId,
+        nodeId: entry.dispatch.nodeId,
+        state,
+        attempt: entry.attempt,
+        generation: entry.generation,
+        at,
+        scheduleToken,
+        idempotencyKey,
+        ...(codeValue === undefined ? {} : { code: code(codeValue) }),
+    });
+}
+function appendEvidence(entry, item) {
+    entry.evidence.push(parseRunDispatchEvidence(item));
+}
+function dispatchFromJob(job) {
+    if (job.name !== DISPATCH_JOB_NAME)
+        throw new TypeError("jobs adapter received an unrelated job");
+    return parseRunDispatch(job.payload);
+}
+/**
+ * Create an at-least-once run dispatch store over an existing JobStore.
+ *
+ * JobStore's `attempt` increments only when a caller explicitly retries; an expired lease is
+ * redelivered at the same logical attempt, which is what makes the idempotency key stable across a
+ * duplicate delivery. A retry intentionally advances the logical attempt and gets a new key.
+ */
+export function createDurableJobsStore(options = {}) {
+    const jobs = options.store ?? new MemoryJobStore();
+    const now = options.now ?? (() => Date.now());
+    const byJobId = new Map();
+    const byDispatchId = new Map();
+    let generation = 0;
+    const dead = [];
+    async function enqueue(source) {
+        const dispatch = parseRunDispatch(source);
+        if (byDispatchId.has(dispatch.dispatchId))
+            throw new Error("duplicate dispatch id");
+        const jobId = await jobs.enqueue({
+            name: DISPATCH_JOB_NAME,
+            payload: dispatch,
+            runAt: dispatch.notBefore,
+            maxAttempts: dispatch.maxAttempts,
+        });
+        const entry = {
+            dispatch,
+            jobId,
+            state: "queued",
+            attempt: 1,
+            generation: 0,
+            leaseId: undefined,
+            leaseUntil: 0,
+            lease: undefined,
+            checkpoint: undefined,
+            evidence: [],
+        };
+        byJobId.set(jobId, entry);
+        byDispatchId.set(dispatch.dispatchId, entry);
+    }
+    async function lease(at, limit, leaseMs) {
+        if (!Number.isSafeInteger(at) || at < 0)
+            throw new RangeError("dispatch lease time is invalid");
+        if (!Number.isSafeInteger(limit) || limit < 1)
+            throw new RangeError("dispatch lease limit is invalid");
+        if (!Number.isFinite(leaseMs) || leaseMs <= 0)
+            throw new RangeError("dispatch lease duration is invalid");
+        const jobsLeased = await jobs.lease(at, limit, leaseMs);
+        const resultLeases = [];
+        for (const job of jobsLeased) {
+            const dispatch = dispatchFromJob(job);
+            const entry = byJobId.get(job.id) ?? byDispatchId.get(dispatch.dispatchId);
+            if (entry === undefined)
+                throw new Error("jobs adapter lost dispatch identity");
+            if (isTerminal(entry.state))
+                continue;
+            entry.state = "leased";
+            entry.attempt = job.attempt + 1;
+            entry.generation = ++generation;
+            entry.leaseUntil = at + leaseMs;
+            entry.leaseId = `${job.id}:${entry.generation}`;
+            const idempotencyKey = await deriveRunIdempotencyKey(dispatch.planDigest, dispatch.runId, dispatch.nodeId, entry.attempt);
+            const value = parseRunLease({
+                version: RUN_DISPATCH_VERSION,
+                leaseId: entry.leaseId,
+                dispatch,
+                attempt: entry.attempt,
+                generation: entry.generation,
+                leasedAt: at,
+                leaseUntil: entry.leaseUntil,
+                scheduleToken: `${job.id}:${entry.generation}`,
+                idempotencyKey,
+            });
+            entry.lease = value;
+            appendEvidence(entry, evidenceFor(entry, "leased", at, value.scheduleToken, value.idempotencyKey));
+            resultLeases.push(value);
+        }
+        return resultLeases;
+    }
+    function current(lease) {
+        return byDispatchId.get(lease.dispatch.dispatchId);
+    }
+    async function checkpoint(lease, source) {
+        const value = parseRunCheckpoint(source);
+        const entry = current(lease);
+        if (!leaseMatches(entry, lease))
+            return result("stale_lease");
+        if (entry.state === "cancelled")
+            return result("cancelled");
+        if (isTerminal(entry.state))
+            return result("terminal");
+        if (now() >= entry.leaseUntil)
+            return result("stale_lease");
+        if (value.dispatchId !== lease.dispatch.dispatchId ||
+            value.runId !== lease.dispatch.runId ||
+            value.nodeId !== lease.dispatch.nodeId ||
+            value.attempt !== lease.attempt ||
+            value.generation !== lease.generation ||
+            value.idempotencyKey !== lease.idempotencyKey)
+            return result("invalid_checkpoint");
+        entry.checkpoint = value;
+        entry.state = "checkpointed";
+        appendEvidence(entry, evidenceFor(entry, "checkpointed", value.at, value.scheduleToken, value.idempotencyKey));
+        return result("accepted");
+    }
+    async function complete(lease, source) {
+        const entry = current(lease);
+        if (!leaseMatches(entry, lease))
+            return result("stale_lease");
+        if (entry.state === "cancelled")
+            return result("cancelled");
+        if (isTerminal(entry.state))
+            return result("terminal");
+        if (now() >= entry.leaseUntil)
+            return result("stale_lease");
+        if (source !== undefined) {
+            const evidence = parseRunDispatchEvidence(source);
+            if (evidence.dispatchId !== lease.dispatch.dispatchId ||
+                evidence.attempt !== lease.attempt ||
+                evidence.generation !== lease.generation ||
+                evidence.idempotencyKey !== lease.idempotencyKey)
+                return result("invalid_checkpoint");
+        }
+        await jobs.complete(entry.jobId);
+        entry.state = "succeeded";
+        appendEvidence(entry, source ?? evidenceFor(entry, "succeeded", now(), lease.scheduleToken, lease.idempotencyKey));
+        entry.lease = undefined;
+        return result("accepted");
+    }
+    async function retry(lease, runAt, failureCode) {
+        const entry = current(lease);
+        if (!leaseMatches(entry, lease))
+            return result("stale_lease");
+        if (entry.state === "cancelled")
+            return result("cancelled");
+        if (isTerminal(entry.state))
+            return result("terminal");
+        if (now() >= entry.leaseUntil)
+            return result("stale_lease");
+        if (!Number.isSafeInteger(runAt) || runAt < 0)
+            throw new RangeError("dispatch retry time is invalid");
+        await jobs.retry(entry.jobId, runAt);
+        entry.state = "retrying";
+        entry.checkpoint = undefined;
+        appendEvidence(entry, evidenceFor(entry, "retrying", now(), lease.scheduleToken, lease.idempotencyKey, failureCode));
+        entry.lease = undefined;
+        return result("accepted");
+    }
+    async function deadLetter(lease, failureCode) {
+        const entry = current(lease);
+        if (!leaseMatches(entry, lease))
+            return result("stale_lease");
+        if (entry.state === "cancelled")
+            return result("cancelled");
+        if (isTerminal(entry.state))
+            return result("terminal");
+        if (now() >= entry.leaseUntil)
+            return result("stale_lease");
+        const stableCode = code(failureCode);
+        await jobs.deadLetter(entry.jobId, stableCode);
+        entry.state = "dead-lettered";
+        const evidence = evidenceFor(entry, "dead-lettered", now(), lease.scheduleToken, lease.idempotencyKey, stableCode);
+        appendEvidence(entry, evidence);
+        dead.push(evidence);
+        entry.lease = undefined;
+        return result("accepted");
+    }
+    async function cancel(runId, cancellationCode = "cancelled") {
+        const stableCode = code(cancellationCode);
+        let changed = 0;
+        for (const entry of byDispatchId.values()) {
+            if (entry.dispatch.runId !== runId || isTerminal(entry.state))
+                continue;
+            entry.state = "cancelled";
+            changed++;
+            const lease = entry.lease;
+            appendEvidence(entry, evidenceFor(entry, "cancelled", now(), lease?.scheduleToken ?? `${entry.jobId}:cancel`, lease?.idempotencyKey ??
+                (await deriveRunIdempotencyKey(entry.dispatch.planDigest, entry.dispatch.runId, entry.dispatch.nodeId, entry.attempt)), stableCode));
+            if (lease !== undefined)
+                await jobs.deadLetter(entry.jobId, stableCode);
+            else
+                await jobs.deadLetter(entry.jobId, stableCode);
+            entry.lease = undefined;
+        }
+        return changed;
+    }
+    function inspect(dispatchId) {
+        const entry = byDispatchId.get(dispatchId);
+        if (entry === undefined)
+            return undefined;
+        return Object.freeze({
+            dispatch: entry.dispatch,
+            state: entry.state,
+            attempt: entry.attempt,
+            generation: entry.generation,
+            ...(entry.checkpoint === undefined ? {} : { checkpoint: entry.checkpoint }),
+            evidence: Object.freeze([...entry.evidence]),
+        });
+    }
+    return {
+        jobs,
+        enqueue,
+        lease,
+        checkpoint,
+        complete,
+        retry,
+        deadLetter,
+        cancel,
+        inspect,
+        deadLetters: () => Object.freeze([...dead]),
+    };
+}
+/** Disposable local reference adapter; it makes no durability or exactly-once guarantee. */
+export function createMemoryRunDispatchStore(options = {}) {
+    return createDurableJobsStore({ store: new MemoryJobStore(), ...options });
+}
+//# sourceMappingURL=durable-jobs.js.map

package/dist/orchestration/durable-jobs.js.map

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

package/dist/orchestration/effect-key.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Content-free idempotency identity for one side-effecting node attempt-boundary.
+ *
+ * The step author projects only the identity-bearing subset of its input into a byte `selector`
+ * (via `CatalogStep.selectEffect`). {@link deriveNodeEffectKey} frames that selector with the
+ * non-secret plan/node coordinates and hashes the whole to a digest. The digest is what crosses a
+ * boundary or lands in evidence; the selector bytes never leave this function. This mirrors
+ * `@nifrajs/core`'s `computeIdempotencyFingerprint`: the hash is the key, the material is consumed.
+ */
+import type { NodeEffectKey } from "@nifrajs/agent-protocol";
+/** Inputs to the effect-key derivation. `selector` is the step's content-free identity projection. */
+export interface EffectKeyMaterial {
+    readonly planDigest: string;
+    readonly nodeId: string;
+    /** Identity-bearing bytes chosen by the step. Consumed into the hash, never retained. */
+    readonly selector: Uint8Array;
+}
+/**
+ * Derive the stable, content-free key for a node attempt. The returned digest is safe to log and to
+ * cross a boundary; two attempts with the same identity converge, distinct identities diverge.
+ */
+export declare function deriveNodeEffectKey(material: EffectKeyMaterial): Promise<NodeEffectKey>;
+//# sourceMappingURL=effect-key.d.ts.map

package/dist/orchestration/effect-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-key.d.ts","sourceRoot":"","sources":["../../src/orchestration/effect-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAK5D,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAA;CAC9B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAO7F"}

package/dist/orchestration/effect-key.js

@@ -0,0 +1,24 @@
+/**
+ * Content-free idempotency identity for one side-effecting node attempt-boundary.
+ *
+ * The step author projects only the identity-bearing subset of its input into a byte `selector`
+ * (via `CatalogStep.selectEffect`). {@link deriveNodeEffectKey} frames that selector with the
+ * non-secret plan/node coordinates and hashes the whole to a digest. The digest is what crosses a
+ * boundary or lands in evidence; the selector bytes never leave this function. This mirrors
+ * `@nifrajs/core`'s `computeIdempotencyFingerprint`: the hash is the key, the material is consumed.
+ */
+import { sha256Hex } from "./hash.js";
+const encoder = new TextEncoder();
+/**
+ * Derive the stable, content-free key for a node attempt. The returned digest is safe to log and to
+ * cross a boundary; two attempts with the same identity converge, distinct identities diverge.
+ */
+export async function deriveNodeEffectKey(material) {
+    const header = encoder.encode(`${material.planDigest}\n${material.nodeId}\n`);
+    const framed = new Uint8Array(header.length + material.selector.length);
+    framed.set(header, 0);
+    framed.set(material.selector, header.length);
+    const digest = await sha256Hex(framed);
+    return { digest, planDigest: material.planDigest, nodeId: material.nodeId };
+}
+//# sourceMappingURL=effect-key.js.map

package/dist/orchestration/effect-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-key.js","sourceRoot":"","sources":["../../src/orchestration/effect-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;AAUjC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAA2B;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,KAAK,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAA;IAC7E,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACvE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACrB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAA;IACtC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAA;AAC7E,CAAC"}