@lssm/lib.contracts 0.0.0-canary-20251217062943 → 0.0.0-canary-20251217072406

package/dist/knowledge/contracts.js

@@ -1 +1,317 @@
-import{l as e}from"../schema/dist/ScalarTypeEnum.js";import{t}from"../schema/dist/SchemaModel.js";import"../schema/dist/index.js";import{defineCommand as n,defineQuery as r}from"../spec.js";const i=new t({name:`KnowledgeSyncSchedule`,fields:{enabled:{type:e.Boolean(),isOptional:!1},cron:{type:e.String_unsecure(),isOptional:!0},intervalMs:{type:e.Int_unsecure(),isOptional:!0}}}),a=new t({name:`KnowledgeSourceRecord`,fields:{id:{type:e.ID(),isOptional:!1},tenantId:{type:e.ID(),isOptional:!1},spaceKey:{type:e.NonEmptyString(),isOptional:!1},spaceVersion:{type:e.Int_unsecure(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!1},sourceType:{type:e.String_unsecure(),isOptional:!1},syncSchedule:{type:i,isOptional:!0},lastSyncStatus:{type:e.String_unsecure(),isOptional:!0},lastSyncAt:{type:e.DateTime(),isOptional:!0},itemsProcessed:{type:e.Int_unsecure(),isOptional:!0},createdAt:{type:e.DateTime(),isOptional:!0},updatedAt:{type:e.DateTime(),isOptional:!0}}}),o=new t({name:`CreateKnowledgeSourceInput`,fields:{tenantId:{type:e.ID(),isOptional:!1},spaceKey:{type:e.NonEmptyString(),isOptional:!1},spaceVersion:{type:e.Int_unsecure(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!1},sourceType:{type:e.NonEmptyString(),isOptional:!1},config:{type:e.JSONObject(),isOptional:!1},syncSchedule:{type:i,isOptional:!0}}}),s=new t({name:`UpdateKnowledgeSourceInput`,fields:{sourceId:{type:e.ID(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!0},config:{type:e.JSONObject(),isOptional:!0},syncSchedule:{type:i,isOptional:!0}}}),c=new t({name:`DeleteKnowledgeSourceInput`,fields:{sourceId:{type:e.ID(),isOptional:!1}}}),l=new t({name:`DeleteKnowledgeSourceOutput`,fields:{success:{type:e.Boolean(),isOptional:!1}}}),u=new t({name:`ListKnowledgeSourcesInput`,fields:{tenantId:{type:e.ID(),isOptional:!1},spaceKey:{type:e.NonEmptyString(),isOptional:!0}}}),d=new t({name:`ListKnowledgeSourcesOutput`,fields:{sources:{type:a,isOptional:!1,isArray:!0}}}),f=new t({name:`TriggerKnowledgeSyncInput`,fields:{sourceId:{type:e.ID(),isOptional:!1}}}),p=new t({name:`TriggerKnowledgeSyncOutput`,fields:{success:{type:e.Boolean(),isOptional:!1},itemsProcessed:{type:e.Int_unsecure(),isOptional:!0},error:{type:e.String_unsecure(),isOptional:!0}}}),m=n({meta:{name:`knowledge.source.create`,version:1,description:`Create a knowledge source binding for a tenant.`,goal:`Onboard a new knowledge ingestion source such as Notion or uploads.`,context:`Used by Ops and App Studio to configure knowledge ingestion per tenant and space.`,owners:[`platform.knowledge`],tags:[`knowledge`,`sources`],stability:`experimental`},io:{input:o,output:a},policy:{auth:`admin`,policies:[{name:`platform.knowledge.manage`,version:1}]}}),h=n({meta:{name:`knowledge.source.update`,version:1,description:`Update metadata or configuration for a knowledge source.`,goal:`Allow rotation of credentials, sync schedules, and labels.`,context:`Supports editing how a tenant ingests knowledge (e.g., toggling sync cadence).`,owners:[`platform.knowledge`],tags:[`knowledge`,`sources`],stability:`experimental`},io:{input:s,output:a},policy:{auth:`admin`,policies:[{name:`platform.knowledge.manage`,version:1}]}}),g=n({meta:{name:`knowledge.source.delete`,version:1,description:`Delete a knowledge source binding for a tenant.`,goal:`Remove obsolete or compromised knowledge ingestion paths.`,context:`Ensures ephemeral or external sources can be removed cleanly without leaving residual bindings.`,owners:[`platform.knowledge`],tags:[`knowledge`,`sources`],stability:`experimental`},io:{input:c,output:l},policy:{auth:`admin`,policies:[{name:`platform.knowledge.manage`,version:1}]}}),_=r({meta:{name:`knowledge.source.list`,version:1,description:`List knowledge sources configured for a tenant.`,goal:`Provide visibility into knowledge ingest configuration and schedules.`,context:`Used by App Studio and Ops flows to surface knowledge sources and their health.`,owners:[`platform.knowledge`],tags:[`knowledge`,`sources`],stability:`experimental`},io:{input:u,output:d},policy:{auth:`admin`,policies:[{name:`platform.knowledge.read`,version:1}]}}),v=n({meta:{name:`knowledge.source.triggerSync`,version:1,description:`Trigger an immediate sync for a knowledge source.`,goal:`Support manual or automated sync retries for knowledge ingestion.`,context:`Invoked by Ops tooling or monitors when knowledge content must be refreshed or reprocessed.`,owners:[`platform.knowledge`],tags:[`knowledge`,`sources`],stability:`experimental`},io:{input:f,output:p},policy:{auth:`admin`,policies:[{name:`platform.knowledge.manage`,version:1}]}}),y={CreateKnowledgeSource:m,UpdateKnowledgeSource:h,DeleteKnowledgeSource:g,ListKnowledgeSources:_,TriggerKnowledgeSourceSync:v};function b(e){return e.register(m).register(h).register(g).register(_).register(v)}export{m as CreateKnowledgeSource,g as DeleteKnowledgeSource,_ as ListKnowledgeSources,v as TriggerKnowledgeSourceSync,h as UpdateKnowledgeSource,y as knowledgeContracts,b as registerKnowledgeContracts};
+import { ScalarTypeEnum } from "../schema/dist/ScalarTypeEnum.js";
+import { SchemaModel } from "../schema/dist/SchemaModel.js";
+import "../schema/dist/index.js";
+import { defineCommand, defineQuery } from "../spec.js";
+
+//#region src/knowledge/contracts.ts
+const KnowledgeSyncSchedule = new SchemaModel({
+	name: "KnowledgeSyncSchedule",
+	fields: {
+		enabled: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: false
+		},
+		cron: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		intervalMs: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const KnowledgeSourceRecord = new SchemaModel({
+	name: "KnowledgeSourceRecord",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		spaceKey: {
+			type: ScalarTypeEnum.NonEmptyString(),
+			isOptional: false
+		},
+		spaceVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		label: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		sourceType: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		syncSchedule: {
+			type: KnowledgeSyncSchedule,
+			isOptional: true
+		},
+		lastSyncStatus: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		lastSyncAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		itemsProcessed: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		createdAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		updatedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		}
+	}
+});
+const CreateKnowledgeSourceInput = new SchemaModel({
+	name: "CreateKnowledgeSourceInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		spaceKey: {
+			type: ScalarTypeEnum.NonEmptyString(),
+			isOptional: false
+		},
+		spaceVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		label: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		sourceType: {
+			type: ScalarTypeEnum.NonEmptyString(),
+			isOptional: false
+		},
+		config: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: false
+		},
+		syncSchedule: {
+			type: KnowledgeSyncSchedule,
+			isOptional: true
+		}
+	}
+});
+const UpdateKnowledgeSourceInput = new SchemaModel({
+	name: "UpdateKnowledgeSourceInput",
+	fields: {
+		sourceId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		label: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		config: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: true
+		},
+		syncSchedule: {
+			type: KnowledgeSyncSchedule,
+			isOptional: true
+		}
+	}
+});
+const DeleteKnowledgeSourceInput = new SchemaModel({
+	name: "DeleteKnowledgeSourceInput",
+	fields: { sourceId: {
+		type: ScalarTypeEnum.ID(),
+		isOptional: false
+	} }
+});
+const DeleteKnowledgeSourceOutput = new SchemaModel({
+	name: "DeleteKnowledgeSourceOutput",
+	fields: { success: {
+		type: ScalarTypeEnum.Boolean(),
+		isOptional: false
+	} }
+});
+const ListKnowledgeSourcesInput = new SchemaModel({
+	name: "ListKnowledgeSourcesInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		spaceKey: {
+			type: ScalarTypeEnum.NonEmptyString(),
+			isOptional: true
+		}
+	}
+});
+const ListKnowledgeSourcesOutput = new SchemaModel({
+	name: "ListKnowledgeSourcesOutput",
+	fields: { sources: {
+		type: KnowledgeSourceRecord,
+		isOptional: false,
+		isArray: true
+	} }
+});
+const TriggerKnowledgeSyncInput = new SchemaModel({
+	name: "TriggerKnowledgeSyncInput",
+	fields: { sourceId: {
+		type: ScalarTypeEnum.ID(),
+		isOptional: false
+	} }
+});
+const TriggerKnowledgeSyncOutput = new SchemaModel({
+	name: "TriggerKnowledgeSyncOutput",
+	fields: {
+		success: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: false
+		},
+		itemsProcessed: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		error: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const CreateKnowledgeSource = defineCommand({
+	meta: {
+		name: "knowledge.source.create",
+		version: 1,
+		description: "Create a knowledge source binding for a tenant.",
+		goal: "Onboard a new knowledge ingestion source such as Notion or uploads.",
+		context: "Used by Ops and App Studio to configure knowledge ingestion per tenant and space.",
+		owners: ["platform.knowledge"],
+		tags: ["knowledge", "sources"],
+		stability: "experimental"
+	},
+	io: {
+		input: CreateKnowledgeSourceInput,
+		output: KnowledgeSourceRecord
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.knowledge.manage",
+			version: 1
+		}]
+	}
+});
+const UpdateKnowledgeSource = defineCommand({
+	meta: {
+		name: "knowledge.source.update",
+		version: 1,
+		description: "Update metadata or configuration for a knowledge source.",
+		goal: "Allow rotation of credentials, sync schedules, and labels.",
+		context: "Supports editing how a tenant ingests knowledge (e.g., toggling sync cadence).",
+		owners: ["platform.knowledge"],
+		tags: ["knowledge", "sources"],
+		stability: "experimental"
+	},
+	io: {
+		input: UpdateKnowledgeSourceInput,
+		output: KnowledgeSourceRecord
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.knowledge.manage",
+			version: 1
+		}]
+	}
+});
+const DeleteKnowledgeSource = defineCommand({
+	meta: {
+		name: "knowledge.source.delete",
+		version: 1,
+		description: "Delete a knowledge source binding for a tenant.",
+		goal: "Remove obsolete or compromised knowledge ingestion paths.",
+		context: "Ensures ephemeral or external sources can be removed cleanly without leaving residual bindings.",
+		owners: ["platform.knowledge"],
+		tags: ["knowledge", "sources"],
+		stability: "experimental"
+	},
+	io: {
+		input: DeleteKnowledgeSourceInput,
+		output: DeleteKnowledgeSourceOutput
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.knowledge.manage",
+			version: 1
+		}]
+	}
+});
+const ListKnowledgeSources = defineQuery({
+	meta: {
+		name: "knowledge.source.list",
+		version: 1,
+		description: "List knowledge sources configured for a tenant.",
+		goal: "Provide visibility into knowledge ingest configuration and schedules.",
+		context: "Used by App Studio and Ops flows to surface knowledge sources and their health.",
+		owners: ["platform.knowledge"],
+		tags: ["knowledge", "sources"],
+		stability: "experimental"
+	},
+	io: {
+		input: ListKnowledgeSourcesInput,
+		output: ListKnowledgeSourcesOutput
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.knowledge.read",
+			version: 1
+		}]
+	}
+});
+const TriggerKnowledgeSourceSync = defineCommand({
+	meta: {
+		name: "knowledge.source.triggerSync",
+		version: 1,
+		description: "Trigger an immediate sync for a knowledge source.",
+		goal: "Support manual or automated sync retries for knowledge ingestion.",
+		context: "Invoked by Ops tooling or monitors when knowledge content must be refreshed or reprocessed.",
+		owners: ["platform.knowledge"],
+		tags: ["knowledge", "sources"],
+		stability: "experimental"
+	},
+	io: {
+		input: TriggerKnowledgeSyncInput,
+		output: TriggerKnowledgeSyncOutput
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.knowledge.manage",
+			version: 1
+		}]
+	}
+});
+const knowledgeContracts = {
+	CreateKnowledgeSource,
+	UpdateKnowledgeSource,
+	DeleteKnowledgeSource,
+	ListKnowledgeSources,
+	TriggerKnowledgeSourceSync
+};
+function registerKnowledgeContracts(registry) {
+	return registry.register(CreateKnowledgeSource).register(UpdateKnowledgeSource).register(DeleteKnowledgeSource).register(ListKnowledgeSources).register(TriggerKnowledgeSourceSync);
+}
+
+//#endregion
+export { CreateKnowledgeSource, DeleteKnowledgeSource, ListKnowledgeSources, TriggerKnowledgeSourceSync, UpdateKnowledgeSource, knowledgeContracts, registerKnowledgeContracts };

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