@mstar-harness/engine 3.9.4 → 3.10.1

package/dist/index.d.ts

@@ -45,8 +45,8 @@ export type { PlanRow, ResidualEntry, StatusDoc, StatusV2Doc, WorkflowEntry, } f
 export { normalizeSeverity, registerWorkflow, resolveCompassEnforcement, resolveMstarcEnforcement, resolveRepoEnforcement, unregisterWorkflow, validatePlanRow, validateResidual, validateStatus, validateStatusV2, validateWorkflowEntry, } from "./status.js";
 export type { ClaimLeaseFields, ExecutionLease, ExecutionLeaseLocations, IntegrationMergeLease, LeaseTransition, LeaseVerifyResult, } from "./lease.js";
 export { canSteal, claimLease, planExecutionLeaseLocations, releaseLease, sameHolderResume, validateExecutionLease, validateIntegrationMergeLease, verifyPlanExecutionLease, withStatusWriteLock, } from "./lease.js";
-export type { CloseWorkflowOptions, WorkflowBranchAnchors, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, WorkflowSnapshotRead, } from "./workflow.js";
-export { closeWorkflow, isTerminalSnapshot, LEGACY_WORKTREE_PATH_CODE, WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, readWorkflowSnapshot, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
+export type { CloseWorkflowOptions, DeclareWorkflowDeliveryKindOptions, DeliveryRegistrationEvidence, RecordWorkflowDeliveryOptions, RecordWorkflowDeliveryResult, RegisterPlanWorkflowOptions, RegisterPlanWorkflowResult, WorkflowBranchAnchors, WorkflowCompoundOutcome, WorkflowDeliveryEvidence, WorkflowDeliveryKind, WorkflowExecutionPolicy, WorkflowLifecycleStatus, WorkflowLifecycleType, WorkflowSnapshot, WorkflowSnapshotRead, } from "./workflow.js";
+export { assertDeliveryRegistrationCoherence, closeWorkflow, consultDeliveryEvidence, declareWorkflowDeliveryKind, isTerminalSnapshot, LEGACY_WORKTREE_PATH_CODE, recordWorkflowDelivery, registerPlanWorkflow, WORKFLOW_COMPOUND_OUTCOMES, WORKFLOW_DELIVERY_KINDS, WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHOT_FILE, WORKFLOW_TERMINAL_STATUSES, readWorkflowSnapshot, validateWorkflowSnapshot, writeWorkflowSnapshot, } from "./workflow.js";
 export type { CleanupDecision, CleanupFacts, CleanupTarget, CleanupTargetKind, } from "./cleanup.js";
 export { planWorktreeCleanup } from "./cleanup.js";
 export type { EvidenceArtifactFact, EvidenceAssessment, EvidenceCaptureRequest, EvidenceCoverage, EvidenceEnvironmentKey, EvidenceExpectation, EvidenceInputEntry, EvidenceInputSnapshot, EvidenceInputSpec, EvidenceLimits, EvidenceLog, EvidenceOutcome, EvidenceToolFingerprint, SddEvidenceRecord, } from "./evidence.js";
@@ -87,5 +87,5 @@ export type { ArtifactDoc, ArtifactKind, ArtifactRef, ArtifactStore } from "./st
 export { assertFsStorePath, createFsStore, getArtifactStore, loadStoreModule, resolveArtifactPath, setArtifactStore } from "./store.js";
 export { collectActiveLifecycleBranches, scanActiveLifecycleBranches, type ActiveLifecycleScan } from "./lifecycle-branches.js";
 export { WorkflowSnapshotValidationError } from "./workflow.js";
-export { CoordinationError, bindPlanSession, mutatePlanCoordination, readCoordinatedArtifact, readPlanCoordination, readSessionEnvelope, replaceCoordinatedArtifact, resolvePlanScope, resolveProcessHarnessDir, } from "./coordination.js";
-export type { BindPlanSessionInput, CoordinatedReplacement, CoordinationRequest, CoordinationResult, CoordinationRole, CoordinationSession, HandoffEvidence, PlanCoordinationOperation, PlanCoordinationView, PlanScopeInput, PrepareCoordinationRequest, ProgressCoordinationRequest, ResidualAddCoordinationRequest, ResidualCloseCoordinationRequest, ResidualInput, ResolvedPlanScope, VersionedArtifact, } from "./coordination.js";
+export { CoordinationError, amendPrepareWorkflow, bindPlanSession, mutatePlanCoordination, readCoordinatedArtifact, readPlanCoordination, readSessionEnvelope, replaceCoordinatedArtifact, resolvePlanScope, resolveProcessHarnessDir, showPrepareWorkflow, } from "./coordination.js";
+export type { BindPlanSessionInput, CoordinatedReplacement, CoordinationRequest, CoordinationResult, CoordinationRole, CoordinationSession, HandoffEvidence, PlanCoordinationOperation, PlanCoordinationView, PlanScopeInput, PrepareCoordinationRequest, PreparePlanAppend, PrepareWorkflowPatch, PrepareWorkflowResult, PrepareWorkflowView, ProgressCoordinationRequest, ResidualAddCoordinationRequest, ResidualCloseCoordinationRequest, ResidualInput, ResolvedPlanScope, VersionedArtifact, } from "./coordination.js";

package/dist/iteration.d.ts

@@ -120,7 +120,39 @@ export declare function evaluatePhaseGate(snapshotDoc: SnapshotDoc, compassDoc:
  * `evaluatePhaseGate` / `PhaseGateResult` (Phase 2–5 exit codes stay
  * intact). Stable machine codes: `PHASE6_NOT_TERMINAL`,
  * `PHASE6_ROOT_ENTRY_PRESENT`, `PHASE6_DANGLING_LEASE`,
- * `PHASE6_INVALID_SNAPSHOT`, `PHASE6_INVALID_ROOT`.
+ * `PHASE6_INVALID_SNAPSHOT`, `PHASE6_INVALID_ROOT`,
+ * `PHASE6_DELIVERY_KIND_UNREGISTERED`, `PHASE6_DELIVERY_EVIDENCE_INCOMPLETE`,
+ * `PHASE6_PLAN_ROW_NOT_DONE`.
+ *
+ * Plan-type delivery-kind consultation (seam S3, contract §6 S3 + §4g): a
+ * terminal `type: plan` snapshot also consults the delivery evidence recorded
+ * over the lifecycle — plan rows are the owned plan (no compass input) and
+ * remote merge verification stays excluded by contract (§4f is the PM's
+ * separate check). The consultation is the shared pure function
+ * `consultDeliveryEvidence` (workflow.ts), which `closeWorkflow` runs before
+ * writing a terminal snapshot — one implementation, so this read-only gate
+ * and the write path can never disagree. It runs for a `completed` close ONLY:
+ * `failed`/`stopped` closes are never demanded delivery evidence (§5 — failure
+ * closes through its explicit status with a recorded reason and is never
+ * treated as delivered), exactly as `closeWorkflow` preserves an
+ * already-terminal snapshot unchanged without consulting; the type-generic
+ * dangling-lease probe still covers every terminal status. The kind is never
+ * inferred (§1): a plan workflow without a registered `delivery_kind` has no
+ * close-verifiable delivery evidence — for a legacy terminal snapshot this is
+ * outside the gate's automated recovery, because the create-only register
+ * cannot backfill terminal bytes, so the remediation names the owner
+ * snapshot-amendment path (the audit-promotion grandfather population is
+ * disclosed there) instead of the register verb — and a registered kind with
+ * incomplete delivery evidence (`development` without its registered
+ * source/target branches, its compound disposition, its PR identity or the
+ * PM's verified-merge record; `verification/report-only` without the recorded
+ * completion policy or its fulfilment record) refuses the same way — missing
+ * fields are incomplete registration, not an exempt workflow. A `completed`
+ * close additionally requires every owned plan row `Done` (the post-write
+ * mirror of `closeWorkflow`'s all-rows-Done guard, §3 terminal stage);
+ * `failed`/`stopped` lifecycles keep their statuses and row states (§5 —
+ * never rewritten as successfully completed). Every refusal is read-only: the
+ * workflow stays registered/resumable.
  */
 export declare function evaluatePostMergeClose(snapshotDoc: SnapshotDoc, rootDoc: unknown): GateResult;
 /**

package/dist/migrate.d.ts

@@ -1,6 +1,6 @@
 import { type ProjectRegisterDoc } from "./project.js";
 import { type StatusV2Doc } from "./status.js";
-import { type WorkflowLifecycleStatus, type WorkflowLifecycleType, type WorkflowSnapshot } from "./workflow.js";
+import { type WorkflowDeliveryKind, type WorkflowLifecycleStatus, type WorkflowLifecycleType, type WorkflowSnapshot } from "./workflow.js";
 /** Root status file name inside `{HARNESS_DIR}` (v1 input / v2 output). */
 export declare const MIGRATE_STATUS_FILE = "status.json";
 /** Legacy v1 root copy written by migration (never deleted without it). */
@@ -62,6 +62,21 @@ export type MigrateOptions = {
     dryRun?: boolean;
     /** Project id for the register/roadmap home (default `_default`). */
     projectId?: string;
+    /**
+     * Delivery kind declared for the ACTIVE standalone plan snapshots this lift
+     * produces (contract §1/§4a). A v1 `plans[]` row becomes a `type: plan`
+     * lifecycle, so its delivery kind is declared at registration and never
+     * inferred: the CLI/API caller passes it explicitly, and a lift that would
+     * create an active kind-less plan snapshot without it is refused (see
+     * `MigratePlan.deliveryKindRequired`).
+     */
+    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 for `verification/report-only` lifts. Required for that kind. */
+    completionPolicy?: string;
 };
 /** Full migration plan: every write is described; the executor applies it. */
 export type MigratePlan = {
@@ -97,6 +112,30 @@ export type MigratePlan = {
     /** Human message (no-op reason when `alreadyMigrated`). */
     message: string;
     snapshots: MigrateSnapshot[];
+    /**
+     * Ids of the ACTIVE (running/paused) standalone plan snapshots this lift
+     * would create WITHOUT a declared delivery kind — i.e. the v1 rows lifted
+     * before the operator passed `opts.deliveryKind`. Non-empty means the plan is
+     * NOT applicable: `applyMigratePlan` refuses it (a close path could never
+     * complete such a lifecycle), and the CLI reports the missing flag as usage
+     * (exit 2) before any write. Terminal (completed) lifted snapshots are exempt
+     * — a finished lifecycle declares nothing (§1; the legacy terminal dead end
+     * is documented, not amended here).
+     */
+    deliveryKindRequired: string[];
+    /**
+     * Ids of the ACTIVE (running/paused) standalone plan snapshots the single
+     * `opts.deliveryKind` declaration would be stamped onto when MORE THAN ONE
+     * lift qualifies. The declaration is one (kind, anchors, policy) tuple — one
+     * delivery identity, and the kind is per-workflow registration evidence (§1)
+     * — so it cannot describe several lifecycles at once. Non-empty means the
+     * plan is NOT applicable: `applyMigratePlan` refuses it and the CLI reports
+     * the ambiguity as usage (exit 2) before any write, so the operator migrates
+     * the tree in batches of one declared plan instead of pinning one identity
+     * onto several. Empty when no declaration was given or exactly one lift
+     * qualifies; terminal lifts are exempt like `deliveryKindRequired`.
+     */
+    deliveryKindAmbiguous: string[];
     notesFiles: MigrateNotesFile[];
     register: MigrateRegister | null;
     roadmap: MigrateRoadmap | null;

package/dist/sdd.d.ts

@@ -253,7 +253,15 @@ export type SddActionKind = "source" | "artifact" | "launch";
  * the context must then match the verified lease exactly. Without an
  * active lease (no row, or a non-InProgress row without lease), the
  * standalone branch policy applies (`assertBranchAlignment`) — an
- * InProgress row without lease is the orphan refusal.
+ * InProgress row without lease is the orphan refusal. The one admission
+ * exception (lifecycle contract §4b/§6 S2): on a register-governed harness
+ * root (readable v2 `status.json` `workflows[]`), a plan with NO active
+ * registered row is an unregistered normal-route plan — refused with
+ * `sdd.context.plan-not-registered` and the register/recovery path; branch
+ * alignment never substitutes for registration, and a plan id retained only
+ * in a terminal snapshot is refused the same way (a retained row is history,
+ * not registration evidence — §4b). Roots without a v2 register keep the
+ * standalone policy byte-for-byte.
  *
  * Throws `SddScriptError` — exit 2 when the declared context itself is
  * malformed (non-absolute path, identity/composition mismatch, missing plan

package/dist/workflow.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -10,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];
 /**
@@ -24,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;
 };
@@ -72,6 +137,27 @@ export type WorkflowSnapshot = {
      * 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;
@@ -168,6 +254,55 @@ export type WriteWorkflowSnapshotOptions = {
 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;
     /**
@@ -182,9 +317,196 @@ export type CloseWorkflowOptions = {
 };
 /**
  * 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.4",
+  "version": "3.10.1",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {