@panaversity/ksor 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @panaversity/ksor
 
+## 0.0.7
+
+### Patch Changes
+
+- fcd44db: feat: restarting an unedited record is free. `ksor serve` runs ingest on every
+  start, and ingest now compares the corpus it just read against the generation
+  already serving — identical content at the same source commit consumes no
+  generation, writes no rows, and embeds nothing ("unchanged — generation N
+  already serves this corpus"). Editing a document still builds a generation and
+  re-embeds only what changed, and a new source commit over identical bytes still
+  records one, because that is a build fact provenance must keep.
+
 ## 0.0.6
 
 ### Patch Changes

package/dist/cli.mjs

@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-MwJTMEjf.mjs
+//#region ../content-gateway/dist/main-C5YO0opc.mjs
 /**
 * The pool checkout timed out — never retried: under saturation a retry is
 * a thundering herd aimed at the component already drowning.
@@ -3050,7 +3050,7 @@ async function runScopedIn(pool, gucs, op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-D8yo1t8o.mjs
+//#region ../content/dist/commands-I0bYSDS5.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -5864,6 +5864,53 @@ async function finalize(client, opts) {
 * finalize (+ optional flip, same transaction). Returns the report; the CLI
 * turns `refusal` into stderr + exit 1.
 */
+async function activeGenerationOf(c, tenantId, corpusId) {
+	const raw = (await c.query("SELECT active_generation FROM corpora WHERE tenant_id = $1 AND corpus_id = $2", [tenantId, corpusId])).rows[0]?.active_generation ?? null;
+	return raw === null ? null : Number(raw);
+}
+/**
+* Do two generations hold the same corpus? Compared on the SET of
+* (stable_id, content_hash) pairs — identity plus content — so a moved
+* document, an edited body, an added or removed file all count as different,
+* while a rebuild of identical bytes does not.
+*/
+async function sameCorpus(c, tenantId, a, b) {
+	return (await c.query(`WITH pair AS (
+       SELECT s.generation, n.stable_id, s.content_hash
+         FROM sources s JOIN content_nodes n
+           ON n.tenant_id = s.tenant_id AND n.generation = s.generation AND n.node_id = s.node_id
+        WHERE s.tenant_id = $1 AND s.generation IN ($2, $3)
+     )
+     SELECT (SELECT count(*) FROM pair WHERE generation = $2) =
+            (SELECT count(*) FROM pair WHERE generation = $3)
+        AND NOT EXISTS (
+              SELECT 1 FROM pair x WHERE x.generation = $2
+               AND NOT EXISTS (SELECT 1 FROM pair y WHERE y.generation = $3
+                                AND y.stable_id = x.stable_id AND y.content_hash = x.content_hash)
+            ) AS same`, [
+		tenantId,
+		a,
+		b
+	])).rows[0]?.same === true;
+}
+/** Was the active generation produced by this same source commit? */
+async function sameCommit(c, tenantId, generation, sourceCommit) {
+	const r = await c.query(`SELECT source_commit FROM ingestion_runs
+      WHERE tenant_id = $1 AND generation = $2
+      ORDER BY run_id DESC LIMIT 1`, [tenantId, generation]);
+	if (r.rows.length === 0) return false;
+	const stored = r.rows[0]?.source_commit ?? null;
+	return String(stored ?? "") === String(sourceCommit ?? "");
+}
+/** Thrown inside the build transaction to roll it back when nothing changed. */
+var UnchangedCorpus = class extends Error {
+	activeGeneration;
+	constructor(activeGeneration) {
+		super("corpus unchanged");
+		this.name = "UnchangedCorpus";
+		this.activeGeneration = activeGeneration;
+	}
+};
 async function buildGeneration(pool, instance, options) {
 	const log = options.onLog ?? (() => void 0);
 	const provider = options.provider;
@@ -5875,27 +5922,57 @@ async function buildGeneration(pool, instance, options) {
 		onSkip: log
 	});
 	const manifestSha256 = "sha256:" + createHash("sha256").update(JSON.stringify(manifestToJson(manifest)), "utf8").digest("hex");
-	const { runId, generation, stats } = await runIngest(pool, tenant, async (c) => {
-		const alloc = await allocateRun(c, {
-			tenantId: tenant,
-			corpusId: instance.corpusId,
-			sourceCommit: options.sourceCommit,
-			manifestSha256
-		});
-		const stats = await buildStructure(c, {
-			tenantId: tenant,
-			corpusId: instance.corpusId,
-			generation: alloc.generation,
-			manifest,
-			files: sources,
-			treeRoot: options.knowledgeDir,
-			modelId
+	let structure;
+	try {
+		structure = await runIngest(pool, tenant, async (c) => {
+			const alloc = await allocateRun(c, {
+				tenantId: tenant,
+				corpusId: instance.corpusId,
+				sourceCommit: options.sourceCommit,
+				manifestSha256
+			});
+			const stats = await buildStructure(c, {
+				tenantId: tenant,
+				corpusId: instance.corpusId,
+				generation: alloc.generation,
+				manifest,
+				files: sources,
+				treeRoot: options.knowledgeDir,
+				modelId
+			});
+			const active = await activeGenerationOf(c, tenant, instance.corpusId);
+			if (active !== null && await sameCommit(c, tenant, active, options.sourceCommit) && await sameCorpus(c, tenant, active, alloc.generation)) throw new UnchangedCorpus(active);
+			return {
+				...alloc,
+				stats
+			};
 		});
-		return {
-			...alloc,
-			stats
-		};
-	});
+	} catch (error) {
+		if (error instanceof UnchangedCorpus) {
+			log(`unchanged: generation ${error.activeGeneration} already serves this corpus`);
+			return {
+				runId: 0,
+				generation: error.activeGeneration,
+				nodes: 0,
+				sources: 0,
+				chunks: 0,
+				carried: 0,
+				embedded: 0,
+				failed: 0,
+				ready: true,
+				centroids: 0,
+				flipped: false,
+				refusal: null,
+				health: {
+					ok: true,
+					reasons: []
+				},
+				unchanged: true
+			};
+		}
+		throw error;
+	}
+	const { runId, generation, stats } = structure;
 	log(`run ${runId}: building generation ${generation} (embed ${provider.providerId}:${provider.recipe})`);
 	log(`structure: ${stats.nodes} nodes, ${stats.sources} sources, ${stats.chunks} chunks; carried ${stats.carried}, pending ${stats.pending}`);
 	const pending = rowsToInputs(await runIngest(pool, tenant, async (c) => {
@@ -5997,7 +6074,8 @@ async function buildGeneration(pool, instance, options) {
 		centroids: fin.centroids,
 		flipped: fin.flipped,
 		refusal: fin.refusal,
-		health: fin.health
+		health: fin.health,
+		unchanged: false
 	};
 }
 /** Python f"{x:.0%}" analogue. */
@@ -6205,6 +6283,10 @@ async function ingestCommand(args) {
 			throw exc;
 		}
 	});
+	if (report.unchanged) {
+		process.stdout.write(`ingest: unchanged — generation ${report.generation} already serves this corpus\n`);
+		return 0;
+	}
 	process.stdout.write(`ingest: generation ${report.generation} — ${report.nodes} nodes, ${report.chunks} chunks; embedded ${report.embedded}, carried ${report.carried}, failed ${report.failed}\n`);
 	if (report.refusal !== null) return fail$1(REFUSED, report.refusal);
 	if (!report.flipped) process.stdout.write("ready; flip withheld (pass --flip to activate)\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Knowledge System of Record — the authoritative, governed source of knowledge that humans and AI agents operate from. Name reserved; implementation in progress.",
   "keywords": [
     "abstention",

package/templates/scaffold/AGENTS.md

@@ -108,8 +108,14 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    unchanged chunks carry forward by content hash, so a rerun on an untouched
    corpus makes **zero provider calls** (`embedded 0, carried N`).
 
-   What a rerun does spend is a generation — each one is created and activated,
-   and they accumulate. Reap them when you think of it, or on a schedule:
+   A rerun on an unchanged record costs **nothing at all**: ingest compares the
+   corpus it just read against the generation already serving and, when they
+   are identical at the same commit, consumes no generation and writes no rows
+   ("unchanged — generation N already serves this corpus"). Edit a document and
+   the next run builds a generation for it, re-embedding only what changed.
+
+   Generations do accumulate as you edit. Reap the superseded ones when you
+   think of it, or on a schedule:
 
    ```sh
    pnpm exec ksor gc --instance instance.md

package/templates/scaffold/README.md

@@ -45,8 +45,9 @@ the NAME of the variable, never the DSN. That is the whole required config:
 (turn it on afterwards with `ksor calibrate`, once the record is serving).
 
 `pnpm serve` is the only command this rung needs — first run, after editing
-`knowledge/`, or just to bring the server back. It re-embeds only what changed,
-so a rerun on an untouched corpus costs no provider calls. `AGENTS.md` → "Serving to agents" is the
+`knowledge/`, or just to bring the server back. A rerun on an unchanged record
+costs nothing: no new generation, no embedding, no rows. Edit a document and
+the next run picks up exactly that change. `AGENTS.md` → "Serving to agents" is the
 full runbook; your coding agent reads it first. `pnpm serve` binds loopback
 with auth off for local use; a public bind fails closed unless auth is
 configured. Any other operation is `pnpm exec ksor <verb>`.