/** * Baseline capture — daemon-side, pre-worktree. * * Captures a signed `baseline` event BEFORE the experiment worktree is * created. The daemon calls this immediately after selecting a task but * before `git worktree add`. The event's timestamp predates the worktree * creation timestamp, closing Round 2 attack #5 (baseline gaming). * * ## Why pre-worktree matters * * An experiment agent could delay writing the baseline until after running a * slow test suite to produce an artificially inflated baseline, making any * future "improvement" trivial. Capturing the baseline from the daemon before * the worktree exists means the experiment agent can never influence the * baseline values. * * ## Time predates guarantee * * {@link captureBaseline} enforces a ≥5s gap between the commit timestamp * and the current wall-clock time. This prevents an agent from racing a * baseline write and an experiment start within the same tick. * * @see DESIGN.md §4.4 — Signed-baseline-predates-experiment enforcement * @task T1021 (T1010-S2 per DESIGN.md) */ /** * A fully-signed baseline event returned by {@link captureBaseline}. * * The `payload.worktreeNotCreatedYet: true` field is a structural assertion * that the worktree did not exist at the time of baseline capture. */ export interface CapturedBaseline { /** The sentient event `kind` — always `"baseline"`. */ kind: 'baseline'; /** ISO-8601 UTC timestamp when the baseline was captured. */ capturedAt: string; /** The git commit SHA used as the baseline anchor. */ commitSha: string; /** Metrics snapshot (test counts, timing, etc.). */ metrics: Record; /** Unique receipt identifier for this baseline event (21 chars). */ receiptId: string; /** Hex-encoded 32-byte Ed25519 public key (64 chars). */ publicKey: string; /** Hex-encoded 64-byte Ed25519 signature over the canonical payload (128 chars). */ signature: string; } /** * Capture a signed baseline event for a given commit SHA. * * Steps: * 1. Verify the commit SHA exists in git and retrieve its author timestamp. * 2. Enforce that `commitSha` is at least {@link MIN_BASELINE_AGE_MS} old * relative to the current wall-clock time. Throws * `E_BASELINE_MUST_PREDATE_EXPERIMENT` if the commit is too recent. * 3. Gather metrics by running `git log --stat` summary (lightweight, no * external test runner required for the baseline capture itself). * 4. Sign the payload via {@link loadSigningIdentity}. * 5. Write the signed `kind:"baseline"` event to the llmtxt/events log. * 6. Return a {@link CapturedBaseline} summary. * * @param projectRoot - Absolute path to the CLEO project root. * @param commitSha - The git commit SHA to anchor the baseline to. * Must be a 40-character hex SHA reachable from the repository. * @returns A fully signed baseline event record. * @throws `E_BASELINE_MUST_PREDATE_EXPERIMENT` if the commit is less than * {@link MIN_BASELINE_AGE_MS} ms old (anti-gaming guard). * @throws If the commit SHA does not exist in the git repository. * @throws If the KMS adapter cannot load the signing key. * * @example * ```ts * import { captureBaseline } from '@cleocode/core/sentient/baseline.js'; * * const baseline = await captureBaseline(projectRoot, 'abc123...'); * console.log('Baseline captured:', baseline.receiptId); * ``` */ export declare function captureBaseline(projectRoot: string, commitSha: string): Promise; //# sourceMappingURL=baseline.d.ts.map