@mstar-harness/engine 3.4.1 → 3.5.1

package/dist/index.d.ts

@@ -61,5 +61,7 @@ export type { DetectResult, HostAdapter, HostId, SkillRootPaths, ToolSignal } fr
 export { detectHost, resolveSkillRoot } from "./host.js";
 export type { FiveQuestionMode, FiveQuestionSection } from "./skill-authoring.js";
 export { FIVE_QUESTION_SECTIONS, RUNTIME_HEADING_ALIASES, lintFiveQuestion, lintFrontmatter, resolveAssetPath, stripFrontmatter, } from "./skill-authoring.js";
-export type { MergeClass, PrReportTarget, PrReviewSeatPromptOptions, PrReviewSizing, PrReviewTier, PrTierKeyword, PrSizeBand, PrTallyInput, PrTallyResult, PrVerdict, ResolvePrReviewTierInput, ReviewChangesetMode, ReviewInlineComment, ReviewPostPlan, ValidateFindingDocOptions, } from "./prreview.js";
-export { MERGE_CLASSES, PR_VERDICTS, REVIEW_EMOJI, computePrTally, pickReviewBranchName, planReviewPost, preflightChangeset, prReviewReportPath, prReviewSeatPrompt, prReviewSizing, resolvePrReviewTier, validateFindingDoc, validatePrReviewReport, } from "./prreview.js";
+export type { MergeClass, MstarReviewFinding, MstarReviewV1, PrReportTarget, PrReviewSeatPromptOptions, PrReviewSizing, PrReviewTier, PrTierKeyword, PrSizeBand, PrTallyInput, PrTallyResult, PrVerdict, ResolvePrReviewTierInput, ReviewChangesetMode, ReviewInlineComment, ReviewPostPlan, ValidateFindingDocOptions, } from "./prreview.js";
+export { MERGE_CLASSES, PR_VERDICTS, REVIEW_EMOJI, computePrTally, pickReviewBranchName, planReviewPost, preflightChangeset, prReviewReportPath, prReviewSeatPrompt, prReviewSizing, resolvePrReviewTier, synthesizeReview, validateFindingDoc, validateMstarReviewV1, validatePrReviewReport, } from "./prreview.js";
+export type { ArtifactDoc, ArtifactKind, ArtifactRef, ArtifactStore } from "./store.js";
+export { assertFsStorePath, createFsStore, getArtifactStore, loadStoreModule, resolveArtifactPath, setArtifactStore } from "./store.js";

package/dist/project.d.ts

@@ -138,9 +138,13 @@ export type CloseProjectRegisterEntryOpts = {
  * duplicate-id detection), set each entry's `source_plan` to the used key
  * (provenance must match the entries key; the caller cannot know the bumped
  * key beforehand), append preserving every other key, validate the whole
- * register with `validateProjectRegister`, then `writeJson` (atomic
- * temp+rename — never `open(w)`). Fail-loud: any validation failure throws
- * and the register is left untouched. Returns the key actually used.
+ * register with `validateProjectRegister`, then `ArtifactStore.put`
+ * (FsStore uses `writeJson` — atomic temp+rename; never `open(w)`).
+ * Fails loud (qc3 F-201) when the active FsStore would resolve a register
+ * path other than `<projectDir>/residuals.json` — callers whose target root
+ * differs from the active store's root MUST
+ * `setArtifactStore(createFsStore(root))` first. Fail-loud: any validation
+ * failure throws and the register is left untouched. Returns the key used.
  */
 export declare function appendProjectRegisterEntries(opts: AppendProjectRegisterEntriesOpts): Promise<{
     ok: true;
@@ -151,8 +155,11 @@ export declare function appendProjectRegisterEntries(opts: AppendProjectRegister
  * Task 1): under `withStatusWriteLock(registerPath, ...)`, find `entryId` in
  * `entries[planKey]` (absent → throw), set `lifecycle: resolved` +
  * `closed_at: <today YYYY-MM-DD>` + `closure_note`, validate the whole
- * register with `validateProjectRegister`, then `writeJson` (atomic
- * temp+rename). Fail-loud: an invalid register throws and nothing is written.
+ * register with `validateProjectRegister`, then `ArtifactStore.put`
+ * (FsStore uses `writeJson` — atomic temp+rename).
+ * Fails loud (qc3 F-201) when the active FsStore would resolve a register
+ * path other than `<projectDir>/residuals.json`. Fail-loud: an invalid
+ * register throws and nothing is written.
  */
 export declare function closeProjectRegisterEntry(opts: CloseProjectRegisterEntryOpts): Promise<{
     ok: true;

package/dist/prreview.d.ts

@@ -56,6 +56,71 @@ export type PrTallyResult = {
  * never overrides the verdict (override invariant).
  */
 export declare function computePrTally(input: PrTallyInput): PrTallyResult;
+/**
+ * One accepted PR-review finding in the `mstar.review/v1` envelope (SP3 §
+ * Schema). `mergeClass` is harness vocab (MERGE_CLASSES); `title`/`body`
+ * are non-empty strings; the rest are optional.
+ */
+export type MstarReviewFinding = {
+    mergeClass: MergeClass;
+    category?: string;
+    file_path?: string | null;
+    line_start?: number | null;
+    line_end?: number | null;
+    title: string;
+    body: string;
+    fingerprint_hint?: string;
+};
+/**
+ * The `mstar.review/v1` envelope (SP3 § Schema) — a parseable review
+ * document with harness vocab, sibling to the Markdown pr-review report.
+ * `verdict` is PR_VERDICTS; `tally` (when present) must be a full
+ * `PrTallyResult` (shape-checked) whose `verdict` must equal the top-level
+ * `verdict` (consistency rule).
+ */
+export type MstarReviewV1 = {
+    schema: "mstar.review/v1";
+    verdict: PrVerdict;
+    summary_md: string;
+    tally?: PrTallyResult;
+    findings: MstarReviewFinding[];
+    target?: {
+        owner?: string;
+        repo?: string;
+        pr?: number;
+        head_sha?: string;
+    };
+};
+/**
+ * Validate a `mstar.review/v1` envelope (SP3 § Schema). Fail-loud sibling
+ * of {@link validatePrReviewReport} (the Markdown report validator) —
+ * shares PR_VERDICTS / MERGE_CLASSES only, never reuses the Markdown
+ * parser. Inspector M1 vocab (`comment|request_changes|approve`,
+ * `critical|warning|suggestion|info`, or a stray `severity` key) is
+ * rejected with `review.inspector-vocab`; a provided `tally` is
+ * shape-checked against the `PrTallyResult` {@link computePrTally} produces
+ * (verdict vocab, integer `scorePct` in [0, 100], four non-negative-integer
+ * counts, string `chatHeader`) and a malformed one is rejected with
+ * `review.tally-malformed` (shape only — no arithmetic consistency); a
+ * `tally.verdict` disagreeing with the top-level `verdict` is rejected
+ * with `review.verdict-tally-mismatch` (consistency rule, architect-locked).
+ */
+export declare function validateMstarReviewV1(doc: unknown): GateResult;
+/**
+ * Fold already-vetted findings into a complete `mstar.review/v1` envelope
+ * (SP3 § synthesizeReview). Pure and synchronous — verdict/tally come ONLY
+ * from {@link computePrTally}; no I/O, no GitHub, no store, no seat
+ * dispatch. `findings` pass through untouched; `target` is carried when
+ * provided. When `summary_md` is omitted, {@link defaultReviewSummary}
+ * builds the locked deterministic template.
+ */
+export declare function synthesizeReview(input: {
+    findings: MstarReviewV1["findings"];
+    summary_md?: string;
+    unverifiedCount?: number;
+    unmetAc?: PrTallyInput["unmetAc"];
+    target?: MstarReviewV1["target"];
+}): MstarReviewV1;
 /**
  * Which reviewed artifact the report (or evidence file) belongs to.
  *

package/dist/status.d.ts

@@ -154,8 +154,16 @@ export declare const validateStatus: typeof validateStatusV2;
  * acquiring the lock; this helper asserts it as a safety net (cheap —
  * an invalid entry would fail `validateStatusV2` anyway, but the explicit
  * gate keeps the pre-lock fail-fast contract of `registerWorkflow`).
+ *
+ * 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.
+ * Fails loud (qc3 F-201) when the active FsStore would resolve its
+ * `status.json` to a path other than `statusPath` — callers whose root
+ * differs from the active store's root MUST
+ * `setArtifactStore(createFsStore(root))` first.
  */
-export declare function registerWorkflowEntryLocked(statusPath: string, entry: WorkflowEntry): StatusV2Doc;
+export declare function registerWorkflowEntryLocked(statusPath: string, entry: WorkflowEntry): Promise<StatusV2Doc>;
 /**
  * Register one active workflow entry in the v2 root file (plan Task 3).
  * Idempotent upsert by entry `id` under the root-file `withStatusWriteLock`,
@@ -177,6 +185,10 @@ export declare function registerWorkflow(root: string, entry: WorkflowEntry): Pr
  * 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.
+ *
+ * Fails loud (qc3 F-201) when the active FsStore would resolve its
+ * `status.json` to a path other than the caller's root — the no-op branches
+ * below never mask a store/path mismatch.
  */
 export declare function unregisterWorkflow(root: string, id: string): Promise<StatusV2Doc>;
 /**

package/dist/store.d.ts

@@ -0,0 +1,76 @@
+/** JSON coordination-doc kinds the store persists (spec SP2). */
+export type ArtifactKind = "status" | "snapshot" | "residuals" | "review" | "json";
+/** Stable key inside the kind. Workflow id, project id, or review id;
+ * `kind: "status"` always uses key `"root"`. */
+export type ArtifactRef = {
+    kind: ArtifactKind;
+    key: string;
+};
+/** A store document: the ref plus the payload and an optional schema id. */
+export type ArtifactDoc<T = unknown> = ArtifactRef & {
+    payload: T;
+    /** Optional content-type / schema id (e.g. mstar.review/v1). */
+    schema?: string;
+};
+/** Type-only persist contract (HostAdapter pattern). `put` / `get` /
+ * `delete` are async-only — a network-backed store never needs a sync
+ * facade (architect-locked 2026-08-27: no `putSync` anywhere). `list?`
+ * is optional enumeration (D4): stores that cannot enumerate decline by
+ * omitting the member — callers probe `typeof store.list === "function"`
+ * (same pattern as `delete?`). */
+export interface ArtifactStore {
+    put(doc: ArtifactDoc): Promise<void>;
+    get<T = unknown>(ref: ArtifactRef): Promise<T | undefined>;
+    delete?(ref: ArtifactRef): Promise<void>;
+    /** Enumerate refs of `kind`, sorted by key ascending (spec D4). Uniform
+     * rule: report what exists — missing backing dir/file → `[]`; every
+     * listed key round-trips through `get`. `json` is not enumerable. */
+    list?(kind: ArtifactKind): Promise<ArtifactRef[]>;
+}
+/** Map an artifact ref to its file path under `harnessRoot` (spec SP2
+ * FsStore path table — the single kind→path mapping, shared with SP3;
+ * SP3 never re-implements or extends it). Exported (qc1 S-002) so SP3
+ * imports the contract instead of re-deriving it textually. */
+export declare function resolveArtifactPath(harnessRoot: string, ref: ArtifactRef): string;
+/** Default local adapter: maps kinds to the existing `.mstar/` paths.
+ * `put` uses the sync `writeJson` (atomic temp+rename unchanged) and
+ * returns a resolved Promise; locks stay with callers (architect-locked
+ * 2026-08-27). `get` mirrors `readJson`: missing file → `undefined`,
+ * malformed JSON → throw with the path in the message. The returned store
+ * also exposes its resolved `root` so the routed writers can fail loud
+ * when a caller's explicit target path diverges from the store-resolved
+ * path (qc3 F-201); `root` is not part of the `ArtifactStore` contract.
+ * `list` enumerates per the D4 table: report what exists — missing
+ * backing dir/file → `[]`, `json` throws, keys sorted ascending. */
+export declare function createFsStore(harnessRoot: string): ArtifactStore & {
+    root: string;
+};
+export declare function setArtifactStore(store: ArtifactStore | undefined): void;
+/** The active store: the injected one when set, otherwise a lazily
+ * created `FsStore` from `resolveHarnessDir(process.cwd())`. A `null`
+ * resolution throws the same fail-loud "harness dir not found" style as
+ * `resolveHarnessSubdir` — never a silent cwd fallback. */
+export declare function getArtifactStore(): ArtifactStore;
+/**
+ * Fail-loud path-agreement guard for the routed writers (qc3 F-201): when
+ * `store` is an FsStore, resolve the path the store would compute for
+ * `ref` and require it to equal `expectedPath` (the caller's explicit
+ * target). A divergence means the caller's path lives outside the active
+ * store's root — the lockdir would serialize the parameter path while the
+ * put lands at the store root (silent decoupling / split-brain window).
+ * Custom (non-FS) stores own their mapping by design and are skipped.
+ * Cheap: pure path resolution, no I/O.
+ */
+export declare function assertFsStorePath(store: ArtifactStore, ref: ArtifactRef, expectedPath: string): void;
+/** Load a store module from a filesystem path (spec SP2 § Injection 2–3,
+ * SP2-AC6 / SP2-AC7). Resolves against cwd; rejects empty values and any
+ * URI scheme before `import()`; throws when the file is missing. Accepts a
+ * `createArtifactStore` named export, a default-exported factory, or a
+ * default-exported object; the result is structurally verified (`put` +
+ * `get` functions) before use.
+ *
+ * CJS interop: `import()` of a CommonJS module surfaces `module.exports`
+ * as `default` (plus statically detected named exports on the namespace);
+ * the `?? mod` fallback covers loaders that surface `module.exports`
+ * directly as the namespace. No loader protocol beyond `import()`. */
+export declare function loadStoreModule(modulePath: string): Promise<ArtifactStore>;

package/dist/store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workflow.d.ts

@@ -73,6 +73,14 @@ export declare function validateWorkflowSnapshot(doc: unknown): GateResult;
  * `withStatusWriteLock(snapshotPath)` (plan Task 2 — 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.
+ * and nothing is written. `dir` is created recursively. The durable write
+ * routes through the active `ArtifactStore` (spec SP2: snapshot →
+ * `{ kind: "snapshot", key: <workflow id> }`) inside the existing lock — the
+ * default FsStore resolves `{WORKFLOW_DIR}/<key>/snapshot.json`, identical
+ * to `join(dir, WORKFLOW_SNAPSHOT_FILE)` for canonical callers. The write
+ * fails loud when the active FsStore would resolve a different path than
+ * the caller's `join(dir, WORKFLOW_SNAPSHOT_FILE)` (qc3 F-201) — callers
+ * 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>;

package/package.json

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