cursedbelt-server 1.0.0

package/dist/server/resume/store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Where "the last place you were" is kept — one small table, in the app's own
+ * database, keyed by the app's own user id.
+ *
+ * ── Why server-side at all ──────────────────────────────────────────────────
+ * `localStorage` would be one line and would answer the wrong question. The
+ * owner's report is about coming BACK to an app, and he does that from another
+ * device — the 2026-08-13 music sign-in from a second laptop is the same shape.
+ * A place remembered only in the browser that saw it is not remembered.
+ *
+ * ── Why the app's database and not a fleet service ──────────────────────────
+ * Same reasoning as `../notifications/migrations.ts`: the SCHEMA is shared, the
+ * DATA is local. A resume row is one string per user per app; a central service
+ * would put a network hop in front of the first paint of every app in the fleet,
+ * and the first thing each would do is cache it.
+ *
+ * The DDL is idempotent, so calling this twice — or beside a migration runner —
+ * converges on one table.
+ */
+import type { Database } from 'bun:sqlite';
+/** Longer than any real place, short enough that nobody can park a payload here. */
+export declare const MAX_LOCATION_LENGTH = 2048;
+export interface ResumeRecord {
+    location: string;
+    updatedAt: number;
+}
+export interface ResumeStore {
+    read(userId: string, key?: string): ResumeRecord | null;
+    write(userId: string, location: string, key?: string): void;
+    /** No key clears every remembered place for that user. */
+    clear(userId: string, key?: string): void;
+}
+export interface ResumeStoreOptions {
+    table?: string;
+    now?: () => number;
+}
+export declare function createSqliteResumeStore(db: Database, options?: ResumeStoreOptions): ResumeStore;

package/dist/server/resume/store.js

@@ -0,0 +1,38 @@
+/** Longer than any real place, short enough that nobody can park a payload here. */
+export const MAX_LOCATION_LENGTH = 2048;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFAULT_KEY = 'default';
+export function createSqliteResumeStore(db, options = {}) {
+    const table = options.table ?? 'cb_resume';
+    if (!IDENTIFIER.test(table))
+        throw new Error(`invalid resume table name: ${table}`);
+    const now = options.now ?? Date.now;
+    db.run(`CREATE TABLE IF NOT EXISTS ${table} (
+    user_id TEXT NOT NULL,
+    place_key TEXT NOT NULL,
+    location TEXT NOT NULL,
+    updated_at INTEGER NOT NULL,
+    PRIMARY KEY (user_id, place_key)
+  )`);
+    return {
+        read(userId, key = DEFAULT_KEY) {
+            const row = db
+                .query(`SELECT location, updated_at FROM ${table} WHERE user_id = ? AND place_key = ?`)
+                .get(userId, key);
+            return row ? { location: row.location, updatedAt: row.updated_at } : null;
+        },
+        write(userId, location, key = DEFAULT_KEY) {
+            // Truncated rather than refused: a place that is somehow too long should
+            // cost the reader nothing, and the next navigation overwrites it anyway.
+            const value = location.slice(0, MAX_LOCATION_LENGTH);
+            db.run(`INSERT INTO ${table} (user_id, place_key, location, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(user_id, place_key) DO UPDATE SET location = excluded.location, updated_at = excluded.updated_at`, [userId, key, value, now()]);
+        },
+        clear(userId, key) {
+            if (key === undefined)
+                db.run(`DELETE FROM ${table} WHERE user_id = ?`, [userId]);
+            else
+                db.run(`DELETE FROM ${table} WHERE user_id = ? AND place_key = ?`, [userId, key]);
+        },
+    };
+}

package/dist/server/retention/archive.d.ts

@@ -0,0 +1,78 @@
+/** One sealed archive file. */
+export interface ArchiveSegment {
+    /** Absolute path on this machine. */
+    path: string;
+    /** Basename — what a collector and the index line name it by. */
+    file: string;
+    rows: number;
+    bytes: number;
+    sha256: string;
+    at: number;
+}
+export interface ArchiveSink {
+    /** Where segments are written. */
+    readonly dir: string;
+    /** True when THIS machine is the archive's final home (no collector is owed). */
+    readonly terminal: boolean;
+    /**
+     * Bytes of sealed segments still waiting for a collector. Always 0 when
+     * `terminal` — a home archive is never "pending", it is the archive.
+     */
+    pendingBytes(): number;
+    /**
+     * Seal one segment, proven on disk. THROWS if it cannot prove it: the caller
+     * treats that as "these rows stay in the table".
+     */
+    write(records: ReadonlyArray<Record<string, unknown>>, at: number): ArchiveSegment;
+}
+/** The default budget of uncollected archive on a staged (deployed-box) home.
+ *  Generous next to the tables it governs — notes' whole `ops` log is ~15 MB —
+ *  and small next to a 6.7 GB root. Reached only if the collector has stopped. */
+export declare const DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES: number;
+/** `20260825-114233` — sortable, second-resolution, and the same shape the
+ *  fleet's dated backup dirs already use, so one eye reads both. */
+export declare function archiveStamp(date: Date): string;
+export interface ArchiveHome {
+    dir: string;
+    terminal: boolean;
+}
+/**
+ * Where this app's archive lives on THIS machine, and whether the machine keeps
+ * it.
+ *
+ * `<app-data-home>/cursed-satellites/archive/<app>/`, reached through the same env
+ * ladder the retention home uses, so a test, a container and a deployed box each
+ * land somewhere writable rather than somewhere assumed.
+ */
+export declare function resolveArchiveHome(app: string, env?: Record<string, string | undefined>): ArchiveHome;
+export interface JsonlArchiveOptions {
+    app: string;
+    /** Stable, app-scoped resource id — the segment name's prefix. */
+    resource: string;
+    /** Overrides the resolved home. Tests and callers that already resolved it. */
+    home?: ArchiveHome;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * The fleet's archive sink: newline-delimited JSON segments plus an append-only
+ * `index.jsonl` naming every segment ever sealed here.
+ *
+ * The index is what makes the archive answerable without reading gigabytes —
+ * "what is in here, how many rows, and does it still hash the same" — and it is
+ * appended rather than rewritten so a crash mid-write can cost at most the last
+ * line, never the catalogue.
+ */
+export declare function createJsonlArchive(options: JsonlArchiveOptions): ArchiveSink;
+/**
+ * Re-verify every segment in an archive directory against the sha256 the index
+ * recorded — the answer to "is this archive still real?" without a restore.
+ *
+ * Exists because an archive nobody can check is a belief, and this whole
+ * category is a promise that the rows still exist somewhere.
+ */
+export declare function verifyArchive(dir: string): {
+    segments: number;
+    rows: number;
+    bytes: number;
+    bad: string[];
+};

package/dist/server/retention/archive.js

@@ -0,0 +1,284 @@
+/**
+ * The ARCHIVE half of `archived-history` — where the rows go before they are
+ * allowed to leave the instance.
+ *
+ * ── The ordering rule IS the safety argument, and this fleet has broken it ───
+ * prod's `diskGuard.sh` rule 1 deletes the oldest `VACUUM INTO` sqlite backups
+ * to free space, and its own comment calls those files "NOT regenerable". A
+ * cleanup routine that runs before the copy is data loss wearing housekeeping's
+ * name, and it is the exact failure this module exists to make impossible. So:
+ *
+ *   1. serialize the rows,
+ *   2. write them to a NEW file, fsync it,
+ *   3. RE-READ that file off the disk and prove it — byte length, sha256, line
+ *      count, and that every line parses back to an object,
+ *   4. only then may the caller delete those rows.
+ *
+ * `write()` throws rather than returning a failure, because the one thing a
+ * caller must never be able to do is treat "the archive did not happen" as
+ * "nothing to delete". A throw ends the sweep for that resource with the rows
+ * still in the table, which is the correct outcome every time.
+ *
+ * ── A segment per sweep, never an appended file ─────────────────────────────
+ * "Append-only" is a property of the DIRECTORY here: each sweep seals its own
+ * `<resource>-<stamp>.jsonl` and nothing is ever rewritten. That is not a style
+ * choice. On a deployed box the archive is a WAY-STATION — the Mac's
+ * `backups:pull-prod` copies segments down and removes the box's copy — and a
+ * collector that scp'd a file the app was still appending to would take a
+ * prefix and then delete the rest. A sealed file cannot be half a file.
+ *
+ * ── Terminal vs staged, and the staleness refusal ───────────────────────────
+ * On a workstation the archive is home: `<app-data-home>/cursed-satellites/
+ * archive/<app>/`, it is `terminal`, and it simply grows. The home is
+ * CONFIGURATION ({@link resolveAppDataHome}) — `$APP_DATA_HOME`, else the OS's own
+ * convention — never a folder this library invented in somebody's home; that was
+ * the published defect fixed 2026-09-13. On a deployed box nothing outside the
+ * app's own data dir is writable, so it resolves to `$APP_DATA_DIR/archive` and
+ * is `staged` — something else has to come and get it. That distinction is what lets the
+ * sweeper honor "refuse to trim if the last successful pull is stale" using a
+ * fact the box can actually observe: how many bytes of sealed segments are still
+ * sitting there uncollected. If the collector stops, the archive fills to its
+ * budget and the trim STOPS — bounded archive, complete table — rather than the
+ * table trimming into an archive nobody is taking away.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome } from "../paths/appDataHome";
+/** The default budget of uncollected archive on a staged (deployed-box) home.
+ *  Generous next to the tables it governs — notes' whole `ops` log is ~15 MB —
+ *  and small next to a 6.7 GB root. Reached only if the collector has stopped. */
+export const DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES = 64 * 1024 * 1024;
+const SAFE_NAME = /^[a-z0-9][a-z0-9-]*$/;
+/** `20260825-114233` — sortable, second-resolution, and the same shape the
+ *  fleet's dated backup dirs already use, so one eye reads both. */
+export function archiveStamp(date) {
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return (`${date.getUTCFullYear()}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}-` +
+        `${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}`);
+}
+/** Can we create and write inside this directory? Probed, never assumed —
+ *  the same reasoning as `resolveRetentionHome`, and the same failure it
+ *  prevents: a writer that silently EROFS-es every time. */
+function isUsable(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, ".write-probe");
+        writeFileSync(probe, "");
+        rmSync(probe, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where this app's archive lives on THIS machine, and whether the machine keeps
+ * it.
+ *
+ * `<app-data-home>/cursed-satellites/archive/<app>/`, reached through the same env
+ * ladder the retention home uses, so a test, a container and a deployed box each
+ * land somewhere writable rather than somewhere assumed.
+ */
+export function resolveArchiveHome(app, env = process.env) {
+    if (!SAFE_NAME.test(app))
+        throw new Error(`archive: app key "${app}" must be lower-kebab`);
+    const candidates = [];
+    if (env.RETENTION_ARCHIVE_HOME) {
+        candidates.push({ dir: join(env.RETENTION_ARCHIVE_HOME, app), terminal: true });
+    }
+    // An explicitly CONFIGURED home is used whether or not it exists yet — the
+    // operator naming it is the statement that it is the right place.
+    const configured = env[APP_DATA_HOME_ENV]?.trim();
+    if (configured) {
+        candidates.push({
+            dir: join(configured, "cursed-satellites", "archive", app),
+            terminal: true,
+        });
+    }
+    const conventional = resolveAppDataHome({ env });
+    // The OS convention is only PREFERRED when it is already there: creating it on
+    // a deployed box would strand the archive where no collector looks.
+    if (!configured && existsSync(conventional)) {
+        candidates.push({
+            dir: join(conventional, "cursed-satellites", "archive", app),
+            terminal: true,
+        });
+    }
+    // A deployed box: only the app's own data dir is writable under
+    // `ProtectSystem=strict`, and something else has to come and collect it.
+    if (env.APP_DATA_DIR)
+        candidates.push({ dir: join(env.APP_DATA_DIR, "archive"), terminal: false });
+    for (const candidate of candidates) {
+        if (isUsable(candidate.dir))
+            return candidate;
+    }
+    // Nothing writable. Return the conventional path and let `write()` throw when
+    // it is actually used — which, by this module's contract, means nothing is
+    // deleted. Never a boot failure.
+    return { dir: join(conventional, "cursed-satellites", "archive", app), terminal: true };
+}
+/**
+ * The fleet's archive sink: newline-delimited JSON segments plus an append-only
+ * `index.jsonl` naming every segment ever sealed here.
+ *
+ * The index is what makes the archive answerable without reading gigabytes —
+ * "what is in here, how many rows, and does it still hash the same" — and it is
+ * appended rather than rewritten so a crash mid-write can cost at most the last
+ * line, never the catalogue.
+ */
+export function createJsonlArchive(options) {
+    const { app, resource } = options;
+    if (!SAFE_NAME.test(resource)) {
+        throw new Error(`archive: resource id "${resource}" must be lower-kebab`);
+    }
+    const home = options.home ?? resolveArchiveHome(app, options.env);
+    const dir = home.dir;
+    const terminal = home.terminal;
+    const indexPath = join(dir, "index.jsonl");
+    return {
+        dir,
+        terminal,
+        pendingBytes() {
+            if (terminal)
+                return 0;
+            let total = 0;
+            let names;
+            try {
+                names = readdirSync(dir);
+            }
+            catch {
+                return 0; // not created yet — nothing is owed
+            }
+            for (const name of names) {
+                if (!name.endsWith(".jsonl") || name === "index.jsonl")
+                    continue;
+                try {
+                    total += statSync(join(dir, name)).size;
+                }
+                catch {
+                    // vanished between readdir and stat — the collector took it
+                }
+            }
+            return total;
+        },
+        write(records, at) {
+            if (records.length === 0)
+                throw new Error("archive: refusing to seal an empty segment");
+            const body = `${records.map((row) => JSON.stringify(row)).join("\n")}\n`;
+            const bytes = Buffer.byteLength(body);
+            const sha256 = createHash("sha256").update(body).digest("hex");
+            const file = `${resource}-${archiveStamp(new Date(at))}.jsonl`;
+            const path = join(dir, file);
+            const tmp = `${path}.${process.pid}.tmp`;
+            mkdirSync(dir, { recursive: true });
+            // Write + fsync THE FILE. Without the fsync the bytes can be in the page
+            // cache while the rows are already gone from a database that fsyncs its
+            // own WAL — a power cut between the two loses exactly the rows this
+            // module exists to keep.
+            const fd = openSync(tmp, "w");
+            try {
+                writeSync(fd, body);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            // Prove it, off the disk, before anything is deleted. Re-reading is the
+            // only check that covers a short write, a full disk that reported
+            // success, and a filesystem that lied.
+            let readBack;
+            try {
+                readBack = readFileSync(tmp, "utf8");
+            }
+            catch (error) {
+                rmSync(tmp, { force: true });
+                throw new Error(`archive: could not read back ${tmp} — ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const verify = (ok, what) => {
+                if (ok)
+                    return;
+                rmSync(tmp, { force: true });
+                throw new Error(`archive: ${file} failed verification (${what}) — nothing was deleted`);
+            };
+            verify(Buffer.byteLength(readBack) === bytes, `expected ${bytes} bytes`);
+            verify(createHash("sha256").update(readBack).digest("hex") === sha256, "sha256 mismatch");
+            const lines = readBack.split("\n").filter((line) => line.length > 0);
+            verify(lines.length === records.length, `expected ${records.length} rows, read ${lines.length}`);
+            for (const line of lines) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    verify(false, "a row did not parse back");
+                    return undefined;
+                }
+                verify(typeof parsed === "object" && parsed !== null, "a row read back as a non-object");
+            }
+            // Sealed. `rename` inside one directory is atomic on every filesystem
+            // this fleet runs on, so a collector never sees a partial segment.
+            renameSync(tmp, path);
+            const segment = { path, file, rows: records.length, bytes, sha256, at };
+            try {
+                appendFileSync(indexPath, `${JSON.stringify({ app, resource, ...segment, path: undefined, file })}\n`);
+            }
+            catch {
+                // The catalogue is a convenience; the segment is the archive. A failed
+                // index append must never make a sealed segment look unsealed and send
+                // the same rows through again.
+            }
+            return segment;
+        },
+    };
+}
+/**
+ * Re-verify every segment in an archive directory against the sha256 the index
+ * recorded — the answer to "is this archive still real?" without a restore.
+ *
+ * Exists because an archive nobody can check is a belief, and this whole
+ * category is a promise that the rows still exist somewhere.
+ */
+export function verifyArchive(dir) {
+    const result = { segments: 0, rows: 0, bytes: 0, bad: [] };
+    let index;
+    try {
+        index = readFileSync(join(dir, "index.jsonl"), "utf8");
+    }
+    catch {
+        return result;
+    }
+    for (const line of index.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            result.bad.push(`unparseable index line: ${line.slice(0, 80)}`);
+            continue;
+        }
+        if (!entry.file || !entry.sha256)
+            continue;
+        result.segments++;
+        const path = join(dir, entry.file);
+        let body;
+        try {
+            body = readFileSync(path, "utf8");
+        }
+        catch {
+            // On a STAGED archive a collected segment is the healthy outcome, so
+            // absence is reported as a fact rather than as corruption.
+            result.bad.push(`${entry.file}: absent (collected, or lost)`);
+            continue;
+        }
+        if (createHash("sha256").update(body).digest("hex") !== entry.sha256) {
+            result.bad.push(`${entry.file}: sha256 mismatch`);
+            continue;
+        }
+        result.rows += entry.rows ?? 0;
+        result.bytes += entry.bytes ?? 0;
+    }
+    return result;
+}

package/dist/server/retention/fleet.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The read model behind the station's Retention view: every app's published
+ * resources joined to the owner's overrides, with the effective policy resolved
+ * by the SAME function the sweeps use.
+ *
+ * That last point is the whole reason this is a shared function rather than a
+ * few lines in the station's route handler. A UI that computes "effective days"
+ * its own way eventually disagrees with the sweeper, and the disagreement shows
+ * up as data that vanished earlier than the screen said it would — which is the
+ * one failure mode that would make the owner stop trusting the control.
+ */
+import type { EffectiveRetentionPolicy, RetentionOverride } from "./policy";
+import type { PublishedResource } from "./store";
+export interface RetentionFleetRow extends PublishedResource {
+    key: string;
+    app: string;
+    policy: EffectiveRetentionPolicy;
+    override?: RetentionOverride;
+    /** The category's description, denormalized so the UI needs no second lookup. */
+    category: {
+        label: string;
+        defaultDays: number;
+        summary: string;
+    };
+    /** Default days for this resource before any override — what "Reset" returns to. */
+    defaultDays: number;
+    /** The publishing app's last heartbeat, so the UI can label a stale row. */
+    publishedAt: number;
+    instance?: string;
+    sweepDisabled?: boolean;
+}
+export interface RetentionFleetView {
+    home: string;
+    updatedAt: number;
+    rows: RetentionFleetRow[];
+    totals: {
+        resources: number;
+        apps: number;
+        items: number;
+        bytes: number;
+    };
+    /** Overrides with no matching declaration — an app renamed or retired a resource. */
+    orphanedOverrides: Array<{
+        key: string;
+        override: RetentionOverride;
+    }>;
+}
+export declare function buildRetentionFleetView(options?: {
+    home?: string;
+}): RetentionFleetView;

package/dist/server/retention/fleet.js

@@ -0,0 +1,66 @@
+import { RETENTION_CATEGORIES, resolveRetentionPolicy } from "./policy";
+import { readRetentionOverrides, readRetentionRegistry, resolveRetentionHome } from "./store";
+export function buildRetentionFleetView(options = {}) {
+    const home = options.home ?? resolveRetentionHome();
+    const publications = readRetentionRegistry(home);
+    const overridesFile = readRetentionOverrides(home);
+    const rows = [];
+    const claimed = new Set();
+    for (const publication of publications) {
+        for (const resource of publication.resources) {
+            const declaration = resource.declaration;
+            if (!declaration || typeof declaration.app !== "string")
+                continue;
+            const key = `${declaration.app}:${declaration.id}`;
+            const override = overridesFile.overrides[key];
+            let policy;
+            try {
+                policy = resolveRetentionPolicy(declaration, override);
+            }
+            catch {
+                // A publication written by an older/newer app version than this reader
+                // understands is skipped rather than allowed to break the whole view.
+                continue;
+            }
+            claimed.add(key);
+            const category = RETENTION_CATEGORIES[declaration.category];
+            rows.push({
+                ...resource,
+                key,
+                app: declaration.app,
+                policy,
+                ...(override ? { override } : {}),
+                category,
+                defaultDays: declaration.defaultDays ?? category.defaultDays,
+                publishedAt: publication.publishedAt,
+                ...(publication.instance ? { instance: publication.instance } : {}),
+                ...(publication.sweepDisabled ? { sweepDisabled: true } : {}),
+            });
+        }
+    }
+    // Biggest first: the view exists to answer "what is filling my disk".
+    rows.sort((a, b) => {
+        const bytes = (b.measurement?.bytes ?? 0) - (a.measurement?.bytes ?? 0);
+        if (bytes !== 0)
+            return bytes;
+        const items = (b.measurement?.items ?? 0) - (a.measurement?.items ?? 0);
+        if (items !== 0)
+            return items;
+        return a.key.localeCompare(b.key);
+    });
+    const orphanedOverrides = Object.entries(overridesFile.overrides)
+        .filter(([key]) => !claimed.has(key))
+        .map(([key, override]) => ({ key, override }));
+    return {
+        home,
+        updatedAt: overridesFile.updatedAt,
+        rows,
+        totals: {
+            resources: rows.length,
+            apps: new Set(rows.map((r) => r.app)).size,
+            items: rows.reduce((sum, r) => sum + (r.measurement?.items ?? 0), 0),
+            bytes: rows.reduce((sum, r) => sum + (r.measurement?.bytes ?? 0), 0),
+        },
+        orphanedOverrides,
+    };
+}

package/dist/server/retention/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `cursedbelt-server/retention` — THE fleet's one retention standard.
+ *
+ * ── Why this lives in cursedbelt ────────────────────────────────────────────
+ * Retention used to be spoken in three unrelated vocabularies: this
+ * category-based opt-in design (born in `cursed-satellites/satellite-kit`), the
+ * DB-backed audit|meter WINDOWS in `cursedbelt-cc/drivers`' retentionPolicy
+ * (billing evidence — a genuinely different concern that keeps the name
+ * {@link RetentionWindows}), and `deploy-engine/backupRetention`'s artifact
+ * pruning. DEDUP-8(c) made THIS one canonical and moved it here, so a single
+ * copy serves cursed-core, cursed-satellites and every generated app, and
+ * `RetentionPolicy` names exactly one thing across the fleet. `satellite-kit`'s
+ * `./retention` subpath is now a thin re-export of this module.
+ *
+ * An app declares what it owns and starts a sweeper; the station reads and
+ * edits the policies. Nothing else in the fleet should contain a timer that
+ * deletes old rows.
+ *
+ *   const sweeper = createRetentionSweeper({
+ *     app: "orch",
+ *     targets: [
+ *       createSqliteTableTarget({ db, declaration: {...}, table: "events", timeColumn: "at" }),
+ *       createFileDirTarget({ declaration: {...}, dir: attemptLogs.dir, match: /\.jsonl$/ }),
+ *     ],
+ *   });
+ *   sweeper.start();
+ *
+ * See `policy.ts` for the rule that decides whether a resource may be governed
+ * at all — retention is opt-in by category, and no category can describe data
+ * the owner would miss (which is exactly why billing evidence is NOT a category
+ * and lives in `retentionPolicy.ts` instead).
+ */
+export { archiveStamp, createJsonlArchive, DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES, resolveArchiveHome, verifyArchive, type ArchiveHome, type ArchiveSegment, type ArchiveSink, type JsonlArchiveOptions, } from "./archive";
+export { ARCHIVING_RETENTION_CATEGORIES, assertRetentionDeclaration, categoryArchivesBeforeDelete, cutoffFor, DAY_MS, FLEET_DEFAULT_RETENTION_DAYS, RETENTION_CATEGORIES, RETENTION_CATEGORY_KEYS, RETENTION_MAX_DAYS, RETENTION_MIN_DAYS, resolveRetentionPolicy, retentionKey, type EffectiveRetentionPolicy, type RetentionPolicy, type RetentionCategory, type RetentionDeclaration, type RetentionFieldSource, type RetentionOverride, type RetentionUnit, } from "./policy";
+export { publishRetention, readRetentionOverrides, readRetentionRegistry, resolveRetentionHome, setRetentionHomeForTests, writeRetentionOverride, type PublishedResource, type RetentionMeasurement, type RetentionOverridesFile, type RetentionPublication, type RetentionSweepReport, } from "./store";
+export { createArchivingSqliteTableTarget, createFileDirTarget, createSqliteTableTarget, type ArchivingSqliteTableTargetOptions, type FileDirTargetOptions, type RetentionPreview, type RetentionTarget, type SqliteTableTargetOptions, } from "./target";
+export { createRetentionSweeper, DEFAULT_SWEEP_INTERVAL_MS, OVERRIDES_PULSE_MS, type CreateRetentionSweeperOptions, type ResourceOutcome, type RetentionRunReport, type RetentionSweeper, } from "./sweeper";
+export { buildRetentionFleetView, type RetentionFleetRow, type RetentionFleetView } from "./fleet";

package/dist/server/retention/index.js

@@ -0,0 +1,38 @@
+/**
+ * `cursedbelt-server/retention` — THE fleet's one retention standard.
+ *
+ * ── Why this lives in cursedbelt ────────────────────────────────────────────
+ * Retention used to be spoken in three unrelated vocabularies: this
+ * category-based opt-in design (born in `cursed-satellites/satellite-kit`), the
+ * DB-backed audit|meter WINDOWS in `cursedbelt-cc/drivers`' retentionPolicy
+ * (billing evidence — a genuinely different concern that keeps the name
+ * {@link RetentionWindows}), and `deploy-engine/backupRetention`'s artifact
+ * pruning. DEDUP-8(c) made THIS one canonical and moved it here, so a single
+ * copy serves cursed-core, cursed-satellites and every generated app, and
+ * `RetentionPolicy` names exactly one thing across the fleet. `satellite-kit`'s
+ * `./retention` subpath is now a thin re-export of this module.
+ *
+ * An app declares what it owns and starts a sweeper; the station reads and
+ * edits the policies. Nothing else in the fleet should contain a timer that
+ * deletes old rows.
+ *
+ *   const sweeper = createRetentionSweeper({
+ *     app: "orch",
+ *     targets: [
+ *       createSqliteTableTarget({ db, declaration: {...}, table: "events", timeColumn: "at" }),
+ *       createFileDirTarget({ declaration: {...}, dir: attemptLogs.dir, match: /\.jsonl$/ }),
+ *     ],
+ *   });
+ *   sweeper.start();
+ *
+ * See `policy.ts` for the rule that decides whether a resource may be governed
+ * at all — retention is opt-in by category, and no category can describe data
+ * the owner would miss (which is exactly why billing evidence is NOT a category
+ * and lives in `retentionPolicy.ts` instead).
+ */
+export { archiveStamp, createJsonlArchive, DEFAULT_PENDING_ARCHIVE_BUDGET_BYTES, resolveArchiveHome, verifyArchive, } from "./archive";
+export { ARCHIVING_RETENTION_CATEGORIES, assertRetentionDeclaration, categoryArchivesBeforeDelete, cutoffFor, DAY_MS, FLEET_DEFAULT_RETENTION_DAYS, RETENTION_CATEGORIES, RETENTION_CATEGORY_KEYS, RETENTION_MAX_DAYS, RETENTION_MIN_DAYS, resolveRetentionPolicy, retentionKey, } from "./policy";
+export { publishRetention, readRetentionOverrides, readRetentionRegistry, resolveRetentionHome, setRetentionHomeForTests, writeRetentionOverride, } from "./store";
+export { createArchivingSqliteTableTarget, createFileDirTarget, createSqliteTableTarget, } from "./target";
+export { createRetentionSweeper, DEFAULT_SWEEP_INTERVAL_MS, OVERRIDES_PULSE_MS, } from "./sweeper";
+export { buildRetentionFleetView } from "./fleet";