@cleocode/core 2026.9.8 → 2026.9.10

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

@@ -12,24 +12,25 @@
  *
  * Design constraints:
  *   - Each gate is self-contained (no cross-gate state).
- *   - Gates run sequentially unless the caller sets `parallel` options.
- *   - Default timeout is 60 000 ms per gate (overridable via `timeoutMs`
- *     on the gate or the `CLEO_GATE_TIMEOUT_MS` env variable).
+ *   - 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.
+ *   - Structured test-count evidence and HTTP service startup require separate capabilities.
+ *   - Results are observations; this module does not persist completion authority.
  *
  * @epic T760
  * @task T781
  */
-import type { AcceptanceGate, AcceptanceGateResult } from '@cleocode/contracts';
-/** Options for `runGates`. */
-export interface RunGatesOptions {
-    /** Absolute project root; defaults to `getProjectRoot()`. */
-    projectRoot?: string;
-    /**
-     * When `true`, manual gates are auto-skipped with a note.
-     * When `false` (default), they return `result: 'skipped'` with a prompt notice.
-     */
-    skipManual?: boolean;
-}
+import type { AcceptanceGate, AcceptanceGateResult, AcRow, DataAccessor, Task } from '@cleocode/contracts';
+import type { AcceptanceGateRunOptions, AcceptanceGateVerificationReceipt } from '@cleocode/contracts/acceptance-gate';
+/**
+ * Captured gate-runner options from the canonical shared contract.
+ * @remarks Nested invocations retain their original operation authority and deadline.
+ * @example
+ * ```typescript
+ * const options: RunGatesOptions = { projectRoot: '/project' };
+ * ```
+ */
+export type RunGatesOptions = AcceptanceGateRunOptions;
 /**
  * Execute all typed `AcceptanceGate` entries and return results.
  *
@@ -39,11 +40,84 @@ export interface RunGatesOptions {
  * @param gates   - Typed gate objects (strings pre-filtered by caller).
  * @param options - Execution options.
  * @returns       Ordered `AcceptanceGateResult[]`, one per gate.
+ * @throws If explicit project authority conflicts, metadata is invalid, or admission options are invalid.
+ * @remarks Results retain the original gate requirement ID. Process outcomes include target,
+ * transport and cleanup observations; they do not by themselves authorize task completion.
+ * Declared operation bytes reserve the per-gate capture ceiling before admission. Filesystem
+ * calls and regular-expression CPU work are cooperatively checked, not synchronously preempted.
+ * Canonical attachment retrieval validates its declared size but is not a streaming read API.
+ * @example
+ * ```typescript
+ * const results = await runGates([{ kind: 'command', description: 'check', cmd: 'node', args: ['check.mjs'] }], { projectRoot: '/project' });
+ * ```
  *
  * @epic T760
  * @task T781
  */
 export declare function runGates(gates: AcceptanceGate[], options?: RunGatesOptions): Promise<AcceptanceGateResult[]>;
+/**
+ * Run task requirements with their canonical AC and bounded input snapshots.
+ * @param task - Captured task, including its complete mixed acceptance array.
+ * @param criteria - Current normalized acceptance rows from the same task snapshot.
+ * @param options - Existing explicitly admitted verification lifetime and process limits.
+ * @returns Results bound to original mixed-array indexes, identities and input bytes.
+ * @remarks This function never writes a result. The canonical verifier must compare
+ * task/criterion freshness again and persist results plus receipt in one transaction.
+ * Untracked harnesses are included; undeclared runtime dependencies are not inferred.
+ * @example
+ * ```typescript
+ * const results = await runTaskGates(task, rows, { projectRoot, execution });
+ * ```
+ */
+export declare function runTaskGates(task: Task, criteria: readonly AcRow[], options: RunGatesOptions): Promise<AcceptanceGateResult[]>;
+/**
+ * Build the existing audit detail payload for one validated typed-result batch.
+ * @param results - Exact result array that is persisted alongside this receipt.
+ * @param passed - Overall verification outcome at the time of recording.
+ * @returns The canonical receipt detail shape with deterministic result-byte hash.
+ * @throws Error when results are absent, unbound, duplicated or belong to different batches.
+ * @remarks This serializer establishes shape and byte identity, not execution authority.
+ * The caller must persist the receipt and results in the same owning transaction.
+ * @example
+ * ```ts
+ * const details = createTaskGateReceipt(results, verification.passed);
+ * await transaction.appendLog({ action: 'gate.verify.typed', taskId, details });
+ * ```
+ */
+export declare function createTaskGateReceipt(results: readonly AcceptanceGateResult[], passed: boolean): AcceptanceGateVerificationReceipt;
+/**
+ * Revalidate persisted typed results against current canonical task and input state.
+ * @param task - Current task read under the caller's transaction ownership.
+ * @param criteria - Current normalized AC rows from that transaction.
+ * @param results - Authentic stored results, never caller-submitted verdicts.
+ * @param options - Current captured lifetime bounding revalidation work.
+ * @param requirePassing - True for completion; false only when recording actual unmet verification outcomes.
+ * @returns Resolves when bound inputs are current and the requested verdict policy holds.
+ * @remarks Historical unbound results and generic text-AC evidence cannot substitute.
+ * Filesystem checks are cooperative and cannot make external file writes atomic with SQLite.
+ * @example
+ * ```typescript
+ * await revalidateTaskGateResults(task, rows, task.verification?.gateResults ?? [], { execution });
+ * ```
+ */
+export declare function revalidateTaskGateResults(task: Task, criteria: readonly AcRow[], results: readonly AcceptanceGateResult[], options: RunGatesOptions, requirePassing?: boolean): Promise<void>;
+/**
+ * Validate completion authority from current typed inputs and the canonical verification receipt.
+ * @param task - Task snapshot owned by the caller's write transaction.
+ * @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.
+ * @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
+ * committing. Advisory gates retain their existing semantics; generic evidence cannot replace
+ * hard typed proof. Filesystem hashing is cooperative, not atomic with external file writes.
+ * @example
+ * ```typescript
+ * await validateTaskGateCompletion(task, rows, { execution }, accessor);
+ * ```
+ */
+export declare function validateTaskGateCompletion(task: Task, criteria: readonly AcRow[], options: RunGatesOptions, accessor: Pick<DataAccessor, 'queryAuditLog'>): 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;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EAQrB,MAAM,qBAAqB,CAAC;AAoB7B,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA8BjC;AAipBD;;;;;;;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":"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"}