@voltro/plan 0.82.0

package/dist/index.d.ts

@@ -0,0 +1,596 @@
+import { Schema } from 'effect';
+
+/** Whether any diagnostic blocks (security or error; warnings too when strict). */
+export declare const blocks: (ds: ReadonlyArray<Diagnostic>, strict?: boolean) => boolean;
+
+/** JSON with object keys sorted at every level; arrays keep their order. */
+export declare const canonicalJson: (value: unknown) => string;
+
+export declare type Certificate = ClosureFile['certificates'][number];
+
+/** Reads the clock once per run, so a whole run sees one "now". */
+export declare interface Clock {
+    readonly now: () => Date;
+}
+
+export declare const CLOSURE_SCHEMA_VERSION = "voltro-plan-closure/v1";
+
+export declare type ClosureDecision = {
+    readonly outcome: 'recorded';
+    readonly file: ClosureFile;
+    readonly run: ClosureRun;
+    readonly certificate: Certificate | null;
+} | {
+    readonly outcome: 'refused';
+    readonly diagnostic: Diagnostic;
+};
+
+export declare type ClosureFile = Schema.Schema.Type<ReturnType<typeof closureFileSchema>>;
+
+/** One plan's closure record: its passes and certificates, oldest first. */
+export declare const closureFileSchema: (shape: ProgramShape) => Schema.Struct<{
+    schemaVersion: Schema.Literal<["voltro-plan-closure/v1"]>;
+    plan: Schema.filter<typeof Schema.String>;
+    runs: Schema.Array$<Schema.Struct<{
+        id: Schema.filter<typeof Schema.String>;
+        pass: Schema.Literal<["contract", "adversarial"]>;
+        reviewer: Schema.filter<typeof Schema.String>;
+        reviewContext: Schema.filter<typeof Schema.String>;
+        planRevision: Schema.filter<typeof Schema.String>;
+        completedAt: Schema.filter<typeof Schema.String>;
+        findingRefs: Schema.Array$<Schema.filter<typeof Schema.String>>;
+        result: Schema.Literal<["passed", "findings"]>;
+        /** The `voltro plan` version that ran the pass. */
+        toolVersion: Schema.filter<typeof Schema.String>;
+    }>>;
+    certificates: Schema.Array$<Schema.Struct<{
+        id: Schema.filter<typeof Schema.String>;
+        plan: Schema.filter<typeof Schema.String>;
+        planRevision: Schema.filter<typeof Schema.String>;
+        workItems: Schema.Array$<Schema.filter<typeof Schema.String>>;
+        evidenceRefs: Schema.Array$<Schema.filter<typeof Schema.String>>;
+        closureRuns: Schema.filter<Schema.Array$<Schema.filter<typeof Schema.String>>>;
+        confirmedBy: Schema.filter<typeof Schema.String>;
+        issuedAt: Schema.filter<typeof Schema.String>;
+        toolVersion: Schema.filter<typeof Schema.String>;
+    }>>;
+}>;
+
+export declare interface ClosureRequest {
+    readonly pass: 'contract' | 'adversarial';
+    readonly reviewer: string;
+    readonly reviewContext: string;
+    readonly findings: ReadonlyArray<string>;
+    readonly at: string;
+    readonly toolVersion: string;
+}
+
+export declare type ClosureRun = ClosureFile['runs'][number];
+
+export declare type ClosureState = {
+    readonly state: 'open';
+}
+/** The contract pass is done on this revision; the adversarial audit is owed. */
+| {
+    readonly state: 'closure-1';
+    readonly run: ClosureRun;
+} | {
+    readonly state: 'certified';
+    readonly certificate: Certificate;
+};
+
+/** Where a plan stands in closure, on its current revision. */
+export declare const closureState: (file: ClosureFile | undefined, revision: string) => ClosureState;
+
+export declare const COMMAND_SCHEMA_VERSION = "voltro-plan-command/v1";
+
+export declare interface CommandEnvelope<R> {
+    readonly schemaVersion: typeof COMMAND_SCHEMA_VERSION;
+    readonly command: 'lint' | 'status' | 'next' | 'evidence add' | 'close' | 'impact';
+    readonly ok: boolean;
+    /** The project root, relative, with `/`. */
+    readonly root: string;
+    readonly inputsFingerprint: string;
+    readonly toolVersion: string;
+    readonly result: R;
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+    readonly observedAt: string;
+}
+
+/**
+ * Record one closure pass for a plan. Refused unless every mandatory item is
+ * verified and no finding against the plan is open; the adversarial pass also
+ * needs a passed contract pass on the same revision, by another reviewer in
+ * another context. A pass that names findings reopens the plan instead. After
+ * the adversarial pass passes, the certificate is issued.
+ */
+export declare const decideClosure: (grammar: IdGrammar, instance: PlanInstance, file: ClosureFile | undefined, revision: string, statusOf: (id: string) => string | undefined, evidence: ReadonlyArray<Evidence>, findings: ReadonlyArray<Finding>, request: ClosureRequest) => ClosureDecision;
+
+/** Decide one `evidence add` against the program and the evidence already there. */
+export declare const decideEvidence: (program: Program, grammar: IdGrammar, request: EvidenceRequest) => EvidenceDecision;
+
+/** The hard dependency cycles, each once, starting at its smallest id; deterministic. */
+export declare const dependencyCycles: (edges: ReadonlyMap<string, ReadonlyArray<string>>) => ReadonlyArray<ReadonlyArray<string>>;
+
+export declare const DERIVED: ReadonlySet<WorkItemStatus>;
+
+/**
+ * The state an item is in: its recorded working state (proposed, ready, active,
+ * blocked), or `verified` when the evidence says so. A recorded `verified` or
+ * `closed` the evidence does not carry falls back to `active`.
+ */
+export declare const derivedStatus: (item: WorkItem, gaps: ReadonlyArray<string>) => WorkItemStatus;
+
+export declare interface Diagnostic {
+    /** `<class>/<rule>`, e.g. `graph/missing-dependency`. */
+    readonly ruleId: string;
+    readonly severity: Severity;
+    readonly message: string;
+    readonly locator: Locator;
+    readonly related: ReadonlyArray<string>;
+    readonly nextAction: string;
+}
+
+export declare const envelope: <R>(fields: Omit<CommandEnvelope<R>, "schemaVersion">) => CommandEnvelope<R>;
+
+export declare type Evidence = Schema.Schema.Type<ReturnType<typeof evidenceSchema>>;
+
+export declare const EVIDENCE_KINDS: readonly ["commit", "typecheck", "unit-test", "integration-test", "e2e", "browser", "schema", "migration", "roundtrip", "documentation", "agent-guide", "template", "security", "privacy", "accessibility", "rights", "operations", "performance", "research", "review", "artifact"];
+
+export declare type EvidenceDecision = {
+    readonly outcome: 'add';
+    readonly evidence: Evidence;
+} | {
+    readonly outcome: 'same';
+    readonly evidence: Evidence;
+} | {
+    readonly outcome: 'refused';
+    readonly diagnostic: Diagnostic;
+    readonly exit: number;
+};
+
+export declare interface EvidenceIndex {
+    readonly evidence: ReadonlyMap<string, Evidence>;
+    /** The evidence naming each work item among its subjects. */
+    readonly bySubject: ReadonlyMap<string, ReadonlyArray<Evidence>>;
+    /** Open findings per work item. */
+    readonly openFindings: ReadonlyMap<string, ReadonlyArray<Finding>>;
+}
+
+export declare interface EvidenceRequest {
+    readonly workItem: string;
+    /** The checks and requirements it proves: `A01`, `E01`, or their full ids. */
+    readonly proves: ReadonlyArray<string>;
+    readonly kind: string;
+    readonly title: string;
+    readonly uri: string;
+    readonly result: 'passed' | 'failed' | 'informational';
+    readonly producedBy: string;
+    readonly command?: string;
+    readonly environment?: string;
+    readonly fingerprint?: string;
+    readonly idempotencyKey?: string;
+    readonly observedAt: string;
+}
+
+/** One piece of evidence: what was observed, by whom, about which subjects. */
+export declare const evidenceSchema: (shape: ProgramShape) => Schema.Struct<{
+    id: Schema.filter<typeof Schema.String>;
+    kind: Schema.Literal<["commit", "typecheck", "unit-test", "integration-test", "e2e", "browser", "schema", "migration", "roundtrip", "documentation", "agent-guide", "template", "security", "privacy", "accessibility", "rights", "operations", "performance", "research", "review", "artifact"]>;
+    title: Schema.filter<typeof Schema.String>;
+    uri: Schema.filter<typeof Schema.String>;
+    fingerprint: Schema.optional<Schema.filter<typeof Schema.String>>;
+    result: Schema.Literal<["passed", "failed", "informational"]>;
+    subjectRefs: Schema.Array$<Schema.filter<typeof Schema.String>>;
+    command: Schema.optional<Schema.filter<typeof Schema.String>>;
+    environment: Schema.optional<Schema.filter<typeof Schema.String>>;
+    producedBy: Schema.filter<typeof Schema.String>;
+    reviewedBy: Schema.optional<Schema.filter<typeof Schema.String>>;
+    observedAt: Schema.filter<typeof Schema.String>;
+    /** Set by `voltro plan evidence add`: the same key with the same payload is the same evidence. */
+    idempotencyKey: Schema.optional<Schema.filter<typeof Schema.String>>;
+}>;
+
+/** The process exit code of a command (0 ok, 1 gate failed, 2 usage, 3 unreadable input, 6 security). */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly input: 3;
+    readonly conflict: 4;
+    readonly provider: 5;
+    readonly security: 6;
+    readonly internal: 70;
+};
+
+export declare type Finding = Schema.Schema.Type<ReturnType<typeof findingSchema>>;
+
+/** A finding against work items: open until resolved or accepted as a risk. */
+export declare const findingSchema: (shape: ProgramShape) => Schema.Struct<{
+    id: Schema.filter<typeof Schema.String>;
+    title: Schema.filter<typeof Schema.String>;
+    severity: Schema.Literal<["critical", "high", "medium", "low"]>;
+    status: Schema.Literal<["open", "resolved", "accepted-risk"]>;
+    source: Schema.Literal<["contract-reconciliation", "adversarial-audit", "test", "incident", "research", "review", "production"]>;
+    targetWorkItems: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+    impactTags: Schema.Array$<Schema.filter<typeof Schema.String>>;
+    evidenceRefs: Schema.optional<Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>>;
+    openedAt: Schema.filter<typeof Schema.String>;
+    resolvedAt: Schema.optional<Schema.filter<typeof Schema.String>>;
+}>;
+
+/** The `sha256:` fingerprint of a value's canonical JSON. */
+export declare const fingerprint: (value: unknown) => string;
+
+export declare interface IdGrammar {
+    readonly prefix: string;
+    readonly plan: RegExp;
+    readonly workItem: RegExp;
+    readonly acceptance: RegExp;
+    readonly requirement: RegExp;
+    readonly source: RegExp;
+    readonly evidence: RegExp;
+    readonly finding: RegExp;
+    readonly adr: RegExp;
+    readonly closureRun: RegExp;
+    readonly certificate: RegExp;
+}
+
+/** The id shapes of a program with `prefix`; throws for a prefix that is not 2–10 capitals/digits. */
+export declare const idGrammar: (prefix: string) => IdGrammar;
+
+export declare interface ImpactInput {
+    readonly tags: ReadonlyArray<string>;
+    /** Project-relative, with `/`. */
+    readonly files: ReadonlyArray<string>;
+}
+
+export declare const impactOf: (program: Program, input: ImpactInput) => ImpactResult;
+
+export declare interface ImpactResult {
+    readonly direct: ReadonlyArray<{
+        readonly workItem: string;
+        readonly because: ReadonlyArray<string>;
+    }>;
+    /** Items affected through a dependency: the path from a direct item. */
+    readonly transitive: ReadonlyArray<{
+        readonly workItem: string;
+        readonly path: ReadonlyArray<string>;
+    }>;
+    readonly plans: ReadonlyArray<string>;
+    /** Certificates on current revisions that the change puts in question: their plans must close again. */
+    readonly certificates: ReadonlyArray<{
+        readonly plan: string;
+        readonly certificate: string;
+    }>;
+    /** Changed files no work item names. */
+    readonly unknown: ReadonlyArray<string>;
+}
+
+export declare const indexEvidence: (evidence: ReadonlyArray<Evidence>, findings: ReadonlyArray<Finding>) => EvidenceIndex;
+
+/** A file as read: its project-relative path (with `/`) and its parsed JSON. */
+export declare interface InputFile {
+    readonly file: string;
+    readonly content: unknown;
+}
+
+export declare const ITEM_KINDS: readonly ["architecture", "feature", "framework", "integration", "migration", "operations", "security", "documentation", "research", "tooling"];
+
+export declare interface LintInput {
+    readonly shape: ProgramShape;
+    readonly instances: ReadonlyArray<InputFile>;
+    readonly evidence?: ReadonlyArray<InputFile>;
+    readonly findings?: ReadonlyArray<InputFile>;
+    /** One closure record per plan (./closure). */
+    readonly closures?: ReadonlyArray<InputFile>;
+    /**
+     * The plans' source files as read, `sha256:` of their bytes. When given, a
+     * plan whose source changed since its decomposition — or is gone — is stale.
+     */
+    readonly sources?: ReadonlyMap<string, string | null>;
+    /** The decision records by id (`ADR-<prefix>-NNN`), `sha256:` of their bytes. When given, a link to an unknown one is an error. */
+    readonly decisions?: ReadonlyMap<string, string>;
+    readonly clock: Clock;
+}
+
+/** Lint the whole program; the diagnostics come sorted (./diagnostics). */
+export declare const lintProgram: (input: LintInput) => LintResult;
+
+export declare interface LintResult {
+    readonly program: Program;
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export declare interface Locator {
+    /** The file, relative to the project root, with `/`. */
+    readonly file?: string;
+    readonly plan?: string;
+    readonly workItem?: string;
+    /** The field inside the object, e.g. `acceptance[1].evidenceRefs`. */
+    readonly path?: string;
+}
+
+export declare const Manifest: Schema.Struct<{
+    schemaVersion: Schema.Literal<["voltro-plan-manifest/v1"]>;
+    prefix: Schema.filter<typeof Schema.String>;
+    /** The `schemaVersion` the plan instances carry. */
+    instanceVersion: Schema.filter<typeof Schema.String>;
+    repos: Schema.filter<Schema.Array$<Schema.filter<typeof Schema.String>>>;
+    instances: Schema.filter<Schema.Array$<Schema.filter<Schema.filter<typeof Schema.String>>>>;
+    evidence: Schema.optional<Schema.Array$<Schema.filter<Schema.filter<typeof Schema.String>>>>;
+    /** Where `voltro plan evidence add` writes: one `<plan number>.json` per plan; read as well. */
+    evidenceDir: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    /** Where `voltro plan close` keeps each plan's closure record (`<plan number>.json`). */
+    closureDir: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    /** The decision records: files named `ADR-<prefix>-NNN-….md`. Items link them; a changed one reopens their plans. */
+    adrDir: Schema.optional<Schema.filter<Schema.filter<typeof Schema.String>>>;
+    findings: Schema.optional<Schema.Array$<Schema.filter<Schema.filter<typeof Schema.String>>>>;
+}>;
+
+export declare type Manifest = Schema.Schema.Type<typeof Manifest>;
+
+export declare const MANIFEST_SCHEMA_VERSION = "voltro-plan-manifest/v1";
+
+export declare interface NextFilter {
+    readonly plan?: string;
+    readonly owner?: string;
+    readonly repo?: string;
+}
+
+export declare const nextItem: (program: Program, filter: NextFilter, lintBlocks: boolean) => NextResult;
+
+export declare type NextResult = {
+    readonly outcome: 'item';
+    readonly workItem: WorkItem;
+    readonly why: ReadonlyArray<string>;
+    readonly file: string;
+} | {
+    readonly outcome: 'complete';
+} | {
+    readonly outcome: 'blocked';
+    readonly reason: string;
+    readonly prepare: WorkItem | null;
+    readonly file: string | null;
+} | {
+    readonly outcome: 'invalid';
+    readonly reason: string;
+};
+
+/** The work item an acceptance check, evidence requirement, source, evidence or finding id belongs to, or null. */
+export declare const ownerItemOf: (grammar: IdGrammar, id: string) => string | null;
+
+export declare type Plan = PlanInstance['plan'];
+
+export declare const PLAN_STATUSES: readonly ["proposed", "decomposing", "ready", "active", "verifying", "closure-1", "closure-2", "complete"];
+
+export declare type PlanInstance = Schema.Schema.Type<ReturnType<typeof planInstanceSchema>>;
+
+/** The Schema of one plan instance for a program. */
+export declare const planInstanceSchema: (shape: ProgramShape) => Schema.Struct<{
+    schemaVersion: Schema.Literal<[string]>;
+    plan: Schema.Struct<{
+        id: Schema.filter<typeof Schema.String>;
+        number: Schema.filter<typeof Schema.String>;
+        title: Schema.filter<typeof Schema.String>;
+        source: Schema.filter<typeof Schema.String>;
+        sourceRevision: Schema.filter<typeof Schema.String>;
+        status: Schema.Literal<["proposed", "decomposing", "ready", "active", "verifying", "closure-1", "closure-2", "complete"]>;
+        decompositionComplete: typeof Schema.Boolean;
+        updatedAt: Schema.filter<typeof Schema.String>;
+    }>;
+    extraction: Schema.Struct<{
+        rulesVersion: Schema.filter<typeof Schema.String>;
+        sourceRevision: Schema.filter<typeof Schema.String>;
+        blockKinds: Schema.Array$<Schema.filter<typeof Schema.String>>;
+        extractedAt: Schema.filter<typeof Schema.String>;
+    }>;
+    workItems: Schema.Array$<Schema.Struct<{
+        id: Schema.filter<typeof Schema.String>;
+        title: Schema.filter<typeof Schema.String>;
+        ownerPlan: Schema.filter<typeof Schema.String>;
+        slice: Schema.filter<typeof Schema.String>;
+        kind: Schema.Literal<["architecture", "feature", "framework", "integration", "migration", "operations", "security", "documentation", "research", "tooling"]>;
+        priority: Schema.Literal<["P0", "P1", "P2", "P3"]>;
+        mandatory: typeof Schema.Boolean;
+        status: Schema.Literal<["proposed", "ready", "active", "blocked", "verified", "closed"]>;
+        owners: Schema.Array$<Schema.filter<typeof Schema.String>>;
+        repos: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+        sourceRefs: Schema.filter<Schema.Array$<Schema.Schema<{
+            readonly id: string;
+            readonly uri: string;
+            readonly locator: string;
+            readonly excerpt: string;
+            readonly lineHint?: number | undefined;
+            readonly contentHash: string;
+            readonly disposition: "owned-by" | "referenced-by" | "decision" | "non-goal";
+            readonly targetId?: string | undefined;
+        }, {
+            readonly id: string;
+            readonly uri: string;
+            readonly locator: string;
+            readonly excerpt: string;
+            readonly contentHash: string;
+            readonly disposition: "owned-by" | "referenced-by" | "decision" | "non-goal";
+            readonly lineHint?: number | undefined;
+            readonly targetId?: string | undefined;
+        }, never>>>;
+        dependsOn: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+        links: Schema.Struct<{
+            capabilities: Schema.Array$<Schema.filter<typeof Schema.String>>;
+            journeys: Schema.Array$<Schema.filter<typeof Schema.String>>;
+            adrs: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+            risks: Schema.Array$<Schema.filter<typeof Schema.String>>;
+            relatedTo: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+        }>;
+        acceptance: Schema.filter<Schema.Array$<Schema.Schema<{
+            readonly id: string;
+            readonly status: "pending" | "passed" | "failed";
+            readonly statement: string;
+            readonly evidenceRefs: readonly string[];
+        }, {
+            readonly id: string;
+            readonly status: "pending" | "passed" | "failed";
+            readonly statement: string;
+            readonly evidenceRefs: readonly string[];
+        }, never>>>;
+        evidenceRequirements: Schema.filter<Schema.Array$<Schema.Schema<{
+            readonly id: string;
+            readonly status: "open" | "satisfied" | "waived";
+            readonly statement: string;
+            readonly evidenceRefs: readonly string[];
+            readonly kinds: readonly ("commit" | "typecheck" | "unit-test" | "integration-test" | "e2e" | "browser" | "schema" | "migration" | "roundtrip" | "documentation" | "agent-guide" | "template" | "security" | "privacy" | "accessibility" | "rights" | "operations" | "performance" | "research" | "review" | "artifact")[];
+            readonly waiver?: {
+                readonly rationale: string;
+                readonly reviewer: string;
+                readonly expiresAt: string;
+                readonly compensatingControl: string;
+            } | undefined;
+        }, {
+            readonly id: string;
+            readonly status: "open" | "satisfied" | "waived";
+            readonly statement: string;
+            readonly evidenceRefs: readonly string[];
+            readonly kinds: readonly ("commit" | "typecheck" | "unit-test" | "integration-test" | "e2e" | "browser" | "schema" | "migration" | "roundtrip" | "documentation" | "agent-guide" | "template" | "security" | "privacy" | "accessibility" | "rights" | "operations" | "performance" | "research" | "review" | "artifact")[];
+            readonly waiver?: {
+                readonly rationale: string;
+                readonly reviewer: string;
+                readonly expiresAt: string;
+                readonly compensatingControl: string;
+            } | undefined;
+        }, never>>>;
+        evidenceRefs: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+        impactTags: Schema.filter<Schema.Array$<Schema.Schema<string, string, never>>>;
+        statusHistory: Schema.filter<Schema.Array$<Schema.Schema<{
+            readonly at: string;
+            readonly from: "proposed" | "ready" | "active" | "blocked" | "verified" | "closed" | null;
+            readonly evidenceRefs: readonly string[];
+            readonly to: "proposed" | "ready" | "active" | "blocked" | "verified" | "closed";
+            readonly reason: string;
+            readonly actor: string;
+        }, {
+            readonly at: string;
+            readonly from: "proposed" | "ready" | "active" | "blocked" | "verified" | "closed" | null;
+            readonly evidenceRefs: readonly string[];
+            readonly to: "proposed" | "ready" | "active" | "blocked" | "verified" | "closed";
+            readonly reason: string;
+            readonly actor: string;
+        }, never>>>;
+        blocker: Schema.optional<Schema.Struct<{
+            reason: Schema.filter<typeof Schema.String>;
+            owner: Schema.filter<typeof Schema.String>;
+            nextAction: Schema.filter<typeof Schema.String>;
+            recheckTrigger: Schema.filter<typeof Schema.String>;
+            since: Schema.filter<typeof Schema.String>;
+        }>>;
+        supersededBy: Schema.optional<Schema.filter<typeof Schema.String>>;
+        createdAt: Schema.filter<typeof Schema.String>;
+        updatedAt: Schema.filter<typeof Schema.String>;
+    }>>;
+    coverage: Schema.Struct<{
+        extractedSources: typeof Schema.Int;
+        disposedSources: typeof Schema.Int;
+        unmatchedSources: typeof Schema.Int;
+        duplicateSources: typeof Schema.Int;
+        sourceIdsHash: Schema.filter<typeof Schema.String>;
+        result: Schema.Literal<["complete", "incomplete"]>;
+    }>;
+}>;
+
+/** The two-digit plan number an id belongs to (`CMS-06-001` → `06`, `CMS-PLAN-06` → `06`), or null. */
+export declare const planNumberOf: (id: string) => string | null;
+
+/**
+ * The fingerprint a closure pass and a certificate are pinned to: the plan's
+ * instance, the evidence about its items, the findings against them, the
+ * decision records its items link (their content hash), and the
+ * state of every dependency outside the plan (`closed` counts as `verified`, so
+ * one plan's certificate does not move another's revision).
+ */
+export declare const planRevision: (instance: PlanInstance, evidence: ReadonlyArray<Evidence>, findings: ReadonlyArray<Finding>, statusOf?: (id: string) => string | undefined, decisions?: ReadonlyMap<string, string>) => string;
+
+export declare interface PlanStatus {
+    readonly plan: string;
+    readonly title: string;
+    readonly file: string;
+    /** What the plan file says. */
+    readonly recorded: string;
+    /** What its items and its closure say: decomposing, ready, active, verifying, closure-1 (contract pass done) or complete (certified). */
+    readonly derived: 'decomposing' | 'ready' | 'active' | 'verifying' | 'closure-1' | 'complete';
+    /** The certificate it holds on its current revision, if any. */
+    readonly certificate: string | null;
+    readonly mandatory: StatusCounts;
+    readonly optional: StatusCounts;
+    readonly blocked: ReadonlyArray<{
+        readonly workItem: string;
+        readonly reason: string;
+        readonly owner: string;
+        readonly nextAction: string;
+    }>;
+}
+
+export declare const PRIORITIES: readonly ["P0", "P1", "P2", "P3"];
+
+export declare interface Program {
+    readonly instances: ReadonlyArray<{
+        readonly file: string;
+        readonly instance: PlanInstance;
+    }>;
+    readonly items: ReadonlyMap<string, {
+        readonly file: string;
+        readonly item: WorkItem;
+    }>;
+    readonly evidence: ReadonlyArray<Evidence>;
+    readonly findings: ReadonlyArray<Finding>;
+    /** Each item's state as the evidence says (./state). */
+    readonly status: ReadonlyMap<string, WorkItemStatus>;
+    /** Why each not-verified item is not. */
+    readonly gaps: ReadonlyMap<string, ReadonlyArray<string>>;
+    /** Each plan's closure record, its current revision and where it stands in closure. */
+    readonly closures: ReadonlyMap<string, {
+        readonly file: string;
+        readonly record: ClosureFile;
+    }>;
+    readonly revisions: ReadonlyMap<string, string>;
+    readonly closure: ReadonlyMap<string, ClosureState>;
+}
+
+/** What a project declares next to its prefix: the repositories work may land in. */
+export declare interface ProgramShape {
+    readonly grammar: IdGrammar;
+    readonly repos: ReadonlyArray<string>;
+    /** The `schemaVersion` its instances carry, e.g. `cms-execution/v1`. */
+    readonly instanceVersion: string;
+}
+
+export declare interface ProgramStatus {
+    readonly plans: ReadonlyArray<PlanStatus>;
+    readonly mandatory: StatusCounts;
+    readonly items: number;
+}
+
+export declare const programStatus: (program: Program) => ProgramStatus;
+
+export declare type Severity = 'security' | 'error' | 'warning';
+
+/** SHA-256 of `text` (UTF-8), as 64 lower-case hex digits. */
+export declare const sha256Hex: (text: string) => string;
+
+/** Severity, plan, work item, rule, then file and path — stable for the same diagnostics in any order. */
+export declare const sortDiagnostics: (ds: ReadonlyArray<Diagnostic>) => ReadonlyArray<Diagnostic>;
+
+export declare type StatusCounts = Readonly<Record<WorkItemStatus, number>>;
+
+/** The edges a work item may take. */
+export declare const TRANSITIONS: Readonly<Record<WorkItemStatus, ReadonlyArray<WorkItemStatus>>>;
+
+/** Why an item is not verified; empty when it is. */
+export declare const verificationGaps: (item: WorkItem, index: EvidenceIndex, statusOf: (id: string) => WorkItemStatus | undefined, clock: Clock) => ReadonlyArray<string>;
+
+export declare const WORK_ITEM_STATUSES: readonly ["proposed", "ready", "active", "blocked", "verified", "closed"];
+
+export declare type WorkItem = PlanInstance['workItems'][number];
+
+export declare type WorkItemStatus = (typeof WORK_ITEM_STATUSES)[number];
+
+export { }