@sigrun/knowledge 0.0.0-stage → 0.1.1

package/dist/card.js

@@ -0,0 +1,83 @@
+import { effectiveFields } from "./schema.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Parse an observedAt as a date-only string or a full ISO timestamp. */
+function parseObserved(observedAt) {
+    const dateOnly = /^\d{4}-\d{2}-\d{2}$/;
+    const parsed = Date.parse(dateOnly.test(observedAt) ? `${observedAt}T00:00:00Z` : observedAt);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function formatField(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.amount === "number") {
+        const money = value;
+        return `${money.amount} ${money.currency}`;
+    }
+    if (Array.isArray(value))
+        return value.map(formatField).join(", ");
+    return String(value);
+}
+/**
+ * Render the review card for one entity: title, one line per field with
+ * its observed date (and a stale mark past the field's horizon), the
+ * inquiries the entity has roles in, and the cited recall handles.
+ */
+export function renderCard(db, entityId, now) {
+    const row = db
+        .raw()
+        .prepare(`SELECT e.id, e.name, e.fields, e.typeId, t.name AS typeName
+			 FROM entities e JOIN types t ON t.id = e.typeId WHERE e.id = ?`)
+        .get(entityId);
+    if (row === undefined) {
+        throw new Error(`renderCard: unknown entity "${entityId}"`);
+    }
+    // Inherited fields carry their defs (horizonDays) down the hierarchy.
+    const typeRows = db
+        .raw()
+        .prepare("SELECT id, parentId, fields FROM types")
+        // SAFETY: the types table columns are fixed by db.ts's schema;
+        // node:sqlite types rows generically.
+        .all();
+    const typeFields = effectiveFields(new Map(typeRows.map((type) => [type.id, type])), row.typeId);
+    const fields = JSON.parse(row.fields);
+    const sources = new Set();
+    // The card body leads with the title line: recall indexes a doc's TEXT
+    // (never its title), so the type/entity name must appear here for the
+    // card to be findable by name.
+    const title = `${row.typeName} — ${row.name}`;
+    const lines = [title];
+    for (const [name, field] of Object.entries(fields)) {
+        sources.add(field.source);
+        const def = typeFields.find((candidate) => candidate.name === name);
+        // observedAt may be date-only or a full ISO timestamp: parse both
+        // for staleness, but always render the date part.
+        const observedMs = parseObserved(field.observedAt);
+        const observedDate = observedMs === null
+            ? field.observedAt
+            : new Date(observedMs).toISOString().slice(0, 10);
+        let observed = `observed ${observedDate}`;
+        if (def?.horizonDays !== undefined &&
+            observedMs !== null &&
+            now - observedMs > def.horizonDays * DAY_MS) {
+            observed += ", stale";
+        }
+        lines.push(`${name}: ${formatField(field.value)} (${observed})`);
+    }
+    const roles = db
+        .raw()
+        .prepare(`SELECT i.question AS question, r.role AS role, r.reason AS reason
+			FROM roles r JOIN inquiries i ON i.id = r.inquiryId
+			WHERE r.entityId = ? AND i.archived = 0 ORDER BY i.question`)
+        .all(entityId);
+    for (const role of roles) {
+        const reason = role.reason === null ? "" : ` — ${role.reason}`;
+        lines.push(`${role.question}: ${role.role}${reason}`);
+    }
+    return {
+        title,
+        text: lines.join("\n"),
+        date: new Date(now).toISOString(),
+        sources: [...sources],
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export interface SettingsReader {
+    get(): Promise<Record<string, unknown>>;
+}
+export interface UserKnowledgeSettings {
+    researchTools: readonly string[];
+}
+/** Test hook: clear the warn-once registry between tests. */
+export declare function resetWarnedForTests(): void;
+/**
+ * Match a tool name against a glob where `*` is the only wildcard and
+ * matches any run of characters (including none). Everything else in the
+ * pattern is literal.
+ */
+export declare function matchesGlob(pattern: string, name: string): boolean;
+export declare function resolveUserSettings(store: SettingsReader): Promise<UserKnowledgeSettings>;

package/dist/config.js

@@ -0,0 +1,44 @@
+const DEFAULT_RESEARCH_TOOLS = [
+    "*/search*",
+    "*/fetch*",
+    "*/crawl*",
+    "*/md",
+    "web_search",
+    "web_fetch",
+];
+function warnInvalid(setting) {
+    // Warn once per setting name: Task 10 resolves settings per tool call,
+    // so a misconfigured user must not spam the log on every call.
+    if (warned.has(setting))
+        return;
+    warned.add(setting);
+    console.warn(`knowledge: invalid ${setting} setting; using its default`);
+}
+const warned = new Set();
+/** Test hook: clear the warn-once registry between tests. */
+export function resetWarnedForTests() {
+    warned.clear();
+}
+/**
+ * Match a tool name against a glob where `*` is the only wildcard and
+ * matches any run of characters (including none). Everything else in the
+ * pattern is literal.
+ */
+export function matchesGlob(pattern, name) {
+    const source = pattern
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${source}$`).test(name);
+}
+export async function resolveUserSettings(store) {
+    const raw = await store.get();
+    if (raw.researchTools !== undefined) {
+        if (Array.isArray(raw.researchTools) &&
+            raw.researchTools.every((tool) => typeof tool === "string" && tool !== "")) {
+            return { researchTools: [...raw.researchTools] };
+        }
+        warnInvalid("researchTools");
+    }
+    return { researchTools: [...DEFAULT_RESEARCH_TOOLS] };
+}

package/dist/db.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseSync } from "node:sqlite";
+/**
+ * The per-user knowledge store. One database per directory user at
+ * join(host.stores.user(user).paths.data, "knowledge.db").
+ *
+ * `typeFamilyRoot` on entity_keys is the topmost ancestor type id, so
+ * identity keys de-duplicate across a type hierarchy.
+ */
+export declare class KnowledgeDb {
+    private readonly db;
+    private constructor();
+    static open(path: string): KnowledgeDb;
+    private migrate;
+    /** Raw handle for the scaffold; table accessors land with Task 9. */
+    raw(): DatabaseSync;
+    transaction<T>(fn: () => T): T;
+    close(): void;
+}

package/dist/db.js

@@ -0,0 +1,156 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const SCHEMA = `
+	CREATE TABLE IF NOT EXISTS types (
+		id INTEGER PRIMARY KEY,
+		name TEXT NOT NULL UNIQUE,
+		description TEXT NOT NULL,
+		parentId INTEGER REFERENCES types(id),
+		fields TEXT NOT NULL,
+		version INTEGER NOT NULL,
+		archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1))
+	);
+	CREATE TABLE IF NOT EXISTS entities (
+		id TEXT PRIMARY KEY,
+		typeId INTEGER NOT NULL REFERENCES types(id),
+		name TEXT NOT NULL,
+		keys TEXT NOT NULL DEFAULT '[]',
+		fields TEXT NOT NULL DEFAULT '{}',
+		attributes TEXT NOT NULL DEFAULT '{}',
+		cls TEXT NOT NULL DEFAULT 'normal' CHECK (cls IN ('normal', 'local-only')),
+		indexedAt INTEGER,
+		archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1))
+	);
+	CREATE TABLE IF NOT EXISTS entity_keys (
+		id INTEGER PRIMARY KEY,
+		entityId TEXT NOT NULL REFERENCES entities(id),
+		typeFamilyRoot INTEGER NOT NULL REFERENCES types(id),
+		key TEXT NOT NULL,
+		normalized TEXT NOT NULL,
+		UNIQUE (typeFamilyRoot, key, normalized)
+	);
+	CREATE TABLE IF NOT EXISTS inquiries (
+		id INTEGER PRIMARY KEY,
+		question TEXT NOT NULL,
+		why TEXT,
+		startedAt INTEGER NOT NULL,
+		touchedAt INTEGER NOT NULL,
+		conversations TEXT NOT NULL DEFAULT '[]',
+		outcome TEXT,
+		archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1))
+	);
+	CREATE TABLE IF NOT EXISTS roles (
+		id INTEGER PRIMARY KEY,
+		inquiryId INTEGER NOT NULL REFERENCES inquiries(id),
+		entityId TEXT NOT NULL REFERENCES entities(id),
+		role TEXT NOT NULL,
+		reason TEXT,
+		UNIQUE (inquiryId, entityId)
+	);
+	CREATE TABLE IF NOT EXISTS versions (
+		seq INTEGER PRIMARY KEY,
+		changeId TEXT NOT NULL,
+		"table" TEXT NOT NULL,
+		rowId TEXT NOT NULL,
+		before TEXT,
+		after TEXT,
+		at INTEGER NOT NULL
+	);
+	CREATE TABLE IF NOT EXISTS applied (
+		callId TEXT PRIMARY KEY,
+		changeId TEXT NOT NULL,
+		result TEXT NOT NULL
+	);
+	CREATE TABLE IF NOT EXISTS maintenance (
+		id INTEGER PRIMARY KEY,
+		kind TEXT NOT NULL,
+		changeId TEXT,
+		payload TEXT NOT NULL DEFAULT '{}',
+		cursor TEXT,
+		at INTEGER NOT NULL
+	);
+	CREATE TABLE IF NOT EXISTS schema_version (
+		version INTEGER NOT NULL
+	);
+`;
+const SCHEMA_VERSION = 2;
+/** Ordered migrations from version N to N+1 (index = from-version - 1). */
+const MIGRATIONS = {
+    // v2: inquiries gain `archived` — records are never deleted, only
+    // archived, and undo of an inquiry create needs somewhere to mark it.
+    1: "ALTER TABLE inquiries ADD COLUMN archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1))",
+};
+/**
+ * The per-user knowledge store. One database per directory user at
+ * join(host.stores.user(user).paths.data, "knowledge.db").
+ *
+ * `typeFamilyRoot` on entity_keys is the topmost ancestor type id, so
+ * identity keys de-duplicate across a type hierarchy.
+ */
+export class KnowledgeDb {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static open(path) {
+        if (path !== ":memory:")
+            mkdirSync(dirname(path), { recursive: true });
+        const db = new DatabaseSync(path);
+        try {
+            const opened = new KnowledgeDb(db);
+            opened.migrate();
+            return opened;
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    migrate() {
+        this.transaction(() => {
+            this.db.exec("CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)");
+            const current = this.db
+                .prepare("SELECT version FROM schema_version")
+                .get();
+            if (current === undefined) {
+                this.db.exec(SCHEMA);
+                this.db
+                    .prepare("INSERT INTO schema_version (version) VALUES (?)")
+                    .run(SCHEMA_VERSION);
+                return;
+            }
+            for (let version = current.version; version < SCHEMA_VERSION; version++) {
+                const migration = MIGRATIONS[version];
+                if (migration === undefined) {
+                    throw new Error(`knowledge: missing migration from schema v${version}`);
+                }
+                this.db.exec(migration);
+            }
+            if (current.version < SCHEMA_VERSION) {
+                this.db
+                    .prepare("UPDATE schema_version SET version = ?")
+                    .run(SCHEMA_VERSION);
+            }
+        });
+    }
+    /** Raw handle for the scaffold; table accessors land with Task 9. */
+    raw() {
+        return this.db;
+    }
+    transaction(fn) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = fn();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { SigrunExtensionResult, SigrunHost } from "@sigrun/sigrun/extension";
+import { KnowledgeDb } from "./db.js";
+export interface FactoryDeps {
+    openDb?: (path: string) => KnowledgeDb;
+    now?: () => number;
+}
+/**
+ * The loader injects the host only when factory.length > 0: keep the host
+ * bare and the optional test dependencies second, so the arity stays one.
+ */
+export default function createKnowledge(host: SigrunHost, deps?: FactoryDeps): SigrunExtensionResult;

package/dist/index.js

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { defineExtension, hook, ToolTask } from "@earendil-works/pi-durable";
+import { KnowledgeDb } from "./db.js";
+import { createTools } from "./tools.js";
+import { createTarget } from "./target.js";
+import { createResearch } from "./research.js";
+/**
+ * The loader injects the host only when factory.length > 0: keep the host
+ * bare and the optional test dependencies second, so the arity stays one.
+ */
+export default function createKnowledge(host, deps = {}) {
+    // One store per directory user, opened on first use. Core does not
+    // create paths.data; KnowledgeDb.open creates its parent.
+    const databases = new Map();
+    function dbForUser(user) {
+        let database = databases.get(user);
+        if (database === undefined) {
+            database = (deps.openDb ?? KnowledgeDb.open)(join(host.stores.user(user).paths.data, "knowledge.db"));
+            databases.set(user, database);
+        }
+        return database;
+    }
+    const now = deps.now ?? Date.now;
+    const tools = createTools({ host, dbForUser, now });
+    const target = createTarget({ host, dbForUser, now });
+    const researchFlag = createResearch({
+        conversationMeta: (id) => host.conversations.meta(id),
+        userStateDir: (user) => host.stores.user(user).paths.state,
+        userSettings: (user) => host.stores.user(user).settings.get(),
+        now,
+    });
+    const result = {
+        extension: defineExtension({
+            name: "@sigrun/knowledge",
+            tools,
+            hooks: [
+                hook(ToolTask, {
+                    afterTool: async (call, toolResult, api) => researchFlag(call, toolResult, api, undefined),
+                }),
+            ],
+        }),
+        dbForUser,
+        curationTargets: [target],
+        harnessShutdown: () => {
+            for (const database of databases.values()) {
+                database.close();
+            }
+            databases.clear();
+        },
+    };
+    return result;
+}

package/dist/maintain.d.ts

@@ -0,0 +1,21 @@
+import type { HandlerContext, MaintenanceBudget, MaintenanceReport } from "@sigrun/sigrun/extension";
+import type { KnowledgeDb } from "./db.js";
+import { type MirrorHost } from "./mirror.js";
+export interface MaintainDeps {
+    host: MirrorHost;
+    dbForUser(user: string): KnowledgeDb;
+    now(): number;
+}
+/** Jaccard similarity of two field-name sets. */
+export declare function jaccard(a: readonly string[], b: readonly string[]): number;
+/**
+ * The idle pass, in order, stopping at the deadline:
+ * 1. re-index up to 50 pending/stale entities (not reported);
+ * 2. continue an unfinished re-typing before proposing anything new;
+ * 3. propose one generalization via budget.run (needs runs >= 1);
+ * 4. apply it as a hierarchy in one change, folding field-less children
+ *    (<= 50 entities per pass; the rest continue next pass under the
+ *    same change id, reported with more: true).
+ * At most one generalization per pass.
+ */
+export declare function maintain(user: string, ctx: HandlerContext, budget: MaintenanceBudget, deps: MaintainDeps): Promise<MaintenanceReport>;