@contractspec/lib.contracts 1.62.0 → 1.63.0

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

@@ -1,222 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
-
-// src/jobs/queue.ts
-var DEFAULT_RETRY_POLICY = {
-  maxRetries: 3,
-  initialBackoffMs: 1000,
-  maxBackoffMs: 60000,
-  multiplier: 2,
-  jitter: true
-};
-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 = 0.8 + Math.random() * 0.4;
-    return Math.floor(baseDelay * jitterFactor);
-  }
-  return baseDelay;
-}
-function defineJobType(def) {
-  return def;
-}
-
-// src/jobs/scaleway-sqs-queue.ts
-import { randomUUID } from "crypto";
-import {
-  DeleteMessageCommand,
-  ReceiveMessageCommand,
-  SendMessageCommand,
-  SQSClient
-} from "@aws-sdk/client-sqs";
-class ScalewaySqsJobQueue {
-  sqs;
-  queueUrl;
-  waitTimeSeconds;
-  maxNumberOfMessages;
-  visibilityTimeoutSeconds;
-  handlers = 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");
-    }
-    const region = config.region ?? process.env.SCALEWAY_REGION ?? "par";
-    const endpoint = "https://sqs.mnq.fr-par.scaleway.com";
-    this.sqs = new SQSClient({
-      region,
-      endpoint,
-      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 = 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.0.0",
-      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 res = await this.sqs.send(new ReceiveMessageCommand({
-          QueueUrl: this.queueUrl,
-          MaxNumberOfMessages: this.maxNumberOfMessages,
-          WaitTimeSeconds: this.waitTimeSeconds,
-          VisibilityTimeout: this.visibilityTimeoutSeconds,
-          MessageSystemAttributeNames: ["ApproximateReceiveCount"]
-        }));
-        const messages = res.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 = new Date;
-          const attempts = parseInt(msg.Attributes?.ApproximateReceiveCount ?? "1", 10);
-          const job = {
-            id: envelope.id,
-            type: envelope.type,
-            version: "1.0.0",
-            payload: envelope.payload,
-            status: "pending",
-            priority: 0,
-            attempts,
-            maxRetries: DEFAULT_RETRY_POLICY.maxRetries,
-            createdAt: now,
-            updatedAt: now
-          };
-          job.status = "running";
-          job.updatedAt = new Date;
-          try {
-            await handler(job);
-            job.status = "completed";
-            job.updatedAt = new Date;
-            await this.deleteMessage(msg.ReceiptHandle);
-          } catch (err) {
-            job.status = "failed";
-            job.lastError = err instanceof Error ? err.message : "Unknown job error";
-            job.updatedAt = 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(5000);
-      }
-    }
-    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));
-  }
-}
-export {
-  ScalewaySqsJobQueue
-};

package/dist/jsonschema.d.ts

@@ -1,40 +0,0 @@
-/**
- * Convert zod I/O to JSON Schema so adapters can generate OpenAPI/MCP.
- */
-import type { OperationSpec } from './operations';
-import type { AnySchemaModel } from '@contractspec/lib.schema';
-import z from 'zod';
-export 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: string;
-        kind: import("./operations").OpKind;
-        description: string;
-        tags: import("./ownership").Tag[];
-        stability: import("./ownership").Stability;
-    };
-};
-/** Helper to derive default REST path */
-export declare function defaultRestPath(name: string, version: string): string;
-/**
- * Sanitize a name for MCP entities (tools, prompts, resources).
- * Replaces dots with underscores and ensures compliance with the pattern ^[a-zA-Z0-9_-]{1,64}$.
- * While MCP spec allows dots, some clients validate against stricter patterns.
- */
-export declare function sanitizeMcpName(name: string): string;
-/**
- * Helper to derive default MCP tool name.
- * Replaces dots with underscores for maximum client compatibility.
- * While MCP spec allows dots, some clients validate against stricter patterns.
- */
-export declare function defaultMcpTool(name: string, version: string): string;
-/**
- * Helper to derive default MCP prompt name from key.
- * Replaces dots with underscores for maximum client compatibility.
- */
-export declare function defaultMcpPrompt(key: string): string;
-/** Helper to derive default GraphQL field name */
-export declare function defaultGqlField(name: string, version: string): string;
-//# sourceMappingURL=jsonschema.d.ts.map

package/dist/jsonschema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"jsonschema.d.ts","sourceRoot":"","sources":["../src/jsonschema.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC;;;;;;;;;;;EAcpD;AAED,yCAAyC;AACzC,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAE5D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAI3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAE5D"}

package/dist/jsonschema.js

@@ -1,73 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
-
-// src/jsonschema.ts
-import z from "zod";
-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"
-    }
-  };
-}
-function defaultRestPath(name, version) {
-  return `/${name.replace(/\./g, "/")}/v${version}`;
-}
-function sanitizeMcpName(name) {
-  const sanitized = name.replace(/\./g, "_");
-  return sanitized.slice(0, 64);
-}
-function defaultMcpTool(name, version) {
-  const safeName = name.replace(/\./g, "_");
-  const safeVersion = version.replace(/\./g, "_");
-  return `${safeName}-v${safeVersion}`;
-}
-function defaultMcpPrompt(key) {
-  return sanitizeMcpName(key);
-}
-function defaultGqlField(name, version) {
-  return `${name.replace(/\./g, "_")}_v${version}`;
-}
-export {
-  sanitizeMcpName,
-  jsonSchemaForSpec,
-  defaultRestPath,
-  defaultMcpTool,
-  defaultMcpPrompt,
-  defaultGqlField
-};

package/dist/jsonschema.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=jsonschema.test.d.ts.map

package/dist/jsonschema.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"jsonschema.test.d.ts","sourceRoot":"","sources":["../src/jsonschema.test.ts"],"names":[],"mappings":""}

package/dist/knowledge/binding.d.ts

@@ -1,23 +0,0 @@
-export interface AppKnowledgeBinding {
-    /** Which KnowledgeSpace to use. */
-    spaceKey: string;
-    spaceVersion?: string;
-    /** 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;
-}
-//# sourceMappingURL=binding.d.ts.map

package/dist/knowledge/binding.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/knowledge/binding.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,KAAK,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,yBAAyB;IACzB,WAAW,CAAC,EAAE;QACZ,4BAA4B;QAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,8BAA8B;QAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/knowledge/binding.js

@@ -1 +0,0 @@
-// @bun

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

@@ -1,3 +0,0 @@
-import type { DocBlock } from '@contractspec/lib.contracts/docs';
-export declare const tech_contracts_knowledge_DocBlocks: DocBlock[];
-//# sourceMappingURL=knowledge.docblock.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"knowledge.docblock.d.ts","sourceRoot":"","sources":["../../../src/knowledge/docs/knowledge.docblock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,kCAAkC,EAAE,QAAQ,EAYxD,CAAC"}

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

@@ -1,301 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/knowledge/docs/knowledge.docblock.ts
-var 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
-
-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\` \u2013 canonical invoices, bills, and contracts.
-- \`knowledge.email-threads\` \u2013 operational Gmail threads.
-- \`knowledge.support-faq\` / \`knowledge.product-canon\` \u2013 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** \u2013 pluggable MIME extractors producing
-   \`DocumentFragment\`s.
-2. **EmbeddingService** \u2013 batches fragments through an \`EmbeddingProvider\`
-   (Mistral in the reference implementation).
-3. **VectorIndexer** \u2013 upserts fragments into a \`VectorStoreProvider\`
-   (Qdrant in production, with in-memory implementations for tests).
-4. **Adapters**
-   - \`GmailIngestionAdapter\`: list threads \u2192 convert to raw documents \u2192
-     index.
-   - \`StorageIngestionAdapter\`: fetch object from storage provider \u2192
-     index.
-
-Background jobs (see \`jobs/\`) orchestrate ingestion via Cloud Tasks /
-Pub/Sub or in-memory workers. Handlers:
-
-- \`storage-document-handler\` \u2013 resolves storage object + indexes.
-- \`gmail-sync-handler\` \u2013 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\` (\`@contractspec/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 '@contractspec/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.
-
-`
-  }
-];
-registerDocBlocks(tech_contracts_knowledge_DocBlocks);
-export {
-  tech_contracts_knowledge_DocBlocks
-};