@aldus-runtime/gate-engine 0.2.0-next.6 → 0.2.0-next.60

package/src/definition.ts

@@ -15,6 +15,14 @@
  */
 
 import type { ActorKind } from "@aldus-runtime/core";
+import {
+  QUALITY_ENFORCEMENTS,
+  QUALITY_LEVELS,
+  validateQualityClaim,
+  type PromotionEvidence,
+  type QualityEnforcement,
+  type QualityLevel,
+} from "@aldus-runtime/core";
 
 import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
 
@@ -26,32 +34,29 @@ import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
  * 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",
-] as const;
+/**
+ * @deprecated in name only — the concept moved to Core (#115) and this is the gate-shaped alias.
+ *
+ * §12's levels are a property of any quality mechanism, not of gates. They lived here alone until
+ * an adopter's blocking evaluator turned out to be a Stage, which could declare none of this. The
+ * canonical definition is `QUALITY_LEVELS`; this name is kept because published code consumes it.
+ */
+export const GATE_LEVELS = QUALITY_LEVELS;
 
 /** @see GATE_LEVELS */
-export type GateLevel = (typeof GATE_LEVELS)[number];
+export type GateLevel = QualityLevel;
 
 /**
- * Whether a gate stops work or merely reports.
+ * Whether a gate stops work or merely reports. The gate-shaped alias of `QUALITY_ENFORCEMENTS`.
  *
- * 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.
+ * Still a two-state enumeration rather than a boolean, for the reason Core records: §12.1 makes
+ * blocking a promotion with evidence behind it, and `blocking: boolean` invites someone to flip it
+ * in a config file without producing any.
  */
-export const GATE_ENFORCEMENTS = ["blocking", "advisory"] as const;
+export const GATE_ENFORCEMENTS = QUALITY_ENFORCEMENTS;
 
 /** @see GATE_ENFORCEMENTS */
-export type GateEnforcement = (typeof GATE_ENFORCEMENTS)[number];
+export type GateEnforcement = QualityEnforcement;
 
 /**
  * Evidence that a model-assisted evaluator was calibrated before it was allowed to block.
@@ -65,14 +70,7 @@ export type GateEnforcement = (typeof GATE_ENFORCEMENTS)[number];
  * scope among what promotion must consider, because an evaluator calibrated on one host says
  * nothing about another. Dimensions are caller-supplied (§4.2), consistent with WP-09's packs.
  */
-export interface PromotionEvidence {
-  /** Identifier of the calibration report that justified promotion (WP-10). */
-  reportRef: string;
-  /** Scope the calibration covers, e.g. `{ host: "example-host", voice: "voice-a" }`. */
-  scope: Record<string, string>;
-  /** Known blind spots recorded at promotion time (§12.1, §9.3). */
-  knownBlindSpots?: string[];
-}
+export type { PromotionEvidence };
 
 /**
  * One configured gate.
@@ -119,6 +117,16 @@ export interface GateDefinition {
    * Defaults to human-only for `human_oracle`, and to any actor otherwise. §13.3 keeps final
    * performance approval human-owned "until a scoped evaluator is demonstrably reliable", and
    * §12 forbids presenting a machine pass as semantic correctness.
+   *
+   * **A `human_oracle` gate permits exactly `["human"]`, and nothing else is accepted** (#207).
+   * Until `next.56` this field only had to *include* `human` at that level, so
+   * `["human", "agent"]` resolved — a per-definition, all-runs, all-agents widening with no record
+   * of who delegated what. The arm could never be the right answer: if the judgement needs a
+   * human, permitting an agent contradicts the declared level; if it does not, the gate is at the
+   * wrong level and widening hides that. Either move the gate to the level its judgement warrants
+   * — an objectively testable check on a signed artifact is a `hard_gate` binding that artifact —
+   * or record that it was bypassed with `aldus waive --reason`. Both leave a decision with a
+   * reason attached; widening left neither.
    */
   permittedActorKinds?: readonly ActorKind[];
   /**
@@ -196,15 +204,15 @@ export function validateGateDefinition(definition: GateDefinition): ResolvedGate
     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 },
-      );
-    }
+  // The shared rule, not a second copy of it (#115). A gate and an evaluator Stage making the same
+  // claim are refused for the same reasons in the same words; two implementations of one clause
+  // is how §12 came to be enforced in one place and not the other.
+  for (const problem of validateQualityClaim({
+    level: definition.level,
+    enforcement: definition.enforcement,
+    promotionEvidence: definition.promotionEvidence,
+  })) {
+    fail(problem.message, { level: definition.level, enforcement: definition.enforcement });
   }
 
   const permittedActorKinds =
@@ -212,10 +220,23 @@ export function validateGateDefinition(definition: GateDefinition): ResolvedGate
   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],
-    });
+  // Exactly `["human"]`, not "includes human" (#207). The includes rule accepted
+  // `["human", "agent"]` on a human-oracle gate, which widens the one gate §12 level 4 gives to a
+  // person to every agent on every run, with no record of who delegated what. If the judgement
+  // needs a human, widening contradicts the level; if it does not, the gate is at the wrong level
+  // and widening hides that. Either way the honest moves exist and this arm is not one of them.
+  if (
+    definition.level === "human_oracle" &&
+    (permittedActorKinds.length !== 1 || permittedActorKinds[0] !== "human")
+  ) {
+    fail(
+      "A human-oracle gate permits exactly [human] (contract §12 level 4, §13.3). A judgement " +
+        "that needs a person cannot also be decided by an agent, and one that does not belongs at " +
+        "a lower level: move the gate to the level its judgement warrants — an objectively " +
+        "testable check on a signed artifact is a hard_gate binding that artifact — or record " +
+        "that it was bypassed with `aldus waive --reason`.",
+      { permittedActorKinds: [...permittedActorKinds] },
+    );
   }
 
   return {

package/src/engine.ts

@@ -35,7 +35,7 @@ import { GateEngineErrorCodes, gateEngineError } from "./errors.js";
 import type { CostReader, GateDecisionStore, GateEventSink } from "./ports.js";
 import {
   checkSpend,
-  grantLimitsDigest,
+  grantTermsDigest,
   type SpendCheck,
   type SpendGrant,
   type SpendRequest,
@@ -107,13 +107,19 @@ export interface GateStatus {
   /** Operator-facing explanation of why work may not proceed past this gate. */
   explanation?: string;
   /**
-   * Whether this state stops work.
+   * Whether this gate is stopping work **right now** — `enforcement` is `blocking` and `state` is
+   * neither `satisfied` nor `waived`.
    *
    * 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.
+   *
+   * Named for the fact it holds, not the class it is derived from (#204). As `blocking` it was read
+   * as the declared enforcement and printed as `(advisory)` for every satisfied blocking gate — a
+   * word that was false in every instance for the first adopter, whose gates are all blocking. The
+   * value was right; the name invited a reader to answer the neighbouring question with it.
    */
-  blocking: boolean;
+  currentlyBlocking: boolean;
 }
 
 /** Current digests of what each gate binds, keyed by gate. */
@@ -138,6 +144,15 @@ export interface DecideInput {
   comment?: string;
   /** Canonical Episode identity, for the emitted event (§6.4). */
   episodeId: string;
+  /**
+   * Present when the decider did not write this record themselves (§19.2).
+   *
+   * Supplied by the composition, which knows the acting actor. The engine's job is to refuse a
+   * transcription that names the decider as its own transcriber — that is not a transcription,
+   * it is the ordinary case wearing an extra field, and letting it through would make the field
+   * mean nothing wherever it appeared.
+   */
+  transcription?: GateDecision["transcription"];
   /** Overrides the gate's default. Defaults to the definition's `expiresOnChange`. */
   expiresOnChange?: boolean;
   /** Supplied for deterministic tests; defaults to a fresh ULID-based id. */
@@ -238,6 +253,58 @@ export class GateEngine {
       );
     }
 
+    // A transcription names someone **other** than the decider. Recording the decider as their own
+    // transcriber says nothing and would make the field unreadable wherever it did appear: a reader
+    // could no longer tell a transcribed decision from one that carried the field by habit.
+    if (
+      input.transcription !== undefined &&
+      input.transcription.recordedBy.kind === input.decidedBy.kind &&
+      input.transcription.recordedBy.id === input.decidedBy.id
+    ) {
+      throw gateEngineError(
+        GateEngineErrorCodes.GATE_TRANSCRIPTION_INVALID,
+        `The decision for gate "${gate.gateId}" records the decider as its own transcriber. A ` +
+          "transcription exists to say that someone else wrote the record down; naming the same " +
+          "actor for both says nothing and makes the field unreadable where it is real (§19.2).",
+        { category: "validation", details: { gateId: gate.gateId } },
+      );
+    }
+
+    // A waiver is not an approval, and the two refusals below are what keep it from becoming one.
+    //
+    // **It must not outlive the content it was granted against.** `expiresOnChange` is a per-
+    // decision override of the gate's default, which is defensible for an *approval* whose subject
+    // cannot drift. A non-expiring **waiver** says the check stays bypassed whatever the content
+    // becomes — that is a config flag disabling a gate, reached through the decision API instead of
+    // the config file, and it is precisely what this design exists to avoid.
+    //
+    // Closing it is also what makes the rest safe. Every gate being waivable — `release.public`
+    // included — is defensible **only** because a waiver cannot survive the subjects moving. Leave
+    // the override open and every gate needs a non-waivable declaration; close it and none does.
+    //
+    // **And it must say why.** A waiver with no reason is a blank with a timestamp: the one thing a
+    // reader of the approvals log needs from it is the part that would be missing.
+    if (input.decision === "waived") {
+      if (input.expiresOnChange === false) {
+        throw gateEngineError(
+          GateEngineErrorCodes.GATE_WAIVER_INVALID,
+          `A waiver of gate "${gate.gateId}" may not be recorded as non-expiring. A waiver says ` +
+            "the check was bypassed rather than passed, so it must not outlive the content it was " +
+            "granted against (§13.1, §13.2).",
+          { category: "policy", details: { gateId: gate.gateId } },
+        );
+      }
+      if (input.comment === undefined || input.comment.trim() === "") {
+        throw gateEngineError(
+          GateEngineErrorCodes.GATE_WAIVER_INVALID,
+          `A waiver of gate "${gate.gateId}" needs a reason. An approval records that the content ` +
+            "was judged; a waiver records that the check was bypassed, and without a reason the " +
+            "log carries a blank with a timestamp (§13.3, §19.2).",
+          { category: "validation", details: { gateId: gate.gateId } },
+        );
+      }
+    }
+
     const decision: GateDecision = {
       schemaVersion: SCHEMA_VERSION,
       decisionId: input.decisionId ?? newGateDecisionId(),
@@ -248,7 +315,10 @@ export class GateEngine {
       decidedBy: input.decidedBy,
       decidedAt: input.decidedAt,
       ...(input.comment !== undefined ? { comment: input.comment } : {}),
-      expiresOnChange: input.expiresOnChange ?? gate.expiresOnChange,
+      ...(input.transcription === undefined ? {} : { transcription: input.transcription }),
+      // Forced for a waiver, never taken from the gate default or the caller. See above.
+      expiresOnChange:
+        input.decision === "waived" ? true : (input.expiresOnChange ?? gate.expiresOnChange),
     };
 
     // Validate before persisting. A malformed decision written to the approvals log is worse
@@ -339,7 +409,7 @@ export class GateEngine {
       return {
         ...base,
         state: "pending",
-        blocking: blocks("pending"),
+        currentlyBlocking: blocks("pending"),
         // Naming the missing values rather than only the absence of a decision: an operator told
         // "no recorded decision" goes looking for who forgot to approve, when the answer is that
         // nothing has produced what the approval would bind (§13.2).
@@ -358,7 +428,7 @@ export class GateEngine {
         ...base,
         state: latest.decision,
         decision: latest,
-        blocking: blocks(latest.decision),
+        currentlyBlocking: blocks(latest.decision),
         explanation:
           latest.comment ?? `Gate "${gate.gateId}" was ${latest.decision.replace("_", " ")}.`,
       };
@@ -375,7 +445,7 @@ export class GateEngine {
         state: "stale",
         decision: latest,
         drift,
-        blocking: blocks("stale"),
+        currentlyBlocking: blocks("stale"),
         explanation:
           `Gate "${gate.gateId}" was ${latest.decision}, but ` +
           `${drift.changed.length > 0 ? `[${drift.changed.join(", ")}] changed` : "its bound inputs changed"}` +
@@ -384,7 +454,7 @@ export class GateEngine {
     }
 
     const state: GateState = latest.decision === "waived" ? "waived" : "satisfied";
-    return { ...base, state, decision: latest, blocking: blocks(state) };
+    return { ...base, state, decision: latest, currentlyBlocking: blocks(state) };
   }
 
   /**
@@ -407,7 +477,7 @@ export class GateEngine {
 
         const blockedBy = gate.dependsOn.filter((dependency) => {
           const upstream = result.get(dependency);
-          return upstream !== undefined && upstream.blocking;
+          return upstream !== undefined && upstream.currentlyBlocking;
         });
         if (blockedBy.length === 0) continue;
         if (current.blockedBy !== undefined && sameIds(current.blockedBy, blockedBy)) continue;
@@ -433,7 +503,7 @@ export class GateEngine {
           ...current,
           state,
           blockedBy,
-          blocking: gate.enforcement === "blocking",
+          currentlyBlocking: gate.enforcement === "blocking",
           explanation: ownStateIsInformative
             ? `${current.explanation ?? `Gate "${gate.gateId}" is ${current.state}.`} Additionally, ${upstreamNote}`
             : `Gate "${gate.gateId}" cannot be relied on because ${upstreamNote}`,
@@ -551,7 +621,7 @@ export class GateEngine {
       };
     }
 
-    if (!decision.subjectHashes.includes(grantLimitsDigest(grant))) {
+    if (!decision.subjectHashes.includes(grantTermsDigest(grant))) {
       return {
         authorized: false,
         statuses: [status],

package/src/errors.ts

@@ -32,6 +32,21 @@ export const GateEngineErrorCodes = {
   GATE_ACTOR_NOT_PERMITTED: "ALDUS_GATE_ACTOR_NOT_PERMITTED",
   /** A decision was submitted that does not bind the subjects its gate requires. */
   GATE_SUBJECTS_INCOMPLETE: "ALDUS_GATE_SUBJECTS_INCOMPLETE",
+  /**
+   * A waiver was recorded without a reason, or asked not to expire when its subjects change.
+   *
+   * Both refusals exist because a waiver is not an approval. An approval says the content was
+   * judged and passed; a waiver says the check was **bypassed** — so it must say why, and it must
+   * not outlive the content it was granted against.
+   */
+  GATE_WAIVER_INVALID: "ALDUS_GATE_WAIVER_INVALID",
+  /**
+   * A decision named the decider as its own transcriber.
+   *
+   * `transcription` exists to record that someone **else** wrote the decision down. Naming the
+   * same actor for both says nothing, and it would make the field unreadable where it is real.
+   */
+  GATE_TRANSCRIPTION_INVALID: "ALDUS_GATE_TRANSCRIPTION_INVALID",
   /**
    * An operation requiring authorization was attempted without a valid one.
    *

package/src/index.ts

@@ -66,11 +66,16 @@ export {
 
 export {
   SPEND_LIMIT_SUBJECT_KEY,
+  availableAuthorization,
+  checkSpendScope,
+  unestimatedPolicyIsSatisfiable,
   checkSpend,
   computeLedger,
   consumesBudget,
   costRecordDraw,
-  grantLimitsDigest,
+  grantTermsDigest,
+  type SpendAvailability,
+  type SpendScopeRefusal,
   type SpendCheck,
   type SpendGrant,
   type SpendLedger,