wyrm-mcp 7.3.2 → 7.3.3

package/dist/internal-dispatch.js

@@ -1,8 +1,217 @@
-import{sanitizeFtsQuery as k}from"./security.js";import{classifyCapture as _}from"./capture.js";function q(p){const{db:r,failures:i,symbols:a,rehydration:m,causality:u,presence:f,federation:j,memory:c,groundTruths:y}=p;return async(d,s)=>{try{switch(d){case"wyrm_search":{const e=String(s.query??s.q??"").slice(0,200);if(!e)return{ok:!1,error:"query required"};const t=k(e);return{ok:!0,result:r.getDatabase().prepare(`
+/**
+ * Internal tool dispatcher for the AgentLoop (v7 F4 T036 — extracted from the
+ * index.ts monolith). A curated subset of read-mostly + bounded-write tools the
+ * autonomous OODA loop is allowed to call; the whitelist itself is enforced in
+ * agent-loop.ts (SAFE_INTERNAL_TOOLS). Lifted VERBATIM out of index.ts behind a
+ * factory that captures the same subsystem singletons it always closed over —
+ * the single-quoted `case` labels here are what tests/tool-surface-integrity.ts
+ * scans to keep the whitelist and the dispatcher in lockstep.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+import { sanitizeFtsQuery } from "./security.js";
+import { classifyCapture } from "./capture.js";
+export function makeInternalDispatch(deps) {
+    const { db, failures, symbols, rehydration, causality, presence, federation, memory, groundTruths } = deps;
+    const internalDispatch = async (name, args) => {
+        try {
+            switch (name) {
+                case 'wyrm_search': {
+                    const q = String(args.query ?? args.q ?? '').slice(0, 200);
+                    if (!q)
+                        return { ok: false, error: 'query required' };
+                    const sanitized = sanitizeFtsQuery(q);
+                    const rows = db.getDatabase().prepare(`
           SELECT s.id, s.date, s.summary FROM sessions s
           JOIN sessions_fts fts ON fts.rowid = s.id
           WHERE sessions_fts MATCH ? LIMIT 10
-        `).all(t)}}case"wyrm_all_quests":return{ok:!0,result:r.getAllPendingQuests().slice(0,30)};case"wyrm_truth_get":{const e=s.projectPath,t=e?r.getProject(e):null;return{ok:!0,result:t?r.getDatabase().prepare(`
+        `).all(sanitized);
+                    return { ok: true, result: rows };
+                }
+                case 'wyrm_all_quests': {
+                    return { ok: true, result: db.getAllPendingQuests().slice(0, 30) };
+                }
+                case 'wyrm_truth_get': {
+                    const projPath = args.projectPath;
+                    const proj = projPath ? db.getProject(projPath) : null;
+                    const rows = proj
+                        ? db.getDatabase().prepare(`
               SELECT category, key, value, rationale FROM ground_truths
               WHERE project_id = ? AND is_current = 1 ORDER BY confidence DESC LIMIT 30
-            `).all(t.id):[]}}case"wyrm_failure_check":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:i.check(e.scope,e.target,e.description,t?.id??null)}}case"wyrm_failure_list":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:i.list(t?.id??null,Math.min(50,e.limit??20))}}case"wyrm_failure_record":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:i.record({project_id:t?.id??null,scope:e.scope,target:e.target,description:e.description,why_failed:e.why_failed,severity:e.severity})}}case"wyrm_symbol_search":{const e=s;if(!e.symbol)return{ok:!1,error:"symbol required"};const t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:a.search(e.symbol,{projectId:t?.id,kind:e.kind,language:e.language,exact:e.exact,limit:Math.min(50,e.limit??20)})}}case"wyrm_symbol_callers":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:a.callers(e.symbol,t?.id).slice(0,30)}}case"wyrm_symbol_stats":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:a.stats(t?.id)}}case"wyrm_session_rehydrate":{const e=s,t=m.rehydrate(e.session_id);return{ok:t!=null,result:t,error:t?void 0:"session not found"}}case"wyrm_decision_upstream":{const e=s;return{ok:!0,result:u.upstreamOf(e.kind,e.id)}}case"wyrm_decision_downstream":{const e=s;return{ok:!0,result:u.downstreamOf(e.kind,e.id)}}case"wyrm_decided_because":{const e=s,t=r.getProject(e.projectPath);return t?{ok:!0,result:u.link({project_id:t.id,...e})}:{ok:!1,error:"project not found"}}case"wyrm_presence_list":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return{ok:!0,result:f.liveAgents(t?.id??null)}}case"wyrm_sync_conflicts":return{ok:!0,result:j.unresolvedConflicts(20)};case"wyrm_quest_add":{const e=s,t=r.getProject(e.projectPath);if(!t)return{ok:!1,error:"project not found"};const o=r.addQuest(t.id,e.title,e.description,e.priority||"medium",e.tags);return{ok:!0,result:{id:o.id,title:o.title}}}case"wyrm_quest_complete":{const e=s;return{ok:!0,result:{id:r.updateQuest(e.questId,"completed").id,status:"completed"}}}case"wyrm_project_context":{const e=s,t=r.getProject(e.projectPath);return t?{ok:!0,result:{project:t.name,quests:r.getAllPendingQuests().filter(n=>n.project_id===t.id).slice(0,10),last_session:r.getDatabase().prepare("SELECT id, date, summary FROM sessions WHERE project_id = ? ORDER BY date DESC LIMIT 1").get(t.id)}}:{ok:!1,error:"project not found"}}case"wyrm_global_context":{const e=s,t=r.getAllProjects(e.maxProjects??20).map(n=>({name:n.name,stack:n.stack??null,stats:r.getProjectStats(n.id)})),o={globalContext:r.getAllGlobalContext(),projects:t};return e.includeQuests&&(o.quests=r.getAllPendingQuests().slice(0,20)),{ok:!0,result:o}}case"wyrm_recall":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;return t?e.query?{ok:!0,result:c.recall(t.id,e.query,{kind:e.kind,limit:Math.min(20,e.limit??10),minConfidence:e.minConfidence}).map(n=>({id:n.artifact.id,kind:n.artifact.kind,problem:n.artifact.problem,validated_fix:n.artifact.validated_fix,relevance:n.relevance_score}))}:{ok:!1,error:"query required"}:{ok:!1,error:"project not found"}}case"wyrm_remember":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;if(!t)return{ok:!1,error:"project not found"};if(!e.problem)return{ok:!1,error:"problem required"};const o=c.add(t.id,{kind:e.kind,problem:e.problem,constraints:e.constraints,validatedFix:e.validatedFix,whyItWorked:e.whyItWorked,outcome:e.outcome,tags:e.tags,confidence:e.confidence,sourceSessionId:e.sourceSessionId});return{ok:!0,result:{id:o.id,kind:o.kind}}}case"wyrm_distill":{const e=s,t=e.projectPath?r.getProject(e.projectPath):null;if(!t)return{ok:!1,error:"project not found"};if(!e.candidates?.length)return{ok:!1,error:"candidates required"};const o=e.candidates.map(n=>c.add(t.id,{kind:n.kind,problem:n.title,validatedFix:n.content,tags:n.tags??[],confidence:n.confidence??.7,needsReview:1}).id);return{ok:!0,result:{queued:o.length,ids:o}}}case"wyrm_capture":{const e=s;if(!e.content)return{ok:!1,error:"content required"};let t=_(e.content);if(e.mode&&e.mode!=="auto"){const l={quest:"quest",truth:"decision",memory:"pattern"};t={type:e.mode,subtype:l[e.mode]??e.mode,confidence:100,reasoning:`mode:${e.mode}`}}const o=e.project_id??null;return t.type==="quest"?o===null?{ok:!1,error:"project_id required for quest"}:{ok:!0,result:{type:"quest",id:r.addQuest(o,e.content.slice(0,200),"","medium",e.tags?.join(",")).id}}:t.type==="truth"?o===null?{ok:!1,error:"project_id required for truth"}:e.mode==="truth"||t.confidence>=100?{ok:!0,result:{type:"truth",id:y.set(o,{category:"decision",key:e.content.slice(0,60),value:e.content}).id}}:{ok:!0,result:{type:"memory_review",id:c.add(o,{kind:"pattern",problem:e.content,tags:e.tags??[],confidence:t.confidence/100,needsReview:1}).id}}:o===null?{ok:!1,error:"project_id required for memory"}:{ok:!0,result:{type:"memory",id:c.add(o,{kind:"pattern",problem:e.content,tags:e.tags??[],confidence:(t.confidence??70)/100,needsReview:1}).id}}}default:return{ok:!1,error:`Internal tool '${d}' not implemented in dispatcher`}}}catch(e){return{ok:!1,error:e.message}}}}export{q as makeInternalDispatch};
+            `).all(proj.id)
+                        : [];
+                    return { ok: true, result: rows };
+                }
+                case 'wyrm_failure_check': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: failures.check(a.scope, a.target, a.description, proj?.id ?? null) };
+                }
+                case 'wyrm_failure_list': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: failures.list(proj?.id ?? null, Math.min(50, a.limit ?? 20)) };
+                }
+                case 'wyrm_failure_record': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: failures.record({ project_id: proj?.id ?? null, scope: a.scope, target: a.target, description: a.description, why_failed: a.why_failed, severity: a.severity }) };
+                }
+                case 'wyrm_symbol_search': {
+                    const a = args;
+                    if (!a.symbol)
+                        return { ok: false, error: 'symbol required' };
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: symbols.search(a.symbol, { projectId: proj?.id, kind: a.kind, language: a.language, exact: a.exact, limit: Math.min(50, a.limit ?? 20) }) };
+                }
+                case 'wyrm_symbol_callers': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: symbols.callers(a.symbol, proj?.id).slice(0, 30) };
+                }
+                case 'wyrm_symbol_stats': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: symbols.stats(proj?.id) };
+                }
+                case 'wyrm_session_rehydrate': {
+                    const a = args;
+                    const brief = rehydration.rehydrate(a.session_id);
+                    return { ok: brief != null, result: brief, error: brief ? undefined : 'session not found' };
+                }
+                case 'wyrm_decision_upstream': {
+                    const a = args;
+                    return { ok: true, result: causality.upstreamOf(a.kind, a.id) };
+                }
+                case 'wyrm_decision_downstream': {
+                    const a = args;
+                    return { ok: true, result: causality.downstreamOf(a.kind, a.id) };
+                }
+                case 'wyrm_decided_because': {
+                    const a = args;
+                    const proj = db.getProject(a.projectPath);
+                    if (!proj)
+                        return { ok: false, error: 'project not found' };
+                    return { ok: true, result: causality.link({ project_id: proj.id, ...a }) };
+                }
+                case 'wyrm_presence_list': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    return { ok: true, result: presence.liveAgents(proj?.id ?? null) };
+                }
+                case 'wyrm_sync_conflicts': {
+                    return { ok: true, result: federation.unresolvedConflicts(20) };
+                }
+                case 'wyrm_quest_add': {
+                    const a = args;
+                    const proj = db.getProject(a.projectPath);
+                    if (!proj)
+                        return { ok: false, error: 'project not found' };
+                    const q = db.addQuest(proj.id, a.title, a.description, a.priority || 'medium', a.tags);
+                    return { ok: true, result: { id: q.id, title: q.title } };
+                }
+                case 'wyrm_quest_complete': {
+                    const a = args;
+                    const q = db.updateQuest(a.questId, 'completed');
+                    return { ok: true, result: { id: q.id, status: 'completed' } };
+                }
+                case 'wyrm_project_context': {
+                    const a = args;
+                    const proj = db.getProject(a.projectPath);
+                    if (!proj)
+                        return { ok: false, error: 'project not found' };
+                    // Summary: open quests + latest session
+                    const ctx = {
+                        project: proj.name,
+                        quests: db.getAllPendingQuests().filter(q => q.project_id === proj.id).slice(0, 10),
+                        last_session: db.getDatabase().prepare('SELECT id, date, summary FROM sessions WHERE project_id = ? ORDER BY date DESC LIMIT 1').get(proj.id),
+                    };
+                    return { ok: true, result: ctx };
+                }
+                // ── Memory ops the OODA loop is whitelisted for (SAFE_INTERNAL_TOOLS).
+                // These were promised by the whitelist but had no dispatch case until 6.8.1,
+                // so the loop silently failed on them. Kept in lockstep by
+                // tests/tool-surface-integrity.test.ts.
+                case 'wyrm_global_context': {
+                    const a = args;
+                    const projects = db.getAllProjects(a.maxProjects ?? 20).map((p) => ({
+                        name: p.name, stack: p.stack ?? null, stats: db.getProjectStats(p.id),
+                    }));
+                    const result = { globalContext: db.getAllGlobalContext(), projects };
+                    if (a.includeQuests)
+                        result.quests = db.getAllPendingQuests().slice(0, 20);
+                    return { ok: true, result };
+                }
+                case 'wyrm_recall': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    if (!proj)
+                        return { ok: false, error: 'project not found' };
+                    if (!a.query)
+                        return { ok: false, error: 'query required' };
+                    const results = memory.recall(proj.id, a.query, { kind: a.kind, limit: Math.min(20, a.limit ?? 10), minConfidence: a.minConfidence });
+                    return { ok: true, result: results.map((r) => ({ id: r.artifact.id, kind: r.artifact.kind, problem: r.artifact.problem, validated_fix: r.artifact.validated_fix, relevance: r.relevance_score })) };
+                }
+                case 'wyrm_remember': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    if (!proj)
+                        return { ok: false, error: 'project not found' };
+                    if (!a.problem)
+                        return { ok: false, error: 'problem required' };
+                    const art = memory.add(proj.id, { kind: a.kind, problem: a.problem, constraints: a.constraints, validatedFix: a.validatedFix, whyItWorked: a.whyItWorked, outcome: a.outcome, tags: a.tags, confidence: a.confidence, sourceSessionId: a.sourceSessionId });
+                    return { ok: true, result: { id: art.id, kind: art.kind } };
+                }
+                case 'wyrm_distill': {
+                    const a = args;
+                    const proj = a.projectPath ? db.getProject(a.projectPath) : null;
+                    if (!proj)
+                        return { ok: false, error: 'project not found' };
+                    if (!a.candidates?.length)
+                        return { ok: false, error: 'candidates required' };
+                    const ids = a.candidates.map((c) => memory.add(proj.id, { kind: c.kind, problem: c.title, validatedFix: c.content, tags: c.tags ?? [], confidence: c.confidence ?? 0.7, needsReview: 1 }).id);
+                    return { ok: true, result: { queued: ids.length, ids } };
+                }
+                case 'wyrm_capture': {
+                    const a = args;
+                    if (!a.content)
+                        return { ok: false, error: 'content required' };
+                    let cls = classifyCapture(a.content);
+                    if (a.mode && a.mode !== 'auto') {
+                        const sub = { quest: 'quest', truth: 'decision', memory: 'pattern' };
+                        cls = { type: a.mode, subtype: sub[a.mode] ?? a.mode, confidence: 100, reasoning: `mode:${a.mode}` };
+                    }
+                    const pid = a.project_id ?? null;
+                    if (cls.type === 'quest') {
+                        if (pid === null)
+                            return { ok: false, error: 'project_id required for quest' };
+                        const q = db.addQuest(pid, a.content.slice(0, 200), '', 'medium', a.tags?.join(','));
+                        return { ok: true, result: { type: 'quest', id: q.id } };
+                    }
+                    if (cls.type === 'truth') {
+                        if (pid === null)
+                            return { ok: false, error: 'project_id required for truth' };
+                        if (a.mode === 'truth' || cls.confidence >= 100) {
+                            const t = groundTruths.set(pid, { category: 'decision', key: a.content.slice(0, 60), value: a.content });
+                            return { ok: true, result: { type: 'truth', id: t.id } };
+                        }
+                        const art = memory.add(pid, { kind: 'pattern', problem: a.content, tags: a.tags ?? [], confidence: cls.confidence / 100, needsReview: 1 });
+                        return { ok: true, result: { type: 'memory_review', id: art.id } };
+                    }
+                    if (pid === null)
+                        return { ok: false, error: 'project_id required for memory' };
+                    const art = memory.add(pid, { kind: 'pattern', problem: a.content, tags: a.tags ?? [], confidence: (cls.confidence ?? 70) / 100, needsReview: 1 });
+                    return { ok: true, result: { type: 'memory', id: art.id } };
+                }
+                default:
+                    return { ok: false, error: `Internal tool '${name}' not implemented in dispatcher` };
+            }
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    };
+    return internalDispatch;
+}
+//# sourceMappingURL=internal-dispatch.js.map

package/dist/keyset.js

@@ -1 +1,110 @@
-const a=50,m=200;function S(t,n={}){const r=n.defaultSize??50,e=n.maxSize??200;return t==null||!Number.isFinite(t)||t<=0?Math.min(r,e):Math.min(Math.floor(t),e)}function c(t){const n=String(t.sortKey),r=`${n.length}.${n}:${t.id}`;return Buffer.from(r,"utf8").toString("base64url")}function g(t){if(typeof t!="string"||t.length===0)return null;let n;try{n=Buffer.from(t,"base64url").toString("utf8")}catch{return null}const r=n.indexOf(".");if(r<=0)return null;const e=n.slice(0,r);if(!/^\d{1,9}$/.test(e))return null;const l=Number(e),u=n.slice(r+1);if(u.length<l+1)return null;const s=u.slice(0,l);if(u.charAt(l)!==":")return null;const o=u.slice(l+1);if(!/^\d{1,15}$/.test(o))return null;const i=Number(o);return!Number.isSafeInteger(i)||i<0?null:{sortKey:s,id:i}}function d(t,n,r){if(t.length<=n)return{items:t};const e=t.slice(0,n),l=e[e.length-1];return{items:e,nextCursor:c(r(l))}}export{a as DEFAULT_PAGE_SIZE,m as MAX_PAGE_SIZE,d as buildPage,S as clampPageSize,g as decodeCursor,c as encodeCursor};
+/**
+ * Keyset (cursor) pagination — the v7 F4 T035 context-economy primitive.
+ *
+ * THE MOVE: a big listing returns a PAGE plus an opaque `nextCursor`, not the
+ * whole table. The cursor is a COMPOSITE `(sortKey, id)` — never a bare
+ * sortKey. This is deliberate: the wyrm-cloud sync keyset bug (fixed at
+ * cloud/client.ts:299 with a `"<updated_at>:<id>"` composite) is the
+ * cautionary tale — a bare `sortKey` cursor SILENTLY DROPS every row that
+ * shares the boundary row's sort value (e.g. three artifacts with identical
+ * `confidence` straddling a page edge). The id tiebreak makes the keyset
+ * total-ordered, so `(sortKey, id) > (lastSortKey, lastId)` resumes EXACTLY
+ * after the last emitted row, dropping nothing and repeating nothing.
+ *
+ * The cursor is OPAQUE on the wire: a base64url-encoded `"<sortKey>:<id>"`
+ * string. Callers MUST treat it as a token (round-trip it verbatim); they
+ * never parse it. A malformed/garbage cursor decodes to `null` and the caller
+ * degrades to "start from the first page" (never throws on the wire — a
+ * resource-less or buggy client can't be wedged by a bad token).
+ *
+ * Article III: pure, deterministic, no network, no clock, no LLM. Same rows in
+ * ⇒ same page + same cursor out. Article VII: hard default + max caps so an
+ * unbounded `limit` can never be requested; the encode/decode is total (no
+ * throw on adversarial input).
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+/** Default page size when a caller passes no `limit`. */
+export const DEFAULT_PAGE_SIZE = 50;
+/** Absolute ceiling on a single page — a caller can never exceed this. */
+export const MAX_PAGE_SIZE = 200;
+/**
+ * Clamp a requested limit into `[1, MAX_PAGE_SIZE]`, defaulting to
+ * `DEFAULT_PAGE_SIZE` when absent/NaN/≤0. The hard cap holds regardless of
+ * what the caller asks for (Article VII: bounded by construction).
+ */
+export function clampPageSize(requested, opts = {}) {
+    const def = opts.defaultSize ?? DEFAULT_PAGE_SIZE;
+    const max = opts.maxSize ?? MAX_PAGE_SIZE;
+    if (requested == null || !Number.isFinite(requested) || requested <= 0)
+        return Math.min(def, max);
+    return Math.min(Math.floor(requested), max);
+}
+/**
+ * Encode a composite `(sortKey, id)` anchor into an opaque base64url token.
+ * The sortKey is length-prefixed (`<len>.<sortKey>:<id>`) so a sortKey that
+ * itself contains a `:` (e.g. an ISO timestamp `2026-06-13T10:00:00`) round-
+ * trips losslessly — decode reads exactly `<len>` chars for the sortKey.
+ */
+export function encodeCursor(cursor) {
+    const sk = String(cursor.sortKey);
+    const raw = `${sk.length}.${sk}:${cursor.id}`;
+    return Buffer.from(raw, 'utf8').toString('base64url');
+}
+/**
+ * Decode an opaque cursor token back into `(sortKey, id)`. Returns `null` for
+ * any malformed/garbage/empty token — the caller degrades to the first page
+ * rather than throwing on the wire (Article VII: total on adversarial input).
+ */
+export function decodeCursor(token) {
+    if (typeof token !== 'string' || token.length === 0)
+        return null;
+    let raw;
+    try {
+        raw = Buffer.from(token, 'base64url').toString('utf8');
+    }
+    catch {
+        return null;
+    }
+    // Grammar: <len>.<sortKey(len chars)>:<id>
+    const dot = raw.indexOf('.');
+    if (dot <= 0)
+        return null;
+    const lenStr = raw.slice(0, dot);
+    if (!/^\d{1,9}$/.test(lenStr))
+        return null;
+    const len = Number(lenStr);
+    const after = raw.slice(dot + 1);
+    if (after.length < len + 1)
+        return null;
+    const sortKey = after.slice(0, len);
+    const sep = after.charAt(len);
+    if (sep !== ':')
+        return null;
+    const idStr = after.slice(len + 1);
+    if (!/^\d{1,15}$/.test(idStr))
+        return null;
+    const id = Number(idStr);
+    if (!Number.isSafeInteger(id) || id < 0)
+        return null;
+    return { sortKey, id };
+}
+/**
+ * Build a page from an OVER-FETCHED row array. Call the underlying query with
+ * `limit = pageSize + 1`; pass the result here. If `pageSize + 1` rows came
+ * back there is a further page: slice to `pageSize` and mint a `nextCursor`
+ * from the LAST emitted row via `anchorOf`. The over-fetch-by-one is how we
+ * know "is there more" without a second COUNT query.
+ *
+ * `anchorOf` must return the SAME `(sortKey, id)` the query's WHERE/ORDER use,
+ * or pages will skip/repeat. Keep them in lockstep at the call site.
+ */
+export function buildPage(rows, pageSize, anchorOf) {
+    if (rows.length <= pageSize)
+        return { items: rows };
+    const items = rows.slice(0, pageSize);
+    const last = items[items.length - 1];
+    return { items, nextCursor: encodeCursor(anchorOf(last)) };
+}
+//# sourceMappingURL=keyset.js.map

package/dist/knowledge-graph.js

@@ -1,31 +1,139 @@
-const p=5,_=200;class l{db;constructor(t){this.db=t}addEntity(t,e,i,n,r){const s=this.db.prepare(`
+/**
+ * Wyrm Knowledge Graph — Entity & Relationship Management
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ *
+ * Manual-first knowledge graph with provenance tracking:
+ * - Named entities with types and metadata
+ * - Typed, directed relationships between entities
+ * - Aliases for deduplication
+ * - Graph traversal via recursive CTEs (neighborhood, paths)
+ * - FTS5 search on entity names
+ */
+const MAX_DEPTH = 5;
+const MAX_RESULTS = 200;
+/**
+ * Knowledge graph operations backed by SQLite.
+ */
+export class KnowledgeGraph {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ==================== ENTITIES ====================
+    addEntity(projectId, name, type, metadata, createdBy) {
+        const result = this.db.prepare(`
       INSERT INTO entities (project_id, name, type, metadata, created_by)
       VALUES (?, ?, ?, ?, ?)
-    `).run(t,e.trim(),i.trim(),n??null,r??"local");return this.db.prepare("SELECT * FROM entities WHERE id = ?").get(s.lastInsertRowid)}getEntity(t){return this.db.prepare("SELECT * FROM entities WHERE id = ?").get(t)??null}findEntity(t,e,i){return i?this.db.prepare("SELECT * FROM entities WHERE project_id = ? AND name = ? AND type = ?").get(t,e,i)??null:this.db.prepare("SELECT * FROM entities WHERE project_id = ? AND name = ?").get(t,e)??null}updateEntity(t,e){return this.getEntity(t)?(this.db.prepare(`
+    `).run(projectId, name.trim(), type.trim(), metadata ?? null, createdBy ?? 'local');
+        return this.db.prepare('SELECT * FROM entities WHERE id = ?').get(result.lastInsertRowid);
+    }
+    getEntity(id) {
+        return this.db.prepare('SELECT * FROM entities WHERE id = ?').get(id) ?? null;
+    }
+    findEntity(projectId, name, type) {
+        if (type) {
+            return this.db.prepare('SELECT * FROM entities WHERE project_id = ? AND name = ? AND type = ?').get(projectId, name, type) ?? null;
+        }
+        return this.db.prepare('SELECT * FROM entities WHERE project_id = ? AND name = ?').get(projectId, name) ?? null;
+    }
+    updateEntity(id, updates) {
+        const entity = this.getEntity(id);
+        if (!entity)
+            return null;
+        this.db.prepare(`
       UPDATE entities SET
         name = COALESCE(?, name),
         type = COALESCE(?, type),
         metadata = COALESCE(?, metadata),
         updated_at = datetime('now')
       WHERE id = ?
-    `).run(e.name??null,e.type??null,e.metadata??null,t),this.getEntity(t)):null}deleteEntity(t){return this.db.prepare("DELETE FROM entities WHERE id = ?").run(t).changes>0}listEntities(t,e){let i="SELECT * FROM entities WHERE project_id = ?";const n=[t];return e?.type&&(i+=" AND type = ?",n.push(e.type)),i+=" ORDER BY name ASC",i+=" LIMIT ? OFFSET ?",n.push(e?.limit??50,e?.offset??0),this.db.prepare(i).all(...n)}searchEntities(t,e,i=20){try{const n=this.db.prepare(`
+    `).run(updates.name ?? null, updates.type ?? null, updates.metadata ?? null, id);
+        return this.getEntity(id);
+    }
+    deleteEntity(id) {
+        const result = this.db.prepare('DELETE FROM entities WHERE id = ?').run(id);
+        return result.changes > 0;
+    }
+    listEntities(projectId, options) {
+        let sql = 'SELECT * FROM entities WHERE project_id = ?';
+        const params = [projectId];
+        if (options?.type) {
+            sql += ' AND type = ?';
+            params.push(options.type);
+        }
+        sql += ' ORDER BY name ASC';
+        sql += ` LIMIT ? OFFSET ?`;
+        params.push(options?.limit ?? 50, options?.offset ?? 0);
+        return this.db.prepare(sql).all(...params);
+    }
+    searchEntities(projectId, query, limit = 20) {
+        // Try FTS first, fall back to LIKE
+        try {
+            const ftsResults = this.db.prepare(`
         SELECT e.* FROM entities e
         JOIN entities_fts f ON f.rowid = e.id
         WHERE f.entities_fts MATCH ? AND e.project_id = ?
         LIMIT ?
-      `).all(e,t,i);if(n.length>0)return n}catch{}return this.db.prepare(`
+      `).all(query, projectId, limit);
+            if (ftsResults.length > 0)
+                return ftsResults;
+        }
+        catch {
+            // FTS query syntax error — fall back to LIKE
+        }
+        return this.db.prepare(`
       SELECT * FROM entities WHERE project_id = ? AND (name LIKE ? OR type LIKE ?)
       ORDER BY name ASC LIMIT ?
-    `).all(t,`%${e}%`,`%${e}%`,i)}addAlias(t,e){this.db.prepare("INSERT OR IGNORE INTO entity_aliases (entity_id, alias) VALUES (?, ?)").run(t,e.trim())}getAliases(t){return this.db.prepare("SELECT alias FROM entity_aliases WHERE entity_id = ?").all(t).map(i=>i.alias)}findByAlias(t,e){return this.db.prepare(`
+    `).all(projectId, `%${query}%`, `%${query}%`, limit);
+    }
+    // ==================== ALIASES ====================
+    addAlias(entityId, alias) {
+        this.db.prepare('INSERT OR IGNORE INTO entity_aliases (entity_id, alias) VALUES (?, ?)').run(entityId, alias.trim());
+    }
+    getAliases(entityId) {
+        const rows = this.db.prepare('SELECT alias FROM entity_aliases WHERE entity_id = ?').all(entityId);
+        return rows.map(r => r.alias);
+    }
+    findByAlias(projectId, alias) {
+        return this.db.prepare(`
       SELECT e.* FROM entities e
       JOIN entity_aliases a ON a.entity_id = e.id
       WHERE e.project_id = ? AND a.alias = ?
-    `).get(t,e)??null}addRelationship(t,e,i,n,r){const s=this.db.prepare(`
+    `).get(projectId, alias) ?? null;
+    }
+    // ==================== RELATIONSHIPS ====================
+    addRelationship(projectId, sourceId, targetId, type, options) {
+        const result = this.db.prepare(`
       INSERT INTO relationships (
         project_id, source_entity_id, target_entity_id, relationship_type,
         weight, confidence, source_memory, extraction_method, metadata, created_by
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(t,e,i,n.trim(),r?.weight??1,r?.confidence??1,r?.sourceMemory??null,r?.extractionMethod??"manual",r?.metadata??null,r?.createdBy??"local");return this.db.prepare("SELECT * FROM relationships WHERE id = ?").get(s.lastInsertRowid)}getRelationships(t,e="both"){switch(e){case"outgoing":return this.db.prepare("SELECT * FROM relationships WHERE source_entity_id = ?").all(t);case"incoming":return this.db.prepare("SELECT * FROM relationships WHERE target_entity_id = ?").all(t);case"both":return this.db.prepare("SELECT * FROM relationships WHERE source_entity_id = ? OR target_entity_id = ?").all(t,t)}}deleteRelationship(t){return this.db.prepare("DELETE FROM relationships WHERE id = ?").run(t).changes>0}getNeighborhood(t,e=2){const i=Math.min(e,5),n=this.db.prepare(`
+    `).run(projectId, sourceId, targetId, type.trim(), options?.weight ?? 1.0, options?.confidence ?? 1.0, options?.sourceMemory ?? null, options?.extractionMethod ?? 'manual', options?.metadata ?? null, options?.createdBy ?? 'local');
+        return this.db.prepare('SELECT * FROM relationships WHERE id = ?').get(result.lastInsertRowid);
+    }
+    getRelationships(entityId, direction = 'both') {
+        switch (direction) {
+            case 'outgoing':
+                return this.db.prepare('SELECT * FROM relationships WHERE source_entity_id = ?').all(entityId);
+            case 'incoming':
+                return this.db.prepare('SELECT * FROM relationships WHERE target_entity_id = ?').all(entityId);
+            case 'both':
+                return this.db.prepare('SELECT * FROM relationships WHERE source_entity_id = ? OR target_entity_id = ?').all(entityId, entityId);
+        }
+    }
+    deleteRelationship(id) {
+        return this.db.prepare('DELETE FROM relationships WHERE id = ?').run(id).changes > 0;
+    }
+    // ==================== GRAPH QUERIES ====================
+    /**
+     * Get neighborhood — all nodes within N hops of a given entity.
+     * Uses recursive CTE with cycle detection.
+     */
+    getNeighborhood(entityId, maxDepth = 2) {
+        const depth = Math.min(maxDepth, MAX_DEPTH);
+        const nodes = this.db.prepare(`
       WITH RECURSIVE neighbors(id, depth, visited) AS (
         SELECT ?, 0, ',' || ? || ','
         UNION ALL
@@ -44,16 +152,31 @@ const p=5,_=200;class l{db;constructor(t){this.db=t}addEntity(t,e,i,n,r){const s
       GROUP BY e.id
       ORDER BY depth ASC
       LIMIT ?
-    `).all(t,t,i,200),r=n.map(a=>a.id);if(r.length===0)return{nodes:[],edges:[]};const s=r.map(()=>"?").join(","),E=this.db.prepare(`
+    `).all(entityId, entityId, depth, MAX_RESULTS);
+        // Get edges between all discovered nodes
+        const nodeIds = nodes.map(n => n.id);
+        if (nodeIds.length === 0)
+            return { nodes: [], edges: [] };
+        const placeholders = nodeIds.map(() => '?').join(',');
+        const edges = this.db.prepare(`
       SELECT r.source_entity_id as source_id, s.name as source_name,
              r.target_entity_id as target_id, t.name as target_name,
              r.relationship_type, r.weight
       FROM relationships r
       JOIN entities s ON s.id = r.source_entity_id
       JOIN entities t ON t.id = r.target_entity_id
-      WHERE r.source_entity_id IN (${s})
-        AND r.target_entity_id IN (${s})
-    `).all(...r,...r);return{nodes:n,edges:E}}findPath(t,e,i=5){const n=Math.min(i,5),r=this.db.prepare(`
+      WHERE r.source_entity_id IN (${placeholders})
+        AND r.target_entity_id IN (${placeholders})
+    `).all(...nodeIds, ...nodeIds);
+        return { nodes, edges };
+    }
+    /**
+     * Find path between two entities using BFS with cycle detection.
+     * Returns the shortest path as a list of entity IDs, or null if no path exists.
+     */
+    findPath(sourceId, targetId, maxDepth = 5) {
+        const depth = Math.min(maxDepth, MAX_DEPTH);
+        const rows = this.db.prepare(`
       WITH RECURSIVE path_finder(id, path, depth) AS (
         SELECT ?, CAST(? AS TEXT), 0
         UNION ALL
@@ -68,4 +191,45 @@ const p=5,_=200;class l{db;constructor(t){this.db=t}addEntity(t,e,i,n,r){const s
           AND INSTR(',' || pf.path || ',', ',' || CASE WHEN r.source_entity_id = pf.id THEN r.target_entity_id ELSE r.source_entity_id END || ',') = 0
       )
       SELECT path FROM path_finder WHERE id = ? LIMIT 1
-    `).all(t,t,n,e);return r.length===0?null:r[0].path.split(",").map(Number)}mergeEntities(t,e){const i=this.getEntity(t),n=this.getEntity(e);return!i||!n?null:(this.db.transaction(()=>{this.addAlias(e,i.name),this.db.prepare("UPDATE entity_aliases SET entity_id = ? WHERE entity_id = ?").run(e,t),this.db.prepare("UPDATE relationships SET source_entity_id = ? WHERE source_entity_id = ?").run(e,t),this.db.prepare("UPDATE relationships SET target_entity_id = ? WHERE target_entity_id = ?").run(e,t),this.db.prepare("DELETE FROM relationships WHERE source_entity_id = target_entity_id").run(),this.deleteEntity(t)})(),this.getEntity(e))}getStats(t){const e=this.db.prepare("SELECT COUNT(*) as c FROM entities WHERE project_id = ?").get(t).c,i=this.db.prepare("SELECT COUNT(*) as c FROM relationships WHERE project_id = ?").get(t).c,n=this.db.prepare("SELECT type, COUNT(*) as cnt FROM entities WHERE project_id = ? GROUP BY type").all(t),r={};for(const s of n)r[s.type]=s.cnt;return{entities:e,relationships:i,entityTypes:r}}}export{l as KnowledgeGraph};
+    `).all(sourceId, sourceId, depth, targetId);
+        if (rows.length === 0)
+            return null;
+        return rows[0].path.split(',').map(Number);
+    }
+    /**
+     * Merge two entities: moves all relationships and aliases from source to target,
+     * adds source name as alias on target, then deletes source.
+     */
+    mergeEntities(sourceId, targetId) {
+        const source = this.getEntity(sourceId);
+        const target = this.getEntity(targetId);
+        if (!source || !target)
+            return null;
+        const merge = this.db.transaction(() => {
+            // Add source name as alias on target
+            this.addAlias(targetId, source.name);
+            // Move source's aliases to target
+            this.db.prepare('UPDATE entity_aliases SET entity_id = ? WHERE entity_id = ?').run(targetId, sourceId);
+            // Redirect relationships from source to target
+            this.db.prepare('UPDATE relationships SET source_entity_id = ? WHERE source_entity_id = ?').run(targetId, sourceId);
+            this.db.prepare('UPDATE relationships SET target_entity_id = ? WHERE target_entity_id = ?').run(targetId, sourceId);
+            // Remove self-loops created by merge
+            this.db.prepare('DELETE FROM relationships WHERE source_entity_id = target_entity_id').run();
+            // Delete source entity
+            this.deleteEntity(sourceId);
+        });
+        merge();
+        return this.getEntity(targetId);
+    }
+    // ==================== STATS ====================
+    getStats(projectId) {
+        const entities = this.db.prepare('SELECT COUNT(*) as c FROM entities WHERE project_id = ?').get(projectId).c;
+        const relationships = this.db.prepare('SELECT COUNT(*) as c FROM relationships WHERE project_id = ?').get(projectId).c;
+        const typeRows = this.db.prepare('SELECT type, COUNT(*) as cnt FROM entities WHERE project_id = ? GROUP BY type').all(projectId);
+        const entityTypes = {};
+        for (const r of typeRows)
+            entityTypes[r.type] = r.cnt;
+        return { entities, relationships, entityTypes };
+    }
+}
+//# sourceMappingURL=knowledge-graph.js.map