@lssm/lib.contracts 1.41.0 → 1.42.1

package/dist/jobs/scaleway-sqs-queue.js

@@ -1 +1,153 @@
-import{DEFAULT_RETRY_POLICY as e}from"./queue.js";import{randomUUID as t}from"crypto";import{DeleteMessageCommand as n,ReceiveMessageCommand as r,SQSClient as i,SendMessageCommand as a}from"@aws-sdk/client-sqs";var o=class{sqs;queueUrl;waitTimeSeconds;maxNumberOfMessages;visibilityTimeoutSeconds;handlers=new Map;running=!1;constructor(e){let t=process.env.SCALEWAY_ACCESS_KEY_QUEUE,n=process.env.SCALEWAY_SECRET_KEY_QUEUE;if(!t||!n)throw Error(`Missing SCALEWAY_ACCESS_KEY_QUEUE / SCALEWAY_SECRET_KEY_QUEUE in env`);this.sqs=new i({region:e.region??process.env.SCALEWAY_REGION??`par`,endpoint:`https://sqs.mnq.fr-par.scaleway.com`,credentials:{accessKeyId:t,secretAccessKey:n}}),this.queueUrl=e.queueUrl,this.waitTimeSeconds=e.waitTimeSeconds??20,this.maxNumberOfMessages=e.maxNumberOfMessages??5,this.visibilityTimeoutSeconds=e.visibilityTimeoutSeconds??60}async enqueue(n,r,i={}){let o=t(),s=new Date,c={id:o,type:n,payload:r};return await this.sqs.send(new a({QueueUrl:this.queueUrl,MessageBody:JSON.stringify(c),DelaySeconds:i.delaySeconds??0})),{id:o,type:n,version:1,payload:r,status:`pending`,priority:i.priority??0,attempts:0,maxRetries:i.maxRetries??e.maxRetries,createdAt:s,updatedAt:s}}register(e,t){if(this.handlers.has(e))throw Error(`Handler already registered for job type "${e}"`);this.handlers.set(e,t)}start(){this.running||(this.running=!0,this.pollLoop().catch(e=>{console.error(`[queue] Fatal error in poll loop`,e),process.exit(1)}))}async stop(){this.running=!1}async pollLoop(){for(console.log(`[queue] SQS worker started for queue:`,this.queueUrl);this.running;)try{let t=(await this.sqs.send(new r({QueueUrl:this.queueUrl,MaxNumberOfMessages:this.maxNumberOfMessages,WaitTimeSeconds:this.waitTimeSeconds,VisibilityTimeout:this.visibilityTimeoutSeconds,MessageSystemAttributeNames:[`ApproximateReceiveCount`]}))).Messages??[];if(t.length===0)continue;for(let n of t){if(!n.Body||!n.ReceiptHandle){console.warn(`[queue] Message missing Body or ReceiptHandle`,n.MessageId);continue}let t;try{t=JSON.parse(n.Body)}catch(e){console.error(`[queue] Failed to parse message body (id=${n.MessageId}), deleting`,e),await this.deleteMessage(n.ReceiptHandle);continue}let r=this.handlers.get(t.type);if(!r){console.error(`[queue] No handler registered for type "${t.type}", deleting message`),await this.deleteMessage(n.ReceiptHandle);continue}let i=new Date,a=parseInt(n.Attributes?.ApproximateReceiveCount??`1`,10),o={id:t.id,type:t.type,version:1,payload:t.payload,status:`pending`,priority:0,attempts:a,maxRetries:e.maxRetries,createdAt:i,updatedAt:i};o.status=`running`,o.updatedAt=new Date;try{await r(o),o.status=`completed`,o.updatedAt=new Date,await this.deleteMessage(n.ReceiptHandle)}catch(e){o.status=`failed`,o.lastError=e instanceof Error?e.message:`Unknown job error`,o.updatedAt=new Date,console.error(`[queue] Error while handling job type=${o.type} id=${o.id}`,e)}}}catch(e){e&&typeof e==`object`&&`$response`in e?console.error(`[queue] Error while polling SQS`,e,e.$response):console.error(`[queue] Error while polling SQS`,e),await this.sleep(5e3)}console.log(`[queue] SQS worker stopped`)}async deleteMessage(e){try{await this.sqs.send(new n({QueueUrl:this.queueUrl,ReceiptHandle:e}))}catch(e){console.error(`[queue] Failed to delete message`,e)}}async sleep(e){await new Promise(t=>setTimeout(t,e))}};export{o as ScalewaySqsJobQueue};
+import { DEFAULT_RETRY_POLICY } from "./queue.js";
+import { randomUUID } from "crypto";
+import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
+
+//#region src/jobs/scaleway-sqs-queue.ts
+var ScalewaySqsJobQueue = class {
+	sqs;
+	queueUrl;
+	waitTimeSeconds;
+	maxNumberOfMessages;
+	visibilityTimeoutSeconds;
+	handlers = /* @__PURE__ */ new Map();
+	running = false;
+	constructor(config) {
+		const accessKeyId = process.env.SCALEWAY_ACCESS_KEY_QUEUE;
+		const secretAccessKey = process.env.SCALEWAY_SECRET_KEY_QUEUE;
+		if (!accessKeyId || !secretAccessKey) throw new Error("Missing SCALEWAY_ACCESS_KEY_QUEUE / SCALEWAY_SECRET_KEY_QUEUE in env");
+		this.sqs = new SQSClient({
+			region: config.region ?? process.env.SCALEWAY_REGION ?? "par",
+			endpoint: "https://sqs.mnq.fr-par.scaleway.com",
+			credentials: {
+				accessKeyId,
+				secretAccessKey
+			}
+		});
+		this.queueUrl = config.queueUrl;
+		this.waitTimeSeconds = config.waitTimeSeconds ?? 20;
+		this.maxNumberOfMessages = config.maxNumberOfMessages ?? 5;
+		this.visibilityTimeoutSeconds = config.visibilityTimeoutSeconds ?? 60;
+	}
+	async enqueue(jobType, payload, options = {}) {
+		const id = randomUUID();
+		const now = /* @__PURE__ */ new Date();
+		const envelope = {
+			id,
+			type: jobType,
+			payload
+		};
+		await this.sqs.send(new SendMessageCommand({
+			QueueUrl: this.queueUrl,
+			MessageBody: JSON.stringify(envelope),
+			DelaySeconds: options.delaySeconds ?? 0
+		}));
+		return {
+			id,
+			type: jobType,
+			version: 1,
+			payload,
+			status: "pending",
+			priority: options.priority ?? 0,
+			attempts: 0,
+			maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+			createdAt: now,
+			updatedAt: now
+		};
+	}
+	register(jobType, handler) {
+		if (this.handlers.has(jobType)) throw new Error(`Handler already registered for job type "${jobType}"`);
+		this.handlers.set(jobType, handler);
+	}
+	start() {
+		if (this.running) return;
+		this.running = true;
+		this.pollLoop().catch((err) => {
+			console.error("[queue] Fatal error in poll loop", err);
+			process.exit(1);
+		});
+	}
+	async stop() {
+		this.running = false;
+	}
+	async pollLoop() {
+		console.log("[queue] SQS worker started for queue:", this.queueUrl);
+		while (this.running) try {
+			const messages = (await this.sqs.send(new ReceiveMessageCommand({
+				QueueUrl: this.queueUrl,
+				MaxNumberOfMessages: this.maxNumberOfMessages,
+				WaitTimeSeconds: this.waitTimeSeconds,
+				VisibilityTimeout: this.visibilityTimeoutSeconds,
+				MessageSystemAttributeNames: ["ApproximateReceiveCount"]
+			}))).Messages ?? [];
+			if (messages.length === 0) continue;
+			for (const msg of messages) {
+				if (!msg.Body || !msg.ReceiptHandle) {
+					console.warn("[queue] Message missing Body or ReceiptHandle", msg.MessageId);
+					continue;
+				}
+				let envelope;
+				try {
+					envelope = JSON.parse(msg.Body);
+				} catch (err) {
+					console.error(`[queue] Failed to parse message body (id=${msg.MessageId}), deleting`, err);
+					await this.deleteMessage(msg.ReceiptHandle);
+					continue;
+				}
+				const handler = this.handlers.get(envelope.type);
+				if (!handler) {
+					console.error(`[queue] No handler registered for type "${envelope.type}", deleting message`);
+					await this.deleteMessage(msg.ReceiptHandle);
+					continue;
+				}
+				const now = /* @__PURE__ */ new Date();
+				const attempts = parseInt(msg.Attributes?.ApproximateReceiveCount ?? "1", 10);
+				const job = {
+					id: envelope.id,
+					type: envelope.type,
+					version: 1,
+					payload: envelope.payload,
+					status: "pending",
+					priority: 0,
+					attempts,
+					maxRetries: DEFAULT_RETRY_POLICY.maxRetries,
+					createdAt: now,
+					updatedAt: now
+				};
+				job.status = "running";
+				job.updatedAt = /* @__PURE__ */ new Date();
+				try {
+					await handler(job);
+					job.status = "completed";
+					job.updatedAt = /* @__PURE__ */ new Date();
+					await this.deleteMessage(msg.ReceiptHandle);
+				} catch (err) {
+					job.status = "failed";
+					job.lastError = err instanceof Error ? err.message : "Unknown job error";
+					job.updatedAt = /* @__PURE__ */ new Date();
+					console.error(`[queue] Error while handling job type=${job.type} id=${job.id}`, err);
+				}
+			}
+		} catch (err) {
+			if (!!err && typeof err === "object" && "$response" in err) console.error("[queue] Error while polling SQS", err, err.$response);
+			else console.error("[queue] Error while polling SQS", err);
+			await this.sleep(5e3);
+		}
+		console.log("[queue] SQS worker stopped");
+	}
+	async deleteMessage(receiptHandle) {
+		try {
+			await this.sqs.send(new DeleteMessageCommand({
+				QueueUrl: this.queueUrl,
+				ReceiptHandle: receiptHandle
+			}));
+		} catch (err) {
+			console.error("[queue] Failed to delete message", err);
+		}
+	}
+	async sleep(ms) {
+		await new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+
+//#endregion
+export { ScalewaySqsJobQueue };

package/dist/jsonschema.d.ts

@@ -0,0 +1,28 @@
+import { Stability, Tag } from "./ownership.js";
+import "./operations/index.js";
+import { OpKind, OperationSpec } from "./operations/operation.js";
+import * as _lssm_lib_schema0 from "@lssm/lib.schema";
+import { AnySchemaModel } from "@lssm/lib.schema";
+import z from "zod";
+
+//#region src/jsonschema.d.ts
+declare function jsonSchemaForSpec(spec: OperationSpec<AnySchemaModel, AnySchemaModel>): {
+  input: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema0.TopLevelZodFromModel<_lssm_lib_schema0.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema0.AnyFieldType | _lssm_lib_schema0.AnyEnumType>>> | null;
+  output: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema0.TopLevelZodFromModel<_lssm_lib_schema0.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema0.AnyFieldType | _lssm_lib_schema0.AnyEnumType>>> | null;
+  meta: {
+    name: string;
+    version: number;
+    kind: OpKind;
+    description: string;
+    tags: Tag[];
+    stability: Stability;
+  };
+};
+/** Helper to derive default REST path */
+declare function defaultRestPath(name: string, version: number): string;
+/** Helper to derive default MCP tool name */
+declare function defaultMcpTool(name: string, version: number): string;
+/** Helper to derive default GraphQL field name */
+declare function defaultGqlField(name: string, version: number): string;
+//#endregion
+export { defaultGqlField, defaultMcpTool, defaultRestPath, jsonSchemaForSpec };

package/dist/jsonschema.js

@@ -1 +1,32 @@
-import e from"zod";function t(t){return{input:t.io.input?e.toJSONSchema(t.io.input.getZod()):null,output:t.io.output?e.toJSONSchema(t.io.output.getZod()):null,meta:{name:t.meta.name,version:t.meta.version,kind:t.meta.kind,description:t.meta.description,tags:t.meta.tags??[],stability:t.meta.stability??`stable`}}}function n(e,t){return`/${e.replace(/\./g,`/`)}/v${t}`}function r(e,t){return`${e}.v${t}`}function i(e,t){return`${e.replace(/\./g,`_`)}_v${t}`}export{i as defaultGqlField,r as defaultMcpTool,n as defaultRestPath,t as jsonSchemaForSpec};
+import z from "zod";
+
+//#region src/jsonschema.ts
+function jsonSchemaForSpec(spec) {
+	return {
+		input: spec.io.input ? z.toJSONSchema(spec.io.input.getZod()) : null,
+		output: spec.io.output ? z.toJSONSchema(spec.io.output.getZod()) : null,
+		meta: {
+			name: spec.meta.key,
+			version: spec.meta.version,
+			kind: spec.meta.kind,
+			description: spec.meta.description,
+			tags: spec.meta.tags ?? [],
+			stability: spec.meta.stability ?? "stable"
+		}
+	};
+}
+/** Helper to derive default REST path */
+function defaultRestPath(name, version) {
+	return `/${name.replace(/\./g, "/")}/v${version}`;
+}
+/** Helper to derive default MCP tool name */
+function defaultMcpTool(name, version) {
+	return `${name}-v${version}`;
+}
+/** Helper to derive default GraphQL field name */
+function defaultGqlField(name, version) {
+	return `${name.replace(/\./g, "_")}_v${version}`;
+}
+
+//#endregion
+export { defaultGqlField, defaultMcpTool, defaultRestPath, jsonSchemaForSpec };

package/dist/knowledge/binding.d.ts

@@ -0,0 +1,25 @@
+//#region src/knowledge/binding.d.ts
+interface AppKnowledgeBinding {
+  /** Which KnowledgeSpace to use. */
+  spaceKey: string;
+  spaceVersion?: number;
+  /** Optional: scope to specific workflows/agents. */
+  scope?: {
+    workflows?: string[];
+    agents?: string[];
+    operations?: string[];
+  };
+  /** Usage constraints. */
+  constraints?: {
+    /** Max tokens per query. */
+    maxTokensPerQuery?: number;
+    /** Max queries per minute. */
+    maxQueriesPerMinute?: number;
+  };
+  /** Priority when multiple spaces overlap. */
+  priority?: number;
+  /** Whether access to the space is required (blocking) or optional. */
+  required?: boolean;
+}
+//#endregion
+export { AppKnowledgeBinding };

package/dist/knowledge/docs/knowledge.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@lssm/lib.contracts/docs";
+
+//#region src/knowledge/docs/knowledge.docblock.d.ts
+declare const tech_contracts_knowledge_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_knowledge_DocBlocks };

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

@@ -1,138 +1,21 @@
-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";
+
+//#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.d.ts

@@ -0,0 +1,11 @@
+import { KnowledgeAccessPolicy, KnowledgeCategory, KnowledgeIndexingConfig, KnowledgeRetentionPolicy, KnowledgeSpaceMeta, KnowledgeSpaceRegistry, KnowledgeSpaceSpec, makeKnowledgeSpaceKey } from "./spec.js";
+import { KnowledgeSourceConfig, KnowledgeSourceMeta, KnowledgeSourceType } from "./source.js";
+import { AppKnowledgeBinding } from "./binding.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 { AppKnowledgeBinding, KnowledgeAccessPolicy, KnowledgeCategory, KnowledgeIndexingConfig, KnowledgeRetentionPolicy, KnowledgeSourceConfig, KnowledgeSourceMeta, KnowledgeSourceType, KnowledgeSpaceMeta, KnowledgeSpaceRegistry, KnowledgeSpaceSpec, emailThreadsKnowledgeSpace, financialDocsKnowledgeSpace, financialOverviewKnowledgeSpace, makeKnowledgeSpaceKey, productCanonKnowledgeSpace, registerEmailThreadsKnowledgeSpace, registerFinancialDocsKnowledgeSpace, registerFinancialOverviewKnowledgeSpace, registerProductCanonKnowledgeSpace, registerSupportFaqKnowledgeSpace, registerUploadedDocsKnowledgeSpace, supportFaqKnowledgeSpace, uploadedDocsKnowledgeSpace };

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.d.ts

@@ -0,0 +1,24 @@
+//#region src/knowledge/ingestion/document-processor.d.ts
+interface RawDocument {
+  id: string;
+  mimeType: string;
+  data: Uint8Array;
+  metadata?: Record<string, string>;
+}
+interface DocumentFragment {
+  id: string;
+  documentId: string;
+  text: string;
+  metadata?: Record<string, string>;
+}
+type Extractor = (input: RawDocument) => Promise<DocumentFragment[]>;
+declare class DocumentProcessor {
+  private readonly extractors;
+  constructor();
+  registerExtractor(mimeType: string, extractor: Extractor): void;
+  process(document: RawDocument): Promise<DocumentFragment[]>;
+  private extractText;
+  private extractJson;
+}
+//#endregion
+export { DocumentFragment, DocumentProcessor, RawDocument };

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.d.ts

@@ -0,0 +1,12 @@
+import { EmbeddingProvider, EmbeddingResult } from "../../integrations/providers/embedding.js";
+import { DocumentFragment } from "./document-processor.js";
+
+//#region src/knowledge/ingestion/embedding-service.d.ts
+declare class EmbeddingService {
+  private readonly provider;
+  private readonly batchSize;
+  constructor(provider: EmbeddingProvider, batchSize?: number);
+  embedFragments(fragments: DocumentFragment[]): Promise<EmbeddingResult[]>;
+}
+//#endregion
+export { EmbeddingService };

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.d.ts

@@ -0,0 +1,18 @@
+import { EmailInboundProvider, EmailThread } from "../../integrations/providers/email.js";
+import { DocumentProcessor } from "./document-processor.js";
+import { EmbeddingService } from "./embedding-service.js";
+import { VectorIndexer } from "./vector-indexer.js";
+
+//#region src/knowledge/ingestion/gmail-adapter.d.ts
+declare class GmailIngestionAdapter {
+  private readonly gmail;
+  private readonly processor;
+  private readonly embeddings;
+  private readonly indexer;
+  constructor(gmail: EmailInboundProvider, processor: DocumentProcessor, embeddings: EmbeddingService, indexer: VectorIndexer);
+  syncThreads(query?: Parameters<EmailInboundProvider['listThreads']>[0]): Promise<void>;
+  ingestThread(thread: EmailThread): Promise<void>;
+  private toRawDocument;
+}
+//#endregion
+export { GmailIngestionAdapter };

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 };