@lssm/lib.contracts 1.11.0 → 1.41.0

package/dist/docs/tech/auth/better-auth-nextjs.docblock.js

@@ -0,0 +1,58 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.auth.better-auth-nextjs`,title:`Better Auth + Next.js integration (ContractSpec)`,summary:`How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).`,kind:`reference`,visibility:`public`,route:`/docs/tech/auth/better-auth-nextjs`,tags:[`auth`,`better-auth`,`nextjs`,`cookies`,`proxy`,`hmr`],body:`# Better Auth + Next.js integration (ContractSpec)
+
+This repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).
+
+## Server config (Better Auth)
+
+- Source: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Important: \`nextCookies()\` must be the **last** plugin in the Better Auth plugin list so \`Set-Cookie\` is applied correctly in Next.js environments.
+
+## Better Auth Admin plugin
+
+ContractSpec Studio enables the Better Auth **Admin plugin** to support platform-admin user operations (list users, impersonation, etc.).
+
+- Server: \`admin()\` plugin in \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
+- Client: \`adminClient()\` in \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+
+### PLATFORM_ADMIN ⇒ Better Auth admin role
+
+Better Auth Admin endpoints authorize via \`user.role\`. ContractSpec enforces an org-driven rule:
+
+- If the **active organization** has \`type = PLATFORM_ADMIN\`, the signed-in user is ensured to have \`User.role\` containing \`admin\`.
+- This is applied in the session creation hook and re-checked in \`assertsPlatformAdmin()\`.
+
+This keeps admin enablement deterministic and avoids manual role backfills.
+
+## Client config (React web + Expo)
+
+To avoid duplicate background refresh/polling loops in dev (Fast Refresh/HMR), the Better Auth client is implemented as a singleton cached on \`globalThis\`.
+
+- Web client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.ts\`
+- Native client: \`packages/bundles/contractspec-studio/src/presentation/providers/auth/client.native.ts\`
+
+Import guidance:
+
+- If you only need the context/hook, prefer importing from \`@lssm/bundle.contractspec-studio/presentation/providers/auth\`.
+- If you explicitly need the Better Auth client instance (e.g. admin impersonation, direct API calls), import from \`@lssm/bundle.contractspec-studio/presentation/providers/auth/client\`.
+
+## Public routes (login / signup)
+
+Public auth pages should avoid eager \`authClient\` initialization.
+
+Pattern used:
+
+- In the submit handler, dynamically import \`@lssm/bundle.contractspec-studio/presentation/providers/auth/index.web\` and call \`authClient.signIn.*\` / \`authClient.signUp.*\`.
+
+This prevents session refresh behavior from starting just because a public page rendered.
+
+## Next.js proxy auth (web-landing)
+
+The Next.js proxy/middleware is used for **redirect decisions only**. It must not perform DB-backed session reads on every request.
+
+- Source: \`packages/apps/web-landing/src/proxy.ts\`
+- Approach: cookie-only checks via Better Auth cookies helpers:
+  - \`getSessionCookie(request)\`
+  - \`getCookieCache(request)\`
+
+These checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.
+`}];e(t);export{t as tech_auth_better_auth_nextjs_DocBlocks};

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

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.README`,title:`Contracts: Specs, Registry, Handlers, Adapters`,summary:"- `packages/lssm/libs/contracts` defines the contracts core (SpecRegistry, ContractSpec, 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 (SpecRegistry, ContractSpec, 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- `@lssm/lib.contracts` (root) keeps the legacy \\\"everything\\\" surface for backward compatibility.\n- `@lssm/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- `@lssm/lib.contracts/server` covers HTTP/MCP adapters, registries, integrations, and other Node-only helpers.\n- `@lssm/lib.contracts/types` exports the runtime handler context utilities, while `@lssm/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- `@lssm/lib.schema`, `@lssm/lib.design-system`, `@lssm/lib.ui-kit`, `@lssm/lib.ui-kit-web`, `@lssm/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- **ContractSpec**: 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- **SpecRegistry**: 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 `SpecRegistry`, 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 SpecRegistry();\ninstallOp(reg, BeginSignupSpec, beginSignupHandler);\nregisterContractsOnBuilder(gqlSchemaBuilder, reg); // GraphQL\n// or: createRestRouter(reg) // REST\n```\n"}];e(t);export{t as tech_contracts_README_DocBlocks};

package/dist/docs/tech/contracts/create-subscription.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.create-subscription`,title:`Subscriptions via Better Auth Stripe`,summary:`This app uses Better Auth's Stripe plugin for subscription management.`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/create-subscription`,tags:[`tech`,`contracts`,`create-subscription`],body:"### Subscriptions via Better Auth Stripe\n\nThis app uses Better Auth's Stripe plugin for subscription management.\n\nKey endpoints:\n\n- `/api/auth/[...all]` – Better Auth server\n- `/api/auth/stripe/webhook` – Stripe webhook handled by Better Auth\n\nClient usage (org mode):\n\n```ts\nimport { subscription } from '@/lib/auth-client';\n\nawait subscription.upgrade({\n  plan: 'core',\n  annual: true,\n  referenceId: activeOrganization?.id,\n  successUrl: '/dashboard',\n  cancelUrl: '/pricing',\n});\n```\n\nPlans are configured in `src/lib/auth.ts` referencing env-provided price IDs. See Better Auth Stripe docs: [plugins: Stripe](`https://better-auth.com/docs/plugins/stripe.mdx`) and [Using with organizations](`https://www.better-auth.com/docs/plugins/stripe#using-with-organizations`).\n\nLanding pricing UX\n\n- Components: `SectionEyebrow`, `PriceBadge`, `FeatureList`, `PriceCard`\n- Sections: `PricingSection`, `StoryPricingBenefits`\n- Canonical pricing source: `src/lib/pricing/config.ts`\n\nTrial period\n\n- Le plan « Essentiel » inclut une période d’essai gratuite de 30 jours.\n- Config côté auth: `freeTrial: { days: 30 }` dans `src/lib/auth.ts` (Better Auth Stripe plugin).\n- Config côté pricing: `trial: { days: 30 }` dans `src/lib/pricing/config.ts`.\n\nDashboard badges\n\n- Le `Tableau de bord` affiche des badges d’état d’abonnement:\n  - « Essai · se termine le JJ/MM/AAAA » lorsque l’essai est en cours\n  - « Abonnement actif » lorsque l’abonnement est actif\n  - « Annulé · fin au terme de la période » lorsque la résiliation est planifiée\n- Composant: `components/dashboard/DashboardPage/molecules/Header.tsx`\n- Source des états: hook `useProfileBillingPage()` (`components/profile/ProfileBillingPage/hooks/useProfileBillingPage.tsx`)\n"}];e(t);export{t as tech_contracts_create_subscription_DocBlocks};

package/dist/docs/tech/contracts/graphql-typed-outputs.docblock.js

@@ -0,0 +1,180 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.graphql-typed-outputs`,title:`GraphQL Typed Outputs for Contracts`,summary:"Improved `@lssm/lib.contracts` to automatically generate proper GraphQL object types from `SchemaModel` outputs instead of defaulting to `JSON` scalar types.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/graphql-typed-outputs`,tags:[`tech`,`contracts`,`graphql-typed-outputs`],body:`# GraphQL Typed Outputs for Contracts
+
+## Overview
+
+Improved \`@lssm/lib.contracts\` to automatically generate proper GraphQL object types from \`SchemaModel\` outputs instead of defaulting to \`JSON\` scalar types.
+
+## Problem
+
+Previously, when GraphQL operations were defined using contracts with \`SchemaModel\` outputs, the GraphQL schema would default to returning \`JSON\` scalar types. This meant:
+
+- GraphQL clients couldn't query specific fields
+- No type safety for operation outputs
+- Codegen would fail with "must have a selection of subfields" errors
+
+## Solution
+
+### 1. Auto-Type Registration in \`graphql-pothos.ts\`
+
+**File**: \`packages/lssm/libs/contracts/src/server/graphql-pothos.ts\`
+
+**Changes**:
+
+- Scan all contract specs and collect their \`SchemaModel\` outputs
+- Automatically register GraphQL object types for each \`SchemaModel\`
+- Map field types from SchemaModel to proper GraphQL scalar types
+- Update \`resolveGraphQLTypeName\` to check for \`SchemaModel\` names before defaulting to \`JSON\`
+
+**Key Code**:
+
+\`\`\`typescript
+// Build a map of output types we need to register
+const outputTypeCache = new Map<string, AnySchemaModel>();
+for (const spec of reg.listSpecs()) {
+  const out = spec.io.output as AnySchemaModel | ResourceRefDescriptor<boolean>;
+  if (out && 'getZod' in out && typeof out.getZod === 'function') {
+    const model = out as AnySchemaModel;
+    const typeName = model.config?.name ?? 'UnknownOutput';
+    if (!outputTypeCache.has(typeName)) {
+      outputTypeCache.set(typeName, model);
+    }
+  }
+}
+
+// Register all output types as GraphQL object types
+for (const [typeName, model] of outputTypeCache.entries()) {
+  builder.objectType(typeName, {
+    fields: (t) => {
+      // Map each field from SchemaModel to GraphQL field
+      // ...
+    },
+  });
+}
+\`\`\`
+
+### 2. Fix Contract Definitions
+
+**File**: \`packages/hcircle/libs/contracts-coliving/src/interactions/onboarding/org/contracts.ts\`
+
+**Changes**:
+
+- Changed \`GetOrgOnboardingDraftSpec\` from \`defineCommand\` to \`defineQuery\` (read-only operation)
+- Added \`defineQuery\` import
+
+**Before**:
+
+\`\`\`typescript
+export const GetOrgOnboardingDraftSpec = defineCommand({
+  // ...
+});
+\`\`\`
+
+**After**:
+
+\`\`\`typescript
+export const GetOrgOnboardingDraftSpec = defineQuery({
+  // ...
+});
+\`\`\`
+
+### 3. Update All GraphQL Queries
+
+Updated all GraphQL operation calls to select proper subfields based on the output type:
+
+#### Output Types and Their Fields
+
+1. **\`CreateOrgOutput\`**:
+   - \`organizationId: ID!\`
+   - \`orgType: String!\`
+
+2. **\`CompleteUserOnboardingOutput\`**:
+   - \`success: Boolean!\`
+   - \`userId: ID!\`
+
+3. **\`CompleteOrgOnboardingOutput\`**:
+   - \`success: Boolean!\`
+   - \`organizationId: ID!\`
+   - \`orgType: String!\`
+
+4. **\`OnboardingDraft\`** (from resource_ref):
+   - \`id: ID!\`
+   - \`organizationId: ID!\`
+   - \`data: JSON!\`
+   - \`createdAt: DateTime!\`
+   - \`updatedAt: DateTime!\`
+
+5. **\`GetOnboardingDraftOutput\`**:
+   - \`id: ID\`
+   - \`organizationId: ID\`
+   - \`data: JSON\`
+   - \`createdAt: DateTime\`
+   - \`updatedAt: DateTime\`
+
+6. **\`DeleteOnboardingDraftOutput\`**:
+   - \`ok: Boolean!\` _(note: not \`success\`)_
+
+#### Files Updated
+
+1. \`/packages/hcircle/apps/mobile-coliving/src/app/onboarding-org-select.tsx\`
+2. \`/packages/hcircle/apps/mobile-coliving/src/app/onboarding-org.tsx\`
+3. \`/packages/hcircle/apps/mobile-coliving/src/app/onboarding-user.tsx\`
+4. \`/packages/hcircle/apps/web-coliving/src/app/onboarding/user/page.tsx\`
+5. \`/packages/hcircle/apps/web-coliving/src/components/onboarding/OnboardingFlow.tsx\`
+6. \`/packages/hcircle/apps/web-coliving/src/components/onboarding/OrgSelectionFlow.tsx\`
+
+**Example Before**:
+
+\`\`\`graphql
+mutation CreateOrg($orgType: String!, $name: String!, $slug: String!) {
+  createOrganization(input: { orgType: $orgType, name: $name, slug: $slug })
+}
+\`\`\`
+
+**Example After**:
+
+\`\`\`graphql
+mutation CreateOrg($orgType: String!, $name: String!, $slug: String!) {
+  createOrganization(input: { orgType: $orgType, name: $name, slug: $slug }) {
+    organizationId
+    orgType
+  }
+}
+\`\`\`
+
+## Benefits
+
+1. **Type Safety**: Full type safety for GraphQL operation outputs
+2. **Auto-Generated Types**: No need to manually specify \`returns\` in contract transport config
+3. **Better DX**: GraphQL clients can now query specific fields and benefit from autocomplete
+4. **Consistency**: All \`SchemaModel\` outputs are automatically typed in GraphQL
+5. **Backward Compatible**: Operations with explicit \`returns\` config still work as before
+
+## Testing
+
+All GraphQL codegen now passes:
+
+\`\`\`bash
+cd packages/hcircle/libs/gql-client-coliving
+bun graphql-codegen --config codegen.ts  # ✅ Success
+\`\`\`
+
+## Migration Guide for Other Verticals
+
+To apply this to other verticals (e.g., Artisanos, Strit):
+
+1. **No code changes needed** - the improved \`graphql-pothos.ts\` automatically handles all \`SchemaModel\` outputs
+2. **Update GraphQL queries** - Add field selections to queries that previously returned \`JSON\`
+3. **Fix query/command mismatches** - Ensure read-only operations use \`defineQuery\` instead of \`defineCommand\`
+
+## Future Improvements
+
+1. Add support for nested \`SchemaModel\` references (currently only supports scalar fields)
+2. Add support for array fields of SchemaModels
+3. Consider auto-generating field selections based on the output type to reduce boilerplate
+
+## Related Documentation
+
+- [Contracts README](../../packages/lssm/libs/contracts/README.md)
+- [Onboarding System](./hcircle/IMPLEMENTATION_COMPLETE.md)
+- [GraphQL Architecture](./graphql/architecture.md)
+`}];e(t);export{t as tech_contracts_graphql_typed_outputs_DocBlocks};

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

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{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 '@lssm/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"}];e(t);export{t as tech_contracts_migrations_DocBlocks};

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

@@ -0,0 +1,38 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.openapi-export`,title:`OpenAPI export (OpenAPI 3.1) from SpecRegistry`,summary:`Generate a deterministic OpenAPI document from a SpecRegistry 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 SpecRegistry
+
+### 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: \`@lssm/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: SpecRegistry\`
+- \`default(): SpecRegistry | Promise<SpecRegistry>\`
+- \`createRegistry(): SpecRegistry | Promise<SpecRegistry>\`
+
+### 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.`}];e(t);export{t as tech_contracts_openapi_export_DocBlocks};

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

@@ -0,0 +1,62 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{id:`docs.tech.contracts.ops-to-presentation-linking`,title:`Ops ↔ Presentation linking (V2)`,summary:`This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) 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)
+
+This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.
+
+- Location: \`@lssm/lib.contracts/src/features.ts\`
+- Field: \`FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]\`
+- Validation: \`installFeature()\` validates that linked ops exist in \`SpecRegistry\` and linked presentations exist in the registry, and that declared targets are present.
+
+Example:
+
+\`\`\`ts
+import type { SpecRegistry } from '@lssm/lib.contracts/src/registry';
+import { FeatureRegistry, createFeatureModule } from '@lssm/lib.contracts';
+
+export function buildFeaturesWithOps(ops: SpecRegistry) {
+  const features = new FeatureRegistry();
+  features.register(
+    createFeatureModule(
+      {
+        key: 'myapp.widgets.linkage',
+        title: 'Widgets (linked)',
+        description: 'Links create/update ops to UI presentations',
+        domain: 'widgets',
+        tags: ['widgets', 'linkage'],
+        stability: 'beta',
+      },
+      {
+        operations: [
+          { name: 'widgets.create', version: 1 },
+          { name: 'widgets.update', version: 1 },
+        ],
+        presentations: [{ name: 'myapp.widgets.editor.page', version: 1 }],
+        opToPresentation: [
+          {
+            op: { name: 'widgets.create', version: 1 },
+            pres: { name: 'myapp.widgets.editor.page', version: 1 },
+          },
+          {
+            op: { name: 'widgets.update', version: 1 },
+            pres: { name: 'myapp.widgets.editor.page', version: 1 },
+          },
+        ],
+        presentationsTargets: [
+          {
+            name: 'myapp.widgets.editor.page',
+            version: 1,
+            targets: ['react', 'markdown'],
+          },
+        ],
+      }
+    )
+  );
+  return { features };
+}
+\`\`\`
+
+Notes
+
+- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.
+- Presentations can target multiple outputs (\`react\`, \`markdown\`, \`application/json\`, \`application/xml\`).
+- Use \`renderFeaturePresentation()\` to render a descriptor to a given target with a component map.
+`}];e(t);export{t as tech_contracts_ops_to_presentation_linking_DocBlocks};

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

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

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

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

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

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../registry.js";const t=[{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 `@lssm/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 `@lssm/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 '@lssm/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 `@lssm/lib.design-system`.\n\n```ts\nimport { ThemeRegistry } from '@lssm/lib.contracts/themes';\nimport { mapTokensForPlatform } from '@lssm/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"}];e(t);export{t as tech_contracts_themes_DocBlocks};