@wildorder/nightshift 0.16.0 → 0.18.0

package/dist/run-analytics.js

@@ -0,0 +1,777 @@
+import { randomBytes } from "node:crypto";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { atomicWriteFile } from "./atomic-write.js";
+/**
+ * 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 const RUN_ANALYTICS_SCHEMA_VERSION = 1;
+/** The closed top-level attribution taxonomy — a new bucket is a plan change. */
+export const BUCKETS = [
+    "preflight",
+    "authoring",
+    "implementation",
+    "verification",
+    "review-and-decisions",
+    "recovery-and-fixes",
+    "git-and-persistence",
+    "whole-program-review",
+    "reporting",
+    "unattributed",
+];
+export const bucketSchema = z.enum(BUCKETS);
+/**
+ * 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 const STAGE_BUCKET = {
+    run: "unattributed",
+    "prerequisite-check": "preflight",
+    "baseline-verification": "preflight",
+    author: "authoring",
+    "re-author": "authoring",
+    "spec-critique": "authoring",
+    implementer: "implementation",
+    recovery: "implementation",
+    "informed-retry": "implementation",
+    "verification-command": "verification",
+    "test-critique": "review-and-decisions",
+    "decision-review": "review-and-decisions",
+    "finding-triage": "review-and-decisions",
+    "causal-analysis": "review-and-decisions",
+    "failure-diagnosis": "recovery-and-fixes",
+    "fix-now": "recovery-and-fixes",
+    "test-critique-fix": "recovery-and-fixes",
+    "manifest-persist": "git-and-persistence",
+    "ledger-persist": "git-and-persistence",
+    "analytics-persist": "git-and-persistence",
+    "git-diff": "git-and-persistence",
+    "git-commit": "git-and-persistence",
+    "worktree-setup": "git-and-persistence",
+    integration: "git-and-persistence",
+    "whole-program-review": "whole-program-review",
+    "as-built-snapshot": "whole-program-review",
+    "report-assembly": "reporting",
+    "report-commit": "reporting",
+};
+const STAGES = Object.keys(STAGE_BUCKET);
+export const stageSchema = z.enum(STAGES);
+/** The observability label every measurement carries; absent telemetry is `unavailable`, never a measured zero. */
+export const COVERAGE_VALUES = ["observed", "estimated", "unavailable", "incomplete"];
+export const coverageSchema = z.enum(COVERAGE_VALUES);
+/**
+ * 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 const KNOWN_OUTCOMES = [
+    "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 const SCHEDULING_POINT_KINDS = [
+    "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 const KNOWN_WAIT_CAUSES = [
+    "dependency",
+    "concurrency-cap",
+    "integration-mutex",
+    /**
+     * WS-05: a workstream whose dependencies had all integrated but whose own
+     * spec was still being authored. Measured on the build item, from the
+     * latest settle of any roster dependency's build item (or the scheduler's
+     * start, for a root workstream) to `workstream-ready`. Pre-`ready`, like
+     * `dependency`; distinguishes a run that was authoring-bound from one that
+     * was dependency-bound, which the critical path (WS-06) needs to tell
+     * apart.
+     */
+    "spec-pending",
+    /**
+     * WS-05: the authoring half of the shared `--max-parallel` budget,
+     * measured on the author item (admissible to launched) rather than the
+     * build item — the only wait cause that answers "did the cap delay the
+     * *spec*?" A root workstream can accrue this with no `concurrency-cap`
+     * point at all, since its build item may never even queue. Nests inside
+     * `spec-pending`, never summed with it (see the wait-cause table in
+     * `docs/run-analytics.md`).
+     */
+    "author-concurrency-cap",
+];
+/** The only evidence locality WS-01 defines: a build-logs reference resolves only on the machine that ran. */
+export const evidenceReferenceSchema = z.object({
+    kind: z.enum(["transcript", "ledger-event", "commit", "diagnosis"]),
+    locality: z.literal("local"),
+    ref: z.string(),
+    note: z.string().optional(),
+});
+const agentRoleSchema = z.enum([
+    "agent",
+    "recoveryAgent",
+    "authorAgent",
+    "deciderAgent",
+    "reviewerAgent",
+]);
+/** The stable facts attached to an interval or point. Provider/model identity is deliberately absent — WS-03's sole home. */
+export const dimensionsSchema = z.object({
+    stage: stageSchema,
+    workstream: z.string().optional(),
+    role: agentRoleSchema.optional(),
+    attemptSeat: z.string().optional(),
+    attemptIndex: z.number().optional(),
+    attemptReason: z.string().optional(),
+    verifyCommand: z.string().optional(),
+    outcome: z.string().optional(),
+    evidence: z.array(evidenceReferenceSchema).optional(),
+    /** Present only on a `workstream-waiting` point (open vocabulary; see {@link KNOWN_WAIT_CAUSES}). */
+    waitCause: z.string().optional(),
+});
+const partialDimensionsSchema = dimensionsSchema.partial();
+/**
+ * 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 const spanSchema = z
+    .object({
+    id: z.string(),
+    parentId: z.string().optional(),
+    stage: stageSchema,
+    bucket: bucketSchema,
+    startOffsetMs: z.number(),
+    /**
+     * Absent means this span's true end was not observed by finalize time.
+     * Usually that is a crashed/interrupted span, but the runner's own
+     * top-level `run` span and its `report-commit` child are open by design
+     * on every run, crashed or not: both close only after `finalize()` has
+     * already persisted this very artifact, so their real end can never be
+     * captured inside the file they are committed in.
+     */
+    endOffsetMs: z.number().optional(),
+    dimensions: dimensionsSchema,
+})
+    .refine((span) => STAGE_BUCKET[span.stage] === span.bucket, {
+    message: "bucket must equal STAGE_BUCKET[stage]",
+    path: ["bucket"],
+})
+    .refine((span) => span.endOffsetMs === undefined || span.endOffsetMs >= span.startOffsetMs, { message: "endOffsetMs must be >= startOffsetMs", path: ["endOffsetMs"] });
+/**
+ * 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 const pointObservationSchema = z.object({
+    id: z.string(),
+    atOffsetMs: z.number(),
+    kind: z.string(),
+    coverage: coverageSchema,
+    value: z.number().optional(),
+    unit: z.string().optional(),
+    label: z.string().optional(),
+    detail: z.string().optional(),
+    dimensions: partialDimensionsSchema.optional(),
+    evidence: z.array(evidenceReferenceSchema).optional(),
+});
+/**
+ * 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 const AGGREGATION_BOUNDARY = "run-start-to-pre-render-snapshot";
+export const runAnalyticsSchema = z
+    .object({
+    // A literal, not z.number(): SC-01 promises one validated versioned
+    // contract, so an artifact stamped with any other schemaVersion — an
+    // unsupported future format, a corrupted file, a stale format after a
+    // real bump — fails validation outright rather than silently parsing as
+    // if it were this version. readPriorRunId relies on exactly this to
+    // never adopt lineage from a schema it does not understand.
+    schemaVersion: z.literal(RUN_ANALYTICS_SCHEMA_VERSION),
+    identity: z.object({
+        runId: z.string(),
+        parentRunId: z.string().optional(),
+        programId: z.string(),
+    }),
+    anchors: z.object({
+        startedAt: z.string(),
+        monotonicAnchorMs: z.number(),
+        finalizedAt: z.string().optional(),
+        finalizedOffsetMs: z.number().optional(),
+    }),
+    aggregationBoundary: z.literal(AGGREGATION_BOUNDARY),
+    spans: z.array(spanSchema),
+    points: z.array(pointObservationSchema),
+})
+    .superRefine((artifact, ctx) => {
+    const ids = new Set(artifact.spans.map((span) => span.id));
+    artifact.spans.forEach((span, index) => {
+        if (span.parentId !== undefined && !ids.has(span.parentId)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `parentId "${span.parentId}" does not resolve to another span in this artifact`,
+                path: ["spans", index, "parentId"],
+            });
+        }
+    });
+    const spanById = new Map(artifact.spans.map((span) => [span.id, span]));
+    // Cycle detection over the raw `parentId` graph, deliberately independent
+    // of `dimensions.workstream`. A walk that only recurses while resolving
+    // *effective* ownership (below) stops at the first span in the chain
+    // that names its own workstream — so an a<->b cycle where both spans
+    // explicitly name the same workstream would never be walked far enough
+    // to be noticed (see WS-01 test-critique). This pass never looks at
+    // dimensions: it only asks whether following `parentId` from a span
+    // returns to a span already on the current path, and is memoized via
+    // `resolved` so no span's chain is walked more than once overall.
+    const cyclicSpanIds = new Set();
+    const resolved = new Set();
+    for (const span of artifact.spans) {
+        if (resolved.has(span.id))
+            continue;
+        const path = [];
+        let currentId = span.id;
+        while (currentId !== undefined && spanById.has(currentId) && !resolved.has(currentId)) {
+            const seenAt = path.indexOf(currentId);
+            if (seenAt !== -1) {
+                for (const id of path.slice(seenAt))
+                    cyclicSpanIds.add(id);
+                break;
+            }
+            path.push(currentId);
+            currentId = spanById.get(currentId)?.parentId;
+        }
+        for (const id of path)
+            resolved.add(id);
+    }
+    artifact.spans.forEach((span, index) => {
+        if (cyclicSpanIds.has(span.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `span "${span.id}" is part of a parentId cycle`,
+                path: ["spans", index, "parentId"],
+            });
+        }
+    });
+    // The effective-workstream rule (WS-01 §3.3, shared clause of SC-09): a
+    // span whose own `dimensions.workstream` is defined and whose nearest
+    // ancestor with a *defined* workstream names a *different* one is
+    // invalid — closed over an unattributed intermediary too, so a
+    // WS-01 → unattributed → WS-02 chain is rejected, not just a direct
+    // WS-01 → WS-02 one. Cycle safety is handled entirely by the pass above;
+    // any span not in `cyclicSpanIds` has a finite, acyclic parent chain, so
+    // this recursion always terminates.
+    const effectiveCache = new Map();
+    const effectiveWorkstreamOf = (id) => {
+        if (effectiveCache.has(id))
+            return effectiveCache.get(id);
+        if (cyclicSpanIds.has(id)) {
+            effectiveCache.set(id, undefined);
+            return undefined;
+        }
+        const span = spanById.get(id);
+        if (span === undefined)
+            return undefined;
+        if (span.dimensions.workstream !== undefined) {
+            effectiveCache.set(id, span.dimensions.workstream);
+            return span.dimensions.workstream;
+        }
+        if (span.parentId === undefined || !spanById.has(span.parentId)) {
+            effectiveCache.set(id, undefined);
+            return undefined;
+        }
+        const parentEffective = effectiveWorkstreamOf(span.parentId);
+        effectiveCache.set(id, parentEffective);
+        return parentEffective;
+    };
+    artifact.spans.forEach((span, index) => {
+        if (span.parentId === undefined || !ids.has(span.parentId) || cyclicSpanIds.has(span.id)) {
+            return;
+        }
+        const parentEffective = effectiveWorkstreamOf(span.parentId);
+        if (span.dimensions.workstream !== undefined &&
+            parentEffective !== undefined &&
+            parentEffective !== span.dimensions.workstream) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `span "${span.id}" (workstream "${span.dimensions.workstream}") is nested ` +
+                    `under a span whose effective workstream is "${parentEffective}"`,
+                path: ["spans", index, "dimensions", "workstream"],
+            });
+        }
+    });
+});
+/** Mirrors `runReportPath` — the one canonical location for a program's analytics artifact. */
+export function runAnalyticsPath(root, programId) {
+    return join(resolve(root), "docs", "programs", `${programId}-run-analytics.json`);
+}
+/** The gitignored crash-durability sidecar (see the incremental-durability decision); never read back by this module. */
+function runAnalyticsSidecarPath(root, programId) {
+    return join(resolve(root), "build-logs", programId, "run-analytics.jsonl");
+}
+function randomId() {
+    return randomBytes(8).toString("hex");
+}
+/**
+ * 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 async function readPriorRunId(root, programId) {
+    try {
+        const raw = await readFile(runAnalyticsPath(root, programId), "utf8");
+        const parsed = runAnalyticsSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data.identity.runId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 class RunRecorder {
+    runId;
+    /** `RunRecorder` is a degenerate, unscoped `SpanScope` — always `undefined`; see the interface doc comment. */
+    workstream = undefined;
+    clock;
+    root;
+    programId;
+    parentRunIdValue;
+    log;
+    monotonicAnchorMs;
+    startedAt;
+    permanentlyDisarmed;
+    armed = false;
+    finalized = false;
+    spans = [];
+    points = [];
+    openStack = [];
+    sidecarQueue = Promise.resolve();
+    // Metadata for every span ever opened (open or closed), keyed by id — the
+    // effective-workstream guard (§3.3) needs to walk a parent chain even
+    // after an ancestor has closed. `effectiveWorkstream` is computed and
+    // cached once, at open time, from the span's own dimensions and its
+    // resolved parent's stored value — a span's parent never changes after
+    // it is opened, so the cached value cannot go stale.
+    spanMeta = new Map();
+    constructor(opts) {
+        this.clock = opts.clock;
+        this.root = opts.root;
+        this.programId = opts.programId;
+        this.parentRunIdValue = opts.parentRunId;
+        this.log = opts.log;
+        this.permanentlyDisarmed = opts.permanentlyDisarmed ?? false;
+        this.startedAt = opts.clock.now().toISOString();
+        this.runId = this.startedAt;
+        this.monotonicAnchorMs = opts.clock.monotonic();
+    }
+    static create(opts) {
+        return new RunRecorder(opts);
+    }
+    /**
+     * 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() {
+        if (this.permanentlyDisarmed)
+            return;
+        this.armed = true;
+    }
+    /** Opens a span; the currently open span (if any) becomes its parent automatically. */
+    span(dims) {
+        return this.openSpan(dims, this.openStack[this.openStack.length - 1]?.id);
+    }
+    point(obs) {
+        try {
+            const point = {
+                id: randomId(),
+                atOffsetMs: this.elapsedMs(),
+                kind: obs.kind,
+                coverage: obs.coverage,
+                ...(obs.value === undefined ? {} : { value: obs.value }),
+                ...(obs.unit === undefined ? {} : { unit: obs.unit }),
+                ...(obs.label === undefined ? {} : { label: obs.label }),
+                ...(obs.detail === undefined ? {} : { detail: obs.detail }),
+                ...(obs.dimensions === undefined ? {} : { dimensions: obs.dimensions }),
+                ...(obs.evidence === undefined ? {} : { evidence: obs.evidence }),
+            };
+            const parsed = pointObservationSchema.safeParse(point);
+            if (!parsed.success) {
+                this.diagnose(`dropped malformed point observation: ${parsed.error.message}`);
+                return;
+            }
+            this.points.push(parsed.data);
+            this.appendSidecar({ kind: "point", point: parsed.data });
+        }
+        catch (error) {
+            this.diagnose(`point record failed: ${error.message}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    compose(finalizedAt, finalizedOffsetMs) {
+        return {
+            schemaVersion: RUN_ANALYTICS_SCHEMA_VERSION,
+            identity: {
+                runId: this.runId,
+                ...(this.parentRunIdValue === undefined ? {} : { parentRunId: this.parentRunIdValue }),
+                programId: this.programId,
+            },
+            anchors: {
+                startedAt: this.startedAt,
+                monotonicAnchorMs: this.monotonicAnchorMs,
+                finalizedAt,
+                finalizedOffsetMs,
+            },
+            aggregationBoundary: AGGREGATION_BOUNDARY,
+            spans: [...this.spans, ...this.openSpanSnapshots()],
+            points: this.points,
+        };
+    }
+    /**
+     * 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.
+     */
+    async finalize() {
+        if (!this.armed || this.finalized)
+            return;
+        this.finalized = true;
+        try {
+            await this.sidecarQueue.catch(() => undefined);
+            const artifact = this.compose(this.clock.now().toISOString(), this.elapsedMs());
+            const parsed = runAnalyticsSchema.safeParse(artifact);
+            if (!parsed.success) {
+                this.diagnose(`analytics artifact failed validation and was not written: ${parsed.error.message}`);
+                return;
+            }
+            await atomicWriteFile(runAnalyticsPath(this.root, this.programId), `${JSON.stringify(parsed.data, null, 2)}\n`, { tempDir: join(resolve(this.root), "build-logs", this.programId, "tmp") });
+        }
+        catch (error) {
+            this.diagnose(`analytics finalize failed: ${error.message}`);
+        }
+    }
+    /**
+     * 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() {
+        try {
+            const artifact = this.compose(this.clock.now().toISOString(), this.elapsedMs());
+            const parsed = runAnalyticsSchema.safeParse(artifact);
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    elapsedMs() {
+        return this.clock.monotonic() - this.monotonicAnchorMs;
+    }
+    /**
+     * 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.
+     */
+    resolveParent(requestedParentId, dims) {
+        let candidateId = requestedParentId;
+        let walked = false;
+        while (dims.workstream !== undefined && candidateId !== undefined) {
+            const meta = this.spanMeta.get(candidateId);
+            if (meta === undefined ||
+                meta.effectiveWorkstream === undefined ||
+                meta.effectiveWorkstream === dims.workstream) {
+                break;
+            }
+            walked = true;
+            candidateId = meta.parentId;
+        }
+        if (walked && requestedParentId !== undefined) {
+            const from = this.spanMeta.get(requestedParentId);
+            this.diagnose(`span "${dims.stage}" (workstream "${dims.workstream}") would have nested under ` +
+                `"${from?.stage}" (workstream "${from?.effectiveWorkstream}") by timing accident; ` +
+                `reparented to the nearest compatible ancestor. A concurrent call site likely ` +
+                "forgot SpanHandle.scope().");
+        }
+        return candidateId;
+    }
+    openSpan(dims, parentId) {
+        try {
+            const resolvedParentId = this.resolveParent(parentId, dims);
+            const id = randomId();
+            const effectiveWorkstream = dims.workstream ??
+                (resolvedParentId === undefined ? undefined : this.spanMeta.get(resolvedParentId)?.effectiveWorkstream);
+            this.spanMeta.set(id, { parentId: resolvedParentId, stage: dims.stage, effectiveWorkstream });
+            const open = {
+                id,
+                ...(resolvedParentId === undefined ? {} : { parentId: resolvedParentId }),
+                stage: dims.stage,
+                bucket: STAGE_BUCKET[dims.stage],
+                startOffsetMs: this.elapsedMs(),
+                dimensions: dims,
+            };
+            this.openStack.push(open);
+            let closed = false;
+            return {
+                close: (result) => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    this.closeSpan(open, result);
+                },
+                child: (childDims) => this.openSpan(childDims, open.id),
+                scope: (options) => this.makeScope(open.id, options?.workstream),
+            };
+        }
+        catch (error) {
+            this.diagnose(`span open failed: ${error.message}`);
+            return this.inertHandle();
+        }
+    }
+    inertHandle() {
+        return {
+            close: () => undefined,
+            child: () => this.inertHandle(),
+            scope: () => this.inertScope(),
+        };
+    }
+    /**
+     * 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.
+     */
+    makeScope(anchorSpanId, workstream) {
+        return {
+            workstream,
+            span: (dims) => {
+                const stamped = workstream !== undefined && dims.workstream === undefined
+                    ? { ...dims, workstream }
+                    : dims;
+                return this.openSpan(stamped, anchorSpanId);
+            },
+            point: (obs) => {
+                const stamped = workstream !== undefined && obs.dimensions?.workstream === undefined
+                    ? { ...obs, dimensions: { ...(obs.dimensions ?? {}), workstream } }
+                    : obs;
+                this.point(stamped);
+            },
+        };
+    }
+    inertScope() {
+        return {
+            workstream: undefined,
+            span: () => this.inertHandle(),
+            point: () => undefined,
+        };
+    }
+    closeSpan(open, result) {
+        try {
+            const dimensions = {
+                ...open.dimensions,
+                ...(result?.outcome === undefined ? {} : { outcome: result.outcome }),
+                ...(result?.evidence === undefined ? {} : { evidence: result.evidence }),
+            };
+            const span = {
+                id: open.id,
+                ...(open.parentId === undefined ? {} : { parentId: open.parentId }),
+                stage: open.stage,
+                bucket: open.bucket,
+                startOffsetMs: open.startOffsetMs,
+                endOffsetMs: this.elapsedMs(),
+                dimensions,
+            };
+            const parsed = spanSchema.safeParse(span);
+            if (!parsed.success) {
+                this.diagnose(`dropped malformed span: ${parsed.error.message}`);
+            }
+            else {
+                this.spans.push(parsed.data);
+                this.appendSidecar({ kind: "span", span: parsed.data });
+            }
+        }
+        catch (error) {
+            this.diagnose(`span close failed: ${error.message}`);
+        }
+        finally {
+            const index = this.openStack.indexOf(open);
+            if (index >= 0)
+                this.openStack.splice(index, 1);
+        }
+    }
+    openSpanSnapshots() {
+        return this.openStack.map((open) => ({
+            id: open.id,
+            ...(open.parentId === undefined ? {} : { parentId: open.parentId }),
+            stage: open.stage,
+            bucket: open.bucket,
+            startOffsetMs: open.startOffsetMs,
+            dimensions: open.dimensions,
+        }));
+    }
+    /**
+     * 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.
+     */
+    appendSidecar(entry) {
+        if (!this.armed)
+            return;
+        const path = runAnalyticsSidecarPath(this.root, this.programId);
+        const line = `${JSON.stringify(entry)}\n`;
+        this.sidecarQueue = this.sidecarQueue.then(async () => {
+            await mkdir(dirname(path), { recursive: true });
+            await appendFile(path, line, "utf8");
+        });
+        this.sidecarQueue = this.sidecarQueue.catch((error) => {
+            this.diagnose(`sidecar append failed: ${error.message}`);
+        });
+    }
+    diagnose(message) {
+        try {
+            this.log(`run-analytics: ${message}`);
+        }
+        catch {
+            // Logging must never be the reason an analytics failure escapes fail-open.
+        }
+    }
+}
+/**
+ * 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 const NOOP_RUN_RECORDER = RunRecorder.create({
+    clock: { now: () => new Date(0), monotonic: () => 0 },
+    root: "",
+    programId: "",
+    log: () => undefined,
+    permanentlyDisarmed: true,
+});
+/**
+ * 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 function recordWorkstreamReady(scope, workstream) {
+    scope.point({
+        kind: "workstream-ready",
+        coverage: "observed",
+        dimensions: { workstream },
+    });
+}
+/** Emitted once per workstream per run, the instant its flow actually launches. */
+export function recordWorkstreamScheduled(scope, workstream) {
+    scope.point({
+        kind: "workstream-scheduled",
+        coverage: "observed",
+        dimensions: { workstream },
+    });
+}
+/**
+ * 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 function recordWorkstreamWaiting(scope, workstream, wait) {
+    scope.point({
+        kind: "workstream-waiting",
+        coverage: "observed",
+        value: wait.waitedMs,
+        unit: "ms",
+        dimensions: { workstream, waitCause: wait.cause },
+    });
+}
+//# sourceMappingURL=run-analytics.js.map