@aid-framework/runtime 0.0.0 → 0.1.48

package/dist/pipeline.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A plain-async pipeline engine.
+ *
+ * This is the answer to "the loop". It is a sequential reducer over an immutable
+ * context: each step receives the context and returns the context, optionally
+ * enriched. No graph, no scheduler, no orchestration dependency.
+ *
+ * That is a deliberate ceiling. When branching, retries and human-in-the-loop
+ * interrupts are real requirements an orchestration library is the right tool, but
+ * adopting one before those requirements exist would place an unobservable graph
+ * between the user and their own trace.
+ */
+/** Context key under which {@link Pipeline.run} records the steps that ran, in order. */
+export declare const STEPS_KEY = "steps";
+/** Thrown from a step to end the pipeline successfully and early. */
+export declare class StopPipeline extends Error {
+    readonly reason: string;
+    constructor(reason?: string);
+}
+/**
+ * The value threaded through a pipeline.
+ *
+ * Immutable, so a step cannot mutate what an earlier step observed; it returns a new
+ * context instead. That keeps a failed run's state inspectable and makes replaying a
+ * pipeline reproducible.
+ */
+export declare class PipelineContext {
+    readonly values: Readonly<Record<string, unknown>>;
+    constructor(values?: Readonly<Record<string, unknown>>);
+    get(key: string, fallback?: unknown): unknown;
+    /** A value that must be present, or a {@link PipelineError} naming the key. */
+    require(key: string): unknown;
+    /** A new context with `values` merged over the current members. */
+    withValues(values: Readonly<Record<string, unknown>>): PipelineContext;
+    /** A new context without the named keys. */
+    without(...keys: readonly string[]): PipelineContext;
+}
+/**
+ * What a step may produce: a new context, a record that *becomes* the new context, or
+ * nothing for an empty one.
+ *
+ * A returned record replaces the context rather than merging into it, matching the
+ * reference runtime: a step that wants to preserve earlier values re-spreads them.
+ */
+export type StepResult = PipelineContext | Record<string, unknown> | null | undefined;
+/** A step: a callable from context to a step result. */
+export type Step = (context: PipelineContext) => StepResult | Promise<StepResult>;
+/** The shape of one pipeline entry. */
+export type NamedStep = readonly [name: string, step: Step];
+/** Runs named steps in order, tracing each one. */
+export declare class Pipeline {
+    private readonly _steps;
+    private readonly _tracerName;
+    private readonly _recordSteps;
+    constructor(steps: readonly NamedStep[], options?: {
+        readonly tracerName?: string;
+        readonly recordSteps?: boolean;
+    });
+    get stepNames(): string[];
+    /** Build a pipeline from bare callables, naming each by its function. */
+    static of(...steps: readonly Step[]): Pipeline;
+    /**
+     * A new pipeline with `step` appended. This instance is unchanged.
+     *
+     * Named `add` rather than Python's `then` because a `then` member makes the
+     * object thenable: `await` on a Pipeline would invoke it with `(resolve,
+     * reject)` and construct a nonsense step instead of leaving it alone.
+     */
+    add(name: string, step: Step): Pipeline;
+    /**
+     * Execute every step, stopping early if one throws {@link StopPipeline}.
+     *
+     * A step that throws anything else aborts the run, and the original error's
+     * message is carried into the {@link PipelineError} so the failure names both the
+     * pipeline coordinate and the real cause.
+     */
+    run(initial?: PipelineContext | Record<string, unknown> | null): Promise<PipelineContext>;
+    private finish;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,yFAAyF;AACzF,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC,qEAAqE;AACrE,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,MAAM,SAAK,EAItB;CACF;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEnD,YAAY,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,EAEzD;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAE5C;IAED,+EAA+E;IAC/E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAK5B;IAED,mEAAmE;IACnE,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,eAAe,CAErE;IAED,4CAA4C;IAC5C,OAAO,CAAC,GAAG,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,CAInD;CACF;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAEtF,wDAAwD;AACxD,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAElF,uCAAuC;AACvC,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAyB5D,mDAAmD;AACnD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IAEvC,YACE,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,GAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,EAW/E;IAED,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAED,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,QAAQ,CAE7C;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,QAAQ,CAKtC;IAED;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAqC9F;IAED,OAAO,CAAC,MAAM;CAGf"}

package/dist/pipeline.js

@@ -0,0 +1,159 @@
+/**
+ * A plain-async pipeline engine.
+ *
+ * This is the answer to "the loop". It is a sequential reducer over an immutable
+ * context: each step receives the context and returns the context, optionally
+ * enriched. No graph, no scheduler, no orchestration dependency.
+ *
+ * That is a deliberate ceiling. When branching, retries and human-in-the-loop
+ * interrupts are real requirements an orchestration library is the right tool, but
+ * adopting one before those requirements exist would place an unobservable graph
+ * between the user and their own trace.
+ */
+import { PipelineError } from './errors.js';
+import { repr } from './internal/json.js';
+import { getTracer, recordException } from './tracing.js';
+/** Context key under which {@link Pipeline.run} records the steps that ran, in order. */
+export const STEPS_KEY = 'steps';
+/** Thrown from a step to end the pipeline successfully and early. */
+export class StopPipeline extends Error {
+    reason;
+    constructor(reason = '') {
+        super(reason || 'pipeline stopped');
+        this.name = 'StopPipeline';
+        this.reason = reason;
+    }
+}
+/**
+ * The value threaded through a pipeline.
+ *
+ * Immutable, so a step cannot mutate what an earlier step observed; it returns a new
+ * context instead. That keeps a failed run's state inspectable and makes replaying a
+ * pipeline reproducible.
+ */
+export class PipelineContext {
+    values;
+    constructor(values = {}) {
+        this.values = values;
+    }
+    get(key, fallback) {
+        return Object.hasOwn(this.values, key) ? this.values[key] : fallback;
+    }
+    /** A value that must be present, or a {@link PipelineError} naming the key. */
+    require(key) {
+        if (!Object.hasOwn(this.values, key)) {
+            throw new PipelineError(`pipeline context has no ${repr(key)}`);
+        }
+        return this.values[key];
+    }
+    /** A new context with `values` merged over the current members. */
+    withValues(values) {
+        return new PipelineContext({ ...this.values, ...values });
+    }
+    /** A new context without the named keys. */
+    without(...keys) {
+        const remaining = { ...this.values };
+        for (const key of keys)
+            delete remaining[key];
+        return new PipelineContext(remaining);
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function asContext(value) {
+    if (value instanceof PipelineContext)
+        return value;
+    if (value === null || value === undefined)
+        return new PipelineContext();
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        return new PipelineContext({ ...value });
+    }
+    // `null` cannot reach this line -- it returned above -- so the old `NoneType` arm
+    // was unreachable and the message never named the one case it was written for.
+    // What does reach it is a list, a primitive or a function, and those are what the
+    // message now names.
+    throw new PipelineError(`a pipeline step must return a PipelineContext, a mapping or None, got ${describeValue(value)}`);
+}
+function describeValue(value) {
+    return Array.isArray(value) ? 'list' : typeof value;
+}
+/** Runs named steps in order, tracing each one. */
+export class Pipeline {
+    _steps;
+    _tracerName;
+    _recordSteps;
+    constructor(steps, options = {}) {
+        if (steps.length === 0)
+            throw new PipelineError('a pipeline needs at least one step');
+        const seen = new Set();
+        for (const [name] of steps) {
+            if (seen.has(name))
+                throw new PipelineError(`duplicate step name ${repr(name)}`);
+            seen.add(name);
+        }
+        this._steps = steps;
+        this._tracerName = options.tracerName ?? 'aid_runtime';
+        this._recordSteps = options.recordSteps ?? true;
+    }
+    get stepNames() {
+        return this._steps.map(([name]) => name);
+    }
+    /** Build a pipeline from bare callables, naming each by its function. */
+    static of(...steps) {
+        return new Pipeline(steps.map((step) => [step.name || 'anonymous', step]));
+    }
+    /**
+     * A new pipeline with `step` appended. This instance is unchanged.
+     *
+     * Named `add` rather than Python's `then` because a `then` member makes the
+     * object thenable: `await` on a Pipeline would invoke it with `(resolve,
+     * reject)` and construct a nonsense step instead of leaving it alone.
+     */
+    add(name, step) {
+        return new Pipeline([...this._steps, [name, step]], {
+            tracerName: this._tracerName,
+            recordSteps: this._recordSteps,
+        });
+    }
+    /**
+     * Execute every step, stopping early if one throws {@link StopPipeline}.
+     *
+     * A step that throws anything else aborts the run, and the original error's
+     * message is carried into the {@link PipelineError} so the failure names both the
+     * pipeline coordinate and the real cause.
+     */
+    async run(initial) {
+        let context = asContext(initial);
+        const ran = [];
+        const tracer = getTracer(this._tracerName);
+        for (const [name, step] of this._steps) {
+            const outcome = await tracer.startActiveSpan(`pipeline.${name}`, { attributes: { 'aid.pipeline.step': name } }, async (span) => {
+                try {
+                    return { stopped: false, context: asContext(await step(context)) };
+                }
+                catch (error) {
+                    if (error instanceof StopPipeline) {
+                        if (error.reason.length > 0) {
+                            span.setAttribute('aid.pipeline.stop_reason', error.reason);
+                        }
+                        return { stopped: true };
+                    }
+                    recordException(span, error);
+                    throw new PipelineError(`step ${repr(name)} failed: ${messageOf(error)}`, {
+                        cause: error,
+                    });
+                }
+            });
+            ran.push(name);
+            if (outcome.stopped)
+                return this.finish(context, ran);
+            context = outcome.context;
+        }
+        return this.finish(context, ran);
+    }
+    finish(context, ran) {
+        return this._recordSteps ? context.withValues({ [STEPS_KEY]: [...ran] }) : context;
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

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

package/dist/policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Evaluation of the IR's `PolicyExpr` AST.
+ *
+ * The grammar is the one `packages/ir/src/policy` parses, and the AST is plain JSON
+ * precisely so a target does not need a second parser:
+ *
+ *     expression := or
+ *     or         := and ('or' and)*
+ *     and        := comparison ('and' comparison)*
+ *     comparison := unary (('==' | '!=' | '<' | '<=' | '>' | '>=') unary)?
+ *     unary      := 'not' unary | primary
+ *     primary    := 'true' | 'false' | string | number | call | '(' expression ')'
+ *     call       := builtin '(' (operand (',' operand)*)? ')'
+ *
+ * The builtins are the closed set `hasRole`, `hasScope`, `isAuthenticated`, so the
+ * context this evaluates against is a {@link Principal} -- who is asking -- and not
+ * loop state such as a step counter. Anything the evaluator cannot decide raises:
+ * for a human-in-the-loop gate, "could not decide" must never degrade into "do not
+ * ask".
+ *
+ * This file mirrors `aid_runtime/agents/policy.py`. The builtin set is duplicated
+ * from `packages/ir` rather than imported, because this package has no dependency on
+ * the spec toolchain; a test reads the IR source and keeps the two sets equal.
+ */
+/** One node of a parsed policy. Plain JSON, as the IR carries it. */
+export type PolicyNode = Readonly<Record<string, unknown>>;
+/** Builtin policy functions, in the order the IR declares them. */
+export declare const POLICY_BUILTINS: readonly ['hasRole', 'hasScope', 'isAuthenticated'];
+/** How many operands each builtin takes. */
+export declare const POLICY_BUILTIN_ARITY: Readonly<Record<string, number>>;
+/**
+ * Who a policy is evaluated for.
+ *
+ * Defaults are the anonymous-but-authenticated caller an app with no auth layer has:
+ * `isAuthenticated()` is true and both role and scope sets are empty, so
+ * `hasRole('admin')` is false rather than undefined.
+ */
+export declare class Principal {
+    readonly roles: ReadonlySet<string>;
+    readonly scopes: ReadonlySet<string>;
+    readonly authenticated: boolean;
+    constructor(init?: {
+        readonly roles?: Iterable<string>;
+        readonly scopes?: Iterable<string>;
+        readonly authenticated?: boolean;
+    });
+}
+/** Evaluate a parsed policy against `principal`. Never returns "maybe". */
+export declare function evaluatePolicy(node: PolicyNode, principal: Principal): boolean;
+/** Render an AST back to source, so a trace or error can quote the policy. */
+export declare function policySource(node: PolicyNode): string;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAK3D,mEAAmE;AACnE,eAAO,MAAM,eAAe,YAAI,SAAS,EAAE,UAAU,EAAE,iBAAiB,CAAU,CAAC;AAEnF,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIjE,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,YACE,IAAI,GAAE;QACJ,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;KAC7B,EAKP;CACF;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAQ9E;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAqBrD"}

package/dist/policy.js

@@ -0,0 +1,199 @@
+/**
+ * Evaluation of the IR's `PolicyExpr` AST.
+ *
+ * The grammar is the one `packages/ir/src/policy` parses, and the AST is plain JSON
+ * precisely so a target does not need a second parser:
+ *
+ *     expression := or
+ *     or         := and ('or' and)*
+ *     and        := comparison ('and' comparison)*
+ *     comparison := unary (('==' | '!=' | '<' | '<=' | '>' | '>=') unary)?
+ *     unary      := 'not' unary | primary
+ *     primary    := 'true' | 'false' | string | number | call | '(' expression ')'
+ *     call       := builtin '(' (operand (',' operand)*)? ')'
+ *
+ * The builtins are the closed set `hasRole`, `hasScope`, `isAuthenticated`, so the
+ * context this evaluates against is a {@link Principal} -- who is asking -- and not
+ * loop state such as a step counter. Anything the evaluator cannot decide raises:
+ * for a human-in-the-loop gate, "could not decide" must never degrade into "do not
+ * ask".
+ *
+ * This file mirrors `aid_runtime/agents/policy.py`. The builtin set is duplicated
+ * from `packages/ir` rather than imported, because this package has no dependency on
+ * the spec toolchain; a test reads the IR source and keeps the two sets equal.
+ */
+import { PolicyEvaluationError } from './errors.js';
+import { repr } from './internal/json.js';
+const COMPARISONS = new Set(['==', '!=', '<', '<=', '>', '>=']);
+const LOGICAL = new Set(['and', 'or']);
+/** Builtin policy functions, in the order the IR declares them. */
+export const POLICY_BUILTINS = ['hasRole', 'hasScope', 'isAuthenticated'];
+/** How many operands each builtin takes. */
+export const POLICY_BUILTIN_ARITY = {
+    hasRole: 1,
+    hasScope: 1,
+    isAuthenticated: 0,
+};
+/**
+ * Who a policy is evaluated for.
+ *
+ * Defaults are the anonymous-but-authenticated caller an app with no auth layer has:
+ * `isAuthenticated()` is true and both role and scope sets are empty, so
+ * `hasRole('admin')` is false rather than undefined.
+ */
+export class Principal {
+    roles;
+    scopes;
+    authenticated;
+    constructor(init = {}) {
+        this.roles = new Set(init.roles ?? []);
+        this.scopes = new Set(init.scopes ?? []);
+        this.authenticated = init.authenticated ?? true;
+    }
+}
+/** Evaluate a parsed policy against `principal`. Never returns "maybe". */
+export function evaluatePolicy(node, principal) {
+    const value = evaluateNode(node, principal);
+    if (typeof value !== 'boolean') {
+        throw new PolicyEvaluationError(`policy did not evaluate to a boolean, got ${typeName(value)}: ${policySource(node)}`);
+    }
+    return value;
+}
+/** Render an AST back to source, so a trace or error can quote the policy. */
+export function policySource(node) {
+    const kind = node.kind;
+    if (kind === 'string' || kind === 'number' || kind === 'boolean') {
+        return literalSource(node.value);
+    }
+    if (kind === 'call') {
+        const args = asArray(node.args).map((argument) => policySource(argument));
+        return `${String(node.name)}(${args.join(', ')})`;
+    }
+    if (kind === 'comparison') {
+        return `${policySource(asNode(node.left))} ${String(node.op)} ${policySource(asNode(node.right))}`;
+    }
+    if (typeof kind === 'string' && LOGICAL.has(kind)) {
+        return `(${policySource(asNode(node.left))} ${kind} ${policySource(asNode(node.right))})`;
+    }
+    if (kind === 'not') {
+        return `not ${policySource(asNode(node.operand))}`;
+    }
+    throw new PolicyEvaluationError(`unsupported policy node kind ${describe(kind)}`);
+}
+function literalSource(value) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string')
+        return `"${value}"`;
+    return String(value);
+}
+function evaluateNode(node, principal) {
+    const kind = node.kind;
+    if (kind === 'string' || kind === 'number' || kind === 'boolean') {
+        return node.value;
+    }
+    if (kind === 'call')
+        return call(node, principal);
+    if (kind === 'comparison')
+        return compare(node, principal);
+    if (typeof kind === 'string' && LOGICAL.has(kind))
+        return logic(kind, node, principal);
+    if (kind === 'not') {
+        return !asBoolean(evaluateNode(asNode(node.operand), principal), node);
+    }
+    throw new PolicyEvaluationError(`unsupported policy node kind ${describe(kind)}`);
+}
+function call(node, principal) {
+    const name = node.name;
+    const args = asArray(node.args).map((argument) => evaluateNode(argument, principal));
+    if (name === 'isAuthenticated') {
+        if (args.length > 0)
+            throw new PolicyEvaluationError('isAuthenticated() takes no arguments');
+        return principal.authenticated;
+    }
+    if (name === 'hasRole')
+        return membership(String(name), args, principal.roles);
+    if (name === 'hasScope')
+        return membership(String(name), args, principal.scopes);
+    throw new PolicyEvaluationError(`unknown policy builtin ${describe(name)}`);
+}
+function membership(name, args, held) {
+    if (args.length !== 1) {
+        throw new PolicyEvaluationError(`${name}() takes exactly one argument`);
+    }
+    const [wanted] = args;
+    if (typeof wanted !== 'string') {
+        throw new PolicyEvaluationError(`${name}() argument must be a string, got ${describe(wanted)}`);
+    }
+    return held.has(wanted);
+}
+function compare(node, principal) {
+    const operator = node.op;
+    if (typeof operator !== 'string' || !COMPARISONS.has(operator)) {
+        throw new PolicyEvaluationError(`unknown comparison operator ${describe(operator)}`);
+    }
+    const left = evaluateNode(asNode(node.left), principal);
+    const right = evaluateNode(asNode(node.right), principal);
+    if (operator === '==')
+        return left === right;
+    if (operator === '!=')
+        return left !== right;
+    const comparable = (typeof left === 'number' && typeof right === 'number') ||
+        (typeof left === 'string' && typeof right === 'string');
+    if (!comparable) {
+        throw new PolicyEvaluationError(`cannot compare ${typeName(left)} ${operator} ${typeName(right)}: ${policySource(node)}`);
+    }
+    const a = left;
+    const b = right;
+    switch (operator) {
+        case '<':
+            return a < b;
+        case '<=':
+            return a <= b;
+        case '>':
+            return a > b;
+        default:
+            return a >= b;
+    }
+}
+function logic(kind, node, principal) {
+    const left = asBoolean(evaluateNode(asNode(node.left), principal), node);
+    // `and`/`or` short-circuit on the left operand's truth value.
+    if (kind === 'and' && !left)
+        return false;
+    if (kind === 'or' && left)
+        return true;
+    return asBoolean(evaluateNode(asNode(node.right), principal), node);
+}
+function asBoolean(value, node) {
+    if (typeof value !== 'boolean') {
+        throw new PolicyEvaluationError(`expected a boolean operand in ${policySource(node)}, got ${describe(value)}`);
+    }
+    return value;
+}
+function asNode(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new PolicyEvaluationError(`policy operand is not a node: ${describe(value)}`);
+    }
+    return value;
+}
+function asArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new PolicyEvaluationError(`policy operands are not a list: ${describe(value)}`);
+    }
+    return value.map((entry) => asNode(entry));
+}
+function typeName(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    const kind = typeof value;
+    return kind === 'object' ? 'object' : kind;
+}
+function describe(value) {
+    return typeof value === 'string' ? repr(value) : String(value);
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

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

package/dist/prompts.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Versioned prompt templates.
+ *
+ * A prompt is a versioned artifact, not a string constant, for the same reason a
+ * model is pinned: a baseline recorded against `support-reply` v2 means nothing if
+ * "v2" quietly becomes v3. The registry therefore refuses a duplicate name+version
+ * rather than overwriting, and version ordering is defined here rather than left to
+ * `Array.prototype.sort` on strings (`'v10' < 'v9'` lexicographically, which is
+ * exactly the bug this ordering exists to prevent).
+ */
+import { Message } from './types.js';
+/** One worked example, rendered into the message list between system and user. */
+export declare class Example {
+    readonly input: string;
+    readonly output: string;
+    constructor(init: {
+        readonly input: string;
+        readonly output: string;
+    });
+}
+/** A template plus the metadata a registry keys it by. */
+export declare class PromptTemplate {
+    readonly name: string;
+    readonly version: string;
+    readonly template: string;
+    readonly description: string;
+    readonly examples: readonly Example[];
+    readonly required: readonly string[];
+    constructor(init: {
+        readonly name: string;
+        readonly version: string;
+        readonly template: string;
+        readonly description?: string;
+        readonly examples?: readonly Example[];
+        readonly required?: readonly string[];
+    });
+    /** The variables the template body actually uses. */
+    get variables(): readonly string[];
+    /** Fill the template, refusing both missing and unused variables. */
+    render(values?: Readonly<Record<string, unknown>>): RenderedPrompt;
+}
+/** The result of rendering a template. */
+export declare class RenderedPrompt {
+    readonly name: string;
+    readonly version: string;
+    readonly text: string;
+    readonly examples: readonly Example[];
+    constructor(init: {
+        readonly name: string;
+        readonly version: string;
+        readonly text: string;
+        readonly examples?: readonly Example[];
+    });
+    /**
+     * The message list this prompt becomes: system, then one pair per example, then
+     * the user turn.
+     *
+     * The examples sit between the system turn and the real question deliberately:
+     * they are part of the instructions, and putting them after the question invites
+     * a model to answer the last example instead.
+     */
+    asMessages(system?: string): Message[];
+}
+/** Compare two version strings by dotted-segment order. */
+export declare function compareVersions(left: string, right: string): number;
+/** Sort version strings oldest to newest. */
+export declare function orderedVersions(versions: Iterable<string>): string[];
+/** A closed set of templates, keyed by name and version. */
+export declare class PromptRegistry {
+    private readonly _templates;
+    constructor(templates?: Iterable<PromptTemplate>);
+    /** Add a template. A duplicate name+version is a configuration error, not a replace. */
+    register(template: PromptTemplate): void;
+    /** The registered names, sorted. */
+    names(): string[];
+    /** Every version of one prompt, oldest first. */
+    versions(name: string): string[];
+    /** The newest version of one prompt. */
+    latest(name: string): PromptTemplate;
+    /** One prompt, by explicit version or the newest. */
+    get(name: string, version?: string): PromptTemplate;
+    /** Resolve and render in one step. */
+    render(name: string, values?: Readonly<Record<string, unknown>>, version?: string): RenderedPrompt;
+    private key;
+}
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

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