@forgezero/runtime 0.1.0

package/dist/backup.js

@@ -0,0 +1,302 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/backup.ts
+import { hkdf, seal, open, sha256, timingSafeEqual } from "@forgezero/access/security";
+
+class BackupError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BackupError";
+  }
+}
+var SNAPSHOT_FORMAT = 1;
+var keyFor = (masterSeed, realm, snapshotId) => hkdf(masterSeed, `forgezero:backup:v1:${realm}:${snapshotId}`, 32);
+var aadFor = (realm, snapshotId, index) => `backup:${realm}:${snapshotId}:${index}`;
+var objectKey = (prefix, realm, id, part) => `${prefix}${realm}/${id}/${part}`;
+async function snapshot(options) {
+  const now = options.now ?? Date.now;
+  const chunkRows = options.chunkRows ?? 1000;
+  const prefix = options.prefix ?? "snapshots/";
+  const id = options.id ?? `snap_${new Date(now()).toISOString().replace(/[-:.]/g, "").slice(0, 15)}`;
+  const key = await keyFor(options.masterSeed, options.realm, id);
+  const chunks = [];
+  const collections = {};
+  let totalRows = 0;
+  const flush = async (collection, batch) => {
+    if (batch.length === 0)
+      return;
+    const plaintext = JSON.stringify({ collection, rows: batch });
+    const index = chunks.length;
+    const sealed = await seal(key, plaintext, aadFor(options.realm, id, index));
+    const object = objectKey(prefix, options.realm, id, `chunk-${String(index).padStart(5, "0")}.json`);
+    const body = JSON.stringify(sealed);
+    await options.store.putObject({ key: object, body, contentType: "application/json" });
+    chunks.push({
+      index,
+      object,
+      digest: await sha256(plaintext),
+      rows: batch.length,
+      bytes: body.length
+    });
+  };
+  for (const collection of await options.source.collections()) {
+    let batch = [];
+    let count = 0;
+    for await (const row of options.source.rows(collection)) {
+      batch.push(row);
+      count += 1;
+      if (batch.length >= chunkRows) {
+        await flush(collection, batch);
+        batch = [];
+      }
+    }
+    await flush(collection, batch);
+    collections[collection] = count;
+    totalRows += count;
+    options.onProgress?.({ collection, rows: count, chunks: chunks.length });
+  }
+  if (totalRows === 0) {
+    throw new BackupError("EMPTY_SNAPSHOT", "The source produced no rows. Refusing to write an empty snapshot.");
+  }
+  const manifest = {
+    format: SNAPSHOT_FORMAT,
+    id,
+    realm: options.realm,
+    createdAtMs: now(),
+    collections,
+    chunks,
+    totalRows,
+    sealDigest: await sha256(chunks.map((chunk) => chunk.digest).join("")),
+    ...options.labels ? { labels: options.labels } : {}
+  };
+  await options.store.putObject({
+    key: objectKey(prefix, options.realm, id, "manifest.json"),
+    body: JSON.stringify(manifest, null, 2),
+    contentType: "application/json"
+  });
+  return manifest;
+}
+async function verifySnapshot(args) {
+  const problems = [];
+  const key = await keyFor(args.masterSeed, args.manifest.realm, args.manifest.id);
+  let rowsChecked = 0;
+  if (args.manifest.format > SNAPSHOT_FORMAT) {
+    return {
+      ok: false,
+      id: args.manifest.id,
+      chunksChecked: 0,
+      rowsChecked: 0,
+      problems: [
+        {
+          chunk: -1,
+          code: "UNSUPPORTED_FORMAT",
+          message: `Snapshot format ${args.manifest.format} is newer than this reader (${SNAPSHOT_FORMAT}).`
+        }
+      ]
+    };
+  }
+  for (const chunk of args.manifest.chunks) {
+    let raw;
+    try {
+      raw = await args.store.getObject(chunk.object);
+    } catch (cause) {
+      problems.push({
+        chunk: chunk.index,
+        code: "CHUNK_MISSING",
+        message: `${chunk.object}: ${cause instanceof Error ? cause.message : "unreadable"}`
+      });
+      continue;
+    }
+    let plaintext;
+    try {
+      const sealed = JSON.parse(new TextDecoder().decode(raw));
+      plaintext = await open(key, sealed, aadFor(args.manifest.realm, args.manifest.id, chunk.index));
+    } catch {
+      problems.push({
+        chunk: chunk.index,
+        code: "DECRYPT_FAILED",
+        message: `${chunk.object} did not authenticate. Wrong realm seed, or the chunk was altered or swapped.`
+      });
+      continue;
+    }
+    if (!timingSafeEqual(await sha256(plaintext), chunk.digest)) {
+      problems.push({
+        chunk: chunk.index,
+        code: "DIGEST_MISMATCH",
+        message: `${chunk.object} decrypts but does not match its manifest digest.`
+      });
+      continue;
+    }
+    rowsChecked += JSON.parse(plaintext).rows.length;
+  }
+  const sealDigest = await sha256(args.manifest.chunks.map((chunk) => chunk.digest).join(""));
+  if (!timingSafeEqual(sealDigest, args.manifest.sealDigest)) {
+    problems.push({
+      chunk: -1,
+      code: "BAD_MANIFEST",
+      message: "The manifest does not match its own seal — a chunk was added to or removed from the list."
+    });
+  }
+  return {
+    ok: problems.length === 0,
+    id: args.manifest.id,
+    chunksChecked: args.manifest.chunks.length,
+    rowsChecked,
+    problems
+  };
+}
+async function restore(options) {
+  const { manifest } = options;
+  if (manifest.realm !== options.realm) {
+    throw new BackupError("REALM_MISMATCH", `This snapshot belongs to realm "${manifest.realm}" and cannot be restored into "${options.realm}".`);
+  }
+  if (manifest.format > SNAPSHOT_FORMAT) {
+    throw new BackupError("UNSUPPORTED_FORMAT", `Snapshot format ${manifest.format} is newer than this reader (${SNAPSHOT_FORMAT}). Restoring it would silently drop whatever the newer format added.`);
+  }
+  if (!options.skipVerify) {
+    const report = await verifySnapshot({
+      store: options.store,
+      manifest,
+      masterSeed: options.masterSeed
+    });
+    if (!report.ok) {
+      const [first] = report.problems;
+      throw new BackupError(first.code, `Refusing to restore: ${report.problems.length} problem(s), first at chunk ${first.chunk} — ${first.message}`);
+    }
+  }
+  await options.sink.begin?.(manifest);
+  const key = await keyFor(options.masterSeed, manifest.realm, manifest.id);
+  const collections = {};
+  let rowsRestored = 0;
+  for (const chunk of manifest.chunks) {
+    const raw = await options.store.getObject(chunk.object);
+    const sealed = JSON.parse(new TextDecoder().decode(raw));
+    const plaintext = await open(key, sealed, aadFor(manifest.realm, manifest.id, chunk.index));
+    const { collection, rows } = JSON.parse(plaintext);
+    await options.sink.write(collection, rows);
+    collections[collection] = (collections[collection] ?? 0) + rows.length;
+    rowsRestored += rows.length;
+    options.onProgress?.({ chunk: chunk.index + 1, of: manifest.chunks.length, rows: rowsRestored });
+  }
+  await options.sink.finish?.(manifest);
+  return { id: manifest.id, rowsRestored, collections };
+}
+async function listSnapshots(args) {
+  const prefix = args.prefix ?? "snapshots/";
+  const objects = await args.store.listObjects(`${prefix}${args.realm}/`, 1e4);
+  const manifests = [];
+  for (const object of objects) {
+    if (!object.key.endsWith("/manifest.json"))
+      continue;
+    try {
+      manifests.push(JSON.parse(new TextDecoder().decode(await args.store.getObject(object.key))));
+    } catch {}
+  }
+  return manifests.sort((a, b) => b.createdAtMs - a.createdAtMs);
+}
+var DEFAULT_RETENTION = {
+  keepLast: 7,
+  keepDaily: 7,
+  keepWeekly: 4,
+  keepMonthly: 6
+};
+var periodOf = (atMs, unit) => {
+  const date = new Date(atMs);
+  if (unit === "month")
+    return `${date.getUTCFullYear()}-${date.getUTCMonth()}`;
+  if (unit === "day")
+    return date.toISOString().slice(0, 10);
+  return String(Math.floor(atMs / (7 * 86400000)));
+};
+function selectForDeletion(manifests, policy = DEFAULT_RETENTION) {
+  if (manifests.length === 0)
+    return [];
+  const newestFirst = [...manifests].sort((a, b) => b.createdAtMs - a.createdAtMs);
+  const keep = new Set;
+  for (const manifest of newestFirst.slice(0, Math.max(1, policy.keepLast)))
+    keep.add(manifest.id);
+  for (const [unit, limit] of [
+    ["day", policy.keepDaily],
+    ["week", policy.keepWeekly],
+    ["month", policy.keepMonthly]
+  ]) {
+    if (!limit)
+      continue;
+    const seen = new Set;
+    for (const manifest of newestFirst) {
+      const period = periodOf(manifest.createdAtMs, unit);
+      if (seen.has(period))
+        continue;
+      seen.add(period);
+      keep.add(manifest.id);
+      if (seen.size >= limit)
+        break;
+    }
+  }
+  keep.add(newestFirst[0].id);
+  return newestFirst.filter((manifest) => !keep.has(manifest.id));
+}
+async function prune(args) {
+  const manifests = await listSnapshots({ store: args.store, realm: args.realm, prefix: args.prefix });
+  const doomed = selectForDeletion(manifests, args.policy);
+  if (doomed.length >= manifests.length) {
+    throw new BackupError("RETENTION_WOULD_EMPTY", "This policy would delete every snapshot. Refusing.");
+  }
+  if (!args.dryRun) {
+    for (const manifest of doomed) {
+      for (const chunk of manifest.chunks)
+        await args.store.deleteObject(chunk.object);
+      await args.store.deleteObject(`${args.prefix ?? "snapshots/"}${args.realm}/${manifest.id}/manifest.json`);
+    }
+  }
+  return { deleted: doomed.map((manifest) => manifest.id), kept: manifests.length - doomed.length };
+}
+function backupJob(options) {
+  return {
+    key: options.key ?? "backup.snapshot",
+    everyMs: options.everyMs ?? 86400000,
+    run: async () => {
+      const manifest = await snapshot(options);
+      const report = await verifySnapshot({
+        store: options.store,
+        manifest,
+        masterSeed: options.masterSeed
+      });
+      if (!report.ok) {
+        return { ok: false, detail: { id: manifest.id, problems: report.problems.length } };
+      }
+      const pruned = await prune({
+        store: options.store,
+        realm: options.realm,
+        policy: options.policy,
+        prefix: options.prefix
+      });
+      return {
+        ok: true,
+        detail: { id: manifest.id, rows: manifest.totalRows, pruned: pruned.deleted.length }
+      };
+    }
+  };
+}
+var VERSION = "0.1.0";
+export {
+  verifySnapshot,
+  snapshot,
+  selectForDeletion,
+  restore,
+  prune,
+  listSnapshots,
+  backupJob,
+  VERSION,
+  SNAPSHOT_FORMAT,
+  DEFAULT_RETENTION,
+  BackupError
+};

package/dist/calendar.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Billing periods, working days and exclusions.
+ *
+ * Pure arithmetic over dates, no I/O. That is exactly the kind of code that
+ * gets written inline in three places and disagrees about whether a period is
+ * inclusive at both ends — and a billing period that is off by one day either
+ * charges twice for a day or never charges for it, both of which surface as a
+ * customer complaint rather than as an exception.
+ *
+ * ## Periods are computed from an anchor, never from "now"
+ *
+ * `now minus seven days` gives a different answer every time it runs. A billing
+ * job that retries after a failure would then invoice a shifted window, so the
+ * same day is billed twice or skipped entirely. Every period here derives from
+ * a fixed anchor and an index, so period 34 is the same seven days whoever asks
+ * and whenever they ask.
+ *
+ * That property is what makes the invoice idempotency key meaningful: the key
+ * is the period index, and a retry recomputes the same one.
+ *
+ * ## UTC throughout
+ *
+ * No local time, no daylight saving. A billing period that shifts by an hour
+ * twice a year eventually straddles a boundary and either double-counts or
+ * loses an hour of usage. If a business wants periods to start at 09:00 in
+ * their own zone, that is an offset applied at presentation — not a different
+ * clock underneath.
+ */
+export declare const DAY_MS = 86400000;
+export declare class CalendarError extends Error {
+    readonly code: 'BAD_ANCHOR' | 'BAD_LENGTH' | 'NO_WORKING_DAY' | 'BAD_DATE';
+    constructor(code: 'BAD_ANCHOR' | 'BAD_LENGTH' | 'NO_WORKING_DAY' | 'BAD_DATE', message: string);
+}
+/** `2026-08-01`. The only date format this module accepts or returns. */
+export type IsoDate = string;
+export declare function toDay(date: IsoDate): number;
+export declare const fromDay: (day: number) => IsoDate;
+export declare const dayOfWeek: (date: IsoDate) => number;
+/**
+ * Which days count.
+ *
+ * `workingDays` is the positive statement — the days a business operates —
+ * rather than a list of weekend days. Stating it positively is what makes a
+ * Sunday-to-Thursday week expressible without special-casing; a `weekend` field
+ * quietly assumes Saturday and Sunday and is wrong in a good part of the world.
+ */
+export interface Calendar {
+    key: string;
+    label: string;
+    /** 0 = Sunday. Defaults to Monday–Friday. */
+    workingDays?: readonly number[];
+    /** Specific dates that are not working days, whatever the weekday says. */
+    holidays?: readonly IsoDate[];
+    /**
+     * Dates that ARE working days even though the rules above say otherwise.
+     *
+     * For the Saturday a business opens to clear a backlog. Exceptions win over
+     * holidays, because a list of exceptions with no way to override is a list
+     * somebody works around by deleting the holiday — and then it is gone for
+     * every year after.
+     */
+    exceptions?: readonly IsoDate[];
+}
+export declare const DEFAULT_WORKING_DAYS: readonly [1, 2, 3, 4, 5];
+export declare function isWorkingDay(date: IsoDate, calendar: Calendar): boolean;
+/**
+ * The next working day on or after a date.
+ *
+ * Bounded, because a calendar with no working days at all — an empty
+ * `workingDays`, or a typo — would otherwise loop forever inside a billing job
+ * and present as a hung process rather than as a configuration error.
+ */
+export declare function nextWorkingDay(date: IsoDate, calendar: Calendar, forward?: boolean): IsoDate;
+export declare function workingDaysBetween(from: IsoDate, to: IsoDate, calendar: Calendar): number;
+/**
+ * How often a bill is raised.
+ *
+ * `anchor` is the first day of period 0 and never moves. `lengthDays` is the
+ * whole configuration — 7, 30, or anything else — because "monthly" is not a
+ * fixed number of days and a system that pretends otherwise drifts by five days
+ * a year.
+ */
+export interface BillingSchedule {
+    anchor: IsoDate;
+    lengthDays: number;
+    /** Calendar used to move a due date off a non-working day. */
+    calendar?: Calendar;
+    /**
+     * Days after a period ends before payment is due.
+     *
+     * Counted in WORKING days when a calendar is given. A seven-day term that
+     * lands on a public holiday is a term nobody could have met, and suspending
+     * an account for it is a support ticket with a refund at the end.
+     */
+    dueAfterDays?: number;
+}
+export interface Period {
+    /** Stable, and the natural idempotency key for the invoice that covers it. */
+    index: number;
+    /** Inclusive. */
+    start: IsoDate;
+    /** Inclusive — the last day covered, NOT the next period's first day. */
+    end: IsoDate;
+    /** Exclusive, for a half-open range query. */
+    endExclusive: IsoDate;
+    dueOn: IsoDate;
+}
+/**
+ * Which period a date falls in.
+ *
+ * Floor division, so a date before the anchor gives a negative index rather
+ * than zero. Clamping to zero would silently place a backdated record in the
+ * first period and bill somebody for a week they had not signed up for.
+ */
+export declare function periodIndexOn(date: IsoDate, schedule: BillingSchedule): number;
+export declare function periodAt(index: number, schedule: BillingSchedule): Period;
+export declare const periodOn: (date: IsoDate, schedule: BillingSchedule) => Period;
+/**
+ * Every period that has fully ended by `asOf` and is therefore billable.
+ *
+ * The current period is deliberately excluded: invoicing a period that is still
+ * accruing produces a figure that changes after it was sent.
+ *
+ * `since` makes a catch-up run possible — a billing job that was down for three
+ * weeks must raise three invoices, not one covering three weeks. A run that
+ * silently collapses missed periods is a run that undercharges and leaves no
+ * trace of having done so.
+ */
+export declare function closedPeriods(schedule: BillingSchedule, args: {
+    asOf: IsoDate;
+    since?: number;
+    limit?: number;
+}): Period[];
+/** Whether a due date has passed — the trigger for suspending an account. */
+export declare const isOverdue: (period: Period, asOf: IsoDate) => boolean;
+export declare const daysOverdue: (period: Period, asOf: IsoDate) => number;

package/dist/calendar.js

@@ -0,0 +1,129 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/calendar.ts
+var DAY_MS = 86400000;
+
+class CalendarError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CalendarError";
+  }
+}
+var ISO = /^\d{4}-\d{2}-\d{2}$/;
+function toDay(date) {
+  if (!ISO.test(date)) {
+    throw new CalendarError("BAD_DATE", `"${date}" is not an ISO date (YYYY-MM-DD).`);
+  }
+  const ms = Date.parse(`${date}T00:00:00.000Z`);
+  if (Number.isNaN(ms))
+    throw new CalendarError("BAD_DATE", `"${date}" is not a real date.`);
+  return Math.floor(ms / DAY_MS);
+}
+var fromDay = (day) => new Date(day * DAY_MS).toISOString().slice(0, 10);
+var dayOfWeek = (date) => new Date(`${date}T00:00:00.000Z`).getUTCDay();
+var DEFAULT_WORKING_DAYS = [1, 2, 3, 4, 5];
+function isWorkingDay(date, calendar) {
+  if (calendar.exceptions?.includes(date))
+    return true;
+  if (calendar.holidays?.includes(date))
+    return false;
+  return (calendar.workingDays ?? DEFAULT_WORKING_DAYS).includes(dayOfWeek(date));
+}
+function nextWorkingDay(date, calendar, forward = true) {
+  const step = forward ? 1 : -1;
+  let day = toDay(date);
+  for (let tried = 0;tried <= 366; tried += 1) {
+    const candidate = fromDay(day);
+    if (isWorkingDay(candidate, calendar))
+      return candidate;
+    day += step;
+  }
+  throw new CalendarError("NO_WORKING_DAY", `"${calendar.key}" has no working day within a year of ${date}. Check workingDays and holidays.`);
+}
+function workingDaysBetween(from, to, calendar) {
+  const start = toDay(from);
+  const end = toDay(to);
+  if (end < start)
+    return 0;
+  let count = 0;
+  for (let day = start;day <= end; day += 1) {
+    if (isWorkingDay(fromDay(day), calendar))
+      count += 1;
+  }
+  return count;
+}
+function assertSchedule(schedule) {
+  if (!ISO.test(schedule.anchor)) {
+    throw new CalendarError("BAD_ANCHOR", `Anchor "${schedule.anchor}" is not an ISO date.`);
+  }
+  if (!Number.isInteger(schedule.lengthDays) || schedule.lengthDays < 1) {
+    throw new CalendarError("BAD_LENGTH", "A billing period must be a whole number of days, at least one.");
+  }
+}
+function periodIndexOn(date, schedule) {
+  assertSchedule(schedule);
+  return Math.floor((toDay(date) - toDay(schedule.anchor)) / schedule.lengthDays);
+}
+function periodAt(index, schedule) {
+  assertSchedule(schedule);
+  const startDay = toDay(schedule.anchor) + index * schedule.lengthDays;
+  const start = fromDay(startDay);
+  const end = fromDay(startDay + schedule.lengthDays - 1);
+  const endExclusive = fromDay(startDay + schedule.lengthDays);
+  let dueOn = fromDay(startDay + schedule.lengthDays + (schedule.dueAfterDays ?? 0));
+  if (schedule.calendar && schedule.dueAfterDays) {
+    let day = toDay(endExclusive);
+    let remaining = schedule.dueAfterDays;
+    while (remaining > 0) {
+      day += 1;
+      if (isWorkingDay(fromDay(day), schedule.calendar))
+        remaining -= 1;
+    }
+    dueOn = fromDay(day);
+  } else if (schedule.calendar) {
+    dueOn = nextWorkingDay(dueOn, schedule.calendar);
+  }
+  return { index, start, end, endExclusive, dueOn };
+}
+var periodOn = (date, schedule) => periodAt(periodIndexOn(date, schedule), schedule);
+function closedPeriods(schedule, args) {
+  assertSchedule(schedule);
+  const current = periodIndexOn(args.asOf, schedule);
+  const from = args.since ?? current - 1;
+  const periods = [];
+  for (let index = from;index < current; index += 1) {
+    if (periods.length >= (args.limit ?? 52))
+      break;
+    if (index < 0)
+      continue;
+    periods.push(periodAt(index, schedule));
+  }
+  return periods;
+}
+var isOverdue = (period, asOf) => toDay(asOf) > toDay(period.dueOn);
+var daysOverdue = (period, asOf) => Math.max(0, toDay(asOf) - toDay(period.dueOn));
+export {
+  workingDaysBetween,
+  toDay,
+  periodOn,
+  periodIndexOn,
+  periodAt,
+  nextWorkingDay,
+  isWorkingDay,
+  isOverdue,
+  fromDay,
+  daysOverdue,
+  dayOfWeek,
+  closedPeriods,
+  DEFAULT_WORKING_DAYS,
+  DAY_MS,
+  CalendarError
+};