@aldus-runtime/gate-engine 0.1.0

package/dist/definition.js

@@ -0,0 +1,231 @@
+/**
+ * Gate definitions (architecture contract §12, §13).
+ *
+ * A definition is **configuration**: what a gate binds to, what it depends on, how strongly it
+ * blocks, and who may decide it. A {@link GateDecision} is a **record**: what someone decided,
+ * when, and against which exact inputs. Keeping them apart is what lets a decision stay a
+ * faithful historical fact while the configuration around it evolves.
+ *
+ * Contract §13 names four gates — Content Freeze (§13.1), Performance Freeze (§13.2), Human Ear
+ * (§13.3), Final Release (§13.4). None of them is hardcoded here. §4.2 keeps show-specific
+ * process out of Core's reach and §4.3 gives adopters their own gates, so `gateId` and the
+ * subject keys are open strings and the contract's four gates are simply the definitions an
+ * adopter is most likely to write. The tests construct them to show the model expresses §13, not
+ * because the engine knows their names.
+ */
+import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
+/**
+ * The four quality levels of contract §12.
+ *
+ * These describe *what kind of judgement* a gate represents, which is independent of how
+ * strongly it blocks. §12's own table pairs them freely: a hard gate blocks, an advisory signal
+ * does not, and a model-assisted review may do either depending on whether it has been
+ * calibrated (§12.1).
+ */
+export const GATE_LEVELS = [
+    /** Blocks on an objectively testable failure (§12 level 1). */
+    "hard_gate",
+    /** Reports a possible issue without blocking (§12 level 2). */
+    "advisory_signal",
+    /** Evaluates meaning, stance, style, or claims under uncertainty (§12 level 3). */
+    "model_assisted",
+    /** A human owns the judgement, because it is subjective or asymmetric-risk (§12 level 4). */
+    "human_oracle",
+];
+/**
+ * Whether a gate stops work or merely reports.
+ *
+ * Deliberately a two-state enumeration rather than a boolean. Contract §12.1 permits an
+ * evaluator to *become* blocking only after calibration, which makes this a promotion with
+ * evidence behind it — and a field named `blocking: boolean` invites someone to flip it in a
+ * config file without producing any.
+ */
+export const GATE_ENFORCEMENTS = ["blocking", "advisory"];
+/** Actor kinds a gate accepts when the definition does not say. */
+function defaultPermittedActorKinds(level) {
+    // §12 level 4 is "human oracle — owns subjective judgment or asymmetric-risk decisions", and
+    // §13.3 keeps final performance approval human-owned. Defaulting these to any actor would let
+    // an agent satisfy the one gate the contract most insists a person owns.
+    return level === "human_oracle" ? ["human"] : ["human", "agent", "worker", "system"];
+}
+/**
+ * Resolve defaults and refuse an internally inconsistent definition.
+ *
+ * @throws {AldusError} `ALDUS_GATE_DEFINITION_INVALID`
+ */
+export function validateGateDefinition(definition) {
+    const fail = (message, details = {}) => {
+        throw gateEngineError(GateEngineErrorCodes.GATE_DEFINITION_INVALID, message, {
+            category: "validation",
+            details: { gateId: definition.gateId, ...details },
+        });
+    };
+    if (definition.gateId.trim().length === 0)
+        fail("A gate definition needs a non-empty gateId.");
+    if (definition.binds.length === 0) {
+        // A gate binding nothing cannot be invalidated by anything, which makes its approval
+        // permanent — the precise failure §13.1 and §13.2 exist to prevent.
+        fail("A gate must bind at least one subject. A gate that binds nothing can never be " +
+            "invalidated by a change, so its approval would outlive the content it approved " +
+            "(contract §13.1, §13.2).");
+    }
+    const duplicates = definition.binds.filter((key, index) => definition.binds.indexOf(key) !== index);
+    if (duplicates.length > 0) {
+        fail(`A gate cannot bind the same subject twice: ${[...new Set(duplicates)].join(", ")}.`, {
+            duplicates: [...new Set(duplicates)],
+        });
+    }
+    if (definition.dependsOn?.includes(definition.gateId) === true) {
+        fail("A gate cannot depend on itself.");
+    }
+    if (definition.level === "model_assisted" && definition.enforcement === "blocking") {
+        if (definition.promotionEvidence === undefined) {
+            fail("A model-assisted gate may only block once it has been calibrated against human-labeled " +
+                "examples (contract §12.1). Set `promotionEvidence`, or leave the gate advisory. " +
+                "Contract §12 forbids presenting a machine pass as semantic correctness.", { level: definition.level, enforcement: definition.enforcement });
+        }
+    }
+    const permittedActorKinds = definition.permittedActorKinds ?? defaultPermittedActorKinds(definition.level);
+    if (permittedActorKinds.length === 0) {
+        fail("A gate that permits no actor kind can never be decided.");
+    }
+    if (definition.level === "human_oracle" && !permittedActorKinds.includes("human")) {
+        fail("A human-oracle gate must permit a human actor (contract §12 level 4, §13.3).", {
+            permittedActorKinds: [...permittedActorKinds],
+        });
+    }
+    return {
+        ...definition,
+        dependsOn: definition.dependsOn ?? [],
+        permittedActorKinds,
+        expiresOnChange: definition.expiresOnChange ?? true,
+        grants: definition.grants ?? [],
+    };
+}
+/**
+ * A validated set of gates and the dependency graph between them.
+ *
+ * Built once and reused: cycle detection and unknown-dependency checks run at construction, so a
+ * misconfiguration surfaces when the registry is assembled rather than when an operator is
+ * waiting on an approval.
+ */
+export class GateRegistry {
+    #gates;
+    constructor(gates) {
+        this.#gates = gates;
+    }
+    /**
+     * Validate a set of definitions and the graph they form.
+     *
+     * @throws {AldusError} `ALDUS_GATE_DEFINITION_INVALID` for an invalid or duplicate definition,
+     * or an edge naming a gate that does not exist.
+     * @throws {AldusError} `ALDUS_GATE_DEPENDENCY_CYCLE` if the dependency edges form a cycle.
+     */
+    static from(definitions) {
+        const gates = new Map();
+        for (const definition of definitions) {
+            const resolved = validateGateDefinition(definition);
+            if (gates.has(resolved.gateId)) {
+                throw gateEngineError(GateEngineErrorCodes.GATE_DEFINITION_INVALID, `Gate "${resolved.gateId}" is defined more than once.`, { category: "validation", details: { gateId: resolved.gateId } });
+            }
+            gates.set(resolved.gateId, resolved);
+        }
+        for (const gate of gates.values()) {
+            for (const dependency of gate.dependsOn) {
+                if (!gates.has(dependency)) {
+                    throw gateEngineError(GateEngineErrorCodes.GATE_DEFINITION_INVALID, `Gate "${gate.gateId}" depends on "${dependency}", which is not defined. An edge to ` +
+                        "a missing gate would silently drop out of the invalidation cascade (§13.1).", { category: "validation", details: { gateId: gate.gateId, dependency } });
+                }
+            }
+        }
+        const cycle = findCycle(gates);
+        if (cycle !== undefined) {
+            throw gateEngineError(GateEngineErrorCodes.GATE_DEPENDENCY_CYCLE, `Gate dependencies form a cycle: ${cycle.join(" → ")}. Contract §13.1's cascade is only ` +
+                'meaningful over an acyclic graph; with a cycle, "what does this invalidate" has no answer.', { category: "validation", details: { cycle } });
+        }
+        return new GateRegistry(gates);
+    }
+    /** Every gate, in definition order. */
+    list() {
+        return [...this.#gates.values()];
+    }
+    /** True if the gate is registered. */
+    has(gateId) {
+        return this.#gates.has(gateId);
+    }
+    /** A gate definition, or `undefined` if it is not registered. */
+    get(gateId) {
+        return this.#gates.get(gateId);
+    }
+    /**
+     * A gate definition.
+     *
+     * @throws {AldusError} `ALDUS_GATE_NOT_FOUND`
+     */
+    require(gateId) {
+        const gate = this.#gates.get(gateId);
+        if (gate === undefined) {
+            throw gateEngineError(GateEngineErrorCodes.GATE_NOT_FOUND, `Gate "${gateId}" is not registered.`, { category: "not_found", details: { gateId } });
+        }
+        return gate;
+    }
+    /** Gates that directly depend on `gateId`. */
+    dependentsOf(gateId) {
+        return this.list().filter((gate) => gate.dependsOn.includes(gateId));
+    }
+    /**
+     * Gates that transitively depend on `gateId`, nearest first, excluding `gateId` itself.
+     *
+     * This is the reach of contract §13.1's cascade: invalidating a Content Freeze invalidates
+     * every approval downstream of it.
+     */
+    downstreamOf(gateId) {
+        const seen = new Set();
+        const ordered = [];
+        let frontier = [gateId];
+        while (frontier.length > 0) {
+            const next = [];
+            for (const current of frontier) {
+                for (const dependent of this.dependentsOf(current)) {
+                    if (seen.has(dependent.gateId))
+                        continue;
+                    seen.add(dependent.gateId);
+                    ordered.push(dependent.gateId);
+                    next.push(dependent.gateId);
+                }
+            }
+            frontier = next;
+        }
+        return ordered;
+    }
+}
+/** Depth-first cycle search, returning the offending path if there is one. */
+function findCycle(gates) {
+    const visiting = new Set();
+    const done = new Set();
+    const path = [];
+    const walk = (gateId) => {
+        if (done.has(gateId))
+            return undefined;
+        if (visiting.has(gateId))
+            return [...path.slice(path.indexOf(gateId)), gateId];
+        visiting.add(gateId);
+        path.push(gateId);
+        for (const dependency of gates.get(gateId)?.dependsOn ?? []) {
+            const found = walk(dependency);
+            if (found !== undefined)
+                return found;
+        }
+        path.pop();
+        visiting.delete(gateId);
+        done.add(gateId);
+        return undefined;
+    };
+    for (const gateId of gates.keys()) {
+        const found = walk(gateId);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+//# sourceMappingURL=definition.js.map

package/dist/definition.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Gate evaluation, decision recording, and authorization (architecture contract §12, §13, §19.3).
+ *
+ * The central design choice: **invalidation is derived, never stored.**
+ *
+ * Contract §13.1 requires a content-changing edit to invalidate the Content Freeze "and
+ * downstream approvals". The obvious implementation writes invalidation records and walks the
+ * graph marking approvals dead. That implementation has a failure mode the contract cannot
+ * tolerate — if the cascade is ever interrupted, or a gate is added after the fact, some approval
+ * stays marked valid while the thing it approved has moved underneath it, and §13.2 forbids
+ * exactly that.
+ *
+ * So nothing is marked. A gate's state is computed on every evaluation from three inputs: its
+ * latest decision, the current digests of what it binds, and the state of the gates it depends
+ * on. A stale approval cannot survive because there is no stored "valid" flag for it to survive
+ * in. Adding a dependency edge invalidates downstream approvals immediately, with no migration.
+ */
+import type { ActorRef, CostRecord, GateDecision } from "@aldus-runtime/core";
+import { type GateSubject, type SubjectDrift } from "./binding.js";
+import type { GateEnforcement, GateLevel, GateRegistry } from "./definition.js";
+import type { CostReader, GateDecisionStore, GateEventSink } from "./ports.js";
+import { type SpendCheck, type SpendGrant, type SpendRequest } from "./spend.js";
+/**
+ * What a gate currently is.
+ *
+ * `stale` is deliberately distinct from `pending`: a gate that was approved and then drifted is
+ * not the same operator situation as one nobody has looked at, and §13.1 wants the difference
+ * visible. `blocked_upstream` is likewise distinct from both — the gate itself may be perfectly
+ * approved while something it depends on is not.
+ */
+export declare const GATE_STATES: readonly [
+/** No decision has been recorded. */
+"pending", 
+/** Approved, and still bound to the current inputs. */
+"satisfied", 
+/** Approved, but a bound value has changed since (§13.1, §13.2). */
+"stale", 
+/** The operator rejected it. */
+"rejected", 
+/** The operator asked for changes. */
+"changes_requested", 
+/** The operator deliberately bypassed the check (§13, distinct from approval). */
+"waived", 
+/** A blocking gate this one depends on is not satisfied (§13.1 cascade). */
+"blocked_upstream"];
+/** @see GATE_STATES */
+export type GateState = (typeof GATE_STATES)[number];
+/** The evaluated state of one gate. */
+export interface GateStatus {
+    gateId: string;
+    state: GateState;
+    /** What kind of judgement this gate represents (§12). */
+    level: GateLevel;
+    /** Whether it stops work or merely reports (§12). */
+    enforcement: GateEnforcement;
+    /** The decision this state was computed from, if any. */
+    decision?: GateDecision;
+    /** Which bound values moved, when `state` is `stale`. */
+    drift?: SubjectDrift;
+    /** Gates that blocked this one, when `state` is `blocked_upstream`. */
+    blockedBy?: string[];
+    /** Operator-facing explanation of why work may not proceed past this gate. */
+    explanation?: string;
+    /**
+     * Whether this state stops work.
+     *
+     * An advisory gate is never blocking whatever its state — §12 level 2 "reports a possible issue
+     * without blocking" — which is why enforcement and state are separate fields rather than one
+     * conflated verdict.
+     */
+    blocking: boolean;
+}
+/** Current digests of what each gate binds, keyed by gate. */
+export type SubjectsByGate = Readonly<Record<string, readonly GateSubject[]>>;
+/** What {@link GateEngine.decide} needs. */
+export interface DecideInput {
+    runId: string;
+    gateId: string;
+    decision: GateDecision["decision"];
+    /** Current digests of everything the gate binds. */
+    subjects: readonly GateSubject[];
+    /** Who decided (§19.2). */
+    decidedBy: ActorRef;
+    /** ISO-8601 timestamp with offset. */
+    decidedAt: string;
+    comment?: string;
+    /** Canonical Episode identity, for the emitted event (§6.4). */
+    episodeId: string;
+    /** Overrides the gate's default. Defaults to the definition's `expiresOnChange`. */
+    expiresOnChange?: boolean;
+    /** Supplied for deterministic tests; defaults to a fresh ULID-based id. */
+    decisionId?: string;
+    /** Supplied for deterministic tests; defaults to a fresh ULID-based id. */
+    eventId?: string;
+}
+/** Why an operation was refused. */
+export interface AuthorizationRefusal {
+    authorized: false;
+    /** Gates that could have authorized the operation, and why none did. */
+    statuses: GateStatus[];
+    explanation: string;
+}
+/** An operation the engine permits. */
+export interface AuthorizationGrant {
+    authorized: true;
+    /** The gate whose approval authorized it. */
+    gateId: string;
+    decision: GateDecision;
+}
+/** Outcome of an authorization check. */
+export type AuthorizationResult = AuthorizationGrant | AuthorizationRefusal;
+/** Outcome of a spend authorization: the gate check and the budget check together. */
+export type SpendAuthorization = {
+    authorized: true;
+    gateId: string;
+    decision: GateDecision;
+    check: Extract<SpendCheck, {
+        allowed: true;
+    }>;
+} | {
+    authorized: false;
+    explanation: string;
+    statuses?: GateStatus[];
+    check?: SpendCheck;
+};
+/** Wiring for a {@link GateEngine}. */
+export interface GateEngineOptions {
+    registry: GateRegistry;
+    decisions: GateDecisionStore;
+    events: GateEventSink;
+    costs?: CostReader;
+}
+/**
+ * Evaluates gates, records decisions, and authorizes operations and spend.
+ */
+export declare class GateEngine {
+    #private;
+    constructor(options: GateEngineOptions);
+    /** The gate definitions this engine evaluates. */
+    get registry(): GateRegistry;
+    /**
+     * Record a human decision (contract §3.6).
+     *
+     * §3.6: "Human review MUST create a durable `GateDecision`. A chat message saying 'looks good'
+     * is not enough unless it is translated into a recorded decision tied to exact inputs." This is
+     * that translation, and it refuses anything that would produce a decision tied to less than the
+     * gate binds.
+     *
+     * @throws {AldusError} `ALDUS_GATE_NOT_FOUND` if the gate is not registered.
+     * @throws {AldusError} `ALDUS_GATE_SUBJECTS_INCOMPLETE` if the subjects do not cover the gate.
+     * @throws {AldusError} `ALDUS_GATE_ACTOR_NOT_PERMITTED` if the actor may not decide this gate.
+     */
+    decide(input: DecideInput): Promise<GateDecision>;
+    /**
+     * Evaluate every registered gate for a Run.
+     *
+     * `subjects` supplies the current digests of what each gate binds. A gate absent from it is
+     * evaluated as having no current inputs, which reads as `pending` — never as satisfied.
+     */
+    evaluate(runId: string, subjects: SubjectsByGate): Promise<Map<string, GateStatus>>;
+    /**
+     * Evaluate against a decision list already in hand.
+     *
+     * Separated from {@link GateEngine.evaluate} so the whole cascade is a pure function of its
+     * inputs — which is what makes it testable without a store and impossible to get into a
+     * partially-updated state.
+     */
+    evaluateWith(decisions: readonly GateDecision[], subjects: SubjectsByGate): Map<string, GateStatus>;
+    /**
+     * Whether an operation is authorized (contract §13.4).
+     *
+     * An approval authorizes exactly the operations its gate names in `grants` and nothing else.
+     * That is what keeps §13.4's "Uploading and making public SHOULD be separate operations"
+     * enforceable: they are two gates granting two operations, and approving one leaves the other
+     * refused.
+     *
+     * Returns a refusal rather than throwing, because a caller needs to display why an operation is
+     * unavailable.
+     */
+    authorize(runId: string, operation: string, subjects: SubjectsByGate): Promise<AuthorizationResult>;
+    /**
+     * Whether a paid request may proceed (contract §13.2, §19.3).
+     *
+     * Three things must hold, and all three are checked here because any one of them alone is
+     * insufficient:
+     *
+     * 1. the gate is satisfied — §13.2 forbids paid synthesis before the operator approves;
+     * 2. the grant's limits are among what that decision bound — otherwise the ceiling could be
+     *    raised after approval without voiding it;
+     * 3. the spend fits the remaining budget — §19.3 stop-on-budget.
+     */
+    authorizeSpend(runId: string, grant: SpendGrant, request: SpendRequest, subjects: SubjectsByGate, costs?: readonly CostRecord[]): Promise<SpendAuthorization>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

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