onadit 0.0.1 → 1.0.0

package/dist/src/server/routes/triage.js

@@ -0,0 +1,97 @@
+/**
+ * POST /triage route — Slice 5.
+ *
+ * Submits a batch of conversation contents for triage. The handler runs
+ * the locked OpenAI provider with per-batch cost cap and parallelism.
+ * Async: returns 202 Accepted with { job_id }.
+ *
+ * Triage is non-exclusive — it doesn't pause watchers and can run
+ * alongside ingest/save.
+ */
+import { z } from "zod";
+import { toJobStatusView } from "../../jobs/types.js";
+import { enqueueJob } from "./enqueue.js";
+import { HISTORICAL_BACKFILL_CAPABILITY_HEADER, HISTORICAL_BACKFILL_OVERRIDE_HEADER, INTERNAL_HISTORICAL_TRIAGE_CODEX_ROUTE, CODEX_CLI_OVERRIDE_PROVIDER, hasHistoricalBackfillCapability, isHistoricalTriageIdempotencyKey, } from "../../providers/operator-overrides.js";
+const TriageItemSchema = z
+    .object({
+    id: z.string().min(1),
+    content: z.string().min(1),
+    source: z.string().min(1).optional(),
+})
+    .strict();
+const TriageRequestSchema = z
+    .object({
+    items: z.array(TriageItemSchema).min(1).max(1000),
+    idempotency_key: z.string().optional(),
+})
+    .strict();
+export function registerTriageRoute(server, queue, dataDir) {
+    const submitTriage = async (request, reply, providerOverride, requireHistoricalCapability = false) => {
+        const parsed = TriageRequestSchema.safeParse(request.body ?? {});
+        if (!parsed.success) {
+            return reply.code(400).send({
+                error: "validation_error",
+                details: parsed.error.issues,
+            });
+        }
+        if (providerOverride === undefined &&
+            (request.headers[HISTORICAL_BACKFILL_OVERRIDE_HEADER] !== undefined ||
+                request.headers[HISTORICAL_BACKFILL_CAPABILITY_HEADER] !== undefined)) {
+            return reply.code(400).send({
+                error: "validation_error",
+                details: [
+                    {
+                        path: [
+                            request.headers[HISTORICAL_BACKFILL_CAPABILITY_HEADER] !== undefined
+                                ? HISTORICAL_BACKFILL_CAPABILITY_HEADER
+                                : HISTORICAL_BACKFILL_OVERRIDE_HEADER,
+                        ],
+                        message: "Historical provider overrides are only allowed through the internal backfill route.",
+                    },
+                ],
+            });
+        }
+        if (requireHistoricalCapability &&
+            !hasHistoricalBackfillCapability(dataDir, request.headers[HISTORICAL_BACKFILL_CAPABILITY_HEADER])) {
+            return reply.code(403).send({ error: "forbidden" });
+        }
+        if (requireHistoricalCapability &&
+            !isHistoricalTriageIdempotencyKey(parsed.data.idempotency_key)) {
+            return reply.code(400).send({
+                error: "validation_error",
+                details: [
+                    {
+                        path: ["idempotency_key"],
+                        message: "Historical Codex triage requires a backfill triage idempotency key.",
+                    },
+                ],
+            });
+        }
+        const opts = {
+            payload: {
+                items: parsed.data.items,
+                ...(providerOverride ? { provider_override: providerOverride } : {}),
+            },
+        };
+        if (parsed.data.idempotency_key !== undefined) {
+            opts.idempotency_key = parsed.data.idempotency_key;
+        }
+        const result = await enqueueJob(reply, queue, "triage", opts);
+        if (!result)
+            return;
+        if ("conflict" in result) {
+            return reply.code(409).send({ error: "conflict" });
+        }
+        if (result.duplicate) {
+            return reply.code(200).send({
+                job_id: result.job.id,
+                duplicate: true,
+                ...toJobStatusView(result.job),
+            });
+        }
+        return reply.code(202).send({ job_id: result.job.id });
+    };
+    server.post("/triage", async (request, reply) => submitTriage(request, reply));
+    server.post(INTERNAL_HISTORICAL_TRIAGE_CODEX_ROUTE, async (request, reply) => submitTriage(request, reply, CODEX_CLI_OVERRIDE_PROVIDER, true));
+}
+//# sourceMappingURL=triage.js.map

package/dist/src/server/routes/triage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triage.js","sourceRoot":"","sources":["../../../../src/server/routes/triage.ts"],"names":[],"mappings":"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"}

package/dist/src/server/save-quality.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Save-quality grader — Slice 2.
+ *
+ * Pure function that scores an incoming save payload and returns a
+ * tier plus warnings. Never rejects: the goal is to nudge agents
+ * toward a useful shape, not to block saves. Warnings flow back in
+ * the 202 response so the caller sees immediate feedback.
+ *
+ * Tiers:
+ *  - "thin"        — summary-only; acceptable for trivial pings but low retrieval value.
+ *  - "substantive" — has content; topically tagged or decision-bearing.
+ *  - "rich"        — content + topics + at least one of decisions/key_outputs.
+ */
+import type { SavePayload } from "./routes/save.js";
+export type SaveTier = "thin" | "substantive" | "rich";
+export interface SaveQualityReport {
+    tier: SaveTier;
+    warnings: string[];
+}
+export declare function gradeSavePayload(payload: SavePayload): SaveQualityReport;
+//# sourceMappingURL=save-quality.d.ts.map

package/dist/src/server/save-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-quality.d.ts","sourceRoot":"","sources":["../../../src/server/save-quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAOD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,iBAAiB,CA6DxE"}

package/dist/src/server/save-quality.js

@@ -0,0 +1,51 @@
+const SUMMARY_MIN = 10;
+const SUMMARY_MAX = 1000;
+const TOPIC_MAX = 40;
+const SUBSTANTIVE_CONTENT_BYTES = 500;
+export function gradeSavePayload(payload) {
+    const warnings = [];
+    const summary = payload.summary ?? "";
+    if (summary.length < SUMMARY_MIN) {
+        warnings.push(`summary too short (${summary.length} < ${SUMMARY_MIN} chars) — describe what was done, not just the topic`);
+    }
+    else if (summary.length > SUMMARY_MAX) {
+        warnings.push(`summary too long (${summary.length} > ${SUMMARY_MAX} chars) — put the transcript in content, keep summary one paragraph`);
+    }
+    const content = payload.content;
+    const contentBytes = content ? Buffer.byteLength(content, "utf-8") : 0;
+    const hasContent = contentBytes > 0;
+    const substantive = contentBytes >= SUBSTANTIVE_CONTENT_BYTES;
+    if (!hasContent) {
+        warnings.push("no content provided — summary-only saves have low retrieval value; send the full transcript when a session is substantive");
+    }
+    const topics = payload.topics ?? [];
+    if (substantive && topics.length === 0) {
+        warnings.push("substantive content without topics — add 1-5 short keywords so filtered search can find this");
+    }
+    for (const t of topics) {
+        if (t.length > TOPIC_MAX) {
+            warnings.push(`topic "${t.slice(0, TOPIC_MAX)}…" is too long (${t.length} chars) — topics should be short keywords, not sentences`);
+            break;
+        }
+    }
+    if (!payload.idempotency_key) {
+        warnings.push("no idempotency_key provided — auto-derived from content hash; prefer an explicit key like <source>:<session-id>:<fingerprint> for cross-session replacement");
+    }
+    const decisions = payload.decisions ?? [];
+    const keyOutputs = payload.key_outputs ?? [];
+    let tier;
+    if (hasContent && topics.length > 0 && (decisions.length > 0 || keyOutputs.length > 0)) {
+        tier = "rich";
+    }
+    else if (hasContent && (topics.length > 0 || decisions.length > 0 || keyOutputs.length > 0)) {
+        tier = "substantive";
+    }
+    else if (hasContent) {
+        tier = "substantive";
+    }
+    else {
+        tier = "thin";
+    }
+    return { tier, warnings };
+}
+//# sourceMappingURL=save-quality.js.map

package/dist/src/server/save-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-quality.js","sourceRoot":"","sources":["../../../src/server/save-quality.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,WAAW,GAAG,IAAI,CAAC;AACzB,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAEtC,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACnD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,IAAI,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QACjC,QAAQ,CAAC,IAAI,CACX,sBAAsB,OAAO,CAAC,MAAM,MAAM,WAAW,sDAAsD,CAC5G,CAAC;IACJ,CAAC;SAAM,IAAI,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QACxC,QAAQ,CAAC,IAAI,CACX,qBAAqB,OAAO,CAAC,MAAM,MAAM,WAAW,qEAAqE,CAC1H,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,UAAU,GAAG,YAAY,GAAG,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,YAAY,IAAI,yBAAyB,CAAC;IAE9D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,QAAQ,CAAC,IAAI,CACX,2HAA2H,CAC5H,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACpC,IAAI,WAAW,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,QAAQ,CAAC,IAAI,CACX,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;YACzB,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC,MAAM,0DAA0D,CACrH,CAAC;YACF,MAAM;QACR,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CACX,6JAA6J,CAC9J,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAC1C,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IAE7C,IAAI,IAAc,CAAC;IACnB,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACvF,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;SAAM,IAAI,UAAU,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9F,IAAI,GAAG,aAAa,CAAC;IACvB,CAAC;SAAM,IAAI,UAAU,EAAE,CAAC;QACtB,IAAI,GAAG,aAAa,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/src/server/serving-marker.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Explicit capability flags. Capability booleans — not a commit/version string —
+ * are the contract: `package.json` still reads `beta.21` on chunk-aware `main`,
+ * so a version string cannot distinguish builds. Each build declares what IT can
+ * do; a future build that drops a capability flips the flag rather than relying
+ * on commit-ancestry math.
+ */
+export interface ServingCapabilities {
+    /** The conversation tables carry `parent_id`/`chunk_index`/`chunk_count`. */
+    conversation_chunk_columns: boolean;
+    /** Retrieval reassembles chunk sets on the expand path (`detail="full"`). */
+    expand_stitching: boolean;
+    /** Safe for `chunk-backfill` to write a chunk-column conversation set here. */
+    chunk_backfill_write_compatible: boolean;
+}
+export interface ServingMarker {
+    version: string;
+    commit: string;
+    booted_at: string;
+    capabilities: ServingCapabilities;
+}
+/**
+ * Capabilities of THIS build. All true: this code defines the chunk columns in
+ * the conversation seed/migration, reassembles chunk sets on expand, and writes
+ * chunk-column sets coherently. A future build that regresses any of these must
+ * set the corresponding flag false.
+ */
+export declare const CURRENT_SERVING_CAPABILITIES: ServingCapabilities;
+/** Path of the marker within a data dir (under `observability/`, daemon-owned). */
+export declare function servingMarkerPath(dataDir: string): string;
+/** Assemble the marker for this build at boot time. */
+export declare function buildServingMarker(bootedAt: string): ServingMarker;
+/**
+ * Stamp the serving-build marker into the data dir. Atomic (write-temp +
+ * rename) so a crash mid-write never leaves a half-written marker that would
+ * read as malformed → refused. Best-effort: any failure is logged and
+ * swallowed so it can never break daemon boot.
+ *
+ * MUST be called only from the serving daemon boot path, never from a CLI tool.
+ */
+export declare function writeServingMarker(dataDir: string, bootedAt?: string): void;
+/** Read the marker. Returns null if absent, unreadable, or malformed. */
+export declare function readServingMarker(dataDir: string): ServingMarker | null;
+export interface CompatibilityVerdict {
+    ok: boolean;
+    /** Operator-facing reason when `ok` is false. */
+    reason: string;
+}
+/**
+ * Maximum age of a serving-build marker the write guard will trust (24h). The
+ * marker certifies a RECENT boot, not an ancient one — see the downgrade note in
+ * the file header. The backfill tool requires the daemon stopped, so the owner
+ * naturally does a boot→stop cycle right before backfilling; that boot re-stamps
+ * the marker fresh. A window of a day gives slack ("booted this morning, backfill
+ * this evening") while still rejecting a months-old, possibly downgrade-era
+ * marker. Small future clock skew is tolerated up to {@link MAX_FUTURE_SKEW_MS}.
+ */
+export declare const MAX_MARKER_AGE_MS: number;
+/** Clock-skew slack for a marker dated slightly in the future (5 min). */
+export declare const MAX_FUTURE_SKEW_MS: number;
+/**
+ * Decide whether a destructive `chunk-backfill` WRITE is safe against the
+ * install that serves `dataDir`. Refuses unless the serving daemon has stamped
+ * a well-formed, RECENT marker in which EVERY capability in
+ * {@link REQUIRED_WRITE_CAPABILITIES} is true.
+ *
+ * Refusal cases:
+ *   - Absent/malformed marker: a pre-chunk daemon never writes one, so we cannot
+ *     prove the install that restarts after the write can serve chunk rows.
+ *   - Unparseable `booted_at`: a marker without a real boot time cannot prove
+ *     freshness, so it is treated as malformed.
+ *   - Missing capability: the serving build self-declares it cannot serve a
+ *     chunk-column set.
+ *   - Stale `booted_at` (older than `maxAgeMs`): proves only that SOME chunk-aware
+ *     daemon booted this dir long ago, not that the CURRENT install is chunk-aware
+ *     (closes the silent-downgrade gap — see file header).
+ *
+ * `now`/`maxAgeMs` are injectable for deterministic tests; production callers use
+ * the wall clock and {@link MAX_MARKER_AGE_MS}.
+ */
+export declare function assertChunkBackfillWriteCompatible(dataDir: string, opts?: {
+    now?: Date;
+    maxAgeMs?: number;
+}): CompatibilityVerdict;
+//# sourceMappingURL=serving-marker.d.ts.map

package/dist/src/server/serving-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving-marker.d.ts","sourceRoot":"","sources":["../../../src/server/serving-marker.ts"],"names":[],"mappings":"AA8CA;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,0BAA0B,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,+EAA+E;IAC/E,+BAA+B,EAAE,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,mBAI1C,CAAC;AAEF,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAQlE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAiC,GAC1C,IAAI,CAcN;AAsBD,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAQvE;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB;AAgBD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,QAAsB,CAAC;AAErD,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3C,oBAAoB,CAoEtB"}

package/dist/src/server/serving-marker.js

@@ -0,0 +1,226 @@
+/**
+ * Serving-build capability marker.
+ *
+ * The serving daemon stamps a small JSON marker into the data dir on every
+ * boot, recording WHICH code last served this data dir and what that code is
+ * capable of. This is the contract that lets an OFFLINE tool — one that runs
+ * with the daemon stopped, so it cannot probe `GET /version` — decide whether a
+ * destructive, schema-touching operation is safe against the install that will
+ * restart and serve this dir.
+ *
+ * Why a capability marker and not the obvious alternatives:
+ *   - On-disk table schema is the very thing that gets accidentally mutated
+ *     (the chunk-backfill `--dry-run` incident added the chunk columns to a
+ *     pre-chunk dir), so the schema cannot certify the serving code.
+ *   - Observability events are an indirect history signal — they tell you what
+ *     happened, not what the currently-installed code can do.
+ *   - `RIFT_CHUNKING` gates whether NEW conversations are split, not whether the
+ *     permanent chunk columns / expand read path exist in the serving build.
+ * Only a marker written BY the serving build answers the question we actually
+ * care about: "what code last served this dir, and can it handle a
+ * chunk-backfill write?".
+ *
+ * Discipline:
+ *   - Written ONLY by the serving daemon (never by CLI tools). A CLI tool that
+ *     stamped the marker would be certifying itself, defeating the purpose.
+ *   - Best-effort and non-fatal — a failed marker write must never break boot.
+ *   - Absent / unknown / malformed is treated by the write guard as "cannot
+ *     confirm compatible → refuse". A pre-chunk daemon (e.g. beta.21) never
+ *     writes the marker, so it always reads as absent → refused.
+ *   - STALE markers are refused too (freshness window, see
+ *     {@link MAX_MARKER_AGE_MS}). A marker proves "a chunk-aware daemon booted
+ *     this dir RECENTLY", not "a chunk-aware daemon booted this dir once, ever".
+ *     This closes the downgrade gap: if a chunk-aware daemon stamps a marker and
+ *     a pre-chunk daemon (beta.21) later serves the same dir, beta.21 neither
+ *     overwrites nor removes the stale chunk-aware marker — so without a
+ *     freshness check the offline write guard would still pass against an install
+ *     that can no longer serve chunk rows. Requiring a recent boot means the
+ *     owner must (re)boot the chunk-aware daemon immediately before backfilling,
+ *     which re-stamps the marker with the CURRENT install's real capabilities.
+ *     Daemon DOWNGRADE (chunk-aware → pre-chunk) after a marker write is
+ *     otherwise unsupported in this owner-only phase.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getBuildInfo } from "./build-info.js";
+/**
+ * Capabilities of THIS build. All true: this code defines the chunk columns in
+ * the conversation seed/migration, reassembles chunk sets on expand, and writes
+ * chunk-column sets coherently. A future build that regresses any of these must
+ * set the corresponding flag false.
+ */
+export const CURRENT_SERVING_CAPABILITIES = {
+    conversation_chunk_columns: true,
+    expand_stitching: true,
+    chunk_backfill_write_compatible: true,
+};
+/** Path of the marker within a data dir (under `observability/`, daemon-owned). */
+export function servingMarkerPath(dataDir) {
+    return path.join(dataDir, "observability", "serving-build.json");
+}
+/** Assemble the marker for this build at boot time. */
+export function buildServingMarker(bootedAt) {
+    const info = getBuildInfo();
+    return {
+        version: info.version,
+        commit: info.commit,
+        booted_at: bootedAt,
+        capabilities: { ...CURRENT_SERVING_CAPABILITIES },
+    };
+}
+/**
+ * Stamp the serving-build marker into the data dir. Atomic (write-temp +
+ * rename) so a crash mid-write never leaves a half-written marker that would
+ * read as malformed → refused. Best-effort: any failure is logged and
+ * swallowed so it can never break daemon boot.
+ *
+ * MUST be called only from the serving daemon boot path, never from a CLI tool.
+ */
+export function writeServingMarker(dataDir, bootedAt = new Date().toISOString()) {
+    try {
+        const target = servingMarkerPath(dataDir);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        const tmp = `${target}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, `${JSON.stringify(buildServingMarker(bootedAt), null, 2)}\n`);
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        process.stderr.write(`serving-marker: failed to write (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+function isServingMarker(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const m = v;
+    if (typeof m.version !== "string" ||
+        typeof m.commit !== "string" ||
+        typeof m.booted_at !== "string") {
+        return false;
+    }
+    const c = m.capabilities;
+    if (!c || typeof c !== "object")
+        return false;
+    const caps = c;
+    return (typeof caps.conversation_chunk_columns === "boolean" &&
+        typeof caps.expand_stitching === "boolean" &&
+        typeof caps.chunk_backfill_write_compatible === "boolean");
+}
+/** Read the marker. Returns null if absent, unreadable, or malformed. */
+export function readServingMarker(dataDir) {
+    try {
+        const raw = fs.readFileSync(servingMarkerPath(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        return isServingMarker(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every capability a chunk-backfill WRITE depends on. The write doesn't just
+ * need a serving build that *tolerates* a chunk-column write — it needs one that
+ * has the columns (`conversation_chunk_columns`), reassembles the sets it writes
+ * on the read path (`expand_stitching`), AND self-certifies the write as safe
+ * (`chunk_backfill_write_compatible`). A build that regresses ANY of these would
+ * serve the backfilled corpus incorrectly, so all must be true.
+ */
+const REQUIRED_WRITE_CAPABILITIES = [
+    "conversation_chunk_columns",
+    "expand_stitching",
+    "chunk_backfill_write_compatible",
+];
+/**
+ * Maximum age of a serving-build marker the write guard will trust (24h). The
+ * marker certifies a RECENT boot, not an ancient one — see the downgrade note in
+ * the file header. The backfill tool requires the daemon stopped, so the owner
+ * naturally does a boot→stop cycle right before backfilling; that boot re-stamps
+ * the marker fresh. A window of a day gives slack ("booted this morning, backfill
+ * this evening") while still rejecting a months-old, possibly downgrade-era
+ * marker. Small future clock skew is tolerated up to {@link MAX_FUTURE_SKEW_MS}.
+ */
+export const MAX_MARKER_AGE_MS = 24 * 60 * 60 * 1000;
+/** Clock-skew slack for a marker dated slightly in the future (5 min). */
+export const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+/**
+ * Decide whether a destructive `chunk-backfill` WRITE is safe against the
+ * install that serves `dataDir`. Refuses unless the serving daemon has stamped
+ * a well-formed, RECENT marker in which EVERY capability in
+ * {@link REQUIRED_WRITE_CAPABILITIES} is true.
+ *
+ * Refusal cases:
+ *   - Absent/malformed marker: a pre-chunk daemon never writes one, so we cannot
+ *     prove the install that restarts after the write can serve chunk rows.
+ *   - Unparseable `booted_at`: a marker without a real boot time cannot prove
+ *     freshness, so it is treated as malformed.
+ *   - Missing capability: the serving build self-declares it cannot serve a
+ *     chunk-column set.
+ *   - Stale `booted_at` (older than `maxAgeMs`): proves only that SOME chunk-aware
+ *     daemon booted this dir long ago, not that the CURRENT install is chunk-aware
+ *     (closes the silent-downgrade gap — see file header).
+ *
+ * `now`/`maxAgeMs` are injectable for deterministic tests; production callers use
+ * the wall clock and {@link MAX_MARKER_AGE_MS}.
+ */
+export function assertChunkBackfillWriteCompatible(dataDir, opts = {}) {
+    const now = opts.now ?? new Date();
+    const maxAgeMs = opts.maxAgeMs ?? MAX_MARKER_AGE_MS;
+    const marker = readServingMarker(dataDir);
+    if (!marker) {
+        return {
+            ok: false,
+            reason: `No serving-build marker at ${servingMarkerPath(dataDir)}. Cannot ` +
+                `confirm the install that serves this data dir is chunk-aware — a ` +
+                `pre-chunk daemon (e.g. beta.21) never writes this marker. Boot the ` +
+                `chunk-aware serving daemon on this dir first (it stamps the marker on ` +
+                `startup), or — if this is a DISPOSABLE COPY, never your live data dir — ` +
+                `re-run with --allow-uncertified-copy to override.`,
+        };
+    }
+    const missing = REQUIRED_WRITE_CAPABILITIES.filter((cap) => !marker.capabilities[cap]);
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            reason: `Serving-build marker (version ${marker.version}, commit ` +
+                `${marker.commit.slice(0, 12)}) is missing required capabilities: ` +
+                `${missing.map((c) => `${c}=false`).join(", ")} — the serving install ` +
+                `cannot safely serve a chunk-column conversation set. Upgrade the ` +
+                `serving daemon before backfilling.`,
+        };
+    }
+    const bootedMs = Date.parse(marker.booted_at);
+    if (Number.isNaN(bootedMs)) {
+        return {
+            ok: false,
+            reason: `Serving-build marker has an invalid booted_at ("${marker.booted_at}") ` +
+                `— cannot prove the chunk-aware daemon booted recently. Reboot the ` +
+                `chunk-aware serving daemon on this dir to re-stamp the marker.`,
+        };
+    }
+    const ageMs = now.getTime() - bootedMs;
+    if (ageMs > maxAgeMs) {
+        const ageHours = Math.round(ageMs / 3_600_000);
+        const maxHours = Math.round(maxAgeMs / 3_600_000);
+        return {
+            ok: false,
+            reason: `Serving-build marker is stale (booted_at ${marker.booted_at}, ~${ageHours}h ` +
+                `old > ${maxHours}h freshness window). A stale marker only proves a ` +
+                `chunk-aware daemon booted this dir long ago — not that the CURRENT ` +
+                `install is chunk-aware (a since-downgraded daemon leaves the old marker ` +
+                `in place). (Re)boot the chunk-aware serving daemon on this dir ` +
+                `immediately before backfilling to re-stamp the marker, or — if this is ` +
+                `a DISPOSABLE COPY, never your live data dir — re-run with ` +
+                `--allow-uncertified-copy to override.`,
+        };
+    }
+    if (ageMs < -MAX_FUTURE_SKEW_MS) {
+        return {
+            ok: false,
+            reason: `Serving-build marker is dated in the future (booted_at ` +
+                `${marker.booted_at}) beyond tolerated clock skew — refusing rather than ` +
+                `trusting a marker that may have been hand-edited. Reboot the chunk-aware ` +
+                `serving daemon on this dir to re-stamp the marker.`,
+        };
+    }
+    return { ok: true, reason: "" };
+}
+//# sourceMappingURL=serving-marker.js.map

package/dist/src/server/serving-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving-marker.js","sourceRoot":"","sources":["../../../src/server/serving-marker.ts"],"names":[],"mappings":"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"}

package/dist/src/storage/atomic.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Atomically write `data` to `filePath`.
+ *
+ * 1. Writes to `${filePath}.tmp.${pid}`
+ * 2. Renames temp -> target (atomic on same filesystem)
+ */
+export declare function atomicWrite(filePath: string, data: string): Promise<void>;
+//# sourceMappingURL=atomic.d.ts.map

package/dist/src/storage/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../../src/storage/atomic.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/E"}

package/dist/src/storage/atomic.js

@@ -0,0 +1,22 @@
+/**
+ * Atomic file write: write to temp, then rename.
+ *
+ * If the process crashes mid-write, only the temp file is corrupted —
+ * the target path either has the old content or the new content, never partial.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Atomically write `data` to `filePath`.
+ *
+ * 1. Writes to `${filePath}.tmp.${pid}`
+ * 2. Renames temp -> target (atomic on same filesystem)
+ */
+export async function atomicWrite(filePath, data) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, data, "utf-8");
+    fs.renameSync(tmp, filePath);
+}
+//# sourceMappingURL=atomic.js.map

package/dist/src/storage/atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../../src/storage/atomic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,IAAY;IAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,MAAM,GAAG,GAAG,GAAG,QAAQ,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IAC7C,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC/B,CAAC"}

package/dist/src/storage/chunk-backfill.d.ts

@@ -0,0 +1,39 @@
+import type { EmbeddingProvider } from "../providers/types.js";
+export interface ChunkBackfillOptions {
+    embedding: EmbeddingProvider;
+    dataDir: string;
+    /** Report what would change without embedding or writing anything. */
+    dryRun?: boolean;
+    /** Stop after this many conversations have been (re)chunked. 0/undefined = no cap. */
+    limit?: number;
+    /** Sleep this many ms between conversations to spare the embedding API. */
+    throttleMs?: number;
+    /** Cooperative cancel — checked between conversations (Ctrl-C safe). */
+    signal?: AbortSignal;
+    /** Progress sink (one line per meaningful event). */
+    log?: (msg: string) => void;
+}
+export interface ChunkBackfillSummary {
+    /** Distinct conversations examined (most-recent raw per id). */
+    scanned: number;
+    /** Conversations split into a multi-chunk set this run (or that would be, in dryRun). */
+    rechunked: number;
+    /** Conversations already in the desired multi-chunk shape — skipped. */
+    alreadyChunked: number;
+    /** Conversations short enough to stay a single unmarked row — skipped. */
+    singleChunk: number;
+    /** Raw artifacts with no matching indexed row — skipped (not resurrected). */
+    orphaned: number;
+    /** Raw artifacts that could not be read/parsed — skipped. */
+    errored: number;
+    /** True if an abort signal stopped the run before all conversations were seen. */
+    aborted: boolean;
+}
+/**
+ * Re-chunk historical conversations from raw into chunk sets. Returns a summary
+ * of what changed. Idempotent: a conversation already in its desired shape (a
+ * complete set of the right count, or a single unmarked row for a short
+ * conversation) is skipped, so re-running only touches the remainder.
+ */
+export declare function backfillConversationChunks(opts: ChunkBackfillOptions): Promise<ChunkBackfillSummary>;
+//# sourceMappingURL=chunk-backfill.d.ts.map

package/dist/src/storage/chunk-backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-backfill.d.ts","sourceRoot":"","sources":["../../../src/storage/chunk-backfill.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AA0B/D,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qDAAqD;IACrD,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;CAClB;AAyGD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAuH/B"}