@sigrun/knowledge 0.0.0-stage → 0.1.2

package/dist/undo.js

@@ -0,0 +1,335 @@
+function writeVersion(db, changeId, table, rowId, before, after, at) {
+    db.raw()
+        .prepare('INSERT INTO versions (changeId, "table", rowId, before, after, at) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(changeId, table, rowId, before === undefined || before === null
+        ? null
+        : JSON.stringify(before), after === undefined || after === null
+        ? null
+        : JSON.stringify(after), at);
+}
+/**
+ * Undo a change: walk its versions newest-first and restore each row's
+ * `before` state — but only while the row still equals the change's
+ * `after`. A row a later change edited is skipped, so undo restores only
+ * what the change last wrote. Every restore is itself recorded as a
+ * version under `undo:<changeId>`, so nothing is lost.
+ */
+export function undoChange(db, changeId, now) {
+    return db.transaction(() => {
+        const undoId = `undo:${changeId}`;
+        const versions = db
+            .raw()
+            .prepare('SELECT seq, changeId, "table", rowId, before, after, at FROM versions WHERE changeId = ? ORDER BY seq DESC')
+            // SAFETY: the versions table columns are fixed by db.ts's schema;
+            // node:sqlite only types rows generically.
+            .all(changeId);
+        let restored = 0;
+        const skipped = [];
+        const touched = new Set();
+        for (const version of versions) {
+            switch (version.table) {
+                case "entities": {
+                    const outcome = undoEntity(db, version, undoId, now);
+                    if (outcome === "restored") {
+                        restored += 1;
+                        touched.add(version.rowId);
+                    }
+                    else if (outcome !== "unchanged") {
+                        skipped.push(outcome);
+                    }
+                    break;
+                }
+                case "roles": {
+                    const outcome = undoRole(db, version, undoId, now);
+                    if (outcome === "restored")
+                        restored += 1;
+                    else if (outcome !== "unchanged")
+                        skipped.push(outcome);
+                    break;
+                }
+                case "inquiries": {
+                    const outcome = undoInquiry(db, version, undoId, now);
+                    if (outcome === "restored")
+                        restored += 1;
+                    else if (outcome !== "unchanged")
+                        skipped.push(outcome);
+                    break;
+                }
+                case "types": {
+                    // Type rows are shared schema: undo restores them only while
+                    // the row still equals what the change wrote (a later
+                    // extension of the type blocks the revert, not other
+                    // types). A type the change created is archived in turn.
+                    const outcome = undoType(db, version, undoId, now);
+                    if (outcome === "restored")
+                        restored += 1;
+                    else if (outcome !== "unchanged")
+                        skipped.push(outcome);
+                    break;
+                }
+                case "entity_keys": {
+                    const outcome = undoEntityKey(db, version, undoId, now);
+                    if (outcome === "restored")
+                        restored += 1;
+                    else if (outcome !== "unchanged")
+                        skipped.push(outcome);
+                    break;
+                }
+            }
+        }
+        return { restored, skipped, touched: [...touched] };
+    });
+}
+function undoEntity(db, version, undoId, now) {
+    const row = db
+        .raw()
+        .prepare("SELECT id, typeId, name, keys, fields, attributes, cls, indexedAt, archived FROM entities WHERE id = ?")
+        .get(version.rowId);
+    if (row === undefined) {
+        return `entity ${version.rowId}: no longer present`;
+    }
+    if (version.before === null) {
+        // The change created this entity: undo archives it — but only
+        // while the row still equals what the change wrote; a later
+        // change's edits (rename, new fields, new keys) stand.
+        if (Number(row.archived) !== 0)
+            return "unchanged";
+        const afterCreate = JSON.parse(version.after ?? "null");
+        const differs = afterDiffersFromRow(afterCreate, row, [
+            "name",
+            "keys",
+            "fields",
+            "attributes",
+            "typeId",
+        ]);
+        if (differs !== null) {
+            return `entity "${String(row.name)}" (${version.rowId}): ${differs}`;
+        }
+        writeVersion(db, undoId, "entities", version.rowId, row, { ...row, archived: 1 }, now);
+        db.raw()
+            .prepare("UPDATE entities SET archived = 1 WHERE id = ?")
+            .run(version.rowId);
+        return "restored";
+    }
+    const before = JSON.parse(version.before ?? "null");
+    const after = JSON.parse(version.after ?? "null");
+    // Whole-row equality: a later change touching anything the change
+    // wrote (name, keys, attributes, type — not just fields) blocks the
+    // undo, so undoing A can never silently revert B's rename.
+    const differs = afterDiffersFromRow(after, row, [
+        "name",
+        "keys",
+        "fields",
+        "attributes",
+        "typeId",
+    ]);
+    if (before === null || after === null || differs !== null) {
+        return `entity "${String(row.name)}" (${version.rowId}): ${differs ?? "changed by a later change"}`;
+    }
+    const restoredRow = { ...row, ...before, id: row.id, archived: row.archived };
+    writeVersion(db, undoId, "entities", version.rowId, row, restoredRow, now);
+    db.raw()
+        .prepare("UPDATE entities SET typeId = ?, name = ?, keys = ?, fields = ?, attributes = ?, indexedAt = ? WHERE id = ?")
+        .run(restoredRow.typeId, restoredRow.name, restoredRow.keys, restoredRow.fields, restoredRow.attributes, restoredRow.indexedAt, version.rowId);
+    return "restored";
+}
+/**
+ * JSON-stable compare of a version's `after` against the current row for
+ * the given columns. Returns null when equal, otherwise a short text
+ * naming the first differing column.
+ */
+function afterDiffersFromRow(after, row, columns) {
+    if (after === null)
+        return "changed by a later change";
+    for (const column of columns) {
+        // Absent key = the version blob doesn't carry that column (partial
+        // blobs, e.g. inquiry updates store only conversations/outcome);
+        // undefined can only mean missing — a stored null is "null".
+        if (after[column] === undefined)
+            continue;
+        if (JSON.stringify(after[column]) !== JSON.stringify(row[column])) {
+            return `${column} changed by a later change`;
+        }
+    }
+    return null;
+}
+function undoRole(db, version, undoId, now) {
+    const row = db
+        .raw()
+        .prepare("SELECT id, inquiryId, entityId, role, reason FROM roles WHERE id = ?")
+        .get(Number(version.rowId));
+    if (row === undefined)
+        return "unchanged";
+    if (version.before === null) {
+        // The change created this role: undo deletes it.
+        const after = JSON.parse(version.after ?? "null");
+        const differs = afterDiffersFromRow(after, row, ["role", "reason"]);
+        if (differs !== null) {
+            return `role ${version.rowId}: ${differs}`;
+        }
+        writeVersion(db, undoId, "roles", version.rowId, row, null, now);
+        db.raw().prepare("DELETE FROM roles WHERE id = ?").run(Number(version.rowId));
+        return "restored";
+    }
+    const before = JSON.parse(version.before ?? "null");
+    const after = JSON.parse(version.after ?? "null");
+    const differs = afterDiffersFromRow(after, row, ["role", "reason"]);
+    if (before === null || after === null || differs !== null) {
+        return `role ${version.rowId}: ${differs ?? "changed by a later change"}`;
+    }
+    writeVersion(db, undoId, "roles", version.rowId, row, { ...row, ...before, id: row.id }, now);
+    db.raw()
+        .prepare("UPDATE roles SET role = ?, reason = ? WHERE id = ?")
+        .run(before.role, before.reason ?? null, Number(version.rowId));
+    return "restored";
+}
+function undoInquiry(db, version, undoId, now) {
+    const row = db
+        .raw()
+        .prepare("SELECT id, question, why, startedAt, touchedAt, conversations, outcome, archived FROM inquiries WHERE id = ?")
+        .get(Number(version.rowId));
+    if (row === undefined)
+        return "unchanged";
+    if (version.before === null) {
+        // The change created this inquiry: undo archives it (records are
+        // never deleted). Only while the row still equals what the change
+        // wrote.
+        if (Number(row.archived) !== 0)
+            return "unchanged";
+        const after = JSON.parse(version.after ?? "null");
+        const differs = afterDiffersFromRow(after, row, [
+            "question",
+            "why",
+            "outcome",
+            "conversations",
+        ]);
+        if (differs !== null) {
+            return `inquiry "${String(row.question)}" (${version.rowId}): ${differs}`;
+        }
+        writeVersion(db, undoId, "inquiries", version.rowId, row, { ...row, archived: 1 }, now);
+        db.raw()
+            .prepare("UPDATE inquiries SET archived = 1, touchedAt = ? WHERE id = ?")
+            .run(now, Number(version.rowId));
+        return "restored";
+    }
+    const before = JSON.parse(version.before ?? "null");
+    const after = JSON.parse(version.after ?? "null");
+    const differs = afterDiffersFromRow(after, row, [
+        "question",
+        "why",
+        "outcome",
+        "conversations",
+    ]);
+    if (before === null || after === null || differs !== null) {
+        return `inquiry "${String(row.question)}" (${version.rowId}): ${differs ?? "changed by a later change"}`;
+    }
+    const restored = { ...row, ...before, id: row.id };
+    writeVersion(db, undoId, "inquiries", version.rowId, row, restored, now);
+    db.raw()
+        .prepare("UPDATE inquiries SET conversations = ?, outcome = ?, archived = ?, touchedAt = ? WHERE id = ?")
+        .run(restored.conversations, restored.outcome ?? null, Number(restored.archived ?? 0), now, Number(version.rowId));
+    return "restored";
+}
+function undoEntityKey(db, version, undoId, now) {
+    const row = db
+        .raw()
+        .prepare("SELECT id, entityId, typeFamilyRoot, key, normalized FROM entity_keys WHERE id = ?")
+        .get(Number(version.rowId));
+    if (version.before !== null) {
+        // A re-root (retypeEntities / maintain): restore the old family
+        // root while the row still sits at the change's after root.
+        if (row === undefined)
+            return "unchanged";
+        const before = JSON.parse(version.before);
+        const after = JSON.parse(version.after ?? "null");
+        const differs = afterDiffersFromRow(after, row, ["typeFamilyRoot"]);
+        if (differs !== null)
+            return `entity_keys ${version.rowId}: ${differs}`;
+        writeVersion(db, undoId, "entity_keys", version.rowId, row, before, now);
+        db.raw()
+            .prepare("UPDATE entity_keys SET typeFamilyRoot = ? WHERE id = ?")
+            .run(before.typeFamilyRoot, Number(version.rowId));
+        return "restored";
+    }
+    // applyRecord only ever creates key rows; undo removes them.
+    if (row === undefined)
+        return "unchanged";
+    writeVersion(db, undoId, "entity_keys", version.rowId, row, null, now);
+    db.raw()
+        .prepare("DELETE FROM entity_keys WHERE id = ?")
+        .run(Number(version.rowId));
+    return "restored";
+}
+/**
+ * Undo a type version: a type the change created is archived (while the
+ * row still equals the creation blob); a type the change edited gets its
+ * parentId/fields/description back (while the row still equals the
+ * change's after). Edits from a later change to the same row block the
+ * revert; other rows are never consulted (a type's schema is its own
+ * row, so undoing a generalization after a child was extended reverts
+ * the child alone).
+ */
+function undoType(db, version, undoId, now) {
+    // Schema rows written by knowledge_record are shared schema and stay
+    // audit-only; only the idle pass's own hierarchy edits (change ids
+    // prefixed "maintain:") are reverted, so a generalization is
+    // undoable without record-applied types ever being rewritten.
+    if (!version.changeId.startsWith("maintain:")) {
+        return `type ${version.rowId}: type schema changes are not reverted`;
+    }
+    const row = db
+        .raw()
+        .prepare("SELECT id, name, description, parentId, fields, version, archived FROM types WHERE id = ?")
+        .get(Number(version.rowId));
+    if (row === undefined)
+        return "unchanged";
+    if (version.before === null) {
+        // Created by this change: archive it (schema rows are never
+        // deleted) while the row still equals the creation blob.
+        if (Number(row.archived) !== 0)
+            return "unchanged";
+        const afterCreate = JSON.parse(version.after ?? "null");
+        const differs = afterDiffersFromRow(afterCreate, row, [
+            "name",
+            "description",
+            "parentId",
+            "fields",
+        ]);
+        if (differs !== null) {
+            return `type "${String(row.name)}" (${version.rowId}): ${differs}`;
+        }
+        // A parent with live children still attached stays live: archiving
+        // it would orphan the hierarchy (the child revert was skipped
+        // because a later change edited that child).
+        const liveChildren = db
+            .raw()
+            .prepare("SELECT 1 AS x FROM types WHERE parentId = ? AND archived = 0 LIMIT 1")
+            .get(Number(version.rowId));
+        if (liveChildren !== undefined) {
+            return `type "${String(row.name)}" (${version.rowId}): live children still attached`;
+        }
+        writeVersion(db, undoId, "types", version.rowId, row, { ...row, archived: 1 }, now);
+        db.raw()
+            .prepare("UPDATE types SET archived = 1, version = version + 1 WHERE id = ?")
+            .run(Number(version.rowId));
+        return "restored";
+    }
+    const before = JSON.parse(version.before ?? "null");
+    const after = JSON.parse(version.after ?? "null");
+    const differs = afterDiffersFromRow(after, row, [
+        "name",
+        "description",
+        "parentId",
+        "fields",
+        "archived",
+    ]);
+    if (before === null || after === null || differs !== null) {
+        return `type "${String(row.name)}" (${version.rowId}): ${differs ?? "changed by a later change"}`;
+    }
+    const restoredRow = { ...row, ...before, id: row.id };
+    writeVersion(db, undoId, "types", version.rowId, row, restoredRow, now);
+    db.raw()
+        .prepare("UPDATE types SET description = ?, parentId = ?, fields = ?, archived = ?, version = version + 1 WHERE id = ?")
+        .run(restoredRow.description, restoredRow.parentId ?? null, restoredRow.fields, Number(restoredRow.archived ?? 0), Number(version.rowId));
+    return "restored";
+}

package/package.json

@@ -1,6 +1,59 @@
 {
-  "name": "@sigrun/knowledge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sigrun/knowledge",
+	"version": "0.1.2",
+	"description": "Curated per-user knowledge extension for sigrun (pi-durable)",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "node scripts/check-manifest.mjs --expect-name @sigrun/knowledge && vitest run",
+		"typecheck": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepare": "npm run build"
+	},
+	"peerDependencies": {
+		"@earendil-works/chord": "~1.5.0",
+		"@earendil-works/pi-ai": "~1.5.0",
+		"@earendil-works/pi-durable": "~1.5.0",
+		"@sigrun/shared": "0.5.0 || 0.6.0 || 0.6.1 || 0.7.0 || 0.8.0 || 0.9.0 || 0.10.0 || 0.10.1 || 0.11.0",
+		"typebox": "1.3.27"
+	},
+	"devDependencies": {
+		"@earendil-works/chord": "1.5.0",
+		"@earendil-works/pi-ai": "1.5.0",
+		"@earendil-works/pi-durable": "1.5.0",
+		"@sigrun/shared": "file:../sigrun/shared",
+		"@sigrun/sigrun": "file:../sigrun",
+		"@types/node": "^26.6.4",
+		"tsx": "^4.23.15",
+		"typebox": "1.3.27",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "github",
+		"url": "git+https://github.com/sigrun-ai/sigrun-knowledge.git"
+	},
+	"bugs": {
+		"url": "https://github.com/sigrun-ai/sigrun-knowledge/issues"
+	},
+	"homepage": "https://github.com/sigrun-ai/sigrun-knowledge#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	}
+}