@lssm/lib.contracts 0.0.0-canary-20251217083314 → 0.0.0-canary-20251219202229

package/dist/docs/tech/studio/team-invitations.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-invitations.docblock.js","names":["tech_studio_team_invitations_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/team-invitations.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_team_invitations_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.team-invitations',\n    title: 'Studio Teams & Invitations',\n    summary:\n      'Admin-only team management and email invitation flow to join an organization and optionally a team.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/team-invitations',\n    tags: ['studio', 'teams', 'invitations', 'access-control', 'onboarding'],\n    body: `# Studio Teams & Invitations\n\nStudio uses **organization membership** as the base access model. Teams are optional and used to refine access to projects.\n\n## Who can manage teams?\n\n- **Admins/owners only**: create, rename, delete teams; manage project team access; issue invitations.\n\n## Invitation data model\n\n- \\`Invitation\\` rows are stored under an organization and target an **email** address.\\n\n- An invitation can optionally target a \\`teamId\\`, which will grant the user membership in that team upon acceptance.\n\nKey fields:\n- \\`email\\`: invited address (must match the accepting user's account email)\\n\n- \\`status\\`: \\`pending | accepted | declined | expired\\`\\n\n- \\`teamId?\\`: optional team to join\\n\n- \\`inviterId\\`: user who issued the invitation\n\n## GraphQL surfaces\n\n- Team CRUD (admin-only):\\n\n  - \\`createTeam(name)\\`\\n\n  - \\`renameTeam(teamId, name)\\`\\n\n  - \\`deleteTeam(teamId)\\`\\n\n\n- Invitations (admin-only):\\n\n  - \\`organizationInvitations\\`\\n\n  - \\`inviteToOrganization(email, role?, teamId?)\\` → returns \\`inviteUrl\\` and whether an email was sent\n\n## Accepting an invitation\n\nThe invite link is served as:\\n\n- \\`/invite/{invitationId}\\`\n\nAcceptance rules:\n- The user must be authenticated.\\n\n- The authenticated user’s email must match \\`Invitation.email\\`.\\n\n- If not already a member, create \\`Member(userId, organizationId, role)\\`.\\n\n- If \\`teamId\\` is present, ensure \\`TeamMember(teamId, userId)\\`.\\n\n- Mark invitation \\`status='accepted'\\` and set \\`acceptedAt\\`.\\n\n- Set \\`activeOrganizationId\\` for the session so \\`/studio/*\\` routes work immediately.\n\n## Email delivery\n\n- If \\`RESEND_API_KEY\\` is set, the system attempts to send an email.\\n\n- Otherwise, the UI uses the returned \\`inviteUrl\\` for manual copy/share.\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_team_invitations_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,yCAAqD,CAChE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAS;EAAe;EAAkB;EAAa;CACxE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDP,CACF;AAED,kBAAkB,uCAAuC"}

package/dist/docs/tech/studio/workspace-ops.docblock.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/docs/tech/studio/workspace-ops.docblock.d.ts
 declare const tech_studio_workspace_ops_DocBlocks: DocBlock[];
 //#endregion
-export { tech_studio_workspace_ops_DocBlocks };
+export { tech_studio_workspace_ops_DocBlocks };
+//# sourceMappingURL=workspace-ops.docblock.d.ts.map

package/dist/docs/tech/studio/workspace-ops.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-ops.docblock.d.ts","names":[],"sources":["../../../../src/docs/tech/studio/workspace-ops.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,qCAAqC"}

package/dist/docs/tech/studio/workspace-ops.docblock.js

@@ -45,4 +45,5 @@ These endpoints are **read-only** in v1 and never push to git:
 registerDocBlocks(tech_studio_workspace_ops_DocBlocks);
 
 //#endregion
-export { tech_studio_workspace_ops_DocBlocks };
+export { tech_studio_workspace_ops_DocBlocks };
+//# sourceMappingURL=workspace-ops.docblock.js.map

package/dist/docs/tech/studio/workspace-ops.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-ops.docblock.js","names":["tech_studio_workspace_ops_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/workspace-ops.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_workspace_ops_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.workspace_ops',\n    title: 'Workspace ops (repo-linked): list / validate / deps / diff',\n    summary:\n      'Read-only repo operations used by Studio to inspect and validate a linked ContractSpec workspace.',\n    kind: 'reference',\n    visibility: 'mixed',\n    route: '/docs/tech/studio/workspace-ops',\n    tags: ['studio', 'repo', 'workspace', 'validate', 'diff'],\n    body: `## API surface (api-contractspec)\n\nBase: \\`/api/workspace-ops\\`\n\nThese endpoints are **read-only** in v1 and never push to git:\n\n- \\`GET /api/workspace-ops/:integrationId/config?organizationId=\\`\n- \\`GET /api/workspace-ops/:integrationId/specs?organizationId=\\`\n- \\`POST /api/workspace-ops/:integrationId/validate\\` (body: organizationId, files?, pattern?)\n- \\`POST /api/workspace-ops/:integrationId/deps\\` (body: organizationId, pattern?)\n- \\`POST /api/workspace-ops/:integrationId/diff\\` (body: organizationId, specPath, baseline?, breakingOnly?)\n\n## Repo resolution\n\n- The repo root is resolved from the Studio Integration (\\`IntegrationProvider.GITHUB\\`) config:\n  - \\`config.repoCachePath\\` (preferred) or \\`config.localPath\\`\n- Resolution is constrained to \\`CONTRACTSPEC_REPO_CACHE_DIR\\` (default: \\`/tmp/contractspec-repos\\`)\n\n## Intended UX\n\n- Studio Assistant can run these checks and present results as suggestions.\n- Users can copy equivalent CLI commands for local runs:\n  - \\`contractspec validate\\`\n  - \\`contractspec deps\\`\n  - \\`contractspec diff --baseline <ref>\\`\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_workspace_ops_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,sCAAkD,CAC7D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAQ;EAAa;EAAY;EAAO;CACzD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BP,CACF;AAED,kBAAkB,oCAAoC"}

package/dist/docs/tech/studio/workspaces.docblock.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/docs/tech/studio/workspaces.docblock.d.ts
 declare const tech_studio_workspaces_DocBlocks: DocBlock[];
 //#endregion
-export { tech_studio_workspaces_DocBlocks };
+export { tech_studio_workspaces_DocBlocks };
+//# sourceMappingURL=workspaces.docblock.d.ts.map

package/dist/docs/tech/studio/workspaces.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.docblock.d.ts","names":[],"sources":["../../../../src/docs/tech/studio/workspaces.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,kCAAkC"}

package/dist/docs/tech/studio/workspaces.docblock.js

@@ -60,4 +60,5 @@ Studio and Sandbox both use a shared shell:
 registerDocBlocks(tech_studio_workspaces_DocBlocks);
 
 //#endregion
-export { tech_studio_workspaces_DocBlocks };
+export { tech_studio_workspaces_DocBlocks };
+//# sourceMappingURL=workspaces.docblock.js.map

package/dist/docs/tech/studio/workspaces.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.docblock.js","names":["tech_studio_workspaces_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/workspaces.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_workspaces_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.workspaces',\n    title: 'Studio projects, teams, environments',\n    summary:\n      'Organization-first Studio: projects live under an organization; teams refine access; projects deploy to multiple environments.',\n    kind: 'reference',\n    visibility: 'mixed',\n    route: '/docs/tech/studio/workspaces',\n    tags: ['studio', 'projects', 'teams', 'rbac', 'environments'],\n    body: `## Concepts\n\n- **Organization**: the primary grouping boundary for Studio projects.\n- **Project**: one application (specs, overlays, deployments, integrations, evolution, learning).\n- **Team**: refines who can see/edit a project within an organization.\n- **Environment**: deployment target (Development / Staging / Production).\n\n## Project access (teams + admin override)\n\nStudio uses multi-team sharing to refine access:\n\n- **Admins/owners** can access all projects.\n- If a project is shared with **no teams**, it is **org-wide** (all org members).\n- If a project is shared with **one or more teams**, it is visible to:\n  - admins/owners, and\n  - members of any linked team.\n\n## Current persistence (DB + GraphQL)\n\n- DB (Prisma): \\`StudioProject\\`, \\`Team\\`, \\`TeamMember\\`, \\`StudioProjectTeam\\`\n- GraphQL:\n  - \\`myStudioProjects\\`\n  - \\`createStudioProject(input.teamIds?)\\`\n  - \\`myTeams\\`\n  - \\`projectTeams(projectId)\\`\n  - \\`setProjectTeams(projectId, teamIds)\\`\n\n## UI shell behavior\n\nStudio and Sandbox both use a shared shell:\n\n- Project selector → Module navigation → Environment selector\n- Always-on Assistant button (floating)\n- Learning journey progress (Studio persists learning events; Sandbox stays local-only)\n\n## Routing\n\n- \\`/studio/projects\\`: create/select/delete projects (organization-first).\n- \\`/studio/{projectSlug}/*\\`: project modules (canvas/specs/deploy/integrations/evolution/learning).\n- \\`/studio/learning\\`: learning hub without selecting a project.\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_workspaces_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,mCAA+C,CAC1D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAY;EAAS;EAAQ;EAAe;CAC7D,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCP,CACF;AAED,kBAAkB,iCAAiC"}

package/dist/docs/tech/telemetry-ingest.docblock.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/docs/tech/telemetry-ingest.docblock.d.ts
 declare const tech_telemetry_ingest_DocBlocks: DocBlock[];
 //#endregion
-export { tech_telemetry_ingest_DocBlocks };
+export { tech_telemetry_ingest_DocBlocks };
+//# sourceMappingURL=telemetry-ingest.docblock.d.ts.map

package/dist/docs/tech/telemetry-ingest.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-ingest.docblock.d.ts","names":[],"sources":["../../../src/docs/tech/telemetry-ingest.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,iCAAiC"}

package/dist/docs/tech/telemetry-ingest.docblock.js

@@ -153,4 +153,5 @@ This allows future migration without changing client code.
 registerDocBlocks(tech_telemetry_ingest_DocBlocks);
 
 //#endregion
-export { tech_telemetry_ingest_DocBlocks };
+export { tech_telemetry_ingest_DocBlocks };
+//# sourceMappingURL=telemetry-ingest.docblock.js.map

package/dist/docs/tech/telemetry-ingest.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-ingest.docblock.js","names":["tech_telemetry_ingest_DocBlocks: DocBlock[]"],"sources":["../../../src/docs/tech/telemetry-ingest.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../registry';\n\nexport const tech_telemetry_ingest_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.telemetry.ingest',\n    title: 'Telemetry Ingest Endpoint',\n    summary:\n      'Server-side telemetry ingestion for ContractSpec clients (VS Code extension, CLI, etc.).',\n    kind: 'reference',\n    visibility: 'internal',\n    route: '/docs/tech/telemetry/ingest',\n    tags: ['telemetry', 'api', 'posthog', 'analytics'],\n    body: `# Telemetry Ingest Endpoint\n\nThe ContractSpec API provides a telemetry ingest endpoint for clients to send product analytics events.\n\n## Endpoint\n\n\\`\\`\\`\nPOST /api/telemetry/ingest\n\\`\\`\\`\n\n## Request\n\n\\`\\`\\`json\n{\n  \"event\": \"contractspec.vscode.command_run\",\n  \"distinct_id\": \"client-uuid\",\n  \"properties\": {\n    \"command\": \"validate\"\n  },\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n\\`\\`\\`\n\n### Headers\n\n| Header | Description |\n|--------|-------------|\n| \\`x-contractspec-client-id\\` | Optional client identifier (used as fallback for distinct_id) |\n| \\`Content-Type\\` | Must be \\`application/json\\` |\n\n### Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| \\`event\\` | string | Yes | Event name (e.g., \\`contractspec.vscode.activated\\`) |\n| \\`distinct_id\\` | string | Yes | Anonymous client identifier |\n| \\`properties\\` | object | No | Event properties |\n| \\`timestamp\\` | string | No | ISO 8601 timestamp |\n\n## Response\n\n\\`\\`\\`json\n{\n  \"success\": true\n}\n\\`\\`\\`\n\n## Configuration\n\nThe endpoint requires \\`POSTHOG_PROJECT_KEY\\` environment variable to be set. If not configured, events are accepted but not forwarded.\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| \\`POSTHOG_HOST\\` | PostHog host URL | \\`https://eu.posthog.com\\` |\n| \\`POSTHOG_PROJECT_KEY\\` | PostHog project API key | (required) |\n\n## Privacy\n\n- No PII is collected or stored\n- \\`distinct_id\\` is an anonymous client-generated UUID\n- File paths and source code are never included in events\n- Respects VS Code telemetry settings on the client side\n\n## Events\n\n### Extension Events\n\n| Event | Description | Properties |\n|-------|-------------|------------|\n| \\`contractspec.vscode.activated\\` | Extension activated | \\`version\\` |\n| \\`contractspec.vscode.command_run\\` | Command executed | \\`command\\` |\n| \\`contractspec.vscode.mcp_call\\` | MCP call made | \\`endpoint\\`, \\`tool\\` |\n\n### API Events\n\n| Event | Description | Properties |\n|-------|-------------|------------|\n| \\`contractspec.api.mcp_request\\` | MCP request processed | \\`endpoint\\`, \\`method\\`, \\`success\\`, \\`duration_ms\\` |\n`,\n  },\n  {\n    id: 'docs.tech.telemetry.hybrid',\n    title: 'Hybrid Telemetry Model',\n    summary:\n      'How ContractSpec clients choose between direct PostHog and API-routed telemetry.',\n    kind: 'usage',\n    visibility: 'internal',\n    route: '/docs/tech/telemetry/hybrid',\n    tags: ['telemetry', 'architecture', 'posthog'],\n    body: `# Hybrid Telemetry Model\n\nContractSpec uses a hybrid telemetry model where clients can send events either directly to PostHog or via the API server.\n\n## Decision Flow\n\n\\`\\`\\`\nIs contractspec.api.baseUrl configured?\n├── Yes → Send via /api/telemetry/ingest\n└── No → Is posthogProjectKey configured?\n    ├── Yes → Send directly to PostHog\n    └── No → Telemetry disabled\n\\`\\`\\`\n\n## Benefits\n\n### Direct PostHog\n- No server dependency\n- Works offline (with batching)\n- Lower latency\n\n### Via API\n- Centralized key management (no client-side keys)\n- Server-side enrichment and validation\n- Rate limiting and abuse prevention\n- Easier migration to other providers\n\n## Recommendation\n\n- **Development**: Use direct PostHog with a dev project key\n- **Production**: Route via API for better governance\n\n## Future: OpenTelemetry\n\nThe current PostHog implementation is behind a simple interface that can be swapped for OpenTelemetry:\n\n\\`\\`\\`typescript\ninterface TelemetryClient {\n  send(event: TelemetryEvent): Promise<void>;\n}\n\\`\\`\\`\n\nThis allows future migration without changing client code.\n`,\n  },\n];\n\nregisterDocBlocks(tech_telemetry_ingest_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,kCAA8C,CACzD;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAa;EAAO;EAAW;EAAY;CAClD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+EP,EACD;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAa;EAAgB;EAAU;CAC9C,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CP,CACF;AAED,kBAAkB,gCAAgC"}

package/dist/docs/tech/templates/runtime.docblock.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/docs/tech/templates/runtime.docblock.d.ts
 declare const tech_templates_runtime_DocBlocks: DocBlock[];
 //#endregion
-export { tech_templates_runtime_DocBlocks };
+export { tech_templates_runtime_DocBlocks };
+//# sourceMappingURL=runtime.docblock.d.ts.map

package/dist/docs/tech/templates/runtime.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.docblock.d.ts","names":[],"sources":["../../../../src/docs/tech/templates/runtime.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,kCAAkC"}

package/dist/docs/tech/templates/runtime.docblock.js

@@ -18,4 +18,5 @@ const tech_templates_runtime_DocBlocks = [{
 registerDocBlocks(tech_templates_runtime_DocBlocks);
 
 //#endregion
-export { tech_templates_runtime_DocBlocks };
+export { tech_templates_runtime_DocBlocks };
+//# sourceMappingURL=runtime.docblock.js.map

package/dist/docs/tech/templates/runtime.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.docblock.js","names":["tech_templates_runtime_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/templates/runtime.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_templates_runtime_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.templates.runtime',\n    title: 'ContractSpec Template Runtime (Phase 9)',\n    summary:\n      'Phase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/templates/runtime',\n    tags: ['tech', 'templates', 'runtime'],\n    body: \"## ContractSpec Template Runtime (Phase 9)\\n\\nPhase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.\\n\\n### Building Blocks\\n\\n- **Local database** \\u2013 `@lssm/lib.runtime-local` wraps `sql.js` (SQLite WASM) and `IndexedDB` so we can seed demo data, run migrations, and persist state between sessions. Tests point the runtime to `node_modules/sql.js/dist` so CI doesn\\u2019t need a browser.\\n- **Local GraphQL** \\u2013 `LocalGraphQLClient` wires Apollo Client + SchemaLink to resolvers for tasks, messaging, and i18n recipes. All `/templates`, `/studio`, and `/sandbox` previews use those resolvers so we never call remote APIs during demos.\\n- **Template registry + installer** \\u2013 `.../templates/registry.ts` stores the catalog (todos, messaging, recipes). `TemplateInstaller` can seed the runtime (`install`) or export a base64 snapshot via the new `saveTemplateToStudio` mutation.\\n- **TemplateShell** \\u2013 Shared UI wrapper that creates a `TemplateRuntimeProvider`, shows `LocalDataIndicator`, and (optionally) surfaces the new `SaveToStudioButton`.\\n\\n### Runtime Flows\\n\\n1. `/templates` now opens a modal that renders `TemplateShell` for each template. Users can explore without leaving the marketing site.\\n2. `/studio` switches to a tabbed mini-app (Projects, Canvas, Specs, Deploy) to showcase Studio surfaces with mock data. Visitors see a **preview** shell, while authenticated users (Better Auth via Sigil) unlock full persistence, versioning, and deployment controls.\\n3. `/sandbox` lets visitors pick a template and mode (Playground, Spec Editor, Visual Builder). The console at the bottom streams runtime events for transparency.\\n\\n### GraphQL Mutations\\n\\n- `saveTemplateToStudio(input: SaveTemplateInput!): SaveTemplateResult!` writes a placeholder project + spec so that templates installed from the sandbox appear in Studio. The mutation is intentionally simple right now: it records which template was imported, stores metadata, and returns `{ projectId, status: 'QUEUED' }` for the UI.\\n- `saveCanvasDraft(input: SaveCanvasDraftInput!): CanvasVersion!` snapshots the current Visual Builder nodes to a draft version tied to a canvas overlay. Inputs include `canvasId`, arbitrary `nodes` JSON, and an optional `label`. The resolver enforces org/org access before calling `CanvasVersionManager`.\\n- `deployCanvasVersion(input: DeployCanvasVersionInput!): CanvasVersion!` promotes a previously saved draft (`versionId`) to the deployed state. The returned object includes `status`, `nodes`, `createdAt`, and `createdBy` for UI timelines.\\n- `undoCanvasVersion(input: UndoCanvasInput!): CanvasVersion` rewinds the visual builder to the prior snapshot (returns `null` when history is empty) so Studio\\u2019s toolbar can surface \\u201cUndo\\u201d without shelling out to local storage.\\n\\n### Studio GraphQL endpoint\\n\\n- The landing app exposes the Studio schema at `/api/studio/graphql` via Yoga so React Query hooks (`useStudioProjects`, `useCreateStudioProject`, `useDeployStudioProject`, etc.) can talk to the bundle without spinning up a separate server.\\n\\n### Spec Editor typing\\n\\n- Studio\\u2019s spec editor now preloads Monaco with ambient declarations for `@lssm/lib.contracts` and `zod`, so snippets receive autocomplete and inline errors even before the spec ships to the backend. The helper lives in `presentation/components/studio/organisms/monaco-spec-types.ts` and registers the extra libs once per browser session via `monaco.languages.typescript.typescriptDefaults.addExtraLib`.\\n- Compiler options are aligned with our frontend toolchain (ES2020 + React JSX) which means drafts written in the editor behave like the compiled artifacts that flow through Studio pipelines.\\n\\n### Spec templates\\n\\n- Selecting a spec type now injects a ready-to-edit scaffold (capability, workflow, policy, dataview, component) so authors start from a canonical layout instead of a blank file. Templates live alongside `SpecEditor.tsx`, and we only overwrite the content when the previous value is empty or when the author explicitly switches types via the dropdown.\\n\\n### Spec preview\\n\\n- The validation side panel now embeds a `SpecPreview` widget that shows validation errors alongside transport artifacts (GraphQL schema, REST endpoints, component summaries) once a preview run completes. Tabs let authors toggle between \\u201cValidation\\u201d and \\u201cArtifacts,\\u201d mirroring the UX described in the Studio plan.\\n\\n### Testing\\n\\n- `src/templates/__tests__/runtime.test.ts` covers todos CRUD, messaging delivery, and recipe locale switching through the local GraphQL API.\\n- Studio infrastructure tests live in `src/__tests__/e2e/project-lifecycle.test.ts` and continue to exercise project creation + deploy flows.\\n\\n### Next Steps\\n\\nFuture templates can register their React components via `registerTemplateComponents(templateId, components)` so TemplateShell can render them automatically. When new templates are added, remember to:\\n\\n1. Update the registry entry (schema + tags).\\n2. Register components inside `presentation/components/templates`.\\n3. Document the template under `docs/templates/`.\\n\\n\\n\\n\\n\\n\",\n  },\n];\nregisterDocBlocks(tech_templates_runtime_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,mCAA+C,CAC1D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAQ;EAAa;EAAU;CACtC,MAAM;CACP,CACF;AACD,kBAAkB,iCAAiC"}

package/dist/docs/tech/vscode-extension.docblock.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/docs/tech/vscode-extension.docblock.d.ts
 declare const tech_vscode_extension_DocBlocks: DocBlock[];
 //#endregion
-export { tech_vscode_extension_DocBlocks };
+export { tech_vscode_extension_DocBlocks };
+//# sourceMappingURL=vscode-extension.docblock.d.ts.map

package/dist/docs/tech/vscode-extension.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vscode-extension.docblock.d.ts","names":[],"sources":["../../../src/docs/tech/vscode-extension.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,iCAAiC"}

package/dist/docs/tech/vscode-extension.docblock.js

@@ -99,4 +99,5 @@ Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab th
 registerDocBlocks(tech_vscode_extension_DocBlocks);
 
 //#endregion
-export { tech_vscode_extension_DocBlocks };
+export { tech_vscode_extension_DocBlocks };
+//# sourceMappingURL=vscode-extension.docblock.js.map

package/dist/docs/tech/vscode-extension.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vscode-extension.docblock.js","names":["tech_vscode_extension_DocBlocks: DocBlock[]"],"sources":["../../../src/docs/tech/vscode-extension.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../registry';\n\nexport const tech_vscode_extension_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.vscode.extension',\n    title: 'ContractSpec VS Code Extension',\n    summary:\n      'VS Code extension for spec-first development with validation, scaffolding, and MCP integration.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/vscode/extension',\n    tags: ['vscode', 'extension', 'tooling', 'dx'],\n    body: `# ContractSpec VS Code Extension\n\nThe ContractSpec VS Code extension provides spec-first development tooling directly in your editor.\n\n## Features\n\n- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files\n- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)\n- **Spec Explorer**: List and navigate all specs in your workspace\n- **Dependency Analysis**: Visualize spec dependencies and detect cycles\n- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol\n- **Snippets**: Code snippets for common ContractSpec patterns\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| \\`ContractSpec: Validate Current Spec\\` | Validate the currently open spec file |\n| \\`ContractSpec: Validate All Specs\\` | Validate all spec files in the workspace |\n| \\`ContractSpec: Build/Scaffold\\` | Generate handler/component from the current spec |\n| \\`ContractSpec: List All Specs\\` | Show all specs in the workspace |\n| \\`ContractSpec: Analyze Dependencies\\` | Analyze and visualize spec dependencies |\n| \\`ContractSpec: Search Docs (MCP)\\` | Search documentation via MCP |\n\n## Configuration\n\n| Setting | Description | Default |\n|---------|-------------|---------|\n| \\`contractspec.api.baseUrl\\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \\`\"\"\\` |\n| \\`contractspec.telemetry.posthogHost\\` | PostHog host URL for direct telemetry | \\`\"https://eu.posthog.com\"\\` |\n| \\`contractspec.telemetry.posthogProjectKey\\` | PostHog project key for direct telemetry | \\`\"\"\\` |\n| \\`contractspec.validation.onSave\\` | Run validation on save | \\`true\\` |\n| \\`contractspec.validation.onOpen\\` | Run validation on open | \\`true\\` |\n\n## Architecture\n\nThe extension uses:\n- \\`@lssm/module.contractspec-workspace\\` for pure analysis + templates\n- \\`@lssm/bundle.contractspec-workspace\\` for workspace services + adapters\n\nThis allows the extension to work without requiring the CLI to be installed.\n\n## Telemetry\n\nThe extension uses a hybrid telemetry approach:\n1. If \\`contractspec.api.baseUrl\\` is configured → send to API \\`/api/telemetry/ingest\\`\n2. Otherwise → send directly to PostHog (if project key configured)\n\nTelemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.\n`,\n  },\n  {\n    id: 'docs.tech.vscode.snippets',\n    title: 'ContractSpec Snippets',\n    summary: 'Code snippets for common ContractSpec patterns in VS Code.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/vscode/snippets',\n    tags: ['vscode', 'snippets', 'dx'],\n    body: `# ContractSpec Snippets\n\nThe VS Code extension includes snippets for common ContractSpec patterns.\n\n## Available Snippets\n\n| Prefix | Description |\n|--------|-------------|\n| \\`contractspec-command\\` | Create a new command (write operation) |\n| \\`contractspec-query\\` | Create a new query (read-only operation) |\n| \\`contractspec-event\\` | Create a new event |\n| \\`contractspec-docblock\\` | Create a new DocBlock |\n| \\`contractspec-telemetry\\` | Create a new TelemetrySpec |\n| \\`contractspec-presentation\\` | Create a new Presentation |\n\n## Usage\n\nType the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.\n`,\n  },\n];\n\nregisterDocBlocks(tech_vscode_extension_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,kCAA8C,CACzD;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAa;EAAW;EAAK;CAC9C,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDP,EACD;CACE,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAY;EAAK;CAClC,MAAM;;;;;;;;;;;;;;;;;;;CAmBP,CACF;AAED,kBAAkB,gCAAgC"}

package/dist/docs/tech/workflows/overview.docblock.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/docs/tech/workflows/overview.docblock.d.ts
 declare const tech_workflows_overview_DocBlocks: DocBlock[];
 //#endregion
-export { tech_workflows_overview_DocBlocks };
+export { tech_workflows_overview_DocBlocks };
+//# sourceMappingURL=overview.docblock.d.ts.map

package/dist/docs/tech/workflows/overview.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.docblock.d.ts","names":[],"sources":["../../../../src/docs/tech/workflows/overview.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,mCAAmC"}

package/dist/docs/tech/workflows/overview.docblock.js

@@ -18,4 +18,5 @@ const tech_workflows_overview_DocBlocks = [{
 registerDocBlocks(tech_workflows_overview_DocBlocks);
 
 //#endregion
-export { tech_workflows_overview_DocBlocks };
+export { tech_workflows_overview_DocBlocks };
+//# sourceMappingURL=overview.docblock.js.map

package/dist/docs/tech/workflows/overview.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.docblock.js","names":["tech_workflows_overview_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/workflows/overview.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_workflows_overview_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.workflows.overview',\n    title: 'WorkflowSpec Overview',\n    summary:\n      'WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/workflows/overview',\n    tags: ['tech', 'workflows', 'overview'],\n    body: \"# WorkflowSpec Overview\\n\\n## Purpose\\n\\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\\n\\n## Core Types\\n\\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\\n- `WorkflowDefinition`:\\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\\n  - `steps[]`: ordered list of `Step` descriptors.\\n  - `transitions[]`: directed edges between steps with optional expressions.\\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\\n- `Step`:\\n  - `type`: `human`, `automation`, or `decision`.\\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\\n- `Transition`: `from` \\u2192 `to` with optional `condition` string (simple data expressions).\\n\\n## Registry & Validation\\n\\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\\n  - Duplicate step IDs.\\n  - Unknown `from`/`to` transitions.\\n  - Empty guards/conditions.\\n  - Reachability from the entry step.\\n  - Cycles in the graph.\\n  - Operation/Form references against provided registries.\\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\\n\\n## Runtime\\n\\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\\n  - `start(name, version?, initialData?)` returns a `workflowId`.\\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\\n  - `getState(workflowId)` retrieves the latest state snapshot.\\n  - `cancel(workflowId)` marks the workflow as cancelled.\\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\\n- React bindings (`@lssm/lib.presentation-runtime-react`):\\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\\n  - `WorkflowStepper` progress indicator using design-system Stepper.\\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\\n\\n## Authoring Checklist\\n\\n1. Reuse existing operations/forms; create new specs when missing.\\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\\n\\n## Testing\\n\\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\\n\\n## Tooling\\n\\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\\n\\n## Next Steps (Non-MVP)\\n\\n- Persistence adapters (database/file) for workflow state (Phase 2).\\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\\n- Telemetry hooks for step execution metrics.\\n\\n\",\n  },\n];\nregisterDocBlocks(tech_workflows_overview_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,oCAAgD,CAC3D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAQ;EAAa;EAAW;CACvC,MAAM;CACP,CACF;AACD,kBAAkB,kCAAkC"}

package/dist/docs/tech-contracts.docs.d.ts

@@ -3,4 +3,5 @@ import { DocBlock } from "./types.js";
 //#region src/docs/tech-contracts.docs.d.ts
 declare const techContractsDocs: DocBlock[];
 //#endregion
-export { techContractsDocs };
+export { techContractsDocs };
+//# sourceMappingURL=tech-contracts.docs.d.ts.map

package/dist/docs/tech-contracts.docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tech-contracts.docs.d.ts","names":[],"sources":["../../src/docs/tech-contracts.docs.ts"],"sourcesContent":[],"mappings":";;;cAGa,mBAAmB"}

package/dist/docs/tech-contracts.docs.js

@@ -1,3 +1,5 @@
+import { registerDocBlocks } from "./registry.js";
+
 //#region src/docs/tech-contracts.docs.ts
 const techContractsDocs = [{
 	id: "docs.tech.contracts.presentations-v2",
@@ -88,6 +90,8 @@ PII paths (JSON-like) are redacted from rendered outputs.
 
 Host apps use a \`componentMap\` (e.g., \`'sigil.webauth.tabs' → WebAuthTabs\`) and a BlockNote renderer to turn the React render descriptor into elements.`
 }];
+registerDocBlocks(techContractsDocs);
 
 //#endregion
-export { techContractsDocs };
+export { techContractsDocs };
+//# sourceMappingURL=tech-contracts.docs.js.map

package/dist/docs/tech-contracts.docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tech-contracts.docs.js","names":["techContractsDocs: DocBlock[]"],"sources":["../../src/docs/tech-contracts.docs.ts"],"sourcesContent":["import type { DocBlock } from './types';\nimport { registerDocBlocks } from './registry';\n\nexport const techContractsDocs: DocBlock[] = [\n  {\n    id: 'docs.tech.contracts.presentations-v2',\n    title: 'Presentations V2 — Unified Descriptor & Transform Engine',\n    summary:\n      'How PresentationDescriptorV2 and TransformEngine keep docs/renderers consistent.',\n    visibility: 'public',\n    route: '/docs/tech/contracts/presentations-v2',\n    kind: 'reference',\n    tags: ['presentations', 'docs', 'mcp'],\n    body: `## Presentations V2 — Unified Descriptor & Transform Engine\n\n### Purpose\n\nUnify presentations into one descriptor (\\`PresentationDescriptorV2\\`) that declares a single source (React component key or BlockNote doc) and a list of output targets (react, markdown, application/json, application/xml). A pluggable \\`TransformEngine\\` renders any target and applies PII redaction.\n\n### Types\n\n\\`\\`\\`ts\ntype PresentationTarget =\n  | 'react'\n  | 'markdown'\n  | 'application/json'\n  | 'application/xml';\n\ntype PresentationSource =\n  | {\n      type: 'component';\n      framework: 'react';\n      componentKey: string;\n      props?: AnySchemaModel;\n    }\n  | { type: 'blocknotejs'; docJson: unknown; blockConfig?: unknown };\n\ninterface PresentationDescriptorV2 {\n  meta: PresentationV2Meta; // includes partial OwnerShipMeta + description\n  policy?: { flags?: string[]; pii?: string[] };\n  source: PresentationSource;\n  targets: PresentationTarget[];\n}\n\n// Shared ownership schema (source of truth in @lssm/lib.contracts/src/ownership.ts)\ninterface OwnerShipMeta {\n  title: string;\n  description: string;\n  domain: string;\n  owners: Owner[];\n  tags: Tag[];\n  stability: Stability;\n}\n\ntype Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';\ntype Owner = string; // curated list available in code (e.g., '@sigil-team', 'team-strit')\ntype Tag = string; // curated list available in code (e.g., 'auth', 'spots')\n\n// For V2 presentations, meta is a Partial<OwnerShipMeta> plus description, name, version\ninterface PresentationV2Meta extends Partial<OwnerShipMeta> {\n  name: string;\n  version: number;\n  description?: string;\n}\n\\`\\`\\`\n\n### Engine\n\nUse \\`createDefaultTransformEngine()\\` and register custom renderers as needed (e.g., high-fidelity BlockNote → Markdown). The default engine supports markdown/json/xml; a React renderer returns a serializable descriptor the host app renders via a \\`componentMap\\` or a BlockNote renderer. The canonical source type string is \\`blocknotejs\\` (not \\`blocknote\\`).\n\nPII paths (JSON-like) are redacted from rendered outputs.\n\n### MCP Integration\n\n\\`createMcpServer\\` accepts \\`presentationsV2\\`. Each descriptor is exposed under \\`presentation://<name>/v<version>\\` and negotiated variants (\\`.md/.json/.xml\\`) are rendered by the engine.\n\n### Migration\n\n- V1 \\`PresentationSpec\\` remains supported; a back-compat helper converts V1 → V2 when convenient.\n- Prefer V2 for new work.\n\n### Examples (Sigil)\n\n- \\`sigil.auth.webauth_tabs_v2\\`: component source (\\`componentKey: 'sigil.webauth.tabs'\\`), targets \\`react/json/xml\\`.\n- \\`sigil.signup.guide_v2\\`: BlockNote doc source, targets \\`react/markdown/json/xml\\`.\n\n### React Rendering\n\nHost apps use a \\`componentMap\\` (e.g., \\`'sigil.webauth.tabs' → WebAuthTabs\\`) and a BlockNote renderer to turn the React render descriptor into elements.`,\n  },\n];\nregisterDocBlocks(techContractsDocs);\n"],"mappings":";;;AAGA,MAAaA,oBAAgC,CAC3C;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,YAAY;CACZ,OAAO;CACP,MAAM;CACN,MAAM;EAAC;EAAiB;EAAQ;EAAM;CACtC,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EP,CACF;AACD,kBAAkB,kBAAkB"}

package/dist/docs/types.d.ts

@@ -38,4 +38,5 @@ interface DocBlock {
   stability?: Stability;
 }
 //#endregion
-export { DocBlock, DocBlockLink, DocKind, DocVisibility };
+export { DocBlock, DocBlockLink, DocKind, DocVisibility };
+//# sourceMappingURL=types.d.ts.map

package/dist/docs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/docs/types.ts"],"sourcesContent":[],"mappings":";;;KAEY,aAAA;UAEK,YAAA;EAFL,KAAA,EAAA,MAAA;EAEK,IAAA,EAAA,MAAA;AAKjB;AAEiB,KAFL,OAAA,GAEa,MAAA,GAAA,KAAA,GAAA,OAAA,GAAA,WAAA,GAAA,KAAA;AAYhB,UAZQ,QAAA,CAYR;EAEM;EAUL,EAAA,EAAA,MAAA;EAII;EAAS,KAAA,EAAA,MAAA;;;;;;;;SAhBd;;eAEM;;;;;;;;;;UAUL;;;;cAII"}

package/dist/events.d.ts

@@ -44,4 +44,5 @@ type EventKey = `${string}.v${number}`;
 /** Build a stable string key for an event name/version pair. */
 declare const eventKey: (name: string, version: number) => EventKey;
 //#endregion
-export { EventEnvelope, EventKey, EventSpec, defineEvent, eventKey };
+export { EventEnvelope, EventKey, EventSpec, defineEvent, eventKey };
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","names":[],"sources":["../src/events.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAQA;;AAUW,UAVM,SAUN,CAAA,UAV0B,cAU1B,CAAA,CAAA;EAEG;EAEJ,IAAA,EAAA,MAAA;EAAK;EAIC,OAAA,EAAA,MAAW;EAAW;EACvB,WAAA,CAAA,EAAA,MAAA;EAAV;EACQ,GAAA,CAAA,EAAA,MAAA,EAAA;EAAV;EAAS,OAAA,EAVD,CAUC;EAIK;EAeL,SAAA,CAAA,EA3BE,aA2BM;EAEP;UA3BH;;;iBAIM,sBAAsB,mBACjC,UAAU,KACZ,UAAU;UAII;;;;;;;;;;;;WAYN;;KAGC,QAAA;;cAEC,6CAA4C"}

package/dist/events.js

@@ -9,4 +9,5 @@ function defineEvent(e) {
 const eventKey = (name, version) => `${name}.v${version}`;
 
 //#endregion
-export { defineEvent, eventKey };
+export { defineEvent, eventKey };
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","names":[],"sources":["../src/events.ts"],"sourcesContent":["import { type AnySchemaModel } from '@lssm/lib.schema';\nimport type { OwnerShipMeta } from './ownership';\nimport type { DocId } from './docs/registry';\n\n/**\n * Typed event specification. Declare once, validate payloads at publish time,\n * and guard emissions via the contracts runtime.\n */\nexport interface EventSpec<T extends AnySchemaModel> {\n  /** Fully-qualified event name, e.g. \"sigil.magic_link.created\". */\n  name: string;\n  /** Event payload version. Bump on any breaking payload change. */\n  version: number;\n  /** Short human-friendly summary. */\n  description?: string;\n  /** JSON-like paths to redact from logs/exports. */\n  pii?: string[];\n  /** Event payload schema from @lssm/lib.schema. */\n  payload: T;\n  /** Optional ownership metadata for governance and docs. */\n  ownership?: OwnerShipMeta;\n  /** Optional doc block id for this event. */\n  docId?: DocId;\n}\n\n/** Identity function to keep type inference when declaring events. */\nexport function defineEvent<T extends AnySchemaModel>(\n  e: EventSpec<T>\n): EventSpec<T> {\n  return e;\n}\n\nexport interface EventEnvelope<T> {\n  /** Unique identifier for the published event (UUID recommended). */\n  id: string;\n  /** ISO timestamp when the event occurred. */\n  occurredAt: string;\n  /** Optional trace identifier for correlating across services. */\n  traceId?: string;\n  /** Event name as published (should match spec.name). */\n  name: string;\n  /** Event version as published (should match spec.version). */\n  version: number;\n  /** Validated payload. */\n  payload: T;\n}\n\nexport type EventKey = `${string}.v${number}`;\n/** Build a stable string key for an event name/version pair. */\nexport const eventKey = (name: string, version: number): EventKey =>\n  `${name}.v${version}`;\n"],"mappings":";;;;AA0BA,SAAgB,YACd,GACc;AACd,QAAO;;;AAoBT,MAAa,YAAY,MAAc,YACrC,GAAG,KAAK,IAAI"}

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

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/experiments/docs/experiments.docblock.d.ts
 declare const tech_contracts_experiments_DocBlocks: DocBlock[];
 //#endregion
-export { tech_contracts_experiments_DocBlocks };
+export { tech_contracts_experiments_DocBlocks };
+//# sourceMappingURL=experiments.docblock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"experiments.docblock.d.ts","names":[],"sources":["../../../src/experiments/docs/experiments.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,sCAAsC"}

package/dist/experiments/docs/experiments.docblock.js

@@ -19,4 +19,5 @@ const tech_contracts_experiments_DocBlocks = [{
 registerDocBlocks(tech_contracts_experiments_DocBlocks);
 
 //#endregion
-export { tech_contracts_experiments_DocBlocks };
+export { tech_contracts_experiments_DocBlocks };
+//# sourceMappingURL=experiments.docblock.js.map

package/dist/experiments/docs/experiments.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiments.docblock.js","names":["tech_contracts_experiments_DocBlocks: DocBlock[]"],"sources":["../../../src/experiments/docs/experiments.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_contracts_experiments_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.contracts.experiments',\n    title: 'ExperimentSpec & ExperimentEvaluator',\n    summary:\n      'Use experiments to test alternative workflows, data views, or themes with controlled allocations and measurable outcomes.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/contracts/experiments',\n    tags: ['tech', 'contracts', 'experiments'],\n    body: \"# ExperimentSpec & ExperimentEvaluator\\n\\nUse experiments to test alternative workflows, data views, or themes with controlled allocations and measurable outcomes.\\n\\n- Types & registry: `packages/libs/contracts/src/experiments/spec.ts`\\n- Runtime evaluator: `packages/libs/contracts/src/experiments/evaluator.ts`\\n- CLI wizard/template: `contractspec create experiment`\\n\\n## Structure\\n\\n```ts\\nexport interface ExperimentSpec {\\n  meta: ExperimentMeta;\\n  controlVariant: string;\\n  variants: ExperimentVariant[];\\n  allocation: AllocationStrategy;\\n  successMetrics?: SuccessMetric[];\\n}\\n```\\n\\n- `variants`: define UI/behavior overrides (data views, workflows, themes, policies)\\n- `allocation`:\\n  - `random`: 50/50 or weighted via `weight`\\n  - `sticky`: deterministic hash on user/organization/session\\n  - `targeted`: rule-based (policy + expression + optional percentage)\\n- `successMetrics`: telemetry events + aggregation (count/avg/p95) to track outcomes\\n\\n### Example\\n\\n```ts\\nexport const OnboardingSplitFormExperiment: ExperimentSpec = {\\n  meta: {\\n    name: 'sigil.onboarding.split_form',\\n    version: 1,\\n    title: 'Split onboarding form',\\n    description: 'Compare single vs multi-step onboarding',\\n    domain: 'onboarding',\\n    owners: ['@team.onboarding'],\\n    tags: ['experiment'],\\n    stability: StabilityEnum.Experimental,\\n  },\\n  controlVariant: 'control',\\n  variants: [\\n    { id: 'control', name: 'Single-step form' },\\n    {\\n      id: 'multi_step',\\n      name: 'Multi-step form',\\n      overrides: [\\n        { type: 'workflow', target: 'sigil.onboarding.workflow.multi_step' },\\n      ],\\n    },\\n  ],\\n  allocation: {\\n    type: 'targeted',\\n    rules: [\\n      {\\n        variantId: 'multi_step',\\n        expression: \\\"context.attributes?.segment === 'vip'\\\",\\n      },\\n    ],\\n    fallback: 'random',\\n  },\\n  successMetrics: [\\n    {\\n      name: 'Completion rate',\\n      telemetryEvent: { name: 'sigil.telemetry.onboarding_completed', version: 1 },\\n      aggregation: 'count',\\n    },\\n  ],\\n};\\n```\\n\\n## Variant evaluation\\n\\n```ts\\nconst evaluator = new ExperimentEvaluator({\\n  registry: experimentRegistry,\\n  policyChecker: (policyRef, context) =>\\n    policyEngine.decide({\\n      action: 'experiment_targeting',\\n      subject: { roles: context.flags },\\n      resource: { type: 'experiment', attributes: { name: context.experiment } },\\n      policies: [policyRef],\\n    }).effect === 'allow',\\n});\\n\\nconst assignment = await evaluator.chooseVariant({\\n  experiment: 'sigil.onboarding.split_form',\\n  userId: ctx.userId,\\n  organizationId: ctx.organizationId,\\n  attributes: ctx.attributes,\\n});\\n\\nif (assignment) {\\n  // Apply overrides for the chosen variant\\n  applyExperimentOverrides(assignment.variant);\\n}\\n```\\n\\n- `random` uses deterministic hashing (`salt` optional) for stable splits\\n- `sticky` hashes a specified attribute (userId/orgId/sessionId)\\n- `targeted` evaluates rules in order; each rule can reference a PolicySpec and simple JS expressions (`context` input)\\n\\n## Integrations\\n\\n- **Feature modules**: `FeatureModuleSpec.experiments` references experiments owned by a module\\n- **DataViewSpec / WorkflowSpec**: `experiments?: ExperimentRef[]` indicate which experiments modify the spec\\n- **Telemetry**: success metrics reference `TelemetrySpec` events to ensure compliant tracking\\n- **Policy**: targeting rules call into `PolicyEngine` via the evaluator callback to respect privacy/security\\n\\n## CLI workflow\\n\\n```\\ncontractspec create experiment\\n```\\n\\n- Prompts for control/variants, allocation strategy, targeting rules, success metrics\\n- Outputs a typed `ExperimentSpec` file alongside your contracts\\n\\n## Best practices\\n\\n1. Keep experiments short-lived; increment `meta.version` when changing allocation or variants.\\n2. Always declare a control variant and ensure overrides are reversible.\\n3. Tie success metrics to privacy-reviewed telemetry events.\\n4. Use targeting rules sparingly; combine with PolicySpec to avoid exposing experiments to unauthorized users.\\n5. When an experiment wins, promote the variant to the canonical spec and retire the experiment.\\n\\n\",\n  },\n];\nregisterDocBlocks(tech_contracts_experiments_DocBlocks);\n"],"mappings":";;;;AAGA,MAAaA,uCAAmD,CAC9D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAQ;EAAa;EAAc;CAC1C,MAAM;CACP,CACF;AACD,kBAAkB,qCAAqC"}

package/dist/experiments/evaluator.d.ts

@@ -34,4 +34,5 @@ declare class ExperimentEvaluator {
   private matchesRule;
 }
 //#endregion
-export { ExperimentContext, ExperimentEvaluation, ExperimentEvaluator, ExperimentEvaluatorConfig };
+export { ExperimentContext, ExperimentEvaluation, ExperimentEvaluator, ExperimentEvaluatorConfig };
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/experiments/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","names":[],"sources":["../../src/experiments/evaluator.ts"],"sourcesContent":[],"mappings":";;;;UASiB,iBAAA;;EAAA,OAAA,CAAA,EAAA,MAAA;EAUA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;EAKA,cAAA,CAAA,EAAA,MAAA,GAAA,IAAyB;EAC9B,SAAA,CAAA,EAAA,MAAA,GAAA,IAAA;EAEA,UAAA,CAAA,EAZG,MAYH,CAAA,MAAA,EAAA,OAAA,CAAA;EACC,KAAA,CAAA,EAAA,MAAA,EAAA;;AAIA,UAbI,oBAAA,CAaJ;EAAiB,OAAA,EAZnB,iBAYmB;EAIjB,MAAA,EAAA,SAAA,GAAA,QAAmB,GAAA,QAAA,GAAA,UAAA;;AAYnB,UAxBI,yBAAA,CAwBJ;EACA,QAAA,EAxBD,kBAwBC;EAAR,aAAA,CAAA,EAAA,CAAA,MAAA,EAtBO,SAsBP,EAAA,OAAA,EArBQ,iBAqBR,EAAA,GApBE,OAoBF,CAAA,OAAA,CAAA,GAAA,OAAA;EAAO,mBAAA,CAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,OAAA,EAjBC,iBAiBD,EAAA,GAAA,OAAA;;cAbC,mBAAA;;;;sBAKS;yBAOT,oBACR,QAAQ"}

package/dist/experiments/evaluator.js

@@ -98,4 +98,5 @@ var ExperimentEvaluator = class {
 };
 
 //#endregion
-export { ExperimentEvaluator };
+export { ExperimentEvaluator };
+//# sourceMappingURL=evaluator.js.map

package/dist/experiments/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","names":[],"sources":["../../src/experiments/evaluator.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport type { PolicyRef } from '../policy/spec';\nimport type {\n  ExperimentRegistry,\n  ExperimentSpec,\n  ExperimentVariant,\n  TargetingRule,\n} from './spec';\n\nexport interface ExperimentContext {\n  experiment: string;\n  version?: number;\n  userId?: string | null;\n  organizationId?: string | null;\n  sessionId?: string | null;\n  attributes?: Record<string, unknown>;\n  flags?: string[];\n}\n\nexport interface ExperimentEvaluation {\n  variant: ExperimentVariant;\n  reason: 'control' | 'random' | 'sticky' | 'targeted';\n}\n\nexport interface ExperimentEvaluatorConfig {\n  registry: ExperimentRegistry;\n  policyChecker?: (\n    policy: PolicyRef,\n    context: ExperimentContext\n  ) => Promise<boolean> | boolean;\n  expressionEvaluator?: (\n    expression: string,\n    context: ExperimentContext\n  ) => boolean;\n}\n\nexport class ExperimentEvaluator {\n  private readonly registry: ExperimentRegistry;\n  private readonly policyChecker?: ExperimentEvaluatorConfig['policyChecker'];\n  private readonly expressionEvaluator?: ExperimentEvaluatorConfig['expressionEvaluator'];\n\n  constructor(config: ExperimentEvaluatorConfig) {\n    this.registry = config.registry;\n    this.policyChecker = config.policyChecker;\n    this.expressionEvaluator = config.expressionEvaluator;\n  }\n\n  async chooseVariant(\n    context: ExperimentContext\n  ): Promise<ExperimentEvaluation | null> {\n    const experiment = this.registry.get(context.experiment, context.version);\n    if (!experiment) return null;\n\n    const control = experiment.variants.find(\n      (variant) => variant.id === experiment.controlVariant\n    );\n    if (!control)\n      throw new Error(\n        `Experiment ${experiment.meta.name} missing control variant ${experiment.controlVariant}`\n      );\n\n    switch (experiment.allocation.type) {\n      case 'random':\n        return {\n          variant: this.pickByWeight(\n            experiment,\n            this.randomSeed(context, experiment.allocation.salt)\n          ),\n          reason: 'random',\n        };\n      case 'sticky':\n        return {\n          variant: this.pickByWeight(\n            experiment,\n            this.stickySeed(\n              context,\n              experiment.allocation.attribute,\n              experiment.allocation.salt\n            )\n          ),\n          reason: 'sticky',\n        };\n      case 'targeted': {\n        const targeted = await this.evaluateTargeting(\n          experiment,\n          context,\n          experiment.allocation.rules\n        );\n        if (targeted) {\n          return {\n            variant: targeted,\n            reason: 'targeted',\n          };\n        }\n        if (experiment.allocation.fallback === 'random') {\n          return {\n            variant: this.pickByWeight(experiment, this.randomSeed(context)),\n            reason: 'random',\n          };\n        }\n        return {\n          variant: control,\n          reason: 'control',\n        };\n      }\n      default:\n        return {\n          variant: control,\n          reason: 'control',\n        };\n    }\n  }\n\n  private pickByWeight(\n    experiment: ExperimentSpec,\n    seed: number\n  ): ExperimentVariant {\n    const variants = experiment.variants;\n    const totalWeight = variants.reduce(\n      (sum, variant) => sum + (variant.weight ?? 1),\n      0\n    );\n    const target = seed * totalWeight;\n    let cumulative = 0;\n    for (const variant of variants) {\n      cumulative += variant.weight ?? 1;\n      if (target <= cumulative) {\n        return variant;\n      }\n    }\n    return variants[variants.length - 1]!;\n  }\n\n  private randomSeed(context: ExperimentContext, salt = ''): number {\n    const base =\n      context.sessionId ??\n      context.userId ??\n      context.organizationId ??\n      `${Date.now()}-${Math.random()}`;\n    return this.hashToUnitInterval(base + salt);\n  }\n\n  private stickySeed(\n    context: ExperimentContext,\n    attribute: 'userId' | 'organizationId' | 'sessionId',\n    salt = ''\n  ): number {\n    const value = context[attribute];\n    if (!value) return this.randomSeed(context, salt);\n    return this.hashToUnitInterval(`${value}-${salt}`);\n  }\n\n  private hashToUnitInterval(value: string): number {\n    const hash = createHash('sha256').update(value).digest('hex').slice(0, 15);\n    const intValue = parseInt(hash, 16);\n    return (intValue % 1_000_000) / 1_000_000;\n  }\n\n  private async evaluateTargeting(\n    experiment: ExperimentSpec,\n    context: ExperimentContext,\n    rules: TargetingRule[]\n  ): Promise<ExperimentVariant | null> {\n    for (const rule of rules) {\n      if (!(await this.matchesRule(rule, context))) continue;\n      const variant = experiment.variants.find((v) => v.id === rule.variantId);\n      if (!variant) continue;\n      if (typeof rule.percentage === 'number') {\n        const seed = this.randomSeed(context, `rule-${rule.variantId}`);\n        if (seed > rule.percentage) {\n          continue;\n        }\n      }\n      return variant;\n    }\n    return null;\n  }\n\n  private async matchesRule(\n    rule: TargetingRule,\n    context: ExperimentContext\n  ): Promise<boolean> {\n    if (rule.policy && this.policyChecker) {\n      const allowed = await this.policyChecker(rule.policy, context);\n      if (!allowed) return false;\n    }\n    if (rule.expression) {\n      if (this.expressionEvaluator) {\n        return Boolean(this.expressionEvaluator(rule.expression, context));\n      }\n      try {\n        const fn = new Function('context', `return (${rule.expression});`);\n        return Boolean(fn(context));\n      } catch (_error) {\n        return false;\n      }\n    }\n    return true;\n  }\n}\n"],"mappings":"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"}

package/dist/experiments/spec-resolver.d.ts

@@ -13,4 +13,5 @@ interface SpecVariantResolver {
   }, ctx: HandlerCtx): Promise<RuntimeContract | undefined> | RuntimeContract | undefined;
 }
 //#endregion
-export { RuntimeContract, SpecVariantResolver };
+export { RuntimeContract, SpecVariantResolver };
+//# sourceMappingURL=spec-resolver.d.ts.map

package/dist/experiments/spec-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-resolver.d.ts","names":[],"sources":["../../src/experiments/spec-resolver.ts"],"sourcesContent":[],"mappings":";;;;;;KAKY,eAAA,GAAkB,aAC5B,gBACA,iBAAiB;UAGF,mBAAA;EALL,OAAA,CAAA,SAAA,EAAe;IACzB,IAAA,EAAA,MAAA;IACA,OAAA,EAAA,MAAA;IAAiB,IAAA,EAKmC,MALnC;EAFW,CAAA,EAAA,GAAA,EAQrB,UARqB,CAAA,EASzB,OATyB,CASjB,eATiB,GAAA,SAAA,CAAA,GASc,eATd,GAAA,SAAA"}

package/dist/experiments/spec.d.ts

@@ -86,4 +86,5 @@ declare class ExperimentRegistry {
 }
 declare function makeExperimentKey(meta: ExperimentMeta): string;
 //#endregion
-export { AllocationStrategy, ExperimentMeta, ExperimentOverride, ExperimentOverrideType, ExperimentRef, ExperimentRegistry, ExperimentSpec, ExperimentVariant, MetricAggregation, SuccessMetric, TargetingRule, makeExperimentKey };
+export { AllocationStrategy, ExperimentMeta, ExperimentOverride, ExperimentOverrideType, ExperimentRef, ExperimentRegistry, ExperimentSpec, ExperimentVariant, MetricAggregation, SuccessMetric, TargetingRule, makeExperimentKey };
+//# sourceMappingURL=spec.d.ts.map

package/dist/experiments/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../src/experiments/spec.ts"],"sourcesContent":[],"mappings":";;;;;UAIiB,cAAA,SAAuB;;EAAvB,IAAA,EAAA,MAAA;EASA;EAKL,OAAA,EAAA,MAAA;EAOK;EAUA,MAAA,EAAA,MAAA;AAWjB;AAWY,UA5CK,aAAA,CA4Ca;EAkBlB,IAAA,EAAA,MAAA;EAEK,OAAA,CAAA,EAAA,MAAa;AAO9B;AACQ,KAnEI,sBAAA,GAmEJ,UAAA,GAAA,UAAA,GAAA,OAAA,GAAA,QAAA,GAAA,cAAA;AAGI,UA/DK,kBAAA,CA+DL;EACE,IAAA,EA/DN,sBA+DM;EACK;EAAa,MAAA,EAAA,MAAA;EAMnB;EAGI,OAAA,CAAA,EAAA,MAAA;EASP;EAI6B,MAAA,CAAA,EAhF5B,MAgF4B,CAAA,MAAA,EAAA,OAAA,CAAA;;AAiBvB,UA9FC,iBAAA,CA8FgB;;;;;;cAxFnB;;aAED;;UAGI,aAAA;;;;;;WAMN;;;;KAKC,kBAAA;;;;;;;;;;;SAcC;;;KAID,iBAAA;UAEK,aAAA;;;UAES;;;eACX;;;UAIE,cAAA;QACT;;;YAGI;cACE;mBACK;;;cAMN,kBAAA;;iBAGI;UASP;uCAI6B;;iBAiBvB,iBAAA,OAAwB"}

package/dist/experiments/spec.js

@@ -30,4 +30,5 @@ function makeExperimentKey(meta) {
 }
 
 //#endregion
-export { ExperimentRegistry, makeExperimentKey };
+export { ExperimentRegistry, makeExperimentKey };
+//# sourceMappingURL=spec.js.map

package/dist/experiments/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","names":["latest: ExperimentSpec | undefined"],"sources":["../../src/experiments/spec.ts"],"sourcesContent":["import type { OwnerShipMeta } from '../ownership';\nimport type { PolicyRef } from '../policy/spec';\nimport type { TelemetryEventDef } from '../telemetry/spec';\n\nexport interface ExperimentMeta extends OwnerShipMeta {\n  /** Fully-qualified experiment name (e.g., \"sigil.onboarding.variant\"). */\n  name: string;\n  /** Version of the experiment; bump when allocation or variants change materially. */\n  version: number;\n  /** Domain/bounded context (e.g., \"onboarding\"). */\n  domain: string;\n}\n\nexport interface ExperimentRef {\n  name: string;\n  version?: number;\n}\n\nexport type ExperimentOverrideType =\n  | 'dataView'\n  | 'workflow'\n  | 'theme'\n  | 'policy'\n  | 'presentation';\n\nexport interface ExperimentOverride {\n  type: ExperimentOverrideType;\n  /** Target spec meta name (e.g., DataViewSpec.meta.name). */\n  target: string;\n  /** Target version. Optional; evaluator may choose latest when omitted. */\n  version?: number;\n  /** Optional configuration applied when this variant is active. */\n  config?: Record<string, unknown>;\n}\n\nexport interface ExperimentVariant {\n  id: string;\n  name: string;\n  description?: string;\n  /** Relative weight for random allocation (defaults to 1). */\n  weight?: number;\n  overrides?: ExperimentOverride[];\n  /** Optional metadata for downstream analytics/UI. */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface TargetingRule {\n  /** Variant to assign when rule matches. */\n  variantId: string;\n  /** Optional percentage of matching traffic (0-1). If omitted, 100%. */\n  percentage?: number;\n  /** Policies that must allow the assignment. */\n  policy?: PolicyRef;\n  /** Expression evaluated against context (see evaluator for details). */\n  expression?: string;\n}\n\nexport type AllocationStrategy =\n  | {\n      type: 'random';\n      /** Optional salt for deterministic hashing. */\n      salt?: string;\n    }\n  | {\n      type: 'sticky';\n      /** Which attribute to hash for sticky assignment. */\n      attribute: 'userId' | 'organizationId' | 'sessionId';\n      salt?: string;\n    }\n  | {\n      type: 'targeted';\n      rules: TargetingRule[];\n      fallback?: 'control' | 'random';\n    };\n\nexport type MetricAggregation = 'count' | 'avg' | 'p75' | 'p90' | 'p95' | 'p99';\n\nexport interface SuccessMetric {\n  name: string;\n  telemetryEvent: { name: TelemetryEventDef['name']; version: number };\n  aggregation: MetricAggregation;\n  target?: number;\n}\n\nexport interface ExperimentSpec {\n  meta: ExperimentMeta;\n  /** Identifier of the control variant (must exist in variants array). */\n  controlVariant: string;\n  variants: ExperimentVariant[];\n  allocation: AllocationStrategy;\n  successMetrics?: SuccessMetric[];\n  tags?: string[];\n}\n\nconst experimentKey = (meta: ExperimentMeta) => `${meta.name}.v${meta.version}`;\n\nexport class ExperimentRegistry {\n  private readonly items = new Map<string, ExperimentSpec>();\n\n  register(spec: ExperimentSpec): this {\n    const key = experimentKey(spec.meta);\n    if (this.items.has(key)) {\n      throw new Error(`Duplicate experiment ${key}`);\n    }\n    this.items.set(key, spec);\n    return this;\n  }\n\n  list(): ExperimentSpec[] {\n    return [...this.items.values()];\n  }\n\n  get(name: string, version?: number): ExperimentSpec | undefined {\n    if (version != null) {\n      return this.items.get(`${name}.v${version}`);\n    }\n    let latest: ExperimentSpec | undefined;\n    let maxVersion = -Infinity;\n    for (const spec of this.items.values()) {\n      if (spec.meta.name !== name) continue;\n      if (spec.meta.version > maxVersion) {\n        maxVersion = spec.meta.version;\n        latest = spec;\n      }\n    }\n    return latest;\n  }\n}\n\nexport function makeExperimentKey(meta: ExperimentMeta) {\n  return experimentKey(meta);\n}\n"],"mappings":";AA8FA,MAAM,iBAAiB,SAAyB,GAAG,KAAK,KAAK,IAAI,KAAK;AAEtE,IAAa,qBAAb,MAAgC;CAC9B,AAAiB,wBAAQ,IAAI,KAA6B;CAE1D,SAAS,MAA4B;EACnC,MAAM,MAAM,cAAc,KAAK,KAAK;AACpC,MAAI,KAAK,MAAM,IAAI,IAAI,CACrB,OAAM,IAAI,MAAM,wBAAwB,MAAM;AAEhD,OAAK,MAAM,IAAI,KAAK,KAAK;AACzB,SAAO;;CAGT,OAAyB;AACvB,SAAO,CAAC,GAAG,KAAK,MAAM,QAAQ,CAAC;;CAGjC,IAAI,MAAc,SAA8C;AAC9D,MAAI,WAAW,KACb,QAAO,KAAK,MAAM,IAAI,GAAG,KAAK,IAAI,UAAU;EAE9C,IAAIA;EACJ,IAAI,aAAa;AACjB,OAAK,MAAM,QAAQ,KAAK,MAAM,QAAQ,EAAE;AACtC,OAAI,KAAK,KAAK,SAAS,KAAM;AAC7B,OAAI,KAAK,KAAK,UAAU,YAAY;AAClC,iBAAa,KAAK,KAAK;AACvB,aAAS;;;AAGb,SAAO;;;AAIX,SAAgB,kBAAkB,MAAsB;AACtD,QAAO,cAAc,KAAK"}

package/dist/features.d.ts

@@ -93,4 +93,5 @@ declare function installFeature(feature: FeatureModuleSpec, deps: {
 /** Ensure declared target requirements exist on the provided descriptors. */
 declare function validateFeatureTargetsV2(feature: FeatureModuleSpec, descriptors: PresentationDescriptorV2[]): boolean;
 //#endregion
-export { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FeatureRegistry, OpRef, PresentationRef, installFeature, validateFeatureTargetsV2 };
+export { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FeatureRegistry, OpRef, PresentationRef, installFeature, validateFeatureTargetsV2 };
+//# sourceMappingURL=features.d.ts.map

package/dist/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","names":[],"sources":["../src/features.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;UAeiB,iBAAA,SAA0B;;;EAA1B;EAOA,KAAA,CAAA,EAHP,KAGY;AAOtB;AAOiB,UAdA,KAAA,CAce;EAQf;EACT,IAAA,EAAA,MAAA;EAEO;EAEJ,OAAA,EAAA,MAAA;;AAIK,UAxBC,QAAA,CAwBD;EAGD;EACA,IAAA,EAAA,MAAA;EAGY;EAAa,OAAA,EAAA,MAAA;;AAepB,UAvCH,eAAA,CAuCG;EAAiB;EAGpB,IAAA,EAAA,MAAA;EASJ;EAIC,OAAA,EAAA,MAAA;;;AAauB,UA5DpB,iBAAA,CA4DoB;EAMrB,IAAA,EAjER,iBAiEsB;EACnB;EAEG,UAAA,CAAA,EAlEC,KAkED,EAAA;EAAe;EACc,MAAA,CAAA,EAjEhC,QAiEgC,EAAA;EAEvB;EACD,aAAA,CAAA,EAlED,eAkEC,EAAA;EAChB;EAAA,WAAA,CAAA,EAjEa,aAiEb,EAAA;EAwFa;;eAtJD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;;;;oBAOO;;UAGH,UAAA;;;;cASJ,eAAA;;;cAIC;;UAQJ;;oBAKU;;;iBAMJ,cAAA,UACL;YAEG;QAAe;kBACc;kBAEvB;iBACD;IAChB;;iBAwFa,wBAAA,UACL,gCACI"}

package/dist/features.js

@@ -65,4 +65,5 @@ function validateFeatureTargetsV2(feature, descriptors) {
 }
 
 //#endregion
-export { FeatureRegistry, installFeature, validateFeatureTargetsV2 };
+export { FeatureRegistry, installFeature, validateFeatureTargetsV2 };
+//# sourceMappingURL=features.js.map

package/dist/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","names":[],"sources":["../src/features.ts"],"sourcesContent":["import type {\n  PresentationTarget,\n  PresentationDescriptorV2,\n} from './presentations.v2';\nimport type { OwnerShipMeta } from './ownership';\nimport type { DocId } from './docs/registry';\nimport type {\n  CapabilityRef,\n  CapabilityRequirement,\n  CapabilityRegistry,\n} from './capabilities';\nimport type { ExperimentRef } from './experiments/spec';\nimport type { ImplementationRef } from './spec';\n\n/** Minimal metadata to identify and categorize a feature module. */\nexport interface FeatureModuleMeta extends OwnerShipMeta {\n  /** Stable slug key used to identify this feature (e.g., \"weekly_pulse\"). */\n  key: string;\n  /** Optional doc block id for this feature. */\n  docId?: DocId;\n}\n\nexport interface OpRef {\n  /** Operation name (ContractSpec.meta.name). */\n  name: string;\n  /** Operation version (ContractSpec.meta.version). */\n  version: number;\n}\n\nexport interface EventRef {\n  /** Event name. */\n  name: string;\n  /** Event version. */\n  version: number;\n}\n\nexport interface PresentationRef {\n  /** Presentation name. */\n  name: string;\n  /** Presentation version. */\n  version: number;\n}\n\n/** Group operations/events/presentations into an installable feature. */\nexport interface FeatureModuleSpec {\n  meta: FeatureModuleMeta;\n  /** Contract operations included in this feature. */\n  operations?: OpRef[];\n  /** Events declared/emitted by this feature. */\n  events?: EventRef[];\n  /** Presentations associated to this feature. */\n  presentations?: PresentationRef[];\n  /** Experiments related to this feature. */\n  experiments?: ExperimentRef[];\n  /** Capability bindings exposed/required by this feature. */\n  capabilities?: {\n    provides?: CapabilityRef[];\n    requires?: CapabilityRequirement[];\n  };\n  /** Optional: link ops to presentations for traceability (e.g., ui for op) */\n  opToPresentation?: { op: OpRef; pres: PresentationRef }[];\n  /** Optional: declare per-presentation target requirements (V2 descriptors) */\n  presentationsTargets?: {\n    /** Presentation name. */\n    name: string;\n    /** Presentation version. */\n    version: number;\n    /** Required targets that must be supported by the descriptor. */\n    targets: PresentationTarget[];\n  }[];\n\n  /**\n   * Explicit implementation file mappings for the entire feature module.\n   * Used for tracking and verifying that this feature is correctly implemented.\n   */\n  implementations?: ImplementationRef[];\n}\n\nexport interface FeatureRef {\n  key: string;\n}\n\nfunction keyOf(f: FeatureModuleSpec) {\n  return f.meta.key;\n}\n\n/** In-memory registry for FeatureModuleSpec. */\nexport class FeatureRegistry {\n  private items = new Map<string, FeatureModuleSpec>();\n\n  /** Register a feature module. Throws when the key already exists. */\n  register(f: FeatureModuleSpec): this {\n    const key = keyOf(f);\n    if (this.items.has(key)) throw new Error(`Duplicate feature ${key}`);\n    this.items.set(key, f);\n    return this;\n  }\n\n  /** List all registered feature modules. */\n  list(): FeatureModuleSpec[] {\n    return [...this.items.values()];\n  }\n\n  /** Get a feature by its key (slug). */\n  get(key: string): FeatureModuleSpec | undefined {\n    return this.items.get(key);\n  }\n}\n\n/** Validate and register a feature against optional registries/descriptors. */\nexport function installFeature(\n  feature: FeatureModuleSpec,\n  deps: {\n    features: FeatureRegistry;\n    ops?: import('./registry').SpecRegistry;\n    presentations?: import('./presentations').PresentationRegistry;\n    descriptorsV2?: PresentationDescriptorV2[];\n    capabilities?: CapabilityRegistry;\n  }\n) {\n  // Validate referenced ops exist if registry provided\n  if (deps.ops && feature.operations) {\n    for (const o of feature.operations) {\n      const s = deps.ops.getSpec(o.name, o.version);\n      if (!s)\n        throw new Error(\n          `installFeature: operation not found ${o.name}.v${o.version}`\n        );\n    }\n  }\n  // Validate referenced presentations exist if registry provided\n  if (deps.presentations && feature.presentations) {\n    for (const p of feature.presentations) {\n      const pres = deps.presentations.get(p.name, p.version);\n      if (!pres)\n        throw new Error(\n          `installFeature: presentation not found ${p.name}.v${p.version}`\n        );\n    }\n  }\n  // Validate V2 target requirements if provided\n  if (feature.presentationsTargets && deps.descriptorsV2) {\n    for (const req of feature.presentationsTargets) {\n      const d = deps.descriptorsV2.find(\n        (x) => x.meta.name === req.name && x.meta.version === req.version\n      );\n      if (!d)\n        throw new Error(\n          `installFeature: V2 descriptor not found ${req.name}.v${req.version}`\n        );\n      for (const t of req.targets) {\n        if (!d.targets.includes(t))\n          throw new Error(\n            `installFeature: descriptor ${req.name}.v${req.version} missing target ${t}`\n          );\n      }\n    }\n  }\n  // Validate op→presentation links\n  if (feature.opToPresentation && feature.opToPresentation.length > 0) {\n    for (const link of feature.opToPresentation) {\n      if (deps.ops) {\n        const s = deps.ops.getSpec(link.op.name, link.op.version);\n        if (!s)\n          throw new Error(\n            `installFeature: linked op not found ${link.op.name}.v${link.op.version}`\n          );\n      }\n      if (deps.presentations) {\n        const pres = deps.presentations.get(link.pres.name, link.pres.version);\n        if (!pres)\n          throw new Error(\n            `installFeature: linked presentation not found ${link.pres.name}.v${link.pres.version}`\n          );\n      }\n    }\n  }\n  // Validate capability bindings when registry provided\n  if (deps.capabilities && feature.capabilities?.provides) {\n    for (const cap of feature.capabilities.provides) {\n      const spec = deps.capabilities.get(cap.key, cap.version);\n      if (!spec)\n        throw new Error(\n          `installFeature: capability not registered ${cap.key}.v${cap.version}`\n        );\n    }\n  }\n  if (feature.capabilities?.requires?.length) {\n    if (!deps.capabilities)\n      throw new Error(\n        `installFeature: capability registry required to validate capability requirements for ${feature.meta.key}`\n      );\n    const provided = feature.capabilities.provides ?? [];\n    for (const req of feature.capabilities.requires) {\n      const satisfied = deps.capabilities.satisfies(req, provided);\n      if (!satisfied)\n        throw new Error(\n          `installFeature: capability requirement not satisfied ${req.key}${req.version ? `.v${req.version}` : ''}`\n        );\n    }\n  }\n  deps.features.register(feature);\n  return deps.features;\n}\n\n/** Ensure declared target requirements exist on the provided descriptors. */\nexport function validateFeatureTargetsV2(\n  feature: FeatureModuleSpec,\n  descriptors: PresentationDescriptorV2[]\n) {\n  if (\n    !feature.presentationsTargets ||\n    feature.presentationsTargets.length === 0\n  )\n    return true;\n  for (const req of feature.presentationsTargets) {\n    const d = descriptors.find(\n      (x) => x.meta.name === req.name && x.meta.version === req.version\n    );\n    if (!d)\n      throw new Error(`V2 descriptor not found ${req.name}.v${req.version}`);\n    for (const t of req.targets)\n      if (!d.targets.includes(t))\n        throw new Error(\n          `Descriptor ${req.name}.v${req.version} missing target ${t}`\n        );\n  }\n  return true;\n}\n"],"mappings":"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"}

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

@@ -3,4 +3,5 @@ import { DocBlock } from "@lssm/lib.contracts/docs";
 //#region src/forms/docs/forms.docblock.d.ts
 declare const tech_contracts_forms_DocBlocks: DocBlock[];
 //#endregion
-export { tech_contracts_forms_DocBlocks };
+export { tech_contracts_forms_DocBlocks };
+//# sourceMappingURL=forms.docblock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forms.docblock.d.ts","names":[],"sources":["../../../src/forms/docs/forms.docblock.ts"],"sourcesContent":[],"mappings":";;;cAGa,gCAAgC"}

package/dist/forms/docs/forms.docblock.js

@@ -19,4 +19,5 @@ const tech_contracts_forms_DocBlocks = [{
 registerDocBlocks(tech_contracts_forms_DocBlocks);
 
 //#endregion
-export { tech_contracts_forms_DocBlocks };
+export { tech_contracts_forms_DocBlocks };
+//# sourceMappingURL=forms.docblock.js.map

package/dist/forms/docs/forms.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.docblock.js","names":["tech_contracts_forms_DocBlocks: DocBlock[]"],"sources":["../../../src/forms/docs/forms.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_contracts_forms_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.contracts.forms',\n    title: 'Contracts: FormSpec',\n    summary:\n      'This document defines the canonical contracts for declarative forms.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/contracts/forms',\n    tags: ['tech', 'contracts', 'forms'],\n    body: '# Contracts: FormSpec\\n\\nThis document defines the canonical contracts for declarative forms.\\n\\n## Overview\\n\\n- `FormSpec` (in `@lssm/lib.contracts/forms`) declares:\\n  - `meta` (extends `OwnerShipMeta`) + `key`/`version` for stability.\\n  - `model` (`@lssm/lib.schema` `SchemaModel`) as the single source of truth.\\n  - `fields` built from `FieldSpec` kinds: `text`, `textarea`, `select`, `checkbox`, `radio`, `switch`, `group`, `array`.\\n  - Optional `actions`, `policy.flags`, `constraints` and `renderHints`.\\n- Relations DSL provides `visibleWhen`, `enabledWhen`, `requiredWhen` based on predicates.\\n- `buildZodWithRelations(spec)` augments the base zod with conditional rules and constraints.\\n- React adapter renders with React Hook Form + driver API for UI components (shadcn driver provided).\\n\\n## Driver API (UI-agnostic)\\n\\nHost apps supply a driver mapping slots \\u2192 components:\\n\\n- Required: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Button`.\\n- Optional: `FieldGroup`, `FieldSet`, `FieldLegend` and input group helpers.\\n\\nUse `createFormRenderer({ driver })` to obtain a `render(spec)` function.\\n\\n## Arrays and Groups\\n\\n- `array` items are rendered with `useFieldArray`, honoring `min`/`max` and add/remove controls.\\n- `group` composes nested fields and provides optional legend/description.\\n\\n## Feature Flags\\n\\n- Declare `policy.flags` on forms to signal gating. Gate usage at host boundary; avoid scattering flags across individual fields.\\n\\n## Example\\n\\nSee `packages/hcircle/apps/web-coliving/src/forms/bug-report.spec.ts` for a concrete form spec and `components/forms/BugReportFormDemo.tsx` for rendering with a minimal shadcn driver mapping.\\n',\n  },\n];\nregisterDocBlocks(tech_contracts_forms_DocBlocks);\n"],"mappings":";;;;AAGA,MAAaA,iCAA6C,CACxD;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAQ;EAAa;EAAQ;CACpC,MAAM;CACP,CACF;AACD,kBAAkB,+BAA+B"}

package/dist/forms.d.ts

@@ -255,4 +255,5 @@ declare function defineFormSpec<M extends AnySchemaModel, F extends readonly Any
   }[];
 }): FormSpec<M>;
 //#endregion
-export { ArrayFieldSpec, BaseFieldSpec, CheckboxFieldSpec, ConstraintDecl, ConstraintHandler, EnhanceFields, FieldSpec, FormAction, FormOption, FormRegistry, FormSpec, FormValuesFor, GroupFieldSpec, OptionsSource, Predicate, PredicateOp, RadioFieldSpec, SelectFieldSpec, SwitchFieldSpec, TextFieldSpec, TextareaFieldSpec, TypedOptionsSource, TypedPredicate, TypedWhenClause, WhenClause, buildZodWithRelations, defineFormSpec, evalPredicate };
+export { ArrayFieldSpec, BaseFieldSpec, CheckboxFieldSpec, ConstraintDecl, ConstraintHandler, EnhanceFields, FieldSpec, FormAction, FormOption, FormRegistry, FormSpec, FormValuesFor, GroupFieldSpec, OptionsSource, Predicate, PredicateOp, RadioFieldSpec, SelectFieldSpec, SwitchFieldSpec, TextFieldSpec, TextareaFieldSpec, TypedOptionsSource, TypedPredicate, TypedWhenClause, WhenClause, buildZodWithRelations, defineFormSpec, evalPredicate };
+//# sourceMappingURL=forms.d.ts.map

package/dist/forms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.d.ts","names":[],"sources":["../src/forms.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/forms.js

@@ -116,4 +116,5 @@ function defineFormSpec(spec) {
 }
 
 //#endregion
-export { FormRegistry, buildZodWithRelations, defineFormSpec, evalPredicate };
+export { FormRegistry, buildZodWithRelations, defineFormSpec, evalPredicate };
+//# sourceMappingURL=forms.js.map

package/dist/forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.js","names":["candidate: FormSpec | undefined","cur: any"],"sources":["../src/forms.ts"],"sourcesContent":["import type { AnySchemaModel, ZodSchemaModel } from '@lssm/lib.schema';\nimport type { OwnerShipMeta } from './ownership';\n\n// ---- Core types\n\nexport type PredicateOp =\n  | 'equals'\n  | 'notEquals'\n  | 'in'\n  | 'notIn'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'truthy'\n  | 'empty'\n  | 'lengthGt'\n  | 'lengthGte'\n  | 'lengthLt'\n  | 'lengthLte';\n\n// Author-time generic path helpers (computed from provided fields shape)\nexport interface WhenClause {\n  /** Dot path in form values; arrays may use `$index` within array context. */\n  path: string;\n  op?: PredicateOp;\n  value?: unknown;\n}\n\nexport interface Predicate {\n  when?: WhenClause;\n  all?: Predicate[];\n  any?: Predicate[];\n  not?: Predicate;\n}\n\nexport interface FormOption {\n  labelI18n: string;\n  value: string | number | boolean;\n  descriptionI18n?: string;\n  disabled?: boolean;\n}\n\nexport type OptionsSource =\n  | { kind: 'static'; options: readonly FormOption[] }\n  | {\n      kind: 'resolver';\n      resolverKey: string;\n      /** Dot paths in form values to watch */\n      deps: string[];\n      args?: Record<string, unknown>;\n    };\n\nexport interface BaseFieldSpec {\n  /** Field kind discriminator. */\n  kind:\n    | 'text'\n    | 'textarea'\n    | 'select'\n    | 'checkbox'\n    | 'radio'\n    | 'switch'\n    | 'group'\n    | 'array';\n  /** Field name (dot path relative to the form root or parent context). */\n  name?: string;\n  labelI18n?: string;\n  descriptionI18n?: string;\n  placeholderI18n?: string;\n  required?: boolean;\n  /** Conditional UI behavior */\n  visibleWhen?: Predicate;\n  enabledWhen?: Predicate;\n  requiredWhen?: Predicate;\n  /** UI hints */\n  uiKey?: string;\n  uiProps?: Record<string, unknown>;\n  wrapper?: { orientation?: 'horizontal' | 'vertical' };\n  /** HTML/Native autofill token (supports custom tokens) */\n  autoComplete?: string;\n  /** Keyboard/adaptation hints (web/native). Shape mirrors design-system KeyboardOptions but stays decoupled. */\n  keyboard?: {\n    kind?: string;\n    autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters';\n    autoComplete?: string;\n    autoCorrect?: boolean;\n    enterKeyHint?: 'enter' | 'done' | 'go' | 'next' | 'search' | 'send';\n  };\n  /** Optional computed value hook, provided by host computations map */\n  computeFrom?: {\n    computeKey: string;\n    deps: string[];\n    mode?: 'change' | 'blur-xs' | 'submit';\n    readOnly?: boolean;\n  };\n}\n\nexport interface TextFieldSpec extends BaseFieldSpec {\n  kind: 'text';\n  name: string;\n  inputMode?:\n    | 'text'\n    | 'email'\n    | 'tel'\n    | 'url'\n    | 'numeric'\n    | 'decimal'\n    | 'search';\n  autoComplete?: string;\n  maxLength?: number;\n  minLength?: number;\n}\n\nexport interface TextareaFieldSpec extends BaseFieldSpec {\n  kind: 'textarea';\n  name: string;\n  rows?: number;\n  maxLength?: number;\n  minLength?: number;\n}\n\nexport interface SelectFieldSpec extends BaseFieldSpec {\n  kind: 'select';\n  name: string;\n  options: OptionsSource | readonly FormOption[]; // allow shorthand array\n}\n\nexport interface CheckboxFieldSpec extends BaseFieldSpec {\n  kind: 'checkbox';\n  name: string;\n}\n\nexport interface RadioFieldSpec extends BaseFieldSpec {\n  kind: 'radio';\n  name: string;\n  options: OptionsSource | readonly FormOption[];\n}\n\nexport interface SwitchFieldSpec extends BaseFieldSpec {\n  kind: 'switch';\n  name: string;\n}\n\nexport interface GroupFieldSpec extends BaseFieldSpec {\n  kind: 'group';\n  /** Optional legend/label at group level */\n  labelI18n?: string;\n  fields: FieldSpec[];\n}\n\nexport interface ArrayFieldSpec extends BaseFieldSpec {\n  kind: 'array';\n  /** Root-level field that is an array in the model (e.g., \"emails\") */\n  name: string;\n  /** Child field spec for each item (e.g., address inside emails[i].address). */\n  of: Exclude<FieldSpec, ArrayFieldSpec | GroupFieldSpec>;\n  min?: number;\n  max?: number;\n}\n\nexport type FieldSpec =\n  | TextFieldSpec\n  | TextareaFieldSpec\n  | SelectFieldSpec\n  | CheckboxFieldSpec\n  | RadioFieldSpec\n  | SwitchFieldSpec\n  | GroupFieldSpec\n  | ArrayFieldSpec;\n\nexport interface FormAction {\n  key: string;\n  labelI18n: string;\n  op?: { name: string; version: number };\n  success?: { navigateTo?: string; toastI18n?: string };\n}\n\nexport interface ConstraintDecl {\n  key: string; // host maps this to a function\n  messageI18n: string;\n  paths: string[]; // inputs for the constraint function\n  args?: Record<string, unknown>;\n}\n\nexport type FormValuesFor<M extends AnySchemaModel> = ZodSchemaModel<M>;\n\nexport interface FormSpec<M extends AnySchemaModel = AnySchemaModel> {\n  meta: OwnerShipMeta & { key: string; version: number };\n  /** Canonical form data shape */\n  model: M;\n  /** Flat list or tree using groups/arrays */\n  fields: FieldSpec[];\n  policy?: { flags?: string[]; pii?: string[] };\n  actions?: FormAction[];\n  renderHints?: { ui: 'shadcn' | 'custom'; form: 'react-hook-form' };\n  constraints?: ConstraintDecl[];\n}\n\n// ---- Registry\n\nfunction formKey(meta: FormSpec['meta']) {\n  return `${meta.key}.v${meta.version}`;\n}\n\nexport class FormRegistry {\n  private items = new Map<string, FormSpec>();\n\n  register(spec: FormSpec): this {\n    const key = formKey(spec.meta);\n    if (this.items.has(key)) throw new Error(`Duplicate form ${key}`);\n    this.items.set(key, spec);\n    return this;\n  }\n\n  list(): FormSpec[] {\n    return [...this.items.values()];\n  }\n\n  get(key: string, version?: number) {\n    if (version != null) return this.items.get(`${key}.v${version}`);\n    let candidate: FormSpec | undefined;\n    let max = -Infinity;\n    for (const [k, v] of this.items.entries()) {\n      if (!k.startsWith(`${key}.v`)) continue;\n      if (v.meta.version > max) {\n        max = v.meta.version;\n        candidate = v;\n      }\n    }\n    return candidate;\n  }\n}\n\n// ---- Relations helpers (runtime)\n\nfunction getAtPath(values: unknown, path: string): unknown {\n  if (!path) return undefined;\n  const segs = path\n    .replace(/\\[(\\d+)\\]/g, '.$1')\n    .split('.')\n    .filter(Boolean);\n  let cur: any = values as any;\n  for (const s of segs) {\n    if (cur == null) return undefined;\n    cur = cur[s as keyof typeof cur];\n  }\n  return cur;\n}\n\nexport function evalPredicate(values: unknown, pred?: Predicate): boolean {\n  if (!pred) return true;\n  if (pred.not) return !evalPredicate(values, pred.not);\n  if (pred.all && pred.all.length)\n    return pred.all.every((p) => evalPredicate(values, p));\n  if (pred.any && pred.any.length)\n    return pred.any.some((p) => evalPredicate(values, p));\n  if (pred.when) {\n    const { path, op = 'truthy', value } = pred.when;\n    const v = getAtPath(values, path);\n    switch (op) {\n      case 'equals':\n        return v === value;\n      case 'notEquals':\n        return v !== value;\n      case 'in':\n        return Array.isArray(value) && value.includes(v as never);\n      case 'notIn':\n        return Array.isArray(value) && !value.includes(v as never);\n      case 'gt':\n        return Number(v) > Number(value);\n      case 'gte':\n        return Number(v) >= Number(value);\n      case 'lt':\n        return Number(v) < Number(value);\n      case 'lte':\n        return Number(v) <= Number(value);\n      case 'empty':\n        return (\n          v == null ||\n          (Array.isArray(v) ? v.length === 0 : String(v).length === 0)\n        );\n      case 'lengthGt':\n        return (\n          (Array.isArray(v) || typeof v === 'string') &&\n          (v as any).length > Number(value ?? 0)\n        );\n      case 'lengthGte':\n        return (\n          (Array.isArray(v) || typeof v === 'string') &&\n          (v as any).length >= Number(value ?? 0)\n        );\n      case 'lengthLt':\n        return (\n          (Array.isArray(v) || typeof v === 'string') &&\n          (v as any).length < Number(value ?? 0)\n        );\n      case 'lengthLte':\n        return (\n          (Array.isArray(v) || typeof v === 'string') &&\n          (v as any).length <= Number(value ?? 0)\n        );\n      case 'truthy':\n      default:\n        return Boolean(v);\n    }\n  }\n  return true;\n}\n\nexport type ConstraintHandler = (\n  values: Record<string, unknown>,\n  paths: string[],\n  args?: Record<string, unknown>\n) => { ok: true } | { ok: false; message?: string; path?: string };\n\n/**\n * Wrap the base zod schema with relation-driven refinements (requiredWhen, array min/max)\n * and optional custom constraints. Call this when wiring RHF resolver.\n */\nexport function buildZodWithRelations(\n  spec: FormSpec,\n  handlers?: Record<string, ConstraintHandler>\n) {\n  const base = spec.model.getZod();\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return (base as any).superRefine(\n    (values: Record<string, unknown>, ctx: any) => {\n      const visit = (field: FieldSpec, parentPath?: string) => {\n        const path = field.name\n          ? parentPath\n            ? `${parentPath}.${field.name}`\n            : field.name\n          : (parentPath ?? '');\n\n        // requiredWhen enforcement (UI also shows required)\n        if (field.requiredWhen) {\n          const should = evalPredicate(values, field.requiredWhen);\n          if (should) {\n            const v = getAtPath(values, path);\n            const empty =\n              v == null ||\n              (typeof v === 'string' && v.trim().length === 0) ||\n              (Array.isArray(v) && v.length === 0);\n            if (empty)\n              ctx.addIssue({\n                code: 'custom',\n                path: path.split('.'),\n                message: 'required',\n              });\n          }\n        }\n\n        // arrays min/max\n        if (field.kind === 'array') {\n          const arr = getAtPath(values, path) as unknown[] | undefined;\n          if (\n            field.min != null &&\n            Array.isArray(arr) &&\n            arr.length < field.min\n          ) {\n            ctx.addIssue({\n              code: 'custom',\n              path: path.split('.'),\n              message: `min:${field.min}`,\n            });\n          }\n          if (\n            field.max != null &&\n            Array.isArray(arr) &&\n            arr.length > field.max\n          ) {\n            ctx.addIssue({\n              code: 'custom',\n              path: path.split('.'),\n              message: `max:${field.max}`,\n            });\n          }\n          // child\n          visit(field.of, path);\n        } else if (field.kind === 'group') {\n          for (const child of field.fields) visit(child, path);\n        }\n      };\n\n      for (const f of spec.fields) visit(f);\n\n      // custom constraints\n      if (spec.constraints && handlers) {\n        for (const c of spec.constraints) {\n          const fn = handlers[c.key];\n          if (!fn) continue;\n          const res = fn(values, c.paths, c.args);\n          if (!res.ok) {\n            ctx.addIssue({\n              code: 'custom',\n              path: (res.path ?? c.paths[0] ?? '').split('.').filter(Boolean),\n              message: res.message ?? c.messageI18n,\n            });\n          }\n        }\n      }\n    }\n  );\n}\n\n// ---- Authoring-time helper: enforce typed paths from fields (best-effort bounded)\n\ninterface AnyFieldLike {\n  kind: string;\n  name?: string;\n  fields?: readonly AnyFieldLike[];\n  of?: AnyFieldLike;\n}\n\ntype TopLevelNames<F extends readonly AnyFieldLike[]> = F[number] extends {\n  name: infer N extends string;\n}\n  ? N\n  : never;\n\ntype ArrayChildren<F extends readonly AnyFieldLike[]> = F[number] extends {\n  kind: 'array';\n  name: infer N extends string;\n  of: infer C;\n}\n  ? C extends { name: infer CN extends string }\n    ? `${N}.$index.${CN}`\n    : never\n  : never;\n\ntype GroupTopLevelNames<F extends readonly AnyFieldLike[]> = F[number] extends {\n  kind: 'group';\n  fields: infer G extends readonly AnyFieldLike[];\n}\n  ? TopLevelNames<G>\n  : never;\n\ntype GroupArrayChildren<F extends readonly AnyFieldLike[]> = F[number] extends {\n  kind: 'group';\n  fields: infer G extends readonly AnyFieldLike[];\n}\n  ? ArrayChildren<G>\n  : never;\n\ntype PathOfFields<F extends readonly AnyFieldLike[]> =\n  | TopLevelNames<F>\n  | ArrayChildren<F>\n  | GroupTopLevelNames<F>\n  | GroupArrayChildren<F>;\n\nexport interface TypedWhenClause<P extends string> {\n  path: P;\n  op?: PredicateOp;\n  value?: unknown;\n}\nexport interface TypedPredicate<P extends string> {\n  when?: TypedWhenClause<P>;\n  all?: TypedPredicate<P>[];\n  any?: TypedPredicate<P>[];\n  not?: TypedPredicate<P>;\n}\nexport type TypedOptionsSource<P extends string> =\n  | { kind: 'static'; options: readonly FormOption[] }\n  | {\n      kind: 'resolver';\n      resolverKey: string;\n      deps: P[];\n      args?: Record<string, unknown>;\n    };\n\nexport type EnhanceFields<\n  F extends readonly AnyFieldLike[],\n  P extends string,\n> = {\n  [K in keyof F]: F[K] & {\n    visibleWhen?: TypedPredicate<P>;\n    enabledWhen?: TypedPredicate<P>;\n    requiredWhen?: TypedPredicate<P>;\n  } & (F[K] extends { kind: 'select' }\n      ? { options: TypedOptionsSource<P> | readonly FormOption[] }\n      : {}) &\n    (F[K] extends { kind: 'radio' }\n      ? { options: TypedOptionsSource<P> | readonly FormOption[] }\n      : {}) & {\n      computeFrom?: {\n        computeKey: string;\n        deps: P[];\n        mode?: 'change' | 'blur-xs' | 'submit';\n        readOnly?: boolean;\n      };\n    };\n};\n\nexport function defineFormSpec<\n  M extends AnySchemaModel,\n  F extends readonly AnyFieldLike[],\n>(spec: {\n  meta: FormSpec<M>['meta'];\n  model: M;\n  fields: EnhanceFields<F, PathOfFields<F>>;\n  policy?: FormSpec<M>['policy'];\n  actions?: FormSpec<M>['actions'];\n  renderHints?: FormSpec<M>['renderHints'];\n  constraints?: {\n    key: string;\n    messageI18n: string;\n    paths: PathOfFields<F>[];\n    args?: Record<string, unknown>;\n  }[];\n}): FormSpec<M> {\n  return spec as unknown as FormSpec<M>;\n}\n"],"mappings":"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"}