@lssm/lib.contracts 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/knowledge/docs/knowledge.docblock.js

@@ -1,138 +1,22 @@
-import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.knowledge`,title:`Knowledge Layer`,summary:`The knowledge layer turns unstructured inputs (uploads, email threads,`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/knowledge`,tags:[`tech`,`contracts`,`knowledge`],body:`# Knowledge Layer
-
-The knowledge layer turns unstructured inputs (uploads, email threads,
-notes) into searchable context for agents and workflows. The Pocket
-Family Office vertical ships a minimal but production-ready stack that
-covers ingestion, indexing, querying, and guardrails.
-
-## Knowledge Spaces
-
-Knowledge is organised via \`KnowledgeSpaceSpec\` definitions under
-\`packages/libs/contracts/src/knowledge/spaces\`:
-
-- \`knowledge.financial-docs\` – canonical invoices, bills, and contracts.
-- \`knowledge.email-threads\` – operational Gmail threads.
-- \`knowledge.support-faq\` / \`knowledge.product-canon\` – reusable shared
-  spaces available to any vertical.
-
-Each space defines:
-
-- Ownership metadata (domain, owners, stability tags).
-- Retention policy (TTL/archival).
-- Access policy (trust level, automation write permissions).
-- Indexing configuration (embedding model, chunk size, vector DB slot).
-
-## Sources & Bindings
-
-- \`KnowledgeSourceConfig\` records tenant-specific connections (bucket,
-  Gmail labels, sync cadence). Pocket Family Office provides sample
-  configs in \`knowledge/sources.sample.ts\`.
-- \`AppKnowledgeBinding\` associates spaces with workflows/agents and adds
-  per-tenant constraints (rate limits, scopes).
-
-Validation ensures that:
-
-- All referenced spaces exist in the registry.
-- At least one source is configured per binding.
-- External/ephemeral spaces trigger warnings for policy-sensitive flows.
-
-## Ingestion Pipeline
-
-Implemented in \`packages/libs/contracts/src/knowledge/ingestion\`:
-
-1. **DocumentProcessor** – pluggable MIME extractors producing
-   \`DocumentFragment\`s.
-2. **EmbeddingService** – batches fragments through an \`EmbeddingProvider\`
-   (Mistral in the reference implementation).
-3. **VectorIndexer** – upserts fragments into a \`VectorStoreProvider\`
-   (Qdrant in production, with in-memory implementations for tests).
-4. **Adapters**
-   - \`GmailIngestionAdapter\`: list threads → convert to raw documents →
-     index.
-   - \`StorageIngestionAdapter\`: fetch object from storage provider →
-     index.
-
-Background jobs (see \`jobs/\`) orchestrate ingestion via Cloud Tasks /
-Pub/Sub or in-memory workers. Handlers:
-
-- \`storage-document-handler\` – resolves storage object + indexes.
-- \`gmail-sync-handler\` – syncs threads based on label/date filters.
-
-## Query Service
-
-\`KnowledgeQueryService\` performs retrieval-augmented generation:
-
-1. Embed the user query using the configured provider.
-2. Search the vector store for top-k matches.
-3. Compose prompts combining system instructions + contextual snippets.
-4. Invoke the LLM provider (Mistral) and return the answer plus
-   references and token usage.
-
-The service is designed for tooling: workflows can execute it directly
-or through custom operations (see \`pfo.summary.generate\` contract).
-
-## Guardrails
-
-- Automation can only write to spaces where \`automationWritable\` is true.
-- Canonical spaces default to high trust; external/ephemeral spaces are
-  flagged during validation.
-- Telemetry captures query volumes per tenant + space.
-
-## Extending
-
-1. Define a new \`KnowledgeSpaceSpec\` with indexing/retention policies.
-2. Add sources pointing to storage providers or APIs.
-3. Register adapters if ingestion requires bespoke logic.
-4. Reference the space in blueprints (\`AppKnowledgeBinding\`) and update
-   workflows/agents accordingly.
-
-The Pocket Family Office tests (\`tests/pocket-family-office.test.ts\`)
-show how to wire the ingestion pipeline, index a document, and run an
-end-to-end knowledge query using in-memory providers.
-## Knowledge Spaces & Guardrails
-
-Knowledge surfaces (\`KnowledgeSpaceSpec\`) describe curated corpora that agents and workflows can consult. Tenant bindings (\`AppKnowledgeBinding\`) declare which spaces are active, who can use them, and optional usage constraints.
-
-### Binding recap
-
-- \`spaceKey\` / \`spaceVersion\`: pointer to the \`KnowledgeSpaceSpec\`
-- \`scope.workflows\` / \`scope.agents\`: explicit allow-lists for consumers
-- \`constraints.maxTokensPerQuery\` & \`constraints.maxQueriesPerMinute\`: throttling knobs for LLM-backed search
-- \`required\`: mark the binding as blocking (defaults to \`true\`)
-
-At runtime, \`ResolvedAppConfig.knowledge\` contains \`ResolvedKnowledge\` entries with the bound space, active sources, and the binding metadata above.
-
-### KnowledgeAccessGuard
-
-\`KnowledgeAccessGuard\` (\`@lssm/lib.contracts/knowledge/runtime\`) centralises the access checks that must run before any workflow/agent reads or mutates a knowledge space.
-
-\`\`\`ts
-import { KnowledgeAccessGuard } from '@lssm/lib.contracts/knowledge/runtime';
-
-const guard = new KnowledgeAccessGuard({
-  disallowWriteCategories: ['external', 'ephemeral'], // default
-  requireWorkflowBinding: true,
-  requireAgentBinding: false,
-});
-
-const result = guard.checkAccess(resolvedKnowledge, {
-  tenantId,
-  appId,
-  workflowName: 'order-processing',
-  operation: 'read', // or 'write' / 'search'
-}, resolvedAppConfig);
-
-if (!result.allowed) {
-  throw new Error(result.reason);
-}
-\`\`\`
-
-Key behaviours:
-
-- **Binding**: rejects access when the space is not present in the resolved tenant config.
-- **Category guardrails**: blocks writes to \`external\` and \`ephemeral\` spaces by default; allows reads but emits warnings for \`ephemeral\`.
-- **Workflow/agent scoping**: when \`requireWorkflowBinding\` or \`requireAgentBinding\` is enabled, only explicitly authorised consumers may access the space.
-
-Use the guard inside workflow operations or agent resolvers to guarantee multi-tenant isolation and honour data governance rules.
-
-`}];e(t);export{t as tech_contracts_knowledge_DocBlocks};
+import { registerDocBlocks } from "../../docs/registry.js";
+import "../../registry.js";
+
+//#region src/knowledge/docs/knowledge.docblock.ts
+const tech_contracts_knowledge_DocBlocks = [{
+	id: "docs.tech.contracts.knowledge",
+	title: "Knowledge Layer",
+	summary: "The knowledge layer turns unstructured inputs (uploads, email threads,",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/knowledge",
+	tags: [
+		"tech",
+		"contracts",
+		"knowledge"
+	],
+	body: "# Knowledge Layer\n\nThe knowledge layer turns unstructured inputs (uploads, email threads,\nnotes) into searchable context for agents and workflows. The Pocket\nFamily Office vertical ships a minimal but production-ready stack that\ncovers ingestion, indexing, querying, and guardrails.\n\n## Knowledge Spaces\n\nKnowledge is organised via `KnowledgeSpaceSpec` definitions under\n`packages/libs/contracts/src/knowledge/spaces`:\n\n- `knowledge.financial-docs` – canonical invoices, bills, and contracts.\n- `knowledge.email-threads` – operational Gmail threads.\n- `knowledge.support-faq` / `knowledge.product-canon` – reusable shared\n  spaces available to any vertical.\n\nEach space defines:\n\n- Ownership metadata (domain, owners, stability tags).\n- Retention policy (TTL/archival).\n- Access policy (trust level, automation write permissions).\n- Indexing configuration (embedding model, chunk size, vector DB slot).\n\n## Sources & Bindings\n\n- `KnowledgeSourceConfig` records tenant-specific connections (bucket,\n  Gmail labels, sync cadence). Pocket Family Office provides sample\n  configs in `knowledge/sources.sample.ts`.\n- `AppKnowledgeBinding` associates spaces with workflows/agents and adds\n  per-tenant constraints (rate limits, scopes).\n\nValidation ensures that:\n\n- All referenced spaces exist in the registry.\n- At least one source is configured per binding.\n- External/ephemeral spaces trigger warnings for policy-sensitive flows.\n\n## Ingestion Pipeline\n\nImplemented in `packages/libs/contracts/src/knowledge/ingestion`:\n\n1. **DocumentProcessor** – pluggable MIME extractors producing\n   `DocumentFragment`s.\n2. **EmbeddingService** – batches fragments through an `EmbeddingProvider`\n   (Mistral in the reference implementation).\n3. **VectorIndexer** – upserts fragments into a `VectorStoreProvider`\n   (Qdrant in production, with in-memory implementations for tests).\n4. **Adapters**\n   - `GmailIngestionAdapter`: list threads → convert to raw documents →\n     index.\n   - `StorageIngestionAdapter`: fetch object from storage provider →\n     index.\n\nBackground jobs (see `jobs/`) orchestrate ingestion via Cloud Tasks /\nPub/Sub or in-memory workers. Handlers:\n\n- `storage-document-handler` – resolves storage object + indexes.\n- `gmail-sync-handler` – syncs threads based on label/date filters.\n\n## Query Service\n\n`KnowledgeQueryService` performs retrieval-augmented generation:\n\n1. Embed the user query using the configured provider.\n2. Search the vector store for top-k matches.\n3. Compose prompts combining system instructions + contextual snippets.\n4. Invoke the LLM provider (Mistral) and return the answer plus\n   references and token usage.\n\nThe service is designed for tooling: workflows can execute it directly\nor through custom operations (see `pfo.summary.generate` contract).\n\n## Guardrails\n\n- Automation can only write to spaces where `automationWritable` is true.\n- Canonical spaces default to high trust; external/ephemeral spaces are\n  flagged during validation.\n- Telemetry captures query volumes per tenant + space.\n\n## Extending\n\n1. Define a new `KnowledgeSpaceSpec` with indexing/retention policies.\n2. Add sources pointing to storage providers or APIs.\n3. Register adapters if ingestion requires bespoke logic.\n4. Reference the space in blueprints (`AppKnowledgeBinding`) and update\n   workflows/agents accordingly.\n\nThe Pocket Family Office tests (`tests/pocket-family-office.test.ts`)\nshow how to wire the ingestion pipeline, index a document, and run an\nend-to-end knowledge query using in-memory providers.\n## Knowledge Spaces & Guardrails\n\nKnowledge surfaces (`KnowledgeSpaceSpec`) describe curated corpora that agents and workflows can consult. Tenant bindings (`AppKnowledgeBinding`) declare which spaces are active, who can use them, and optional usage constraints.\n\n### Binding recap\n\n- `spaceKey` / `spaceVersion`: pointer to the `KnowledgeSpaceSpec`\n- `scope.workflows` / `scope.agents`: explicit allow-lists for consumers\n- `constraints.maxTokensPerQuery` & `constraints.maxQueriesPerMinute`: throttling knobs for LLM-backed search\n- `required`: mark the binding as blocking (defaults to `true`)\n\nAt runtime, `ResolvedAppConfig.knowledge` contains `ResolvedKnowledge` entries with the bound space, active sources, and the binding metadata above.\n\n### KnowledgeAccessGuard\n\n`KnowledgeAccessGuard` (`@lssm/lib.contracts/knowledge/runtime`) centralises the access checks that must run before any workflow/agent reads or mutates a knowledge space.\n\n```ts\nimport { KnowledgeAccessGuard } from '@lssm/lib.contracts/knowledge/runtime';\n\nconst guard = new KnowledgeAccessGuard({\n  disallowWriteCategories: ['external', 'ephemeral'], // default\n  requireWorkflowBinding: true,\n  requireAgentBinding: false,\n});\n\nconst result = guard.checkAccess(resolvedKnowledge, {\n  tenantId,\n  appId,\n  workflowName: 'order-processing',\n  operation: 'read', // or 'write' / 'search'\n}, resolvedAppConfig);\n\nif (!result.allowed) {\n  throw new Error(result.reason);\n}\n```\n\nKey behaviours:\n\n- **Binding**: rejects access when the space is not present in the resolved tenant config.\n- **Category guardrails**: blocks writes to `external` and `ephemeral` spaces by default; allows reads but emits warnings for `ephemeral`.\n- **Workflow/agent scoping**: when `requireWorkflowBinding` or `requireAgentBinding` is enabled, only explicitly authorised consumers may access the space.\n\nUse the guard inside workflow operations or agent resolvers to guarantee multi-tenant isolation and honour data governance rules.\n\n"
+}];
+registerDocBlocks(tech_contracts_knowledge_DocBlocks);
+
+//#endregion
+export { tech_contracts_knowledge_DocBlocks };

package/dist/knowledge/index.js

@@ -1 +1,10 @@
-import{KnowledgeSpaceRegistry as e,makeKnowledgeSpaceKey as t}from"./spec.js";import{productCanonKnowledgeSpace as n,registerProductCanonKnowledgeSpace as r}from"./spaces/product-canon.js";import{registerSupportFaqKnowledgeSpace as i,supportFaqKnowledgeSpace as a}from"./spaces/support-faq.js";import{emailThreadsKnowledgeSpace as o,registerEmailThreadsKnowledgeSpace as s}from"./spaces/email-threads.js";import{registerUploadedDocsKnowledgeSpace as c,uploadedDocsKnowledgeSpace as l}from"./spaces/uploaded-docs.js";import{financialDocsKnowledgeSpace as u,registerFinancialDocsKnowledgeSpace as d}from"./spaces/financial-docs.js";import{financialOverviewKnowledgeSpace as f,registerFinancialOverviewKnowledgeSpace as p}from"./spaces/financial-overview.js";import"./spaces/index.js";export{e as KnowledgeSpaceRegistry,o as emailThreadsKnowledgeSpace,u as financialDocsKnowledgeSpace,f as financialOverviewKnowledgeSpace,t as makeKnowledgeSpaceKey,n as productCanonKnowledgeSpace,s as registerEmailThreadsKnowledgeSpace,d as registerFinancialDocsKnowledgeSpace,p as registerFinancialOverviewKnowledgeSpace,r as registerProductCanonKnowledgeSpace,i as registerSupportFaqKnowledgeSpace,c as registerUploadedDocsKnowledgeSpace,a as supportFaqKnowledgeSpace,l as uploadedDocsKnowledgeSpace};
+import { KnowledgeSpaceRegistry, makeKnowledgeSpaceKey } from "./spec.js";
+import { productCanonKnowledgeSpace, registerProductCanonKnowledgeSpace } from "./spaces/product-canon.js";
+import { registerSupportFaqKnowledgeSpace, supportFaqKnowledgeSpace } from "./spaces/support-faq.js";
+import { emailThreadsKnowledgeSpace, registerEmailThreadsKnowledgeSpace } from "./spaces/email-threads.js";
+import { registerUploadedDocsKnowledgeSpace, uploadedDocsKnowledgeSpace } from "./spaces/uploaded-docs.js";
+import { financialDocsKnowledgeSpace, registerFinancialDocsKnowledgeSpace } from "./spaces/financial-docs.js";
+import { financialOverviewKnowledgeSpace, registerFinancialOverviewKnowledgeSpace } from "./spaces/financial-overview.js";
+import "./spaces/index.js";
+
+export { KnowledgeSpaceRegistry, emailThreadsKnowledgeSpace, financialDocsKnowledgeSpace, financialOverviewKnowledgeSpace, makeKnowledgeSpaceKey, productCanonKnowledgeSpace, registerEmailThreadsKnowledgeSpace, registerFinancialDocsKnowledgeSpace, registerFinancialOverviewKnowledgeSpace, registerProductCanonKnowledgeSpace, registerSupportFaqKnowledgeSpace, registerUploadedDocsKnowledgeSpace, supportFaqKnowledgeSpace, uploadedDocsKnowledgeSpace };

package/dist/knowledge/ingestion/document-processor.js

@@ -1 +1,54 @@
-import{Buffer as e}from"node:buffer";var t=class{extractors=new Map;constructor(){this.registerExtractor(`text/plain`,this.extractText),this.registerExtractor(`application/json`,this.extractJson)}registerExtractor(e,t){this.extractors.set(e.toLowerCase(),t)}async process(e){let t=this.extractors.get(e.mimeType.toLowerCase())??this.extractors.get(`*/*`);if(!t)throw Error(`No extractor registered for mime type ${e.mimeType}`);let n=await t(e);return n.length===0?[{id:`${e.id}:0`,documentId:e.id,text:``,metadata:e.metadata}]:n}async extractText(t){let n=e.from(t.data).toString(`utf-8`);return[{id:`${t.id}:0`,documentId:t.id,text:n,metadata:t.metadata}]}async extractJson(t){let n=e.from(t.data).toString(`utf-8`);try{let e=JSON.parse(n);return[{id:`${t.id}:0`,documentId:t.id,text:JSON.stringify(e,null,2),metadata:{...t.metadata,contentType:`application/json`}}]}catch{return this.extractText(t)}}};export{t as DocumentProcessor};
+import { Buffer } from "node:buffer";
+
+//#region src/knowledge/ingestion/document-processor.ts
+var DocumentProcessor = class {
+	extractors = /* @__PURE__ */ new Map();
+	constructor() {
+		this.registerExtractor("text/plain", this.extractText);
+		this.registerExtractor("application/json", this.extractJson);
+	}
+	registerExtractor(mimeType, extractor) {
+		this.extractors.set(mimeType.toLowerCase(), extractor);
+	}
+	async process(document) {
+		const extractor = this.extractors.get(document.mimeType.toLowerCase()) ?? this.extractors.get("*/*");
+		if (!extractor) throw new Error(`No extractor registered for mime type ${document.mimeType}`);
+		const fragments = await extractor(document);
+		if (fragments.length === 0) return [{
+			id: `${document.id}:0`,
+			documentId: document.id,
+			text: "",
+			metadata: document.metadata
+		}];
+		return fragments;
+	}
+	async extractText(document) {
+		const text = Buffer.from(document.data).toString("utf-8");
+		return [{
+			id: `${document.id}:0`,
+			documentId: document.id,
+			text,
+			metadata: document.metadata
+		}];
+	}
+	async extractJson(document) {
+		const text = Buffer.from(document.data).toString("utf-8");
+		try {
+			const json = JSON.parse(text);
+			return [{
+				id: `${document.id}:0`,
+				documentId: document.id,
+				text: JSON.stringify(json, null, 2),
+				metadata: {
+					...document.metadata,
+					contentType: "application/json"
+				}
+			}];
+		} catch {
+			return this.extractText(document);
+		}
+	}
+};
+
+//#endregion
+export { DocumentProcessor };

package/dist/knowledge/ingestion/embedding-service.js

@@ -1 +1,25 @@
-var e=class{provider;batchSize;constructor(e,t=16){this.provider=e,this.batchSize=t}async embedFragments(e){let t=[];for(let n=0;n<e.length;n+=this.batchSize){let r=e.slice(n,n+this.batchSize).map(e=>({id:e.id,text:e.text,metadata:e.metadata})),i=await this.provider.embedDocuments(r);t.push(...i)}return t}};export{e as EmbeddingService};
+//#region src/knowledge/ingestion/embedding-service.ts
+var EmbeddingService = class {
+	provider;
+	batchSize;
+	constructor(provider, batchSize = 16) {
+		this.provider = provider;
+		this.batchSize = batchSize;
+	}
+	async embedFragments(fragments) {
+		const results = [];
+		for (let i = 0; i < fragments.length; i += this.batchSize) {
+			const documents = fragments.slice(i, i + this.batchSize).map((fragment) => ({
+				id: fragment.id,
+				text: fragment.text,
+				metadata: fragment.metadata
+			}));
+			const embeddings = await this.provider.embedDocuments(documents);
+			results.push(...embeddings);
+		}
+		return results;
+	}
+};
+
+//#endregion
+export { EmbeddingService };

package/dist/knowledge/ingestion/gmail-adapter.js

@@ -1,6 +1,51 @@
-var e=class{constructor(e,t,n,r){this.gmail=e,this.processor=t,this.embeddings=n,this.indexer=r}async syncThreads(e){let t=await this.gmail.listThreads(e);for(let e of t)await this.ingestThread(e)}async ingestThread(e){let t=this.toRawDocument(e),n=await this.processor.process(t),r=await this.embeddings.embedFragments(n);await this.indexer.upsert(n,r)}toRawDocument(e){let n=t(e);return{id:e.id,mimeType:`text/plain`,data:Buffer.from(n,`utf-8`),metadata:{subject:e.subject??``,participants:e.participants.map(e=>e.email).join(`, `),updatedAt:e.updatedAt.toISOString()}}}};function t(e){let t=[`Subject: ${e.subject??``}`,`Snippet: ${e.snippet??``}`],i=e.messages.map(e=>{let t=[`From: ${n(e.from)}`,`To: ${e.to.map(n).join(`, `)}`];e.sentAt&&t.push(`Date: ${e.sentAt.toISOString()}`);let i=e.textBody??r(e.htmlBody??``);return`${t.join(`
-`)}\n\n${i??``}`});return[...t,...i].join(`
+//#region src/knowledge/ingestion/gmail-adapter.ts
+var GmailIngestionAdapter = class {
+	constructor(gmail, processor, embeddings, indexer) {
+		this.gmail = gmail;
+		this.processor = processor;
+		this.embeddings = embeddings;
+		this.indexer = indexer;
+	}
+	async syncThreads(query) {
+		const threads = await this.gmail.listThreads(query);
+		for (const thread of threads) await this.ingestThread(thread);
+	}
+	async ingestThread(thread) {
+		const document = this.toRawDocument(thread);
+		const fragments = await this.processor.process(document);
+		const embeddings = await this.embeddings.embedFragments(fragments);
+		await this.indexer.upsert(fragments, embeddings);
+	}
+	toRawDocument(thread) {
+		const content = composeThreadText(thread);
+		return {
+			id: thread.id,
+			mimeType: "text/plain",
+			data: Buffer.from(content, "utf-8"),
+			metadata: {
+				subject: thread.subject ?? "",
+				participants: thread.participants.map((p) => p.email).join(", "),
+				updatedAt: thread.updatedAt.toISOString()
+			}
+		};
+	}
+};
+function composeThreadText(thread) {
+	const header = [`Subject: ${thread.subject ?? ""}`, `Snippet: ${thread.snippet ?? ""}`];
+	const messageTexts = thread.messages.map((message) => {
+		const parts = [`From: ${formatAddress(message.from)}`, `To: ${message.to.map(formatAddress).join(", ")}`];
+		if (message.sentAt) parts.push(`Date: ${message.sentAt.toISOString()}`);
+		const body = message.textBody ?? stripHtml(message.htmlBody ?? "");
+		return `${parts.join("\n")}\n\n${body ?? ""}`;
+	});
+	return [...header, ...messageTexts].join("\n\n---\n\n");
+}
+function formatAddress(address) {
+	return address.name ? `${address.name} <${address.email}>` : address.email;
+}
+function stripHtml(html) {
+	return html.replace(/<[^>]+>/g, " ");
+}
 
----
-
-`)}function n(e){return e.name?`${e.name} <${e.email}>`:e.email}function r(e){return e.replace(/<[^>]+>/g,` `)}export{e as GmailIngestionAdapter};
+//#endregion
+export { GmailIngestionAdapter };

package/dist/knowledge/ingestion/index.js

@@ -1 +1,7 @@
-import{DocumentProcessor as e}from"./document-processor.js";import{EmbeddingService as t}from"./embedding-service.js";import{GmailIngestionAdapter as n}from"./gmail-adapter.js";import{VectorIndexer as r}from"./vector-indexer.js";import{StorageIngestionAdapter as i}from"./storage-adapter.js";export{e as DocumentProcessor,t as EmbeddingService,n as GmailIngestionAdapter,i as StorageIngestionAdapter,r as VectorIndexer};
+import { DocumentProcessor } from "./document-processor.js";
+import { EmbeddingService } from "./embedding-service.js";
+import { GmailIngestionAdapter } from "./gmail-adapter.js";
+import { VectorIndexer } from "./vector-indexer.js";
+import { StorageIngestionAdapter } from "./storage-adapter.js";
+
+export { DocumentProcessor, EmbeddingService, GmailIngestionAdapter, StorageIngestionAdapter, VectorIndexer };

package/dist/knowledge/ingestion/storage-adapter.js

@@ -1 +1,26 @@
-var e=class{constructor(e,t,n){this.processor=e,this.embeddings=t,this.indexer=n}async ingestObject(e){if(!(`data`in e)||!e.data)throw Error(`Storage ingestion requires object data`);let t={id:e.key,mimeType:e.contentType??`application/octet-stream`,data:e.data,metadata:{bucket:e.bucket,checksum:e.checksum??``}},n=await this.processor.process(t),r=await this.embeddings.embedFragments(n);await this.indexer.upsert(n,r)}};export{e as StorageIngestionAdapter};
+//#region src/knowledge/ingestion/storage-adapter.ts
+var StorageIngestionAdapter = class {
+	constructor(processor, embeddings, indexer) {
+		this.processor = processor;
+		this.embeddings = embeddings;
+		this.indexer = indexer;
+	}
+	async ingestObject(object) {
+		if (!("data" in object) || !object.data) throw new Error("Storage ingestion requires object data");
+		const raw = {
+			id: object.key,
+			mimeType: object.contentType ?? "application/octet-stream",
+			data: object.data,
+			metadata: {
+				bucket: object.bucket,
+				checksum: object.checksum ?? ""
+			}
+		};
+		const fragments = await this.processor.process(raw);
+		const embeddings = await this.embeddings.embedFragments(fragments);
+		await this.indexer.upsert(fragments, embeddings);
+	}
+};
+
+//#endregion
+export { StorageIngestionAdapter };

package/dist/knowledge/ingestion/vector-indexer.js

@@ -1 +1,32 @@
-var e=class{provider;config;constructor(e,t){this.provider=e,this.config=t}async upsert(e,t){let n=t.map(t=>{let n=e.find(e=>e.id===t.id);return{id:t.id,vector:t.vector,payload:{...this.config.metadata,...n?.metadata??{},documentId:n?.documentId},namespace:this.config.namespace}}),r={collection:this.config.collection,documents:n};await this.provider.upsert(r)}};export{e as VectorIndexer};
+//#region src/knowledge/ingestion/vector-indexer.ts
+var VectorIndexer = class {
+	provider;
+	config;
+	constructor(provider, config) {
+		this.provider = provider;
+		this.config = config;
+	}
+	async upsert(fragments, embeddings) {
+		const documents = embeddings.map((embedding) => {
+			const fragment = fragments.find((f) => f.id === embedding.id);
+			return {
+				id: embedding.id,
+				vector: embedding.vector,
+				payload: {
+					...this.config.metadata,
+					...fragment?.metadata ?? {},
+					documentId: fragment?.documentId
+				},
+				namespace: this.config.namespace
+			};
+		});
+		const request = {
+			collection: this.config.collection,
+			documents
+		};
+		await this.provider.upsert(request);
+	}
+};
+
+//#endregion
+export { VectorIndexer };

package/dist/knowledge/query/index.js

@@ -1 +1,3 @@
-import{KnowledgeQueryService as e}from"./service.js";export{e as KnowledgeQueryService};
+import { KnowledgeQueryService } from "./service.js";
+
+export { KnowledgeQueryService };

package/dist/knowledge/query/service.js

@@ -1,3 +1,65 @@
-var e=class{embeddings;vectorStore;llm;config;constructor(e,t,n,r){this.embeddings=e,this.vectorStore=t,this.llm=n,this.config=r}async query(e){let r=await this.embeddings.embedQuery(e),i=await this.vectorStore.search({collection:this.config.collection,vector:r.vector,topK:this.config.topK??5,namespace:this.config.namespace,filter:void 0}),a=t(i),o=this.buildMessages(e,a),s=await this.llm.chat(o);return{answer:s.message.content.map(e=>`text`in e?e.text:``).join(``),references:i.map(e=>({...e,text:n(e)})),usage:s.usage}}buildMessages(e,t){return[{role:`system`,content:[{type:`text`,text:this.config.systemPrompt??`You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.`}]},{role:`user`,content:[{type:`text`,text:`Question:\n${e}\n\nContext:\n${t}`}]}]}};function t(e){return e.length===0?`No relevant documents found.`:e.map((e,t)=>{let r=n(e);return`Source ${t+1} (score: ${e.score.toFixed(3)}):\n${r}`}).join(`
+//#region src/knowledge/query/service.ts
+var KnowledgeQueryService = class {
+	embeddings;
+	vectorStore;
+	llm;
+	config;
+	constructor(embeddings, vectorStore, llm, config) {
+		this.embeddings = embeddings;
+		this.vectorStore = vectorStore;
+		this.llm = llm;
+		this.config = config;
+	}
+	async query(question) {
+		const embedding = await this.embeddings.embedQuery(question);
+		const results = await this.vectorStore.search({
+			collection: this.config.collection,
+			vector: embedding.vector,
+			topK: this.config.topK ?? 5,
+			namespace: this.config.namespace,
+			filter: void 0
+		});
+		const context = buildContext(results);
+		const messages = this.buildMessages(question, context);
+		const response = await this.llm.chat(messages);
+		return {
+			answer: response.message.content.map((part) => "text" in part ? part.text : "").join(""),
+			references: results.map((result) => ({
+				...result,
+				text: extractText(result)
+			})),
+			usage: response.usage
+		};
+	}
+	buildMessages(question, context) {
+		return [{
+			role: "system",
+			content: [{
+				type: "text",
+				text: this.config.systemPrompt ?? "You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible."
+			}]
+		}, {
+			role: "user",
+			content: [{
+				type: "text",
+				text: `Question:\n${question}\n\nContext:\n${context}`
+			}]
+		}];
+	}
+};
+function buildContext(results) {
+	if (results.length === 0) return "No relevant documents found.";
+	return results.map((result, index) => {
+		const text = extractText(result);
+		return `Source ${index + 1} (score: ${result.score.toFixed(3)}):\n${text}`;
+	}).join("\n\n");
+}
+function extractText(result) {
+	const payload = result.payload ?? {};
+	if (typeof payload.text === "string") return payload.text;
+	if (typeof payload.content === "string") return payload.content;
+	return JSON.stringify(payload);
+}
 
-`)}function n(e){let t=e.payload??{};return typeof t.text==`string`?t.text:typeof t.content==`string`?t.content:JSON.stringify(t)}export{e as KnowledgeQueryService};
+//#endregion
+export { KnowledgeQueryService };

package/dist/knowledge/runtime.js

@@ -1 +1,49 @@
-const e=[`external`,`ephemeral`];var t=class{disallowedWrite;requireWorkflowBinding;requireAgentBinding;constructor(t={}){this.disallowedWrite=new Set(t.disallowWriteCategories??e),this.requireWorkflowBinding=t.requireWorkflowBinding??!0,this.requireAgentBinding=t.requireAgentBinding??!1}checkAccess(e,t,n){let{binding:r,space:i}=e;if(r.required!==!1&&!this.isSpaceBound(e,n))return{allowed:!1,reason:`Knowledge space "${i.meta.key}" is not bound in the resolved app config.`};if(t.operation===`write`&&this.disallowedWrite.has(i.meta.category))return{allowed:!1,reason:`Knowledge space "${i.meta.key}" is category "${i.meta.category}" and is read-only.`};if(this.requireWorkflowBinding&&t.workflowName){let e=r.scope?.workflows;if(e&&!e.includes(t.workflowName))return{allowed:!1,reason:`Workflow "${t.workflowName}" is not authorized to access knowledge space "${i.meta.key}".`}}if(this.requireAgentBinding&&t.agentName){let e=r.scope?.agents;if(e&&!e.includes(t.agentName))return{allowed:!1,reason:`Agent "${t.agentName}" is not authorized to access knowledge space "${i.meta.key}".`}}return i.meta.category===`ephemeral`?{allowed:!0,severity:`warning`,reason:`Knowledge space "${i.meta.key}" is ephemeral; results may be transient.`}:{allowed:!0}}isSpaceBound(e,t){return t.knowledge.some(t=>t.space.meta.key===e.space.meta.key&&(e.space.meta.version==null||t.space.meta.version===e.space.meta.version))}};export{t as KnowledgeAccessGuard};
+//#region src/knowledge/runtime.ts
+const DEFAULT_DISALLOWED_WRITE = ["external", "ephemeral"];
+var KnowledgeAccessGuard = class {
+	disallowedWrite;
+	requireWorkflowBinding;
+	requireAgentBinding;
+	constructor(options = {}) {
+		this.disallowedWrite = new Set(options.disallowWriteCategories ?? DEFAULT_DISALLOWED_WRITE);
+		this.requireWorkflowBinding = options.requireWorkflowBinding ?? true;
+		this.requireAgentBinding = options.requireAgentBinding ?? false;
+	}
+	checkAccess(spaceBinding, context, appConfig) {
+		const { binding, space } = spaceBinding;
+		if (binding.required !== false && !this.isSpaceBound(spaceBinding, appConfig)) return {
+			allowed: false,
+			reason: `Knowledge space "${space.meta.key}" is not bound in the resolved app config.`
+		};
+		if (context.operation === "write" && this.disallowedWrite.has(space.meta.category)) return {
+			allowed: false,
+			reason: `Knowledge space "${space.meta.key}" is category "${space.meta.category}" and is read-only.`
+		};
+		if (this.requireWorkflowBinding && context.workflowName) {
+			const allowedWorkflows = binding.scope?.workflows;
+			if (allowedWorkflows && !allowedWorkflows.includes(context.workflowName)) return {
+				allowed: false,
+				reason: `Workflow "${context.workflowName}" is not authorized to access knowledge space "${space.meta.key}".`
+			};
+		}
+		if (this.requireAgentBinding && context.agentName) {
+			const allowedAgents = binding.scope?.agents;
+			if (allowedAgents && !allowedAgents.includes(context.agentName)) return {
+				allowed: false,
+				reason: `Agent "${context.agentName}" is not authorized to access knowledge space "${space.meta.key}".`
+			};
+		}
+		if (space.meta.category === "ephemeral") return {
+			allowed: true,
+			severity: "warning",
+			reason: `Knowledge space "${space.meta.key}" is ephemeral; results may be transient.`
+		};
+		return { allowed: true };
+	}
+	isSpaceBound(resolved, appConfig) {
+		return appConfig.knowledge.some((entry) => entry.space.meta.key === resolved.space.meta.key && (resolved.space.meta.version == null || entry.space.meta.version === resolved.space.meta.version));
+	}
+};
+
+//#endregion
+export { KnowledgeAccessGuard };

package/dist/knowledge/spaces/email-threads.js

@@ -1 +1,38 @@
-import{StabilityEnum as e}from"../../ownership.js";const t={meta:{key:`knowledge.email-threads`,version:1,category:`operational`,displayName:`Email Threads`,title:`Operational Email Threads`,description:`Indexed copies of operational email threads used for support, onboarding, and workflows.`,domain:`operations`,owners:[`platform.operations`],tags:[`email`,`operations`],stability:e.Beta},retention:{ttlDays:365},access:{policy:{name:`knowledge.access.email-threads`,version:1},trustLevel:`medium`,automationWritable:!0},indexing:{embeddingModel:`mistral-embed`,chunkSize:600,vectorDbIntegration:`vectordb.qdrant`},description:`Operational email threads synchronized from Gmail to support automations and contextual assistance.`};function n(e){return e.register(t)}export{t as emailThreadsKnowledgeSpace,n as registerEmailThreadsKnowledgeSpace};
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/knowledge/spaces/email-threads.ts
+const emailThreadsKnowledgeSpace = {
+	meta: {
+		key: "knowledge.email-threads",
+		version: 1,
+		category: "operational",
+		displayName: "Email Threads",
+		title: "Operational Email Threads",
+		description: "Indexed copies of operational email threads used for support, onboarding, and workflows.",
+		domain: "operations",
+		owners: ["platform.operations"],
+		tags: ["email", "operations"],
+		stability: StabilityEnum.Beta
+	},
+	retention: { ttlDays: 365 },
+	access: {
+		policy: {
+			name: "knowledge.access.email-threads",
+			version: 1
+		},
+		trustLevel: "medium",
+		automationWritable: true
+	},
+	indexing: {
+		embeddingModel: "mistral-embed",
+		chunkSize: 600,
+		vectorDbIntegration: "vectordb.qdrant"
+	},
+	description: "Operational email threads synchronized from Gmail to support automations and contextual assistance."
+};
+function registerEmailThreadsKnowledgeSpace(registry) {
+	return registry.register(emailThreadsKnowledgeSpace);
+}
+
+//#endregion
+export { emailThreadsKnowledgeSpace, registerEmailThreadsKnowledgeSpace };

package/dist/knowledge/spaces/financial-docs.js

@@ -1 +1,38 @@
-import{StabilityEnum as e}from"../../ownership.js";const t={meta:{key:`knowledge.financial-docs`,version:1,category:`canonical`,displayName:`Financial Documents`,title:`Household Financial Documents`,description:`Invoices, bills, and contracts powering Pocket Family Office financial automation.`,domain:`finance`,owners:[`platform.finance`],tags:[`finance`,`documents`],stability:e.Beta},retention:{ttlDays:null},access:{policy:{name:`knowledge.access.financial-docs`,version:1},trustLevel:`high`,automationWritable:!0},indexing:{embeddingModel:`mistral-embed`,chunkSize:700,vectorDbIntegration:`vectordb.qdrant`},description:`Normalized financial documents enabling bill pay automation, reminders, and summaries.`};function n(e){return e.register(t)}export{t as financialDocsKnowledgeSpace,n as registerFinancialDocsKnowledgeSpace};
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/knowledge/spaces/financial-docs.ts
+const financialDocsKnowledgeSpace = {
+	meta: {
+		key: "knowledge.financial-docs",
+		version: 1,
+		category: "canonical",
+		displayName: "Financial Documents",
+		title: "Household Financial Documents",
+		description: "Invoices, bills, and contracts powering Pocket Family Office financial automation.",
+		domain: "finance",
+		owners: ["platform.finance"],
+		tags: ["finance", "documents"],
+		stability: StabilityEnum.Beta
+	},
+	retention: { ttlDays: null },
+	access: {
+		policy: {
+			name: "knowledge.access.financial-docs",
+			version: 1
+		},
+		trustLevel: "high",
+		automationWritable: true
+	},
+	indexing: {
+		embeddingModel: "mistral-embed",
+		chunkSize: 700,
+		vectorDbIntegration: "vectordb.qdrant"
+	},
+	description: "Normalized financial documents enabling bill pay automation, reminders, and summaries."
+};
+function registerFinancialDocsKnowledgeSpace(registry) {
+	return registry.register(financialDocsKnowledgeSpace);
+}
+
+//#endregion
+export { financialDocsKnowledgeSpace, registerFinancialDocsKnowledgeSpace };