@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -6,9 +6,9 @@ import { clearParseCache as defaultClearParseCache } from "../files.js";
 import { clearPathCache } from "../paths.js";
 import { logWarning } from "../workflow-logger.js";
 import { ReconciliationFailedError, } from "./errors.js";
-import { DRIFT_REGISTRY } from "./registry.js";
+import { DRIFT_REGISTRY, RECONCILIATION_REPAIR_PHASES } from "./registry.js";
 export { ReconciliationFailedError } from "./errors.js";
-export { DRIFT_REGISTRY } from "./registry.js";
+export { DRIFT_REGISTRY, RECONCILIATION_REPAIR_PHASES, handlerPhaseIndex } from "./registry.js";
 const MAX_PASSES = 2;
 const defaultDeps = {
     invalidateStateCache: defaultInvalidate,
@@ -32,6 +32,7 @@ const defaultDeps = {
 export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
     const deps = { ...defaultDeps, ...partialDeps };
     const registry = deps.registry ?? DRIFT_REGISTRY;
+    const repairPhases = getRepairPhases(registry);
     const clearParseCache = deps.clearParseCache ?? defaultClearParseCache;
     const repaired = [];
     // Capture-on-first-read: infer .planning/ layout, import content into DB, and
@@ -88,27 +89,29 @@ export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
         const failures = [];
         const blockers = [...detection.detectBlockers];
         let repairedThisPass = false;
-        for (const record of drift) {
-            const handler = registry.find((h) => h.kind === record.kind);
-            if (!handler) {
-                failures.push({
-                    drift: record,
-                    cause: new Error(`No drift handler registered for kind "${record.kind}"`),
-                });
-                continue;
-            }
-            const blocker = handler.blocker ? await handler.blocker(record, ctx) : null;
-            if (blocker) {
-                blockers.push(blocker);
-                continue;
-            }
-            try {
-                await handler.repair(record, ctx);
-                repaired.push(record);
-                repairedThisPass = true;
-            }
-            catch (cause) {
-                failures.push({ drift: record, cause });
+        const repairedKindsThisPass = new Set();
+        for (const phase of repairPhases) {
+            for (const record of drift) {
+                const recordKey = `${record.kind}:${JSON.stringify(record)}`;
+                if (repairedKindsThisPass.has(recordKey))
+                    continue;
+                const handler = phase.handlers.find((h) => h.kind === record.kind);
+                if (!handler)
+                    continue;
+                const blocker = handler.blocker ? await handler.blocker(record, ctx) : null;
+                if (blocker) {
+                    blockers.push(blocker);
+                    continue;
+                }
+                try {
+                    await handler.repair(record, ctx);
+                    repaired.push(record);
+                    repairedKindsThisPass.add(recordKey);
+                    repairedThisPass = true;
+                }
+                catch (cause) {
+                    failures.push({ drift: record, cause });
+                }
             }
         }
         if (repairedThisPass) {
@@ -177,6 +180,28 @@ export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
         ],
     };
 }
+function getRepairPhases(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+registry) {
+    const assigned = new Set();
+    const phases = RECONCILIATION_REPAIR_PHASES.map((phase) => {
+        const phaseKinds = new Set(phase.handlers.map((handler) => handler.kind));
+        const handlers = registry.filter((handler) => phaseKinds.has(handler.kind));
+        for (const handler of handlers)
+            assigned.add(handler);
+        return { name: phase.name, handlers };
+    }).filter((phase) => phase.handlers.length > 0);
+    const unphasedHandlers = registry.filter((handler) => !assigned.has(handler));
+    if (unphasedHandlers.length === 0)
+        return phases;
+    return [
+        ...phases,
+        {
+            name: "custom",
+            handlers: unphasedHandlers,
+        },
+    ];
+}
 /**
  * Run every detector. A single detector throwing (e.g. a transient file read
  * error) must NOT abort the whole cycle and hide every later handler's drift —

package/dist/resources/extensions/gsd/state-reconciliation/registry.js

@@ -1,6 +1,5 @@
 // Project/App: gsd-pi
-// File Purpose: ADR-017 drift handler registry. Single source of truth for
-// the catalog. Tests can override per-call via ReconciliationDeps.registry.
+// File Purpose: ADR-017 drift handler registry and explicit repair phases.
 import { completionTimestampHandler } from "./drift/completion.js";
 import { artifactDbStatusDivergenceHandler, completedMilestoneReopenedHandler, diskSliceIdDivergenceHandler, } from "./drift/artifact-db.js";
 import { mergeStateHandler } from "./drift/merge-state.js";
@@ -11,30 +10,35 @@ import { roadmapDivergenceHandler } from "./drift/roadmap.js";
 import { sketchFlagHandler } from "./drift/sketch-flag.js";
 import { staleRenderHandler } from "./drift/stale-render.js";
 import { staleWorkerHandler } from "./drift/stale-worker.js";
-// Each handler is parameterized over its specific DriftRecord variant for
-// internal type safety. The registry stores them under DriftHandler<any> so
-// handlers with disjoint repair parameter types coexist; the lifecycle matches
-// by kind before invoking repair, so this is sound at runtime.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const DRIFT_REGISTRY = [
-    // ⚠ ORDER IS SIGNIFICANT for repairs within a single pass.
-    // external-markdown-edit MUST run before any handler that re-projects
-    // markdown from DB (stale-render, roadmap-divergence). If a DB-projection
-    // handler runs first it overwrites the gsd-core file and the subsequent
-    // external-markdown-edit repair imports the already-overwritten content —
-    // silently discarding the cross-tool edit. With external-markdown-edit first
-    // the DB is updated to reflect the gsd-core edit before stale-render
-    // re-renders, so the canonical re-projection preserves the edit's intent.
-    externalMarkdownEditHandler,
-    externalPlanningEditHandler,
-    sketchFlagHandler,
-    mergeStateHandler,
-    staleRenderHandler,
-    staleWorkerHandler,
-    unregisteredMilestoneHandler,
-    diskSliceIdDivergenceHandler,
-    roadmapDivergenceHandler,
-    completedMilestoneReopenedHandler,
-    artifactDbStatusDivergenceHandler,
-    completionTimestampHandler,
+/**
+ * Repairs run phase-by-phase; detection uses the flattened registry (all handlers).
+ * external-markdown-edit MUST complete before re-project handlers (stale-render,
+ * roadmap-divergence) so cross-tool edits are imported before DB re-projection.
+ */
+export const RECONCILIATION_REPAIR_PHASES = [
+    {
+        name: "import-external-edits",
+        handlers: [externalMarkdownEditHandler, externalPlanningEditHandler],
+    },
+    {
+        name: "normalize-db",
+        handlers: [
+            sketchFlagHandler,
+            mergeStateHandler,
+            staleWorkerHandler,
+            unregisteredMilestoneHandler,
+            diskSliceIdDivergenceHandler,
+            completedMilestoneReopenedHandler,
+            artifactDbStatusDivergenceHandler,
+        ],
+    },
+    {
+        name: "re-project",
+        handlers: [staleRenderHandler, roadmapDivergenceHandler, completionTimestampHandler],
+    },
 ];
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const DRIFT_REGISTRY = RECONCILIATION_REPAIR_PHASES.flatMap((phase) => phase.handlers);
+export function handlerPhaseIndex(kind) {
+    return RECONCILIATION_REPAIR_PHASES.findIndex((phase) => phase.handlers.some((handler) => handler.kind === kind));
+}