@anchrd/intel-api 0.2.0

package/dist/knowledge/knowledge.js

@@ -0,0 +1,479 @@
+import { IntelError } from "../shared/intel-error/intel-error.js";
+function decodeBase64(value) {
+    if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        throw new IntelError(400, "attachment_invalid", "Attachment content is not valid base64");
+    }
+    try {
+        return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+    }
+    catch {
+        throw new IntelError(400, "attachment_invalid", "Attachment content is not valid base64");
+    }
+}
+export function createKnowledge(deps) {
+    function mergeSearchResults(lexical, semantic, semanticScores, limit) {
+        const merged = new Map();
+        for (const citation of lexical) {
+            merged.set(citation.nodeId, {
+                citation,
+                lexicalScore: citation.score,
+                semanticScore: undefined,
+            });
+        }
+        for (const citation of semantic) {
+            const current = merged.get(citation.nodeId);
+            merged.set(citation.nodeId, {
+                citation: current?.citation ?? citation,
+                lexicalScore: current?.lexicalScore,
+                semanticScore: semanticScores.get(citation.nodeId) ?? citation.score,
+            });
+        }
+        return [...merged.values()]
+            .map(({ citation, lexicalScore, semanticScore }) => {
+            const score = lexicalScore !== undefined && semanticScore !== undefined
+                ? lexicalScore * 0.45 + semanticScore * 0.55
+                : lexicalScore !== undefined
+                    ? lexicalScore * 0.9
+                    : (semanticScore ?? 0) * 0.85;
+            return {
+                ...citation,
+                score: Math.max(0, Math.min(1, score)),
+                match: lexicalScore !== undefined && semanticScore !== undefined
+                    ? "hybrid"
+                    : lexicalScore !== undefined
+                        ? "lexical"
+                        : "semantic",
+            };
+        })
+            .sort((left, right) => right.score - left.score || right.freshness.localeCompare(left.freshness))
+            .slice(0, limit);
+    }
+    async function getDocument(node) {
+        if (node.currentVersionId === null)
+            return { node, version: null, content: null };
+        const version = await deps.repository.getVersion(node.currentVersionId);
+        if (!version)
+            throw new IntelError(500, "version_missing", "Current version is missing");
+        if (node.kind === "attachment")
+            return { node, version, content: null };
+        const content = await deps.content.get(version.contentKey);
+        if (content === null)
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        return { node, version, content };
+    }
+    async function requireVisible(actor, nodeId) {
+        const node = await deps.repository.getVisible(actor, nodeId);
+        if (!node)
+            throw new IntelError(404, "knowledge_not_found", "Knowledge was not found");
+        return node;
+    }
+    async function nextSequence(node) {
+        if (!node.currentVersionId)
+            return 1;
+        const current = await deps.repository.getVersion(node.currentVersionId);
+        if (!current) {
+            throw new IntelError(500, "version_missing", "Current Knowledge version is missing");
+        }
+        return current.sequence + 1;
+    }
+    async function attachment(actor, nodeId) {
+        const node = await requireVisible(actor, nodeId);
+        if (node.kind !== "attachment" || !node.currentVersionId) {
+            throw new IntelError(404, "attachment_not_found", "Attachment was not found");
+        }
+        const version = await deps.repository.getVersion(node.currentVersionId);
+        if (!version)
+            throw new IntelError(500, "version_missing", "Current version is missing");
+        return {
+            node,
+            version,
+            resourceUri: `intel://knowledge/${encodeURIComponent(node.id)}/attachment`,
+        };
+    }
+    return {
+        async list(actor, input) {
+            return { items: await deps.repository.listVisible(actor, input) };
+        },
+        async get(actor, nodeId) {
+            return await getDocument(await requireVisible(actor, nodeId));
+        },
+        async create(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "knowledge.create", input.idempotencyKey);
+            if (existingId)
+                return await requireVisible(actor, existingId);
+            if (input.parentId !== null && !(await deps.repository.canEdit(actor, input.parentId))) {
+                throw new IntelError(403, "knowledge_forbidden", "Parent folder cannot be edited");
+            }
+            const timestamp = deps.now().toISOString();
+            return await deps.repository.insertNode({
+                node: {
+                    id: deps.id(),
+                    parentId: input.parentId,
+                    kind: input.kind,
+                    title: input.title,
+                    description: input.description,
+                    contextPolicy: input.contextPolicy,
+                    ownerId: actor.id,
+                    currentVersionId: null,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                    archivedAt: null,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        },
+        async save(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "knowledge.save", input.idempotencyKey);
+            if (existingId) {
+                const document = await getDocument(await requireVisible(actor, input.nodeId));
+                await deps.indexing.enqueue(existingId);
+                return document;
+            }
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "document") {
+                throw new IntelError(409, "document_content_required", "Only documents accept editor content versions");
+            }
+            if (!(await deps.repository.canEdit(actor, node.id))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge cannot be edited");
+            }
+            if (node.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const versionId = deps.id();
+            const contentKey = `knowledge/${node.id}/versions/${versionId}`;
+            const createdAt = deps.now().toISOString();
+            const version = {
+                id: versionId,
+                nodeId: node.id,
+                sequence: await nextSequence(node),
+                contentKey,
+                mediaType: input.mediaType,
+                contentHash: await deps.hash(input.content),
+                size: new TextEncoder().encode(input.content).byteLength,
+                createdBy: actor.id,
+                createdAt,
+            };
+            await deps.content.put(contentKey, input.content, input.mediaType);
+            let saved;
+            try {
+                saved = await deps.repository.appendVersion({
+                    version,
+                    actorId: actor.id,
+                    baseVersionId: input.baseVersionId,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                });
+            }
+            catch (error) {
+                await deps.content.delete(contentKey).catch(() => undefined);
+                throw error;
+            }
+            if (saved === "conflict") {
+                await deps.content.delete(contentKey);
+                const replayed = await deps.repository.findIdempotentNode(actor.id, "knowledge.save", input.idempotencyKey);
+                if (replayed)
+                    return await getDocument(await requireVisible(actor, node.id));
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const updated = await requireVisible(actor, node.id);
+            await deps.indexing.enqueue(version.id);
+            return { node: updated, version, content: input.content };
+        },
+        async saveAttachment(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "knowledge.save", input.idempotencyKey);
+            if (existingId) {
+                const document = await getDocument(await requireVisible(actor, input.nodeId));
+                await deps.indexing.enqueue(existingId);
+                return document;
+            }
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "attachment") {
+                throw new IntelError(409, "not_an_attachment", "Only attachment nodes accept file uploads");
+            }
+            if (!(await deps.repository.canEdit(actor, node.id))) {
+                throw new IntelError(403, "knowledge_forbidden", "Attachment cannot be edited");
+            }
+            if (node.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const bytes = decodeBase64(input.contentBase64);
+            const versionId = deps.id();
+            const contentKey = `knowledge/${node.id}/versions/${versionId}`;
+            const createdAt = deps.now().toISOString();
+            const version = {
+                id: versionId,
+                nodeId: node.id,
+                sequence: await nextSequence(node),
+                contentKey,
+                mediaType: input.mediaType,
+                contentHash: await deps.hash(bytes),
+                size: bytes.byteLength,
+                createdBy: actor.id,
+                createdAt,
+            };
+            await deps.content.putBytes(contentKey, bytes.buffer, input.mediaType);
+            let saved;
+            try {
+                saved = await deps.repository.appendVersion({
+                    version,
+                    actorId: actor.id,
+                    baseVersionId: input.baseVersionId,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                });
+            }
+            catch (error) {
+                await deps.content.delete(contentKey).catch(() => undefined);
+                throw error;
+            }
+            if (saved === "conflict") {
+                await deps.content.delete(contentKey);
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            await deps.indexing.enqueue(version.id);
+            return { node: await requireVisible(actor, node.id), version, content: null };
+        },
+        async getAttachment(actor, nodeId) {
+            return await attachment(actor, nodeId);
+        },
+        async readAttachment(actor, nodeId) {
+            const metadata = await attachment(actor, nodeId);
+            const body = await deps.content.getStream(metadata.version.contentKey);
+            if (body === null)
+                throw new IntelError(500, "content_missing", "Attachment is missing");
+            return { attachment: metadata, body };
+        },
+        async listVersions(actor, nodeId) {
+            await requireVisible(actor, nodeId);
+            return { items: await deps.repository.listVersions(nodeId) };
+        },
+        async update(actor, input) {
+            const current = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.canEdit(actor, current.id))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge cannot be edited");
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.update", input.idempotencyKey);
+            if (replayedId)
+                return await requireVisible(actor, replayedId);
+            if (input.parentId !== undefined && input.parentId !== null) {
+                if (input.parentId === current.id) {
+                    throw new IntelError(409, "move_cycle", "Knowledge cannot contain itself");
+                }
+                const parent = await requireVisible(actor, input.parentId);
+                if (parent.kind !== "folder") {
+                    throw new IntelError(409, "parent_not_folder", "Knowledge parent must be a folder");
+                }
+                if (!(await deps.repository.canEdit(actor, parent.id))) {
+                    throw new IntelError(403, "knowledge_forbidden", "Destination folder cannot be edited");
+                }
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.updateNode({
+                node: {
+                    ...current,
+                    parentId: input.parentId === undefined ? current.parentId : input.parentId,
+                    title: input.title ?? current.title,
+                    description: input.description === undefined ? current.description : input.description,
+                    contextPolicy: input.contextPolicy ?? current.contextPolicy,
+                    updatedAt,
+                },
+                baseUpdatedAt: input.baseUpdatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "cycle") {
+                throw new IntelError(409, "move_cycle", "Knowledge cannot be moved into its descendant");
+            }
+            if (updated === "conflict") {
+                throw new IntelError(409, "update_conflict", "Knowledge was changed by another editor");
+            }
+            if (updated.currentVersionId)
+                await deps.indexing.enqueue(updated.currentVersionId);
+            return updated;
+        },
+        async archive(actor, input) {
+            const current = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.canEdit(actor, current.id))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge cannot be edited");
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.archive", input.idempotencyKey);
+            if (replayedId)
+                return await requireVisible(actor, replayedId);
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.archiveNode({
+                nodeId: current.id,
+                baseUpdatedAt: input.baseUpdatedAt,
+                archivedAt: input.archived ? updatedAt : null,
+                updatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                throw new IntelError(409, "update_conflict", "Knowledge was changed by another editor");
+            }
+            return updated;
+        },
+        async listGrants(actor, resourceId) {
+            await requireVisible(actor, resourceId);
+            if (!(await deps.repository.canManage(actor, resourceId))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge sharing cannot be managed");
+            }
+            return { items: await deps.repository.listGrants(resourceId) };
+        },
+        async listLinks(actor, nodeId) {
+            await requireVisible(actor, nodeId);
+            return { items: await deps.repository.listLinksVisible(actor, nodeId) };
+        },
+        async createLink(actor, input) {
+            await requireVisible(actor, input.sourceNodeId);
+            await requireVisible(actor, input.targetNodeId);
+            if (!(await deps.repository.canEdit(actor, input.sourceNodeId))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge links cannot be edited");
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.link", input.idempotencyKey);
+            if (replayedId) {
+                const replayed = await deps.repository.getLinkVisible(actor, replayedId);
+                if (replayed)
+                    return replayed;
+            }
+            const existing = await deps.repository.findLinkVisible(actor, input);
+            if (existing)
+                return existing;
+            const createdAt = deps.now().toISOString();
+            return await deps.repository.insertLink({
+                link: {
+                    id: deps.id(),
+                    sourceNodeId: input.sourceNodeId,
+                    targetNodeId: input.targetNodeId,
+                    relation: input.relation,
+                    label: input.label,
+                    createdBy: actor.id,
+                    createdAt,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        },
+        async deleteLink(actor, input) {
+            await requireVisible(actor, input.sourceNodeId);
+            if (!(await deps.repository.canEdit(actor, input.sourceNodeId))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge links cannot be edited");
+            }
+            const replayed = await deps.repository.findIdempotentNode(actor.id, "knowledge.unlink", input.idempotencyKey);
+            if (replayed)
+                return { deleted: replayed.startsWith("1:") };
+            const link = await deps.repository.getLinkVisible(actor, input.linkId);
+            if (!link || link.sourceNodeId !== input.sourceNodeId) {
+                throw new IntelError(404, "knowledge_link_not_found", "Knowledge link was not found");
+            }
+            return {
+                deleted: await deps.repository.deleteLink({
+                    sourceNodeId: input.sourceNodeId,
+                    linkId: input.linkId,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    occurredAt: deps.now().toISOString(),
+                }),
+            };
+        },
+        async graph(actor, input) {
+            return await deps.repository.graphVisible(actor, input);
+        },
+        async share(actor, input) {
+            await requireVisible(actor, input.resourceId);
+            if (!(await deps.repository.canManage(actor, input.resourceId))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge sharing cannot be managed");
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.share", input.idempotencyKey);
+            if (replayedId) {
+                const replayed = (await deps.repository.listGrants(input.resourceId)).find((grant) => grant.id === replayedId);
+                if (replayed)
+                    return replayed;
+            }
+            const principal = input.principal.type === "email"
+                ? { type: "email", email: input.principal.email.toLowerCase() }
+                : input.principal;
+            const timestamp = deps.now().toISOString();
+            return await deps.repository.setGrant({
+                grant: {
+                    id: deps.id(),
+                    resourceId: input.resourceId,
+                    principal,
+                    role: input.role,
+                    expiresAt: input.expiresAt,
+                    createdBy: actor.id,
+                    createdAt: timestamp,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        },
+        async revokeGrant(actor, input) {
+            await requireVisible(actor, input.resourceId);
+            if (!(await deps.repository.canManage(actor, input.resourceId))) {
+                throw new IntelError(403, "knowledge_forbidden", "Knowledge sharing cannot be managed");
+            }
+            const replayed = await deps.repository.findIdempotentRevocation(actor.id, input.idempotencyKey);
+            if (replayed !== null)
+                return { revoked: replayed };
+            return {
+                revoked: await deps.repository.revokeGrant({
+                    resourceId: input.resourceId,
+                    grantId: input.grantId,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    occurredAt: deps.now().toISOString(),
+                }),
+            };
+        },
+        async search(actor, input) {
+            const lexical = await deps.repository.searchVisible(actor, {
+                ...input,
+                limit: Math.min(50, input.limit * 2),
+            });
+            if (!deps.semantic)
+                return { items: lexical.slice(0, input.limit) };
+            try {
+                const hits = await deps.semantic.search(input.query, Math.min(100, input.limit * 4));
+                const semanticScores = new Map();
+                for (const hit of hits) {
+                    semanticScores.set(hit.nodeId, Math.max(semanticScores.get(hit.nodeId) ?? 0, hit.score));
+                }
+                const semantic = await deps.repository.hydrateVisibleCitations(actor, [
+                    ...semanticScores.keys(),
+                ]);
+                return {
+                    items: mergeSearchResults(lexical, semantic, semanticScores, input.limit),
+                };
+            }
+            catch {
+                return { items: lexical.slice(0, input.limit) };
+            }
+        },
+        async reindex(actor) {
+            if (actor.canReindex !== true) {
+                throw new IntelError(403, "knowledge_reindex_forbidden", "Reindex permission is required");
+            }
+            let queued = 0;
+            let after = null;
+            for (;;) {
+                const versionIds = await deps.repository.listCurrentVersionIds({ after, limit: 100 });
+                for (const versionId of versionIds)
+                    await deps.indexing.enqueue(versionId);
+                queued += versionIds.length;
+                if (versionIds.length < 100)
+                    break;
+                after = versionIds.at(-1) ?? null;
+            }
+            return { queued };
+        },
+    };
+}

package/dist/knowledge/knowledge.types.d.ts

@@ -0,0 +1,162 @@
+import type { ArchiveKnowledgeNodeInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, KnowledgeAttachment, KnowledgeCitation, KnowledgeDocument, KnowledgeGraph, KnowledgeGraphInput, KnowledgeLink, KnowledgeNode, KnowledgeVersion, ListKnowledgeNodesInput, ResourceGrant, RevokeKnowledgeGrantInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, UpdateKnowledgeNodeInput } from "@anchrd/intel-contract";
+import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
+export interface Actor {
+    id: string;
+    email: string;
+    canReindex?: boolean;
+}
+export interface NewKnowledgeNode {
+    node: KnowledgeNode;
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface NewKnowledgeVersion {
+    version: KnowledgeVersion;
+    actorId: string;
+    baseVersionId: string | null;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface KnowledgeRepository {
+    listVisible(actor: Actor, input: ListKnowledgeNodesInput): Promise<KnowledgeNode[]>;
+    getVisible(actor: Actor, nodeId: string): Promise<KnowledgeNode | null>;
+    canEdit(actor: Actor, nodeId: string): Promise<boolean>;
+    canManage(actor: Actor, nodeId: string): Promise<boolean>;
+    findIdempotentNode(actorId: string, operation: "knowledge.create" | "knowledge.save" | "knowledge.update" | "knowledge.archive" | "knowledge.link" | "knowledge.unlink" | "knowledge.share" | "knowledge.revoke", idempotencyKey: string): Promise<string | null>;
+    findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
+    insertNode(input: NewKnowledgeNode): Promise<KnowledgeNode>;
+    getVersion(versionId: string): Promise<KnowledgeVersion | null>;
+    appendVersion(input: NewKnowledgeVersion): Promise<"saved" | "conflict">;
+    listVersions(nodeId: string): Promise<KnowledgeVersion[]>;
+    updateNode(input: {
+        node: KnowledgeNode;
+        baseUpdatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"cycle" | "conflict" | KnowledgeNode>;
+    archiveNode(input: {
+        nodeId: string;
+        baseUpdatedAt: string;
+        archivedAt: string | null;
+        updatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | KnowledgeNode>;
+    listGrants(resourceId: string): Promise<ResourceGrant[]>;
+    listLinksVisible(actor: Actor, nodeId: string): Promise<KnowledgeLink[]>;
+    getLinkVisible(actor: Actor, linkId: string): Promise<KnowledgeLink | null>;
+    findLinkVisible(actor: Actor, input: Pick<CreateKnowledgeLinkInput, "sourceNodeId" | "targetNodeId" | "relation">): Promise<KnowledgeLink | null>;
+    insertLink(input: {
+        link: KnowledgeLink;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<KnowledgeLink>;
+    deleteLink(input: {
+        sourceNodeId: string;
+        linkId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    graphVisible(actor: Actor, input: KnowledgeGraphInput): Promise<KnowledgeGraph>;
+    setGrant(input: {
+        grant: ResourceGrant;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<ResourceGrant>;
+    revokeGrant(input: {
+        resourceId: string;
+        grantId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    searchVisible(actor: Actor, input: SearchKnowledgeInput): Promise<KnowledgeCitation[]>;
+    hydrateVisibleCitations(actor: Actor, nodeIds: string[]): Promise<KnowledgeCitation[]>;
+    listCurrentVersionIds(input: {
+        after: string | null;
+        limit: number;
+    }): Promise<string[]>;
+}
+export interface ContentStore {
+    get(key: string): Promise<string | null>;
+    getBytes(key: string): Promise<ArrayBuffer | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    put(key: string, content: string, mediaType: string): Promise<void>;
+    putBytes(key: string, content: ArrayBuffer, mediaType: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface KnowledgeAttachmentBody {
+    attachment: KnowledgeAttachment;
+    body: ReadableStream<Uint8Array>;
+}
+export interface KnowledgeDeps {
+    repository: KnowledgeRepository;
+    content: ContentStore;
+    id(): string;
+    now(): Date;
+    hash(content: string | Uint8Array): Promise<string>;
+    indexing: {
+        enqueue(versionId: string): Promise<void>;
+    };
+    semantic?: SemanticIndex | undefined;
+}
+export interface KnowledgeService {
+    list(actor: Actor, input: ListKnowledgeNodesInput): Promise<{
+        items: KnowledgeNode[];
+    }>;
+    get(actor: Actor, nodeId: string): Promise<KnowledgeDocument>;
+    create(actor: Actor, input: CreateKnowledgeNodeInput): Promise<KnowledgeNode>;
+    save(actor: Actor, input: SaveKnowledgeVersionInput): Promise<KnowledgeDocument>;
+    saveAttachment(actor: Actor, input: SaveKnowledgeAttachmentInput): Promise<KnowledgeDocument>;
+    getAttachment(actor: Actor, nodeId: string): Promise<KnowledgeAttachment>;
+    readAttachment(actor: Actor, nodeId: string): Promise<KnowledgeAttachmentBody>;
+    listVersions(actor: Actor, nodeId: string): Promise<{
+        items: KnowledgeVersion[];
+    }>;
+    update(actor: Actor, input: UpdateKnowledgeNodeInput): Promise<KnowledgeNode>;
+    archive(actor: Actor, input: ArchiveKnowledgeNodeInput): Promise<KnowledgeNode>;
+    listGrants(actor: Actor, resourceId: string): Promise<{
+        items: ResourceGrant[];
+    }>;
+    listLinks(actor: Actor, nodeId: string): Promise<{
+        items: KnowledgeLink[];
+    }>;
+    createLink(actor: Actor, input: CreateKnowledgeLinkInput): Promise<KnowledgeLink>;
+    deleteLink(actor: Actor, input: DeleteKnowledgeLinkInput): Promise<{
+        deleted: boolean;
+    }>;
+    graph(actor: Actor, input: KnowledgeGraphInput): Promise<KnowledgeGraph>;
+    share(actor: Actor, input: ShareKnowledgeInput): Promise<ResourceGrant>;
+    revokeGrant(actor: Actor, input: RevokeKnowledgeGrantInput): Promise<{
+        revoked: boolean;
+    }>;
+    search(actor: Actor, input: SearchKnowledgeInput): Promise<{
+        items: KnowledgeCitation[];
+    }>;
+    reindex(actor: Actor): Promise<{
+        queued: number;
+    }>;
+}
+export interface KnowledgeIndexTarget {
+    nodeId: string;
+    versionId: string;
+    title: string;
+    contentKey: string;
+    mediaType: string;
+    kind: "document" | "attachment";
+    updatedAt: string;
+}
+export interface KnowledgeIndexRepository {
+    getTarget(versionId: string): Promise<KnowledgeIndexTarget | null>;
+    replace(target: KnowledgeIndexTarget, content: string): Promise<void>;
+    markIndexed(versionId: string, occurredAt: string): Promise<void>;
+    markError(versionId: string, message: string, occurredAt: string): Promise<void>;
+}

package/dist/knowledge/knowledge.types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { McpDeps } from "./mcp.types.js";
+export declare function handleMcp(request: Request, deps: McpDeps): Promise<Response>;