@mstar-harness/engine 3.9.3 → 3.10.0

package/dist/workflow.d.ts

@@ -1,4 +1,5 @@
-import type { GateResult, ValidationResult } from "./core.js";
+import { type GateResult, type ValidationResult } from "./core.js";
+import { type SnapshotCoordination } from "./coordination-write.js";
 import { type IntegrationMergeLease } from "./lease.js";
 import { type PlanRow } from "./status.js";
 /** Snapshot file name inside `workflows/<id>/` ( — writer contract). */
@@ -9,6 +10,58 @@ export declare const WORKFLOW_LIFECYCLE_STATUSES: readonly ["running", "paused",
 export declare const WORKFLOW_TERMINAL_STATUSES: readonly ["completed", "failed", "stopped"];
 /** Lifecycle type enum ( — id reuses the orchestration id). */
 export declare const WORKFLOW_LIFECYCLE_TYPES: readonly ["plan", "iteration"];
+/**
+ * Delivery kinds declared at registration (mstar-artifacts/references/plan-workflow-lifecycle-contract.md
+ * §1). The declared kind is recorded at registration and never inferred
+ * retroactively; `development` carries the full PR/merge delivery lifecycle,
+ * `verification/report-only` follows the explicit completion policy recorded
+ * alongside it.
+ */
+export declare const WORKFLOW_DELIVERY_KINDS: readonly ["development", "verification/report-only"];
+export type WorkflowDeliveryKind = (typeof WORKFLOW_DELIVERY_KINDS)[number];
+/**
+ * Compound disposition outcomes (contract §4c): `created` / `updated` /
+ * reasoned `skipped`. The disposition is recorded on the workflow before the
+ * PR head is finalized, so the delivery evidence names the compound outcome
+ * it was taken from.
+ */
+export declare const WORKFLOW_COMPOUND_OUTCOMES: readonly ["created", "updated", "skipped"];
+export type WorkflowCompoundOutcome = (typeof WORKFLOW_COMPOUND_OUTCOMES)[number];
+/**
+ * Delivery evidence recorded on the snapshot (contract §3 lifecycle stages,
+ * §4c/§4d/§4f, seam S3). Each member is recorded by its owner at its own
+ * stage through the authorized write seam (`recordWorkflowDelivery`), and the
+ * close consultation reads the block for the DECLARED delivery kind — never
+ * inferring a kind from which members happen to be present (§1):
+ *
+ * - `compound` — compound disposition (§4c), recorded before the PR head is
+ *   finalized; `skipped` carries the mandatory reason;
+ * - `pr` — PR identity recorded at submission (§4d): repo/head/target. A
+ *   local commit or a pre-existing unrelated PR does not satisfy it;
+ * - `merge` — the PM's verified-merge record (§4f): the provider evidence
+ *   they checked. The engine NEVER verifies the remote merge itself;
+ * - `completion` — the fulfilment record of the `completion_policy` recorded
+ *   at registration (§1) for `verification/report-only` workflows.
+ */
+export type WorkflowDeliveryEvidence = {
+    compound?: {
+        outcome: WorkflowCompoundOutcome;
+        reason?: string;
+    };
+    pr?: {
+        repo: string;
+        head: string;
+        target: string;
+    };
+    merge?: {
+        provider: string;
+        evidence: string;
+    };
+    completion?: {
+        policy: string;
+        evidence: string;
+    };
+};
 export type WorkflowLifecycleStatus = (typeof WORKFLOW_LIFECYCLE_STATUSES)[number];
 export type WorkflowLifecycleType = (typeof WORKFLOW_LIFECYCLE_TYPES)[number];
 /**
@@ -23,7 +76,20 @@ export type WorkflowExecutionPolicy = {
 };
 /** Iteration branch anchors ( — from root metadata anchors). */
 export type WorkflowBranchAnchors = {
+    /**
+     * Protected base anchor: the branch the lifecycle starts from (iteration
+     * `iteration_base_branch`). Cleanup Rule 2 never deletes it and L1 uses it
+     * as the explicit main-worktree residency fallback — it is NEVER a
+     * feature/working branch (`registerPlanWorkflow` records the plan's
+     * delivery branch under `source`).
+     */
     base?: string;
+    /**
+     * Source branch of a standalone `type: plan` delivery, recorded at
+     * registration (`--branch-source`). Semantically a delivery branch, not a
+     * protected base anchor: cleanup/L1 consumers keep reading `base`.
+     */
+    source?: string;
     integration?: string;
     target?: string;
 };
@@ -63,7 +129,38 @@ export type WorkflowSnapshot = {
     integration_worktree_path?: string;
     legacy_metadata?: Record<string, unknown>;
     compass_ref?: string;
+    /**
+     * Snapshot-level coordination block ( — scoped plan-PM coordination).
+     * Present only on a coordinated lifecycle: it carries the workflow's
+     * coordinator binding (session id + canonical envelope path). The block
+     * is validated strictly (`validateSnapshotCoordination`) and may only be
+     * changed by the locked coordination writer.
+     */
+    coordination?: SnapshotCoordination;
+    /**
+     * Delivery kind declared at registration (mstar-artifacts/references/plan-workflow-lifecycle-contract.md
+     * §1). Recorded by the registration producer; never inferred from runtime
+     * behavior or from the presence/absence of other fields.
+     */
+    delivery_kind?: WorkflowDeliveryKind;
+    /** Project register id recorded at registration (contract §3 register row). */
+    project?: string;
+    /**
+     * Explicit completion policy for `verification/report-only` workflows,
+     * recorded at registration (contract §1): names the evidence that completes
+     * the workflow (e.g. acceptance artifacts or the report location).
+     */
+    completion_policy?: string;
+    /**
+     * Delivery evidence collected over the lifecycle (contract §3/§4c/§4d/§4f,
+     * seam S3). Optional at the schema level — it is populated stage by stage
+     * through `recordWorkflowDelivery` and consulted by the close path (and the
+     * read-only phase-6 gate) for the declared `delivery_kind`.
+     */
+    delivery?: WorkflowDeliveryEvidence;
 };
+/** Stable JSON for change detection (sorted keys, recursive). */
+export declare function stableJson(value: unknown): string;
 /**
  * Validate a v3 workflow snapshot document ( — final schema):
  * enum/type/id checks, `schema_version: 1`, required timestamps, `plans[]`
@@ -114,8 +211,34 @@ export declare class WorkflowSnapshotValidationError extends Error {
 }
 export declare function readWorkflowSnapshot(dir: string): WorkflowSnapshotRead;
 /**
- * Write a workflow snapshot as a whole-rewrite of `dir/snapshot.json` under
- * `withStatusWriteLock(snapshotPath)` ( — the `.status-write.lockdir`
+ * Writer contract (spec §C4). `expectedVersion` is the CAS token — the exact
+ * on-disk artifact version (`sha256:<64 hex>`), or `"absent"` for
+ * create-only. `createOnly` is the locked `absent` shorthand used by the
+ * scaffold/migrate/audit writers: an existing document (even an empty or
+ * malformed one) is never silently replaced.
+ *
+ * Omitting `expectedVersion` means create-only, NOT "replace whatever is
+ * there": there is no missing-version compatibility fallback, so an existing
+ * snapshot still refuses with `coordination.expected-version-required`.
+ *
+ * The delta allowed here is `phase` + `updated_at` and nothing else — a
+ * coordinator persists its phase projection through this writer without ever
+ * gaining a backdoor to row owners, leases, lifecycle scalars or branch
+ * anchors. Lifecycle terminal changes belong to `closeWorkflow` (spec §C4).
+ */
+export type WriteWorkflowSnapshotOptions = {
+    expectedVersion?: string;
+    createOnly?: boolean;
+    /**
+     * Canonical coordinator session envelope path (spec §C4). Required when the
+     * stored snapshot is coordinated: only the snapshot's own bound coordinator
+     * may pass, and the `coordination` block itself is never part of the delta.
+     */
+    sessionPath?: string;
+};
+/**
+ * Write a workflow snapshot as a field-scoped update of `dir/snapshot.json`
+ * under `withStatusWriteLock(snapshotPath)` ( — the `.status-write.lockdir`
  * lands inside `workflows/<id>/`, dirname of the snapshot; no harness-root
  * pollution). The snapshot is validated first — an invalid snapshot throws
  * and nothing is written. `dir` is created recursively. The durable write
@@ -128,14 +251,262 @@ export declare function readWorkflowSnapshot(dir: string): WorkflowSnapshotRead;
  * whose target root differs from the active store's root MUST
  * `setArtifactStore(createFsStore(root))` first.
  */
-export declare function writeWorkflowSnapshot(snapshot: WorkflowSnapshot, dir: string): Promise<void>;
+export declare function writeWorkflowSnapshot(snapshot: WorkflowSnapshot, dir: string, opts?: WriteWorkflowSnapshotOptions): Promise<void>;
 /** Terminal enum predicate only; callers validate document shape separately. */
 export declare function isTerminalSnapshot(doc: WorkflowSnapshot): boolean;
+/** Delivery-registration inputs every producer declares (contract §1/§4a). */
+export type DeliveryRegistrationEvidence = {
+    branchSource?: string;
+    branchTarget?: string;
+    completionPolicy?: string;
+};
+/**
+ * Per-kind registration-evidence coherence (contract §1) — the ONE rule shared
+ * by every producer that declares a delivery kind at registration time:
+ * `registerPlanWorkflow` (the normal-entry producer), `promoteAuditPlans`
+ * (audit promotion) and `migrateHarnessTree` (v1 lift), plus the one-time
+ * `declareWorkflowDeliveryKind` backfill for active kind-less snapshots.
+ * Lockstep here is the point: a `development` workflow declares BOTH delivery
+ * anchors and a `verification/report-only` workflow declares the completion
+ * policy that completes it — missing fields are incomplete registration, never
+ * an exemption, and a producer that drifted would otherwise mint an
+ * unclosable lifecycle. `what` prefixes the refusal (the caller's own name).
+ */
+export declare function assertDeliveryRegistrationCoherence(kind: WorkflowDeliveryKind, evidence: DeliveryRegistrationEvidence, what: string): void;
+/**
+ * Delivery-kind evidence consultation (seam S3 — contract §4g + §6 S3): the
+ * ONE implementation behind both the read-only Phase-6 gate
+ * (`evaluatePostMergeClose`) and the close write path (`closeWorkflow`), so
+ * the gate's verdict and the close's refusal can never drift apart. Pure,
+ * read-only, no writes; the input snapshot is consumed as read.
+ *
+ * Only `type: plan` lifecycles consult (an iteration declares no delivery
+ * kind — §1); WHEN the consultation runs is the caller's rule, and both
+ * callers scope it to a delivered lifecycle: `closeWorkflow` consults the
+ * running snapshot it is about to complete, and the Phase-6 gate consults a
+ * `completed` terminal snapshot. A `failed`/`stopped` close is therefore never
+ * demanded delivery evidence (§5). The DECLARED kind decides the required
+ * evidence; nothing is inferred from which fields happen to be present, and a
+ * missing field is incomplete registration, never an exemption (§1):
+ *
+ * - no registered `delivery_kind` → `PHASE6_DELIVERY_KIND_UNREGISTERED` (a
+ *   legacy terminal snapshot cannot be backfilled: the register producer is
+ *   create-only and preserves the terminal bytes);
+ * - `development` → the registered `branch.source`/`branch.target` plus the
+ *   collected `delivery` evidence: compound disposition (§4c), PR identity
+ *   (§4d) and the PM's verified-merge record (§4f — the engine never verifies
+ *   the remote merge itself);
+ * - `verification/report-only` → the recorded `completion_policy` plus its
+ *   fulfilment record, which must name that same policy (§1).
+ *
+ * Everything missing is named in one refusal (`PHASE6_DELIVERY_EVIDENCE_INCOMPLETE`)
+ * whose fix hint points at the authorized recording seam.
+ */
+export declare function consultDeliveryEvidence(snapshot: WorkflowSnapshot): ValidationResult[];
 export type CloseWorkflowOptions = {
     endedAt: string;
+    /**
+     * Canonical coordinator session envelope path (spec §C4). Required when the
+     * stored snapshot is coordinated: the close writes the snapshot, so only the
+     * snapshot's own bound coordinator may pass. A missing/mismatched envelope
+     * refuses the close with `coordination.session-mismatch` before anything is
+     * written. Non-coordinated snapshots ignore it; an already-terminal snapshot
+     * is returned unchanged (no write, no authorization needed).
+     */
+    sessionPath?: string;
 };
 /**
  * Complete the latest snapshot under its write lock. Never releases leases.
- * A valid terminal snapshot is returned unchanged, including failed/stopped.
+ * A valid terminal snapshot is returned unchanged, including failed/stopped
+ * (idempotent preservation — nothing is rewritten, not even the timestamp).
+ * A coordinated snapshot is closed only by its own bound coordinator
+ * (spec §C4) — the same envelope seam as `writeWorkflowSnapshot` — so a plan
+ * actor or a bare CLI call can never complete a lifecycle it does not own.
+ *
+ * Before the terminal write the close consults the registered delivery
+ * kind's evidence through `consultDeliveryEvidence` — the SAME pure function
+ * the read-only Phase-6 gate runs (contract §4g/§6 S3), so the gate's verdict
+ * and this refusal can never disagree. An incomplete delivery (a
+ * `development` workflow without its compound disposition / PR identity /
+ * verified-merge record, a `verification/report-only` workflow without the
+ * fulfilment of its recorded completion policy) throws with every missing
+ * item named and ZERO writes: the snapshot stays `running` and the root entry
+ * stays registered, so the workflow remains resumable. The local close never
+ * verifies a remote merge (§4f keeps that as the PM's separate check) and
+ * never releases leases.
  */
 export declare function closeWorkflow(workflowId: string, dir: string, opts: CloseWorkflowOptions): Promise<WorkflowSnapshot>;
+export type RecordWorkflowDeliveryOptions = {
+    /**
+     * Partial delivery-evidence patch: only the named members are merged into
+     * the stored block, so the compound disposition, the PR identity and the
+     * merge record can be recorded at their own lifecycle stages without
+     * rewriting each other. At least one member is required.
+     */
+    evidence: WorkflowDeliveryEvidence;
+    /**
+     * Canonical coordinator session envelope path (spec §C4) — the same
+     * authority seam `closeWorkflow` uses: a coordinated snapshot is written
+     * only by its own bound coordinator. Non-coordinated snapshots have no
+     * coordinator to bind and ignore it.
+     */
+    sessionPath?: string;
+    /** Recording timestamp (YYYY-MM-DD or RFC3339). Default: now. */
+    at?: string;
+};
+export type RecordWorkflowDeliveryResult = {
+    snapshot: WorkflowSnapshot;
+    /** `false` when the recorded evidence already matched disk — nothing was written. */
+    written: boolean;
+};
+/**
+ * Record (or extend) the delivery evidence on a `type: plan` workflow's
+ * snapshot, under the snapshot write lock: the close path's consultation is
+ * only as good as the evidence recorded here, so this is the seam that makes
+ * a `development` close possible at all.
+ *
+ * Refusals (before any write):
+ * - a terminal snapshot: delivery evidence is collected BEFORE the close, and
+ *   a terminal lifecycle is never amended (§5 — no rewriting a closed
+ *   lifecycle);
+ * - a lifecycle other than `type: plan`, or one without a registered
+ *   `delivery_kind`: the evidence belongs to the declared kind (§1);
+ * - evidence the declared kind does not use (e.g. a completion record on a
+ *   `development` workflow) — the declared kind is authoritative;
+ * - a rewrite of the recorded PR identity (§4d records it once at submission:
+ *   an identical re-record is idempotent, a different pair is refused);
+ * - an empty patch or a malformed member: nothing is silently dropped.
+ *
+ * Idempotent and re-entrant: re-recording the exact stored evidence performs
+ * NO write and returns the snapshot as read (the timestamp is untouched), so
+ * a retried recording never produces a spurious revision. The write itself
+ * routes through the same protected-writer path as the close (the store's
+ * locked put inside the snapshot lock).
+ */
+export declare function recordWorkflowDelivery(workflowId: string, dir: string, opts: RecordWorkflowDeliveryOptions): Promise<RecordWorkflowDeliveryResult>;
+export type DeclareWorkflowDeliveryKindOptions = {
+    /** The declared kind (contract §1). Required — never inferred. */
+    deliveryKind: WorkflowDeliveryKind;
+    /** Delivery source branch, recorded as `branch.source`. Required for `development`. */
+    branchSource?: string;
+    /** Delivery target branch, recorded as `branch.target`. Required for `development`. */
+    branchTarget?: string;
+    /** Completion policy naming the evidence that completes the workflow. Required for `verification/report-only`. */
+    completionPolicy?: string;
+    /**
+     * Canonical coordinator session envelope path (spec §C4) — the same
+     * authority seam `closeWorkflow` and `recordWorkflowDelivery` use: a
+     * coordinated snapshot is written only by its own bound coordinator. An
+     * uncoordinated snapshot has no coordinator binding to authenticate (the
+     * historical audit-promotion / migrate population is exactly that), so it
+     * keeps the harness-owner stance the close already applies.
+     */
+    sessionPath?: string;
+    /** Declaration timestamp (YYYY-MM-DD or RFC3339). Default: now. */
+    at?: string;
+};
+/**
+ * Declare the delivery kind (and its per-kind registration evidence) of an
+ * ACTIVE `type: plan` snapshot whose producer declared none — the one-time
+ * upgrade seam for the historical population (contract §1/§4a). ONE-TIME by
+ * construction: the kind is registration evidence that is never inferred
+ * retroactively (§1), so a second declaration is refused even with the same
+ * value, and a terminal snapshot is refused outright (§5 — a closed lifecycle
+ * is never amended; the legacy terminal dead end keeps its documented
+ * owner-amendment path).
+ *
+ * The declaration carries the kind's own evidence through the shared
+ * `assertDeliveryRegistrationCoherence` rule, so it cannot mint an unclosable
+ * lifecycle (a `development` kind needs its delivery anchors, a
+ * `verification/report-only` kind its completion policy). A supplied delivery
+ * anchor either FILLS the missing one or restates the value the snapshot
+ * already registers; a contradicting value is refused, so the declaration can
+ * never re-point a lifecycle at another delivery. The write lands in the
+ * snapshot lock through the same protected writer as the close.
+ */
+export declare function declareWorkflowDeliveryKind(workflowId: string, dir: string, opts: DeclareWorkflowDeliveryKindOptions): Promise<WorkflowSnapshot>;
+/** Options for `registerPlanWorkflow`. `harnessDir` is required — the
+ * snapshot and `status.json` live under the harness root. */
+export type RegisterPlanWorkflowOptions = {
+    /** Absolute harness dir that contains `status.json` + `workflows/`. Required. */
+    harnessDir: string;
+    /** The owned plan (contract §2: one independently owned plan per workflow on the new normal route). */
+    plan: {
+        id: string;
+        title: string;
+        file: string;
+    };
+    /** Delivery kind declared at registration (contract §1). Required — never inferred. */
+    deliveryKind: WorkflowDeliveryKind;
+    /** Project register id recorded on the snapshot (contract §3 register row). */
+    project?: string;
+    /** Source branch of the delivery, recorded as `branch.source`. Required together with `branchTarget` for `development`. */
+    branchSource?: string;
+    /** Target branch. Required together with `branchSource` for `development`. */
+    branchTarget?: string;
+    /**
+     * Completion policy for `verification/report-only` workflows (contract §1):
+     * names the evidence that completes the workflow. Required for that kind.
+     */
+    completionPolicy?: string;
+    /**
+     * Pre-existing coordinator binding recorded at registration. Optional —
+     * binding a NEW coordinator session stays on the authorized `bind` seam
+     * (`coordination.ts`); this only records an already-held binding.
+     */
+    coordinator?: {
+        session_id: string;
+        session_file: string;
+    };
+    /** Registration timestamp (YYYY-MM-DD or RFC3339). Default: now. */
+    startedAt?: string;
+};
+export type RegisterPlanWorkflowResult = {
+    workflowId: string;
+    snapshotPath: string;
+    /**
+     * True when this call completed a registration whose snapshot already
+     * existed (crash between snapshot creation and root registration): the
+     * existing snapshot bytes — identity, timestamps, ownership — were kept
+     * and only the root entry was written (contract §4b recovery).
+     */
+    recovered: boolean;
+};
+/**
+ * Register a standalone plan workflow (seam S1 — the generic normal-entry
+ * producer). Builds the create-only `type: plan` snapshot (workflow id, the
+ * owned plan as its single Todo row, project, delivery kind, source/target
+ * branches, optional coordinator) and the root `workflows[]` entry, then
+ * writes BOTH under one atomic section of the root `withStatusWriteLock`
+ * — the same serialization point `registerWorkflow` uses — mirroring
+ * `promoteAuditPlans`'s primitive sequence: create-only
+ * `writeWorkflowSnapshot` (its snapshot-dir lock nests inside the root lock,
+ * root → snapshot is the documented acquisition order) →
+ * `registerWorkflowEntryLocked`, with rollback that removes ONLY the exact
+ * snapshot version this call created (plus the now-empty workflow dir), so a
+ * failed register write is never treated as partial activation success.
+ *
+ * Refusals (fail-loud, no partial activation):
+ * - existing id: the workflow is already registered (snapshot + root entry) —
+ *   registration is create-only, never a re-registration;
+ * - unreadable root: a malformed/v1 `status.json` refuses (the created
+ *   snapshot is rolled back first);
+ * - missing required fields: id/plan/delivery-kind shape per the existing
+ *   snapshot validators; `development` additionally requires source+target
+ *   branches (contract §1 — a development workflow with missing branch
+ *   fields is incomplete registration, not an exempt workflow) and
+ *   `verification/report-only` requires the completion policy.
+ *
+ * Crash/retry recovery (contract §4b): a crash between snapshot creation and
+ * root registration leaves the snapshot orphaned (no root entry = no
+ * activation). Re-running this producer with the same registration identity
+ * completes the registration against the EXISTING snapshot bytes — identity,
+ * timestamps and ownership are preserved, never rewritten. An existing
+ * snapshot with a DIFFERENT registration identity refuses (it belongs to
+ * another registration).
+ *
+ * The caller must pin the artifact store to the harness root first
+ * (`setArtifactStore(createFsStore(harnessDir))`) when the active store's
+ * root could differ — the routed writers fail loud on a path mismatch.
+ */
+export declare function registerPlanWorkflow(workflowId: string, options: RegisterPlanWorkflowOptions): Promise<RegisterPlanWorkflowResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.9.3",
+  "version": "3.10.0",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {