@gentbajko/slopify 0.1.0

package/dist/slices/storage/repo.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { outputRoles, stagedFileStates, stageKinds } from "./model.js";
+const metaSchema = z.object({
+    promptName: z.string().optional(),
+    prompt: z.string().optional(),
+    index: z.number().optional(),
+    provider: z.string().optional(),
+    model: z.string().optional(),
+    voice: z.string().optional(),
+});
+const outputRow = z.object({
+    id: z.string(),
+    project_id: z.string(),
+    stage_kind: z.enum(stageKinds),
+    role: z.enum(outputRoles),
+    path: z.string(),
+    original_filename: z.string().nullable(),
+    bytes: z.number(),
+    duration_ms: z.number().nullable(),
+    meta: z.string().nullable(),
+    created_at: z.string(),
+});
+const stagedFileRow = z.object({
+    id: z.string(),
+    stage_kind: z.enum(stageKinds),
+    path: z.string(),
+    original_filename: z.string(),
+    bytes: z.number(),
+    state: z.enum(stagedFileStates),
+    created_at: z.string(),
+});
+export function insertOutput(db, output) {
+    db.prepare("INSERT INTO outputs (id, project_id, stage_kind, role, path, original_filename, bytes, duration_ms, meta, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)").run(output.id, output.projectId, output.stageKind, output.role, output.path, output.originalFilename, output.bytes, output.durationMs, JSON.stringify(output.meta), output.createdAt);
+}
+export function outputsOf(db, projectId) {
+    return db
+        .prepare("SELECT * FROM outputs WHERE project_id = ? ORDER BY rowid")
+        .all(projectId)
+        .map((row) => toOutput(outputRow.parse(row)));
+}
+export function outputById(db, id) {
+    const row = db.prepare("SELECT * FROM outputs WHERE id = ?").get(id);
+    return row === undefined ? undefined : toOutput(outputRow.parse(row));
+}
+// `logic/12` §Q106: an action replaces an output rather than versioning it. The row goes
+// here; the file it names is the caller's to unlink once this has committed.
+export function deleteOutput(db, id) {
+    db.prepare("DELETE FROM outputs WHERE id = ?").run(id);
+}
+export function insertStagedFile(db, file) {
+    db.prepare("INSERT INTO staged_files (id, stage_kind, path, original_filename, bytes, state, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)").run(file.id, file.stageKind, file.path, file.originalFilename, file.bytes, file.state, file.createdAt);
+}
+export function markStagedFileCopied(db, id, bytes) {
+    db.prepare("UPDATE staged_files SET bytes = ?, state = 'staged' WHERE id = ?").run(bytes, id);
+}
+export function stagedFileById(db, id) {
+    const row = db.prepare("SELECT * FROM staged_files WHERE id = ?").get(id);
+    return row === undefined ? undefined : toStagedFile(stagedFileRow.parse(row));
+}
+export function stagedFiles(db) {
+    return db
+        .prepare("SELECT * FROM staged_files ORDER BY created_at, id")
+        .all()
+        .map((row) => toStagedFile(stagedFileRow.parse(row)));
+}
+export function deleteStagedFile(db, id) {
+    db.prepare("DELETE FROM staged_files WHERE id = ?").run(id);
+}
+export function projectTitle(db, projectId) {
+    const row = db.prepare("SELECT title FROM projects WHERE id = ?").get(projectId);
+    if (row === undefined) {
+        return undefined;
+    }
+    return z.object({ title: z.string() }).parse(row).title;
+}
+function toOutput(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        stageKind: row.stage_kind,
+        role: row.role,
+        path: row.path,
+        originalFilename: row.original_filename,
+        bytes: row.bytes,
+        durationMs: row.duration_ms,
+        meta: toMeta(row.meta),
+        createdAt: row.created_at,
+    };
+}
+// A JSON column never reaches a caller as a string.
+function toMeta(meta) {
+    return meta === null ? {} : metaSchema.parse(JSON.parse(meta));
+}
+function toStagedFile(row) {
+    return {
+        id: row.id,
+        stageKind: row.stage_kind,
+        path: row.path,
+        originalFilename: row.original_filename,
+        bytes: row.bytes,
+        state: row.state,
+        createdAt: row.created_at,
+    };
+}

package/dist/slices/storage/staging.js

@@ -0,0 +1,224 @@
+import { copyFileSync, createWriteStream, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { extensionOf, outputFileName, outputPath, stagingPath } from "./layout.js";
+import { deleteStagedFile, insertOutput, insertStagedFile, markStagedFileCopied, stagedFileById, } from "./repo.js";
+// The upload's own name is data, never a path component: the file is stored under a
+// generated id, and anything with a separator, a traversal, or a control character is
+// refused rather than sanitised, so nothing silently lands under a name nobody chose.
+const filename = z
+    .string()
+    .trim()
+    .min(1)
+    .max(255)
+    .refine((name) => !name.includes("/") && !name.includes("\\"))
+    .refine((name) => name !== "." && name !== "..")
+    .refine((name) => ![...name].some((character) => (character.codePointAt(0) ?? 0) < 0x20));
+// ceiling: progress is coalesced to one event per 200 ms per upload. A page that wants
+// a smoother bar reads bytes from the staging list instead of asking for more events.
+const progressIntervalMs = 200;
+export async function stageUpload(deps, input) {
+    const named = filename.safeParse(input.originalFilename);
+    if (!named.success) {
+        return { ok: false, reason: "unsafe-filename" };
+    }
+    const originalFilename = named.data;
+    const id = deps.ids.next();
+    const target = stagingPath(deps.paths, id);
+    const file = {
+        id,
+        stageKind: input.stageKind,
+        path: id,
+        originalFilename,
+        bytes: 0,
+        state: "copying",
+        createdAt: deps.clock.now().toISOString(),
+    };
+    // The row exists before the first byte, so a process that dies mid-copy leaves a
+    // record reconcile collects rather than an untracked file (logic/05 §Q44).
+    insertStagedFile(deps.db, file);
+    let bytes = 0;
+    let lastEmit = 0;
+    const notify = (event) => {
+        // Nothing about progress delivery may abort the write: a page that navigated away
+        // is not a reason to lose the upload it started (logic/05 §Q43).
+        try {
+            deps.emit(event);
+        }
+        catch (error) {
+            deps.log.write("warn", "staging.emit", { detail: messageOf(error) });
+        }
+    };
+    const progress = (state) => {
+        notify({
+            type: "staging.progress",
+            stagedFileId: id,
+            stageKind: input.stageKind,
+            originalFilename,
+            bytes,
+            state,
+        });
+    };
+    async function* counted() {
+        for await (const chunk of input.content) {
+            yield chunk;
+            bytes += chunk.byteLength;
+            const at = deps.clock.now().getTime();
+            if (at - lastEmit >= progressIntervalMs) {
+                lastEmit = at;
+                progress("copying");
+            }
+        }
+    }
+    const sink = createWriteStream(target, { mode: 0o600, flags: "wx" });
+    try {
+        await pipeline(counted(), sink);
+    }
+    catch (error) {
+        // pipeline rejects the moment the source throws, which can be before the file the
+        // write stream is opening exists. Removing it first would leave the stray file the
+        // reconcile has to collect at the next boot, so the close is waited for.
+        await closed(sink);
+        discard(deps, id, target, "staging.aborted");
+        notify({
+            type: "staging.failed",
+            stagedFileId: id,
+            stageKind: input.stageKind,
+            originalFilename,
+            detail: messageOf(error),
+        });
+        deps.log.write("error", "staging.failed", {
+            detail: `${id} ${originalFilename}: ${messageOf(error)}`,
+        });
+        throw error;
+    }
+    if (bytes === 0) {
+        discard(deps, id, target, "staging.empty");
+        return { ok: false, reason: "empty-file" };
+    }
+    markStagedFileCopied(deps.db, id, bytes);
+    progress("staged");
+    return { ok: true, file: { ...file, bytes, state: "staged" } };
+}
+export function attachStagedFile(deps, input) {
+    const staged = stagedFileById(deps.db, input.stagedFileId);
+    if (staged === undefined) {
+        return { ok: false, reason: "unknown-staged-file" };
+    }
+    // A run never starts with provided content that is still copying (logic/05 §Q44).
+    if (staged.state !== "staged") {
+        return { ok: false, reason: "still-copying" };
+    }
+    const index = input.index ?? 1;
+    const name = outputFileName(input.role, index, extensionOf(staged.originalFilename), staged.stageKind);
+    const target = outputPath(deps.paths, input.projectId, name);
+    const source = stagingPath(deps.paths, staged.path);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    // Copied, not renamed. A rename cannot be undone when the caller's transaction rolls
+    // back, so a run that failed on its fourth file would have left the first three with
+    // restored staged_files rows pointing at files that had already moved, and every retry
+    // of the same form would fail the same way. Copying also survives a staging directory
+    // mounted separately from projects/, which a rename cannot (EXDEV).
+    copyFileSync(source, target);
+    const output = {
+        id: deps.ids.next(),
+        projectId: input.projectId,
+        stageKind: staged.stageKind,
+        role: input.role,
+        path: name,
+        originalFilename: staged.originalFilename,
+        bytes: staged.bytes,
+        durationMs: null,
+        meta: input.role === "image" ? { index } : {},
+        createdAt: deps.clock.now().toISOString(),
+    };
+    // The file already moved. If this fails the file is under projects/ with no row,
+    // which is exactly what the boot reconcile collects.
+    // A savepoint rather than BEGIN, so startRun can attach several files inside the one
+    // transaction that creates the project.
+    try {
+        transact(deps.db, () => {
+            insertOutput(deps.db, output);
+            deleteStagedFile(deps.db, staged.id);
+        });
+    }
+    catch (error) {
+        deps.log.write("error", "storage.attach", {
+            projectId: input.projectId,
+            detail: `${staged.id} → ${name}: ${messageOf(error)}`,
+        });
+        throw error;
+    }
+    return { ok: true, output, stagedSource: source };
+}
+// The other half of attachStagedFile: called once the transaction that attached the file
+// has committed. A failure here is not worth failing the run over, because the file is a
+// duplicate of one the project already holds and the next boot's reconcile clears it.
+export function dropStagedSource(deps, source) {
+    try {
+        rmSync(source, { force: true });
+    }
+    catch (error) {
+        deps.log.write("warn", "staging.source", { detail: `${source}: ${messageOf(error)}` });
+    }
+}
+// logic/05 step 1: a stage set to Provide can carry pasted text instead of a file, and
+// the project holds it as an output like any other. Unlike an attached upload this needs
+// no two-phase dance: the text came in on the request, so a rollback loses nothing the
+// caller cannot write again, and the file left under a project id that was rolled back
+// is an orphan the boot reconcile removes.
+// ceiling: the paste is stored as typed. logic/05 §Q37 also asks for markdown syntax to
+// be stripped for the narration source; that reduction belongs to the narration slice
+// that reads this file, and lands with it.
+export function storeText(deps, input) {
+    const name = outputFileName(input.role, 1, ".txt", input.stageKind);
+    const target = outputPath(deps.paths, input.projectId, name);
+    const bytes = Buffer.from(input.text, "utf8");
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    writeFileSync(target, bytes, { mode: 0o600 });
+    const output = {
+        id: deps.ids.next(),
+        projectId: input.projectId,
+        stageKind: input.stageKind,
+        role: input.role,
+        path: name,
+        originalFilename: null,
+        bytes: bytes.byteLength,
+        durationMs: null,
+        meta: {},
+        createdAt: deps.clock.now().toISOString(),
+    };
+    insertOutput(deps.db, output);
+    return output;
+}
+export function discardStagedFile(deps, id) {
+    const staged = stagedFileById(deps.db, id);
+    if (staged === undefined) {
+        return { ok: false, reason: "unknown-staged-file" };
+    }
+    discard(deps, id, stagingPath(deps.paths, staged.path), "staging.discarded");
+    return { ok: true };
+}
+function discard(deps, id, target, event) {
+    try {
+        rmSync(target, { force: true });
+    }
+    catch (error) {
+        // The row stays `copying`, so the next boot's reconcile removes the file instead.
+        deps.log.write("warn", event, { detail: `${id}: ${messageOf(error)}` });
+        return;
+    }
+    deleteStagedFile(deps.db, id);
+}
+function closed(sink) {
+    return sink.closed
+        ? Promise.resolve()
+        : new Promise((resolve) => {
+            sink.once("close", resolve);
+        });
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/slices/telemetry/collector-client.js

@@ -0,0 +1,51 @@
+// 07-operations: the collector URL is built into the release and is not user
+// configurable. The environment variable below is a test seam, not a documented knob:
+// packages/app/test/telemetry-flush.test.ts points it at a fake collector.
+export const defaultCollectorUrl = "https://collector.slopify.stream";
+export function collectorEndpoint(env) {
+    const override = env.SLOPIFY_COLLECTOR_URL?.trim();
+    if (override === undefined || override === "") {
+        return defaultCollectorUrl;
+    }
+    const parsed = URL.parse(override);
+    if (parsed === null || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+        return defaultCollectorUrl;
+    }
+    return override.replace(/\/+$/, "");
+}
+export function httpPostEvents(endpoint, timeoutMs) {
+    return async (events) => {
+        if (events.length === 0) {
+            return { ok: true };
+        }
+        try {
+            const response = await fetch(`${endpoint}/events`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ events }),
+                // Without this an unanswering collector would hold a socket open for as long as
+                // the app runs, and the shutdown would wait on it.
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            // Nothing here reads the answer, and undici holds the connection open until a body
+            // is consumed or cancelled.
+            await response.body?.cancel();
+            if (response.ok) {
+                return { ok: true };
+            }
+            return {
+                ok: false,
+                retriable: response.status >= 500 || response.status === 429,
+                reason: `the collector answered ${response.status}`,
+            };
+        }
+        catch (error) {
+            // Offline is the ordinary case, not a fault: the events stay queued and the user is
+            // told nothing (logic/16 step 5).
+            return { ok: false, retriable: true, reason: messageOf(error) };
+        }
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/slices/telemetry/flush.js

@@ -0,0 +1,111 @@
+import { machineOf, markDelivered, undeliveredEvents } from "./repo.js";
+// ceiling: 200 events per request against the collector's cap of 500, and at most 25
+// requests per flush. A queue longer than 5000 undelivered events drains over several
+// flushes rather than in one burst, which is the back-pressure an unbounded queue
+// (logic/16 §Q134) needs against a collector that has been away for months.
+export const batchSize = 200;
+const maxBatchesPerFlush = 25;
+// logic/16 step 5: the queue is flushed at app start and after each new event. Nothing
+// here touches a pipeline, and an unreachable collector costs one refused socket.
+export async function flush(deps) {
+    const machine = machineOf(deps.db);
+    if (machine === undefined) {
+        // Before the notice is dismissed there is no machine id to send events under, and
+        // logic/16 step 1 says nothing leaves until then.
+        return { delivered: 0, dropped: 0 };
+    }
+    let delivered = 0;
+    let dropped = 0;
+    for (let batch = 0; batch < maxBatchesPerFlush; batch += 1) {
+        const events = undeliveredEvents(deps.db, batchSize);
+        if (events.length === 0) {
+            break;
+        }
+        const outcome = await deps.post(events.map((event) => envelope(event, machine.machineId)));
+        const ids = events.map((event) => event.id);
+        if (outcome.ok) {
+            markDelivered(deps.db, ids, deps.clock.now().toISOString());
+            delivered += ids.length;
+            continue;
+        }
+        if (outcome.retriable) {
+            // Offline, or the collector is having a bad day. The events stay queued and the
+            // user is told nothing (logic/16 step 5).
+            deps.log.write("info", "telemetry.deferred", {
+                detail: `${ids.length} events stay queued: ${outcome.reason}`,
+            });
+            break;
+        }
+        // The collector refused the batch itself. Retrying it would refuse it again and park
+        // every later event behind it, so it is marked delivered and lost on purpose.
+        markDelivered(deps.db, ids, deps.clock.now().toISOString());
+        dropped += ids.length;
+        deps.log.write("warn", "telemetry.dropped", {
+            detail: `${ids.length} events were refused and discarded: ${outcome.reason}`,
+        });
+        break;
+    }
+    return { delivered, dropped };
+}
+// The schedule from logic/16 step 5, debounced: a fan-out that finishes four stages at
+// once sends one request, not four. Every timer is unref'd, so a queued flush never
+// keeps the process alive.
+export function createFlusher(deps, delayMs) {
+    let timer;
+    let running = false;
+    let again = false;
+    let stopped = false;
+    const soon = () => {
+        if (stopped || timer !== undefined) {
+            return;
+        }
+        if (running) {
+            // Events recorded while a flush is in flight would otherwise wait for the next
+            // one, and on a short run there is no next one.
+            again = true;
+            return;
+        }
+        timer = setTimeout(run, delayMs);
+        timer.unref();
+    };
+    const run = () => {
+        timer = undefined;
+        running = true;
+        flush(deps)
+            .catch((error) => {
+            // The timer has no caller to fail: a broken flush is logged and the next one
+            // tries again (logic/16 step 5).
+            deps.log.write("warn", "telemetry.flush", { detail: messageOf(error) });
+        })
+            .finally(() => {
+            running = false;
+            if (again) {
+                again = false;
+                soon();
+            }
+        });
+    };
+    return {
+        soon,
+        stop: () => {
+            stopped = true;
+            again = false;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}
+function envelope(event, machineId) {
+    return {
+        id: event.id,
+        machineId,
+        type: event.type,
+        payload: event.payload,
+        createdAt: event.createdAt,
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/slices/telemetry/machine.js

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { transact } from "../../kernel/db/tx.js";
+import { writeEvent } from "./record.js";
+import { insertMachine, machineOf } from "./repo.js";
+// logic/16 step 1: the notice is shown when no machine id exists.
+export function noticeSeen(db) {
+    return machineOf(db) !== undefined;
+}
+// logic/16 step 1 and mockup/02-first-run-notice: the id is created when the user
+// dismisses the notice, never at boot, so nothing is collected before the promise about
+// what is collected has been made. Deleting the data directory makes a new install
+// (§Q127); there is no reset control and no opt-out.
+export function dismissNotice(deps) {
+    const existing = machineOf(deps.db);
+    if (existing !== undefined) {
+        return existing;
+    }
+    // Not the ULID generator the rest of the app uses: a ULID is sortable and carries the
+    // millisecond it was made, so a machine id built from one would order every install by
+    // install time and leak it to the collector. This one is random and nothing else.
+    const machine = {
+        machineId: randomUUID(),
+        noticeSeenAt: deps.clock.now().toISOString(),
+        appVersion: deps.appVersion,
+    };
+    transact(deps.db, () => {
+        insertMachine(deps.db, machine);
+        // logic/16 step 2: exactly one install event per machine. Written in the same
+        // transaction as the row that makes it unique, so a machine cannot exist without it.
+        writeEvent(deps, "install", {});
+    });
+    return machine;
+}

package/dist/slices/telemetry/model.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { stageKinds } from "../../kernel/pipeline.js";
+// logic/16 step 2: one install event, one per project created, one per stage completing.
+export const telemetryEventTypes = ["install", "project.created", "stage.completed"];
+// logic/16 step 2 counts finer than a stage: "one event per stage completing: research,
+// article, each intro/outro text, audio per segment (body, intro, outro), images,
+// thumbnail, video". The three that are not whole stages are named by `segment` beside
+// the stage that produced them - the article stage writes the intro and outro texts
+// (logic/07 step 5) and the audio stage narrates all three (logic/08 step 5) - so the
+// event type stays `stage.completed` and the pair (stage, segment) says which unit it is.
+export const audioSegments = ["body", "intro", "outro"];
+export const noTokens = { tokensIn: 0, tokensOut: 0 };
+export function plusUsage(tokens, usage) {
+    return {
+        tokensIn: tokens.tokensIn + (usage?.inputTokens ?? 0),
+        tokensOut: tokens.tokensOut + (usage?.outputTokens ?? 0),
+    };
+}
+// The whole privacy surface. logic/16 step 4 bars API keys, prompt bodies, keyword
+// values, titles, article and research text, files, filenames, OS, locale and hardware
+// from a payload, and mockup/02-first-run-notice promises the user exactly that. The
+// schema below is strict, so a caller that hands `record` anything not named here is
+// rejected before the row is written; model.test.ts pins the set and record.test.ts
+// sweeps every event type against it.
+export const payloadSchema = z.strictObject({
+    appVersion: z.string().max(40),
+    stage: z.enum(stageKinds).optional(),
+    segment: z.enum(audioSegments).optional(),
+    // ceiling: provider and model are length-capped, not matched against an allow-list,
+    // because model ids are the providers' own and change weekly. The cap is what stops a
+    // caller from smuggling prose through the one free-text pair the payload has.
+    provider: z.string().max(40).optional(),
+    model: z.string().max(120).optional(),
+    tokensIn: z.number().int().nonnegative().optional(),
+    tokensOut: z.number().int().nonnegative().optional(),
+    audioSeconds: z.number().nonnegative().finite().optional(),
+    images: z.number().int().nonnegative().optional(),
+    thumbnails: z.number().int().nonnegative().optional(),
+});

package/dist/slices/telemetry/record.js

@@ -0,0 +1,41 @@
+import { payloadSchema } from "./model.js";
+import { insertTelemetryEvent, machineOf } from "./repo.js";
+// Appends one row to the local queue and hands it back. Throws: the notice dismissal
+// needs the machine row and the install event to land together or not at all. Pipeline
+// callers use `record` below instead.
+export function writeEvent(deps, type, counters) {
+    const event = {
+        id: deps.ids.next(),
+        type,
+        // Strict: the payload is checked against the allow-list before it is written, so a
+        // caller cannot widen what leaves this machine by passing an extra field.
+        payload: payloadSchema.parse({ appVersion: deps.appVersion, ...counters }),
+        createdAt: deps.clock.now().toISOString(),
+        deliveredAt: null,
+    };
+    insertTelemetryEvent(deps.db, event);
+    return event;
+}
+// logic/16 step 5: telemetry never blocks and never fails a pipeline stage. This is the
+// one place in the codebase where an error is swallowed rather than propagated - a
+// failure to count a finished render must not undo the render. It is logged, so the
+// failure is still visible in <data-dir>/logs, and nothing else in this module catches.
+export function record(deps, type, counters) {
+    try {
+        // logic/16 step 2 precondition: a machine id exists for every event except the
+        // install event that creates it. Before the notice is dismissed nothing is written,
+        // so nothing about a run the user has not been told about can ever be sent.
+        if (type !== "install" && machineOf(deps.db) === undefined) {
+            return;
+        }
+        writeEvent(deps, type, counters);
+    }
+    catch (error) {
+        deps.log.write("warn", "telemetry.record", {
+            detail: `${type}: ${messageOf(error)}`,
+        });
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/slices/telemetry/repo.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { payloadSchema, telemetryEventTypes } from "./model.js";
+const eventRow = z.object({
+    id: z.string(),
+    type: z.enum(telemetryEventTypes),
+    payload: z.string(),
+    created_at: z.string(),
+    delivered_at: z.string().nullable(),
+});
+const machineRow = z.object({
+    machine_id: z.string(),
+    notice_seen_at: z.string().nullable(),
+    app_version: z.string(),
+});
+export function insertTelemetryEvent(db, event) {
+    db.prepare("INSERT INTO telemetry_events (id, type, payload, created_at, delivered_at) VALUES (?, ?, ?, ?, ?)").run(event.id, event.type, JSON.stringify(event.payload), event.createdAt, event.deliveredAt);
+}
+// The queue in the order it was written. By rowid rather than by created_at: two events
+// recorded in the same millisecond carry the same timestamp and their ULIDs are random
+// within it, so a timestamp sort would hand back the install after the project it
+// preceded. The collector deduplicates by id, so re-sending the head of the queue after
+// an ambiguous failure is safe (logic/16 §Q134).
+export function undeliveredEvents(db, limit) {
+    return db
+        .prepare("SELECT * FROM telemetry_events WHERE delivered_at IS NULL ORDER BY rowid LIMIT ?")
+        .all(limit)
+        .map((row) => toEvent(eventRow.parse(row)));
+}
+// logic/16 step 6 and §Q132: the Usage page's totals are the sum of the whole local log,
+// delivered or not, and §Q134 keeps that log forever.
+//
+// ceiling: every row is read and folded in memory. One event per stage of one run is a
+// few dozen bytes and a machine would need a hundred thousand runs to make this cost a
+// page load; the upgrade is to sum the counters in SQL with json_extract.
+export function allTelemetryEvents(db) {
+    return db
+        .prepare("SELECT * FROM telemetry_events ORDER BY rowid")
+        .all()
+        .map((row) => toEvent(eventRow.parse(row)));
+}
+export function markDelivered(db, ids, at) {
+    if (ids.length === 0) {
+        return;
+    }
+    const holes = ids.map(() => "?").join(", ");
+    db.prepare(`UPDATE telemetry_events SET delivered_at = ? WHERE id IN (${holes})`).run(at, ...ids);
+}
+// 02-models: a single row, so the first one is the machine.
+export function machineOf(db) {
+    const row = db.prepare("SELECT * FROM machine LIMIT 1").get();
+    return row === undefined ? undefined : toMachine(machineRow.parse(row));
+}
+export function insertMachine(db, machine) {
+    db.prepare("INSERT INTO machine (machine_id, notice_seen_at, app_version) VALUES (?, ?, ?)").run(machine.machineId, machine.noticeSeenAt, machine.appVersion);
+}
+function toEvent(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        // A JSON column never reaches a caller as a string, and the payload is re-checked on
+        // the way out: a row hand-edited into the database still cannot widen what is sent.
+        payload: payloadSchema.parse(JSON.parse(row.payload)),
+        createdAt: row.created_at,
+        deliveredAt: row.delivered_at,
+    };
+}
+function toMachine(row) {
+    return {
+        machineId: row.machine_id,
+        noticeSeenAt: row.notice_seen_at,
+        appVersion: row.app_version,
+    };
+}