@mstar-harness/engine 3.9.3 → 3.10.0

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,3 +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, 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/lease.d.ts

@@ -42,7 +42,7 @@ export type ClaimLeaseFields = {
 export type LeaseTransition = {
     ok: boolean;
     row: PlanRow;
-    outcome?: "claimed" | "resumed" | "released";
+    outcome?: "claimed" | "resumed" | "released" | "transferred";
     violations: ValidationResult[];
 };
 /**
@@ -103,6 +103,18 @@ export declare function claimLease(row: PlanRow, holder: string, fields: ClaimLe
  * protocol); the caller enforces that ordering around the locked update.
  */
 export declare function releaseLease(row: PlanRow, holder: string): LeaseTransition;
+/**
+ * Holder transfer for the scoped coordination `accept` transition (spec §D):
+ * move an ACTIVE `execution_lease` to another holder verbatim — same
+ * `claimed_at`, `worktree_path`, `working_branch`, extra fields preserved;
+ * only `holder` changes. Deliberately NOT `claimLease`: there is no
+ * Todo/Blocked → InProgress transition and no steal path here. The locked
+ * coordination writer has already authenticated the receiving holder as the
+ * workflow's coordinator, so `from` must still match the stored holder — a
+ * mismatched `from` is `lease.transfer.other-holder` and leaves the row
+ * untouched.
+ */
+export declare function transferLease(row: PlanRow, from: string, to: string): LeaseTransition;
 /**
  * Same-holder resume check (status-and-residuals.md § Claim-before-`InProgress`
  * #2): `true` iff the stored lease `holder` equals the session `holder`.

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 = {
@@ -84,11 +99,43 @@ export type MigratePlan = {
    */
     projectDir: string;
     dryRun: boolean;
+    /**
+     * Byte version (`sha256:…`, or `"absent"`) of the source `status.json` this
+     * plan was derived from (spec §C3 source-version CAS). The executor
+     * re-reads the source under the root lock before its first write and
+     * refuses a root whose bytes moved after planning — a still-v1 document
+     * changed by another writer is never silently replaced.
+     */
+    sourceVersion: string;
     /** Root status.json already at `version: 2` -> nothing to plan/apply. */
     alreadyMigrated: boolean;
     /** 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/path.d.ts

@@ -1,4 +1,4 @@
-import { type ValidationResult } from "./core.js";
+import type { ValidationResult } from "./core.js";
 /**
  * Options for `resolveHarnessDir`.
  */
@@ -164,11 +164,20 @@ export declare function resolveScaffoldDirs(root: string): {
  * `.mstarc`-declared `project_dir`) with a valid `roadmap.md` + empty
  * `residuals.json` (plan-conventions § 初始化 Plan 目录;
  * mstar-project-governance § `_default` 回退). Idempotent: an existing
- * non-empty `status.json`, `roadmap.md`, or `residuals.json` is never
- * clobbered; re-running on an initialized tree only creates missing
- * pieces. Returns the absolute resolved harness dir.
- */
-export declare function scaffoldHarness(root: string): string;
+ * `roadmap.md` is never clobbered, and re-running on an initialized tree only
+ * creates missing pieces. Returns the absolute resolved harness dir.
+ *
+ * The two coordination documents (`status.json`, `_default/residuals.json`)
+ * are written create-only through the active `ArtifactStore` inside the
+ * private protected-write context, serialized on the target's
+ * `withStatusWriteLock` (spec §C4): a concurrent writer's bytes are never
+ * replaced, and an existing empty/malformed document fails validation instead
+ * of being silently reinitialized. Callers whose target root differs from the
+ * active store's root MUST `setArtifactStore(createFsStore(<harnessRoot>))`
+ * first (same contract as the other routed writers). No scoped session or
+ * coordination record is created here.
+ */
+export declare function scaffoldHarness(root: string): Promise<string>;
 /**
  * Harness kind for the gitignore fence — the canonical snippet is per
  * harness layout (plan-conventions § Git 跟踪策略): `.mstar/` (default) and

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/status.d.ts

@@ -63,6 +63,18 @@ export type PlanRow = {
     execution_lease?: unknown;
     [key: string]: unknown;
 };
+/**
+ * Every plan id a `plans[]` row can be addressed by (status-and-residuals.md
+ * § Compatibility: read accepts `id` or the legacy `plan_id`; write prefers
+ * `id`). Both non-empty keys are reported, in canonical-first order: a row
+ * whose two keys disagree is ambiguous (`status.plan-row.dual-id`), and an
+ * ownership guard keyed on one of them would let the other escape protection.
+ * Empty strings never count; a non-object or a row carrying neither key has
+ * no address.
+ */
+export declare function rowPlanIds(row: unknown): string[];
+/** The canonical single plan id of a row — `id`, else legacy `plan_id`. */
+export declare function rowPlanId(row: unknown): string | undefined;
 /**
  * Normalize a residual `severity` value for reading/rolling up
  * (status-and-residuals.md § severity 5 + rollup `norm_sev`):
@@ -156,6 +168,11 @@ export declare const validateStatus: typeof validateStatusV2;
  * an invalid entry would fail `validateStatusV2` anyway, but the explicit
  * gate keeps the pre-lock fail-fast contract of `registerWorkflow`).
  *
+ * Replacing an existing entry additionally takes that entry's snapshot lock
+ * (spec §C3 root → snapshot order, `withRegisteredSnapshotLock`) and holds it
+ * across the root write; callers must therefore hold the root lock only, not
+ * a snapshot lock.
+ *
  * Async-only (architect-locked 2026-08-27): the durable write goes through
  * `getArtifactStore().put({ kind: "status", key: "root", ... })` inside the
  * caller's lock — the store is the persist backend, never a second lock.
@@ -185,7 +202,10 @@ export declare function registerWorkflow(root: string, entry: WorkflowEntry): Pr
  * `withStatusWriteLock`, bumping root `updated_at` only when an entry was
  * actually removed. The final document is validated (removal-at-terminal
  * invariant included) before the write — a v1 root is refused with the
- * `mstar migrate` hint.
+ * `mstar migrate` hint. Removing a registered entry additionally takes that
+ * entry's snapshot lock (spec §C3 root → snapshot order) and holds it across
+ * the root write, so the coordination check cannot be raced by a concurrent
+ * bind.
  *
  * Fails loud when the active FsStore would resolve its
  * `status.json` to a path other than the caller's root — the no-op branches