@mstar-harness/engine 3.9.2 → 3.9.4

package/dist/coordination-write.d.ts

@@ -0,0 +1,170 @@
+import type { ValidationResult } from "./core.js";
+/** Stable refusal codes of the scoped coordination surface (spec §C4). */
+export declare const COORDINATION_ERROR_CODES: readonly ["coordination.harness-not-found", "coordination.workflow-not-found", "coordination.plan-not-found", "coordination.scope-mismatch", "coordination.path-mismatch", "coordination.assignment-invalid", "coordination.assignment-stale", "coordination.not-prepared", "coordination.duplicate-holder", "coordination.session-mismatch", "coordination.session-not-found", "coordination.session-role", "coordination.version-conflict", "coordination.expected-version-required", "coordination.invalid-transition", "coordination.invalid-input", "coordination.forbidden-field", "coordination.not-in-git", "coordination.git-unavailable", "coordination.git-proof", "coordination.evidence-stale", "coordination.integration-unresolved", "coordination.integration-diverged", "coordination.local-store-required", "coordination.direct-write-refused", "coordination.scoped-writer-required", "coordination.unknown-operation", "coordination.not-implemented", "coordination.lock", "coordination.store"];
+export type CoordinationErrorCode = (typeof COORDINATION_ERROR_CODES)[number];
+/**
+ * Stable exception of the coordination surface: `code` is the consumer
+ * contract, `details` carries the machine-readable context (path, expected,
+ * actual, holder, …). Exported publicly from `coordination.ts`.
+ */
+export declare class CoordinationError extends Error {
+    readonly code: CoordinationErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: CoordinationErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Non-empty trimmed string predicate. */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** `sha256:<64 lowercase hex>` of the exact bytes handed in. */
+export declare function artifactVersion(bytes: Buffer | string): string;
+/** SHA-256 (bare lowercase hex) of the exact bytes handed in. */
+export declare function sha256Bytes(bytes: Buffer | string): string;
+/** Artifact bytes read once: payload + byte version from that same read. */
+export type ArtifactBytes = {
+    payload: unknown;
+    version: string;
+};
+/**
+ * Read an artifact once and derive both payload and version from the same
+ * bytes. Missing file → `undefined` (the caller reports `absent`).
+ * Malformed JSON throws (never a silent empty document).
+ */
+export declare function readArtifactBytes(filePath: string): ArtifactBytes | undefined;
+/**
+ * Canonicalize a target: realpath when it exists (symlinks resolved), else the
+ * realpath of its nearest existing ancestor with the missing tail re-attached.
+ * Aliases therefore collapse onto the real protected file whether or not the
+ * leaf has been created yet, so a `json`/symlink ref can never dodge the
+ * boundary. A lexical fallback would do exactly that: a symlinked parent stays
+ * unresolved, the alias classifies as unprotected, and `put` creates the
+ * protected document through it.
+ *
+ * The same rule as `path.ts#canonicalizeNearestExisting`, restated here because
+ * `path.ts` imports this module (importing back would close an ESM cycle).
+ */
+export declare function canonicalTarget(target: string): string;
+/** Protected document class, decided by the caller's resolved path table. */
+export type ProtectedWriteKind = "root" | "snapshot" | "register";
+/**
+ * Run `fn` inside the private authorization context for `target`. Only the
+ * locked coordination/writer implementation calls this; the context records
+ * canonical target + operation, never a caller-supplied boolean, and nested
+ * authorizations stack (a residual write authorizes both the snapshot and
+ * the register it touches).
+ */
+export declare function withProtectedWrite<T>(target: string, operation: "put" | "delete", fn: () => T | Promise<T>): Promise<T>;
+/** `true` when the current async context authorized exactly this target+operation. */
+export declare function isWriteAuthorized(target: string, operation: "put" | "delete"): boolean;
+/**
+ * Refuse an un-authorized write to a protected target (spec §C4). The
+ * target's class is decided by the store's resolved path table (never by
+ * document content, which a caller could shape); the authorization is the
+ * private context alone.
+ */
+export declare function assertProtectedWriteAuthorized(target: string, operation: "put" | "delete", kind: ProtectedWriteKind): void;
+/** Exact-key contract: unknown keys anywhere are rejected before mutation. */
+export declare function assertExactKeys(value: Record<string, unknown>, allowed: readonly string[], what: string): void;
+/** Row/progress status a plan session may report (`progress` op). */
+export type PlanProgressStatus = "InProgress" | "InReview" | "Blocked";
+/** Progress payload a plan session reports on its own row. */
+export type PlanProgress = {
+    status: PlanProgressStatus;
+    summary: string;
+    /** Canonical absolute artifacts inside the plan's own plan/SDD area. */
+    evidence_paths: string[];
+    /** L2 track branches reported for this plan (never main/integration). */
+    track_branches?: string[];
+};
+/** Hash-pinned reference to a submitted evidence file. */
+export type EvidenceRef = {
+    path: string;
+    sha256: string;
+};
+/** Handoff lifecycle state (`PlanHandoff.state`). */
+export type HandoffState = "submitted" | "accepted" | "returned" | "integrating" | "merged" | "completed";
+/** QC review outcome recorded on a handoff. */
+export type HandoffQc = {
+    decision: string;
+    reports: EvidenceRef[];
+    consolidated: EvidenceRef;
+};
+/** QA verification outcome recorded on a handoff. */
+export type HandoffQa = {
+    gate: string;
+    decision: string;
+    report: EvidenceRef;
+};
+/** The single integration attempt recorded on a handoff. */
+export type HandoffIntegration = {
+    target_branch: string;
+    worktree_path: string;
+    base_sha: string;
+    started_at: string;
+    result_sha?: string;
+    verified_at?: string;
+};
+/** The durable review package of one plan (spec §B `PlanHandoff`). */
+export type PlanHandoff = {
+    id: string;
+    attempt: number;
+    state: HandoffState;
+    submitted_by: string;
+    submitted_at: string;
+    source_branch: string;
+    source_sha: string;
+    worktree_path: string;
+    review_base: string;
+    review_head: string;
+    qc: HandoffQc;
+    qa: HandoffQa;
+    accepted_by?: string;
+    accepted_at?: string;
+    returned_at?: string;
+    return_reason?: string;
+    integration?: HandoffIntegration;
+    completed_at?: string;
+};
+/** Coordinator-recorded preparation of one plan (spec §D `prepare`). */
+export type PreparedCoordination = {
+    assignment_path: string;
+    assignment_sha256: string;
+    plan_sha256: string;
+    qa_gate: string;
+    findings_cleanup: string;
+    prepared_by: string;
+    prepared_at: string;
+};
+/** A bound session: identity + the canonical envelope that proves it. */
+export type CoordinatorBinding = {
+    session_id: string;
+    session_file: string;
+    bound_at: string;
+};
+/** Snapshot-level coordination block (the workflow's coordinator). */
+export type SnapshotCoordination = {
+    coordinator: CoordinatorBinding;
+};
+/** Row-level coordination block (one plan). */
+export type RowCoordination = {
+    revision: number;
+    prepared?: PreparedCoordination;
+    session?: CoordinatorBinding;
+    progress?: PlanProgress;
+    handoff?: PlanHandoff;
+};
+export declare const HANDOFF_STATES: readonly HandoffState[];
+export declare const PLAN_PROGRESS_STATUSES: readonly PlanProgressStatus[];
+/** Validate a stored `PlanProgress` (`status`, `summary`, `evidence_paths`, `track_branches`). */
+export declare function validatePlanProgress(value: unknown, what?: string): ValidationResult[];
+/** Validate a stored `PlanHandoff`, including its state/field coherence. */
+export declare function validatePlanHandoff(value: unknown, what?: string): ValidationResult[];
+/** Validate a stored `PreparedCoordination`. */
+export declare function validatePreparedCoordination(value: unknown, what?: string): ValidationResult[];
+/** Validate one plan row's `coordination` object (spec §C2). */
+export declare function validateRowCoordination(value: unknown, what?: string): ValidationResult[];
+/** Validate a snapshot's top `coordination` block (spec §C2). */
+export declare function validateSnapshotCoordination(value: unknown, what?: string): ValidationResult[];
+/** Hash-pinned evidence reference for an absolute path, read from disk. */
+export declare function evidenceRefOf(filePath: string): EvidenceRef;
+/** Whether `value` is a well-formed `sha256:<64 hex>` artifact version. */
+export declare function isArtifactVersion(value: unknown): value is string;

package/dist/coordination.d.ts

@@ -0,0 +1,284 @@
+import { CoordinationError, type PlanProgress, type PreparedCoordination } from "./coordination-write.js";
+import { type PlanRow } from "./status.js";
+import { type ArtifactRef } from "./store.js";
+/**
+ * Re-exported from the storage layer because this module is the public entry
+ * point for the scoped writers: callers catch `CoordinationError` and branch
+ * on its `code` without importing the storage layer directly.
+ */
+export { CoordinationError };
+/** Bind roles: one coordinator per lifecycle, one plan session per plan. */
+export type CoordinationRole = "plan-pm" | "coordinator";
+/**
+ * Scope address, both forms required by spec §B: from a pinned Assignment
+ * path, or from a workflow/plan pair resolved through that row's `prepared`
+ * block. Both forms resolve to the same `ResolvedPlanScope`.
+ */
+export type PlanScopeInput = {
+    assignmentPath: string;
+} | {
+    workflowId: string;
+    planId: string;
+    harnessDir?: string;
+};
+/** The fully pinned plan scope (spec §B `ResolvedPlanScope`). */
+export type ResolvedPlanScope = {
+    harnessRoot: string;
+    workflowId: string;
+    planId: string;
+    /** `{WORKFLOW_DIR}/<workflow-id>/snapshot.json`. */
+    snapshotPath: string;
+    /** The plan markdown pinned by the Assignment `Plan Path`. */
+    planPath: string;
+    assignmentPath: string;
+    worktreePath: string;
+    workingBranch: string;
+    projectId: string;
+    sddDir: string;
+};
+/**
+ * Session envelope persisted at
+ * `{WORKFLOW_DIR}/<workflow-id>/sessions/<session-id>.json` (mode `0600`).
+ * The envelope is the durable proof of who holds the session: the snapshot
+ * stores its canonical path and every later call must present the same file.
+ */
+export type CoordinationSession = {
+    schema_version: 1;
+    role: CoordinationRole;
+    session_id: string;
+    workflow_id: string;
+    plan_id?: string;
+    harness_root: string;
+};
+/**
+ * Bind addressing (spec §B). A fresh bind never supplies a session path: the
+ * engine generates the session UUID and creates
+ * `<workflow-dir>/<workflow-id>/sessions/<session-id>.json` itself. An existing
+ * session is reached only through its explicit `resumePath`, which resumes
+ * read-only and never writes.
+ */
+export type BindPlanSessionInput = {
+    scope: PlanScopeInput;
+    cwd: string;
+} | {
+    coordinator: true;
+    workflowId: string;
+    harnessDir?: string;
+    cwd: string;
+} | {
+    resumePath: string;
+    cwd: string;
+};
+/** One artifact read: payload plus the byte version it was read at. */
+export type VersionedArtifact = {
+    payload: unknown;
+    version: string;
+};
+/** Everything `mstar plan show` needs, in one read. */
+export type PlanCoordinationView = {
+    /** Row `coordination.revision` (`0` when the row is not yet coordinated). */
+    revision: number;
+    /** `sha256:…` of the snapshot bytes, or `"absent"`. */
+    snapshot_version: string;
+    /** `sha256:…` of this plan's project register bytes, or `"absent"`. */
+    register_version: string;
+    /** `null` while the row carries no `prepared` block. */
+    scope: ResolvedPlanScope | null;
+    row: PlanRow;
+    prepared?: PreparedCoordination;
+    session: CoordinationSession;
+    session_file: string;
+    /** Operations this session may run now — implemented operations only. */
+    allowed_operations: string[];
+};
+/** Success shape of a coordination call. */
+export type CoordinationResult = {
+    ok: true;
+    operation: string;
+    session: CoordinationSession;
+    session_file: string;
+    /** `claimed` / `resumed` / `prepared` / `progressed` / `residual-added` / `residual-closed`. */
+    outcome?: string;
+    view?: PlanCoordinationView;
+};
+/** One residual being registered: the nine v1 fields (+ optional `detail_doc`). */
+export type ResidualInput = {
+    id: string;
+    title: string;
+    severity: string;
+    source: string;
+    scope: string;
+    decision: string;
+    owner: string;
+    target: string;
+    tracking: string;
+    detail_doc?: string;
+};
+export type PrepareCoordinationRequest = {
+    kind: "prepare";
+    /** The plan's pinned Assignment (absolute). */
+    assignmentPath: string;
+    expectedRevision: number;
+};
+export type ProgressCoordinationRequest = {
+    kind: "progress";
+    progress: PlanProgress;
+    expectedRevision: number;
+};
+export type ResidualAddCoordinationRequest = {
+    kind: "residual-add";
+    entries: ResidualInput[];
+    expectedRegisterVersion: string;
+    /** Optional extra guard: the row revision must still match. */
+    expectedRevision?: number;
+};
+export type ResidualCloseCoordinationRequest = {
+    kind: "residual-close";
+    entryId: string;
+    note: string;
+    expectedRegisterVersion: string;
+    expectedRevision?: number;
+};
+/**
+ * Handoff evidence (spec §D). Slice A types it so the union is stable; the
+ * operations that consume it arrive with the handoff slice.
+ */
+export type HandoffEvidence = {
+    source_sha: string;
+    review_base: string;
+    review_head: string;
+    qc: {
+        decision: "Approve" | "Approve with residuals";
+        reports: string[];
+        consolidated: string;
+    };
+    qa: {
+        gate: "mandatory" | "pm-acceptance";
+        decision: "pass";
+        report: string;
+    };
+};
+/**
+ * The operation surface (spec §B): every kind is implemented and typed, so an
+ * unknown shape is refused as `coordination.invalid-input` rather than
+ * silently accepted.
+ */
+export type PlanCoordinationOperation = {
+    kind: "prepare";
+    assignmentPath: string;
+} | {
+    kind: "progress";
+    progress: PlanProgress;
+} | {
+    kind: "residual-add";
+    entries: ResidualInput[];
+    expectedRegisterVersion: string;
+} | {
+    kind: "residual-close";
+    entryId: string;
+    note: string;
+    expectedRegisterVersion: string;
+} | {
+    kind: "handoff";
+    evidence: HandoffEvidence;
+} | {
+    kind: "accept";
+    handoffId: string;
+} | {
+    kind: "return";
+    handoffId: string;
+    reason: string;
+} | {
+    kind: "integration-start";
+    handoffId: string;
+} | {
+    kind: "integration-accept";
+    handoffId: string;
+} | {
+    kind: "complete";
+    handoffId: string;
+} | {
+    kind: "reconcile";
+    handoffId: string;
+};
+/** One whole coordination request: one session, one operation, one precondition. */
+export type CoordinationRequest = {
+    sessionPath: string;
+    /** Required for a coordinator session; never another plan for a plan session. */
+    planId?: string;
+    /** The selected row's `coordination.revision` from `show` (absent row = 0). */
+    expectedRevision: number;
+    operation: PlanCoordinationOperation;
+};
+/** Coordinator replacement of a coordinated artifact (spec §B). */
+export type CoordinatedReplacement = {
+    harnessRoot: string;
+    ref: ArtifactRef;
+    payload: unknown;
+    /** Byte version the writer expects (`sha256:…`, or `absent` to create). */
+    expectedVersion: string;
+    /** Required for snapshot replacement (the coordinator session envelope). */
+    sessionPath?: string;
+};
+/**
+ * The process-wide harness root (spec §C1): resolved from the **main**
+ * worktree's root, never from the checkout the process happens to sit in.
+ * This is the fix for the process-root bug — a process inside a linked
+ * worktree must not resolve the worktree's own `.mstar`.
+ *
+ * Returns `null` when no harness root is resolvable (the unscoped CLI keeps
+ * its existing non-Git fallback). Throws `coordination.not-in-git` when the
+ * cwd is provably a linked checkout (a `.git` **file**) whose main worktree
+ * cannot be read — falling back to local artifacts there is exactly the bug.
+ */
+export declare function resolveProcessHarnessDir(cwd?: string, harnessDir?: string): string | null;
+/**
+ * Resolve the plan scope (spec §B). Form A pins the scope from the Assignment
+ * itself; form B starts from `{workflowId, planId}` and reads the pinned
+ * Assignment path out of that row's `prepared` block — never "the first
+ * unfinished row".
+ */
+export declare function resolvePlanScope(input: PlanScopeInput, cwd?: string): Promise<ResolvedPlanScope>;
+/** Read and validate a session envelope (throws `coordination.session-*`). */
+export declare function readSessionEnvelope(sessionPath: string): CoordinationSession;
+/**
+ * Read this session's plan coordination view (spec §B). A coordinator session
+ * must select a plan; a plan session reads only its own row. A row that is not
+ * yet prepared yields `scope: null` and the raw row.
+ */
+export declare function readPlanCoordination(sessionPath: string, planId?: string, cwd?: string): Promise<PlanCoordinationView>;
+/**
+ * Read one coordinated artifact plus its byte version, from a **single** byte
+ * read. `payload` is `undefined` and `version` is `"absent"` when the document
+ * does not exist. Snapshot payloads are validated before they are handed out.
+ */
+export declare function readCoordinatedArtifact(harnessRoot: string, ref: ArtifactRef): Promise<VersionedArtifact>;
+/**
+ * Bind a session (spec §C2). A fresh bind creates the envelope, claims the L1
+ * lease and records the binding in the same snapshot commit; an existing
+ * envelope is a **read-only** resume that only re-verifies the binding.
+ */
+/**
+ * Bind a session (spec §B, §C2). Fresh addressing never supplies a session
+ * path: the engine generates the UUID and creates the envelope. `resumePath`
+ * names an existing envelope and resumes read-only.
+ */
+export declare function bindPlanSession(input: BindPlanSessionInput): Promise<CoordinationResult>;
+/**
+ * Run one coordinated mutation (spec §B/§D). Every call re-authenticates the
+ * session from its envelope, re-checks the Assignment hash, enforces the
+ * revision/register precondition under the lock, and writes through
+ * `withProtectedWrite`. The operation surface is a closed discriminated union:
+ * an unknown key anywhere is rejected before any state is touched.
+ */
+export declare function mutatePlanCoordination(request: CoordinationRequest): Promise<CoordinationResult>;
+/**
+ * Replace a coordinated artifact with an exact-version precondition (spec §B,
+ * §C4 line 156). Snapshot replacement goes through the canonical snapshot
+ * writer (coordinator session, phase-only delta, locked CAS); the root status
+ * and a project register are written with the same byte-version CAS under
+ * root → snapshot → destination locks, refusing any document that carries
+ * coordinated ownership. `review`/`json` are not coordinated artifacts, so
+ * they refuse explicitly instead of silently no-opping.
+ */
+export declare function replaceCoordinatedArtifact(input: CoordinatedReplacement): Promise<VersionedArtifact>;