clay-server 4.1.0-beta.4 → 4.1.0-beta.6

package/lib/durable-scheduler.js

@@ -0,0 +1,495 @@
+var crypto = require("crypto");
+var path = require("path");
+var attachStore = require("./durable-scheduler-store").attachDurableSchedulerStore;
+var validateSavedJobs = require("./durable-scheduler-record").validateSavedJobs;
+
+function copy(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function requiredString(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(name + " is required");
+  if (value.length > 256) throw new Error(name + " is too long");
+  return value;
+}
+
+function safeValue(value, name, maxBytes) {
+  var cloned;
+  var serialized;
+  try {
+    cloned = copy(value);
+    serialized = JSON.stringify(cloned);
+  } catch (error) {
+    throw new Error(name + " must be JSON serializable");
+  }
+  if (Buffer.byteLength(serialized || "", "utf8") > maxBytes) throw new Error(name + " is too large");
+  return cloned;
+}
+
+function attachDurableScheduler(ctx) {
+  var namespace = requiredString(ctx.namespace, "namespace");
+  var now = ctx.now || Date.now;
+  var makeId = ctx.makeId || function () { return crypto.randomUUID(); };
+  var setTimer = ctx.setTimer || setTimeout;
+  var clearTimer = ctx.clearTimer || clearTimeout;
+  var maxTimerDelay = Math.min(Math.max(ctx.maxTimerDelay || 30000, 10), 2147483647);
+  var globalConcurrency = Math.max(1, ctx.globalConcurrency || 4);
+  var perOwnerConcurrency = Math.max(1, ctx.perOwnerConcurrency || 1);
+  var store = ctx.store || attachStore({
+    filePath: ctx.filePath || path.join(ctx.storageDir, "scheduler-" + namespace + ".json"),
+    namespace: namespace,
+  });
+  var handlers = Object.create(null);
+  var eligibility = Object.create(null);
+  var active = Object.create(null);
+  var timer = null;
+  var started = false;
+  var closed = false;
+  var unhealthyError = null;
+  var ownerCursor = 0;
+  var data;
+
+  function persist(nextData) {
+    if (unhealthyError) throw unhealthyError;
+    try {
+      store.save(nextData);
+    } catch (error) {
+      unhealthyError = error;
+      stopTimer();
+      throw error;
+    }
+    data = nextData;
+  }
+
+  function recover() {
+    try {
+      data = store.load();
+      validateSavedJobs(data.jobs);
+    } catch (error) {
+      store.close();
+      var loadError = new Error("Scheduler store contains invalid durable data: " + error.message);
+      loadError.code = error.code || "SCHEDULER_STORE_CORRUPT";
+      loadError.cause = error;
+      throw loadError;
+    }
+    var changed = false;
+    var recoveredAt = now();
+    for (var i = 0; i < data.jobs.length; i++) {
+      var job = data.jobs[i];
+      if (job.state === "claimed" || job.state === "running") {
+        job.state = "interrupted";
+        job.updatedAt = recoveredAt;
+        job.execution = job.execution || {};
+        job.execution.interruptedAt = recoveredAt;
+        job.execution.interruptionReason = "server_restarted_after_claim";
+        changed = true;
+      }
+    }
+    if (changed) persist(data);
+  }
+
+  function ensureReady() {
+    if (closed) throw new Error("Scheduler is shut down");
+    if (unhealthyError) throw unhealthyError;
+  }
+
+  function findJob(id) {
+    for (var i = 0; i < data.jobs.length; i++) if (data.jobs[i].id === id) return data.jobs[i];
+    return null;
+  }
+
+  function findIdempotency(key, exceptId) {
+    for (var i = 0; i < data.jobs.length; i++) {
+      if (data.jobs[i].id !== exceptId && data.jobs[i].idempotencyKey === key) return data.jobs[i];
+    }
+    return null;
+  }
+
+  function validateSpec(spec) {
+    var runAt = Number(spec.runAt);
+    if (!isFinite(runAt) || runAt < 0) throw new Error("runAt must be a non-negative timestamp");
+    var target = safeValue(spec.target, "target", 4096);
+    if (!target || typeof target !== "object" || Array.isArray(target)) throw new Error("target is required");
+    requiredString(target.kind, "target.kind");
+    requiredString(target.id, "target.id");
+    return {
+      type: requiredString(spec.type, "type"),
+      idempotencyKey: requiredString(spec.idempotencyKey, "idempotencyKey"),
+      ownerId: requiredString(spec.ownerId, "ownerId"),
+      projectId: requiredString(spec.projectId, "projectId"),
+      target: target,
+      payload: safeValue(spec.payload === undefined ? null : spec.payload, "payload", 256 * 1024),
+      runAt: runAt,
+    };
+  }
+
+  function enqueue(spec) {
+    ensureReady();
+    var valid = validateSpec(spec || {});
+    var existing = findIdempotency(valid.idempotencyKey);
+    if (existing) {
+      var same = existing.type === valid.type && existing.ownerId === valid.ownerId &&
+        existing.projectId === valid.projectId && existing.runAt === valid.runAt &&
+        JSON.stringify(existing.target) === JSON.stringify(valid.target) &&
+        JSON.stringify(existing.payload) === JSON.stringify(valid.payload);
+      if (!same) throw new Error("idempotencyKey was already used with different job data");
+      return copy(existing);
+    }
+    var createdAt = now();
+    var job = {
+      id: spec.id ? requiredString(spec.id, "id") : makeId(),
+      idempotencyKey: valid.idempotencyKey,
+      type: valid.type,
+      ownerId: valid.ownerId,
+      projectId: valid.projectId,
+      target: valid.target,
+      payload: valid.payload,
+      runAt: valid.runAt,
+      state: "queued",
+      createdAt: createdAt,
+      updatedAt: createdAt,
+      execution: null,
+    };
+    if (findJob(job.id)) throw new Error("job id already exists");
+    var next = copy(data);
+    next.jobs.push(job);
+    persist(next);
+    scheduleTimer();
+    return copy(job);
+  }
+
+  function cancel(id, reason) {
+    ensureReady();
+    var current = findJob(id);
+    if (!current) return null;
+    if (current.state !== "queued") throw new Error("Only queued jobs can be cancelled");
+    var next = copy(data);
+    var job = null;
+    for (var i = 0; i < next.jobs.length; i++) if (next.jobs[i].id === id) job = next.jobs[i];
+    job.state = "cancelled";
+    job.updatedAt = now();
+    job.cancelledReason = typeof reason === "string" ? reason.slice(0, 1024) : null;
+    persist(next);
+    scheduleTimer();
+    return copy(job);
+  }
+
+  function replaceQueued(id, spec) {
+    ensureReady();
+    var current = findJob(id);
+    if (!current) return null;
+    if (current.state !== "queued") throw new Error("Only queued jobs can be replaced");
+    var merged = {
+      type: spec.type === undefined ? current.type : spec.type,
+      idempotencyKey: spec.idempotencyKey === undefined ? current.idempotencyKey : spec.idempotencyKey,
+      ownerId: spec.ownerId === undefined ? current.ownerId : spec.ownerId,
+      projectId: spec.projectId === undefined ? current.projectId : spec.projectId,
+      target: spec.target === undefined ? current.target : spec.target,
+      payload: spec.payload === undefined ? current.payload : spec.payload,
+      runAt: spec.runAt === undefined ? current.runAt : spec.runAt,
+    };
+    var valid = validateSpec(merged);
+    if (findIdempotency(valid.idempotencyKey, id)) throw new Error("idempotencyKey already exists");
+    var next = copy(data);
+    var job = null;
+    for (var i = 0; i < next.jobs.length; i++) if (next.jobs[i].id === id) job = next.jobs[i];
+    job.type = valid.type;
+    job.idempotencyKey = valid.idempotencyKey;
+    job.ownerId = valid.ownerId;
+    job.projectId = valid.projectId;
+    job.target = valid.target;
+    job.payload = valid.payload;
+    job.runAt = valid.runAt;
+    job.updatedAt = now();
+    persist(next);
+    scheduleTimer();
+    return copy(job);
+  }
+
+  function activeOwnerCount(ownerId) {
+    var ids = Object.keys(active);
+    var count = 0;
+    for (var i = 0; i < ids.length; i++) if (active[ids[i]].ownerId === ownerId) count++;
+    return count;
+  }
+
+  function isEligible(job) {
+    if (!eligibility[job.type]) return true;
+    try { return eligibility[job.type](copy(job)) === true; } catch (error) { return false; }
+  }
+
+  function dueByFairOwner(timestamp) {
+    var byOwner = Object.create(null);
+    var owners = [];
+    for (var i = 0; i < data.jobs.length; i++) {
+      var job = data.jobs[i];
+      if (job.state !== "queued" || job.runAt > timestamp || !handlers[job.type]) continue;
+      if (!isEligible(job)) continue;
+      if (!byOwner[job.ownerId]) {
+        byOwner[job.ownerId] = [];
+        owners.push(job.ownerId);
+      }
+      byOwner[job.ownerId].push(job);
+    }
+    for (var ownerName in byOwner) {
+      byOwner[ownerName].sort(function (left, right) {
+        return left.runAt - right.runAt || left.createdAt - right.createdAt || left.id.localeCompare(right.id);
+      });
+    }
+    owners.sort();
+    if (!owners.length) return [];
+    var offset = ownerCursor % owners.length;
+    var ordered = owners.slice(offset).concat(owners.slice(0, offset));
+    ownerCursor = (offset + 1) % owners.length;
+    var result = [];
+    var selectedByOwner = Object.create(null);
+    var available = globalConcurrency - Object.keys(active).length;
+    while (available > 0) {
+      var progressed = false;
+      for (var oi = 0; oi < ordered.length && available > 0; oi++) {
+        var owner = ordered[oi];
+        if (activeOwnerCount(owner) + (selectedByOwner[owner] || 0) >= perOwnerConcurrency) continue;
+        if (!byOwner[owner].length) continue;
+        result.push(byOwner[owner].shift());
+        selectedByOwner[owner] = (selectedByOwner[owner] || 0) + 1;
+        available--;
+        progressed = true;
+      }
+      if (!progressed) break;
+    }
+    return result;
+  }
+
+  function updateExecution(id, claimId, mutate) {
+    ensureReady();
+    var current = findJob(id);
+    if (!current || !current.execution || current.execution.claimId !== claimId || current.state !== "running") {
+      throw new Error("Job execution is no longer active");
+    }
+    var next = copy(data);
+    var job = null;
+    for (var i = 0; i < next.jobs.length; i++) if (next.jobs[i].id === id) job = next.jobs[i];
+    mutate(job);
+    job.updatedAt = now();
+    persist(next);
+    return copy(job.execution);
+  }
+
+  function settle(id, claimId, state, result) {
+    if (closed || unhealthyError) return;
+    var current = findJob(id);
+    if (!current || !current.execution || current.execution.claimId !== claimId || current.state !== "running") return;
+    var next = copy(data);
+    var job = null;
+    for (var i = 0; i < next.jobs.length; i++) if (next.jobs[i].id === id) job = next.jobs[i];
+    job.state = state;
+    job.updatedAt = now();
+    if (state === "completed") {
+      job.execution.completedAt = job.updatedAt;
+      if (result !== undefined) {
+        try {
+          job.execution.result = safeValue(result, "handler result", 64 * 1024);
+        } catch (error) {
+          job.state = "failed";
+          delete job.execution.completedAt;
+          job.execution.failedAt = job.updatedAt;
+          job.execution.error = error.message;
+        }
+      }
+    } else {
+      job.execution.failedAt = job.updatedAt;
+      job.execution.error = String(result && result.message ? result.message : result).slice(0, 4096);
+    }
+    try { persist(next); } catch (error) {}
+  }
+
+  function requeueUnstarted(id, claimId) {
+    if (closed || unhealthyError) return;
+    var current = findJob(id);
+    if (!current || !current.execution || current.execution.claimId !== claimId || current.state !== "running") return;
+    var next = copy(data);
+    var job = null;
+    for (var i = 0; i < next.jobs.length; i++) if (next.jobs[i].id === id) job = next.jobs[i];
+    job.state = "queued";
+    job.updatedAt = now();
+    job.execution = null;
+    persist(next);
+  }
+
+  function dispatch(job) {
+    if (active[job.id] || unhealthyError || closed) return;
+    var handler = handlers[job.type];
+    if (!handler) return;
+    var claimId = makeId();
+    var claimedAt = now();
+    var claimed = copy(data);
+    var claimedJob = null;
+    for (var i = 0; i < claimed.jobs.length; i++) if (claimed.jobs[i].id === job.id) claimedJob = claimed.jobs[i];
+    if (!claimedJob || claimedJob.state !== "queued") return;
+    claimedJob.state = "claimed";
+    claimedJob.updatedAt = claimedAt;
+    claimedJob.execution = { claimId: claimId, claimedAt: claimedAt, attempt: 1, metadata: null, receipt: null };
+    persist(claimed);
+
+    var running = copy(data);
+    var runningJob = null;
+    for (var ri = 0; ri < running.jobs.length; ri++) if (running.jobs[ri].id === job.id) runningJob = running.jobs[ri];
+    runningJob.state = "running";
+    runningJob.updatedAt = now();
+    runningJob.execution.startedAt = runningJob.updatedAt;
+    persist(running);
+    active[job.id] = { ownerId: job.ownerId, claimId: claimId };
+
+    var execution = {
+      claimId: claimId,
+      recordMetadata: function (metadata) {
+        return updateExecution(job.id, claimId, function (record) {
+          record.execution.metadata = safeValue(metadata, "execution metadata", 64 * 1024);
+        });
+      },
+      recordReceipt: function (receipt) {
+        return updateExecution(job.id, claimId, function (record) {
+          record.execution.receipt = safeValue(receipt, "execution receipt", 64 * 1024);
+        });
+      },
+    };
+    Promise.resolve().then(function () {
+      if (closed || unhealthyError || !active[job.id]) return undefined;
+      if (handlers[job.type] !== handler) {
+        requeueUnstarted(job.id, claimId);
+        return undefined;
+      }
+      if (!isEligible(runningJob)) {
+        requeueUnstarted(job.id, claimId);
+        return undefined;
+      }
+      return handler(copy(runningJob), execution);
+    }).then(function (result) {
+      settle(job.id, claimId, "completed", result);
+    }, function (error) {
+      settle(job.id, claimId, "failed", error);
+    }).finally(function () {
+      delete active[job.id];
+      scheduleTimer();
+      if (!closed && !unhealthyError) {
+        try { tick(); } catch (error) {}
+      }
+    }).catch(function () {});
+  }
+
+  function tick() {
+    ensureReady();
+    var due = dueByFairOwner(now());
+    for (var i = 0; i < due.length; i++) {
+      dispatch(due[i]);
+    }
+    scheduleTimer();
+    return due.length;
+  }
+
+  function stopTimer() {
+    if (timer !== null) {
+      clearTimer(timer);
+      timer = null;
+    }
+  }
+
+  function scheduleTimer() {
+    stopTimer();
+    if (!started || closed || unhealthyError) return;
+    var timestamp = now();
+    var earliest = null;
+    var activeCount = Object.keys(active).length;
+    if (activeCount < globalConcurrency) {
+      for (var i = 0; i < data.jobs.length; i++) {
+        var job = data.jobs[i];
+        if (job.state !== "queued" || !handlers[job.type]) continue;
+        if (!isEligible(job)) continue;
+        if (activeOwnerCount(job.ownerId) >= perOwnerConcurrency) continue;
+        if (earliest === null || job.runAt < earliest) earliest = job.runAt;
+      }
+    }
+    var delay = maxTimerDelay;
+    if (earliest !== null) delay = Math.min(maxTimerDelay, Math.max(0, earliest - timestamp));
+    timer = setTimer(function () {
+      timer = null;
+      try { tick(); } catch (error) {}
+    }, delay);
+    if (timer && typeof timer.unref === "function") timer.unref();
+  }
+
+  function registerHandler(type, handler, options) {
+    ensureReady();
+    requiredString(type, "handler type");
+    if (typeof handler !== "function") throw new Error("handler must be a function");
+    if (options && options.canRun !== undefined && typeof options.canRun !== "function") throw new Error("canRun must be a function");
+    if (handlers[type]) throw new Error("handler already registered for " + type);
+    handlers[type] = handler;
+    if (options && options.canRun) eligibility[type] = options.canRun;
+    if (started) tick();
+    return function () {
+      if (handlers[type] !== handler) return;
+      delete handlers[type];
+      delete eligibility[type];
+      scheduleTimer();
+    };
+  }
+
+  function start() {
+    ensureReady();
+    if (started) return false;
+    started = true;
+    tick();
+    return true;
+  }
+
+  function shutdown() {
+    if (closed) return Promise.resolve();
+    closed = true;
+    started = false;
+    stopTimer();
+    var ids = Object.keys(active);
+    if (ids.length && !unhealthyError) {
+      var next = copy(data);
+      var stoppedAt = now();
+      for (var i = 0; i < next.jobs.length; i++) {
+        if (!active[next.jobs[i].id] || next.jobs[i].state !== "running") continue;
+        next.jobs[i].state = "interrupted";
+        next.jobs[i].updatedAt = stoppedAt;
+        next.jobs[i].execution.interruptedAt = stoppedAt;
+        next.jobs[i].execution.interruptionReason = "scheduler_shutdown";
+      }
+      try { store.save(next); data = next; } catch (error) { unhealthyError = error; }
+    }
+    store.close();
+    return Promise.resolve();
+  }
+
+  function getJob(id) { var job = findJob(id); return job ? copy(job) : null; }
+  function listJobs() { return copy(data.jobs); }
+  function getReceipt(id) { var job = findJob(id); return job && job.execution ? copy(job.execution.receipt) : null; }
+  function status() { return { started: started, closed: closed, healthy: !unhealthyError, error: unhealthyError ? unhealthyError.message : null, active: Object.keys(active).length }; }
+
+  try {
+    recover();
+  } catch (error) {
+    store.close();
+    throw error;
+  }
+  return {
+    start: start,
+    shutdown: shutdown,
+    registerHandler: registerHandler,
+    enqueue: enqueue,
+    cancel: cancel,
+    replaceQueued: replaceQueued,
+    tick: tick,
+    getJob: getJob,
+    listJobs: listJobs,
+    getReceipt: getReceipt,
+    status: status,
+  };
+}
+
+module.exports = { attachDurableScheduler: attachDurableScheduler };

package/lib/loop-cron.js

@@ -0,0 +1,47 @@
+var validateCron = require("./schedule-validation").validateCron;
+
+function parseField(field, min, max) {
+  var values = [];
+  var parts = field.split(",");
+  for (var i = 0; i < parts.length; i++) {
+    var part = parts[i].trim();
+    if (part.indexOf("/") !== -1) {
+      var slash = part.split("/");
+      var step = parseInt(slash[1], 10);
+      var range = slash[0] === "*" ? [min, max] : slash[0].split("-").map(function (value) { return parseInt(value, 10); });
+      if (range.length === 1) range.push(range[0]);
+      for (var stepped = range[0]; stepped <= range[1]; stepped += step) values.push(stepped);
+    } else if (part === "*") {
+      for (var any = min; any <= max; any++) values.push(any);
+    } else if (part.indexOf("-") !== -1) {
+      var bounds = part.split("-");
+      for (var ranged = parseInt(bounds[0], 10); ranged <= parseInt(bounds[1], 10); ranged++) values.push(ranged);
+    } else values.push(parseInt(part, 10));
+  }
+  return values;
+}
+
+function parse(expr) {
+  if (!validateCron(expr).ok) return null;
+  var fields = expr.trim().split(/\s+/);
+  return { minutes: parseField(fields[0], 0, 59), hours: parseField(fields[1], 0, 23), daysOfMonth: parseField(fields[2], 1, 31), months: parseField(fields[3], 1, 12), daysOfWeek: parseField(fields[4], 0, 6) };
+}
+
+function matches(parsed, date) {
+  return parsed.minutes.indexOf(date.getMinutes()) !== -1 && parsed.hours.indexOf(date.getHours()) !== -1 &&
+    parsed.daysOfMonth.indexOf(date.getDate()) !== -1 && parsed.months.indexOf(date.getMonth() + 1) !== -1 && parsed.daysOfWeek.indexOf(date.getDay()) !== -1;
+}
+
+function nextRunTime(expr, after) {
+  var parsed = parse(expr);
+  if (!parsed) return null;
+  var date = new Date(after || Date.now());
+  date.setSeconds(0, 0); date.setMinutes(date.getMinutes() + 1);
+  for (var i = 0; i < 366 * 24 * 60; i++) {
+    if (matches(parsed, date)) return date.getTime();
+    date.setMinutes(date.getMinutes() + 1);
+  }
+  return null;
+}
+
+module.exports = { nextRunTime: nextRunTime };

package/lib/loop-durable-schedule.js

@@ -0,0 +1,159 @@
+var crypto = require("crypto");
+
+function identity(prefix, projectId, scheduleIdentity, scheduleEpoch, occurrenceAt) {
+  var raw = projectId + "\n" + scheduleIdentity + "\n" + scheduleEpoch + "\n" + occurrenceAt;
+  return prefix + crypto.createHash("sha256").update(raw).digest("hex");
+}
+
+function attachLoopDurableSchedule(ctx) {
+  var scheduler = ctx.scheduler;
+  var registry = ctx.registry;
+  var type = "loop-occurrence:" + ctx.projectId;
+  var unregister = null;
+  var syncing = false;
+
+  function isMultiUser() { return typeof ctx.isMultiUser === "function" ? ctx.isMultiUser() : !!ctx.isMultiUser; }
+
+  function ownerFor(record) {
+    if (!isMultiUser()) return "local-user";
+    return typeof record.ownerId === "string" && record.ownerId ? record.ownerId : null;
+  }
+
+  function jobsFor(recordId) {
+    return scheduler.listJobs().filter(function (job) {
+      return job.type === type && job.projectId === ctx.projectId && job.target && job.target.id === recordId;
+    });
+  }
+
+  function queuedFor(recordId) {
+    var jobs = jobsFor(recordId);
+    for (var i = jobs.length - 1; i >= 0; i--) if (jobs[i].state === "queued") return jobs[i];
+    return null;
+  }
+
+  function spec(record, ownerId) {
+    var dueAt = record.nextRunAt;
+    var occurrenceKey = identity("occurrence:", ctx.projectId, record.scheduleIdentity, record.scheduleEpoch, dueAt);
+    return {
+      idempotencyKey: "loop-" + occurrenceKey,
+      type: type,
+      ownerId: ownerId,
+      projectId: ctx.projectId,
+      target: { kind: "loop-record", id: record.id },
+      payload: { recordId: record.id, occurrenceAt: dueAt, occurrenceKey: occurrenceKey, scheduleIdentity: record.scheduleIdentity, scheduleEpoch: record.scheduleEpoch, recordRevision: Number(record.updatedAt || 0) },
+      runAt: dueAt,
+    };
+  }
+
+  function matchesOccurrence(job, record) {
+    return job && job.payload && job.payload.scheduleIdentity === record.scheduleIdentity &&
+      Number(job.payload.scheduleEpoch) === Number(record.scheduleEpoch) && job.payload.occurrenceAt === record.nextRunAt;
+  }
+
+  function cancelQueued(recordId, reason) {
+    var jobs = jobsFor(recordId);
+    for (var i = 0; i < jobs.length; i++) {
+      if (jobs[i].state === "queued") scheduler.cancel(jobs[i].id, reason);
+    }
+  }
+
+  function syncRecord(record) {
+    var related = jobsFor(record.id);
+    var persistedDueOwned = related.some(function (job) {
+      return ["queued", "claimed", "running"].indexOf(job.state) !== -1 && matchesOccurrence(job, record);
+    });
+    var terminal = null;
+    for (var ti = related.length - 1; ti >= 0; ti--) {
+      if (["completed", "failed", "interrupted"].indexOf(related[ti].state) !== -1 && matchesOccurrence(related[ti], record)) { terminal = related[ti]; break; }
+    }
+    if (terminal && record.enabled && Number.isFinite(record.nextRunAt)) {
+      if (!registry.reconcileDurableOccurrence(record.id, record.nextRunAt)) throw new Error("The interrupted occurrence could not be reconciled.");
+      record = registry.getById(record.id); related = jobsFor(record.id); persistedDueOwned = false;
+    }
+    if (!persistedDueOwned) {
+      record = registry.normalizeDurableOccurrence(record.id, Date.now());
+      if (!record) throw new Error("The scheduled occurrence could not be normalized.");
+      related = jobsFor(record.id);
+    }
+    var queued = queuedFor(record.id);
+    var ownerId = ownerFor(record);
+    if (isMultiUser() && !ownerId) {
+      if (queued) scheduler.cancel(queued.id, "record_requires_owner");
+      registry.markNeedsOwner(record.id);
+      return;
+    }
+    if (!record.enabled || !Number.isFinite(record.nextRunAt)) {
+      if (queued) scheduler.cancel(queued.id, "record_disabled_or_unscheduled");
+      return;
+    }
+    var wanted = spec(record, ownerId);
+    if (queued) {
+      if (matchesOccurrence(queued, record)) {
+        scheduler.replaceQueued(queued.id, wanted);
+        return;
+      }
+      scheduler.cancel(queued.id, "record_schedule_changed");
+    }
+    for (var i = related.length - 1; i >= 0; i--) {
+      if ((related[i].state === "claimed" || related[i].state === "running") && matchesOccurrence(related[i], record)) return;
+      if (related[i].state === "cancelled" && matchesOccurrence(related[i], record)) return;
+    }
+    scheduler.enqueue(wanted);
+  }
+
+  function sync() {
+    if (syncing) return;
+    syncing = true;
+    try {
+      var records = registry.getAll();
+      var present = Object.create(null);
+      for (var i = 0; i < records.length; i++) {
+        present[records[i].id] = true;
+        syncRecord(records[i]);
+      }
+      var jobs = scheduler.listJobs();
+      for (var ji = 0; ji < jobs.length; ji++) {
+        if (jobs[ji].type === type && jobs[ji].state === "queued" && !present[jobs[ji].target.id]) {
+          scheduler.cancel(jobs[ji].id, "record_deleted");
+        }
+      }
+    } finally { syncing = false; }
+  }
+
+  function canRun(job) {
+    var record = registry.getById(job.target.id);
+    if (!record || !record.enabled || !matchesOccurrence(job, record)) return true;
+    if (ownerFor(record) !== job.ownerId) return true;
+    if (ctx.authorize && !ctx.authorize(record, job.ownerId)) return false;
+    return !ctx.canRun || ctx.canRun(record);
+  }
+
+  function dispatch(job, execution) {
+    var record = registry.getById(job.target.id);
+    if (!record) throw new Error("The scheduled record was deleted.");
+    if (!record.enabled || !matchesOccurrence(job, record)) throw new Error("The scheduled occurrence is stale.");
+    if (ownerFor(record) !== job.ownerId) throw new Error("The scheduled record owner changed.");
+    if (ctx.authorize && !ctx.authorize(record, job.ownerId)) throw new Error("The scheduled record owner is no longer authorized.");
+    execution.recordMetadata({ projectId: ctx.projectId, recordId: record.id, occurrenceAt: job.payload.occurrenceAt, recordRevision: Number(record.updatedAt || 0) });
+    var prepared = registry.prepareDurableOccurrence(record.id, job.payload.occurrenceAt);
+    if (!prepared || prepared.ok === false) throw new Error(prepared && prepared.error || "The scheduled occurrence could not be reserved.");
+    execution.recordReceipt({ state: "dispatching", projectId: ctx.projectId, recordId: record.id, occurrenceAt: job.payload.occurrenceAt, recordedAt: Date.now() });
+    var triggerError = null;
+    try { registry.triggerDurableOccurrence(record.id, prepared.value); }
+    catch (error) { triggerError = error; }
+    if (!registry.completeDurableOccurrence(record.id, job.payload.occurrenceAt)) throw new Error("The next scheduled occurrence could not be stored after dispatch.");
+    if (triggerError) throw triggerError;
+    return { dispatched: true, recordId: record.id, occurrenceAt: job.payload.occurrenceAt };
+  }
+
+  unregister = scheduler.registerHandler(type, dispatch, { canRun: canRun });
+  sync();
+  return {
+    sync: sync,
+    wake: function () { try { scheduler.tick(); } catch (error) {} },
+    shutdown: function () { if (unregister) { unregister(); unregister = null; } },
+    type: type,
+  };
+}
+
+module.exports = { attachLoopDurableSchedule: attachLoopDurableSchedule };