@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/docs/tech/cli.docblock.js

@@ -0,0 +1,138 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/cli.docblock.ts
+const tech_cli_DocBlocks = [{
+	id: "docs.tech.cli.contractspec",
+	title: "ContractSpec CLI",
+	summary: "The command-line interface for creating, building, and validating contract specifications.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/cli/contractspec",
+	tags: [
+		"cli",
+		"tooling",
+		"reference"
+	],
+	owners: ["@contractspec/app.cli-contractspec"],
+	body: `# ContractSpec CLI
+
+The \`@contractspec/app.cli-contractspec\` package provides the command-line interface for the ContractSpec ecosystem.
+
+It is also exposed via \`@contractspec/apps-registry/contractspec\` for convenience.
+
+## Installation
+
+\`\`\`bash
+bun add -D @contractspec/app.cli-contractspec
+\`\`\`
+
+## Quick Start
+
+\`\`\`bash
+# Create a new contract spec interactively
+contractspec create
+
+# Create with AI assistance
+contractspec create --ai
+
+# Build implementation from spec
+contractspec build src/contracts/mySpec.ts
+
+# Validate a spec
+contractspec validate src/contracts/mySpec.ts
+\`\`\`
+
+## Core Commands
+
+### \`create\`
+
+Interactive wizard to create contract specifications.
+
+\`\`\`bash
+contractspec create --type operation --ai
+\`\`\`
+
+### \`build\`
+
+Generate implementation code from contract specs using AI agents or templates.
+
+\`\`\`bash
+contractspec build src/contracts/signup.contracts.ts --agent-mode claude-code
+\`\`\`
+
+### \`validate\`
+
+Validate contract specifications and verify implementations.
+
+\`\`\`bash
+contractspec validate src/contracts/signup.contracts.ts --check-implementation
+\`\`\`
+
+### \`watch\`
+
+Watch contract specifications and auto-regenerate on changes.
+
+\`\`\`bash
+contractspec watch --build --validate
+\`\`\`
+
+### \`list\`
+
+List all contract specifications in the project.
+
+\`\`\`bash
+contractspec list --owner @team-platform
+\`\`\`
+
+### \`cleanup\` / \`clean\`
+
+Clean generated files and build artifacts.
+
+\`\`\`bash
+contractspec clean
+\`\`\`
+
+### \`deps\`
+
+Analyze contract dependencies and relationships (circular dependencies, missing refs).
+
+\`\`\`bash
+contractspec deps --circular
+\`\`\`
+
+### \`diff\`
+
+Compare contract specifications and show differences (breaking changes, semantic diff).
+
+\`\`\`bash
+contractspec diff spec1.ts spec2.ts --breaking
+\`\`\`
+
+### \`ci\`
+
+Run all validation checks for CI/CD pipelines (structure, integrity, deps, doctor, handlers, tests).
+
+\`\`\`bash
+contractspec ci --format sarif --output results.sarif
+\`\`\`
+
+## Configuration
+
+The CLI is configured via \`.contractsrc.json\` in your project root.
+
+\`\`\`json
+{
+  "aiProvider": "claude",
+  "aiModel": "claude-3-7-sonnet-20250219",
+  "agentMode": "claude-code",
+  "outputDir": "./src"
+}
+\`\`\`
+
+For full documentation, refer to the [package README](https://github.com/contractspec/monorepo/tree/main/packages/apps/cli-contractspec).
+`
+}];
+registerDocBlocks(tech_cli_DocBlocks);
+
+//#endregion
+export { tech_cli_DocBlocks };

package/dist/docs/tech/contracts/README.docblock.d.ts

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

package/dist/docs/tech/contracts/README.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/README.docblock.ts
+const tech_contracts_README_DocBlocks = [{
+	id: "docs.tech.contracts.README",
+	title: "Contracts: Specs, Registry, Handlers, Adapters",
+	summary: "- `packages/lssm/libs/contracts` defines the contracts core (OperationSpecRegistry, OperationSpec, PresentationSpec, install helpers, REST/MCP adapters, ...).",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/README",
+	tags: [
+		"tech",
+		"contracts",
+		"README"
+	],
+	body: "## Contracts: Specs, Registry, Handlers, Adapters\n\n### What lives where\n\n- `packages/lssm/libs/contracts` defines the contracts core (OperationSpecRegistry, OperationSpec, PresentationSpec, install helpers, REST/MCP adapters).\n- `packages/lssm/libs/schema` defines the schema dictionary (`SchemaModel`, `FieldType`) used to describe I/O once and map to multiple targets (zod, GraphQL, JSON Schema).\n- App adapters (e.g. GraphQL) live close to the app. Example: `packages/hcircle/apps/api-coliving/src/graphql/contracts-adapter.ts`.\n\n### npm distribution\n\n- `@contractspec/lib.contracts` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@contractspec/lib.contracts/client` exposes only browser-safe helpers (React renderers, client SDK, drivers). Import from this entry when bundling for the web or React Native to avoid dragging server adapters.\n- `@contractspec/lib.contracts/server` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@contractspec/lib.contracts/types` exports the runtime handler context utilities, while `@contractspec/lib.contracts/types/all` re-exports every type alias/interface across the package via `export type` so consumers can import a single module for typings without shipping runtime code.\n- `@contractspec/lib.schema`, `@contractspec/lib.design-system`, `@contractspec/lib.ui-kit`, `@contractspec/lib.ui-kit-web`, `@contractspec/lib.accessibility`, and the presentation runtime packages are published to npm alongside contracts; prefer the scoped packages to keep tree-shaking intact.\n- Bundlers with conditional exports should resolve subpaths first; keep root imports for server-only code paths.\n\n### Core concepts\n\n- **OperationSpec**: immutable description of an operation.\n  - `meta`: `{ name, version, kind: 'query' | 'command' }`\n  - `io`: `{ input: SchemaModel | zod schema, output: SchemaModel | zod schema }`\n  - `policy`: `{ auth?: {...}, rateLimit?: {...}, flags?: string[] }`\n  - `transport.gql.field?`: explicit GraphQL field name (otherwise derived via `defaultGqlField`).\n- **OperationSpecRegistry**: registry of specs + handlers. Use `installOp(reg, spec, handler)` to attach a handler.\n- **Handler**: `(ctx, input) => Promise<output>` implementing the operation.\n- **CapabilitySpec**: canonical capability declaration stored in `src/capabilities.ts`. Tracks `meta` (`{ key, version, kind, title, description, domain, owners, tags, stability }`), `provides` surfaces (`operation`, `event`, `workflow`, `presentation`, `resource`), and `requires` which other capabilities must be present. Enforced during `installFeature`.\n- **PolicySpec**: declarative policy rules (`src/policy/spec.ts`) covering ABAC/ReBAC, consent + rate limit requirements, field-level controls, and PII guidance. `PolicyEngine` evaluates refs, while `OPAPolicyAdapter` lets OPA override/augment runtime decisions.\n- **TelemetrySpec**: analytics definitions (`src/telemetry/spec.ts`) describing event semantics, privacy level, retention, sampling, and anomaly detection. `TelemetryTracker` handles redaction/sampling, `TelemetryAnomalyMonitor` raises alerts, and specs integrate with contracts/workflows via `ctx.telemetry`.\n- **TestSpec**: declarative scenario definitions in `src/tests/spec.ts`. `TestRunner` executes fixtures/actions/assertions against a `OperationSpecRegistry`, and the CLI (`contractspec test`) wraps the runner for automation.\n- **ExperimentSpec**: experiment definitions (`src/experiments/spec.ts`) describing variants, allocation strategies, and success metrics. `ExperimentEvaluator` assigns variants (random/sticky/targeted) and integrates with Policy/Telemetry for safe experimentation.\n- **AppBlueprintSpec / TenantAppConfig**: global blueprints and per-tenant overrides (`src/app-config/spec.ts`). `resolveAppConfig()` merges the two into a `ResolvedAppConfig`, while `composeAppConfig()` hydrates the merged view against registries and reports missing references for safe rollout.\n- **RegeneratorService**: background daemon (`src/regenerator/service.ts`) that consumes telemetry/error/behavior signals, evaluates regeneration rules, and produces `SpecChangeProposal`s for Studio review.\n- **DataViewSpec**: declarative data presentation layer in `src/data-views.ts`. Describes entity projections (`fields`, `filters`, `actions`) with `view.kind` (`list`, `table`, `detail`, `grid`), ties to query operations via `source.primary`, and exposes optional presentation-based empty/error states.\n- **ThemeSpec**: design token + component variant definitions in `src/themes.ts`. Supports inheritance (`extends`), tenant/user overrides, and component-specific variant metadata for the design system.\n- **MigrationSpec**: schema/data migration descriptors (`src/migrations.ts`) with ordered step plans, dependency tracking, and pre/post checks to support automated database/content migrations.\n- **WorkflowSpec**: typed definition of multi-step workflows living in `src/workflow/spec.ts`. `WorkflowRegistry` stores versioned specs, and `validateWorkflowSpec()` (in `src/workflow/validation.ts`) checks graph integrity, step references, and reachability.\n\n### Lifecycle\n\n1. Define the spec (I/O via `SchemaModel` or zod) in a vertical lib (e.g. `contracts-coliving`).\n2. Register it: `installOp(registry, spec, handler)` within the app/service.\n3. Expose it via an adapter (REST, GraphQL, MCP). Each adapter maps the I/O to its transport and enforces policy.\n4. Validate at runtime: parse `input` before executing, parse `output` before returning.\n\n### Adapters\n\n- **REST**: see `packages/lssm/libs/contracts/src/server/rest-*`. Binds routes, validates request/response, maps errors/policies.\n- **MCP**: see `packages/lssm/libs/contracts/src/server/provider-mcp.ts` (standalone MCP server) and `packages/lssm/libs/contracts/src/server/rest-next-mcp.ts` (MCP over Next.js route). Provides tools/resources/prompts.\n  - Tools + resources are registered from Zod schemas.\n  - Resource templates are keyed by full `ResourceMeta.uriTemplate` (e.g. `docs://list`, `docs://doc/{id}`), so multiple templates can share a scheme (`docs://*`) without collisions.\n- **GraphQL (Pothos)**: see `packages/lssm/libs/contracts/src/server/graphql-pothos.ts`. Adds Query/Mutation fields by transforming contract I/O to GraphQL types.\n\n### GraphQL adapter behaviour (summary)\n\n- Field naming: `spec.transport.gql.field` or `<name_with_dots>_v<version>`.\n- Input/Output types from `SchemaModel` (preferred) or fallback zod introspection.\n- Scalars: String/Int/Float/Boolean/Date/JSON; Objects/Arrays/Enums; unions for outputs; input unions => JSON.\n- Policy: auth gate checks GraphQL context; optional feature flag gating.\n- Complexity & tracing: attaches hints and records timings; log includes `{ specName, version }`.\n\n#### Returns mapping and hydration\n\n- `spec.transport.gql.returns` can declare the GraphQL return wrapper: e.g. `\"Spot\"` or `[Spot]`. If omitted, the adapter infers from `io.output` (SchemaModel) or `resourceRef.graphQLType`.\n- Resource outputs: when `io.output` is a `resourceRef(...)` or `transport.gql.resource` is set, the adapter will optionally hydrate via a `ResourceRegistry` using `contracts-adapter-hydration.ts`:\n  - Grammar is parsed with `parseReturns()`.\n  - Entities are resolved via `hydrateResourceIfNeeded(resources, result, { template, varName, returns })` after handler execution.\n\n### Resource outputs\n\n- Declare resource outputs using `resourceRef(uriTemplate, opts)`.\n- `opts.varName` (default `id`) selects the identifier field returned by the handler for URI substitution.\n- `opts.graphQLType` is the GraphQL return type name (e.g., `Spot`) or list form (e.g., `[Spot]`).\n- `opts.many: true` indicates the handler returns an array of resources. The handler type becomes an array of items that include the identifier field.\n\nExample:\n\n```ts\nio: {\n  input: ListThingsInput,\n  output: resourceRef('myapp://thing/{id}', { graphQLType: '[Thing]', many: true }),\n}\n```\n\nHandler return (simplified): `{ id: string | number }[]`.\n\n### Errors\n\n- Validation errors → transport 400/GraphQL UserInputError.\n- Policy/auth errors → 401/403 or GraphQL ForbiddenError.\n- Handler errors → mapped to transport error with safe message.\n\n### Versioning & naming\n\n- Keep `meta.version` monotonic. Clients should pin to a versioned field/key.\n- Avoid renaming existing fields; add new fields with new versions.\n\n### Ownership metadata (OwnerShipMeta)\n\nAll contracts, events, features, and presentations reference a shared ownership schema (source of truth in `packages/lssm/libs/contracts/src/ownership.ts`).\n\n- Required fields: `title`, `description`, `domain`, `owners[]`, `tags[]`, `stability`.\n- Curated enums: the library exports suggested constants for owners and tags; free-form strings are still allowed for forward-compatibility.\n- Operations (`spec.ts`): `meta` requires `stability`, `owners`, and `tags` alongside `name`, `version`, `kind`, `description`, `goal`, and `context`.\n- Presentations V2: `meta` is a partial of ownership plus `description`.\n- Events: may specify `ownership` (recommended) for discoverability and docs.\n\n### Quick start\n\n```ts\n// app bootstrap\nconst reg = new OperationSpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"
+}];
+registerDocBlocks(tech_contracts_README_DocBlocks);
+
+//#endregion
+export { tech_contracts_README_DocBlocks };

package/dist/docs/tech/contracts/migrations.docblock.d.ts

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

package/dist/docs/tech/contracts/migrations.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/migrations.docblock.ts
+const tech_contracts_migrations_DocBlocks = [{
+	id: "docs.tech.contracts.migrations",
+	title: "MigrationSpec Overview",
+	summary: "`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/migrations",
+	tags: [
+		"tech",
+		"contracts",
+		"migrations"
+	],
+	body: "# MigrationSpec Overview\n\n## Purpose\n\n`MigrationSpec` provides a declarative plan for schema/data/validation steps so migrations can be generated, reviewed, and executed safely by tooling. Each spec captures ownership metadata, ordered up/down steps, and optional dependency information. Runtime tooling can consume the spec to run SQL/data scripts with pre/post checks and produce audit logs.\n\n## Location\n\n- Spec + registry: `packages/libs/contracts/src/migrations.ts`\n- Tests: `packages/.../migrations.test.ts`\n\n## Schema\n\n```ts\nexport interface MigrationSpec {\n  meta: MigrationMeta;   // ownership metadata + { name, version }\n  plan: {\n    up: MigrationStep[];   // required forward plan\n    down?: MigrationStep[];// optional rollback steps\n  };\n  dependencies?: string[]; // optional list of migration keys this depends on\n}\n```\n\n- **MigrationStep**\n  - `kind`: `'schema' | 'data' | 'validation'`\n  - Shared fields: `description?`, `timeoutMs?`, `retries?`, `preChecks?`, `postChecks?`\n  - `schema`: `sql` string executed in transactional context\n  - `data`: arbitrary `script` (e.g., JS/TS snippet, path to file, instructions)\n  - `validation`: `assertion` expression verifying state (e.g., SQL returning boolean)\n- **MigrationCheck** (`preChecks`/`postChecks`)\n  - `description`: human context\n  - `expression`: expression or SQL snippet to evaluate before/after the step\n- **Dependencies**\n  - Array of migration keys (`\"boundedContext.namespace.timestamp_slug\"`) used to ensure the registry executes prerequisites first\n\n## Registry Usage\n\n```ts\nimport { MigrationRegistry } from '@contractspec/lib.contracts/migrations';\nimport { AddUsersMigration } from './migrations/core.db.2025_01_add_users';\n\nconst registry = new MigrationRegistry();\nregistry.register(AddUsersMigration);\n\nconst migration = registry.get('core.db.2025_01_add_users');\nconst all = registry.list(); // sorted by name/version\n```\n\n## Authoring Guidelines\n\n1. Name migrations with timestamped slugs (`domain.db.YYYY_MM_description`) for clarity.\n2. Capture ownership metadata (`owners`, `tags`, `stability`) so tooling can route approvals.\n3. Prefer small, reversible steps. Use `plan.down` when safe; otherwise document fallback.\n4. Use `preChecks`/`postChecks` for critical invariants (row counts, schema existence).\n5. Specify dependencies explicitly to avoid parallel execution hazards.\n6. For large data scripts, use `script` as a pointer (URL, file path) rather than embedding code directly.\n\n## Tooling Roadmap\n\nUpcoming CLI support (Phase 4 plan):\n\n- `contractspec create --type migration` (scaffolds spec skeleton)\n- `contractspec build <migration>` (generate executor harness)\n- `contractspec migrate create/up/down/status` orchestration commands\n\nThe current implementation focuses on the spec/registry foundation so downstream tooling can be layered iteratively.\n\n"
+}];
+registerDocBlocks(tech_contracts_migrations_DocBlocks);
+
+//#endregion
+export { tech_contracts_migrations_DocBlocks };

package/dist/docs/tech/contracts/openapi-export.docblock.d.ts

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

package/dist/docs/tech/contracts/openapi-export.docblock.js

@@ -0,0 +1,58 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/openapi-export.docblock.ts
+const tech_contracts_openapi_export_DocBlocks = [{
+	id: "docs.tech.contracts.openapi-export",
+	title: "OpenAPI export (OpenAPI 3.1) from OperationSpecRegistry",
+	summary: "Generate a deterministic OpenAPI document from a OperationSpecRegistry using jsonSchemaForSpec + REST transport metadata.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/openapi-export",
+	tags: [
+		"contracts",
+		"openapi",
+		"rest"
+	],
+	body: `## OpenAPI export (OpenAPI 3.1) from OperationSpecRegistry
+
+### Purpose
+
+ContractSpec specs can be exported into an **OpenAPI 3.1** document for tooling (SDK generation, docs, gateways).
+
+The export is **spec-first**:
+
+- Uses \`jsonSchemaForSpec(spec)\` for input/output JSON Schema (from SchemaModel → zod → JSON Schema)
+- Uses \`spec.transport.rest.method/path\` when present
+- Falls back to deterministic defaults:
+  - Method: \`POST\` for commands, \`GET\` for queries
+  - Path: \`defaultRestPath(name, version)\` → \`/<dot/name>/v<version>\`
+
+### Library API
+
+- Function: \`openApiForRegistry(registry, options?)\`
+- Location: \`@contractspec/lib.contracts/openapi\`
+
+### CLI
+
+Export OpenAPI from a registry module:
+
+\`\`\`bash
+contractspec openapi --registry ./src/registry.ts --out ./openapi.json
+\`\`\`
+
+The registry module must export one of:
+
+- \`registry: OperationSpecRegistry\`
+- \`default(): OperationSpecRegistry | Promise<OperationSpecRegistry>\`
+- \`createRegistry(): OperationSpecRegistry | Promise<OperationSpecRegistry>\`
+
+### Notes / limitations (current)
+
+- Responses are generated as a basic \`200\` response (plus schemas when available).
+- Query (GET) inputs are currently represented as a JSON request body when an input schema exists.
+- Errors are not yet expanded into OpenAPI responses; that will be added when we standardize error envelopes.`
+}];
+registerDocBlocks(tech_contracts_openapi_export_DocBlocks);
+
+//#endregion
+export { tech_contracts_openapi_export_DocBlocks };

package/dist/docs/tech/contracts/openapi-import.docblock.d.ts

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

package/dist/docs/tech/contracts/openapi-import.docblock.js

@@ -0,0 +1,65 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/openapi-import.docblock.ts
+const tech_contracts_openapi_import_DocBlocks = [{
+	id: "docs.tech.contracts.openapi-import",
+	title: "OpenAPI Import (OpenAPI 3.1) to ContractSpec",
+	summary: "Import OpenAPI specifications into ContractSpec models, or generate pure Zod/JSON-Schema/GraphQL representations.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/openapi-import",
+	tags: [
+		"contracts",
+		"openapi",
+		"import",
+		"codegen"
+	],
+	body: `## OpenAPI Import (OpenAPI 3.1)
+
+### Purpose
+
+Import external API definitions into your codebase. Supports both one-time scaffolding and multi-format generation for integration.
+
+### Modes
+
+#### 1. ContractSpec Scaffolding (Default)
+
+Generates standard \`defineSchemaModel\` definitions for full ContractSpec integration.
+
+\`\`\`bash
+contractspec openapi import --file api.json --output ./src/contracts
+\`\`\`
+
+#### 2. Multi-Format Generation
+
+Generate schemas in specific formats for direct use in other parts of your stack (adapters, UI, etc.).
+
+- **Zod**: Pure Zod schemas (\`z.object(...)\`).
+- **GraphQL**: GraphQL SDL type definitions.
+- **JSON Schema**: Standard JSON Schema objects.
+
+\`\`\`bash
+# Generate Zod schemas suitable for runtime validation
+contractspec openapi import --file api.json --output ./src/zod --schema-format zod
+\`\`\`
+
+### Library API
+
+- Function: \`importFromOpenApi(doc, options)\`
+- Location: \`@contractspec/lib.contracts-transformers/openapi\`
+- Options:
+  - \`schemaFormat\`: 'contractspec' | 'zod' | 'json-schema' | 'graphql'
+  - \`prefix\`: Prefix for model names
+  - \`tags\`: Filter by OpenAPI tags
+
+### CLI
+
+\`\`\`bash
+contractspec openapi import --file <path-or-url> --output <dir> [--schema-format <format>]
+\`\`\`
+`
+}];
+registerDocBlocks(tech_contracts_openapi_import_DocBlocks);
+
+//#endregion
+export { tech_contracts_openapi_import_DocBlocks };

package/dist/docs/tech/contracts/ops-to-presentation-linking.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/ops-to-presentation-linking.docblock.d.ts
+declare const tech_contracts_ops_to_presentation_linking_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_ops_to_presentation_linking_DocBlocks };

package/dist/docs/tech/contracts/ops-to-presentation-linking.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/ops-to-presentation-linking.docblock.ts
+const tech_contracts_ops_to_presentation_linking_DocBlocks = [{
+	id: "docs.tech.contracts.ops-to-presentation-linking",
+	title: "Ops ↔ Presentation linking (V2)",
+	summary: "This document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/ops-to-presentation-linking",
+	tags: [
+		"tech",
+		"contracts",
+		"ops-to-presentation-linking"
+	],
+	body: "### Ops ↔ Presentation linking (V2)\n\nThis document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.\n\n- Location: `@contractspec/lib.contracts/src/features.ts`\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\n- Validation: `installFeature()` validates that linked ops exist in `OperationSpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\n\nExample:\n\n```ts\nimport type { OperationSpecRegistry } from '@contractspec/lib.contracts/src/registry';\nimport { FeatureRegistry, createFeatureModule } from '@contractspec/lib.contracts';\n\nexport function buildFeaturesWithOps(ops: OperationSpecRegistry) {\n  const features = new FeatureRegistry();\n  features.register(\n    createFeatureModule(\n      {\n        key: 'myapp.widgets.linkage',\n        title: 'Widgets (linked)',\n        description: 'Links create/update ops to UI presentations',\n        domain: 'widgets',\n        tags: ['widgets', 'linkage'],\n        stability: 'beta',\n      },\n      {\n        operations: [\n          { name: 'widgets.create', version: '1.0.0' },\n          { name: 'widgets.update', version: '1.0.0' },\n        ],\n        presentations: [{ name: 'myapp.widgets.editor.page', version: '1.0.0' }],\n        opToPresentation: [\n          {\n            op: { name: 'widgets.create', version: '1.0.0' },\n            pres: { name: 'myapp.widgets.editor.page', version: '1.0.0' },\n          },\n          {\n            op: { name: 'widgets.update', version: '1.0.0' },\n            pres: { name: 'myapp.widgets.editor.page', version: '1.0.0' },\n          },\n        ],\n        presentationsTargets: [\n          {\n            name: 'myapp.widgets.editor.page',\n            version: '1.0.0',\n            targets: ['react', 'markdown'],\n          },\n        ],\n      }\n    )\n  );\n  return { features };\n}\n```\n\nNotes\n\n- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.\n- Presentations can target multiple outputs (`react`, `markdown`, `application/json`, `application/xml`).\n- Use `renderFeaturePresentation()` to render a descriptor to a given target with a component map.\n"
+}];
+registerDocBlocks(tech_contracts_ops_to_presentation_linking_DocBlocks);
+
+//#endregion
+export { tech_contracts_ops_to_presentation_linking_DocBlocks };

package/dist/docs/tech/contracts/overlays.docblock.d.ts

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

package/dist/docs/tech/contracts/overlays.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/overlays.docblock.ts
+const tech_contracts_overlays_DocBlocks = [{
+	id: "docs.tech.contracts.overlays",
+	title: "OverlaySpec Implementation",
+	summary: "OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@contractspec/lib.overlay-engine`.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/overlays",
+	tags: [
+		"tech",
+		"contracts",
+		"overlays"
+	],
+	body: "# OverlaySpec Implementation\n\nOverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@contractspec/lib.overlay-engine`.\n\n## Structure\n\n```ts\ninterface OverlaySpec {\n  overlayId: string;\n  version: string;\n  appliesTo: {\n    capability?: string;\n    workflow?: string;\n    dataView?: string;\n    presentation?: string;\n    tenantId?: string;\n    userId?: string;\n    role?: string;\n    device?: string;\n  };\n  modifications: OverlayModification[];\n}\n```\n\nSupported modifications:\n\n- `hideField`\n- `renameLabel`\n- `reorderFields`\n- `setDefault`\n- `addHelpText`\n- `makeRequired`\n\n## Signing\n\nOverlays must be signed. Use the signer helper:\n\n```ts\nimport { signOverlay } from '@contractspec/lib.overlay-engine/signer';\n\nconst signed = await signOverlay(overlay, privateKeyPem);\nregistry.register(signed);\n```\n\nKeys are stored in `OverlaySigningKey` (Prisma) and referenced by the `Overlay` model for auditing.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"
+}];
+registerDocBlocks(tech_contracts_overlays_DocBlocks);
+
+//#endregion
+export { tech_contracts_overlays_DocBlocks };

package/dist/docs/tech/contracts/tests.docblock.d.ts

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

package/dist/docs/tech/contracts/tests.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/tests.docblock.ts
+const tech_contracts_tests_DocBlocks = [{
+	id: "docs.tech.contracts.tests",
+	title: "TestSpec & TestRunner",
+	summary: "Use `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/tests",
+	tags: [
+		"tech",
+		"contracts",
+		"tests"
+	],
+	body: "## TestSpec & TestRunner\n\nUse `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.\n\n- Types & registry: `packages/libs/contracts/src/tests/spec.ts`\n- Runtime runner: `packages/libs/contracts/src/tests/runner.ts`\n- CLI: `contractspec test`\n\n### Structure\n\n```ts\nexport interface TestSpec {\n  meta: TestSpecMeta;\n  target: TestTarget;  // contract or workflow\n  fixtures?: Fixture[]; // optional shared setup before each scenario\n  scenarios: TestScenario[];\n  coverage?: CoverageRequirement;\n}\n```\n\n- `Fixture`: run an operation before the scenario (`operation`, optional `input`)\n- `Action`: operation input that the scenario exercises\n- `Assertion`:\n  - `expectOutput` `{ match }` deep-equals the handler output\n  - `expectError` `{ messageIncludes? }` ensures an error was thrown\n  - `expectEvents` `{ events: [{ name, version, min?, max? }] }` checks emitted events\n\n### Example\n\n```ts\nimport { defineCommand, type TestSpec } from '@contractspec/lib.contracts';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { name: 'math.add', version: '1.0.0', /* … */ },\n  io: {\n    input: AddNumbersInput,\n    output: AddNumbersOutput,\n  },\n  policy: { auth: 'user' },\n});\n\nexport const MathAddTests: TestSpec = {\n  meta: {\n    name: 'math.add.tests',\n    version: '1.0.0',\n    title: 'Math add scenarios',\n    owners: ['@team.math'],\n    tags: ['math'],\n    stability: StabilityEnum.Experimental,\n  },\n  target: { type: 'contract', operation: { name: 'math.add' } },\n  scenarios: [\n    {\n      name: 'adds positive numbers',\n      when: {\n        operation: { name: 'math.add' },\n        input: { a: 2, b: 3 },\n      },\n      then: [\n        { type: 'expectOutput', match: { sum: 5 } },\n        {\n          type: 'expectEvents',\n          events: [{ name: 'math.sum_calculated', version: '1.0.0', min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `OperationSpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new OperationSpecRegistry();\n  registry.register(AddNumbersSpec);\n  registry.bind(AddNumbersSpec, addNumbersHandler);\n  return registry;\n}\n```\n\n2. Run the CLI:\n\n```\ncontractspec test apps/math/tests/math.add.tests.ts \\\n  --registry apps/math/tests/registry.ts\n```\n\n- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via `TestRunner`.\n- `--json` outputs machine-readable results.\n\n### Programmatic usage\n\n```ts\nconst runner = new TestRunner({\n  registry,\n  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),\n});\n\nconst result = await runner.run(MathAddTests);\nconsole.log(result.passed, result.failed);\n```\n\n- `createContext` can supply default `HandlerCtx` values.\n- `beforeEach` / `afterEach` hooks let you seed databases or reset state.\n\n### Best practices\n\n- Keep fixtures idempotent so scenarios can run in parallel in the future.\n- Use `expectEvents` to guard analytics/telemetry expectations.\n- Add specs to `TestRegistry` for discovery and documentation.\n- `coverage` captures desired coverage metrics (enforced by future tooling).\n- Pair TestSpec files with CI using `contractspec test --json` and fail builds when `failed > 0`.\n\n### Mocking with Bun's `vi`\n\n- Pass a single function type to `vi.fn<TFunction>()` so calls retain typed arguments:\n\n```ts\nconst handler = vi.fn<typeof fetch>();\nconst fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;\nObject.defineProperty(fetchImpl, 'preconnect', {\n  value: vi.fn<typeof fetch.preconnect>(),\n});\n```\n\n- When you need to inspect calls, use the typed mock (`handler.mock.calls`) rather than casting to `any`.\n- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict `tsconfig` settings.\n\n"
+}];
+registerDocBlocks(tech_contracts_tests_DocBlocks);
+
+//#endregion
+export { tech_contracts_tests_DocBlocks };

package/dist/docs/tech/contracts/themes.docblock.d.ts

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

package/dist/docs/tech/contracts/themes.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/themes.docblock.ts
+const tech_contracts_themes_DocBlocks = [{
+	id: "docs.tech.contracts.themes",
+	title: "ThemeSpec Overview",
+	summary: "`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@contractspec/lib.contracts`, making them accessible to generators, docs, and runtime tooling.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/themes",
+	tags: [
+		"tech",
+		"contracts",
+		"themes"
+	],
+	body: "# ThemeSpec Overview\n\n## Purpose\n\n`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@contractspec/lib.contracts`, making them accessible to generators, docs, and runtime tooling.\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/themes.ts`\n- Design tokens bridge: `packages/libs/design-system/src/theme/*`\n\n## Schema\n\n```ts\nexport interface ThemeSpec {\n  meta: ThemeMeta;            // ownership metadata + { name, version, extends?, scopes? }\n  tokens: ThemeTokens;        // design tokens grouped by colors, radii, space, etc.\n  components?: ComponentVariantSpec[]; // per-component variant configuration\n  overrides?: ThemeOverride[];         // scoped tenant/user overrides\n}\n```\n\n- **ThemeMeta**\n  - `name`: fully-qualified identifier (e.g., `design.pastel`)\n  - `version`: increment when tokens/variants change in a breaking way\n  - `extends?`: optional `{ name, version }` pointer to a base theme\n  - `scopes?`: default scopes where the theme applies (`global`, `tenant`, `user`)\n- **ThemeTokens**\n  - `colors`, `radii`, `space`, `typography`, `shadows`, `motion`\n  - Each entry is a map of `{ value: T; description?: string }`\n- **ComponentVariantSpec**\n  - `component`: design-system component key (e.g., `Button`, `NavMain`)\n  - `variants`: map of variant names → `{ props?, tokens? }`\n- **ThemeOverride**\n  - `scope`: `'global' | 'tenant' | 'user'`\n  - `target`: identifier (e.g., `tenant:artisanos`, `user:123`)\n  - `tokens?` / `components?`: partial token/variant overrides for the target\n\n## Registry Usage\n\n```ts\nimport { ThemeRegistry } from '@contractspec/lib.contracts/themes';\nimport { PastelTheme } from './themes/design.pastel';\n\nconst themes = new ThemeRegistry();\nthemes.register(PastelTheme);\n\nconst theme = themes.get('design.pastel');\nconst tenantVariant = themes\n  .get('design.pastel')\n  ?.overrides?.find((o) => o.target === 'tenant:artisanos');\n```\n\nThe registry guarantees `name + version` uniqueness and exposes `list()` for discovery tooling.\n\n## Rendering\n\nThe design system consumes specs (via adapters you provide) to build runtime tokens. A simple adapter might:\n\n1. Resolve the base theme + applicable overrides.\n2. Merge token maps using `ThemeTokens`.\n3. Feed the result into `mapTokensForPlatform` in `@contractspec/lib.design-system`.\n\n```ts\nimport { ThemeRegistry } from '@contractspec/lib.contracts/themes';\nimport { mapTokensForPlatform } from '@contractspec/lib.design-system';\n\nfunction resolveTokens(registry: ThemeRegistry, ref: ThemeRef, ctx: { tenant?: string; user?: string }) {\n  const spec = registry.get(ref.name, ref.version);\n  if (!spec) throw new Error('Theme not found');\n\n  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));\n  return mapTokensForPlatform(tokens);\n}\n```\n\n## Authoring Guidelines\n\n1. Keep token names aligned with the design-system defaults (`background`, `mutedForeground`, etc.).\n2. Use `extends` to create layered themes (base brand → tenant tweaks → user-level overrides).\n3. Document variants with `description` to help designers and automation understand intent.\n4. Prefer scoped overrides (`tenant:foo`) instead of duplicating the entire theme per tenant.\n5. When tokens influence multiple components, capture them in `tokens` and keep `components` for API-level variant wiring.\n\n## CLI (Future Work)\n\nThe `contractspec` CLI does not yet scaffold theme specs. Planned additions:\n\n- `contractspec create --type theme`\n- `contractspec build <theme.theme.ts>` → generate design-system adapters\n\nFor now, author specs manually and register them alongside contract bundles.\n\n"
+}];
+registerDocBlocks(tech_contracts_themes_DocBlocks);
+
+//#endregion
+export { tech_contracts_themes_DocBlocks };

package/dist/docs/tech/contracts/vertical-pocket-family-office.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/contracts/vertical-pocket-family-office.docblock.d.ts
+declare const tech_contracts_vertical_pocket_family_office_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_vertical_pocket_family_office_DocBlocks };

package/dist/docs/tech/contracts/vertical-pocket-family-office.docblock.js

@@ -0,0 +1,126 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region src/docs/tech/contracts/vertical-pocket-family-office.docblock.ts
+const tech_contracts_vertical_pocket_family_office_DocBlocks = [{
+	id: "docs.tech.contracts.vertical-pocket-family-office",
+	title: "Pocket Family Office Vertical",
+	summary: "Pocket Family Office is a ContractSpec reference vertical that",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/vertical-pocket-family-office",
+	tags: [
+		"tech",
+		"contracts",
+		"vertical-pocket-family-office"
+	],
+	body: `# Pocket Family Office Vertical
+
+Pocket Family Office is a ContractSpec reference vertical that
+demonstrates finance automation atop the integration and knowledge
+layers. It is optimised for the hackathon stack (Google Cloud, Mistral,
+Qdrant, ElevenLabs) while remaining provider-agnostic.
+
+## Goals
+
+- Ingest household financial documents (uploads + Gmail threads).
+- Generate AI summaries and optionally deliver them as voice notes.
+- Schedule multi-channel reminders for upcoming bills.
+- Showcase spec-first composition of integrations, knowledge spaces, and
+  workflows.
+
+## Blueprint Overview
+
+Source: \`packages/examples/pocket-family-office/blueprint.ts\`
+
+- **Integration slots**
+  - \`primaryLLM\` \u2192 Mistral chat/embeddings
+  - \`primaryVectorDb\` \u2192 Qdrant
+  - \`primaryStorage\` \u2192 Google Cloud Storage
+  - \`primaryOpenBanking\` \u2192 Powens BYOK project for account aggregation
+  - \`emailInbound\` / \`emailOutbound\` \u2192 Gmail + Postmark
+  - \`calendarScheduling\` \u2192 Google Calendar
+  - \`voicePlayback\` \u2192 ElevenLabs (optional)
+  - \`smsNotifications\` \u2192 Twilio (optional)
+  - \`paymentsProcessing\` \u2192 Stripe (optional)
+- **Workflows**
+  - \`process-uploaded-document\`
+  - \`upcoming-payments-reminder\`
+  - \`generate-financial-summary\`
+  - \`ingest-email-threads\`
+  - \`sync-openbanking-accounts\`
+  - \`sync-openbanking-transactions\`
+  - \`refresh-openbanking-balances\`
+  - \`generate-openbanking-overview\`
+- **Policies/Telemetry** \u2013 references tenant policy specs and
+  \`pfo.telemetry\` for observability.
+
+## Tenant Sample
+
+\`tenant.sample.ts\` binds each slot to sample connections defined in
+\`connections/samples.ts\`. Key details:
+
+- Uses Google Cloud Secret Manager URIs for all credentials.
+- Enables knowledge spaces \`knowledge.financial-docs\` and
+  \`knowledge.email-threads\`, plus the derived summaries space
+  \`knowledge.financial-overview\` populated by open banking workflows.
+- Keeps \`voicePlayback\` and \`paymentsProcessing\` optional so tenants can
+  enable them incrementally.
+
+## Contracts
+
+\`contracts/index.ts\` defines command/query specs that power the
+workflows:
+
+- \`pfo.documents.upload\` \u2013 store object + enqueue ingestion.
+- \`pfo.reminders.schedule-payment\` \u2013 send email/SMS/calendar reminders.
+- \`pfo.summary.generate\` \u2013 run RAG over knowledge spaces.
+- \`pfo.summary.dispatch\` \u2013 deliver summaries via email / voice.
+- \`pfo.email.sync-threads\` \u2013 ingest Gmail threads.
+
+## Workflows
+
+- **Process Uploaded Document**
+  1. Upload to storage / queue ingestion.
+  2. Optional human review step.
+- **Upcoming Payments Reminder**
+  1. Human review (confirm due date / channel).
+  2. Automation schedules reminders (email/SMS/calendar).
+- **Generate Financial Summary**
+  1. Run RAG to produce Markdown summary.
+  2. Dispatch summary (email + optional ElevenLabs voice note).
+- **Ingest Email Threads**
+  1. Sync Gmail threads into knowledge space.
+  2. Triage step for operators when nothing new is ingested.
+
+## Knowledge & Jobs
+
+- Knowledge spaces registered via
+  \`registerFinancialDocsKnowledgeSpace\` and
+  \`registerEmailThreadsKnowledgeSpace\`.
+- Ingestion adapters (\`GmailIngestionAdapter\`, \`StorageIngestionAdapter\`)
+  and job handlers (\`createGmailSyncHandler\`,
+  \`createStorageDocumentHandler\`) wire Gmail labels & GCS prefixes into
+  Qdrant.
+- \`KnowledgeQueryService\` provides summarisation + references for the
+  summary generation workflow.
+
+## Tests & Usage
+
+\`tests/pocket-family-office.test.ts\` exercises:
+
+- Blueprint validation + config composition.
+- In-memory ingestion of a sample invoice.
+- Retrieval augmented generation producing a summary with references.
+
+Use these files as scaffolding for new tenants or as a template for the
+hackathon deliverable. Replace the sample connection metadata with
+tenant-specific IDs/secret references before deploying.
+
+
+
+`
+}];
+registerDocBlocks(tech_contracts_vertical_pocket_family_office_DocBlocks);
+
+//#endregion
+export { tech_contracts_vertical_pocket_family_office_DocBlocks };

package/dist/docs/tech/lifecycle-stage-system.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/tech/lifecycle-stage-system.docblock.d.ts
+declare const tech_lifecycle_stage_system_DocBlocks: DocBlock[];
+//#endregion
+export { tech_lifecycle_stage_system_DocBlocks };