@revealui/mcp 0.8.9 → 0.8.10

package/dist/servers/factories/knowledge-graph.js

@@ -32,12 +32,20 @@
  * reserved for `revkg scan`), Zod-validates `episodeType` plus every node kind
  * and edge relation against the ontology enums, and accepts no raw SQL or
  * table-name input of any kind.
+ *
+ * Product mode (`mode: 'product'`) extracts `createKnowledgeGraphToolset` so
+ * stdio and a later hosted composite share one dispatcher. CallTool threads
+ * `extra.authInfo` / `extra.sessionId`. Writes stamp actor + scope from
+ * `principalProvider` (client `source` / `contentRef.actorDid` are ignored).
+ * Compat mode (default) keeps today's unwrapped JSON for in-repo tests.
  */
+import { createHash } from 'node:crypto';
 import { hostname } from 'node:os';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { EDGE_RELATIONS, EPISODE_TYPES, ingestEpisode, kgAtTime, kgNeighbors, kgPath, kgSearch, makePoolExecutor, NODE_KINDS, } from '@revealui/knowledge-graph';
+import { assembleContext, EDGE_RELATIONS, EPISODE_TYPES, ingestEpisode, kgAtTime, kgNeighbors, kgPath, kgSearch, makePoolExecutor, NODE_KINDS, } from '@revealui/knowledge-graph';
 import { resolveNaturalKey } from '@revealui/knowledge-graph/ingest';
+import { countDeniedMemoryHits, inspectNodeVisibility, MEMORY_MAX_CONTENT_CHARS, MEMORY_MAX_EDGES, MEMORY_MAX_NODES, MEMORY_SCHEMA, shouldNamespaceKeys, tenantNaturalKey, validatePrincipal, } from '@revealui/knowledge-graph/memory';
 import { z } from 'zod/v4';
 import { validateToolArgs } from '../../validate-tool-args.js';
 const SERVER_NAME = 'knowledge-graph';
@@ -47,6 +55,11 @@ const DEFAULT_CONTEXT_CHAR_BUDGET = 16_000;
 /** Hard caps for kg_add_episode payloads (prevents unbounded Neon writes). */
 const MAX_EPISODE_CONTENT_CHARS = 64_000;
 const MAX_EPISODE_ATTRIBUTES_JSON_CHARS = 16_000;
+/** Product-mode write types. Compat still accepts the full ontology enum. */
+const PRODUCT_EPISODE_TYPES = ['agent-fact', 'memory', 'manual'];
+/** Dispatch Promise.race budget. Hung writes must not block the agent. */
+export const DEFAULT_KG_TOOL_TIMEOUT_MS = 4_000;
+const DEFAULT_MUTATING_TOOLS = new Set(['kg_add_episode']);
 // ---------------------------------------------------------------------------
 // Tool argument schemas (Zod 4)
 // ---------------------------------------------------------------------------
@@ -102,22 +115,7 @@ const EdgeInputArgsSchema = z
     attributes: z.record(z.string(), z.unknown()).optional(),
 })
     .strict();
-export const KgAddEpisodeArgsSchema = z
-    .object({
-    episodeType: z.enum(EPISODE_TYPES),
-    source: z.string().min(1),
-    content: z
-        .string()
-        .max(MAX_EPISODE_CONTENT_CHARS, `content max ${MAX_EPISODE_CONTENT_CHARS} chars`)
-        .optional(),
-    contentRef: z.record(z.string(), z.unknown()).optional(),
-    referenceTime: z.string().datetime().optional(),
-    siteId: z.string().min(1).optional(),
-    nodes: z.array(NodeInputArgsSchema).default([]),
-    edges: z.array(EdgeInputArgsSchema).default([]),
-})
-    .strict()
-    .superRefine((val, ctx) => {
+function refineEpisodeJsonCaps(val, ctx) {
     if (val.contentRef) {
         const size = JSON.stringify(val.contentRef).length;
         if (size > MAX_EPISODE_ATTRIBUTES_JSON_CHARS) {
@@ -154,7 +152,41 @@ export const KgAddEpisodeArgsSchema = z
             });
         }
     }
-});
+}
+export const KgAddEpisodeArgsSchema = z
+    .object({
+    episodeType: z.enum(EPISODE_TYPES),
+    source: z.string().min(1),
+    content: z
+        .string()
+        .max(MAX_EPISODE_CONTENT_CHARS, `content max ${MAX_EPISODE_CONTENT_CHARS} chars`)
+        .optional(),
+    contentRef: z.record(z.string(), z.unknown()).optional(),
+    referenceTime: z.string().datetime().optional(),
+    siteId: z.string().min(1).optional(),
+    nodes: z.array(NodeInputArgsSchema).default([]),
+    edges: z.array(EdgeInputArgsSchema).default([]),
+})
+    .strict()
+    .superRefine(refineEpisodeJsonCaps);
+export const KgProductAddEpisodeArgsSchema = z
+    .object({
+    episodeType: z.enum(PRODUCT_EPISODE_TYPES),
+    /** Ignored; stamped from `principalProvider`. */
+    source: z.string().min(1).optional(),
+    content: z
+        .string()
+        .max(MEMORY_MAX_CONTENT_CHARS, `content max ${MEMORY_MAX_CONTENT_CHARS} chars`)
+        .optional(),
+    contentRef: z.record(z.string(), z.unknown()).optional(),
+    classification: z.enum(['private', 'workspace']).optional(),
+    referenceTime: z.string().datetime().optional(),
+    siteId: z.string().min(1).optional(),
+    nodes: z.array(NodeInputArgsSchema).max(MEMORY_MAX_NODES).default([]),
+    edges: z.array(EdgeInputArgsSchema).max(MEMORY_MAX_EDGES).default([]),
+})
+    .strict()
+    .superRefine(refineEpisodeJsonCaps);
 export const KgPathArgsSchema = z
     .object({
     fromNaturalKey: z.string().min(1),
@@ -368,6 +400,86 @@ const TOOLS = [
         },
     },
 ];
+function productAddEpisodeTool() {
+    return {
+        name: 'kg_add_episode',
+        description: 'Publish an episode (provenance unit) plus candidate nodes/edges into the ' +
+            'graph. The ONLY write tool. Always additive (never a rescan). Product ' +
+            'mode stamps actor and scope from the session principal — client `source` ' +
+            'and `contentRef.actorDid` are ignored. episodeType is agent-fact, memory, ' +
+            'or manual.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                episodeType: { type: 'string', enum: [...PRODUCT_EPISODE_TYPES] },
+                source: {
+                    type: 'string',
+                    description: 'Ignored in product mode; stamped from the session principal.',
+                },
+                content: {
+                    type: 'string',
+                    description: `Raw payload or pointer summary (max ${MEMORY_MAX_CONTENT_CHARS} chars).`,
+                },
+                contentRef: {
+                    type: 'object',
+                    description: 'e.g. { repo, path, sha }. actorDid is ignored.',
+                },
+                classification: {
+                    type: 'string',
+                    enum: ['private', 'workspace'],
+                    description: 'Memory classification. Default workspace. public is not allowed.',
+                },
+                referenceTime: {
+                    type: 'string',
+                    description: 'ISO-8601; when the described state was true. Defaults to now.',
+                },
+                siteId: {
+                    type: 'string',
+                    description: 'Origin machine/replica id. Defaults to hostname().',
+                },
+                nodes: {
+                    type: 'array',
+                    description: `Candidate nodes to upsert (max ${MEMORY_MAX_NODES}).`,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', enum: NODE_KIND_ENUM },
+                            name: { type: 'string' },
+                            naturalKey: { type: 'string' },
+                            repo: { type: 'string' },
+                            summary: { type: 'string' },
+                            attributes: { type: 'object' },
+                        },
+                        required: ['kind', 'name', 'naturalKey'],
+                    },
+                },
+                edges: {
+                    type: 'array',
+                    description: `Candidate facts between nodes (max ${MEMORY_MAX_EDGES}).`,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            source: NODE_REF_SCHEMA,
+                            target: NODE_REF_SCHEMA,
+                            relation: { type: 'string', enum: EDGE_RELATION_ENUM },
+                            fact: { type: 'string' },
+                            repo: { type: 'string' },
+                            validAt: { type: 'string', description: 'ISO-8601; defaults to referenceTime.' },
+                            attributes: { type: 'object' },
+                        },
+                        required: ['source', 'target', 'relation', 'fact'],
+                    },
+                },
+            },
+            required: ['episodeType'],
+        },
+    };
+}
+function toolsForMode(mode) {
+    if (mode === 'compat')
+        return TOOLS;
+    return TOOLS.map((tool) => (tool.name === 'kg_add_episode' ? productAddEpisodeTool() : tool));
+}
 // ---------------------------------------------------------------------------
 // Result helpers
 // ---------------------------------------------------------------------------
@@ -382,106 +494,140 @@ function errorResult(message) {
         isError: true,
     };
 }
-async function assembleContext(exec, anchorId, opts) {
-    const neighbors = await kgNeighbors(exec, anchorId, { depth: opts.depth, at: opts.at });
-    const nodeIds = neighbors.nodes.map((n) => n.id);
-    const summaryRows = nodeIds.length
-        ? await exec.query(`SELECT id, summary FROM kg_nodes WHERE id = ANY($1::text[])`, [nodeIds])
-        : [];
-    const summaryById = new Map(summaryRows.map((r) => [r.id, r.summary]));
-    const rankedNodes = neighbors.nodes
-        .map((n) => ({
-        id: n.id,
-        kind: n.kind,
-        name: n.name,
-        naturalKey: n.naturalKey,
-        summary: summaryById.get(n.id) ?? null,
-        distance: n.distance,
-    }))
-        .sort((a, b) => a.distance - b.distance !== 0
-        ? a.distance - b.distance
-        : a.naturalKey < b.naturalKey
-            ? -1
-            : 1);
-    const distanceById = new Map(rankedNodes.map((n) => [n.id, n.distance]));
-    const edgeIds = neighbors.edges.map((e) => e.id);
-    const mentionRows = edgeIds.length
-        ? await exec.query(`SELECT e.id, count(ee.episode_id)::int AS mentions,
-                coalesce(array_agg(ee.episode_id) FILTER (WHERE ee.episode_id IS NOT NULL), '{}') AS episode_ids
-         FROM kg_edges e
-         LEFT JOIN kg_edge_episodes ee ON ee.edge_id = e.id
-         WHERE e.id = ANY($1::text[])
-         GROUP BY e.id`, [edgeIds])
-        : [];
-    const mentionById = new Map(mentionRows.map((r) => [
-        r.id,
-        { mentions: Number(r.mentions), episodeIds: r.episode_ids ?? [] },
-    ]));
-    const rankedFacts = neighbors.edges
-        .map((e) => {
-        const m = mentionById.get(e.id) ?? { mentions: 0, episodeIds: [] };
-        const nearDistance = Math.min(distanceById.get(e.sourceId) ?? Number.POSITIVE_INFINITY, distanceById.get(e.targetId) ?? Number.POSITIVE_INFINITY);
-        return {
-            id: e.id,
-            sourceId: e.sourceId,
-            targetId: e.targetId,
-            relation: e.relation,
-            fact: e.fact,
-            mentions: m.mentions,
-            episodeIds: m.episodeIds,
-            rankDistance: nearDistance,
-        };
-    })
-        .sort((a, b) => {
-        if (b.mentions - a.mentions !== 0)
-            return b.mentions - a.mentions;
-        if (a.rankDistance - b.rankDistance !== 0)
-            return a.rankDistance - b.rankDistance;
-        return a.id < b.id ? -1 : 1;
-    })
-        .map(({ rankDistance: _rankDistance, ...fact }) => fact);
-    const lines = [`# Context for ${anchorId} (depth=${opts.depth})`, '', '## Nodes'];
-    for (const n of rankedNodes) {
-        const summaryPart = n.summary ? ` — ${n.summary}` : '';
-        lines.push(`- [${n.kind}] ${n.naturalKey} (${n.distance} hop)${summaryPart}`);
-    }
-    lines.push('', '## Facts');
-    for (const f of rankedFacts) {
-        const provenance = f.episodeIds.length > 0 ? f.episodeIds.join(', ') : 'none';
-        lines.push(`- (${f.relation}) ${f.fact} [episodes: ${provenance}]`);
-    }
-    let charsUsed = 0;
-    let truncated = false;
-    const packed = [];
-    for (const line of lines) {
-        const addedLength = line.length + 1; // + newline
-        if (charsUsed + addedLength > opts.charBudget) {
-            truncated = true;
-            break;
-        }
-        packed.push(line);
-        charsUsed += addedLength;
+// ---------------------------------------------------------------------------
+// Product-mode helpers
+// ---------------------------------------------------------------------------
+const AUDIT_SCALAR_ALLOWLIST = [
+    'naturalKey',
+    'fromNaturalKey',
+    'toNaturalKey',
+    'episodeType',
+    'classification',
+    'query',
+];
+function extraToContext(extra) {
+    const record = extra;
+    return { authInfo: record?.authInfo, sessionId: record?.sessionId };
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}
+function digestArgs(args) {
+    return createHash('sha256').update(canonicalJson(args)).digest('hex');
+}
+function pickAuditScalars(args) {
+    const out = {};
+    if (!args || typeof args !== 'object')
+        return out;
+    const record = args;
+    for (const key of AUDIT_SCALAR_ALLOWLIST) {
+        const raw = record[key];
+        if (typeof raw === 'string' && raw.length > 0)
+            out[key] = raw;
     }
+    return out;
+}
+function namespaceKey(principal, kind, key) {
+    if (kind === 'agent')
+        return key;
+    if (!shouldNamespaceKeys(principal))
+        return key;
+    return tenantNaturalKey(principal.tenantId, key);
+}
+function inboundKey(principal, key) {
+    if (!(principal && shouldNamespaceKeys(principal)))
+        return key;
+    return tenantNaturalKey(principal.tenantId, key);
+}
+function stampContentRef(principal, clientRef, classification) {
+    const rest = { ...(clientRef ?? {}) };
+    const repo = typeof rest.repo === 'string' ? rest.repo : undefined;
     return {
-        context: packed.join('\n'),
-        anchor: {
-            id: anchorId,
-            naturalKey: rankedNodes.find((n) => n.id === anchorId)?.naturalKey ?? anchorId,
+        ...rest,
+        schema: MEMORY_SCHEMA,
+        actorDid: principal.did,
+        harness: principal.harness,
+        scope: {
+            tenantId: principal.tenantId,
+            workspaceId: principal.workspaceId,
+            repo,
+            classification,
         },
-        nodeCount: rankedNodes.length,
-        factCount: rankedFacts.length,
-        charBudget: opts.charBudget,
-        charsUsed,
-        truncated,
     };
 }
+function productUnavailable(reason, message) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    status: 'unavailable',
+                    available: false,
+                    reason,
+                    message,
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+function wrapOk(mode, data, principal, deniedCount = 0) {
+    if (mode === 'compat')
+        return textResult(data);
+    const enforcement = principal?.trustBoundary === 'hosted' ? 'enforced' : 'deferred';
+    return textResult({
+        status: 'ok',
+        available: true,
+        enforcement,
+        deniedCount,
+        data,
+    });
+}
+function wrapDenied(principal, deniedCount) {
+    return textResult({
+        status: 'denied',
+        available: true,
+        reason: 'scope-denied',
+        deniedCount,
+        scope: {
+            tenantId: principal.tenantId,
+            workspaceId: principal.workspaceId,
+            classification: 'workspace',
+        },
+        message: 'memory-schema hits existed but none were in scope',
+    });
+}
+async function raceTimeout(work, timeoutMs, onTimeout) {
+    if (timeoutMs <= 0)
+        return work;
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(onTimeout()), timeoutMs);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
- * Create a fresh `knowledge-graph` MCP Server instance. Safe to call multiple
- * times — each call returns an independent Server with its own request
- * handlers and its own lazily-resolved executor/embedder cache.
+ * Shared dispatcher for stdio and a later hosted composite. CallTool must pass
+ * `extra` so `principalProvider` can read `authInfo` / `sessionId`.
  */
-export function createKnowledgeGraphServer(options) {
-    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+export function createKnowledgeGraphToolset(options) {
+    const mode = options?.mode ?? 'compat';
+    const trustBoundary = options?.trustBoundary ?? 'studio-local';
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_KG_TOOL_TIMEOUT_MS;
+    const mutatingTools = options?.mutatingTools ?? DEFAULT_MUTATING_TOOLS;
+    const tools = toolsForMode(mode);
+    const names = new Set(tools.map((tool) => tool.name));
     const defaultSiteId = options?.siteId ?? hostname();
     let cachedExecutor = options?.executor;
     async function resolveExecutor() {
@@ -534,92 +680,218 @@ export function createKnowledgeGraphServer(options) {
             return row ? [row] : [];
         });
     }
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    function dbUnavailable(err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const message = `knowledge graph database unavailable: ${detail}`;
+        return mode === 'product'
+            ? productUnavailable('kg-database-unavailable', message)
+            : errorResult(message);
+    }
+    async function handleTool(request, extra) {
+        const startTime = Date.now();
         const toolName = request.params.name;
+        const rawArgs = request.params.arguments;
+        const ctx = extraToContext(extra);
+        const mutating = mutatingTools.has(toolName);
+        async function writeReceipt(outcome, opts) {
+            if (!options?.auditSink)
+                return true;
+            const record = {
+                outcome,
+                tool: toolName,
+                argsDigest: digestArgs(rawArgs ?? null),
+                scalars: pickAuditScalars(rawArgs),
+                durationMs: Date.now() - startTime,
+                reason: opts?.reason,
+                context: ctx,
+            };
+            try {
+                await options.auditSink(record);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        if (!names.has(toolName)) {
+            await writeReceipt('denied');
+            return errorResult(`Unknown tool: ${toolName}`);
+        }
+        let principal = null;
+        if (mode === 'product') {
+            try {
+                principal = (await options?.principalProvider?.(ctx)) ?? null;
+            }
+            catch {
+                principal = null;
+            }
+            const missing = validatePrincipal(principal);
+            if (missing || !principal) {
+                await writeReceipt('denied', { reason: 'principal-missing' });
+                return productUnavailable('principal-missing', missing ?? 'principal is required');
+            }
+            if (principal.trustBoundary !== trustBoundary) {
+                await writeReceipt('denied', { reason: 'principal-missing' });
+                return productUnavailable('principal-missing', 'principal trustBoundary does not match the server');
+            }
+        }
+        if (mutating) {
+            const recorded = await writeReceipt('invoked');
+            if (!recorded) {
+                return errorResult('audit log unavailable; mutating tool refused');
+            }
+        }
         let exec;
         try {
             exec = await resolveExecutor();
         }
         catch (err) {
-            return errorResult(`knowledge graph database unavailable: ${err instanceof Error ? err.message : String(err)}`);
+            if (!mutating)
+                await writeReceipt('failed');
+            return dbUnavailable(err);
         }
         try {
-            switch (toolName) {
-                case 'kg_search': {
-                    const parsed = validateToolArgs(KgSearchArgsSchema, request.params.arguments, toolName);
-                    if (!parsed.ok)
-                        return parsed.error;
-                    const { query, anchor, kinds, relations, at, limit, bfsDepth } = parsed.value;
-                    let anchorId = anchor;
-                    if (anchor) {
-                        // Accept natural key or node id: try resolveNaturalKey first; fall back to raw id.
-                        const resolved = await resolveNaturalKey(exec, anchor);
-                        if (resolved) {
-                            anchorId = resolved;
-                        }
+            const result = await dispatchNamedTool(exec, toolName, request, principal);
+            if (!mutating) {
+                await writeReceipt(result.isError ? 'failed' : 'invoked');
+            }
+            return result;
+        }
+        catch (err) {
+            if (!mutating)
+                await writeReceipt('failed');
+            return mode === 'product'
+                ? dbUnavailable(err)
+                : errorResult(err instanceof Error ? err.message : String(err));
+        }
+    }
+    async function dispatchNamedTool(exec, toolName, request, principal) {
+        switch (toolName) {
+            case 'kg_search': {
+                const parsed = validateToolArgs(KgSearchArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const { query, anchor, kinds, relations, at, limit, bfsDepth } = parsed.value;
+                let anchorId = anchor ? inboundKey(principal, anchor) : anchor;
+                if (anchorId) {
+                    const resolved = await resolveNaturalKey(exec, anchorId);
+                    if (resolved) {
+                        anchorId = resolved;
                     }
-                    const queryEmbedding = await tryEmbed(query);
-                    const result = await kgSearch(exec, {
-                        query,
-                        anchor: anchorId,
-                        kinds: kinds,
-                        relations: relations,
-                        at: at ? new Date(at) : undefined,
-                        limit,
-                        bfsDepth,
-                        queryEmbedding,
-                    });
-                    return textResult(result);
                 }
-                case 'kg_get_node': {
-                    const parsed = validateToolArgs(KgGetNodeArgsSchema, request.params.arguments, toolName);
-                    if (!parsed.ok)
-                        return parsed.error;
-                    const { naturalKey } = parsed.value;
-                    const id = await resolveNaturalKey(exec, naturalKey);
-                    if (!id)
+                const queryEmbedding = await tryEmbed(query);
+                const scoped = mode === 'product' ? (principal ?? undefined) : undefined;
+                const result = await kgSearch(exec, {
+                    query,
+                    anchor: anchorId,
+                    kinds: kinds,
+                    relations: relations,
+                    at: at ? new Date(at) : undefined,
+                    limit,
+                    bfsDepth,
+                    queryEmbedding,
+                    principal: scoped,
+                });
+                const deniedCount = scoped ? await countDeniedMemoryHits(exec, query, scoped) : 0;
+                if (mode === 'product' &&
+                    principal &&
+                    result.nodes.length === 0 &&
+                    result.facts.length === 0 &&
+                    deniedCount > 0) {
+                    return wrapDenied(principal, deniedCount);
+                }
+                return wrapOk(mode, result, principal, deniedCount);
+            }
+            case 'kg_get_node': {
+                const parsed = validateToolArgs(KgGetNodeArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const naturalKey = inboundKey(principal, parsed.value.naturalKey);
+                const id = await resolveNaturalKey(exec, naturalKey);
+                if (!id)
+                    return errorResult(`no node with natural key: ${naturalKey}`);
+                const scoped = mode === 'product' ? (principal ?? undefined) : undefined;
+                if (scoped) {
+                    const visibility = await inspectNodeVisibility(exec, id, scoped);
+                    if (visibility === 'missing') {
                         return errorResult(`no node with natural key: ${naturalKey}`);
+                    }
                     const rows = await exec.query(`SELECT id, kind, name, natural_key, repo, summary, attributes, first_seen_at, last_confirmed_at
              FROM kg_nodes WHERE id = $1`, [id]);
                     const node = rows[0];
                     if (!node)
                         return errorResult(`node ${id} vanished`);
-                    const facts = await kgAtTime(exec, id, new Date());
-                    return textResult({ node, facts });
+                    const facts = await kgAtTime(exec, id, new Date(), { principal: scoped });
+                    if (visibility === 'shell') {
+                        return wrapOk(mode, {
+                            node: {
+                                id: node.id,
+                                kind: node.kind,
+                                name: node.name,
+                                natural_key: node.natural_key,
+                            },
+                            facts,
+                        }, principal);
+                    }
+                    return wrapOk(mode, { node, facts }, principal);
                 }
-                case 'kg_neighbors': {
-                    const parsed = validateToolArgs(KgNeighborsArgsSchema, request.params.arguments, toolName);
-                    if (!parsed.ok)
-                        return parsed.error;
-                    const { naturalKey, depth, relations, at } = parsed.value;
-                    const id = await resolveNaturalKey(exec, naturalKey);
-                    if (!id)
-                        return errorResult(`no node with natural key: ${naturalKey}`);
-                    const result = await kgNeighbors(exec, id, {
-                        depth,
-                        relations: relations,
-                        at: at ? new Date(at) : undefined,
-                    });
-                    return textResult(result);
+                const rows = await exec.query(`SELECT id, kind, name, natural_key, repo, summary, attributes, first_seen_at, last_confirmed_at
+           FROM kg_nodes WHERE id = $1`, [id]);
+                const node = rows[0];
+                if (!node)
+                    return errorResult(`node ${id} vanished`);
+                const facts = await kgAtTime(exec, id, new Date());
+                return wrapOk(mode, { node, facts }, principal);
+            }
+            case 'kg_neighbors': {
+                const parsed = validateToolArgs(KgNeighborsArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const { depth, relations, at } = parsed.value;
+                const naturalKey = inboundKey(principal, parsed.value.naturalKey);
+                const id = await resolveNaturalKey(exec, naturalKey);
+                if (!id)
+                    return errorResult(`no node with natural key: ${naturalKey}`);
+                const scoped = mode === 'product' ? (principal ?? undefined) : undefined;
+                if (scoped && (await inspectNodeVisibility(exec, id, scoped)) === 'missing') {
+                    return errorResult(`no node with natural key: ${naturalKey}`);
                 }
-                case 'kg_add_episode': {
-                    const parsed = validateToolArgs(KgAddEpisodeArgsSchema, request.params.arguments, toolName);
+                const result = await kgNeighbors(exec, id, {
+                    depth,
+                    relations: relations,
+                    at: at ? new Date(at) : undefined,
+                    principal: scoped,
+                });
+                return wrapOk(mode, result, principal);
+            }
+            case 'kg_add_episode': {
+                if (mode === 'product') {
+                    if (!principal) {
+                        return productUnavailable('principal-missing', 'principal is required');
+                    }
+                    const parsed = validateToolArgs(KgProductAddEpisodeArgsSchema, request.params.arguments, toolName);
                     if (!parsed.ok)
                         return parsed.error;
                     const v = parsed.value;
+                    const classification = v.classification ?? 'workspace';
                     const referenceTime = v.referenceTime ? new Date(v.referenceTime) : new Date();
                     const nodes = v.nodes.map((n) => ({
                         kind: n.kind,
                         name: n.name,
-                        naturalKey: n.naturalKey,
+                        naturalKey: namespaceKey(principal, n.kind, n.naturalKey),
                         repo: n.repo,
                         summary: n.summary,
                         attributes: n.attributes,
                     }));
                     const edges = v.edges.map((e) => ({
-                        source: e.source,
-                        target: e.target,
+                        source: {
+                            kind: e.source.kind,
+                            naturalKey: namespaceKey(principal, e.source.kind, e.source.naturalKey),
+                        },
+                        target: {
+                            kind: e.target.kind,
+                            naturalKey: namespaceKey(principal, e.target.kind, e.target.naturalKey),
+                        },
                         relation: e.relation,
                         fact: e.fact,
                         repo: e.repo,
@@ -630,75 +902,155 @@ export function createKnowledgeGraphServer(options) {
                     const result = await ingestEpisode(exec, {
                         episode: {
                             episodeType: v.episodeType,
-                            source: v.source,
+                            source: `agent:${principal.did}`,
                             siteId: v.siteId ?? defaultSiteId,
                             content: v.content,
-                            contentRef: v.contentRef,
+                            contentRef: stampContentRef(principal, v.contentRef, classification),
                             referenceTime,
                         },
                         nodes,
                         edges,
-                    }, { embedder, recordOutbox: true });
-                    return textResult({
+                    }, { embedder, recordOutbox: true, invalidateContradictions: false });
+                    return wrapOk(mode, {
                         episodeId: result.episodeId,
                         nodeCount: result.nodeCount,
                         edgeCount: result.edgeCount,
-                    });
+                    }, principal);
                 }
-                case 'kg_path': {
-                    const parsed = validateToolArgs(KgPathArgsSchema, request.params.arguments, toolName);
-                    if (!parsed.ok)
-                        return parsed.error;
-                    const { fromNaturalKey, toNaturalKey, at, maxDepth } = parsed.value;
-                    const fromId = await resolveNaturalKey(exec, fromNaturalKey);
-                    if (!fromId)
+                const parsed = validateToolArgs(KgAddEpisodeArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const v = parsed.value;
+                const referenceTime = v.referenceTime ? new Date(v.referenceTime) : new Date();
+                const nodes = v.nodes.map((n) => ({
+                    kind: n.kind,
+                    name: n.name,
+                    naturalKey: n.naturalKey,
+                    repo: n.repo,
+                    summary: n.summary,
+                    attributes: n.attributes,
+                }));
+                const edges = v.edges.map((e) => ({
+                    source: e.source,
+                    target: e.target,
+                    relation: e.relation,
+                    fact: e.fact,
+                    repo: e.repo,
+                    validAt: e.validAt ? new Date(e.validAt) : undefined,
+                    attributes: e.attributes,
+                }));
+                const embedder = await resolveEmbedder();
+                const result = await ingestEpisode(exec, {
+                    episode: {
+                        episodeType: v.episodeType,
+                        source: v.source,
+                        siteId: v.siteId ?? defaultSiteId,
+                        content: v.content,
+                        contentRef: v.contentRef,
+                        referenceTime,
+                    },
+                    nodes,
+                    edges,
+                }, { embedder, recordOutbox: true });
+                return wrapOk(mode, {
+                    episodeId: result.episodeId,
+                    nodeCount: result.nodeCount,
+                    edgeCount: result.edgeCount,
+                }, principal);
+            }
+            case 'kg_path': {
+                const parsed = validateToolArgs(KgPathArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const { at, maxDepth } = parsed.value;
+                const fromNaturalKey = inboundKey(principal, parsed.value.fromNaturalKey);
+                const toNaturalKey = inboundKey(principal, parsed.value.toNaturalKey);
+                const fromId = await resolveNaturalKey(exec, fromNaturalKey);
+                if (!fromId)
+                    return errorResult(`no node with natural key: ${fromNaturalKey}`);
+                const toId = await resolveNaturalKey(exec, toNaturalKey);
+                if (!toId)
+                    return errorResult(`no node with natural key: ${toNaturalKey}`);
+                const scoped = mode === 'product' ? (principal ?? undefined) : undefined;
+                if (scoped) {
+                    if ((await inspectNodeVisibility(exec, fromId, scoped)) === 'missing') {
                         return errorResult(`no node with natural key: ${fromNaturalKey}`);
-                    const toId = await resolveNaturalKey(exec, toNaturalKey);
-                    if (!toId)
+                    }
+                    if ((await inspectNodeVisibility(exec, toId, scoped)) === 'missing') {
                         return errorResult(`no node with natural key: ${toNaturalKey}`);
-                    const path = await kgPath(exec, fromId, toId, {
-                        at: at ? new Date(at) : undefined,
-                        maxDepth,
-                    });
-                    if (!path)
-                        return textResult({ path: null });
-                    const detail = await hydratePath(exec, path);
-                    return textResult({ path: detail });
+                    }
                 }
-                case 'kg_at_time': {
-                    const parsed = validateToolArgs(KgAtTimeArgsSchema, request.params.arguments, toolName);
-                    if (!parsed.ok)
-                        return parsed.error;
-                    const { naturalKey, at } = parsed.value;
-                    const id = await resolveNaturalKey(exec, naturalKey);
-                    if (!id)
-                        return errorResult(`no node with natural key: ${naturalKey}`);
-                    const facts = await kgAtTime(exec, id, new Date(at));
-                    return textResult({ facts });
+                const path = await kgPath(exec, fromId, toId, {
+                    at: at ? new Date(at) : undefined,
+                    maxDepth,
+                    principal: scoped,
+                });
+                if (!path)
+                    return wrapOk(mode, { path: null }, principal);
+                const detail = await hydratePath(exec, path);
+                return wrapOk(mode, { path: detail }, principal);
+            }
+            case 'kg_at_time': {
+                const parsed = validateToolArgs(KgAtTimeArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const { at } = parsed.value;
+                const naturalKey = inboundKey(principal, parsed.value.naturalKey);
+                const id = await resolveNaturalKey(exec, naturalKey);
+                if (!id)
+                    return errorResult(`no node with natural key: ${naturalKey}`);
+                const scoped = mode === 'product' ? (principal ?? undefined) : undefined;
+                if (scoped && (await inspectNodeVisibility(exec, id, scoped)) === 'missing') {
+                    return errorResult(`no node with natural key: ${naturalKey}`);
                 }
-                case 'kg_context': {
-                    const parsed = validateToolArgs(KgContextArgsSchema, request.params.arguments, toolName);
-                    if (!parsed.ok)
-                        return parsed.error;
-                    const { naturalKey, charBudget, depth, at } = parsed.value;
-                    const id = await resolveNaturalKey(exec, naturalKey);
-                    if (!id)
-                        return errorResult(`no node with natural key: ${naturalKey}`);
-                    const assembled = await assembleContext(exec, id, {
-                        charBudget: charBudget ?? DEFAULT_CONTEXT_CHAR_BUDGET,
-                        depth: depth ?? 3,
-                        at: at ? new Date(at) : undefined,
-                    });
-                    return textResult(assembled);
+                const facts = await kgAtTime(exec, id, new Date(at), { principal: scoped });
+                return wrapOk(mode, { facts }, principal);
+            }
+            case 'kg_context': {
+                const parsed = validateToolArgs(KgContextArgsSchema, request.params.arguments, toolName);
+                if (!parsed.ok)
+                    return parsed.error;
+                const { charBudget, depth, at } = parsed.value;
+                const naturalKey = inboundKey(principal, parsed.value.naturalKey);
+                const id = await resolveNaturalKey(exec, naturalKey);
+                if (!id)
+                    return errorResult(`no node with natural key: ${naturalKey}`);
+                const scoped = mode === 'product' ? (principal ?? undefined) : undefined;
+                if (scoped && (await inspectNodeVisibility(exec, id, scoped)) === 'missing') {
+                    return errorResult(`no node with natural key: ${naturalKey}`);
                 }
-                default:
-                    return errorResult(`Unknown tool: ${toolName}`);
+                const assembled = await assembleContext(exec, id, {
+                    charBudget: charBudget ?? DEFAULT_CONTEXT_CHAR_BUDGET,
+                    depth: depth ?? 3,
+                    at: at ? new Date(at) : undefined,
+                    principal: scoped,
+                });
+                return wrapOk(mode, assembled, principal);
             }
+            default:
+                return errorResult(`Unknown tool: ${toolName}`);
         }
-        catch (err) {
-            return errorResult(err instanceof Error ? err.message : String(err));
-        }
-    });
+    }
+    return {
+        tools,
+        names,
+        async dispatch(request, extra) {
+            return raceTimeout(handleTool(request, extra), timeoutMs, () => mode === 'product'
+                ? productUnavailable('timeout', 'knowledge graph tool timed out')
+                : errorResult('knowledge graph tool timed out'));
+        },
+    };
+}
+/**
+ * Create a fresh `knowledge-graph` MCP Server instance. Safe to call multiple
+ * times — each call returns an independent Server with its own request
+ * handlers and its own lazily-resolved executor/embedder cache.
+ */
+export function createKnowledgeGraphServer(options) {
+    const toolset = createKnowledgeGraphToolset(options);
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolset.tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => toolset.dispatch(request, extra));
     return server;
 }
 //# sourceMappingURL=knowledge-graph.js.map