@chkit/plugin-backfill 0.1.0-beta.0

package/dist/state.js

@@ -0,0 +1,198 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { BackfillConfigError } from './errors.js';
+export function hashId(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function stableSerialize(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableSerialize(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries
+        .map(([key, item]) => `${JSON.stringify(key)}:${stableSerialize(item)}`)
+        .join(',')}}`;
+}
+export function computeCompatibilityToken(input) {
+    return hashId(stableSerialize({
+        planId: input.plan.planId,
+        target: input.plan.target,
+        from: input.plan.from,
+        to: input.plan.to,
+        planOptions: input.plan.options,
+        runtimeDefaults: input.options.defaults,
+        runtimePolicy: input.options.policy,
+        runtimeLimits: input.options.limits,
+    }));
+}
+export function planIdentity(target, from, to, chunkHours) {
+    return `${target}|${from}|${to}|${chunkHours}`;
+}
+export function computeBackfillStateDir(config, configPath, options) {
+    if (options.stateDir && options.stateDir.length > 0) {
+        return resolve(dirname(configPath), options.stateDir);
+    }
+    return resolve(dirname(configPath), config.metaDir, 'backfill');
+}
+export function backfillPaths(stateDir, planId) {
+    const plansDir = join(stateDir, 'plans');
+    const runsDir = join(stateDir, 'runs');
+    const eventsDir = join(stateDir, 'events');
+    return {
+        stateDir,
+        plansDir,
+        runsDir,
+        eventsDir,
+        planPath: join(plansDir, `${planId}.json`),
+        runPath: join(runsDir, `${planId}.json`),
+        eventPath: join(eventsDir, `${planId}.ndjson`),
+    };
+}
+async function readJsonMaybe(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    return JSON.parse(await readFile(filePath, 'utf8'));
+}
+export async function writeJson(filePath, value) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+async function appendEvent(eventPath, event) {
+    await mkdir(dirname(eventPath), { recursive: true });
+    await appendFile(eventPath, `${JSON.stringify({ at: nowIso(), ...event })}\n`, 'utf8');
+}
+export async function readExistingPlan(planPath) {
+    return readJsonMaybe(planPath);
+}
+export async function readPlan(input) {
+    const stateDir = computeBackfillStateDir(input.config, input.configPath, input.options);
+    const paths = backfillPaths(stateDir, input.planId);
+    const plan = await readJsonMaybe(paths.planPath);
+    if (!plan) {
+        throw new BackfillConfigError(`Backfill plan not found: ${paths.planPath}`);
+    }
+    return {
+        plan,
+        planPath: paths.planPath,
+        stateDir,
+    };
+}
+export async function readRun(runPath) {
+    return readJsonMaybe(runPath);
+}
+export function createRunState(input) {
+    const startedAt = nowIso();
+    return {
+        planId: input.plan.planId,
+        target: input.plan.target,
+        status: 'planned',
+        createdAt: startedAt,
+        startedAt,
+        updatedAt: startedAt,
+        replayDone: input.execution.replayDone ?? false,
+        replayFailed: input.execution.replayFailed ?? false,
+        compatibilityToken: computeCompatibilityToken({
+            plan: input.plan,
+            options: input.options,
+        }),
+        options: input.plan.options,
+        chunks: input.plan.chunks.map((chunk) => ({
+            id: chunk.id,
+            from: chunk.from,
+            to: chunk.to,
+            status: 'pending',
+            attempts: 0,
+            idempotencyToken: chunk.idempotencyToken,
+            sqlTemplate: chunk.sqlTemplate,
+        })),
+    };
+}
+export async function collectActiveRunTargets(runsDir) {
+    const active = new Map();
+    if (!existsSync(runsDir))
+        return active;
+    const entries = await readdir(runsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const file = join(runsDir, entry.name);
+        const run = await readRun(file);
+        if (!run)
+            continue;
+        if (run.status !== 'running')
+            continue;
+        active.set(run.planId, run.target);
+    }
+    return active;
+}
+export async function listPlanIds(plansDir) {
+    if (!existsSync(plansDir))
+        return [];
+    const entries = await readdir(plansDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => entry.name.replace(/\.json$/, ''))
+        .sort();
+}
+export function summarizeRunStatus(run, runPath, eventPath) {
+    const summary = {
+        total: run.chunks.length,
+        pending: 0,
+        running: 0,
+        done: 0,
+        failed: 0,
+        skipped: 0,
+    };
+    let attempts = 0;
+    for (const chunk of run.chunks) {
+        attempts += chunk.attempts;
+        if (chunk.status === 'pending')
+            summary.pending += 1;
+        if (chunk.status === 'running')
+            summary.running += 1;
+        if (chunk.status === 'done')
+            summary.done += 1;
+        if (chunk.status === 'failed')
+            summary.failed += 1;
+        if (chunk.status === 'skipped')
+            summary.skipped += 1;
+    }
+    return {
+        planId: run.planId,
+        target: run.target,
+        status: run.status,
+        totals: summary,
+        attempts,
+        updatedAt: run.updatedAt,
+        runPath,
+        eventPath,
+        lastError: run.lastError,
+    };
+}
+export async function persistRunAndEvent(input) {
+    input.run.updatedAt = nowIso();
+    await writeJson(input.runPath, input.run);
+    await appendEvent(input.eventPath, input.event);
+}
+export function ensureRunCompatibility(input) {
+    if (!input.run.compatibilityToken)
+        return;
+    const expected = computeCompatibilityToken({
+        plan: input.plan,
+        options: input.options,
+    });
+    if (input.run.compatibilityToken === expected)
+        return;
+    if (input.forceCompatibility)
+        return;
+    throw new BackfillConfigError(`Run compatibility check failed for plan ${input.plan.planId}. Runtime options changed since last checkpoint. Retry with --force-compatibility to acknowledge override.`);
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAClF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAWjD,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;AACjC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IACpE,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5E,OAAO,IAAI,OAAO;SACf,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;SACvE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;AACjB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAGzC;IACC,OAAO,MAAM,CACX,eAAe,CAAC;QACd,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;QACzB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;QACzB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI;QACrB,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE;QACjB,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;QAC/B,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ;QACvC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;QACnC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;KACpC,CAAC,CACH,CAAA;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,IAAY,EAAE,EAAU,EAAE,UAAkB;IACvF,OAAO,GAAG,MAAM,IAAI,IAAI,IAAI,EAAE,IAAI,UAAU,EAAE,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAA0C,EAC1C,UAAkB,EAClB,OAAwC;IAExC,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACvD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;AACjE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,MAAc;IAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAC1C,OAAO;QACL,QAAQ;QACR,QAAQ;QACR,OAAO;QACP,SAAS;QACT,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,MAAM,OAAO,CAAC;QAC1C,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,MAAM,OAAO,CAAC;QACxC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,SAAS,CAAC;KAC/C,CAAA;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAAI,QAAgB;IAC9C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAM,CAAA;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAc;IAC9D,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACnD,MAAM,SAAS,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AAC1E,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,SAAiB,EAAE,KAA8B;IAC1E,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACpD,MAAM,UAAU,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACxF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAgB;IACrD,OAAO,aAAa,CAAoB,QAAQ,CAAC,CAAA;AACnD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAK9B;IACC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACvF,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IACnD,MAAM,IAAI,GAAG,MAAM,aAAa,CAAoB,KAAK,CAAC,QAAQ,CAAC,CAAA;IACnE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,mBAAmB,CAAC,4BAA4B,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC7E,CAAC;IACD,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ;KACT,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAe;IAC3C,OAAO,aAAa,CAAmB,OAAO,CAAC,CAAA;AACjD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAI9B;IACC,MAAM,SAAS,GAAG,MAAM,EAAE,CAAA;IAC1B,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;QACzB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;QACzB,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,SAAS;QACpB,SAAS;QACT,SAAS,EAAE,SAAS;QACpB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,UAAU,IAAI,KAAK;QAC/C,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,YAAY,IAAI,KAAK;QACnD,kBAAkB,EAAE,yBAAyB,CAAC;YAC5C,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;QACF,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO;QAC3B,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACxC,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,CAAC;YACX,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B,CAAC,CAAC;KACJ,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,OAAe;IAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IACxC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAA;IAEvC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAQ;QAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACtC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;QAC/B,IAAI,CAAC,GAAG;YAAE,SAAQ;QAClB,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS;YAAE,SAAQ;QACtC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACpC,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB;IAChD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAA;IACpC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IAChE,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SACjE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;SACjD,IAAI,EAAE,CAAA;AACX,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAAqB,EACrB,OAAe,EACf,SAAiB;IAEjB,MAAM,OAAO,GAAG;QACd,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM;QACxB,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,CAAC;QACP,MAAM,EAAE,CAAC;QACT,OAAO,EAAE,CAAC;KACX,CAAA;IAED,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAA;QAC1B,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,OAAO,IAAI,CAAC,CAAA;QACpD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,OAAO,IAAI,CAAC,CAAA;QACpD,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,OAAO,CAAC,IAAI,IAAI,CAAC,CAAA;QAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;QAClD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,OAAO,IAAI,CAAC,CAAA;IACtD,CAAC;IAED,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,OAAO;QACf,QAAQ;QACR,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,OAAO;QACP,SAAS;QACT,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAKxC;IACC,KAAK,CAAC,GAAG,CAAC,SAAS,GAAG,MAAM,EAAE,CAAA;IAC9B,MAAM,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;IACzC,MAAM,WAAW,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;AACjD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAKtC;IACC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB;QAAE,OAAM;IACzC,MAAM,QAAQ,GAAG,yBAAyB,CAAC;QACzC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAA;IACF,IAAI,KAAK,CAAC,GAAG,CAAC,kBAAkB,KAAK,QAAQ;QAAE,OAAM;IACrD,IAAI,KAAK,CAAC,kBAAkB;QAAE,OAAM;IAEpC,MAAM,IAAI,mBAAmB,CAC3B,2CAA2C,KAAK,CAAC,IAAI,CAAC,MAAM,4GAA4G,CACzK,CAAA;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,229 @@
+import type { ChxInlinePluginRegistration, ResolvedChxConfig } from '@chkit/core';
+export interface BackfillPluginDefaults {
+    chunkHours?: number;
+    maxParallelChunks?: number;
+    maxRetriesPerChunk?: number;
+    requireIdempotencyToken?: boolean;
+}
+export interface BackfillPluginPolicy {
+    requireDryRunBeforeRun?: boolean;
+    requireExplicitWindow?: boolean;
+    blockOverlappingRuns?: boolean;
+    failCheckOnRequiredPendingBackfill?: boolean;
+}
+export interface BackfillPluginLimits {
+    maxWindowHours?: number;
+    minChunkMinutes?: number;
+}
+export interface BackfillPluginOptions {
+    stateDir?: string;
+    defaults?: BackfillPluginDefaults;
+    policy?: BackfillPluginPolicy;
+    limits?: BackfillPluginLimits;
+}
+export interface NormalizedBackfillPluginOptions {
+    stateDir?: string;
+    defaults: Required<BackfillPluginDefaults>;
+    policy: Required<BackfillPluginPolicy>;
+    limits: Required<BackfillPluginLimits>;
+}
+export type BackfillPlanStatus = 'planned' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+export interface BackfillChunk {
+    id: string;
+    from: string;
+    to: string;
+    status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+    attempts: number;
+    idempotencyToken: string;
+    sqlTemplate: string;
+    lastError?: string;
+}
+export interface BackfillPlanState {
+    planId: string;
+    target: string;
+    createdAt: string;
+    status: BackfillPlanStatus;
+    from: string;
+    to: string;
+    chunks: BackfillChunk[];
+    options: {
+        chunkHours: number;
+        maxParallelChunks: number;
+        maxRetriesPerChunk: number;
+        requireIdempotencyToken: boolean;
+    };
+    policy: Required<BackfillPluginPolicy>;
+    limits: Required<BackfillPluginLimits>;
+}
+export interface BackfillRunChunkState {
+    id: string;
+    from: string;
+    to: string;
+    status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+    attempts: number;
+    idempotencyToken: string;
+    sqlTemplate: string;
+    startedAt?: string;
+    completedAt?: string;
+    lastError?: string;
+}
+export interface BackfillRunState {
+    planId: string;
+    target: string;
+    status: BackfillPlanStatus;
+    createdAt: string;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    lastError?: string;
+    replayDone: boolean;
+    replayFailed: boolean;
+    compatibilityToken: string;
+    options: BackfillPlanState['options'];
+    chunks: BackfillRunChunkState[];
+}
+export interface BackfillStatusSummary {
+    planId: string;
+    target: string;
+    status: BackfillPlanStatus;
+    totals: {
+        total: number;
+        pending: number;
+        running: number;
+        done: number;
+        failed: number;
+        skipped: number;
+    };
+    attempts: number;
+    updatedAt: string;
+    runPath: string;
+    eventPath: string;
+    lastError?: string;
+}
+export interface BackfillPluginCheckContext {
+    command: 'check';
+    config: ResolvedChxConfig;
+    configPath: string;
+    jsonMode: boolean;
+    options: Record<string, unknown>;
+}
+export interface BackfillPluginCheckResult {
+    plugin: string;
+    evaluated: boolean;
+    ok: boolean;
+    findings: Array<{
+        code: 'backfill_required_pending' | 'backfill_plan_missing' | 'backfill_plan_stale' | 'backfill_overlap_blocked' | 'backfill_window_exceeds_limit' | 'backfill_chunk_failed_retry_exhausted' | 'backfill_policy_relaxed';
+        message: string;
+        severity: 'info' | 'warn' | 'error';
+        metadata?: Record<string, unknown>;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+export interface BuildBackfillPlanOutput {
+    plan: BackfillPlanState;
+    planPath: string;
+    existed: boolean;
+}
+export interface ReadPlanOutput {
+    plan: BackfillPlanState;
+    planPath: string;
+    stateDir: string;
+}
+export interface BackfillPathSet {
+    stateDir: string;
+    plansDir: string;
+    runsDir: string;
+    eventsDir: string;
+    planPath: string;
+    runPath: string;
+    eventPath: string;
+}
+export interface BackfillExecutionOptions {
+    replayDone?: boolean;
+    replayFailed?: boolean;
+    forceOverlap?: boolean;
+    forceCompatibility?: boolean;
+    simulation?: {
+        failChunkId?: string;
+        failCount?: number;
+    };
+}
+export interface BackfillDoctorReport {
+    planId: string;
+    status: BackfillPlanStatus;
+    issueCodes: string[];
+    recommendations: string[];
+    failedChunkIds: string[];
+}
+export interface ExecuteBackfillRunOutput {
+    run: BackfillRunState;
+    status: BackfillStatusSummary;
+    runPath: string;
+    eventPath: string;
+}
+export interface BackfillPluginCommandContext {
+    args: string[];
+    jsonMode: boolean;
+    options: Record<string, unknown>;
+    config: ResolvedChxConfig;
+    configPath: string;
+    print: (value: unknown) => void;
+}
+export interface BackfillPlugin {
+    manifest: {
+        name: 'backfill';
+        apiVersion: 1;
+        version?: string;
+    };
+    commands: Array<{
+        name: 'plan' | 'run' | 'resume' | 'status' | 'cancel' | 'doctor';
+        description: string;
+        run: (context: BackfillPluginCommandContext) => undefined | number | Promise<undefined | number>;
+    }>;
+    hooks?: {
+        onConfigLoaded?: (context: {
+            command: string;
+            configPath: string;
+            options: Record<string, unknown>;
+        }) => void;
+        onCheck?: (context: BackfillPluginCheckContext) => BackfillPluginCheckResult | undefined | Promise<BackfillPluginCheckResult | undefined>;
+        onCheckReport?: (context: {
+            result: BackfillPluginCheckResult;
+            print: (line: string) => void;
+        }) => void | Promise<void>;
+    };
+}
+export type BackfillPluginRegistration = ChxInlinePluginRegistration<BackfillPlugin, BackfillPluginOptions>;
+export interface ParsedPlanArgs {
+    target: string;
+    from: string;
+    to: string;
+    chunkHours?: number;
+    forceLargeWindow: boolean;
+}
+export interface ParsedRunArgs {
+    planId: string;
+    replayDone: boolean;
+    replayFailed: boolean;
+    forceOverlap: boolean;
+    forceCompatibility: boolean;
+    simulateFailChunk?: string;
+    simulateFailCount: number;
+}
+export interface ParsedResumeArgs {
+    planId: string;
+    replayDone: boolean;
+    replayFailed: boolean;
+    forceOverlap: boolean;
+    forceCompatibility: boolean;
+}
+export interface ParsedStatusArgs {
+    planId: string;
+}
+export interface ParsedCancelArgs {
+    planId: string;
+}
+export interface ParsedDoctorArgs {
+    planId: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@chkit/plugin-backfill",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome lint src",
+    "test": "bun test src",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@chkit/core": "workspace:*"
+  }
+}