@contractspec/lib.contracts 1.44.0

package/dist/jobs/handlers/ping-handler.js

@@ -0,0 +1,15 @@
+import * as z$1 from "zod";
+
+//#region src/jobs/handlers/ping-handler.ts
+const PING_JOB_TYPE = "core.ping";
+const PingPayloadSchema = z$1.object({});
+const pingJob = {
+	type: PING_JOB_TYPE,
+	schema: PingPayloadSchema,
+	handler: async (_payload, job) => {
+		console.log("[ping] job id=%s attempts=%d", job.id, job.attempts);
+	}
+};
+
+//#endregion
+export { PING_JOB_TYPE, PingPayloadSchema, pingJob };

package/dist/jobs/handlers/storage-document-handler.d.ts

@@ -0,0 +1,12 @@
+import { ObjectStorageProvider } from "../../integrations/providers/storage.js";
+import { JobHandler } from "../queue.js";
+import { StorageIngestionAdapter } from "../../knowledge/ingestion/storage-adapter.js";
+
+//#region src/jobs/handlers/storage-document-handler.d.ts
+interface StorageDocumentJobPayload {
+  bucket: string;
+  key: string;
+}
+declare function createStorageDocumentHandler(storage: ObjectStorageProvider, adapter: StorageIngestionAdapter): JobHandler<StorageDocumentJobPayload>;
+//#endregion
+export { StorageDocumentJobPayload, createStorageDocumentHandler };

package/dist/jobs/handlers/storage-document-handler.js

@@ -0,0 +1,14 @@
+//#region src/jobs/handlers/storage-document-handler.ts
+function createStorageDocumentHandler(storage, adapter) {
+	return async (job) => {
+		const object = await storage.getObject({
+			bucket: job.payload.bucket,
+			key: job.payload.key
+		});
+		if (!object) throw new Error(`Object ${job.payload.bucket}/${job.payload.key} not found`);
+		await adapter.ingestObject(object);
+	};
+}
+
+//#endregion
+export { createStorageDocumentHandler };

package/dist/jobs/index.d.ts

@@ -0,0 +1,3 @@
+import { DEFAULT_RETRY_POLICY, EnqueueOptions, Job, JobHandler, JobQueue, JobStatus, JobTypeDef, QueueStats, RetryPolicy, calculateBackoff, defineJobType } from "./queue.js";
+import { DefinedJob, registerDefinedJob } from "./define-job.js";
+export { DEFAULT_RETRY_POLICY, DefinedJob, EnqueueOptions, Job, JobHandler, JobQueue, JobStatus, JobTypeDef, QueueStats, RetryPolicy, calculateBackoff, defineJobType, registerDefinedJob };

package/dist/jobs/index.js

@@ -0,0 +1,4 @@
+import { registerDefinedJob } from "./define-job.js";
+import { DEFAULT_RETRY_POLICY, calculateBackoff, defineJobType } from "./queue.js";
+
+export { DEFAULT_RETRY_POLICY, calculateBackoff, defineJobType, registerDefinedJob };

package/dist/jobs/memory-queue.d.ts

@@ -0,0 +1,18 @@
+import { EnqueueOptions, Job, JobHandler, JobQueue } from "./queue.js";
+
+//#region src/jobs/memory-queue.d.ts
+declare class MemoryJobQueue implements JobQueue {
+  private readonly pollIntervalMs;
+  private readonly jobs;
+  private readonly handlers;
+  private timer?;
+  private processing;
+  constructor(pollIntervalMs?: number);
+  enqueue<TPayload>(jobType: string, payload: TPayload, options?: EnqueueOptions): Promise<Job<TPayload>>;
+  register<TPayload, TResult = void>(jobType: string, handler: JobHandler<TPayload, TResult>): void;
+  start(): void;
+  stop(): Promise<void>;
+  private processNext;
+}
+//#endregion
+export { MemoryJobQueue };

package/dist/jobs/memory-queue.js

@@ -0,0 +1,71 @@
+import { DEFAULT_RETRY_POLICY } from "./queue.js";
+import { randomUUID } from "node:crypto";
+
+//#region src/jobs/memory-queue.ts
+var MemoryJobQueue = class {
+	jobs = [];
+	handlers = /* @__PURE__ */ new Map();
+	timer;
+	processing = false;
+	constructor(pollIntervalMs = 200) {
+		this.pollIntervalMs = pollIntervalMs;
+	}
+	async enqueue(jobType, payload, options = {}) {
+		const job = {
+			id: randomUUID(),
+			type: jobType,
+			version: 1,
+			payload,
+			status: "pending",
+			priority: options.priority ?? 0,
+			attempts: 0,
+			maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
+			createdAt: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+		if (options.delaySeconds) job.updatedAt = new Date(Date.now() + options.delaySeconds * 1e3);
+		this.jobs.push(job);
+		return job;
+	}
+	register(jobType, handler) {
+		this.handlers.set(jobType, handler);
+	}
+	start() {
+		if (this.timer) return;
+		this.timer = setInterval(() => {
+			this.processNext();
+		}, this.pollIntervalMs);
+	}
+	async stop() {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = void 0;
+		}
+		while (this.processing) await new Promise((resolve) => setTimeout(resolve, 10));
+	}
+	async processNext() {
+		if (this.processing) return;
+		const job = this.jobs.find((j) => j.status === "pending" && j.updatedAt <= /* @__PURE__ */ new Date());
+		if (!job) return;
+		const handler = this.handlers.get(job.type);
+		if (!handler) return;
+		this.processing = true;
+		job.status = "running";
+		job.updatedAt = /* @__PURE__ */ new Date();
+		job.attempts += 1;
+		try {
+			await handler(job);
+			job.status = "completed";
+			job.updatedAt = /* @__PURE__ */ new Date();
+		} catch (error) {
+			job.status = "failed";
+			job.lastError = error instanceof Error ? error.message : "Unknown job error";
+			job.updatedAt = /* @__PURE__ */ new Date();
+		} finally {
+			this.processing = false;
+		}
+	}
+};
+
+//#endregion
+export { MemoryJobQueue };

package/dist/jobs/queue.d.ts

@@ -0,0 +1,131 @@
+import * as z$1 from "zod";
+
+//#region src/jobs/queue.d.ts
+
+/**
+ * Job status values.
+ */
+type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'dead_letter';
+/**
+ * A job in the queue.
+ */
+interface Job<TPayload = unknown> {
+  id: string;
+  type: string;
+  version: number;
+  payload: TPayload;
+  status: JobStatus;
+  priority: number;
+  attempts: number;
+  maxRetries: number;
+  createdAt: Date;
+  updatedAt: Date;
+  scheduledAt?: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  timeoutAt?: Date;
+  lastError?: string;
+  dedupeKey?: string;
+  tenantId?: string;
+  userId?: string;
+  traceId?: string;
+  metadata?: Record<string, unknown>;
+  result?: unknown;
+}
+/**
+ * Options for enqueueing a job.
+ */
+interface EnqueueOptions {
+  /** Delay execution by this many seconds */
+  delaySeconds?: number;
+  /** Key for deduplication (only one job with this key can be pending) */
+  dedupeKey?: string;
+  /** Maximum retry attempts (overrides job type default) */
+  maxRetries?: number;
+  /** Job priority (higher = more urgent) */
+  priority?: number;
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+  /** Tenant context */
+  tenantId?: string;
+  /** User who enqueued */
+  userId?: string;
+  /** Trace ID for distributed tracing */
+  traceId?: string;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Job handler function.
+ */
+type JobHandler<TPayload = unknown, TResult = void> = (job: Job<TPayload>) => Promise<TResult>;
+/**
+ * Job queue interface.
+ */
+interface JobQueue {
+  /** Enqueue a new job */
+  enqueue<TPayload>(jobType: string, payload: TPayload, options?: EnqueueOptions): Promise<Job<TPayload>>;
+  /** Register a handler for a job type */
+  register<TPayload, TResult = void>(jobType: string, handler: JobHandler<TPayload, TResult>): void;
+  /** Start processing jobs */
+  start(): void;
+  /** Stop processing jobs gracefully */
+  stop(): Promise<void>;
+  /** Get job by ID */
+  getJob?(jobId: string): Promise<Job | null>;
+  /** Cancel a pending job */
+  cancelJob?(jobId: string): Promise<boolean>;
+  /** Get queue stats */
+  getStats?(): Promise<QueueStats>;
+}
+/**
+ * Queue statistics.
+ */
+interface QueueStats {
+  pending: number;
+  running: number;
+  completed: number;
+  failed: number;
+  deadLetter: number;
+}
+/**
+ * Retry policy configuration.
+ */
+interface RetryPolicy {
+  /** Maximum number of retry attempts */
+  maxRetries: number;
+  /** Initial backoff in milliseconds */
+  initialBackoffMs: number;
+  /** Maximum backoff in milliseconds */
+  maxBackoffMs: number;
+  /** Backoff multiplier (exponential) */
+  multiplier: number;
+  /** Add jitter to backoff */
+  jitter: boolean;
+}
+/**
+ * Default retry policy.
+ */
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Calculate backoff delay for a retry attempt.
+ */
+declare function calculateBackoff(attempt: number, policy?: RetryPolicy): number;
+/**
+ * Job type definition.
+ */
+interface JobTypeDef<TPayload = unknown> {
+  type: string;
+  version: number;
+  payload: z$1.ZodType<TPayload>;
+  options?: Partial<RetryPolicy & {
+    timeoutMs: number;
+  }>;
+  description?: string;
+}
+/**
+ * Define a typed job type.
+ */
+declare function defineJobType<TPayload>(def: JobTypeDef<TPayload>): JobTypeDef<TPayload>;
+//#endregion
+export { DEFAULT_RETRY_POLICY, EnqueueOptions, Job, JobHandler, JobQueue, JobStatus, JobTypeDef, QueueStats, RetryPolicy, calculateBackoff, defineJobType };

package/dist/jobs/queue.js

@@ -0,0 +1,33 @@
+import "zod";
+
+//#region src/jobs/queue.ts
+/**
+* Default retry policy.
+*/
+const DEFAULT_RETRY_POLICY = {
+	maxRetries: 3,
+	initialBackoffMs: 1e3,
+	maxBackoffMs: 6e4,
+	multiplier: 2,
+	jitter: true
+};
+/**
+* Calculate backoff delay for a retry attempt.
+*/
+function calculateBackoff(attempt, policy = DEFAULT_RETRY_POLICY) {
+	const baseDelay = Math.min(policy.initialBackoffMs * Math.pow(policy.multiplier, attempt - 1), policy.maxBackoffMs);
+	if (policy.jitter) {
+		const jitterFactor = .8 + Math.random() * .4;
+		return Math.floor(baseDelay * jitterFactor);
+	}
+	return baseDelay;
+}
+/**
+* Define a typed job type.
+*/
+function defineJobType(def) {
+	return def;
+}
+
+//#endregion
+export { DEFAULT_RETRY_POLICY, calculateBackoff, defineJobType };

package/dist/jobs/scaleway-sqs-queue.d.ts

@@ -0,0 +1,30 @@
+import { EnqueueOptions, Job, JobHandler, JobQueue } from "./queue.js";
+
+//#region src/jobs/scaleway-sqs-queue.d.ts
+interface ScalewaySqsQueueConfig {
+  queueUrl: string;
+  region?: string;
+  endpoint?: string;
+  waitTimeSeconds?: number;
+  maxNumberOfMessages?: number;
+  visibilityTimeoutSeconds?: number;
+}
+declare class ScalewaySqsJobQueue implements JobQueue {
+  private readonly sqs;
+  private readonly queueUrl;
+  private readonly waitTimeSeconds;
+  private readonly maxNumberOfMessages;
+  private readonly visibilityTimeoutSeconds;
+  private readonly handlers;
+  private running;
+  constructor(config: ScalewaySqsQueueConfig);
+  enqueue<TPayload>(jobType: string, payload: TPayload, options?: EnqueueOptions): Promise<Job<TPayload>>;
+  register<TPayload, TResult = void>(jobType: string, handler: JobHandler<TPayload, TResult>): void;
+  start(): void;
+  stop(): Promise<void>;
+  private pollLoop;
+  private deleteMessage;
+  private sleep;
+}
+//#endregion
+export { ScalewaySqsJobQueue };

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

@@ -0,0 +1,153 @@
+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,27 @@
+import { Stability, Tag } from "./ownership.js";
+import { OpKind, OperationSpec } from "./operations/operation.js";
+import "./operations/index.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+import z from "zod";
+
+//#region src/jsonschema.d.ts
+declare function jsonSchemaForSpec(spec: OperationSpec<AnySchemaModel, AnySchemaModel>): {
+  input: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | null;
+  output: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | 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

@@ -0,0 +1,32 @@
+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 "@contractspec/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

@@ -0,0 +1,21 @@
+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` (`@contractspec/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 '@contractspec/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

@@ -0,0 +1,10 @@
+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 };