@mstar-harness/engine 3.10.2 → 3.11.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, 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 { CloseWorkflowOptions, DeclareWorkflowDeliveryKindOptions, DeliveryRegistrationEvidence, RecordWorkflowDeliveryOptions, RecordWorkflowDeliveryResult, RegisterIterationWorkflowOptions, RegisterIterationWorkflowResult, 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, registerIterationWorkflow, 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";
@@ -67,8 +67,8 @@ export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, Mi
 export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.js";
 export type { CompletenessItem, CompletenessLevel, CompletenessPlaceholder, CompletenessResult, DesignFrontmatter, } from "./design-md.js";
 export { assertLightDarkParity, completenessLevel, parseDesignFrontmatter, validateDesignTokenFrontmatter, } from "./design-md.js";
-export type { AuditCategory, AuditConfidence, AuditEffort, AuditFinding, AuditPriority, AuditRisk, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, ScannedSecret, SecretFinding, SupplyChainFinding, SupplyChainFindingKind, SupplyChainResult, } from "./audit.js";
-export { AUDIT_CATEGORIES, AUDIT_CONFIDENCES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, scanSecrets, supplyChainChecks, validateAuditStatusBlocks, } from "./audit.js";
+export type { AuditCategory, AuditConfidence, AuditEffort, AuditEvidence, AuditFinding, AuditPriority, AuditRisk, AuditSeverity, AuditSeverityRank, AuditTraceKind, AuditTraceStep, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, ScannedSecret, SecretFinding, SupplyChainFinding, SupplyChainFindingKind, SupplyChainResult, } from "./audit.js";
+export { AUDIT_CATEGORIES, AUDIT_CONFIDENCES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, scanSecrets, supplyChainChecks, validateAuditFindingGates, validateAuditStatusBlocks, } from "./audit.js";
 export { KNOWLEDGE_BUG_PROBLEM_TYPES, KNOWLEDGE_CATEGORY_MAP, KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_REQUIRED_FIELDS, KNOWLEDGE_RESOLUTION_TYPES, KNOWLEDGE_SEVERITIES, assertIndexRows, compoundRefreshScope, referenceExists, scopeGuard, validateSchemaYaml, } from "./compound.js";
 export type { ReferenceCheckResult } from "./compound.js";
 export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, ProvenanceCitation, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";

package/dist/workflow.d.ts

@@ -1,5 +1,5 @@
 import { type GateResult, type ValidationResult } from "./core.js";
-import { type SnapshotCoordination } from "./coordination-write.js";
+import { type RowValidationRoute, 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). */
@@ -159,6 +159,10 @@ export type WorkflowSnapshot = {
      */
     delivery?: WorkflowDeliveryEvidence;
 };
+/** True exactly for a single-row standalone development plan workflow (spec A1). */
+export declare function isStandaloneDevelopmentWorkflow(snapshot: WorkflowSnapshot): boolean;
+/** Classify row coordination validation: standalone development vs integration delivery. */
+export declare function rowValidationRoute(snapshot: WorkflowSnapshot, row: PlanRow): RowValidationRoute;
 /** Stable JSON for change detection (sorted keys, recursive). */
 export declare function stableJson(value: unknown): string;
 /**
@@ -518,3 +522,78 @@ export type RegisterPlanWorkflowResult = {
  * root could differ — the routed writers fail loud on a path mismatch.
  */
 export declare function registerPlanWorkflow(workflowId: string, options: RegisterPlanWorkflowOptions): Promise<RegisterPlanWorkflowResult>;
+/** Options for `registerIterationWorkflow`. `harnessDir` is required — the
+ * snapshot and `status.json` live under the harness root. */
+export type RegisterIterationWorkflowOptions = {
+    /** Absolute harness dir that contains `status.json` + `workflows/`. Required. */
+    harnessDir: string;
+    /** Harness-relative compass ref recorded on the snapshot, e.g. `iterations/<id>/delivery-compass.md`. Required. */
+    compassRef: string;
+    /** The three iteration branch anchors. All three required. */
+    branch: {
+        base: string;
+        integration: string;
+        target: string;
+    };
+    /** Initial plan rows. At least one. Every row is written `status: "Todo"`. */
+    rows: Array<{
+        id: string;
+        title: string;
+        file: string;
+    }>;
+    /** Project register id recorded on the snapshot. */
+    project?: string;
+    /** Registration timestamp (YYYY-MM-DD or RFC3339). Default: now. */
+    startedAt?: string;
+};
+export type RegisterIterationWorkflowResult = {
+    workflowId: string;
+    snapshotPath: string;
+    /**
+     * True on orphan recovery: existing snapshot bytes/timestamps are preserved
+     * and only the missing root entry is written.
+     */
+    recovered: boolean;
+};
+/**
+ * Register an iteration workflow (seam S1 sibling of `registerPlanWorkflow`).
+ * Builds the create-only `type: iteration` snapshot (workflow id, compass
+ * ref, the three branch anchors, Todo rows whose `metadata` —
+ * `iteration_refs`, `spec_integration_branch`, `merge_target` — is derived
+ * from the already-required compass/integration inputs; registration never
+ * authorizes implementation) and the root `workflows[]` entry, then writes
+ * BOTH under one atomic section of the root `withStatusWriteLock` — the same
+ * create-only `writeWorkflowSnapshot(..., { createOnly: true })` →
+ * `registerWorkflowEntryLocked` primitive sequence the plan producer uses —
+ * with rollback that removes ONLY the exact snapshot version this call
+ * created (plus the now-empty workflow dir; a non-empty directory is never
+ * force-removed).
+ *
+ * Refusals (fail-loud, before any write): non-empty `workflowId`
+ * (`assertSafePathComponent`), `harnessDir`, `compassRef`, all three branch
+ * anchors, `project` when given, and each row's `id`/`title`/`file`;
+ * non-empty row array; duplicate row ids; a SUPPLIED row `status` (a
+ * requested state transition is never treated as successful registration);
+ * `startedAt` must be a valid YYYY-MM-DD / RFC3339 timestamp. Rows are
+ * constructed from the declared fields — untrusted row objects are never
+ * spread.
+ *
+ * Already-registered refusals: inside the root lock, an existing entry for
+ * the requested id refuses BEFORE either branch — including a stale entry
+ * whose snapshot is missing. This producer is not the low-level upsert and
+ * does not repair/repoint an existing identity. Malformed/v1 roots refuse
+ * without replacing their bytes.
+ *
+ * Crash/retry recovery: a snapshot without its root entry (an orphan)
+ * re-registers only when `iterationWorkflowRegistrationIdentity` matches —
+ * the existing snapshot's bytes and timestamps are preserved verbatim and
+ * the root entry is written with the orphan's `started_at` (`recovered:
+ * true`). A differing identity (including a mismatched snapshot id or an
+ * existing coordinator binding) refuses; a failed recovery root write never
+ * deletes the orphan.
+ *
+ * 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 registerIterationWorkflow(workflowId: string, options: RegisterIterationWorkflowOptions): Promise<RegisterIterationWorkflowResult>;

package/package.json

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