@elysra/tungsten-runtime 0.0.0-stage → 0.1.1

package/dist/confirm.d.ts

@@ -0,0 +1,7 @@
+/** Lifetime of a confirmation token. */
+export declare const CONFIRMATION_TTL_MS: number;
+/** SHA-256 of the canonical JSON of the arguments. */
+export declare function argsDigest(args: unknown): Promise<string>;
+export declare function issueToken(key: Uint8Array, operation: string, args: unknown, now: number): Promise<string>;
+export type TokenCheck = "valid" | "expired" | "mismatch" | "malformed";
+export declare function checkToken(key: Uint8Array, token: string, operation: string, args: unknown, now: number): Promise<TokenCheck>;

package/dist/confirm.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Confirmation tokens (planning/06 "Preview and confirmation"):
+ * `tgc1.<expiry ms>.<base64url(HMAC-SHA-256(key, op id, args digest, expiry))>`.
+ * A token is valid only for the operation and the exact arguments it was
+ * issued for, until its expiry.
+ */
+import { base64url, canonicalJson, hmacSha256, sha256Hex, timingSafeEqual } from "./util.js";
+/** Lifetime of a confirmation token. */
+export const CONFIRMATION_TTL_MS = 5 * 60 * 1000;
+const PREFIX = "tgc1";
+/** SHA-256 of the canonical JSON of the arguments. */
+export async function argsDigest(args) {
+    return sha256Hex(canonicalJson(args));
+}
+async function signature(key, operation, digest, expiry) {
+    return base64url(await hmacSha256(key, `${operation}\n${digest}\n${expiry}`));
+}
+export async function issueToken(key, operation, args, now) {
+    const expiry = Math.floor(now) + CONFIRMATION_TTL_MS;
+    return `${PREFIX}.${expiry}.${await signature(key, operation, await argsDigest(args), expiry)}`;
+}
+export async function checkToken(key, token, operation, args, now) {
+    const match = /^tgc1\.(\d{1,16})\.([A-Za-z0-9_-]{43})$/.exec(token);
+    if (!match)
+        return "malformed";
+    const expiry = Number(match[1]);
+    const expected = await signature(key, operation, await argsDigest(args), expiry);
+    if (!timingSafeEqual(expected, match[2]))
+        return "mismatch";
+    return expiry > now ? "valid" : "expired";
+}

package/dist/define.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Identity helpers for generated code: they return their argument
+ * unchanged and exist so descriptor literals are checked against the
+ * contract types while keeping their literal types (`satisfies` without
+ * widening).
+ */
+import type { ApiDescriptor, MacroDescriptor, OperationDescriptor } from "./types.js";
+/** Declare one operation descriptor. */
+export declare function defineOperation<const T extends OperationDescriptor>(op: T): T;
+/** Declare the API descriptor of a client. */
+export declare function defineApi<const T extends ApiDescriptor>(api: T): T;
+/** Declare a compiled macro. */
+export declare function defineMacro<const T extends MacroDescriptor>(macro: T): T;

package/dist/define.js

@@ -0,0 +1,12 @@
+/** Declare one operation descriptor. */
+export function defineOperation(op) {
+    return op;
+}
+/** Declare the API descriptor of a client. */
+export function defineApi(api) {
+    return api;
+}
+/** Declare a compiled macro. */
+export function defineMacro(macro) {
+    return macro;
+}

package/dist/envelope.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The diagnostic error envelope (planning/06): construction with stable
+ * field order, default `retryable` per category, status → category
+ * mapping and the generic remediation texts used when neither the
+ * operation nor the API has a specific entry.
+ */
+import type { Category, Diagnostic, Retryable } from "./types.js";
+/** Default `retryable` per category (planning/06 table). */
+export declare const DEFAULT_RETRYABLE: Readonly<Record<Category, Retryable>>;
+/** Remediation used when no manifest entry applies. */
+export declare const GENERIC_REMEDIATION: Readonly<Record<Category, string>>;
+export declare function isCategory(value: unknown): value is Category;
+export declare function isRetryable(value: unknown): value is Retryable;
+export type DiagnosticFields = Partial<Omit<Diagnostic, "status" | "category" | "operation">>;
+/** Build an envelope with every field present, in the documented order. */
+export declare function diagnostic(operation: string, category: Category, fields?: DiagnosticFields): Diagnostic;
+/** Category of an HTTP error status when no manifest entry says otherwise. */
+export declare function categoryForStatus(status: number, jsonBody: boolean): Category;
+/** Replace every occurrence of the given secrets (four characters or
+ * more) in a text. */
+export declare function scrubText(text: string, secrets: ReadonlySet<string>): string;
+/** Replace every occurrence of the given secrets in the envelope's string
+ * fields. A last line of defence: no field is built from a secret. */
+export declare function scrubDiagnostic(d: Diagnostic, secrets: ReadonlySet<string>): Diagnostic;

package/dist/envelope.js

@@ -0,0 +1,152 @@
+import { REDACTED } from "./util.js";
+const CATEGORIES = [
+    "VALIDATION_FAILED",
+    "MALFORMED_REQUEST",
+    "REQUEST_TOO_LARGE",
+    "AUTH_FAILED",
+    "NOT_FOUND",
+    "CONFLICT",
+    "PRECONDITION_FAILED",
+    "RATE_LIMITED",
+    "UPSTREAM_UNAVAILABLE",
+    "OUTCOME_UNKNOWN",
+    "TRANSPORT_FAILED",
+    "CONFIRMATION_REQUIRED",
+    "GATE_DISABLED",
+    "UNEXPECTED_RESPONSE",
+];
+const RETRYABLE_VALUES = ["never", "after_delay", "same_key_only", "after_remediation"];
+/** Default `retryable` per category (planning/06 table). */
+export const DEFAULT_RETRYABLE = {
+    VALIDATION_FAILED: "never",
+    MALFORMED_REQUEST: "never",
+    REQUEST_TOO_LARGE: "never",
+    AUTH_FAILED: "never",
+    NOT_FOUND: "never",
+    CONFLICT: "never",
+    PRECONDITION_FAILED: "never",
+    RATE_LIMITED: "after_delay",
+    UPSTREAM_UNAVAILABLE: "after_delay",
+    OUTCOME_UNKNOWN: "same_key_only",
+    TRANSPORT_FAILED: "after_delay",
+    CONFIRMATION_REQUIRED: "never",
+    GATE_DISABLED: "never",
+    UNEXPECTED_RESPONSE: "never",
+};
+/** Remediation used when no manifest entry applies. */
+export const GENERIC_REMEDIATION = {
+    VALIDATION_FAILED: "The server rejected the arguments. Fix the parameter the API error names and call again; the same request fails the same way.",
+    MALFORMED_REQUEST: "The server could not parse the request. Check the format of path and query parameters (for example canonical UUIDs); do not retry unchanged.",
+    REQUEST_TOO_LARGE: "The request body is larger than the server accepts. Send a smaller body; do not retry unchanged.",
+    AUTH_FAILED: "The credential is missing, expired, revoked or lacks permission. Do not retry; fix the credential configured in ClientOptions.auth.",
+    NOT_FOUND: "The resource does not exist or is not visible to this credential. Check the identifiers; do not retry unchanged.",
+    CONFLICT: "The request conflicts with the resource's current state. Read the current state before deciding what to do; do not retry unchanged.",
+    PRECONDITION_FAILED: "A precondition of this operation is not met (account, billing or resource state). Resolve it first; do not retry unchanged.",
+    RATE_LIMITED: "Rate limited. Wait retry_after_ms (or a few seconds when it is null) before calling again.",
+    UPSTREAM_UNAVAILABLE: "The service is temporarily unavailable. Wait, then call again.",
+    OUTCOME_UNKNOWN: "The server may or may not have applied this call; do not retry it blindly. Check whether it took effect before doing anything else.",
+    TRANSPORT_FAILED: "The request could not be delivered (DNS, TLS or connection failure), so the server did not receive it. Check baseUrl and network access, then call again.",
+    CONFIRMATION_REQUIRED: "This operation needs confirmation: call preview(...) and pass its confirmation_token.",
+    GATE_DISABLED: "This operation is disabled on this deployment. It is a deployment setting; do not retry.",
+    UNEXPECTED_RESPONSE: "The server's response did not match the API description. Do not retry blindly; report it.",
+};
+export function isCategory(value) {
+    return typeof value === "string" && CATEGORIES.includes(value);
+}
+export function isRetryable(value) {
+    return typeof value === "string" && RETRYABLE_VALUES.includes(value);
+}
+/** Build an envelope with every field present, in the documented order. */
+export function diagnostic(operation, category, fields = {}) {
+    return {
+        status: "error",
+        category,
+        operation,
+        http_status: fields.http_status ?? null,
+        code: fields.code ?? null,
+        failed_parameter: fields.failed_parameter ?? null,
+        received_value: fields.received_value === undefined ? null : fields.received_value,
+        expected: fields.expected ?? null,
+        remediation: fields.remediation ?? GENERIC_REMEDIATION[category],
+        retryable: fields.retryable ?? DEFAULT_RETRYABLE[category],
+        retry_after_ms: fields.retry_after_ms ?? null,
+        next_action: fields.next_action ?? null,
+        request_id: fields.request_id ?? null,
+        trace: { attempts: fields.trace?.attempts ?? 0 },
+    };
+}
+/** Category of an HTTP error status when no manifest entry says otherwise. */
+export function categoryForStatus(status, jsonBody) {
+    switch (status) {
+        case 400:
+            return jsonBody ? "VALIDATION_FAILED" : "MALFORMED_REQUEST";
+        case 401:
+        case 403:
+        case 407:
+            return "AUTH_FAILED";
+        case 404:
+        case 410:
+            return "NOT_FOUND";
+        case 409:
+            return "CONFLICT";
+        case 402:
+        case 412:
+        case 428:
+            return "PRECONDITION_FAILED";
+        case 413:
+            return "REQUEST_TOO_LARGE";
+        case 422:
+            return "VALIDATION_FAILED";
+        case 429:
+            return "RATE_LIMITED";
+        case 408:
+        case 502:
+        case 503:
+        case 504:
+            return "UPSTREAM_UNAVAILABLE";
+    }
+    if (status >= 500 && status <= 599)
+        return "UPSTREAM_UNAVAILABLE";
+    if (status >= 400 && status <= 499)
+        return jsonBody ? "VALIDATION_FAILED" : "MALFORMED_REQUEST";
+    return "UNEXPECTED_RESPONSE";
+}
+/** Replace every occurrence of the given secrets (four characters or
+ * more) in a text. */
+export function scrubText(text, secrets) {
+    let out = text;
+    for (const secret of secrets) {
+        if (secret.length >= 4 && out.includes(secret))
+            out = out.split(secret).join(REDACTED);
+    }
+    return out;
+}
+/** Replace every occurrence of the given secrets in the envelope's string
+ * fields. A last line of defence: no field is built from a secret. */
+export function scrubDiagnostic(d, secrets) {
+    if (secrets.size === 0)
+        return d;
+    const scrub = (text) => scrubText(text, secrets);
+    const scrubValue = (value) => {
+        if (typeof value === "string")
+            return scrub(value);
+        if (value === null || typeof value !== "object")
+            return value;
+        try {
+            return JSON.parse(scrub(JSON.stringify(value)));
+        }
+        catch {
+            return REDACTED;
+        }
+    };
+    return {
+        ...d,
+        code: d.code === null ? null : scrub(d.code),
+        failed_parameter: d.failed_parameter === null ? null : scrub(d.failed_parameter),
+        received_value: scrubValue(d.received_value),
+        expected: d.expected === null ? null : scrub(d.expected),
+        remediation: scrub(d.remediation),
+        next_action: d.next_action === null ? null : scrub(d.next_action),
+        request_id: d.request_id === null ? null : scrub(d.request_id),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Throwing ergonomics for people (planning/05: "a throwing client variant
+ * is exposed for human ergonomics, implemented in the runtime"). Agents
+ * should keep branching on `Result.ok`.
+ */
+import type { Diagnostic, Result } from "./types.js";
+/** An error carrying the diagnostic envelope of a failed call. */
+export declare class TungstenError extends Error {
+    /** The envelope, exactly as the non-throwing API returns it. */
+    readonly diagnostic: Diagnostic;
+    /** The failed result's `partial`: what the call or macro already
+     * produced (it can hold values the API shows only once). */
+    readonly partial: unknown;
+    constructor(diagnostic: Diagnostic, partial?: unknown);
+    /** Serializes to the envelope, so logging the error logs the envelope
+     * (never `partial`, which can hold secrets). */
+    toJSON(): Diagnostic;
+}
+/** The value of a successful result; throws {@link TungstenError} otherwise. */
+export declare function unwrap<T>(result: Result<T>): T;
+type Unwrapped<R> = [R] extends [Result<infer V>] ? V : R;
+type ThrowingReturn<R> = R extends Promise<infer P> ? Promise<Unwrapped<P>> : R extends AsyncIterable<infer Y> ? AsyncIterable<Unwrapped<Y>> : R;
+type ThrowingCallable<T> = T extends (...args: infer A) => infer R ? (...args: A) => ThrowingReturn<R> : unknown;
+/** `T` with every method returning `Promise<Result<V>>` turned into one
+ * returning `Promise<V>` (throwing {@link TungstenError}), and every
+ * `AsyncIterable<Result<V>>` into `AsyncIterable<V>`, recursively through
+ * nested resources. */
+export type Throwing<T> = T extends object ? ThrowingCallable<T> & {
+    readonly [K in keyof T]: Throwing<T[K]>;
+} : T;
+/**
+ * A view of a generated client (or any object of resources) whose methods
+ * throw {@link TungstenError} instead of returning `{ok: false}`:
+ * `throwing(client).webhooks.list()` resolves to the body.
+ */
+export declare function throwing<T extends object>(target: T): Throwing<T>;
+export {};

package/dist/errors.js

@@ -0,0 +1,75 @@
+import { isRecord } from "./util.js";
+/** An error carrying the diagnostic envelope of a failed call. */
+export class TungstenError extends Error {
+    /** The envelope, exactly as the non-throwing API returns it. */
+    diagnostic;
+    /** The failed result's `partial`: what the call or macro already
+     * produced (it can hold values the API shows only once). */
+    partial;
+    constructor(diagnostic, partial) {
+        super(`${diagnostic.category} (${diagnostic.operation}): ${diagnostic.remediation}`);
+        this.name = "TungstenError";
+        this.diagnostic = diagnostic;
+        this.partial = partial;
+    }
+    /** Serializes to the envelope, so logging the error logs the envelope
+     * (never `partial`, which can hold secrets). */
+    toJSON() {
+        return this.diagnostic;
+    }
+}
+/** The value of a successful result; throws {@link TungstenError} otherwise. */
+export function unwrap(result) {
+    if (result.ok)
+        return result.value;
+    throw new TungstenError(result.error, result.partial);
+}
+function isResult(value) {
+    return isRecord(value) && typeof value.ok === "boolean" && (value.ok ? "value" in value : isRecord(value.error));
+}
+function throwingIterable(iterable) {
+    return {
+        async *[Symbol.asyncIterator]() {
+            for await (const item of iterable)
+                yield isResult(item) ? unwrap(item) : item;
+        },
+    };
+}
+function convert(value) {
+    if (value instanceof Promise)
+        return value.then((resolved) => (isResult(resolved) ? unwrap(resolved) : resolved));
+    if (isRecord(value) && typeof value[Symbol.asyncIterator] === "function") {
+        return throwingIterable(value);
+    }
+    return value;
+}
+/**
+ * A view of a generated client (or any object of resources) whose methods
+ * throw {@link TungstenError} instead of returning `{ok: false}`:
+ * `throwing(client).webhooks.list()` resolves to the body.
+ */
+export function throwing(target) {
+    const proxies = new WeakMap();
+    const originals = new WeakMap();
+    const wrap = (value) => {
+        const cached = proxies.get(value);
+        if (cached)
+            return cached;
+        const proxy = new Proxy(value, {
+            get(obj, prop, receiver) {
+                const inner = Reflect.get(obj, prop, receiver === proxy ? obj : receiver);
+                if (typeof inner === "function" && prop === "constructor")
+                    return inner;
+                return (typeof inner === "object" && inner !== null) || typeof inner === "function" ? wrap(inner) : inner;
+            },
+            apply(fn, thisArg, args) {
+                const self = typeof thisArg === "object" && thisArg !== null ? (originals.get(thisArg) ?? thisArg) : thisArg;
+                return convert(Reflect.apply(fn, self, args));
+            },
+        });
+        proxies.set(value, proxy);
+        originals.set(proxy, value);
+        return proxy;
+    };
+    return wrap(target);
+}

package/dist/expr.d.ts

@@ -0,0 +1,24 @@
+/** True when every entry of `predicate` holds on `value`. Malformed
+ * predicates never hold. */
+export declare function evaluatePredicate(predicate: unknown, value: unknown): boolean;
+/** Bindings an expression can reference, by name without `$`. */
+export type Scope = Readonly<Record<string, unknown>>;
+/** Resolve one `$name.path` reference; `undefined` when the name is unbound. */
+export declare function resolveRef(ref: string, scope: Scope): unknown;
+/** Evaluate an expression against `scope`. Unknown references are
+ * `undefined` (dropped from objects); malformed `expr` strings are `null`. */
+export declare function evaluateExpr(expr: unknown, scope: Scope, depth?: number): unknown;
+/** A JSON literal, also accepting single-quoted strings (`'a'`). */
+/** The placeholder a dry evaluation shows for a result not produced yet. */
+export declare function placeholder(name: string, path: string): string;
+/** The placeholders in `value`, at any depth, in order of appearance. */
+export declare function placeholdersIn(value: unknown, out?: string[], depth?: number): string[];
+/** Whether `value` is a placeholder, or holds one at any depth. */
+export declare function containsPlaceholder(value: unknown): boolean;
+/** {@link evaluateExpr} for a dry run: references to the `pending` names
+ * (results of steps that have not run) become placeholders. */
+export declare function evaluateDry(expr: unknown, scope: Scope, pending: ReadonlySet<string>, depth?: number): unknown;
+/** A predicate in words, for remediation and preview text:
+ * `state in ["delivered", "failed"]`, `endpoints contains {...}`, `a = 1`,
+ * joined with "and"; "" for an empty predicate. */
+export declare function describePredicate(predicate: unknown): string;

package/dist/expr.js

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Predicates (verify `expect`/`terminal`, poll `until`) and the reference
+ * expressions used by verification argument mappings and macros.
+ *
+ * Predicate: field path → `{in: [...]}` | `{equals: x}` | `{contains: {...}}`;
+ * any other value is compared for equality. Every entry must hold.
+ *
+ * Expression: JSON in which a string starting with `$` is a reference
+ * resolved against a scope (`$input.a.b`, `$<name>.a`, `$response.x`,
+ * `$args.y`), an object `{expr: "<ref> in [..]" | "<ref> == x" | "<ref> != x"}`
+ * evaluates to a boolean, and anything else is a literal.
+ *
+ * A dry evaluation (macro previews) knows the input but not the results of
+ * the steps before: a reference to such a result evaluates to a placeholder
+ * string, `<from step NAME: path>` (`<from step NAME>` for the whole
+ * result), and so does an `expr` over one.
+ */
+import { containsSubset, deepEqual, getPath, hasOwn, isRecord, splitPath } from "./util.js";
+/** True when every entry of `predicate` holds on `value`. Malformed
+ * predicates never hold. */
+export function evaluatePredicate(predicate, value) {
+    if (predicate === null || predicate === undefined)
+        return true;
+    if (!isRecord(predicate))
+        return false;
+    return Object.keys(predicate).every((path) => holds(predicate[path], getPath(value, path)));
+}
+function holds(test, actual) {
+    if (isRecord(test)) {
+        const keys = Object.keys(test);
+        if (keys.length === 1 && keys[0] === "in") {
+            return Array.isArray(test.in) && test.in.some((candidate) => deepEqual(candidate, actual));
+        }
+        if (keys.length === 1 && keys[0] === "equals")
+            return deepEqual(test.equals, actual);
+        if (keys.length === 1 && keys[0] === "contains") {
+            const pattern = test.contains;
+            if (typeof pattern === "string") {
+                return (typeof actual === "string" && actual.includes(pattern)) || (Array.isArray(actual) && actual.includes(pattern));
+            }
+            if (Array.isArray(actual) && !Array.isArray(pattern))
+                return actual.some((item) => containsSubset(item, pattern));
+            return containsSubset(actual, pattern);
+        }
+    }
+    return deepEqual(test, actual);
+}
+/** Resolve one `$name.path` reference; `undefined` when the name is unbound. */
+export function resolveRef(ref, scope) {
+    const segments = splitPath(ref.slice(1));
+    const [name, ...rest] = segments;
+    if (name === undefined || !hasOwn(scope, name))
+        return undefined;
+    return getPath(scope[name], rest);
+}
+/** Evaluate an expression against `scope`. Unknown references are
+ * `undefined` (dropped from objects); malformed `expr` strings are `null`. */
+export function evaluateExpr(expr, scope, depth = 0) {
+    if (depth > 64)
+        return null;
+    if (typeof expr === "string")
+        return expr.startsWith("$") ? resolveRef(expr, scope) : expr;
+    if (Array.isArray(expr))
+        return expr.map((item) => evaluateExpr(item, scope, depth + 1));
+    if (isRecord(expr)) {
+        const keys = Object.keys(expr);
+        if (keys.length === 1 && keys[0] === "expr" && typeof expr.expr === "string")
+            return evaluateBoolean(expr.expr, scope);
+        const out = {};
+        for (const key of keys) {
+            const value = evaluateExpr(expr[key], scope, depth + 1);
+            if (value !== undefined)
+                out[key] = value;
+        }
+        return out;
+    }
+    return expr;
+}
+/** A JSON literal, also accepting single-quoted strings (`'a'`). */
+/** The placeholder a dry evaluation shows for a result not produced yet. */
+export function placeholder(name, path) {
+    return path === "" ? `<from step ${name}>` : `<from step ${name}: ${path}>`;
+}
+const PLACEHOLDER = /^<from step [^<>]+>$/;
+/** The placeholders in `value`, at any depth, in order of appearance. */
+export function placeholdersIn(value, out = [], depth = 0) {
+    if (depth > 64)
+        return out;
+    if (typeof value === "string" && PLACEHOLDER.test(value))
+        out.push(value);
+    else if (Array.isArray(value))
+        for (const item of value)
+            placeholdersIn(item, out, depth + 1);
+    else if (isRecord(value))
+        for (const item of Object.values(value))
+            placeholdersIn(item, out, depth + 1);
+    return out;
+}
+/** Whether `value` is a placeholder, or holds one at any depth. */
+export function containsPlaceholder(value) {
+    return placeholdersIn(value).length > 0;
+}
+/** The pending binding a `$name.path` reference names, with the path as
+ * written after the name; null when the name is not pending. */
+function pendingRef(ref, pending) {
+    const name = splitPath(ref.slice(1))[0];
+    if (name === undefined || !pending.has(name) || !ref.startsWith(`$${name}`))
+        return null;
+    return { name, path: ref.slice(name.length + 1).replace(/^\./, "") };
+}
+/** {@link evaluateExpr} for a dry run: references to the `pending` names
+ * (results of steps that have not run) become placeholders. */
+export function evaluateDry(expr, scope, pending, depth = 0) {
+    if (depth > 64)
+        return null;
+    if (typeof expr === "string") {
+        if (!expr.startsWith("$"))
+            return expr;
+        const ref = pendingRef(expr, pending);
+        return ref ? placeholder(ref.name, ref.path) : resolveRef(expr, scope);
+    }
+    if (Array.isArray(expr))
+        return expr.map((item) => evaluateDry(item, scope, pending, depth + 1));
+    if (isRecord(expr)) {
+        const keys = Object.keys(expr);
+        if (keys.length === 1 && keys[0] === "expr" && typeof expr.expr === "string") {
+            const source = expr.expr.trim();
+            const ref = pendingRef(/^\$[^\s=!]+/.exec(source)?.[0] ?? "", pending);
+            return ref ? placeholder(ref.name, source.slice(ref.name.length + 1).replace(/^\./, "")) : evaluateBoolean(source, scope);
+        }
+        const out = {};
+        for (const key of keys) {
+            const value = evaluateDry(expr[key], scope, pending, depth + 1);
+            if (value !== undefined)
+                out[key] = value;
+        }
+        return out;
+    }
+    return expr;
+}
+/** A predicate in words, for remediation and preview text:
+ * `state in ["delivered", "failed"]`, `endpoints contains {...}`, `a = 1`,
+ * joined with "and"; "" for an empty predicate. */
+export function describePredicate(predicate) {
+    if (!isRecord(predicate))
+        return "";
+    const json = (value) => {
+        try {
+            return JSON.stringify(value) ?? String(value);
+        }
+        catch {
+            return String(value);
+        }
+    };
+    const parts = Object.keys(predicate).map((path) => {
+        const test = predicate[path];
+        if (isRecord(test) && Object.keys(test).length === 1) {
+            if (Array.isArray(test.in))
+                return `${path} in [${test.in.map(json).join(", ")}]`;
+            if ("equals" in test)
+                return `${path} = ${json(test.equals)}`;
+            if ("contains" in test)
+                return `${path} contains ${json(test.contains)}`;
+        }
+        return `${path} = ${json(test)}`;
+    });
+    return parts.join(" and ");
+}
+function parseLiteral(text) {
+    const trimmed = text.trim();
+    try {
+        return { ok: true, value: JSON.parse(trimmed) };
+    }
+    catch {
+        const normalized = trimmed.replace(/'((?:[^'\\]|\\.)*)'/g, (_m, inner) => JSON.stringify(inner.replace(/\\'/g, "'")));
+        try {
+            return { ok: true, value: JSON.parse(normalized) };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+}
+function evaluateBoolean(source, scope) {
+    const match = /^\s*(\$[^\s=!]+)\s+(in|==|!=)\s+([\s\S]+)$/.exec(source);
+    if (!match)
+        return null;
+    const [, ref, op, literalText] = match;
+    const literal = parseLiteral(literalText);
+    if (!literal.ok)
+        return null;
+    const actual = resolveRef(ref, scope);
+    if (op === "in")
+        return Array.isArray(literal.value) ? literal.value.some((v) => deepEqual(v, actual)) : null;
+    const equal = deepEqual(actual === undefined ? null : actual, literal.value);
+    return op === "==" ? equal : !equal;
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Idempotency (planning/04 "Idempotency policies", planning/06
+ * "Idempotency store"): the default in-memory store, key formats and the
+ * header an operation's key travels in.
+ */
+import type { IdempotencyStore, OperationDescriptor } from "./types.js";
+/**
+ * The default {@link IdempotencyStore}: keys live as long as the process.
+ * Use a persistent store (`FileIdempotencyStore` from
+ * `@elysra/tungsten-runtime/node`, or your own) when a key must survive a crash.
+ */
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    #private;
+    get(scope: string, logicalId: string): Promise<string | undefined>;
+    put(scope: string, logicalId: string, key: string): Promise<void>;
+}
+/** Human description of the key format a policy expects. */
+export declare function keyFormatDescription(format: string | null): string;
+/** Checks a caller-owned key against the policy's `format`. Returns the
+ * description of the expected format when the key does not match. */
+export declare function checkKeyFormat(key: string, format: string | null): string | null;
+/** The wire header of the operation's key: the policy's header, else the
+ * parameter with role `idempotency_key`, else `Idempotency-Key`. */
+export declare function keyHeader(op: OperationDescriptor): string;
+/** Whether the operation sends an idempotency key or an identity body, so
+ * resending it cannot apply its effect twice. */
+export declare function hasReplayProtection(op: OperationDescriptor, key: string | null): boolean;

package/dist/idempotency.js

@@ -0,0 +1,56 @@
+/**
+ * The default {@link IdempotencyStore}: keys live as long as the process.
+ * Use a persistent store (`FileIdempotencyStore` from
+ * `@elysra/tungsten-runtime/node`, or your own) when a key must survive a crash.
+ */
+export class MemoryIdempotencyStore {
+    #keys = new Map();
+    async get(scope, logicalId) {
+        return this.#keys.get(`${scope}\u0000${logicalId}`);
+    }
+    async put(scope, logicalId, key) {
+        this.#keys.set(`${scope}\u0000${logicalId}`, key);
+    }
+}
+const UUID_ANY = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function formatKind(format) {
+    const f = (format ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (f === "uuidv4" || f === "uuid4")
+        return "uuid_v4";
+    return f === "uuid" ? "uuid" : "token";
+}
+/** Human description of the key format a policy expects. */
+export function keyFormatDescription(format) {
+    switch (formatKind(format)) {
+        case "uuid_v4":
+            return "UUIDv4 string";
+        case "uuid":
+            return "UUID string";
+        case "token":
+            return "a non-empty printable ASCII string of at most 255 characters";
+    }
+}
+/** Checks a caller-owned key against the policy's `format`. Returns the
+ * description of the expected format when the key does not match. */
+export function checkKeyFormat(key, format) {
+    const kind = formatKind(format);
+    const valid = kind === "uuid_v4" ? UUID_V4.test(key) : kind === "uuid" ? UUID_ANY.test(key) : key.length > 0 && key.length <= 255 && /^[\x21-\x7e]+$/.test(key);
+    return valid ? null : keyFormatDescription(format);
+}
+/** The wire header of the operation's key: the policy's header, else the
+ * parameter with role `idempotency_key`, else `Idempotency-Key`. */
+export function keyHeader(op) {
+    const fromPolicy = op.agent.idempotency.header;
+    if (fromPolicy)
+        return fromPolicy;
+    const param = op.params.find((p) => p.role === "idempotency_key");
+    return param?.wire ?? "Idempotency-Key";
+}
+/** Whether the operation sends an idempotency key or an identity body, so
+ * resending it cannot apply its effect twice. */
+export function hasReplayProtection(op, key) {
+    if (op.agent.idempotency.policy === "content_identity")
+        return true;
+    return key !== null;
+}