@wildorder/nightshift 0.16.0 → 0.18.0

package/dist/run-analytics.d.ts

@@ -0,0 +1,844 @@
+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 "worktree-setup": "git-and-persistence";
+    readonly integration: "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";
+    "worktree-setup": "worktree-setup";
+    integration: "integration";
+    "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 fixed scheduling-observation vocabulary (WS-01 SC-10): a workstream
+ * becomes ready, is scheduled, or waits, and why. `workstream-ready` and
+ * `workstream-scheduled` are instants, emitted at most once per workstream
+ * per run; `workstream-waiting` is emitted once per (workstream, cause)
+ * pair, when the wait ends, carrying `value` = milliseconds waited. No
+ * emitter runs yet in this workstream — WS-04 is the first caller — but the
+ * vocabulary, the schema support, and the typed emitters below are final.
+ */
+export declare const SCHEDULING_POINT_KINDS: readonly ["workstream-ready", "workstream-scheduled", "workstream-waiting"];
+/** Open vocabulary, exactly like KNOWN_OUTCOMES: documentation and a lint
+ *  target, never a gate. A future wait cause is not a schema change. */
+export declare const KNOWN_WAIT_CAUSES: readonly ["dependency", "concurrency-cap", "integration-mutex", "spec-pending", "author-concurrency-cap"];
+/** 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";
+        "worktree-setup": "worktree-setup";
+        integration: "integration";
+        "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>>>;
+    waitCause: z.ZodOptional<z.ZodString>;
+}, 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";
+        "worktree-setup": "worktree-setup";
+        integration: "integration";
+        "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";
+            "worktree-setup": "worktree-setup";
+            integration: "integration";
+            "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>>>;
+        waitCause: z.ZodOptional<z.ZodString>;
+    }, 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";
+            "worktree-setup": "worktree-setup";
+            integration: "integration";
+            "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>>>>;
+        waitCause: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    }, 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";
+            "worktree-setup": "worktree-setup";
+            integration: "integration";
+            "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";
+                "worktree-setup": "worktree-setup";
+                integration: "integration";
+                "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>>>;
+            waitCause: z.ZodOptional<z.ZodString>;
+        }, 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";
+                "worktree-setup": "worktree-setup";
+                integration: "integration";
+                "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>>>>;
+            waitCause: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        }, 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;
+    /**
+     * A scope whose spans parent to this span — the explicit alternative to
+     * the implicit open-span stack. `options.workstream`, when given, is
+     * stamped onto every span/point this scope opens whose own dimensions
+     * omit `workstream`; a call site's explicit dimension is never
+     * overridden.
+     */
+    scope(options?: {
+        workstream?: string;
+    }): SpanScope;
+}
+/**
+ * A fixed parent span, plus an optional workstream to stamp. The explicit
+ * alternative to attaching a new span to whatever happens to be open on the
+ * recorder's implicit stack at that microsecond — which is correct only
+ * serially. `RunRecorder` itself is a valid (degenerate) `SpanScope`: its
+ * `span()` keeps the implicit-stack behaviour and its `workstream` is
+ * always `undefined`, so `NOOP_RUN_RECORDER` and every no-scope call site
+ * are unaffected.
+ */
+export interface SpanScope {
+    /** Opens a span parented to this scope's span — never to the open-span stack. */
+    span(dims: Dimensions): SpanHandle;
+    point(obs: PointObservationInput): void;
+    /** The workstream this scope attributes to, when it has one. */
+    readonly workstream: string | undefined;
+}
+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 implements SpanScope {
+    readonly runId: string;
+    /** `RunRecorder` is a degenerate, unscoped `SpanScope` — always `undefined`; see the interface doc comment. */
+    readonly workstream: string | undefined;
+    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 readonly spanMeta;
+    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;
+    /**
+     * Resolves the parent for a new span, explicit or implicit (§3.3). Starts
+     * from `requestedParentId` (a scope's own anchor span, or — for the
+     * implicit path — whatever is currently open on the stack). While the new
+     * span's `workstream` is defined, the candidate's *effective* workstream
+     * (walking through unattributed intermediaries) is defined, and the two
+     * differ, walks to the candidate's own parent. The first compatible
+     * ancestor is the parent; if the walk runs out, the span has none. A walk
+     * that actually moves the parent emits one diagnostic naming both stages
+     * and both workstreams.
+     */
+    private resolveParent;
+    private openSpan;
+    private inertHandle;
+    /**
+     * Builds a `SpanScope` anchored to `anchorSpanId` (a specific span's id,
+     * or `undefined` for the recorder's own top-level scope), stamping
+     * `workstream` onto every span/point it opens whose own dimensions omit
+     * it — never overriding a dimension the call site supplied.
+     */
+    private makeScope;
+    private inertScope;
+    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;
+/**
+ * Typed emitters for the scheduling-observation vocabulary (§3.4). They
+ * take the workstream id explicitly rather than reading it off `scope`: a
+ * workstream becomes ready, and waits, *before* its own flow scope exists —
+ * these are called from the run-level scope with the subject named. No
+ * emitter runs yet in this workstream; WS-04 is the first caller.
+ */
+/** Emitted once per workstream per run, the instant its dependencies are integrated, its spec is complete, and it is not blocked. */
+export declare function recordWorkstreamReady(scope: SpanScope, workstream: string): void;
+/** Emitted once per workstream per run, the instant its flow actually launches. */
+export declare function recordWorkstreamScheduled(scope: SpanScope, workstream: string): void;
+/**
+ * Emitted when a wait *ends*, once per (workstream, cause) pair —
+ * `wait.waitedMs` is the milliseconds spent waiting on that cause. A
+ * workstream that waited on two causes emits two points; their sum should
+ * approximate `scheduled − ready`.
+ */
+export declare function recordWorkstreamWaiting(scope: SpanScope, workstream: string, wait: {
+    cause: string;
+    waitedMs: number;
+}): void;
+//# sourceMappingURL=run-analytics.d.ts.map