looply-cli 0.0.0-stage → 0.2.0

package/dist/gate.d.ts

@@ -0,0 +1,278 @@
+import { type Exemption, type GateStepResult, type GateVerdict } from '@looply/core';
+import { type ChangedEntry, type ScopeDecl, type ScopeViolation } from './scope-rule';
+/**
+ * The gate executor.
+ *
+ * Two classes of failure, and conflating them is a real bug: an **abort** means an
+ * interlock tripped (a production database is reachable, or the diff touched a
+ * railed path) and must stop everything before a single step runs; a **red** means
+ * a check failed and the round is discarded normally.
+ */
+export interface StepSpec {
+    name: string;
+    run: string;
+    timeoutS?: number;
+    /** Glob; the step is skipped when no changed path matches it. */
+    when?: string;
+    /** A required step that never ran blocks the commit — it is not an implicit pass. */
+    required?: boolean;
+}
+export interface CommandResult {
+    ok: boolean;
+    timedOut: boolean;
+    ms: number;
+    output?: string;
+    /**
+     * The process exit status, when the runner had one.
+     *
+     * ⚠️ ABSENT MEANS THE RUNNER DID NOT SAY, NOT ZERO. The contained gate runner
+     * always had the code — `UntrustedExecutionResult` carries it — and folded it
+     * into `ok` on the way out, so a rejected candidate's evidence could record
+     * "it failed" and never "it exited 2". A runner that cannot produce one
+     * (a step that never started) leaves it out, and the evidence says null.
+     */
+    exitCode?: number;
+    /**
+     * The step did not RUN, as distinct from running and failing.
+     *
+     * Set only by a runner that could not start the step at all — no contained
+     * toolchain, untrusted execution unavailable. `ok` is still false, so every
+     * existing reader keeps refusing the commit; this only tells the round what
+     * it may charge the item for.
+     */
+    unavailable?: boolean;
+    /**
+     * WHAT THIS INVOCATION COST, WHEN THE PROVIDER SAID.
+     *
+     * 🔴 IT WAS PARSED AND THEN DROPPED ON THE FLOOR. `parseAgentEnvelope` reads
+     * `total_cost_usd`, `num_turns`, `usage` and `session_id` off every JSON
+     * envelope — and `unwrapEnvelope`, the only thing any production caller uses,
+     * returned a `CommandResult` with nowhere to put them. So the field existed,
+     * the parser had a docblock about why discarding it was theatre, and all
+     * three call sites discarded it anyway.
+     *
+     * ⚠️ ABSENT MEANS THE PROVIDER DID NOT SAY, NOT ZERO. The round runs its
+     * agent with `--output-format text` and gets no envelope at all, so the
+     * expensive path reports nothing here — which `withinEnvelope` reads as
+     * unmeasurable and REFUSES against a dollar ceiling, rather than as free.
+     */
+    cost?: InvocationCost;
+}
+/**
+ * WHAT ONE PROVIDER INVOCATION COST, DECLARED ONCE.
+ *
+ * 🔴 THIS WAS TWO DECLARATIONS AND THEY DRIFTED THE MOMENT ONE GREW. The same
+ * six fields were written out here and again on `AgentEnvelope['cost']`;
+ * `unwrapEnvelope` spreads the envelope's object into this one wholesale, so
+ * adding a field to the parser put it on the wire at RUNTIME while this type
+ * said it did not exist — and a field a type does not name is a field nothing
+ * downstream can read. Found the moment M7-3 added the two cache counts.
+ *
+ * One type, in the lower module, imported by the parser above it. There is no
+ * second place to update and therefore no second place to forget.
+ *
+ * ⚠️ ABSENT MEANS THE PROVIDER DID NOT SAY, NOT ZERO. The round runs its agent
+ * with `--output-format text` and gets no envelope at all, so the expensive
+ * path reports nothing here — which `withinEnvelope` reads as unmeasurable and
+ * REFUSES against a dollar ceiling, rather than as free.
+ */
+export interface InvocationCost {
+    readonly usd?: number;
+    readonly turns?: number;
+    readonly sessionId?: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    /**
+     * Context served from the provider's cache, and context written into it —
+     * whether this turn paid again for what it already had (the audit's E-05).
+     */
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+export type CommandRunner = (cmd: string, timeoutMs: number) => Promise<CommandResult>;
+export declare const ABORT_PROD = 91;
+export declare const ABORT_RAILS = 92;
+/**
+ * The name of the synthetic gate step a scope refusal fails.
+ *
+ * 🔴 A SCOPE VIOLATION IS A RED, NOT AN ABORT, AND THE DIFFERENCE IS NOT
+ * COSMETIC. It was written as a third abort code first, and two things already
+ * in this codebase said that was wrong:
+ *
+ *   - `rejectionInput` WITHHOLDS THE PATCH of an aborted candidate, because the
+ *     rails fire on content that must not be copied into a record. A change that
+ *     is merely in the wrong PLACE is ordinary work, and withholding it would
+ *     destroy the very evidence bounded repair runs on. That withheld message
+ *     even reads "the rails aborted this candidate", which a scope abort would
+ *     have made false.
+ *   - an abort raises a `critical` alert. A model that strayed one file outside
+ *     its grant is a round to discard and brief, not a page at 3am.
+ *
+ * So the round goes red on this named step: the candidate is never accepted, no
+ * gate step runs against a tree that may have weakened it, the attempt is spent,
+ * the evidence is retained, and the worker is told what it did. Rails keep sole
+ * ownership of `abort`.
+ *
+ * ⚠️ A PROJECT COULD NAME A REAL GATE STEP `scope`. Nothing forbids it, and the
+ * result would be two steps sharing a name in the record rather than a wrong
+ * verdict. Said here rather than left to be discovered.
+ */
+export declare const SCOPE_STEP = "scope";
+export interface Rails {
+    forbiddenPaths: readonly string[];
+    prodPatterns: readonly string[];
+}
+export interface InterlockInput {
+    changedPaths: readonly string[];
+    rails: Rails;
+    /** Contents of any env files worth inspecting, plus the live environment. */
+    envValues: readonly string[];
+    /**
+     * Granted exemptions (DESIGN §8). A grant opens a railed path only when
+     * `isExemptionValid` accepts it for this item, this exact path and this
+     * moment — a raw path list here would skip the expiry and the one-item
+     * check, which is precisely the widening the core model exists to prevent.
+     */
+    exemptions?: readonly Exemption[];
+    /** The item this round is running; exemptions are per-item. */
+    itemId?: string;
+    /** Clock for the expiry check. */
+    now?: number;
+    /**
+     * The diff WITH its status codes, which `changedPaths` does not carry.
+     *
+     * Required for the scope interlock and for nothing else: telling an added
+     * file from a modified one is the entire difference between `scope.additive`
+     * meaning what it says and meaning nothing. A caller that omits it leaves
+     * the scope check unrun rather than guessing, and a guess here would be a
+     * guess about whether a file already existed.
+     */
+    changedEntries?: readonly ChangedEntry[];
+    /** The project's declared scope; see `scope-rule.ts` for the semantics. */
+    scope?: ScopeDecl;
+}
+export interface AbortResult {
+    code: number;
+    reason: string;
+    paths?: string[];
+}
+export declare const DEFAULT_TIMEOUT_S = 600;
+/**
+ * Interlocks run before any step. They are hard aborts, not tallied failures —
+ * a railed path in the diff may mean the gate itself is broken, which is a
+ * different emergency from a failing test.
+ */
+export declare function checkInterlocks(input: InterlockInput): AbortResult | null;
+export interface ScopeRefusal {
+    readonly reason: string;
+    readonly paths: string[];
+    readonly violations: readonly ScopeViolation[];
+}
+/**
+ * Whether this diff left the grant it was given.
+ *
+ * Runs BEFORE any gate step, for the reason `judged-by.ts` gives: a round's
+ * spec files sit inside the scope it may change, so a gate measured after a
+ * candidate edited it is measuring the candidate's own gate.
+ *
+ * ⚠️ RETURNS null WHEN IT CANNOT MEASURE, rather than passing quietly on a
+ * technicality. Two distinct ways that happens, and neither is a violation: the
+ * caller supplied no `scope` (every caller that predates this check), or supplied
+ * no `changedEntries` (no status codes, so an addition and a modification are
+ * indistinguishable). Both are absences of INPUT, not findings about a diff, and
+ * turning either into a refusal would fail every round on a field nobody filled
+ * in.
+ */
+export declare function scopeRefusal(input: InterlockInput): ScopeRefusal | null;
+/**
+ * The grants that actually opened a railed path for this diff. The caller puts
+ * these in the commit trailer — a door opened silently is indistinguishable in
+ * the log from a rail that never fired, and DESIGN §8 requires the opposite.
+ */
+export declare function exemptionsUsed(input: InterlockInput): Exemption[];
+/** A step runs unless it has a `when:` filter that no changed path satisfies. */
+export declare function shouldRunStep(step: StepSpec, changedPaths: readonly string[]): boolean;
+export interface GateResult {
+    verdict: GateVerdict;
+    steps: GateStepResult[];
+    abort?: AbortResult;
+    /** Grants that opened railed paths this round; the trailer records them. */
+    exemptionsUsed?: Exemption[];
+}
+/**
+ * One executed step, as it happened: the command, the exit, the text.
+ *
+ * 🔴 NOT ON `GateResult`, AND NOT ON THE LEDGER. The result is the wire shape:
+ * it reaches the event stream and the server, it carries a digest for exactly
+ * that reason, and a test pins that no raw output appears anywhere on it. This
+ * is the other half — the text a person needs to see WHY a candidate was
+ * rejected — and it travels through `RunGateInput.diagnostics`, a sink the
+ * round hands straight to evidence retention, so the text exists in one place
+ * (beside the discarded patch, before `git reset --hard` destroys the only
+ * other copy) and never on an object that is serialised. The previous trial
+ * recorded `outputDigest: 38faf4ea…` for a red typecheck and nothing else; the
+ * reason it failed was unrecoverable from the run.
+ *
+ * Bounded per step (`GATE_STEP_OUTPUT_MAX_CHARS`), truncation marked in the
+ * text and in `outputTruncated`. Skipped steps produce none.
+ */
+export interface GateStepDiagnostic {
+    step: string;
+    /** The configured shell line, verbatim. */
+    command: string;
+    /** null when the runner produced no status — a step that never started. */
+    exitCode: number | null;
+    timedOut: boolean;
+    /** The step could not run at all (no toolchain, no container). */
+    unavailable: boolean;
+    ok: boolean;
+    ms: number;
+    /**
+     * Which of the four things happened. `failed` is the ordinary red: the step
+     * ran to completion and said no. The others are about the environment or a
+     * resource, and a repair prompt must not present them as the code's fault.
+     */
+    classification: 'passed' | 'failed' | 'timed_out' | 'unavailable';
+    /** stdout and stderr interleaved — the runner reports them as one stream. */
+    output: string;
+    outputChars: number;
+    outputTruncated: boolean;
+}
+/**
+ * How much of one step's output the round keeps for evidence.
+ *
+ * 256K characters keeps a whole failing jest run with its summary; a tsc error
+ * list is far smaller. Past the bound the HEAD and the TAIL are kept — the tail
+ * because that is where every toolchain prints its summary, the head because
+ * that is where the first error is — and the cut is announced in the text.
+ */
+export declare const GATE_STEP_OUTPUT_MAX_CHARS: number;
+/**
+ * Keep `text` inside `maxChars`, announcing the cut in the text itself.
+ *
+ * ⚠️ NEVER SILENT. Evidence that was trimmed and does not say so reads as the
+ * whole story, and a person repairing from it would be repairing against a
+ * log that stops mid-error with no warning that it did.
+ */
+export declare function boundText(text: string, maxChars: number): {
+    text: string;
+    chars: number;
+    truncated: boolean;
+};
+export interface RunGateInput {
+    steps: readonly StepSpec[];
+    changedPaths: readonly string[];
+    runner: CommandRunner;
+    interlocks?: InterlockInput;
+    /** Receives each executed step's {@link GateStepDiagnostic}; see that type for why it is a sink. */
+    diagnostics?: (d: GateStepDiagnostic) => void;
+}
+/**
+ * Run the gate. Steps execute in the order given — configuration puts the cheapest
+ * first, so a broken typecheck never waits on a full test suite — and execution
+ * stops at the first failure, because everything after it is uninformative.
+ */
+export declare function runGate(input: RunGateInput): Promise<GateResult>;
+/** Required step names, for the commit check in `@looply/core`. */
+export declare function requiredSteps(steps: readonly StepSpec[]): string[];
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAEtB;;;;;;;GAOG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAEvF,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,MAAM,WAAW,KAAK;IACpB,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,6EAA6E;IAC7E,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAClC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAoBrC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,GAAG,IAAI,CAsBzE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,GAAG,IAAI,CAUvE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,EAAE,CAEjE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAItF;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,SAAS,EAAE,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,WAAW,EAAE,OAAO,CAAC;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,cAAc,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;IAClE,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAarD;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,oGAAoG;IACpG,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CA+GtE;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,EAAE,CAElE"}

package/dist/gate.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATE_STEP_OUTPUT_MAX_CHARS = exports.DEFAULT_TIMEOUT_S = exports.SCOPE_STEP = exports.ABORT_RAILS = exports.ABORT_PROD = void 0;
+exports.checkInterlocks = checkInterlocks;
+exports.scopeRefusal = scopeRefusal;
+exports.exemptionsUsed = exemptionsUsed;
+exports.shouldRunStep = shouldRunStep;
+exports.boundText = boundText;
+exports.runGate = runGate;
+exports.requiredSteps = requiredSteps;
+const core_1 = require("@looply/core");
+const glob_1 = require("./glob");
+const scope_rule_1 = require("./scope-rule");
+exports.ABORT_PROD = 91;
+exports.ABORT_RAILS = 92;
+/**
+ * The name of the synthetic gate step a scope refusal fails.
+ *
+ * 🔴 A SCOPE VIOLATION IS A RED, NOT AN ABORT, AND THE DIFFERENCE IS NOT
+ * COSMETIC. It was written as a third abort code first, and two things already
+ * in this codebase said that was wrong:
+ *
+ *   - `rejectionInput` WITHHOLDS THE PATCH of an aborted candidate, because the
+ *     rails fire on content that must not be copied into a record. A change that
+ *     is merely in the wrong PLACE is ordinary work, and withholding it would
+ *     destroy the very evidence bounded repair runs on. That withheld message
+ *     even reads "the rails aborted this candidate", which a scope abort would
+ *     have made false.
+ *   - an abort raises a `critical` alert. A model that strayed one file outside
+ *     its grant is a round to discard and brief, not a page at 3am.
+ *
+ * So the round goes red on this named step: the candidate is never accepted, no
+ * gate step runs against a tree that may have weakened it, the attempt is spent,
+ * the evidence is retained, and the worker is told what it did. Rails keep sole
+ * ownership of `abort`.
+ *
+ * ⚠️ A PROJECT COULD NAME A REAL GATE STEP `scope`. Nothing forbids it, and the
+ * result would be two steps sharing a name in the record rather than a wrong
+ * verdict. Said here rather than left to be discovered.
+ */
+exports.SCOPE_STEP = 'scope';
+exports.DEFAULT_TIMEOUT_S = 600;
+/**
+ * Split the railed paths in the diff into violations and doors legitimately
+ * opened. Missing `itemId` or `now` fails closed — with no item to check
+ * against or no clock for the expiry, no grant can be shown valid, so none is.
+ */
+function splitRailViolations(input) {
+    const { exemptions = [], itemId, now } = input;
+    const canExempt = exemptions.length > 0 && itemId !== undefined && now !== undefined;
+    const violations = [];
+    const used = [];
+    for (const path of (0, glob_1.filterMatching)(input.changedPaths, input.rails.forbiddenPaths)) {
+        const grant = canExempt ? exemptions.find((e) => (0, core_1.isExemptionValid)(e, now, itemId, path)) : undefined;
+        if (grant === undefined)
+            violations.push(path);
+        else if (!used.includes(grant))
+            used.push(grant);
+    }
+    return { violations, used };
+}
+/**
+ * Interlocks run before any step. They are hard aborts, not tallied failures —
+ * a railed path in the diff may mean the gate itself is broken, which is a
+ * different emergency from a failing test.
+ */
+function checkInterlocks(input) {
+    for (const value of input.envValues) {
+        const hit = input.rails.prodPatterns.find((p) => value.toLowerCase().includes(p.toLowerCase()));
+        if (hit) {
+            return {
+                code: exports.ABORT_PROD,
+                reason: `a database URL points at a remote host (matched ${JSON.stringify(hit)})`,
+            };
+        }
+    }
+    const { violations } = splitRailViolations(input);
+    if (violations.length) {
+        return {
+            code: exports.ABORT_RAILS,
+            reason: 'the round touched paths the rails forbid',
+            paths: violations,
+        };
+    }
+    return null;
+}
+/**
+ * Whether this diff left the grant it was given.
+ *
+ * Runs BEFORE any gate step, for the reason `judged-by.ts` gives: a round's
+ * spec files sit inside the scope it may change, so a gate measured after a
+ * candidate edited it is measuring the candidate's own gate.
+ *
+ * ⚠️ RETURNS null WHEN IT CANNOT MEASURE, rather than passing quietly on a
+ * technicality. Two distinct ways that happens, and neither is a violation: the
+ * caller supplied no `scope` (every caller that predates this check), or supplied
+ * no `changedEntries` (no status codes, so an addition and a modification are
+ * indistinguishable). Both are absences of INPUT, not findings about a diff, and
+ * turning either into a refusal would fail every round on a field nobody filled
+ * in.
+ */
+function scopeRefusal(input) {
+    const { scope, changedEntries } = input;
+    if (scope === undefined || changedEntries === undefined)
+        return null;
+    const violations = (0, scope_rule_1.scopeViolations)(changedEntries, scope);
+    if (violations.length === 0)
+        return null;
+    return {
+        reason: (0, scope_rule_1.describeScopeViolations)(violations),
+        paths: violations.map((v) => v.path),
+        violations,
+    };
+}
+/**
+ * The grants that actually opened a railed path for this diff. The caller puts
+ * these in the commit trailer — a door opened silently is indistinguishable in
+ * the log from a rail that never fired, and DESIGN §8 requires the opposite.
+ */
+function exemptionsUsed(input) {
+    return splitRailViolations(input).used;
+}
+/** A step runs unless it has a `when:` filter that no changed path satisfies. */
+function shouldRunStep(step, changedPaths) {
+    const when = step.when;
+    if (!when)
+        return true;
+    return changedPaths.some((p) => (0, glob_1.matchesGlob)(p, when));
+}
+/**
+ * How much of one step's output the round keeps for evidence.
+ *
+ * 256K characters keeps a whole failing jest run with its summary; a tsc error
+ * list is far smaller. Past the bound the HEAD and the TAIL are kept — the tail
+ * because that is where every toolchain prints its summary, the head because
+ * that is where the first error is — and the cut is announced in the text.
+ */
+exports.GATE_STEP_OUTPUT_MAX_CHARS = 256 * 1024;
+/**
+ * Keep `text` inside `maxChars`, announcing the cut in the text itself.
+ *
+ * ⚠️ NEVER SILENT. Evidence that was trimmed and does not say so reads as the
+ * whole story, and a person repairing from it would be repairing against a
+ * log that stops mid-error with no warning that it did.
+ */
+function boundText(text, maxChars) {
+    const chars = text.length;
+    if (chars <= maxChars)
+        return { text, chars, truncated: false };
+    const head = Math.floor(maxChars / 4);
+    const tail = maxChars - head;
+    const omitted = chars - head - tail;
+    return {
+        text: `${text.slice(0, head)}\n\n[… looply: ${omitted} characters omitted here; ` +
+            `the full output was ${chars} characters …]\n\n${text.slice(chars - tail)}`,
+        chars,
+        truncated: true,
+    };
+}
+/**
+ * Run the gate. Steps execute in the order given — configuration puts the cheapest
+ * first, so a broken typecheck never waits on a full test suite — and execution
+ * stops at the first failure, because everything after it is uninformative.
+ */
+async function runGate(input) {
+    let used = [];
+    if (input.interlocks) {
+        const abort = checkInterlocks(input.interlocks);
+        if (abort)
+            return { verdict: 'abort', steps: [], abort };
+        used = exemptionsUsed(input.interlocks);
+        /**
+         * Scope AFTER the rails and BEFORE the first step. Both halves of that
+         * ordering are load-bearing: rails first, so a mandatory deny is never
+         * reported as a scope question and `scope.free` can never open a railed path;
+         * steps after, so nothing is measured on a tree whose candidate may have
+         * altered the measuring.
+         */
+        const refusal = scopeRefusal(input.interlocks);
+        if (refusal) {
+            // The reason reaches the worker through the DIAGNOSTICS, which is the
+            // channel `prepareRepair` reads to brief a repair attempt. A step result
+            // carries a digest and never text, by the contract on `GateStepResult`.
+            const detail = refusal.violations
+                .map((v) => v.path + ' [' + v.status + '] ' + v.because)
+                .join('\n');
+            const text = refusal.reason + '\n' + detail;
+            input.diagnostics?.({
+                step: exports.SCOPE_STEP,
+                command: '(scope check - no command was run)',
+                exitCode: null,
+                timedOut: false,
+                // Not `unavailable`: the check RAN and answered. `unavailable` means the
+                // environment could not measure, and a repair prompt must not present
+                // this as something other than the candidate's own doing.
+                unavailable: false,
+                ok: false,
+                ms: 0,
+                classification: 'failed',
+                output: text,
+                outputChars: text.length,
+                outputTruncated: false,
+            });
+            return {
+                verdict: 'red',
+                steps: [{ step: exports.SCOPE_STEP, ok: false, ms: 0, outputDigest: (0, core_1.failureOutputDigest)(refusal.reason) }],
+                ...(used.length ? { exemptionsUsed: used } : {}),
+            };
+        }
+    }
+    const done = (verdict, steps) => used.length ? { verdict, steps, exemptionsUsed: used } : { verdict, steps };
+    const results = [];
+    for (const step of input.steps) {
+        if (!shouldRunStep(step, input.changedPaths)) {
+            // Recorded, never silently omitted: a skip is information, and hiding it is
+            // how a gate starts claiming coverage it does not have.
+            results.push({ step: step.name, ok: true, ms: 0, skipped: true });
+            continue;
+        }
+        const timeoutMs = (step.timeoutS ?? exports.DEFAULT_TIMEOUT_S) * 1000;
+        const r = await input.runner(step.run, timeoutMs);
+        const result = { step: step.name, ok: r.ok, ms: r.ms };
+        if (r.timedOut)
+            result.timedOut = true;
+        // The text, kept OFF the result and handed to the sink. Bounded now rather
+        // than at the point of writing, so nothing downstream can hold an
+        // unbounded log by forgetting to.
+        const bounded = boundText(r.output ?? '', exports.GATE_STEP_OUTPUT_MAX_CHARS);
+        input.diagnostics?.({
+            step: step.name,
+            command: step.run,
+            exitCode: typeof r.exitCode === 'number' ? r.exitCode : null,
+            timedOut: r.timedOut,
+            unavailable: r.unavailable === true,
+            ok: r.ok,
+            ms: r.ms,
+            classification: r.unavailable === true ? 'unavailable' : r.timedOut ? 'timed_out' : r.ok ? 'passed' : 'failed',
+            output: bounded.text,
+            outputChars: bounded.chars,
+            outputTruncated: bounded.truncated,
+        });
+        /**
+         * Only on failure, and only when there was output. A green step has no
+         * failure to identify, and signing one would put a digest of ordinary build
+         * chatter on every event for nothing.
+         *
+         * ⚠️ A TIMEOUT STILL GETS ONE, and that is deliberate even though
+         * `FailureFacts` excludes the timeout FLAG from the signature: what a
+         * timeout printed before it was killed is often the same text every time,
+         * and the detector's own contract says a timeout is a resource outcome
+         * rather than a deterministic failure — so it is the OUTPUT that decides
+         * sameness here, not the fact of timing out.
+         */
+        if (!r.ok && r.output !== undefined && r.output !== '' && r.unavailable !== true) {
+            result.outputDigest = (0, core_1.failureOutputDigest)(r.output);
+        }
+        results.push(result);
+        /**
+         * A step that could not run stops the gate as a failure does — everything
+         * after it would be as uninformative — but it is a different verdict.
+         *
+         * ⚠️ AND IT CARRIES NO DIGEST, above. A signature is what loop safety uses
+         * to decide "the same failure keeps coming back"; signing "no contained
+         * toolchain" would let a broken machine raise a hold against a pursuit
+         * whose code was never examined.
+         */
+        if (r.unavailable === true)
+            return done('blocked', results);
+        if (!r.ok)
+            return done('red', results);
+    }
+    return done('green', results);
+}
+/** Required step names, for the commit check in `@looply/core`. */
+function requiredSteps(steps) {
+    return steps.filter((s) => s.required).map((s) => s.name);
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

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