@wildorder/nightshift 0.15.0 → 0.17.0

package/dist/run-analytics.d.ts

@@ -0,0 +1,738 @@
+import { z } from "zod";
+/**
+ * The versioned, provider-neutral run-observation contract (WS-01). This
+ * module defines the schema, the stage-to-bucket mapping, the injectable
+ * clock, the recorder, and the atomic persistence boundary — it emits no
+ * per-stage spans of its own beyond a handful of reference spans proving the
+ * API end-to-end (see the WS-01/WS-02 emission-boundary decision). WS-02
+ * instruments the full run lifecycle against this contract; WS-03 attaches
+ * provider/prompt facts; WS-04 aggregates; WS-05 interprets.
+ */
+/** Bumped only when the shape of the finalized artifact changes incompatibly. */
+export declare const RUN_ANALYTICS_SCHEMA_VERSION = 1;
+/** The closed top-level attribution taxonomy — a new bucket is a plan change. */
+export declare const BUCKETS: readonly ["preflight", "authoring", "implementation", "verification", "review-and-decisions", "recovery-and-fixes", "git-and-persistence", "whole-program-review", "reporting", "unattributed"];
+export declare const bucketSchema: z.ZodEnum<{
+    preflight: "preflight";
+    authoring: "authoring";
+    implementation: "implementation";
+    verification: "verification";
+    "review-and-decisions": "review-and-decisions";
+    "recovery-and-fixes": "recovery-and-fixes";
+    "git-and-persistence": "git-and-persistence";
+    "whole-program-review": "whole-program-review";
+    reporting: "reporting";
+    unattributed: "unattributed";
+}>;
+export type Bucket = z.infer<typeof bucketSchema>;
+/**
+ * The closed set of concrete operations, each mapping to exactly one bucket.
+ * WS-02 emits stages; WS-04 reads buckets; both import this exact table so
+ * they cannot drift ("same stage, different bucket" is closed by
+ * construction). Bar one exception, there is no `unattributed` stage:
+ * `unattributed` is normally a residual WS-04 computes as elapsed time minus
+ * the union of known top-level spans, never emitted by an instrumentation
+ * site. The exception is `"run"` itself (below) — a single, WS-01-owned span
+ * opened once per run, never an ad hoc WS-02 filler, whose entire purpose is
+ * to prove full temporal coverage from run start onward by parenting every
+ * other span; once WS-04 subtracts the union of its children, what remains
+ * of its own duration is, by construction, exactly the residual its bucket
+ * already names.
+ */
+export declare const STAGE_BUCKET: {
+    readonly run: "unattributed";
+    readonly "prerequisite-check": "preflight";
+    readonly "baseline-verification": "preflight";
+    readonly author: "authoring";
+    readonly "re-author": "authoring";
+    readonly "spec-critique": "authoring";
+    readonly implementer: "implementation";
+    readonly recovery: "implementation";
+    readonly "informed-retry": "implementation";
+    readonly "verification-command": "verification";
+    readonly "test-critique": "review-and-decisions";
+    readonly "decision-review": "review-and-decisions";
+    readonly "finding-triage": "review-and-decisions";
+    readonly "causal-analysis": "review-and-decisions";
+    readonly "failure-diagnosis": "recovery-and-fixes";
+    readonly "fix-now": "recovery-and-fixes";
+    readonly "test-critique-fix": "recovery-and-fixes";
+    readonly "manifest-persist": "git-and-persistence";
+    readonly "ledger-persist": "git-and-persistence";
+    readonly "analytics-persist": "git-and-persistence";
+    readonly "git-diff": "git-and-persistence";
+    readonly "git-commit": "git-and-persistence";
+    readonly "whole-program-review": "whole-program-review";
+    readonly "as-built-snapshot": "whole-program-review";
+    readonly "report-assembly": "reporting";
+    readonly "report-commit": "reporting";
+};
+export type Stage = keyof typeof STAGE_BUCKET;
+export declare const stageSchema: z.ZodEnum<{
+    "whole-program-review": "whole-program-review";
+    run: "run";
+    "prerequisite-check": "prerequisite-check";
+    "baseline-verification": "baseline-verification";
+    author: "author";
+    "re-author": "re-author";
+    "spec-critique": "spec-critique";
+    implementer: "implementer";
+    recovery: "recovery";
+    "informed-retry": "informed-retry";
+    "verification-command": "verification-command";
+    "test-critique": "test-critique";
+    "decision-review": "decision-review";
+    "finding-triage": "finding-triage";
+    "causal-analysis": "causal-analysis";
+    "failure-diagnosis": "failure-diagnosis";
+    "fix-now": "fix-now";
+    "test-critique-fix": "test-critique-fix";
+    "manifest-persist": "manifest-persist";
+    "ledger-persist": "ledger-persist";
+    "analytics-persist": "analytics-persist";
+    "git-diff": "git-diff";
+    "git-commit": "git-commit";
+    "as-built-snapshot": "as-built-snapshot";
+    "report-assembly": "report-assembly";
+    "report-commit": "report-commit";
+}>;
+/** The observability label every measurement carries; absent telemetry is `unavailable`, never a measured zero. */
+export declare const COVERAGE_VALUES: readonly ["observed", "estimated", "unavailable", "incomplete"];
+export declare const coverageSchema: z.ZodEnum<{
+    observed: "observed";
+    estimated: "estimated";
+    unavailable: "unavailable";
+    incomplete: "incomplete";
+}>;
+export type Coverage = z.infer<typeof coverageSchema>;
+/**
+ * Documented, non-exhaustive outcome vocabulary (SC-04): `outcome` is an open
+ * `z.string()` so a future outcome (e.g. a timeout) can be added without a
+ * schema version bump. This is documentation and a lint target, never a gate
+ * — an unknown outcome string still validates and round-trips.
+ */
+export declare const KNOWN_OUTCOMES: readonly ["success", "failed", "discarded", "no-op", "skipped", "interrupted"];
+/** The only evidence locality WS-01 defines: a build-logs reference resolves only on the machine that ran. */
+export declare const evidenceReferenceSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        transcript: "transcript";
+        "ledger-event": "ledger-event";
+        commit: "commit";
+        diagnosis: "diagnosis";
+    }>;
+    locality: z.ZodLiteral<"local">;
+    ref: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EvidenceReference = z.infer<typeof evidenceReferenceSchema>;
+/** The stable facts attached to an interval or point. Provider/model identity is deliberately absent — WS-03's sole home. */
+export declare const dimensionsSchema: z.ZodObject<{
+    stage: z.ZodEnum<{
+        "whole-program-review": "whole-program-review";
+        run: "run";
+        "prerequisite-check": "prerequisite-check";
+        "baseline-verification": "baseline-verification";
+        author: "author";
+        "re-author": "re-author";
+        "spec-critique": "spec-critique";
+        implementer: "implementer";
+        recovery: "recovery";
+        "informed-retry": "informed-retry";
+        "verification-command": "verification-command";
+        "test-critique": "test-critique";
+        "decision-review": "decision-review";
+        "finding-triage": "finding-triage";
+        "causal-analysis": "causal-analysis";
+        "failure-diagnosis": "failure-diagnosis";
+        "fix-now": "fix-now";
+        "test-critique-fix": "test-critique-fix";
+        "manifest-persist": "manifest-persist";
+        "ledger-persist": "ledger-persist";
+        "analytics-persist": "analytics-persist";
+        "git-diff": "git-diff";
+        "git-commit": "git-commit";
+        "as-built-snapshot": "as-built-snapshot";
+        "report-assembly": "report-assembly";
+        "report-commit": "report-commit";
+    }>;
+    workstream: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        authorAgent: "authorAgent";
+        deciderAgent: "deciderAgent";
+        reviewerAgent: "reviewerAgent";
+        recoveryAgent: "recoveryAgent";
+    }>>;
+    attemptSeat: z.ZodOptional<z.ZodString>;
+    attemptIndex: z.ZodOptional<z.ZodNumber>;
+    attemptReason: z.ZodOptional<z.ZodString>;
+    verifyCommand: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            transcript: "transcript";
+            "ledger-event": "ledger-event";
+            commit: "commit";
+            diagnosis: "diagnosis";
+        }>;
+        locality: z.ZodLiteral<"local">;
+        ref: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Dimensions = z.infer<typeof dimensionsSchema>;
+/**
+ * An interval observation — the unit that carries wall-clock time. The
+ * schema permits overlapping spans (a parent and its children overlap by
+ * construction); WS-01 validates only the local invariants (bucket matches
+ * stage, end >= start when present, parentId resolves within the artifact).
+ * WS-04 owns interval-union conservation and rejecting double-counted
+ * overlaps at the top level.
+ */
+export declare const spanSchema: z.ZodObject<{
+    id: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+    stage: z.ZodEnum<{
+        "whole-program-review": "whole-program-review";
+        run: "run";
+        "prerequisite-check": "prerequisite-check";
+        "baseline-verification": "baseline-verification";
+        author: "author";
+        "re-author": "re-author";
+        "spec-critique": "spec-critique";
+        implementer: "implementer";
+        recovery: "recovery";
+        "informed-retry": "informed-retry";
+        "verification-command": "verification-command";
+        "test-critique": "test-critique";
+        "decision-review": "decision-review";
+        "finding-triage": "finding-triage";
+        "causal-analysis": "causal-analysis";
+        "failure-diagnosis": "failure-diagnosis";
+        "fix-now": "fix-now";
+        "test-critique-fix": "test-critique-fix";
+        "manifest-persist": "manifest-persist";
+        "ledger-persist": "ledger-persist";
+        "analytics-persist": "analytics-persist";
+        "git-diff": "git-diff";
+        "git-commit": "git-commit";
+        "as-built-snapshot": "as-built-snapshot";
+        "report-assembly": "report-assembly";
+        "report-commit": "report-commit";
+    }>;
+    bucket: z.ZodEnum<{
+        preflight: "preflight";
+        authoring: "authoring";
+        implementation: "implementation";
+        verification: "verification";
+        "review-and-decisions": "review-and-decisions";
+        "recovery-and-fixes": "recovery-and-fixes";
+        "git-and-persistence": "git-and-persistence";
+        "whole-program-review": "whole-program-review";
+        reporting: "reporting";
+        unattributed: "unattributed";
+    }>;
+    startOffsetMs: z.ZodNumber;
+    endOffsetMs: z.ZodOptional<z.ZodNumber>;
+    dimensions: z.ZodObject<{
+        stage: z.ZodEnum<{
+            "whole-program-review": "whole-program-review";
+            run: "run";
+            "prerequisite-check": "prerequisite-check";
+            "baseline-verification": "baseline-verification";
+            author: "author";
+            "re-author": "re-author";
+            "spec-critique": "spec-critique";
+            implementer: "implementer";
+            recovery: "recovery";
+            "informed-retry": "informed-retry";
+            "verification-command": "verification-command";
+            "test-critique": "test-critique";
+            "decision-review": "decision-review";
+            "finding-triage": "finding-triage";
+            "causal-analysis": "causal-analysis";
+            "failure-diagnosis": "failure-diagnosis";
+            "fix-now": "fix-now";
+            "test-critique-fix": "test-critique-fix";
+            "manifest-persist": "manifest-persist";
+            "ledger-persist": "ledger-persist";
+            "analytics-persist": "analytics-persist";
+            "git-diff": "git-diff";
+            "git-commit": "git-commit";
+            "as-built-snapshot": "as-built-snapshot";
+            "report-assembly": "report-assembly";
+            "report-commit": "report-commit";
+        }>;
+        workstream: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            agent: "agent";
+            authorAgent: "authorAgent";
+            deciderAgent: "deciderAgent";
+            reviewerAgent: "reviewerAgent";
+            recoveryAgent: "recoveryAgent";
+        }>>;
+        attemptSeat: z.ZodOptional<z.ZodString>;
+        attemptIndex: z.ZodOptional<z.ZodNumber>;
+        attemptReason: z.ZodOptional<z.ZodString>;
+        verifyCommand: z.ZodOptional<z.ZodString>;
+        outcome: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                transcript: "transcript";
+                "ledger-event": "ledger-event";
+                commit: "commit";
+                diagnosis: "diagnosis";
+            }>;
+            locality: z.ZodLiteral<"local">;
+            ref: z.ZodString;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Span = z.infer<typeof spanSchema>;
+/**
+ * A fact measured at an instant, not an interval. `kind` is an open string
+ * for the same forward-compatibility reason as `outcome`.
+ *
+ * `label` and `detail` are WS-03's sole, additive amendment to this schema
+ * (see the `scalar-points-plus-additive-fields` decision): `label` names the
+ * specific metric or prompt component a point measures (e.g.
+ * `"input-tokens"`, `"model"`, `"roster"`), and `detail` carries a
+ * string-valued fact — an exact model identity, a provider label, a
+ * comma-joined demoted-dependency id list — when the measurement is not
+ * numeric. Both are optional and unconstrained by an enum, so every existing
+ * point (and every WS-01 fixture) round-trips unchanged.
+ */
+export declare const pointObservationSchema: z.ZodObject<{
+    id: z.ZodString;
+    atOffsetMs: z.ZodNumber;
+    kind: z.ZodString;
+    coverage: z.ZodEnum<{
+        observed: "observed";
+        estimated: "estimated";
+        unavailable: "unavailable";
+        incomplete: "incomplete";
+    }>;
+    value: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    dimensions: z.ZodOptional<z.ZodObject<{
+        stage: z.ZodOptional<z.ZodEnum<{
+            "whole-program-review": "whole-program-review";
+            run: "run";
+            "prerequisite-check": "prerequisite-check";
+            "baseline-verification": "baseline-verification";
+            author: "author";
+            "re-author": "re-author";
+            "spec-critique": "spec-critique";
+            implementer: "implementer";
+            recovery: "recovery";
+            "informed-retry": "informed-retry";
+            "verification-command": "verification-command";
+            "test-critique": "test-critique";
+            "decision-review": "decision-review";
+            "finding-triage": "finding-triage";
+            "causal-analysis": "causal-analysis";
+            "failure-diagnosis": "failure-diagnosis";
+            "fix-now": "fix-now";
+            "test-critique-fix": "test-critique-fix";
+            "manifest-persist": "manifest-persist";
+            "ledger-persist": "ledger-persist";
+            "analytics-persist": "analytics-persist";
+            "git-diff": "git-diff";
+            "git-commit": "git-commit";
+            "as-built-snapshot": "as-built-snapshot";
+            "report-assembly": "report-assembly";
+            "report-commit": "report-commit";
+        }>>;
+        workstream: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        role: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+            agent: "agent";
+            authorAgent: "authorAgent";
+            deciderAgent: "deciderAgent";
+            reviewerAgent: "reviewerAgent";
+            recoveryAgent: "recoveryAgent";
+        }>>>;
+        attemptSeat: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        attemptIndex: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        attemptReason: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        verifyCommand: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        outcome: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        evidence: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                transcript: "transcript";
+                "ledger-event": "ledger-event";
+                commit: "commit";
+                diagnosis: "diagnosis";
+            }>;
+            locality: z.ZodLiteral<"local">;
+            ref: z.ZodString;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            transcript: "transcript";
+            "ledger-event": "ledger-event";
+            commit: "commit";
+            diagnosis: "diagnosis";
+        }>;
+        locality: z.ZodLiteral<"local">;
+        ref: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PointObservation = z.infer<typeof pointObservationSchema>;
+/**
+ * States the window the reconciled numbers cover: run start through the
+ * pre-render analytics snapshot taken just before `finalize()` persists this
+ * artifact and the report is written and committed (SC-03, SC-14). The
+ * report-write/commit tail is unobservable from inside the artifact — the
+ * `run` and `report-commit` spans stay open and the tail lands as a sidecar
+ * point — and publish runs after the CLI's run call returns. Adopted by
+ * human ruling (decisions 062f9cc308fe22fa, 987817d69c457259).
+ */
+export declare const AGGREGATION_BOUNDARY: "run-start-to-pre-render-snapshot";
+export declare const runAnalyticsSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    identity: z.ZodObject<{
+        runId: z.ZodString;
+        parentRunId: z.ZodOptional<z.ZodString>;
+        programId: z.ZodString;
+    }, z.core.$strip>;
+    anchors: z.ZodObject<{
+        startedAt: z.ZodString;
+        monotonicAnchorMs: z.ZodNumber;
+        finalizedAt: z.ZodOptional<z.ZodString>;
+        finalizedOffsetMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    aggregationBoundary: z.ZodLiteral<"run-start-to-pre-render-snapshot">;
+    spans: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodOptional<z.ZodString>;
+        stage: z.ZodEnum<{
+            "whole-program-review": "whole-program-review";
+            run: "run";
+            "prerequisite-check": "prerequisite-check";
+            "baseline-verification": "baseline-verification";
+            author: "author";
+            "re-author": "re-author";
+            "spec-critique": "spec-critique";
+            implementer: "implementer";
+            recovery: "recovery";
+            "informed-retry": "informed-retry";
+            "verification-command": "verification-command";
+            "test-critique": "test-critique";
+            "decision-review": "decision-review";
+            "finding-triage": "finding-triage";
+            "causal-analysis": "causal-analysis";
+            "failure-diagnosis": "failure-diagnosis";
+            "fix-now": "fix-now";
+            "test-critique-fix": "test-critique-fix";
+            "manifest-persist": "manifest-persist";
+            "ledger-persist": "ledger-persist";
+            "analytics-persist": "analytics-persist";
+            "git-diff": "git-diff";
+            "git-commit": "git-commit";
+            "as-built-snapshot": "as-built-snapshot";
+            "report-assembly": "report-assembly";
+            "report-commit": "report-commit";
+        }>;
+        bucket: z.ZodEnum<{
+            preflight: "preflight";
+            authoring: "authoring";
+            implementation: "implementation";
+            verification: "verification";
+            "review-and-decisions": "review-and-decisions";
+            "recovery-and-fixes": "recovery-and-fixes";
+            "git-and-persistence": "git-and-persistence";
+            "whole-program-review": "whole-program-review";
+            reporting: "reporting";
+            unattributed: "unattributed";
+        }>;
+        startOffsetMs: z.ZodNumber;
+        endOffsetMs: z.ZodOptional<z.ZodNumber>;
+        dimensions: z.ZodObject<{
+            stage: z.ZodEnum<{
+                "whole-program-review": "whole-program-review";
+                run: "run";
+                "prerequisite-check": "prerequisite-check";
+                "baseline-verification": "baseline-verification";
+                author: "author";
+                "re-author": "re-author";
+                "spec-critique": "spec-critique";
+                implementer: "implementer";
+                recovery: "recovery";
+                "informed-retry": "informed-retry";
+                "verification-command": "verification-command";
+                "test-critique": "test-critique";
+                "decision-review": "decision-review";
+                "finding-triage": "finding-triage";
+                "causal-analysis": "causal-analysis";
+                "failure-diagnosis": "failure-diagnosis";
+                "fix-now": "fix-now";
+                "test-critique-fix": "test-critique-fix";
+                "manifest-persist": "manifest-persist";
+                "ledger-persist": "ledger-persist";
+                "analytics-persist": "analytics-persist";
+                "git-diff": "git-diff";
+                "git-commit": "git-commit";
+                "as-built-snapshot": "as-built-snapshot";
+                "report-assembly": "report-assembly";
+                "report-commit": "report-commit";
+            }>;
+            workstream: z.ZodOptional<z.ZodString>;
+            role: z.ZodOptional<z.ZodEnum<{
+                agent: "agent";
+                authorAgent: "authorAgent";
+                deciderAgent: "deciderAgent";
+                reviewerAgent: "reviewerAgent";
+                recoveryAgent: "recoveryAgent";
+            }>>;
+            attemptSeat: z.ZodOptional<z.ZodString>;
+            attemptIndex: z.ZodOptional<z.ZodNumber>;
+            attemptReason: z.ZodOptional<z.ZodString>;
+            verifyCommand: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
+            evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    transcript: "transcript";
+                    "ledger-event": "ledger-event";
+                    commit: "commit";
+                    diagnosis: "diagnosis";
+                }>;
+                locality: z.ZodLiteral<"local">;
+                ref: z.ZodString;
+                note: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    points: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        atOffsetMs: z.ZodNumber;
+        kind: z.ZodString;
+        coverage: z.ZodEnum<{
+            observed: "observed";
+            estimated: "estimated";
+            unavailable: "unavailable";
+            incomplete: "incomplete";
+        }>;
+        value: z.ZodOptional<z.ZodNumber>;
+        unit: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        dimensions: z.ZodOptional<z.ZodObject<{
+            stage: z.ZodOptional<z.ZodEnum<{
+                "whole-program-review": "whole-program-review";
+                run: "run";
+                "prerequisite-check": "prerequisite-check";
+                "baseline-verification": "baseline-verification";
+                author: "author";
+                "re-author": "re-author";
+                "spec-critique": "spec-critique";
+                implementer: "implementer";
+                recovery: "recovery";
+                "informed-retry": "informed-retry";
+                "verification-command": "verification-command";
+                "test-critique": "test-critique";
+                "decision-review": "decision-review";
+                "finding-triage": "finding-triage";
+                "causal-analysis": "causal-analysis";
+                "failure-diagnosis": "failure-diagnosis";
+                "fix-now": "fix-now";
+                "test-critique-fix": "test-critique-fix";
+                "manifest-persist": "manifest-persist";
+                "ledger-persist": "ledger-persist";
+                "analytics-persist": "analytics-persist";
+                "git-diff": "git-diff";
+                "git-commit": "git-commit";
+                "as-built-snapshot": "as-built-snapshot";
+                "report-assembly": "report-assembly";
+                "report-commit": "report-commit";
+            }>>;
+            workstream: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            role: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+                agent: "agent";
+                authorAgent: "authorAgent";
+                deciderAgent: "deciderAgent";
+                reviewerAgent: "reviewerAgent";
+                recoveryAgent: "recoveryAgent";
+            }>>>;
+            attemptSeat: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            attemptIndex: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+            attemptReason: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            verifyCommand: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            outcome: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            evidence: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    transcript: "transcript";
+                    "ledger-event": "ledger-event";
+                    commit: "commit";
+                    diagnosis: "diagnosis";
+                }>;
+                locality: z.ZodLiteral<"local">;
+                ref: z.ZodString;
+                note: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>>;
+        }, z.core.$strip>>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                transcript: "transcript";
+                "ledger-event": "ledger-event";
+                commit: "commit";
+                diagnosis: "diagnosis";
+            }>;
+            locality: z.ZodLiteral<"local">;
+            ref: z.ZodString;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RunAnalytics = z.infer<typeof runAnalyticsSchema>;
+/** Mirrors `runReportPath` — the one canonical location for a program's analytics artifact. */
+export declare function runAnalyticsPath(root: string, programId: string): string;
+/**
+ * Reads any prior finalized artifact for `programId` purely to source
+ * `parentRunId` — a plain read with no durable effect, safe before the
+ * could-not-start gate. Absent, unreadable, or invalid prior artifacts all
+ * resolve to `undefined` (fail open): a missing lineage is not a reason to
+ * fail a run.
+ */
+export declare function readPriorRunId(root: string, programId: string): Promise<string | undefined>;
+/**
+ * Wall time (`now`) anchors the artifact to a human timeline; monotonic time
+ * drives every span offset, because wall-clock is not monotonic and an NTP
+ * step mid-run must never make a span appear negative-length.
+ */
+export interface RunClock {
+    now(): Date;
+    monotonic(): number;
+}
+export interface SpanHandle {
+    close(result?: {
+        outcome?: string;
+        evidence?: EvidenceReference[];
+    }): void;
+    /** Explicit nesting when the implicit open-span stack doesn't fit (e.g. a span opened and closed across an `await` boundary). */
+    child(dims: Dimensions): SpanHandle;
+}
+export interface PointObservationInput {
+    kind: string;
+    coverage: Coverage;
+    value?: number;
+    unit?: string;
+    label?: string;
+    detail?: string;
+    dimensions?: Partial<Dimensions>;
+    evidence?: EvidenceReference[];
+}
+export interface RunRecorderCreateOptions {
+    clock: RunClock;
+    root: string;
+    programId: string;
+    parentRunId?: string;
+    log: (line: string) => void;
+    /**
+     * Set only by {@link NOOP_RUN_RECORDER}'s own construction (WS-02): makes
+     * `arm()` a permanent no-op, so a caller that injects the shared singleton
+     * as a test seam (`RunProgramOptions.recorder`) can never accidentally arm
+     * — and thereby make durably writing — the one shared instance every other
+     * caller with no run-scoped recorder also relies on staying inert.
+     */
+    permanentlyDisarmed?: boolean;
+}
+/**
+ * Records a run's spans and point observations and persists them
+ * fail-open. Created at run start so pre-gate stages (preflight, baseline
+ * verification) can be buffered in memory; stays disarmed — writing nothing
+ * durable — until `arm()` is called immediately after the could-not-start
+ * gate. Every method is non-throwing: a malformed observation is diagnosed
+ * and dropped, a persistence failure is diagnosed and swallowed, and nothing
+ * here can change a run's outcome, exit code, status, or report.
+ */
+export declare class RunRecorder {
+    readonly runId: string;
+    private readonly clock;
+    private readonly root;
+    private readonly programId;
+    private readonly parentRunIdValue;
+    private readonly log;
+    private readonly monotonicAnchorMs;
+    private readonly startedAt;
+    private readonly permanentlyDisarmed;
+    private armed;
+    private finalized;
+    private readonly spans;
+    private readonly points;
+    private readonly openStack;
+    private sidecarQueue;
+    private constructor();
+    static create(opts: RunRecorderCreateOptions): RunRecorder;
+    /**
+     * Enables durable writes. Idempotent; intended to be called once,
+     * immediately after the could-not-start gate. A no-op on a
+     * permanently-disarmed instance ({@link NOOP_RUN_RECORDER}) — WS-02's
+     * `RunProgramOptions.recorder` test seam lets a caller inject that shared
+     * singleton straight into a real run, and `runProgramWith` calls `arm()`
+     * unconditionally on whatever recorder it holds, so this guard is what
+     * keeps that injection from durably arming — and thereby writing through
+     * — the one instance every other no-recorder caller also depends on
+     * staying inert.
+     */
+    arm(): void;
+    /** Opens a span; the currently open span (if any) becomes its parent automatically. */
+    span(dims: Dimensions): SpanHandle;
+    point(obs: PointObservationInput): void;
+    /**
+     * Builds the in-memory buffer (including any span still open — a
+     * crashed/interrupted span composes with no `endOffsetMs`) into a
+     * `RunAnalytics` shape at the given wall/monotonic instant. Shared by
+     * `finalize()` (which persists the result) and `snapshot()` (which does
+     * not), so the two can never independently drift on what "the observed
+     * artifact so far" means.
+     */
+    private compose;
+    /**
+     * Composes the in-memory buffer into a `RunAnalytics` object, validates
+     * it, and atomically persists it. Fail-open: never throws. A no-op when
+     * not armed, or when already finalized once.
+     */
+    finalize(): Promise<void>;
+    /**
+     * A validated in-memory view of everything observed so far, for the run
+     * report's "Where the time went" section (WS-04) — which renders before
+     * `finalize()` runs, so it cannot read the file `finalize()` writes.
+     * Read-only: composes and validates exactly as `finalize()` does but
+     * writes nothing, to the canonical artifact or the sidecar, and is safe to
+     * call before `arm()`, after `finalize()`, or any number of times.
+     * Non-throwing; returns `undefined` on any failure (fail open).
+     */
+    snapshot(): RunAnalytics | undefined;
+    private elapsedMs;
+    private openSpan;
+    private inertHandle;
+    private closeSpan;
+    private openSpanSnapshots;
+    /**
+     * Appends one JSON line to the gitignored `build-logs/` sidecar — the
+     * crash-durability layer for a hard kill that never reaches the flush
+     * seam. Queued so concurrent closes/points never interleave partial
+     * writes; a failing append is diagnosed and never breaks the queue for
+     * subsequent appends.
+     */
+    private appendSidecar;
+    private diagnose;
+}
+/**
+ * A shared, permanently disarmed recorder — the default for callers that
+ * have no run-scoped recorder to hand (a standalone test, the doctor probe,
+ * a fix/critique path WS-02 has not yet wired), and a valid injection
+ * straight into `RunProgramOptions.recorder` (WS-02, SC-13) for a test that
+ * wants to prove fail-open by equivalence. Buffers harmlessly in memory and
+ * never performs I/O: `permanentlyDisarmed` makes `arm()` a no-op even when
+ * a real run calls it unconditionally, so this one shared instance can never
+ * be armed by any caller, ever.
+ */
+export declare const NOOP_RUN_RECORDER: RunRecorder;
+//# sourceMappingURL=run-analytics.d.ts.map