@mstar-harness/engine 3.9.3 → 3.9.4

package/dist/index.d.ts

@@ -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, 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";

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

@@ -84,6 +84,14 @@ 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`). */

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/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

package/dist/workflow.d.ts

@@ -1,4 +1,5 @@
 import type { GateResult, 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). */
@@ -63,7 +64,17 @@ 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;
 };
+/** 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 +125,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 +165,26 @@ 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;
 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 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.
  */
 export declare function closeWorkflow(workflowId: string, dir: string, opts: CloseWorkflowOptions): Promise<WorkflowSnapshot>;

package/package.json

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