@wildorder/nightshift 0.16.0 → 0.17.0

package/dist/causal-analysis.d.ts

@@ -0,0 +1,212 @@
+import { type AgentRunner } from "./agent-runner.js";
+import type { NightshiftConfig } from "./config.js";
+import type { DecisionLedgerView } from "./decision-ledger.js";
+import type { ProgramManifest } from "./manifest.js";
+import { type PermitsContext } from "./permits.js";
+import { type PromptComponentSize } from "./prompt-telemetry.js";
+import { type RunAnalytics, type RunRecorder } from "./run-analytics.js";
+import { aggregateRunAnalytics, type RunAnalyticsSummary } from "./run-analytics-report.js";
+export interface WorkstreamTimelineEntry {
+    id: string;
+    name: string;
+    /** The caller's own outcome-status vocabulary, verbatim. */
+    status: string;
+    reason?: string;
+    failureDiagnoses?: ReadonlyArray<{
+        attempt: string;
+        verdict: string;
+    }>;
+    testCritique?: {
+        stopReason: string;
+        roundsRun: number;
+        openSubjects: readonly string[];
+        resolvedSubjects: readonly string[];
+    };
+}
+/**
+ * One workstream's actual spec-file content, as read by the caller from
+ * `taskFile` (SC-12: the analyzer must consume the specifications
+ * themselves, not merely a path to them). `spec` is `undefined` when the
+ * file could not be read — an honest per-workstream gap, never a thrown run
+ * (fail-open, SC-13).
+ */
+export interface WorkstreamSpecInput {
+    id: string;
+    name: string;
+    taskFile: string;
+    spec?: string;
+}
+/** Combines every workstream's spec content into one labelled block, ready for the caller to clip like the diff and program narrative. Pure. */
+export declare function combineWorkstreamSpecs(specs: readonly WorkstreamSpecInput[]): string;
+export type HandleKind = "span" | "point" | "evidence" | "ledger-event" | "bucket" | "workstream" | "verify-command";
+export interface HandleEntry {
+    kind: HandleKind;
+    /** A duration, a count, a coverage label, a ledger claim — resolved from the snapshot/summary/ledger, never authored by a model. */
+    value: string;
+}
+/** span, point, evidence, and ledger-event handles are concrete observations; bucket/workstream/verify-command are category labels — context, never support on their own (D2). */
+export declare function isConcreteHandleKind(kind: HandleKind): boolean;
+export type HandleRegistry = ReadonlyMap<string, HandleEntry>;
+/**
+ * Builds the citable-handle registry from what this run actually observed
+ * (D2): every span and point id in `snapshot`, every `EvidenceReference.ref`
+ * carried on them, every ledger event id, and — only when the run actually
+ * has a span under them — bucket, workstream, and verify-command category
+ * labels sourced from `summary`'s own already-observed groupings. Pure,
+ * deterministic; never a static vocabulary dump.
+ */
+export declare function buildHandleRegistry(snapshot: RunAnalytics, summary: RunAnalyticsSummary, ledger: DecisionLedgerView): HandleRegistry;
+export interface CausalStep {
+    claim: string;
+    cites: string[];
+    from?: string;
+    to?: string;
+}
+export interface PlanningConstraint {
+    constraint: string;
+    cites: string[];
+}
+export interface CausalAnalysisReply {
+    interpretation: CausalStep[];
+    constraints: PlanningConstraint[];
+    unresolved: string[];
+    /** Malformed-block errors. Reported, never fatal. */
+    errors: string[];
+    /** True when none of the three fenced blocks appeared at all — the analyzer-error path. */
+    blockless: boolean;
+}
+/** Parses the analyzer's three-layer reply. Total: a missing block is empty, malformed JSON is a recorded error and an empty layer, and a reply with none of the three blocks is `blockless` — the analyzer-error path (§3.4). */
+export declare function parseCausalAnalysis(output: string): CausalAnalysisReply;
+export interface ResolvedCitation {
+    handle: string;
+    kind: HandleKind;
+    value: string;
+}
+export interface ValidatedClaim<T> {
+    source: T;
+    resolved: ResolvedCitation[];
+    unresolvedCites: string[];
+    supported: boolean;
+}
+export interface ValidatedCausalAnalysis {
+    supportedSteps: ValidatedClaim<CausalStep>[];
+    unsupportedSteps: ValidatedClaim<CausalStep>[];
+    supportedConstraints: ValidatedClaim<PlanningConstraint>[];
+    unsupportedConstraints: ValidatedClaim<PlanningConstraint>[];
+}
+/** The deterministic gate: proves every rendered causal step cites at least one concrete observation the run actually retained, and no cited handle is fabricated. Never judges whether a resolving citation logically supports its claim (D2) — that is left to the human. Pure. */
+export declare function validateCausalEvidence(reply: CausalAnalysisReply, registry: HandleRegistry): ValidatedCausalAnalysis;
+/** The ```interpretation/```constraints/```unresolved block-format instructions. */
+export declare function causalAnalysisContract(): string;
+export interface CausalAnalysisBriefInput {
+    manifest: ProgramManifest;
+    programId: string;
+    summary: RunAnalyticsSummary;
+    registry: HandleRegistry;
+    ledger: DecisionLedgerView;
+    workstreams: readonly WorkstreamTimelineEntry[];
+    diff: string;
+    baseCommit?: string;
+    /**
+     * The program document's own narrative (`docs/programs/<id>-program.md`),
+     * already clipped by the caller — SC-12 requires the analyzer to consume
+     * the plan, not just the manifest's roster/success-criteria fields.
+     * Absent when the document could not be read; rendered as an honest gap,
+     * never silently dropped (fail-open, SC-13).
+     */
+    programNarrative?: string;
+    /**
+     * Every workstream's actual spec file content, already combined and
+     * clipped by the caller — SC-12 requires the analyzer to consume the
+     * specifications, not merely a path to them. A workstream whose spec could
+     * not be read renders as an honest per-workstream gap, never a silent
+     * omission (fail-open, SC-13).
+     */
+    workstreamSpecsText: string;
+}
+export interface CausalAnalysisBrief {
+    brief: string;
+    components: PromptComponentSize[];
+}
+/**
+ * Assembles the analyzer's read-only brief (§3.3): framing, the
+ * software-rendered observed measurements, the citable span/point/evidence/
+ * ledger handles (drawn straight from `registry`, so what is shown is
+ * exactly what is citable), the plan, the ledger, the verification/retry
+ * timeline, the clipped final diff, and the response contract. Pure;
+ * returns the per-component byte sizes for SC-07 prompt telemetry.
+ */
+export declare function causalAnalysisBrief(input: CausalAnalysisBriefInput): CausalAnalysisBrief;
+export type CausalAnalysisStatus = "no-reviewer" | "no-analytics" | "analyzer-error" | "unresolved" | "analyzed";
+export interface CausalAnalysisOutcome {
+    ran: boolean;
+    status: CausalAnalysisStatus;
+    reason?: string;
+    validated?: ValidatedCausalAnalysis;
+    unresolvedQuestions: string[];
+    parseErrors: string[];
+    inputClipped: boolean;
+    /** The analyzer's own summary block, verbatim, for the report. */
+    note?: string;
+}
+/** The outcome recorded when no reviewerAgent is configured. */
+export declare function causalAnalysisReviewerAbsent(): CausalAnalysisOutcome;
+export interface RunCausalAnalysisOptions {
+    root: string;
+    programId: string;
+    manifest: ProgramManifest;
+    config: NightshiftConfig;
+    agentRunner: AgentRunner;
+    /** Defaults to a no-op context; the caller threads the run's real `PermitsContext` through. */
+    permits?: PermitsContext;
+    /** The run's analytics recorder; a caller with no run-scoped recorder gets a shared no-op default. */
+    recorder?: RunRecorder;
+    /**
+     * The snapshot the caller already took, **before** spawning this pass, via
+     * `recorder.snapshot()` — so the analyzer never reasons about its own
+     * cost (§3.2). `undefined` routes to `no-analytics`.
+     */
+    snapshot: RunAnalytics | undefined;
+    ledger: DecisionLedgerView;
+    workstreams: readonly WorkstreamTimelineEntry[];
+    diff: string;
+    baseCommit?: string;
+    /**
+     * The program document's own narrative, read by the caller from
+     * `docs/programs/<id>-program.md`. `undefined` when the file could not be
+     * read — a fail-open gap noted in the brief, never a thrown run (§3.3/SC-12).
+     */
+    programNarrative?: string;
+    /**
+     * Every workstream's spec file content, read by the caller from its own
+     * `taskFile` (SC-12). Defaults to empty — a program with no workstreams
+     * yields an honest empty specs section, never a thrown run.
+     */
+    workstreamSpecs?: readonly WorkstreamSpecInput[];
+    log?: (line: string) => void;
+}
+/**
+ * Runs the pass once: resolve reviewer → build brief → spawn → parse →
+ * validate → outcome. Never throws — every failure becomes a status and a
+ * `reason` sentence on the returned outcome (§3.5).
+ */
+export declare function runCausalAnalysis(options: RunCausalAnalysisOptions): Promise<CausalAnalysisOutcome>;
+/**
+ * A human-facing render of one completed (or absent) causal analysis, for
+ * the run report. Markdown lines, no heading — the caller splices them
+ * under its own `## Why the time went there` heading, immediately after
+ * WS-04's own section. Total, never-throwing.
+ */
+export declare function renderCausalAnalysis(outcome: CausalAnalysisOutcome, summary: RunAnalyticsSummary): string[];
+/**
+ * The run's own fail-open isolation boundary for the causal-analysis section
+ * (mirrors `renderAnalyticsSection` in run-analytics-report.ts): always
+ * returns a `## Why the time went there` section, never throws. `artifact`
+ * accepts a thunk so an evaluation failure of `recorder.snapshot()` itself
+ * stays inside this function's own try/catch rather than escaping before it
+ * is reached.
+ */
+export declare function renderCausalAnalysisSection(outcome: CausalAnalysisOutcome, artifact: RunAnalytics | undefined | (() => RunAnalytics | undefined), deps?: {
+    aggregate?: typeof aggregateRunAnalytics;
+}): string[];
+//# sourceMappingURL=causal-analysis.d.ts.map

package/dist/causal-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal-analysis.d.ts","sourceRoot":"","sources":["../src/causal-analysis.ts"],"names":[],"mappings":"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"}