/** * Worker-dispatch effect verification (#2891, S1 direct/shared checkpoint). * * Modelled on the ledger lock recovery (`src/effects/lock-recovery.ts`): an * extension kind whose verifier is registered only when the evidence it * checks actually exists. Here the evidence is Tier 0 supervisor evidence * held by the conductor — the dispatch record digest for one invocation, * plus optional `file.digest` artifacts. Without supervisor evidence the * factory returns null and the kind stays unregistered, so reconciliation * through the existing ledger answers `unknown` / `verifier-missing` instead * of manufacturing proof. * * Artifact checks reuse the built-in `file.digest` verifier by delegation; * this module owns no second ledger and no file hashing of its own. * * Managed (S2+) durable dispatch proof and Tier 1 registration are out of * scope; this verifier covers direct/shared supervisor evidence only. * * @see docs/contracts/effect-ledger.v1.md "Verifier interface" */ import { type EffectVerifier } from './verifiers/types.js'; export declare const DISPATCH_KIND: "x.aiwg.worker-dispatch"; export declare const DISPATCH_VERIFIER_VERSION = "1.0.0"; /** * Canonical invocation-ID shape for dispatch evidence (#2891). This is the * SINGLE definition: `tools/ralph-external/lib/dispatch-evidence.mjs` * imports this exact binding (through `tools/_resolve-impl.mjs`'s * `importImpl`, since `tools/` cannot import `src/*.js` directly) rather * than duplicating the literal, so the two can never drift. */ export declare const INVOCATION_PATTERN: RegExp; /** Conductor-owned evidence directories and files are owner-only. */ export declare const DISPATCH_EVIDENCE_DIR_MODE = 448; export declare const DISPATCH_EVIDENCE_FILE_MODE = 384; /** Supervisor evidence the conductor holds for one direct dispatch. */ export interface DispatchSupervisorEvidence { /** The dispatched invocation this evidence supervises. */ invocationId: string; /** `sha256:` over the supervisor's dispatch record. */ evidenceDigest: string; /** Optional artifact verified through `file.digest`, relative to the project root. */ artifactPath?: string; /** `sha256:` of the artifact; required when `artifactPath` is set. */ artifactDigest?: string; } export declare function dispatchEffectTarget(invocationId: string): string; /** * Test-only race-injection seam (#2891 R1/R7), mirroring the equivalent hook * in `tools/ralph-external/lib/dispatch-evidence.mjs`. No-op in production * (`afterOpen` defaults to `null`); this package's own conformance suite * sets it to a one-shot callback that performs a deterministic TOCTOU swap * between `loadSupervisorEvidence`'s two `open()` calls, then clears * itself. Never read outside `openTraced` below. */ export declare const __raceTestHooks: { afterOpen: ((targetPath: string) => void | Promise) | null; }; /** * Read supervisor evidence from the conductor-owned evidence location. The * evidence directory is opened `O_NOFOLLOW` ONCE and kept open for the * whole read: the file `.json` is then opened through that * SAME still-open directory descriptor, via `/proc/self/fd//`, * never by re-resolving `/.json` as a fresh path * string. This means a swap of `evidenceDir`'s path between validating the * directory and reading the file cannot redirect the read onto an attacker- * controlled location — the descriptor still refers to the original, * validated directory regardless of what the path now names. * * Every check runs against an open fd: the evidence directory must be a * real directory owned by us with mode exactly 0700, and the evidence file * must be a regular file owned by us with mode exactly 0600 and exactly one * link (no surprise hardlink). Supervisor evidence is never read from a * worker-writable path: any symlink, wrong mode, wrong owner, extra link or * unbound invocationId throws instead of verifying. * * When `expectedRecordDigest` is supplied (the sha256 of the evidence * file's raw bytes, recorded by the conductor at capture time — for * example from the effect ledger intent this evidence backs), the freshly * read bytes must hash to it or the load throws. Shape and permission * checks alone cannot detect in-place mutation of an already-captured * evidence file; this closes that gap for any caller that has an earlier * recorded digest to check against. */ export declare function loadSupervisorEvidence(options: { evidenceDir: string; invocationId: string; expectedRecordDigest?: string; }): Promise; /** True only when actual supervisor evidence exists: a bound invocation and digest. */ export declare function hasSupervisorEvidence(evidence: unknown): evidence is DispatchSupervisorEvidence; /** * Build the dispatch verifier bound to one project's supervisor evidence, or * null when no actual supervisor evidence exists. Callers register the * returned verifier (for example through the `extensions` of * `buildCliVerifierRegistry`) only when it is non-null; a null result means * the kind stays unregistered and reconciliation reports unknown. */ export declare function createDispatchVerifierIfSupervised(options: { projectDir: string; evidence?: unknown; /** * Conductor-owned 0700 evidence directory holding this dispatch's * artifacts. `file.digest` delegation roots here — NEVER at the broad * project directory, and never falls back to it — so a supervised * artifact cannot name files outside the evidence tree. Omitting this * when the supervised evidence names an artifact (`artifactPath` set) is * not verifiable: `verify()` reports `evidence-conflict`, it does not * fall back to `projectDir`. Omit only when the supervised evidence names * no artifact at all; callers that bind supervisor evidence through * {@link loadSupervisorEvidence} already hold this directory. */ evidenceDir?: string; }): EffectVerifier | null; //# sourceMappingURL=dispatch-verifier.d.ts.map