@fullstackhouse/open-mercato-data-sync-durable 0.1.0

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "@fullstackhouse/open-mercato-data-sync-durable",
+  "version": "0.1.0",
+  "description": "Drop-in replacement for Open Mercato's core data_sync module that runs sync runs as durable at-least-once work (via @fullstackhouse/open-mercato-durable-work): survives deploys and worker kills, resumes from the committed cursor, retries transient errors at the batch, never leaves a run 'running' forever. Same tables, API, adapter contract, events and UI as core; swap one line in modules.ts.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "license": "MIT",
+  "author": "Full Stack House",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fullstackhouse/open-mercato-durable.git",
+    "directory": "packages/data-sync-durable"
+  },
+  "keywords": [
+    "open-mercato",
+    "data-sync",
+    "durable",
+    "at-least-once",
+    "background-jobs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "src",
+    "generated",
+    "README.md"
+  ],
+  "scripts": {
+    "gen:mirror": "node scripts/gen-mirror.mjs",
+    "prebuild": "node scripts/gen-mirror.mjs --check",
+    "build": "node build.mjs",
+    "prepack": "yarn build",
+    "watch": "node watch.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src scripts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
+    "./*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@fullstackhouse/open-mercato-durable-work": "^0.1.0",
+    "@mikro-orm/core": ">=7.0.0",
+    "@mikro-orm/migrations": ">=7.0.0",
+    "@mikro-orm/postgresql": ">=7.0.0",
+    "@open-mercato/core": ">=0.7.0 <0.8.0",
+    "@open-mercato/queue": ">=0.7.0 <0.8.0",
+    "@open-mercato/shared": ">=0.7.0 <0.8.0",
+    "@open-mercato/ui": ">=0.7.0 <0.8.0",
+    "next": ">=15.0.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "zod": ">=3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@fullstackhouse/open-mercato-durable-work": "^0.1.0",
+    "@mikro-orm/core": "^7.1.8",
+    "@mikro-orm/migrations": "^7.1.8",
+    "@mikro-orm/postgresql": "^7.1.8",
+    "@open-mercato/core": "0.7.0",
+    "@open-mercato/queue": "0.7.0",
+    "@open-mercato/shared": "0.7.0",
+    "@open-mercato/ui": "0.7.0",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.0.0",
+    "awilix": "^13.0.5",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.0.0",
+    "glob": "^13.0.6",
+    "globals": "^16.0.0",
+    "next": "16.3.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.4.3"
+  }
+}

package/src/compat/mirror-shape.test.ts

@@ -0,0 +1,106 @@
+import { createRequire } from 'node:module'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import manifest from '../mirror.manifest.json'
+
+// Guards the three findings of the phase-0 mirror spike (docs/adr/0006). Each is a case
+// where the Open Mercato generator reads a module's own file statically and therefore
+// cannot see through `export * from '@open-mercato/core/...'`. Losing any of them is
+// silent — the app boots, the module is registered, and only the affected contract is
+// missing — so they are asserted rather than trusted.
+const pkgDir = path.resolve(__dirname, '..', '..')
+const moduleDir = path.join(pkgDir, 'src', 'modules', 'data_sync')
+const require = createRequire(path.join(pkgDir, 'package.json'))
+
+function corePackageRoot(): string {
+  // The `exports` map rewrites "./package.json" to "./src/package.json"; walk up instead.
+  let dir = path.dirname(require.resolve('@open-mercato/core'))
+  for (;;) {
+    const file = path.join(dir, 'package.json')
+    if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file, 'utf8')).name === '@open-mercato/core') return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) throw new Error('could not locate @open-mercato/core')
+    dir = parent
+  }
+}
+
+const coreModuleDir = path.join(corePackageRoot(), 'src', 'modules', 'data_sync')
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
+
+function walk(dir: string, rel = ''): string[] {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const next = rel ? `${rel}/${entry.name}` : entry.name
+    if (entry.isDirectory()) return entry.name.startsWith('__') ? [] : walk(path.join(dir, entry.name), next)
+    return /\.tsx?$/.test(entry.name) ? [next] : []
+  })
+}
+
+const coreApiFiles = walk(path.join(coreModuleDir, 'api')).map((rel) => `api/${rel}`)
+// Mirrors `detectExportedHttpMethods` in @open-mercato/cli: declarations and named
+// re-export blocks, both by regex over the file's own text.
+function methodsOf(source: string): string[] {
+  const found = new Set<string>()
+  for (const m of HTTP_METHODS) {
+    if (new RegExp(`export\\s+(?:async\\s+)?function\\s+${m}\\b|export\\s+(?:const|let|var)\\s+${m}\\b`).test(source)) found.add(m)
+  }
+  for (const match of source.matchAll(/export\s*\{([^}]+)\}/g)) {
+    for (const part of (match[1] ?? '').split(',')) {
+      const name = part.trim().split(/\s+as\s+/i).pop()?.trim()
+      if (name && HTTP_METHODS.includes(name)) found.add(name)
+    }
+  }
+  return HTTP_METHODS.filter((m) => found.has(m))
+}
+
+describe('data_sync mirror shape', () => {
+  it('mirrors the core version the manifest was generated from', () => {
+    expect(manifest.coreVersion).toBe(JSON.parse(fs.readFileSync(path.join(corePackageRoot(), 'package.json'), 'utf8')).version)
+  })
+
+  it('covers every core api file', () => {
+    expect(coreApiFiles.length).toBeGreaterThan(0)
+    for (const rel of coreApiFiles) expect(fs.existsSync(path.join(moduleDir, rel))).toBe(true)
+  })
+
+  // Finding 1: `detectExportedHttpMethods` is a regex over the file's own text.
+  it('names every HTTP method core exports, so the route registers with the same methods', () => {
+    for (const rel of coreApiFiles) {
+      const expected = methodsOf(fs.readFileSync(path.join(coreModuleDir, rel), 'utf8'))
+      if (!expected.length) continue
+      expect({ rel, methods: methodsOf(fs.readFileSync(path.join(moduleDir, rel), 'utf8')) }).toEqual({ rel, methods: expected })
+    }
+  })
+
+  // Finding 2: route `metadata` is read by AST, and carries requireAuth/requireFeatures.
+  it('copies the route metadata literal rather than re-exporting it', () => {
+    for (const rel of coreApiFiles) {
+      const core = fs.readFileSync(path.join(coreModuleDir, rel), 'utf8')
+      if (!methodsOf(core).length || !/export\s+const\s+metadata\s*=\s*\{/.test(core)) continue
+      expect({ rel, copied: /export const metadata = \{/.test(fs.readFileSync(path.join(moduleDir, rel), 'utf8')) })
+        .toEqual({ rel, copied: true })
+    }
+  })
+
+  // Finding 3: entity ids and fields come from @Entity() classes a stub does not have,
+  // so they ship as the package-level `generated/` descriptor the CLI looks for.
+  it('ships an entity descriptor listing every entity core declares', () => {
+    const coreEntities = [...fs.readFileSync(path.join(coreModuleDir, 'data', 'entities.ts'), 'utf8')
+      .matchAll(/export\s+class\s+(\w+)/g)].map((m) => m[1].replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase())
+    expect(coreEntities.length).toBeGreaterThan(0)
+
+    const ids = fs.readFileSync(path.join(pkgDir, 'generated', 'entities.ids.generated.ts'), 'utf8')
+    for (const entity of coreEntities) {
+      expect({ entity, declared: ids.includes(`"${entity}": "data_sync:${entity}"`) }).toEqual({ entity, declared: true })
+      expect(fs.existsSync(path.join(pkgDir, 'generated', 'entities', entity, 'index.ts'))).toBe(true)
+    }
+  })
+
+  // `data/entities.ts` must stay a re-export: the app spreads our namespace into MikroORM's
+  // entity list, so copying the classes would register duplicates instead of core's.
+  it('keeps the entities module a re-export so core keeps class identity', () => {
+    const ours = fs.readFileSync(path.join(moduleDir, 'data', 'entities.ts'), 'utf8')
+    expect(ours).toContain("export * from '@open-mercato/core/modules/data_sync/data/entities'")
+    expect(ours).not.toMatch(/export\s+class\s/)
+  })
+})

package/src/compat/seams.test.ts

@@ -0,0 +1,97 @@
+// The seams this package depends on, asserted against the installed `@open-mercato/core`.
+//
+// The adopter does not fork core's engine; it decorates three methods and relies on one
+// documented branch of `finalizeRun` (ADR 0004). That is a far smaller coupling than a fork —
+// but only if it is *checked*, because every one of these could be changed upstream in a way
+// that compiles fine and silently stops the durable behaviour:
+//
+//   - if `markStatus` stopped returning the row unchanged on a refused terminal transition,
+//     core would write the terminal state itself and the durable one would arrive second
+//   - if the batch loop stopped consulting `isCancellationRequested`, a slice would have no
+//     hand-back point and could only be interrupted between whole runs
+//   - if `commitBatchProgress` changed shape, cursor commits would stop being fenced
+//
+// These run in the `compat` CI lane against both the released and the development channel, so
+// a core release that moves any of them fails here rather than in a host.
+
+import { createRequire } from 'node:module'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const require = createRequire(path.join(__dirname, '..', '..', 'package.json'))
+
+function coreRoot(): string {
+  let dir = path.dirname(require.resolve('@open-mercato/core'))
+  for (;;) {
+    const manifest = path.join(dir, 'package.json')
+    if (fs.existsSync(manifest) && JSON.parse(fs.readFileSync(manifest, 'utf8')).name === '@open-mercato/core') return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) throw new Error('could not locate @open-mercato/core')
+    dir = parent
+  }
+}
+
+const read = (relative: string): string => fs.readFileSync(path.join(coreRoot(), 'src', 'modules', 'data_sync', relative), 'utf8')
+
+describe('the seams the durable adopter decorates', () => {
+  const runService = read('lib/sync-run-service.ts')
+  const engine = read('lib/sync-engine.ts')
+
+  it('still exposes the three run-service methods the adopter wraps', () => {
+    for (const method of ['getRun', 'markStatus', 'commitBatchProgress']) {
+      expect({ method, present: new RegExp(`\\b${method}\\s*\\(`).test(runService) }).toEqual({ method, present: true })
+    }
+  })
+
+  it('still returns the row unchanged when a terminal transition is refused', () => {
+    // This is what lets the adopter record a terminal outcome instead of performing it. Without
+    // it, core writes the run's terminal state itself and the durable transition arrives second
+    // — two writers, and the domain row no longer moves with the job row.
+    expect(runService).toMatch(/isTerminal\s*&&\s*row\.status\s*!==\s*status/)
+    expect(runService).toMatch(/if \(isTerminal && row\.status !== status\) \{\s*\n\s*return row/)
+  })
+
+  it('still stays silent when the status it wrote is not the status it asked for', () => {
+    // `finalizeRun`'s "another worker already finalized this" branch. It is what suppresses the
+    // progress write, the operational log and the lifecycle event, so the durable terminal
+    // transition can emit them exactly once instead.
+    expect(engine).toMatch(/const run = await syncRunService\.markStatus\(runId, status, scope, error\)/)
+    expect(engine).toMatch(/if \(run\.status !== status\) \{/)
+  })
+
+  it('still asks whether to cancel at every batch boundary', () => {
+    // The hand-back point. Without it a slice has nowhere to stop, and the mechanism's
+    // headline property — a deploy does not kill a multi-day run — is gone.
+    //
+    // Asserted as a property rather than a phrasing, because the phrasing has already moved:
+    // `develop` puts a background poller in front of the check
+    // (`cancellation.signal.aborted || (run.progressJobId && await isCancellationRequested(…))`).
+    // The seam is unaffected — the question is still asked per batch and a true answer still
+    // stops the stream — and a probe that failed on the wording would cry wolf on every
+    // upstream refactor while missing the change that actually matters.
+    const checks = engine.match(/progressService\.isCancellationRequested\(/g) ?? []
+    expect(checks.length).toBeGreaterThanOrEqual(2) // import and export
+
+    for (const branch of engine.split('isCancellationRequested(').slice(1)) {
+      // Every use either leads to a stop, or feeds the poller that aborts to the same end.
+      const leadsToStop = /return 'stop'/.test(branch.slice(0, 400))
+      const feedsThePoller = /controller\.abort\(\)/.test(branch.slice(0, 400))
+      expect(leadsToStop || feedsThePoller).toBe(true)
+    }
+  })
+
+  it('still ends the stream cleanly when a batch says stop', () => {
+    expect(engine).toMatch(/streamResult === 'stopped'/)
+  })
+
+  it('still commits the cursor through the run service, batch by batch', () => {
+    expect(engine).toMatch(/syncRunService\.commitBatchProgress\(/)
+  })
+
+  it('still consults the cancellation check only for runs that have a progress job', () => {
+    // Recorded because it is a real constraint on the adopter rather than an incidental
+    // detail: a run created without a progress job has no batch boundary to stop at, so the
+    // start path must always create one.
+    expect(engine).toMatch(/run\.progressJobId && await progressService\.isCancellationRequested/)
+  })
+})

package/src/engine/durable-run.ts

@@ -0,0 +1,231 @@
+// How a `data_sync` run becomes durable work without core's engine being changed or copied.
+//
+// Core's engine already survives being displaced by another worker: it asks a cancellation
+// question at every batch boundary, and it stays silent when a terminal write is refused. A
+// durable adopter is exactly a worker in that position, so all this does is answer those two
+// questions differently — and route the cursor commit through the lease fence.
+//
+// See docs/adr/0004: the original plan was to fork the batch loop. Reading the engine showed
+// the seams were already there.
+
+import type { SliceContext, SliceOutcome, SqlExecutor } from '@fullstackhouse/open-mercato-durable-work'
+
+import { SeamBrokenError } from '../modules/data_sync/lib/version-guard'
+
+export type SyncScope = { tenantId: string; organizationId: string | null; userId?: string | null }
+export type SyncTerminalStatus = 'completed' | 'failed' | 'cancelled'
+
+/** The methods this decorator *wraps*, not the whole service: core's engine calls plenty more,
+ *  and they are passed through untouched. Anything not listed here is delegated. */
+export type SyncRunServiceLike = {
+  [method: string]: unknown
+  getRun(runId: string, scope: SyncScope): Promise<{ status: string; progressJobId?: string | null } | null>
+  markStatus(runId: string, status: string, scope: SyncScope, error?: string): Promise<unknown>
+  commitBatchProgress(
+    runId: string,
+    delta: Record<string, unknown>,
+    cursor: unknown,
+    scope: SyncScope,
+    options?: Record<string, unknown>,
+  ): Promise<unknown>
+}
+
+export type ProgressServiceLike = {
+  [method: string]: unknown
+  isCancellationRequested(progressJobId: string, tenantId: string, organizationId: string | null): Promise<boolean>
+}
+
+/** What core's engine tried to do, captured rather than applied. */
+export type CapturedOutcome = { status: SyncTerminalStatus; error?: string } | null
+
+export type SliceRecorder = {
+  runService: SyncRunServiceLike
+  progressService: ProgressServiceLike
+  /** What the engine tried to finalize the run as, if anything. */
+  captured(): CapturedOutcome
+  /** Why the slice stopped early, when it did. */
+  stopReason(): 'budget' | 'cancelled' | null
+  /** Batches whose cursor this slice committed. Zero means the slice made no progress. */
+  committedBatches(): number
+}
+
+/**
+ * Wraps core's two services for the duration of one slice.
+ *
+ * @param ctx  the slice this recorder belongs to; its lease is what fences the cursor commits
+ */
+export function recordSlice(
+  ctx: SliceContext,
+  runService: SyncRunServiceLike,
+  progressService: ProgressServiceLike,
+): SliceRecorder {
+  let captured: CapturedOutcome = null
+  let stopReason: 'budget' | 'cancelled' | null = null
+  let committed = 0
+
+  return {
+    captured: () => captured,
+    stopReason: () => stopReason,
+    committedBatches: () => committed,
+
+    // Spread, not rebuilt.
+    //
+    // Core's engine calls far more than the three methods decorated here — `startJob`,
+    // `updateProgress`, `touchJobHeartbeat`, `markCancelled` and others on the progress
+    // service, and more of the run service besides. An object carrying only the overrides
+    // looks fine to TypeScript through a structural type and then fails at the first
+    // undecorated call, mid-run.
+    runService: {
+      ...runService,
+
+      /**
+       * Records a terminal transition instead of performing it, and answers with the run
+       * unchanged.
+       *
+       * Core's `finalizeRun` compares what comes back to what it asked for, and stays silent
+       * when they differ — the branch it has for "another worker already finalized this". So
+       * this both captures the outcome and suppresses the progress write, the operational log
+       * and the lifecycle event, leaving all three to the durable terminal transition, which
+       * writes them in the same transaction as the job's own terminal state.
+       */
+      async markStatus(runId, status, scope, error) {
+        if (status === 'completed' || status === 'failed' || status === 'cancelled') {
+          captured = { status, error }
+          return runService.getRun(runId, scope)
+        }
+        return runService.markStatus(runId, status, scope, error)
+      },
+
+      /**
+       * Commits the batch cursor under the lease.
+       *
+       * This is the write that must not outlive the right to make it: a worker whose lease
+       * expired mid-batch would otherwise advance the cursor of a run another worker is now
+       * driving, and the two would interleave over one stream.
+       */
+      async commitBatchProgress(runId, delta, cursor, scope, options) {
+        const result = await ctx.fencedWrite(async () => runService.commitBatchProgress(runId, delta, cursor, scope, options))
+        committed += 1
+        // A committed unit of work resets the failure and orphan budgets: a run that is making
+        // progress has not earned the suspicion those counters represent, however many times
+        // it was interrupted getting there.
+        await ctx.heartbeat({ committed: true })
+        return result
+      },
+    },
+
+    progressService: {
+      ...progressService,
+
+      /**
+       * Mirrors the run's counters onto the durable job as they move.
+       *
+       * Core reports progress here after every committed batch. Without this the operator API
+       * shows a job that is plainly running with `0 of null` processed, and the one place
+       * somebody looks to see whether a multi-day backfill is advancing tells them nothing.
+       */
+      async updateProgress(progressJobId: string, patch: { processedCount?: number; totalCount?: number | null }, scope: unknown) {
+        await ctx
+          .heartbeat({ processedCount: patch?.processedCount, totalCount: patch?.totalCount ?? null })
+          .catch(() => undefined)
+        const inner = progressService.updateProgress as
+          | ((id: string, patch: unknown, scope: unknown) => Promise<unknown>)
+          | undefined
+        return inner?.call(progressService, progressJobId, patch, scope)
+      },
+
+      /**
+       * Core asks this once per batch and stops the stream cleanly when it is true. That makes
+       * it the slice's hand-back point as well as its cancellation point — the two need the
+       * same clean stop, and differ only in what happens afterwards.
+       */
+      async isCancellationRequested(progressJobId, tenantId, organizationId) {
+        if (await progressService.isCancellationRequested(progressJobId, tenantId, organizationId)) {
+          stopReason = 'cancelled'
+          return true
+        }
+        if (ctx.signal.aborted || ctx.shouldYield()) {
+          stopReason = 'budget'
+          return true
+        }
+        return false
+      },
+    },
+  }
+}
+
+/** A run that ended `failed` inside core's engine. Thrown so the durable error taxonomy and the
+ *  retry budget apply to it, instead of the run being thrown away at the first blip. */
+export class SyncRunFailedError extends Error {
+  readonly durableErrorClass = 'transient' as const
+  constructor(
+    readonly runId: string,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'SyncRunFailedError'
+  }
+}
+
+/**
+ * Turns what the recorder saw into the outcome the mechanism understands.
+ *
+ * @param runStatus the run's status after the slice, used only to tell "already finished" from
+ *                  "core finalized this itself" — see the seam check below
+ */
+export function outcomeOf(recorder: SliceRecorder, runId: string, runStatus?: string): SliceOutcome {
+  const captured = recorder.captured()
+
+  if (recorder.stopReason() === 'budget') return 'budget'
+  if (recorder.stopReason() === 'cancelled') return 'cancelled'
+
+  if (!captured) {
+    // Nothing was recorded. Two very different situations look the same from here, and telling
+    // them apart is the whole point:
+    //
+    //   - the run was already terminal, or gone, before this slice started — nothing to do
+    //   - core finalized the run itself, without going through the decorated `markStatus`
+    //
+    // The second means the seam this package rests on has moved (ADR 0004), and reporting it
+    // as success would leave a job that says `completed` beside a run that says `failed`.
+    // Committed batches are what distinguishes them: a slice that did real work and then found
+    // the run terminal without recording anything did not simply arrive late.
+    if (recorder.committedBatches() > 0 && runStatus && runStatus !== 'running' && runStatus !== 'pending') {
+      throw new SeamBrokenError(runId, `the run reached "${runStatus}" without the adopter recording it`)
+    }
+    return 'drained'
+  }
+  if (captured.status === 'failed') throw new SyncRunFailedError(runId, captured.error ?? 'Sync run failed')
+  if (captured.status === 'cancelled') return 'cancelled'
+  return 'drained'
+}
+
+/** Maps a durable terminal state onto the run's own, inside the terminal transaction. */
+export async function mirrorRunStatus(
+  tx: SqlExecutor,
+  runId: string,
+  status: SyncTerminalStatus,
+  errorMessage: string | null,
+): Promise<{ matched: number }> {
+  // Fenced on the run still being open, so a run finished by another path is not overwritten —
+  // "mirrored" means the domain row agrees, and a row that already disagrees for a good reason
+  // must not be forced.
+  const result = await tx.query(
+    `update sync_runs
+        set status = $2, last_error = $3, updated_at = now()
+      where id = $1 and deleted_at is null and status in ('pending','running')`,
+    [runId, status, errorMessage],
+  )
+  return { matched: result.rowCount }
+}
+
+/** Re-opens a run when an operator re-drives its job. The mirror image of the above. */
+export async function reopenRun(tx: SqlExecutor, runId: string): Promise<{ matched: number }> {
+  const result = await tx.query(
+    `update sync_runs
+        set status = 'running', last_error = null, updated_at = now()
+      where id = $1 and deleted_at is null and status in ('failed','pending','running')`,
+    [runId],
+  )
+  return { matched: result.rowCount }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+// Public API of @fullstackhouse/open-mercato-data-sync-durable.
+// The host loads ./modules/data_sync as module id `data_sync` in place of core's:
+//   { id: 'data_sync', from: '@fullstackhouse/open-mercato-data-sync-durable' }
+export { metadata } from './modules/data_sync/index'