@cleocode/core 2026.9.20 → 2026.9.22

package/dist/tasks/gate-result-cache.js

@@ -0,0 +1,285 @@
+/**
+ * Result cache for typed acceptance gates (T12621 · ADR-061).
+ *
+ * `tool:` evidence atoms have been cached since T1534; typed gates were not, so
+ * `cleo verify <id> --run` followed by the attesting `cleo verify <id> --gate …`
+ * executed a slow suite twice, and a retry after any unrelated failure executed
+ * it a third time. This module gives typed gates the same content-addressed
+ * cache, in the same directory (`.cleo/cache/evidence/`, `gate-` prefix).
+ *
+ * The key is `(gate definition hash, git HEAD, dirty-tree fingerprint, cwd,
+ * inputs digest)`. HEAD and the fingerprint come from the exact helpers the tool
+ * cache uses, so every tracked byte is unchanged on a hit. The inputs digest
+ * covers what the fingerprint cannot: the captured invocation (including its
+ * environment hash) and the bytes of every input the verifier binds — untracked
+ * harness scripts and task files included. Like the tool cache, a directory that
+ * is not a git checkout gets no caching at all rather than one answer forever
+ * (gh#1419).
+ *
+ * NOT in the key (the gh#1221 trade-off, stated rather than hidden): modules an
+ * untracked harness imports, `node_modules`, and an in-place toolchain upgrade.
+ * A reused pass is therefore always marked `source: 'cache'` on the result and
+ * on the receipt, and `evidence.allowCachedGates: false` in
+ * `.cleo/project-context.json` turns reuse off and makes completion refuse it.
+ *
+ * ## Authentication
+ *
+ * Entries are plain JSON in the project, and every key input is public, so an
+ * unauthenticated entry is a forgeable pass. Each entry therefore carries an
+ * HMAC-SHA256 under a per-machine key at `<cleoHome>/keys/evidence-cache.key`
+ * (created `0600` on first use, outside every project and worktree). An entry
+ * whose MAC does not verify is never served. This module can VERIFY an entry
+ * given the key; only the gate runner can create one, from a result it executed
+ * itself, and nothing exported from core loads the key. The key defends against
+ * hand-written, tampered and copied entries; it cannot defend against a process
+ * that reads the key file directly with the user's own privileges.
+ *
+ * Only a `pass` is ever written. A failure, an error or a timeout is not a
+ * reusable fact about the tree — it is the thing the next run exists to change.
+ * Only process-executing kinds (`test`, `command`, `lint`) are cacheable.
+ *
+ * @task T12621
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { acceptanceGateResultSchema } from '@cleocode/contracts';
+import { getCleoHome } from '../paths.js';
+import { acItemToText } from './ac-table.js';
+import { captureDirtyFingerprint, captureHead } from './tool-cache.js';
+/** Schema version of an on-disk gate cache entry; bump to invalidate every entry. */
+export const GATE_CACHE_SCHEMA_VERSION = 2;
+/** Gate kinds whose pass can be reused for an unchanged tree. */
+const CACHEABLE_GATE_KINDS = new Set([
+    'test',
+    'command',
+    'lint',
+]);
+/**
+ * Whether a gate kind's pass may be served from the cache.
+ * @param gate - Gate to classify.
+ * @returns `true` for `test`, `command` and `lint` gates.
+ * @example
+ * ```typescript
+ * isCacheableGate({ kind: 'manual', description: 'look', prompt: 'ok?' }); // false
+ * ```
+ * @task T12621
+ */
+export function isCacheableGate(gate) {
+    return CACHEABLE_GATE_KINDS.has(gate.kind);
+}
+/**
+ * Capture the repo state gate cache keys are computed against.
+ * @param projectRoot - Directory the gates execute in.
+ * @returns The state, or `null` when the directory is not a git checkout.
+ * @example
+ * ```typescript
+ * const state = await captureGateCacheState('/project');
+ * ```
+ * @task T12621
+ */
+export async function captureGateCacheState(projectRoot) {
+    const head = await captureHead(projectRoot);
+    if (!head)
+        return null;
+    const dirtyFingerprint = await captureDirtyFingerprint(projectRoot);
+    if (!dirtyFingerprint)
+        return null;
+    let cwd;
+    try {
+        cwd = realpathSync(projectRoot);
+    }
+    catch {
+        cwd = resolve(projectRoot);
+    }
+    return { head, dirtyFingerprint, cwd };
+}
+function gateHash(gate) {
+    return createHash('sha256').update(acItemToText(gate)).digest('hex');
+}
+function gateCacheKey(gate, state, inputsHash) {
+    return createHash('sha256')
+        .update(JSON.stringify([gateHash(gate), state.head, state.dirtyFingerprint, state.cwd, inputsHash]))
+        .digest('hex')
+        .slice(0, 32);
+}
+/**
+ * Absolute path of the cache entry for a gate against a repo state.
+ * @param projectRoot - Project whose `.cleo/cache/evidence/` holds the entry.
+ * @param gate - Gate definition.
+ * @param state - Repo state from {@link captureGateCacheState}.
+ * @param inputsHash - Digest of the captured invocation and input artifacts.
+ * @returns The entry path (which may not exist).
+ * @example
+ * ```typescript
+ * const path = gateCacheEntryPath(root, gate, state, inputsHash);
+ * ```
+ * @task T12621
+ */
+export function gateCacheEntryPath(projectRoot, gate, state, inputsHash) {
+    return join(projectRoot, '.cleo', 'cache', 'evidence', `gate-${gateCacheKey(gate, state, inputsHash)}.json`);
+}
+/**
+ * Path of the per-machine key that authenticates evidence cache entries.
+ * @returns `<cleoHome>/keys/evidence-cache.key`.
+ * @example
+ * ```typescript
+ * evidenceCacheKeyPath(); // ~/.local/share/cleo/keys/evidence-cache.key
+ * ```
+ * @task T12621
+ */
+export function evidenceCacheKeyPath() {
+    return join(getCleoHome(), 'keys', 'evidence-cache.key');
+}
+/**
+ * Build the unsealed entry body for an observed pass.
+ * @param gate - Gate the result was observed for.
+ * @param state - Repo state captured BEFORE the gate executed.
+ * @param inputsHash - Inputs digest captured BEFORE the gate executed.
+ * @param result - The runner's observed result.
+ * @returns The body to seal, or `null` for anything but a cacheable pass.
+ * @example
+ * ```typescript
+ * const body = buildGateCacheEntryBody(gate, state, inputsHash, observed);
+ * ```
+ * @task T12621
+ */
+export function buildGateCacheEntryBody(gate, state, inputsHash, result) {
+    if (!isCacheableGate(gate) || result.result !== 'pass')
+        return null;
+    const { index: _index, binding: _binding, source: _source, cachedAt: _cachedAt, ...observed } = result;
+    return {
+        schemaVersion: GATE_CACHE_SCHEMA_VERSION,
+        key: gateCacheKey(gate, state, inputsHash),
+        gateHash: gateHash(gate),
+        head: state.head,
+        dirtyFingerprint: state.dirtyFingerprint,
+        cwd: state.cwd,
+        inputsHash,
+        createdAt: new Date().toISOString(),
+        result: observed,
+    };
+}
+/**
+ * Canonical bytes an entry's MAC covers: every body field, in a fixed order.
+ * @param body - Entry body (a `mac` field, if present, is ignored).
+ * @returns The string to MAC.
+ * @example
+ * ```typescript
+ * const payload = gateCacheEntryMacPayload(body);
+ * ```
+ * @task T12621
+ */
+export function gateCacheEntryMacPayload(body) {
+    return JSON.stringify([
+        body.schemaVersion,
+        body.key,
+        body.gateHash,
+        body.head,
+        body.dirtyFingerprint,
+        body.cwd,
+        body.inputsHash,
+        body.createdAt,
+        body.result,
+    ]);
+}
+function macOf(body, key) {
+    return createHmac('sha256', key).update(gateCacheEntryMacPayload(body)).digest('hex');
+}
+/**
+ * Seal an entry body with the machine key.
+ * @param body - Entry body from {@link buildGateCacheEntryBody}.
+ * @param key - Machine key; the caller is the only holder.
+ * @returns The sealed entry.
+ * @example
+ * ```typescript
+ * const entry = sealGateCacheEntry(body, key);
+ * ```
+ * @task T12621
+ */
+export function sealGateCacheEntry(body, key) {
+    return { ...body, mac: macOf(body, key) };
+}
+/**
+ * Look a gate up in the cache and authenticate what is found.
+ * @param projectRoot - Project whose `.cleo/cache/evidence/` holds the entry.
+ * @param gate - Gate definition; any change to it changes the key.
+ * @param state - Repo state from {@link captureGateCacheState}.
+ * @param inputsHash - Digest of the captured invocation and input artifacts.
+ * @param key - Machine key the entry must be sealed under.
+ * @returns `hit` with the observation, `miss` when there is no entry, or
+ * `invalid` when an entry exists but is unauthenticated, tampered or not a pass.
+ * @example
+ * ```typescript
+ * const lookup = readGateCacheEntry(root, gate, state, inputsHash, key);
+ * ```
+ * @task T12621
+ */
+export function readGateCacheEntry(projectRoot, gate, state, inputsHash, key) {
+    if (!isCacheableGate(gate))
+        return { status: 'miss' };
+    const path = gateCacheEntryPath(projectRoot, gate, state, inputsHash);
+    if (!existsSync(path))
+        return { status: 'miss' };
+    let entry;
+    try {
+        entry = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return { status: 'invalid', reason: 'entry is not readable JSON' };
+    }
+    if (entry.schemaVersion !== GATE_CACHE_SCHEMA_VERSION ||
+        entry.key !== gateCacheKey(gate, state, inputsHash) ||
+        entry.gateHash !== gateHash(gate) ||
+        entry.head !== state.head ||
+        entry.dirtyFingerprint !== state.dirtyFingerprint ||
+        entry.cwd !== state.cwd ||
+        entry.inputsHash !== inputsHash ||
+        typeof entry.createdAt !== 'string' ||
+        !entry.result ||
+        typeof entry.mac !== 'string')
+        return { status: 'invalid', reason: 'entry is unsealed or describes another gate or tree' };
+    const expected = Buffer.from(macOf(entry, key), 'hex');
+    const actual = Buffer.from(entry.mac, 'hex');
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        return { status: 'invalid', reason: 'entry MAC does not verify under this machine key' };
+    try {
+        const result = acceptanceGateResultSchema.parse({ ...entry.result, index: 0 });
+        if (result.result !== 'pass' || result.kind !== gate.kind || result.req !== gate.req)
+            return { status: 'invalid', reason: 'entry is not a pass for this gate' };
+        const { index: _index, binding: _binding, source: _source, cachedAt: _cachedAt, ...observation } = result;
+        return { status: 'hit', observation, createdAt: entry.createdAt };
+    }
+    catch {
+        return { status: 'invalid', reason: 'entry result is malformed' };
+    }
+}
+/**
+ * Project policy: may a typed gate pass be reused from the cache?
+ *
+ * Reads `evidence.allowCachedGates` from `.cleo/project-context.json` with a
+ * bare read, like `evidence.gitRoot`. Only an explicit `false` disables reuse.
+ *
+ * @param projectRoot - CLEO store root holding `.cleo/`.
+ * @returns `false` only when the project declares `evidence.allowCachedGates: false`.
+ * @example
+ * ```typescript
+ * if (!readAllowCachedGates(root)) cache = 'off';
+ * ```
+ * @task T12621
+ */
+export function readAllowCachedGates(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectRoot, '.cleo', 'project-context.json'), 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return true;
+        const evidence = parsed.evidence;
+        if (evidence === null || typeof evidence !== 'object' || Array.isArray(evidence))
+            return true;
+        return evidence.allowCachedGates !== false;
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=gate-result-cache.js.map

package/dist/tasks/gate-result-cache.js.map

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

package/dist/tasks/gate-runner.d.ts

@@ -12,8 +12,12 @@
  *
  * Design constraints:
  *   - Each gate is self-contained (no cross-gate state).
- *   - Gates run sequentially under the original shared deadline (two seconds by default).
- *   - Per-gate timeouts can only tighten the shared deadline. Long work needs runtime admission.
+ *   - Gates run sequentially under ONE captured operation deadline. The caller admits it
+ *     with {@link typedGateAdmissionMs}: the ADR-061 tool deadline of every executing gate
+ *     plus {@link TYPED_GATE_BOOKKEEPING_MS} for the surrounding bookkeeping (T12516).
+ *   - Per-gate timeouts can only tighten the captured deadline, never renew it.
+ *   - Passing process gates can be served from the ADR-061 evidence cache
+ *     (`options.cache`, see `gate-result-cache.ts`); failures are never cached (T12621).
  *   - Structured test-count evidence and HTTP service startup require separate capabilities.
  *   - Results are observations; this module does not persist completion authority.
  *
@@ -22,6 +26,19 @@
  */
 import type { AcceptanceGate, AcceptanceGateResult, AcRow, DataAccessor, Task } from '@cleocode/contracts';
 import type { AcceptanceGateRunOptions, AcceptanceGateVerificationReceipt } from '@cleocode/contracts/acceptance-gate';
+import type { OperationExecutionContext } from '@cleocode/contracts/jobs';
+/**
+ * Shared budget for the bookkeeping around typed gates: task and criterion
+ * reads, input snapshots, result binding and the persisting transaction.
+ *
+ * It is the same two seconds the maintenance paths use, and it is ADDED to the
+ * tool deadlines rather than bounding them. Before T12516 it was the whole
+ * lifetime of a typed verification, so any gate whose tool ran longer than two
+ * seconds — every real test suite — stopped with `E_OPERATION_DEADLINE`.
+ *
+ * @task T12516
+ */
+export declare const TYPED_GATE_BOOKKEEPING_MS = 2000;
 /**
  * Captured gate-runner options from the canonical shared contract.
  * @remarks Nested invocations retain their original operation authority and deadline.
@@ -31,6 +48,98 @@ import type { AcceptanceGateRunOptions, AcceptanceGateVerificationReceipt } from
  * ```
  */
 export type RunGatesOptions = AcceptanceGateRunOptions;
+/**
+ * Resolve the wall-clock deadline for one gate's tool execution.
+ *
+ * Precedence: the gate's own `timeoutMs`; then the legacy blanket
+ * `CLEO_GATE_TIMEOUT_MS`; then the ADR-061 tool deadline for the gate kind,
+ * resolved by {@link resolveSpawnTimeoutMs} — `CLEO_TOOL_TIMEOUT_<KIND>`, else
+ * 1,800,000 ms for `test` and 300,000 ms for every other kind.
+ *
+ * @param gate - Gate whose tool deadline is needed.
+ * @param env - Environment to read the overrides from.
+ * @returns Deadline in milliseconds.
+ * @throws When a declared or configured deadline is not a positive safe integer.
+ * @example
+ * ```typescript
+ * resolveGateTimeoutMs({ kind: 'test', description: 'suite', command: 'npm', args: ['test'], expect: 'exit0' }); // 1_800_000
+ * ```
+ * @task T12516
+ */
+export declare function resolveGateTimeoutMs(gate: AcceptanceGate, env?: NodeJS.ProcessEnv): number;
+/**
+ * Wall-clock lifetime to admit for running a set of typed gates.
+ *
+ * The sum of every tool-executing gate's ADR-061 deadline plus
+ * {@link TYPED_GATE_BOOKKEEPING_MS}. Callers that own the operation lifetime
+ * create it with this budget so the two-second shared budget covers the
+ * bookkeeping only and never bounds a tool (T12516).
+ *
+ * @param gates - Gates that will run.
+ * @param env - Environment to read deadline overrides from.
+ * @returns Budget in milliseconds, clamped to the safe-integer range.
+ * @throws When a gate deadline override is invalid (see {@link resolveGateTimeoutMs}).
+ * @example
+ * ```typescript
+ * const execution = createOperationExecutionContext(identity, { budgetMs: typedGateAdmissionMs(gates) });
+ * ```
+ * @task T12516
+ */
+export declare function typedGateAdmissionMs(gates: readonly AcceptanceGate[], env?: NodeJS.ProcessEnv): number;
+/**
+ * Prefix of the `errorMessage` a gate carries when `cache: 'only'` refused to
+ * execute it. The verifier matches it to refuse the whole write with
+ * `E_GATE_NOT_CACHED` instead of recording an `error` result.
+ * @task T12621
+ */
+export declare const GATE_NOT_CACHED_PREFIX = "--no-run:";
+/**
+ * Prefix of the `errorMessage` a gate carries when `cache: 'only'` found an
+ * entry that failed authentication. The verifier refuses the write with
+ * `E_GATE_CACHE_INVALID`: a forged or tampered pass is never recorded.
+ * @task T12621
+ */
+export declare const GATE_CACHE_INVALID_PREFIX = "--no-run [invalid cache entry]:";
+/**
+ * Compute a gate's cache inputs digest the same way the attesting verifier does.
+ * @param task - Task that owns the gate; its `files` are verifier inputs.
+ * @param gate - Gate whose invocation and inputs are captured.
+ * @param execution - Admitted lifetime whose project root scopes the capture.
+ * @param env - Environment the gate will launch with.
+ * @returns Digest to pass as `cacheInputsHash` to {@link runGates}.
+ * @example
+ * ```typescript
+ * const cacheInputsHash = await captureGateInputsHash(task, gate, execution);
+ * ```
+ * @task T12621
+ */
+export declare function captureGateInputsHash(task: Task, gate: AcceptanceGate, execution: OperationExecutionContext, env?: NodeJS.ProcessEnv): Promise<string>;
+/**
+ * The tree a typed gate runs in and is fingerprinted against.
+ *
+ * `projectRoot` is the CLEO store root, which for a git worktree is the MAIN
+ * checkout (all worktrees share one `.cleo/`). Evidence tools already run in the
+ * caller's own worktree (gh#1220); typed gates ran in the store root, so from a
+ * worktree `cleo done` measured the task's code with its tools and the main
+ * checkout with its typed gates (T12625 review). The caller's git toplevel is
+ * used only when it is a linked worktree OF THIS project — any other cwd
+ * (an unrelated repo, a test harness, a declared child repo in a multi-repo
+ * root) keeps `projectRoot`, so typed-gate paths written against the CLEO root
+ * keep resolving exactly as before.
+ *
+ * Known limit (documented, accepted): "linked worktree of this project" is read
+ * from the `.git` gitlink, so a plain directory carrying a forged gitlink that
+ * points into this project's `.git/worktrees/` is treated as a worktree. That
+ * grants nothing a copy of the checkout would not: its typed results are only
+ * carried to another tree by content (tracked inputs must hash identically and
+ * the recorded HEAD must be merged there).
+ *
+ * @param projectRoot - CLEO store root (the typed gate's authority).
+ * @param cwd - Invocation directory. Defaults to `process.cwd()`.
+ * @returns The realpath of the tree typed gates execute in.
+ * @task T12625
+ */
+export declare function resolveTypedGateRoot(projectRoot: string, cwd?: string): string;
 /**
  * Execute all typed `AcceptanceGate` entries and return results.
  *
@@ -55,6 +164,17 @@ export type RunGatesOptions = AcceptanceGateRunOptions;
  * @task T781
  */
 export declare function runGates(gates: AcceptanceGate[], options?: RunGatesOptions): Promise<AcceptanceGateResult[]>;
+/**
+ * A typed result was verified in another tree of this project and cannot be
+ * accepted from the completing tree. Carries the exact re-verify command.
+ *
+ * @task T12625
+ */
+export declare class TypedRevalidationError extends Error {
+    /** The command that re-verifies the task's typed gates in the completing tree. */
+    readonly fix: string;
+    constructor(message: string, fix: string);
+}
 /**
  * Run task requirements with their canonical AC and bounded input snapshots.
  * @param task - Captured task, including its complete mixed acceptance array.
@@ -107,6 +227,7 @@ export declare function revalidateTaskGateResults(task: Task, criteria: readonly
  * @param criteria - Normalized criteria from that same transaction.
  * @param options - Captured original execution lifetime and project scope.
  * @param accessor - Canonical receipt reader bound to the same project store.
+ * @param policy - Project evidence policy; `allowCachedGates: false` refuses cached passes (T12621).
  * @returns Resolves only when every hard typed requirement has current authentic proof.
  * @throws When typed representations, results, inputs or canonical receipts disagree.
  * @remarks Callers retain transaction ownership and must check their execution context before
@@ -117,7 +238,9 @@ export declare function revalidateTaskGateResults(task: Task, criteria: readonly
  * await validateTaskGateCompletion(task, rows, { execution }, accessor);
  * ```
  */
-export declare function validateTaskGateCompletion(task: Task, criteria: readonly AcRow[], options: RunGatesOptions, accessor: Pick<DataAccessor, 'queryAuditLog'>): Promise<void>;
+export declare function validateTaskGateCompletion(task: Task, criteria: readonly AcRow[], options: RunGatesOptions, accessor: Pick<DataAccessor, 'queryAuditLog'>, policy?: {
+    allowCachedGates?: boolean;
+}): Promise<void>;
 /**
  * Filter a mixed acceptance array to only typed `AcceptanceGate` objects.
  * Free-text strings are silently dropped with their original index preserved

package/dist/tasks/gate-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-runner.d.ts","sourceRoot":"","sources":["../../src/tasks/gate-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,KAAK,EAEL,YAAY,EAMZ,IAAI,EAEL,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAIV,wBAAwB,EACxB,iCAAiC,EAClC,MAAM,qCAAqC,CAAC;AA4B7C;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAsEjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,SAAS,KAAK,EAAE,EAC1B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAwDjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,oBAAoB,EAAE,EACxC,MAAM,EAAE,OAAO,GACd,iCAAiC,CA2BnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,SAAS,KAAK,EAAE,EAC1B,OAAO,EAAE,SAAS,oBAAoB,EAAE,EACxC,OAAO,EAAE,eAAe,EACxB,cAAc,UAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAiDf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,SAAS,KAAK,EAAE,EAC1B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAoBf;AAk2BD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,GACjC,KAAK,CAAC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAQxD"}
+{"version":3,"file":"gate-runner.d.ts","sourceRoot":"","sources":["../../src/tasks/gate-runner.ts"],"names":[],"mappings":"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"}