@x12i/memorix-service 3.12.3 → 3.13.0

package/dist/patches/engine.js

@@ -0,0 +1,966 @@
+/**
+ * MX-PATCH-01 — plan, apply, and revert a patch on stored content rows.
+ *
+ * Rows are read and written directly so a row the writer cannot address (a legacy row
+ * without a discriminator) can still be fixed. Each write keeps the content-write rules:
+ * a revision precondition, a new revision, `_history`, `_system.modifiedAt`, and JSON
+ * markdown rebuilt from `data`.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { canonicalJson, computeDiscriminatedStorageKey, createCollectionRouter, readStoredMarkdown, resolveRecordMarkdown, } from "@x12i/memorix-data";
+import { ServiceError } from "../errors.js";
+import { applyOps, bodyChanged, bodyDiff } from "./ops.js";
+import { invalid } from "./parse.js";
+import { evaluatePredicate, isPlainObject, PatchRowError, readPlain } from "./paths.js";
+import { invalidatePatchGuards } from "./guards.js";
+import { patchCollections, } from "./store.js";
+const PAGE = 500;
+const WORK_BATCH = 50;
+const SAMPLE_LIMIT = 20;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const PROCESS_OWNER = randomBytes(6).toString("hex");
+const running = new Set();
+const router = createCollectionRouter();
+function envInt(name, fallback) {
+    const raw = Number(process.env[name]);
+    return Number.isInteger(raw) && raw > 0 ? raw : fallback;
+}
+export function patchLimits(overrides) {
+    return {
+        maxRows: envInt("MEMORIX_PATCH_MAX_ROWS", 100_000),
+        maxRowsPerHour: envInt("MEMORIX_PATCH_MAX_ROWS_PER_HOUR", 250_000),
+        syncRows: envInt("MEMORIX_PATCH_SYNC_ROWS", 200),
+        planTtlMs: DAY_MS,
+        retainMs: 15 * DAY_MS,
+        leaseMs: 120_000,
+        ...overrides,
+    };
+}
+function nowOf(deps) {
+    return (deps.now ?? (() => new Date().toISOString()))();
+}
+function plusMs(iso, ms) {
+    return new Date(Date.parse(iso) + ms).toISOString();
+}
+function newPatchId() {
+    return `mxp_${Date.now().toString(36).toUpperCase().padStart(9, "0")}${randomBytes(8).toString("hex").toUpperCase()}`;
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isInfrastructureError(err) {
+    const name = err instanceof Error ? err.name : "";
+    return /^Mongo(Network|ServerSelection|NotConnected|Topology)/.test(name);
+}
+function resolveTarget(deps, objectType, contentType) {
+    let routed;
+    try {
+        routed = router.contentCollection(deps.scope, deps.catalog, objectType, contentType);
+    }
+    catch (err) {
+        invalid(`${objectType}/${contentType}: ${message(err)}`, "select.contentTypes");
+    }
+    return {
+        objectType,
+        contentType,
+        coll: deps.client.db(routed.database.databaseName).collection(routed.collectionName),
+        discriminatorPath: deps.catalog.getContentProfile?.(contentType)?.discriminator?.path,
+    };
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function selectFilter(select, discriminatorPath) {
+    const filter = {};
+    const and = [];
+    if (select.recordIds)
+        filter.recordId = { $in: select.recordIds };
+    if (select.idPrefix)
+        filter.recordId = { $regex: `^${escapeRegex(select.idPrefix)}` };
+    if (select.state === "active")
+        filter["_system.state"] = { $in: ["active", null] };
+    else if (select.state === "tombstoned")
+        filter["_system.state"] = "archived";
+    if (select.discriminator && "value" in select.discriminator && discriminatorPath) {
+        filter[discriminatorPath] = select.discriminator.value;
+        and.push({ $expr: { $ne: ["$_id", "$recordId"] } });
+    }
+    if (select.discriminator && "absent" in select.discriminator && discriminatorPath) {
+        and.push({
+            $or: [{ [discriminatorPath]: { $in: [null, ""] } }, { $expr: { $eq: ["$_id", "$recordId"] } }],
+        });
+    }
+    if (and.length)
+        filter.$and = and;
+    return filter;
+}
+function withoutId(doc) {
+    const { _id: _drop, ...rest } = doc;
+    void _drop;
+    return rest;
+}
+function recordIdOf(doc) {
+    return typeof doc.recordId === "string" ? doc.recordId : doc._id;
+}
+function revisionOf(doc) {
+    return Number(doc.revision);
+}
+function stateOf(doc) {
+    const system = doc._system;
+    return isPlainObject(system) && typeof system.state === "string" ? system.state : "active";
+}
+function setDiscriminatorOp(ops) {
+    return ops.find((op) => op.op === "setDiscriminator");
+}
+async function evaluate(target, doc, ops) {
+    const stored = withoutId(doc);
+    let result;
+    try {
+        result = applyOps(stored, ops, { discriminatorPath: target.discriminatorPath });
+    }
+    catch (err) {
+        if (err instanceof PatchRowError)
+            return { kind: "fail", error: err.message };
+        throw err;
+    }
+    if (result.conflict)
+        return { kind: "conflict", reason: result.conflict };
+    const diff = bodyDiff(stored, result.record);
+    const sample = () => ({
+        recordId: recordIdOf(doc),
+        contentType: target.contentType,
+        revision: revisionOf(doc),
+        before: diff.before,
+        after: diff.after,
+    });
+    if (result.deleteRecord === "purge") {
+        const s = sample();
+        s.before.deleted = false;
+        s.after.deleted = true;
+        return { kind: "change", result, sample: s };
+    }
+    if (result.deleteRecord === "tombstone") {
+        if (stateOf(stored) === "archived" && !bodyChanged(stored, result.record))
+            return { kind: "unchanged" };
+        const s = sample();
+        s.before.state = stateOf(stored);
+        s.after.state = "archived";
+        return { kind: "change", result, sample: s };
+    }
+    if (result.discriminator && target.discriminatorPath) {
+        const recordId = recordIdOf(doc);
+        const newKey = computeDiscriminatedStorageKey({
+            recordId,
+            contentType: target.contentType,
+            discriminatorPath: target.discriminatorPath,
+            discriminatorValue: result.discriminator.value,
+        });
+        if (newKey !== doc._id) {
+            const existing = await target.coll.findOne({ _id: newKey });
+            if (existing && result.discriminator.onExisting === "skip") {
+                return {
+                    kind: "conflict",
+                    reason: `instance ${result.discriminator.value} already exists for ${recordId}`,
+                };
+            }
+            const s = sample();
+            const current = doc._id === recordId ? null : (readPlain(stored, target.discriminatorPath) ?? null);
+            s.before.discriminator = current;
+            if (existing && result.discriminator.onExisting === "deleteLegacy") {
+                s.after = { deleted: true, keptInstance: result.discriminator.value };
+            }
+            else {
+                s.after.discriminator = result.discriminator.value;
+                if (existing)
+                    s.after.replacesInstanceRevision = revisionOf(existing);
+            }
+            return { kind: "change", result, newKey, existingTarget: existing, sample: s };
+        }
+    }
+    if (!bodyChanged(stored, result.record))
+        return { kind: "unchanged" };
+    return { kind: "change", result, sample: sample() };
+}
+function collectWarnings(deps, request, targets) {
+    const warnings = new Set();
+    const meta = deps.catalog.getObjectType(request.select.objectType);
+    const dataPaths = [];
+    for (const op of request.ops) {
+        const paths = op.op === "move" || op.op === "copy"
+            ? [op.from, op.to]
+            : op.op === "set" || op.op === "mapValues" || op.op === "dropValues" || op.op === "rename"
+                ? [op.path]
+                : op.op === "delete" && "path" in op
+                    ? [op.path]
+                    : [];
+        for (const path of paths) {
+            if (path.startsWith("data."))
+                dataPaths.push(path.replace(/\[\]/g, ""));
+        }
+    }
+    const disc = setDiscriminatorOp(request.ops);
+    const selected = request.select.discriminator && "value" in request.select.discriminator
+        ? request.select.discriminator.value
+        : undefined;
+    for (const target of targets) {
+        const fields = (meta?.fields ?? []).filter((f) => !f.contentType || f.contentType === target.contentType);
+        if (fields.length) {
+            for (const path of dataPaths) {
+                const declared = fields.some((f) => f.path === path || path.startsWith(`${f.path}.`) || f.path.startsWith(`${path}.`));
+                if (!declared) {
+                    warnings.add(`${path} is not declared for ${target.objectType}/${target.contentType}`);
+                }
+            }
+        }
+        if (target.discriminatorPath && deps.declaredDiscriminatorValues) {
+            const values = deps.declaredDiscriminatorValues(target.objectType, target.contentType, target.discriminatorPath);
+            for (const value of [disc?.value, selected]) {
+                if (value !== undefined && values && !values.includes(value)) {
+                    warnings.add(`${target.discriminatorPath}='${value}' is not one of ${values.join(", ")} for ${target.contentType}`);
+                }
+            }
+        }
+    }
+    return [...warnings];
+}
+async function loadPatch(deps, patchId) {
+    const { patches } = await patchCollections(deps.operationalDb);
+    const doc = await patches.findOne({ _id: patchId, orgId: deps.scope.orgId });
+    if (!doc)
+        throw new ServiceError("PATCH_NOT_FOUND", `patch ${patchId} not found`, 404, { patchId });
+    if (doc.state === "planned" && doc.planExpiresAt < nowOf(deps)) {
+        throw new ServiceError("PATCH_NOT_FOUND", `the plan for ${patchId} expired; plan the patch again`, 404, {
+            patchId,
+            expiredAt: doc.planExpiresAt,
+        });
+    }
+    return doc;
+}
+export async function planPatch(deps, request) {
+    const limits = patchLimits(deps.limits);
+    const now = nowOf(deps);
+    const { patches, rows } = await patchCollections(deps.operationalDb);
+    const targets = request.select.contentTypes.map((ct) => resolveTarget(deps, request.select.objectType, ct));
+    const disc = setDiscriminatorOp(request.ops);
+    for (const target of targets) {
+        if (!target.discriminatorPath && request.select.discriminator && "value" in request.select.discriminator) {
+            invalid(`${target.contentType} has no discriminator; select.discriminator.value does not apply`, "select.discriminator");
+        }
+        if (!target.discriminatorPath && disc) {
+            invalid(`${target.contentType} has no discriminator; setDiscriminator does not apply`, "ops");
+        }
+    }
+    const warnings = collectWarnings(deps, request, targets);
+    const patchId = newPatchId();
+    const planExpiresAt = plusMs(now, limits.planTtlMs);
+    const expireAt = new Date(planExpiresAt);
+    const hash = createHash("sha256").update(canonicalJson({ orgId: deps.scope.orgId, request }));
+    const totals = { matched: 0, wouldChange: 0, unchanged: 0, conflicts: 0, failed: 0 };
+    const samples = [];
+    let limitHit = false;
+    let seq = 0;
+    let pending = [];
+    const flush = async () => {
+        if (!pending.length)
+            return;
+        await rows.insertMany(pending, { ordered: false });
+        pending = [];
+    };
+    try {
+        scan: for (const target of targets) {
+            const base = selectFilter(request.select, target.discriminatorPath);
+            let last;
+            for (;;) {
+                const filter = last === undefined ? base : { ...base, _id: { $gt: last } };
+                const page = await target.coll.find(filter).sort({ _id: 1 }).limit(PAGE).toArray();
+                for (const doc of page) {
+                    last = doc._id;
+                    if (request.select.where && !request.select.where.every((p) => evaluatePredicate(doc, p)))
+                        continue;
+                    if (request.select.limit !== undefined && totals.matched >= request.select.limit) {
+                        limitHit = true;
+                        break scan;
+                    }
+                    totals.matched += 1;
+                    if (totals.matched > limits.maxRows) {
+                        throw new ServiceError("PATCH_TOO_LARGE", `the patch matches more than ${limits.maxRows} rows; narrow select or set select.limit`, 413, { cap: limits.maxRows, field: "select", retryable: false });
+                    }
+                    const evaluation = await evaluate(target, doc, request.ops);
+                    const planned = evaluation.kind === "change" ? "change" : evaluation.kind === "fail" ? "fail" : evaluation.kind;
+                    if (evaluation.kind === "change") {
+                        totals.wouldChange += 1;
+                        if (samples.length < SAMPLE_LIMIT)
+                            samples.push(evaluation.sample);
+                    }
+                    else if (evaluation.kind === "unchanged")
+                        totals.unchanged += 1;
+                    else if (evaluation.kind === "conflict")
+                        totals.conflicts += 1;
+                    else
+                        totals.failed += 1;
+                    const row = {
+                        _id: `${patchId}:${seq}`,
+                        patchId,
+                        seq,
+                        objectType: target.objectType,
+                        contentType: target.contentType,
+                        recordId: recordIdOf(doc),
+                        storageKey: doc._id,
+                        plannedRevision: revisionOf(doc),
+                        planned,
+                        ...(evaluation.kind === "conflict" ? { plannedError: evaluation.reason } : {}),
+                        ...(evaluation.kind === "fail" ? { plannedError: evaluation.error } : {}),
+                        expireAt,
+                    };
+                    seq += 1;
+                    hash.update(`${target.contentType}\u0000${row.storageKey}\u0000${row.plannedRevision}\u0000${planned}\n`);
+                    pending.push(row);
+                    if (pending.length >= PAGE)
+                        await flush();
+                }
+                if (page.length < PAGE)
+                    break;
+            }
+        }
+        await flush();
+    }
+    catch (err) {
+        await rows.deleteMany({ patchId }).catch(() => undefined);
+        throw err;
+    }
+    const planChecksum = `sha256:${hash.digest("hex")}`;
+    const doc = {
+        _id: patchId,
+        patchId,
+        orgId: deps.scope.orgId,
+        agentIds: [...deps.scope.agentIds],
+        caller: deps.caller,
+        objectType: request.select.objectType,
+        contentTypes: [...request.select.contentTypes],
+        request,
+        state: "planned",
+        planChecksum,
+        plan: { ...totals, limitHit, warnings, samples },
+        counts: { changed: 0, unchanged: 0, drifted: 0, conflicts: 0, failed: 0 },
+        guards: request.guards,
+        guardsActive: false,
+        createdAt: now,
+        planExpiresAt,
+        expireAt,
+    };
+    await patches.insertOne(doc);
+    return {
+        patchId,
+        state: "planned",
+        planChecksum,
+        ...totals,
+        limitHit,
+        warnings,
+        samples,
+        guards: request.guards,
+        planExpiresAt,
+    };
+}
+async function liveCounts(rows, patchId) {
+    const grouped = await rows
+        .aggregate([
+        { $match: { patchId } },
+        { $group: { _id: { outcome: "$outcome", revert: "$revert" }, n: { $sum: 1 } } },
+    ])
+        .toArray();
+    const counts = { changed: 0, unchanged: 0, drifted: 0, conflicts: 0, failed: 0 };
+    const revert = { reverted: 0, drifted: 0, failed: 0 };
+    for (const { _id, n } of grouped) {
+        if (_id.outcome === "changed")
+            counts.changed += n;
+        else if (_id.outcome === "unchanged")
+            counts.unchanged += n;
+        else if (_id.outcome === "drifted")
+            counts.drifted += n;
+        else if (_id.outcome === "conflict")
+            counts.conflicts += n;
+        else if (_id.outcome === "failed")
+            counts.failed += n;
+        if (_id.revert === "reverted")
+            revert.reverted += n;
+        else if (_id.revert === "drifted")
+            revert.drifted += n;
+        else if (_id.revert === "failed")
+            revert.failed += n;
+    }
+    return { counts, revert };
+}
+function statusBody(doc, live) {
+    const counts = live?.counts ?? doc.counts;
+    const revertCounts = live && (doc.state === "reverting" || doc.state === "reverted") ? live.revert : doc.revertCounts;
+    return {
+        patchId: doc.patchId,
+        state: doc.state,
+        objectType: doc.objectType,
+        contentTypes: doc.contentTypes,
+        ...(doc.request.reason ? { reason: doc.request.reason } : {}),
+        caller: doc.caller,
+        createdAt: doc.createdAt,
+        ...(doc.state === "planned" ? { planExpiresAt: doc.planExpiresAt } : {}),
+        ...(doc.startedAt ? { startedAt: doc.startedAt } : {}),
+        ...(doc.finishedAt ? { finishedAt: doc.finishedAt } : {}),
+        ...(doc.revertStartedAt ? { revertStartedAt: doc.revertStartedAt } : {}),
+        ...(doc.revertedAt ? { revertedAt: doc.revertedAt } : {}),
+        ...(doc.revertRetainUntil ? { revertRetainUntil: doc.revertRetainUntil } : {}),
+        planChecksum: doc.planChecksum,
+        plan: doc.plan,
+        counts,
+        ...(revertCounts ? { revertCounts } : {}),
+        request: doc.request,
+        guards: doc.guards,
+        guardsActive: doc.guardsActive,
+        ...(doc.error ? { error: doc.error } : {}),
+    };
+}
+export async function getPatchStatus(deps, patchId) {
+    const doc = await loadPatch(deps, patchId);
+    if (doc.state === "applying" || doc.state === "reverting") {
+        const { rows } = await patchCollections(deps.operationalDb);
+        return statusBody(doc, await liveCounts(rows, patchId));
+    }
+    return statusBody(doc);
+}
+export async function listPatches(deps, query) {
+    const { patches } = await patchCollections(deps.operationalDb);
+    const limit = Math.min(Math.max(query.limit ?? 50, 1), 200);
+    const filter = {
+        orgId: deps.scope.orgId,
+        $or: [{ state: { $ne: "planned" } }, { planExpiresAt: { $gt: nowOf(deps) } }],
+    };
+    if (query.objectType)
+        filter.objectType = query.objectType;
+    if (query.state)
+        filter.state = query.state;
+    const docs = await patches.find(filter).sort({ createdAt: -1 }).limit(limit).toArray();
+    return { items: docs.map((doc) => statusBody(doc)) };
+}
+const ROW_OUTCOMES = new Set(["changed", "unchanged", "drifted", "conflict", "failed"]);
+export async function listPatchRecords(deps, patchId, query) {
+    await loadPatch(deps, patchId);
+    const { rows } = await patchCollections(deps.operationalDb);
+    const limit = Math.min(Math.max(query.limit ?? 100, 1), 500);
+    const filter = { patchId };
+    if (query.outcome !== undefined) {
+        if (query.outcome === "pending")
+            filter.outcome = { $exists: false };
+        else if (ROW_OUTCOMES.has(query.outcome))
+            filter.outcome = query.outcome;
+        else {
+            throw new ServiceError("VALIDATION", "outcome must be changed, unchanged, drifted, conflict, failed, or pending", 400, {
+                field: "outcome",
+            });
+        }
+    }
+    if (query.cursor !== undefined) {
+        const after = Number(query.cursor);
+        if (!Number.isInteger(after) || after < 0) {
+            throw new ServiceError("VALIDATION", "cursor is invalid", 400, { field: "cursor" });
+        }
+        filter.seq = { $gt: after };
+    }
+    const page = await rows
+        .find(filter, { projection: { before: 0, beforeTarget: 0 } })
+        .sort({ seq: 1 })
+        .limit(limit)
+        .toArray();
+    return {
+        items: page.map((row) => ({
+            recordId: row.recordId,
+            objectType: row.objectType,
+            contentType: row.contentType,
+            storageKey: row.storageKey,
+            plannedRevision: row.plannedRevision,
+            planned: row.planned,
+            ...(row.plannedError ? { plannedError: row.plannedError } : {}),
+            ...(row.outcome ? { outcome: row.outcome } : {}),
+            ...(row.error ? { error: row.error } : {}),
+            ...(row.after ? { after: row.after } : {}),
+            ...(row.revert ? { revert: row.revert } : {}),
+            ...(row.revertError ? { revertError: row.revertError } : {}),
+        })),
+        nextCursor: page.length === limit ? String(page.at(-1).seq) : null,
+    };
+}
+function historyOf(doc) {
+    return doc && Array.isArray(doc._history) ? doc._history : [];
+}
+function nextDoc(current, patched, now, entry, tombstone) {
+    const system = isPlainObject(current._system) ? { ...current._system } : {};
+    system.modifiedAt = now;
+    system.writtenAt = now;
+    if (tombstone) {
+        system.state = "archived";
+        const lifecycle = Array.isArray(system.lifecycle) ? system.lifecycle : [];
+        system.lifecycle = [...lifecycle, { process: "patch", processedAt: now }];
+    }
+    const next = {
+        ...patched,
+        revision: revisionOf(current) + 1,
+        _system: system,
+        _history: [...historyOf(current), entry],
+    };
+    next._markdown = resolveRecordMarkdown({
+        specified: false,
+        previous: readStoredMarkdown(current),
+        data: patched.data,
+        previousData: current.data,
+        now,
+    });
+    return next;
+}
+function restoredDoc(body, revision, history, now) {
+    const rest = withoutId(body);
+    const system = isPlainObject(rest._system) ? { ...rest._system } : {};
+    system.modifiedAt = now;
+    system.writtenAt = now;
+    return { ...rest, revision, _system: system, _history: history };
+}
+async function notify(deps, event) {
+    try {
+        await deps.onRowWritten?.(event);
+    }
+    catch (err) {
+        deps.log?.("patch: row effects failed", { recordId: event.recordId, error: message(err) });
+    }
+}
+function writtenByPatch(doc, patchId) {
+    const last = historyOf(doc ?? undefined).at(-1);
+    return Boolean(doc && last && last.patchId === patchId && last.action === "patch");
+}
+/** A row whose prior body was saved but whose outcome was not: the write may have landed before a restart. */
+async function recoverApplied(target, patch, row) {
+    const disc = setDiscriminatorOp(patch.request.ops);
+    const current = await target.coll.findOne({ _id: row.storageKey });
+    if (disc && target.discriminatorPath) {
+        const newKey = computeDiscriminatedStorageKey({
+            recordId: row.recordId,
+            contentType: row.contentType,
+            discriminatorPath: target.discriminatorPath,
+            discriminatorValue: disc.value,
+        });
+        if (newKey !== row.storageKey) {
+            const moved = await target.coll.findOne({ _id: newKey });
+            if (writtenByPatch(moved, patch.patchId)) {
+                if (current && revisionOf(current) === row.plannedRevision) {
+                    await target.coll.deleteOne({ _id: row.storageKey, revision: row.plannedRevision });
+                }
+                return { outcome: "changed", after: { storageKey: newKey, revision: revisionOf(moved) } };
+            }
+            if (!current && disc.onExisting === "deleteLegacy" && moved) {
+                return { outcome: "changed", after: { deleted: true, mode: "legacy", keptStorageKey: newKey } };
+            }
+        }
+    }
+    if (current && revisionOf(current) === row.plannedRevision)
+        return null;
+    if (writtenByPatch(current, patch.patchId)) {
+        return { outcome: "changed", after: { storageKey: row.storageKey, revision: revisionOf(current) } };
+    }
+    const purge = patch.request.ops.some((op) => op.op === "deleteRecord" && op.mode === "purge");
+    if (!current && purge)
+        return { outcome: "changed", after: { deleted: true, mode: "purge" } };
+    return { outcome: "drifted" };
+}
+async function commitChange(deps, patch, target, current, evaluation) {
+    const now = nowOf(deps);
+    const recordId = recordIdOf(current);
+    const revision = revisionOf(current);
+    const entry = { action: "patch", patchId: patch.patchId, caller: deps.caller, modifiedAt: now };
+    const { result } = evaluation;
+    const event = (op, next) => ({
+        objectType: target.objectType,
+        contentType: target.contentType,
+        recordId,
+        op,
+        ...(next ? { revision: Number(next.revision), data: next.data } : {}),
+    });
+    if (result.deleteRecord === "purge") {
+        const deleted = await target.coll.deleteOne({ _id: current._id, revision });
+        if (!deleted.deletedCount)
+            return { outcome: "drifted" };
+        await deps.reconcileDirectory?.(recordId);
+        await notify(deps, event("removed"));
+        return { outcome: "changed", after: { deleted: true, mode: "purge" } };
+    }
+    const next = nextDoc(current, result.record, now, entry, result.deleteRecord === "tombstone");
+    if (evaluation.newKey && result.discriminator) {
+        const newKey = evaluation.newKey;
+        const existing = evaluation.existingTarget ?? null;
+        if (existing && result.discriminator.onExisting === "deleteLegacy") {
+            const deleted = await target.coll.deleteOne({ _id: current._id, revision });
+            if (!deleted.deletedCount)
+                return { outcome: "drifted" };
+            return { outcome: "changed", after: { deleted: true, mode: "legacy", keptStorageKey: newKey } };
+        }
+        if (existing) {
+            next.revision = Math.max(revisionOf(existing), revision) + 1;
+            const replaced = await target.coll.replaceOne({ _id: newKey, revision: revisionOf(existing) }, { _id: newKey, ...next });
+            if (!replaced.matchedCount)
+                return { outcome: "drifted", error: "the existing instance moved after the plan" };
+        }
+        else {
+            try {
+                await target.coll.insertOne({ _id: newKey, ...next });
+            }
+            catch (err) {
+                if (/E11000|duplicate/i.test(message(err))) {
+                    return { outcome: "drifted", error: "the target instance was written after the plan" };
+                }
+                throw err;
+            }
+        }
+        const deleted = await target.coll.deleteOne({ _id: current._id, revision });
+        if (!deleted.deletedCount) {
+            if (existing) {
+                await target.coll.replaceOne({ _id: newKey, revision: Number(next.revision) }, existing);
+            }
+            else {
+                await target.coll.deleteOne({ _id: newKey, revision: Number(next.revision) });
+            }
+            return { outcome: "drifted" };
+        }
+        await notify(deps, event("updated", next));
+        return { outcome: "changed", after: { storageKey: newKey, revision: Number(next.revision) } };
+    }
+    const replaced = await target.coll.replaceOne({ _id: current._id, revision }, { _id: current._id, ...next });
+    if (!replaced.matchedCount)
+        return { outcome: "drifted" };
+    await notify(deps, event("updated", next));
+    return { outcome: "changed", after: { storageKey: current._id, revision: Number(next.revision) } };
+}
+async function applyRow(deps, patch, row) {
+    if (row.planned === "unchanged")
+        return { outcome: "unchanged" };
+    if (row.planned === "conflict")
+        return { outcome: "conflict", ...(row.plannedError ? { error: row.plannedError } : {}) };
+    if (row.planned === "fail")
+        return { outcome: "failed", ...(row.plannedError ? { error: row.plannedError } : {}) };
+    const target = resolveTarget(deps, row.objectType, row.contentType);
+    if (row.before) {
+        const recovered = await recoverApplied(target, patch, row);
+        if (recovered)
+            return recovered;
+    }
+    const current = await target.coll.findOne({ _id: row.storageKey });
+    if (!current || revisionOf(current) !== row.plannedRevision)
+        return { outcome: "drifted" };
+    const evaluation = await evaluate(target, current, patch.request.ops);
+    if (evaluation.kind === "unchanged")
+        return { outcome: "unchanged" };
+    if (evaluation.kind === "conflict")
+        return { outcome: "conflict", error: evaluation.reason };
+    if (evaluation.kind === "fail")
+        return { outcome: "failed", error: evaluation.error };
+    const { rows } = await patchCollections(deps.operationalDb);
+    const keepTarget = evaluation.existingTarget && evaluation.result.discriminator?.onExisting === "replace"
+        ? { beforeTarget: evaluation.existingTarget }
+        : {};
+    await rows.updateOne({ _id: row._id }, { $set: { before: current, ...keepTarget } });
+    return commitChange(deps, patch, target, current, evaluation);
+}
+async function revertRow(deps, patch, row) {
+    const before = row.before;
+    const after = row.after;
+    if (!before || !after)
+        return { revert: "skipped" };
+    const target = resolveTarget(deps, row.objectType, row.contentType);
+    const now = nowOf(deps);
+    const entry = { action: "patch-revert", patchId: patch.patchId, caller: deps.caller, modifiedAt: now };
+    const event = (revision, data) => ({
+        objectType: row.objectType,
+        contentType: row.contentType,
+        recordId: row.recordId,
+        op: "updated",
+        revision,
+        data: data,
+    });
+    if ("deleted" in after) {
+        if (await target.coll.findOne({ _id: row.storageKey }))
+            return { revert: "drifted" };
+        const restored = restoredDoc(before, revisionOf(before) + 1, [...historyOf(before), entry], now);
+        try {
+            await target.coll.insertOne({ _id: row.storageKey, ...restored });
+        }
+        catch (err) {
+            if (/E11000|duplicate/i.test(message(err)))
+                return { revert: "drifted" };
+            throw err;
+        }
+        if (after.mode === "purge")
+            await deps.reconcileDirectory?.(row.recordId);
+        await notify(deps, event(Number(restored.revision), restored.data));
+        return { revert: "reverted" };
+    }
+    const current = await target.coll.findOne({ _id: after.storageKey });
+    if (!current || revisionOf(current) !== after.revision)
+        return { revert: "drifted" };
+    if (after.storageKey === row.storageKey) {
+        const restored = restoredDoc(before, revisionOf(current) + 1, [...historyOf(current), entry], now);
+        const replaced = await target.coll.replaceOne({ _id: row.storageKey, revision: revisionOf(current) }, { _id: row.storageKey, ...restored });
+        if (!replaced.matchedCount)
+            return { revert: "drifted" };
+        await notify(deps, event(Number(restored.revision), restored.data));
+        return { revert: "reverted" };
+    }
+    if (await target.coll.findOne({ _id: row.storageKey }))
+        return { revert: "drifted" };
+    const legacy = restoredDoc(before, Math.max(revisionOf(before), revisionOf(current)) + 1, [...historyOf(current), entry], now);
+    try {
+        await target.coll.insertOne({ _id: row.storageKey, ...legacy });
+    }
+    catch (err) {
+        if (/E11000|duplicate/i.test(message(err)))
+            return { revert: "drifted" };
+        throw err;
+    }
+    let undone;
+    if (row.beforeTarget) {
+        const restoredTarget = restoredDoc(row.beforeTarget, revisionOf(current) + 1, [...historyOf(row.beforeTarget), entry], now);
+        const replaced = await target.coll.replaceOne({ _id: after.storageKey, revision: revisionOf(current) }, { _id: after.storageKey, ...restoredTarget });
+        undone = replaced.matchedCount === 1;
+    }
+    else {
+        const deleted = await target.coll.deleteOne({ _id: after.storageKey, revision: revisionOf(current) });
+        undone = deleted.deletedCount === 1;
+    }
+    if (!undone) {
+        await target.coll.deleteOne({ _id: row.storageKey, revision: Number(legacy.revision) });
+        return { revert: "drifted" };
+    }
+    await notify(deps, event(Number(legacy.revision), legacy.data));
+    return { revert: "reverted" };
+}
+async function runWork(deps, patchId, mode) {
+    if (running.has(patchId))
+        return;
+    running.add(patchId);
+    const limits = patchLimits(deps.limits);
+    let collections;
+    try {
+        collections = await patchCollections(deps.operationalDb);
+    }
+    catch (err) {
+        running.delete(patchId);
+        deps.log?.("patch: work not started", { patchId, mode, error: message(err) });
+        return;
+    }
+    const { patches, rows } = collections;
+    const activeState = mode === "apply" ? "applying" : "reverting";
+    try {
+        for (;;) {
+            const owned = await patches.findOneAndUpdate({ _id: patchId, state: activeState, "lease.owner": PROCESS_OWNER }, { $set: { "lease.until": plusMs(nowOf(deps), limits.leaseMs) } }, { returnDocument: "after" });
+            if (!owned)
+                return;
+            const filter = mode === "apply"
+                ? { patchId, outcome: { $exists: false } }
+                : { patchId, outcome: "changed", revert: { $exists: false } };
+            const batch = await rows.find(filter).sort({ seq: 1 }).limit(WORK_BATCH).toArray();
+            if (!batch.length)
+                break;
+            for (const row of batch) {
+                let update;
+                try {
+                    update = mode === "apply" ? await applyRow(deps, owned, row) : await revertRow(deps, owned, row);
+                }
+                catch (err) {
+                    if (isInfrastructureError(err))
+                        throw err;
+                    update = mode === "apply" ? { outcome: "failed", error: message(err) } : { revert: "failed", revertError: message(err) };
+                }
+                await rows.updateOne({ _id: row._id }, { $set: update });
+            }
+        }
+        const live = await liveCounts(rows, patchId);
+        const finishedAt = nowOf(deps);
+        if (mode === "apply") {
+            await rows.updateMany({ patchId }, { $set: { expireAt: new Date(Date.parse(finishedAt) + limits.retainMs) } });
+            await patches.updateOne({ _id: patchId, "lease.owner": PROCESS_OWNER }, {
+                $set: {
+                    state: "applied",
+                    counts: live.counts,
+                    finishedAt,
+                    revertRetainUntil: plusMs(finishedAt, limits.retainMs - DAY_MS),
+                },
+                $unset: { lease: "", error: "" },
+            });
+        }
+        else {
+            await patches.updateOne({ _id: patchId, "lease.owner": PROCESS_OWNER }, { $set: { state: "reverted", revertCounts: live.revert, revertedAt: finishedAt }, $unset: { lease: "", error: "" } });
+        }
+    }
+    catch (err) {
+        deps.log?.("patch: work stopped", { patchId, mode, error: message(err) });
+        if (isInfrastructureError(err)) {
+            await patches
+                .updateOne({ _id: patchId, "lease.owner": PROCESS_OWNER }, { $set: { error: message(err) }, $unset: { lease: "" } })
+                .catch(() => undefined);
+        }
+        else {
+            const live = await liveCounts(rows, patchId).catch(() => undefined);
+            await patches
+                .updateOne({ _id: patchId, "lease.owner": PROCESS_OWNER }, {
+                $set: {
+                    state: "failed",
+                    error: message(err),
+                    finishedAt: nowOf(deps),
+                    ...(live ? { counts: live.counts } : {}),
+                },
+                $unset: { lease: "" },
+            })
+                .catch(() => undefined);
+        }
+    }
+    finally {
+        running.delete(patchId);
+    }
+}
+async function assertHourlyCap(deps, doc, limits) {
+    const { patches } = await patchCollections(deps.operationalDb);
+    const since = plusMs(nowOf(deps), -60 * 60 * 1000);
+    const [used] = await patches
+        .aggregate([
+        { $match: { orgId: deps.scope.orgId, startedAt: { $gte: since } } },
+        { $group: { _id: null, n: { $sum: "$plan.wouldChange" } } },
+    ])
+        .toArray();
+    const total = (used?.n ?? 0) + doc.plan.wouldChange;
+    if (total > limits.maxRowsPerHour) {
+        throw new ServiceError("PATCH_TOO_LARGE", `applying ${doc.plan.wouldChange} rows would pass the cap of ${limits.maxRowsPerHour} changed rows per hour`, 413, { cap: limits.maxRowsPerHour, window: "1h", used: used?.n ?? 0, retryable: true, retryAfterMs: 60 * 60 * 1000 });
+    }
+}
+function requireConfirm(body, action) {
+    const raw = isPlainObject(body) ? body : {};
+    if (raw.confirm !== true) {
+        throw new ServiceError("CONFIRMATION_REQUIRED", `confirm: true is required; nothing was ${action}`, 400, {
+            field: "confirm",
+            retryable: false,
+        });
+    }
+    return raw;
+}
+async function finishOrBackground(deps, patchId, mode, pending) {
+    const limits = patchLimits(deps.limits);
+    if (pending <= limits.syncRows) {
+        await runWork(deps, patchId, mode);
+        const body = await getPatchStatus(deps, patchId);
+        return { httpStatus: body.state === "applying" || body.state === "reverting" ? 202 : 200, body };
+    }
+    void runWork(deps, patchId, mode);
+    return { httpStatus: 202, body: await getPatchStatus(deps, patchId) };
+}
+export async function applyPatch(deps, patchId, body) {
+    const raw = requireConfirm(body, "applied");
+    const doc = await loadPatch(deps, patchId);
+    if (raw.planChecksum !== doc.planChecksum) {
+        throw new ServiceError("PATCH_PLAN_STALE", "planChecksum does not match the plan for this patch", 409, {
+            field: "planChecksum",
+            retryable: false,
+        });
+    }
+    if (doc.state === "applying" || doc.state === "applied") {
+        return { httpStatus: doc.state === "applied" ? 200 : 202, body: await getPatchStatus(deps, patchId) };
+    }
+    if (doc.state !== "planned") {
+        throw new ServiceError("PATCH_STATE_CONFLICT", `patch ${patchId} is ${doc.state}; it cannot be applied`, 409, {
+            state: doc.state,
+        });
+    }
+    const limits = patchLimits(deps.limits);
+    await assertHourlyCap(deps, doc, limits);
+    const now = nowOf(deps);
+    const { patches, rows } = await patchCollections(deps.operationalDb);
+    const claimed = await patches.findOneAndUpdate({ _id: patchId, state: "planned" }, {
+        $set: {
+            state: "applying",
+            startedAt: now,
+            appliedBy: deps.caller,
+            guardsActive: doc.guards.length > 0,
+            lease: { owner: PROCESS_OWNER, until: plusMs(now, limits.leaseMs) },
+        },
+        $unset: { expireAt: "" },
+    }, { returnDocument: "after" });
+    if (!claimed)
+        return { httpStatus: 202, body: await getPatchStatus(deps, patchId) };
+    if (claimed.guardsActive)
+        invalidatePatchGuards(deps.scope.orgId);
+    await rows.updateMany({ patchId }, { $set: { expireAt: new Date(Date.parse(now) + limits.retainMs) } });
+    await rows.updateMany({ patchId, planned: "unchanged" }, { $set: { outcome: "unchanged" } });
+    return finishOrBackground(deps, patchId, "apply", doc.plan.wouldChange + doc.plan.conflicts + doc.plan.failed);
+}
+export async function revertPatch(deps, patchId, body) {
+    requireConfirm(body, "reverted");
+    const doc = await loadPatch(deps, patchId);
+    if (doc.state === "reverting" || doc.state === "reverted") {
+        return { httpStatus: doc.state === "reverted" ? 200 : 202, body: await getPatchStatus(deps, patchId) };
+    }
+    if (doc.state !== "applied" && doc.state !== "failed") {
+        throw new ServiceError("PATCH_STATE_CONFLICT", `patch ${patchId} is ${doc.state}; only an applied patch can be reverted`, 409, {
+            state: doc.state,
+        });
+    }
+    const now = nowOf(deps);
+    if (doc.revertRetainUntil && doc.revertRetainUntil < now) {
+        throw new ServiceError("PATCH_REVERT_EXPIRED", `prior bodies for ${patchId} are no longer kept`, 409, {
+            revertRetainUntil: doc.revertRetainUntil,
+        });
+    }
+    const limits = patchLimits(deps.limits);
+    const { patches } = await patchCollections(deps.operationalDb);
+    const claimed = await patches.findOneAndUpdate({ _id: patchId, state: doc.state }, {
+        $set: {
+            state: "reverting",
+            revertStartedAt: now,
+            revertedBy: deps.caller,
+            guardsActive: false,
+            lease: { owner: PROCESS_OWNER, until: plusMs(now, limits.leaseMs) },
+        },
+    }, { returnDocument: "after" });
+    if (!claimed)
+        return { httpStatus: 202, body: await getPatchStatus(deps, patchId) };
+    invalidatePatchGuards(deps.scope.orgId);
+    return finishOrBackground(deps, patchId, "revert", doc.counts.changed);
+}
+export async function removePatchGuards(deps, patchId) {
+    const doc = await loadPatch(deps, patchId);
+    const { patches } = await patchCollections(deps.operationalDb);
+    await patches.updateOne({ _id: patchId }, { $set: { guardsActive: false } });
+    invalidatePatchGuards(deps.scope.orgId);
+    return { patchId, guards: doc.guards, guardsActive: false };
+}
+export async function loadPatchForAccess(deps, patchId) {
+    return loadPatch(deps, patchId);
+}
+/**
+ * Pick up apply or revert work whose lease ran out, for example after a restart.
+ * `depsFor` builds engine deps from the stored patch (org, agents, caller).
+ */
+export async function resumePatchWork(db, depsFor) {
+    const { patches } = await patchCollections(db);
+    const now = new Date().toISOString();
+    const stale = {
+        state: { $in: ["applying", "reverting"] },
+        $or: [{ lease: { $exists: false } }, { "lease.until": { $lt: now } }],
+    };
+    const candidates = await patches.find(stale).limit(5).toArray();
+    let resumed = 0;
+    for (const candidate of candidates) {
+        if (running.has(candidate._id))
+            continue;
+        const deps = depsFor(candidate);
+        if (!deps)
+            continue;
+        const limits = patchLimits(deps.limits);
+        const claimed = await patches.findOneAndUpdate({ _id: candidate._id, ...stale }, { $set: { lease: { owner: PROCESS_OWNER, until: plusMs(now, limits.leaseMs) } } }, { returnDocument: "after" });
+        if (!claimed)
+            continue;
+        resumed += 1;
+        void runWork(deps, claimed._id, claimed.state === "applying" ? "apply" : "revert");
+    }
+    return resumed;
+}
+//# sourceMappingURL=engine.js.map