@panaversity/ksor 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @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
+
+- 3890ad2: fix: a scaffolded project has exactly two commands, one per surface —
+  `pnpm dev` for the site people read, `pnpm serve` for the record agents query
+  (it applies the schema, authorizes ingest, ingests, and serves). Neither asks
+  the reader to decide anything.
+
+  fix: the one-command script is no longer called `up`. `up` is
+  pnpm's own alias for `update`, so the script shipped in 0.0.5 was shadowed by
+  the package manager: an adopter following the runbook ran `pnpm up` expecting
+  to bring their record up and instead upgraded their dependencies. Anyone on
+  0.0.5 should use `pnpm run schema && pnpm run grant && pnpm run ingest &&
+pnpm run serve` until they re-scaffold.
+
 ## 0.0.5
 
 ### 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.5",
+  "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

@@ -93,28 +93,39 @@ Stand it up in this order (each step's errors explain how to fix themselves):
 3. **Bring it up — one command:**
 
    ```sh
-   pnpm up      # schema → grant → ingest → serve
+   pnpm serve   # schema → grant → ingest → serve
    ```
 
    Every step is re-runnable, so this is also how you **refresh after editing
    `knowledge/`**: an applied schema reports "already applied", an existing
    grant reports "already granted", and ingest builds a fresh generation.
 
-   **`pnpm up` ingests every time — but it re-EMBEDS nothing that has not
-   changed.** Chunks carry forward by content hash, so a rerun on an untouched
-   corpus makes zero provider calls (`embedded 0, carried N` in the output).
-   What it does spend is a generation: each run creates and activates a new one,
-   and they accumulate. So:
-
-   | You want to                      | Run                                        |
-   | -------------------------------- | ------------------------------------------ |
-   | set up, or refresh after an edit | `pnpm up`                                  |
-   | just restart the server          | `pnpm serve` — no new generation           |
-   | reap superseded generations      | `pnpm exec ksor gc --instance instance.md` |
-
-   Run the steps individually (`pnpm schema`, `pnpm grant`, `pnpm ingest`)
-   when the acts belong to different people — a DBA holding the credentials
-   that authorize ingest, for instance.
+   **`pnpm serve` is the only command this rung needs.** Run it the first
+   time, run it after editing `knowledge/`, run it to bring the server back —
+   it is always the right answer, so there is nothing to decide. Every step it
+   chains reports the state it found rather than failing: an applied schema
+   says "already applied", an existing grant says "already granted", and
+   unchanged chunks carry forward by content hash, so a rerun on an untouched
+   corpus makes **zero provider calls** (`embedded 0, carried N`).
+
+   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
+   ```
+
+   The individual verbs (`pnpm schema`, `pnpm grant`, `pnpm ingest`,
+   `pnpm serve`) exist for pipelines and split duties — a deploy step that
+   ingests while a different process serves, or a DBA who holds the credentials
+   that authorize ingest. Reach for them when something else runs the steps;
+   not as a daily choice.
 
 4. **Turn the abstention gate on — deliberately, once it serves.** This is the
    step that makes "not in this corpus" a real answer, and it is measured, never

package/templates/scaffold/README.md

@@ -31,7 +31,7 @@ part of `pnpm dev`. The ordered path is:
 
 ```sh
 cp .env.example .env    # fill in KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH_DISABLED=1
-pnpm up                 # schema → grant → ingest → serve
+pnpm serve             # schema → grant → ingest → serve
 ```
 
 `ksor` reads `.env` automatically — nothing to export. `KSOR_AUTH_DISABLED=1`
@@ -44,10 +44,10 @@ the NAME of the variable, never the DSN. That is the whole required config:
 `retrieval:` out starts you with the abstention gate off and honest about it
 (turn it on afterwards with `ksor calibrate`, once the record is serving).
 
-`pnpm up` is re-runnable — it is also how you refresh after editing
-`knowledge/`. It re-ingests each time but re-embeds only what changed, so an
-untouched corpus costs no provider calls; to simply restart the server without
-building a new generation, run `pnpm serve` on its own. `AGENTS.md` → "Serving to agents" is the
+`pnpm serve` is the only command this rung needs — first run, after editing
+`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>`.
@@ -76,7 +76,7 @@ different coding agent's way of finding the same working contract.
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
 | `.env.example`                   | the variables the served rung needs; copy to `.env` (gitignored) and fill in. |
 | `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history.                                                                                                                                                    |
-| `package.json`                   | the `pnpm dev` / `pnpm build` / `pnpm check` commands and the served rung's `pnpm up` (schema → grant → ingest → serve, or run them separately), the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
+| `package.json`                   | the two surface commands — `pnpm dev` (the site) and `pnpm serve` (the agent surface: schema → grant → ingest → serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
 | `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
 | `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
 

package/templates/scaffold/package.json

@@ -7,11 +7,10 @@
     "dev": "pnpm -C system/site dev",
     "build": "pnpm -C system/site build",
     "check": "node .agents/skills/format-checker/check.mjs",
-    "up": "pnpm schema && pnpm grant && pnpm ingest && pnpm serve",
+    "serve": "pnpm schema && pnpm grant && pnpm ingest && ksor serve",
     "schema": "ksor schema --instance instance.md --apply",
     "grant": "ksor grant --instance instance.md",
-    "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip",
-    "serve": "ksor serve"
+    "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip"
   },
   "dependencies": {
     "@panaversity/ksor": "KSOR-STAMP-VERSION"