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

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

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

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

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

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

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

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

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"openapi-export.docblock.js","names":["tech_contracts_openapi_export_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/contracts/openapi-export.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_contracts_openapi_export_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.contracts.openapi-export',\n    title: 'OpenAPI export (OpenAPI 3.1) from SpecRegistry',\n    summary:\n      'Generate a deterministic OpenAPI document from a SpecRegistry using jsonSchemaForSpec + REST transport metadata.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/contracts/openapi-export',\n    tags: ['contracts', 'openapi', 'rest'],\n    body: `## OpenAPI export (OpenAPI 3.1) from SpecRegistry\n\n### Purpose\n\nContractSpec specs can be exported into an **OpenAPI 3.1** document for tooling (SDK generation, docs, gateways).\n\nThe export is **spec-first**:\n\n- Uses \\`jsonSchemaForSpec(spec)\\` for input/output JSON Schema (from SchemaModel → zod → JSON Schema)\n- Uses \\`spec.transport.rest.method/path\\` when present\n- Falls back to deterministic defaults:\n  - Method: \\`POST\\` for commands, \\`GET\\` for queries\n  - Path: \\`defaultRestPath(name, version)\\` → \\`/<dot/name>/v<version>\\`\n\n### Library API\n\n- Function: \\`openApiForRegistry(registry, options?)\\`\n- Location: \\`@lssm/lib.contracts/openapi\\`\n\n### CLI\n\nExport OpenAPI from a registry module:\n\n\\`\\`\\`bash\ncontractspec openapi --registry ./src/registry.ts --out ./openapi.json\n\\`\\`\\`\n\nThe registry module must export one of:\n\n- \\`registry: SpecRegistry\\`\n- \\`default(): SpecRegistry | Promise<SpecRegistry>\\`\n- \\`createRegistry(): SpecRegistry | Promise<SpecRegistry>\\`\n\n### Notes / limitations (current)\n\n- Responses are generated as a basic \\`200\\` response (plus schemas when available).\n- Query (GET) inputs are currently represented as a JSON request body when an input schema exists.\n- Errors are not yet expanded into OpenAPI responses; that will be added when we standardize error envelopes.`,\n  },\n];\n\nregisterDocBlocks(tech_contracts_openapi_export_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,0CAAsD,CACjE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAa;EAAW;EAAO;CACtC,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCP,CACF;AAED,kBAAkB,wCAAwC"}

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

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"ops-to-presentation-linking.docblock.js","names":["tech_contracts_ops_to_presentation_linking_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/contracts/ops-to-presentation-linking.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_contracts_ops_to_presentation_linking_DocBlocks: DocBlock[] =\n  [\n    {\n      id: 'docs.tech.contracts.ops-to-presentation-linking',\n      title: 'Ops \\u2194 Presentation linking (V2)',\n      summary:\n        'This document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.',\n      kind: 'reference',\n      visibility: 'public',\n      route: '/docs/tech/contracts/ops-to-presentation-linking',\n      tags: ['tech', 'contracts', 'ops-to-presentation-linking'],\n      body: \"### Ops \\u2194 Presentation linking (V2)\\n\\nThis document explains how operations (ContractSpec) are linked to Presentations (PresentationDescriptorV2) via Feature modules.\\n\\n- Location: `@lssm/lib.contracts/src/features.ts`\\n- Field: `FeatureModuleSpec.opToPresentation?: { op: { name; version }; pres: { name; version } }[]`\\n- Validation: `installFeature()` validates that linked ops exist in `SpecRegistry` and linked presentations exist in the registry, and that declared targets are present.\\n\\nExample:\\n\\n```ts\\nimport type { SpecRegistry } from '@lssm/lib.contracts/src/registry';\\nimport { FeatureRegistry, createFeatureModule } from '@lssm/lib.contracts';\\n\\nexport function buildFeaturesWithOps(ops: SpecRegistry) {\\n  const features = new FeatureRegistry();\\n  features.register(\\n    createFeatureModule(\\n      {\\n        key: 'myapp.widgets.linkage',\\n        title: 'Widgets (linked)',\\n        description: 'Links create/update ops to UI presentations',\\n        domain: 'widgets',\\n        tags: ['widgets', 'linkage'],\\n        stability: 'beta',\\n      },\\n      {\\n        operations: [\\n          { name: 'widgets.create', version: 1 },\\n          { name: 'widgets.update', version: 1 },\\n        ],\\n        presentations: [{ name: 'myapp.widgets.editor.page', version: 1 }],\\n        opToPresentation: [\\n          {\\n            op: { name: 'widgets.create', version: 1 },\\n            pres: { name: 'myapp.widgets.editor.page', version: 1 },\\n          },\\n          {\\n            op: { name: 'widgets.update', version: 1 },\\n            pres: { name: 'myapp.widgets.editor.page', version: 1 },\\n          },\\n        ],\\n        presentationsTargets: [\\n          {\\n            name: 'myapp.widgets.editor.page',\\n            version: 1,\\n            targets: ['react', 'markdown'],\\n          },\\n        ],\\n      }\\n    )\\n  );\\n  return { features };\\n}\\n```\\n\\nNotes\\n\\n- This enables traceability: the UI flow that realizes an op is discoverable via the feature catalog.\\n- Presentations can target multiple outputs (`react`, `markdown`, `application/json`, `application/xml`).\\n- Use `renderFeaturePresentation()` to render a descriptor to a given target with a component map.\\n\",\n    },\n  ];\nregisterDocBlocks(tech_contracts_ops_to_presentation_linking_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,uDACX,CACE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAQ;EAAa;EAA8B;CAC1D,MAAM;CACP,CACF;AACH,kBAAkB,qDAAqD"}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/docs/tech/lifecycle-stage-system.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"lifecycle-stage-system.docblock.js","names":["tech_lifecycle_stage_system_DocBlocks: DocBlock[]"],"sources":["../../../src/docs/tech/lifecycle-stage-system.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../registry';\n\nexport const tech_lifecycle_stage_system_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.lifecycle-stage-system',\n    title: 'ContractSpec Lifecycle Stage System \\u2013 Technical Design',\n    summary:\n      'This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/lifecycle-stage-system',\n    tags: ['tech', 'lifecycle-stage-system'],\n    body: '## ContractSpec Lifecycle Stage System \\u2013 Technical Design\\n\\nThis document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.\\n\\n---\\n\\n### 1. Architecture Overview\\n\\n```\\n\\u250c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2510\\n\\u2502 @lssm/lib.lifecycle  \\u2502  Types, enums, helpers (pure data)\\n\\u2514\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u252c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2518\\n            \\u2502\\n\\u250c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u25bc\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2510    \\u250c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2510\\n\\u2502 modules/lifecycle-   \\u2502    \\u2502 modules/lifecycle-advisor  \\u2502\\n\\u2502 core (detection)     \\u2502    \\u2502 (guidance & ceremonies)    \\u2502\\n\\u2514\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u252c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2518    \\u2514\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u252c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2518\\n            \\u2502                           \\u2502\\n            \\u251c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u252c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2524\\n            \\u25bc            \\u25bc              \\u25bc\\n  Adapters: analytics, intent, questionnaires\\n            \\u2502\\n\\u250c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u25bc\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2510\\n\\u2502 bundles/lifecycle-   \\u2502  Managed service for Studio\\n\\u2502 managed              \\u2502  (REST handlers, AI agent)     \\u2502\\n\\u2514\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u252c\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2500\\u2518\\n            \\u2502\\n  ContractSpec Studio surfaces\\n  (web/mobile APIs, CLI, docs)\\n```\\n\\n- **Libraries** provide shared vocabulary.\\n- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.\\n- **Bundles** compose modules, register agents/events, and expose APIs for Studio.\\n- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve `@lssm/bundle.contractspec-studio` and `@lssm/lib.database-contractspec-studio` directly from their `packages/.../src` folders via `tsconfig` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled `dist` artifacts into client chunks.\\n\\n---\\n\\n### 2. Core Library (`@lssm/lib.lifecycle`)\\n\\n- Stage enum (0\\u20136) with metadata (`question`, `signals`, `traps`).\\n- Axes types (`ProductPhase`, `CompanyPhase`, `CapitalPhase`).\\n- `LifecycleSignal` (source, metric, value, timestamp).\\n- `LifecycleMetricSnapshot` (aggregated numbers).\\n- `LifecycleMilestone`, `LifecycleAction`, `LifecycleAssessment` interfaces.\\n- Utility helpers:\\n  - `formatStageSummary(stage, assessment)`\\n  - `rankStageCandidates(scores)`\\n\\nThe library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.\\n\\n---\\n\\n### 3. Lifecycle Core Module\\n\\n**Location:** `packages/modules/lifecycle-core/`\\n\\n#### Components\\n1. **StageSignalCollector**\\n   - Accepts adapter interfaces:\\n     - `AnalyticsAdapter` (pulls metrics from `@lssm/lib.analytics` or fixture streams).\\n     - `IntentAdapter` (hooks into `@lssm/lib.observability` intent detectors or logs).\\n     - `QuestionnaireAdapter` (loads JSON questionnaires and responses).\\n   - Produces normalized `LifecycleSignal[]`.\\n\\n2. **StageScorer**\\n   - Weighted scoring model:\\n     - Base weight per stage (reflecting expected maturity).\\n     - Feature weights (retention, revenue, team size, qualitative feedback).\\n     - Confidence computed via variance of contributing signals.\\n   - Supports pluggable scoring matrices via JSON config.\\n   - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.\\n\\n3. **LifecycleOrchestrator**\\n   - Coordinates collectors + scorer.\\n   - Returns `LifecycleAssessment` with:\\n     - `stage`, `confidence`, `axisSnapshot`, `signalsUsed`.\\n     - Recommended focus areas (high-level categories only).\\n   - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).\\n\\n4. **LifecycleMilestonePlanner**\\n   - Loads `milestones-catalog.json` (no DB).\\n   - Filters upcoming milestones per stage + axis.\\n   - Tracks completion using provided IDs (caller persists).\\n\\n#### Data Files\\n- `configs/stage-weights.json`\\n- `configs/milestones-catalog.json`\\n- `questionnaires/stage-readiness.json`\\n\\n#### Extension Hooks\\n- All adapters exported as TypeScript interfaces.\\n- Implementations for analytics/intent can live in bundles or apps without modifying module code.\\n\\n---\\n\\n### 4. Lifecycle Advisor Module\\n\\n**Location:** `packages/modules/lifecycle-advisor/`\\n\\n#### Components\\n1. **LifecycleRecommendationEngine**\\n   - Consumes `LifecycleAssessment`.\\n   - Maps gaps to `LifecycleAction[]` using rule tables (`stage-playbooks.ts`).\\n   - Supports override hooks for customer-specific rules.\\n\\n2. **ContractSpecLibraryRecommender**\\n   - Maintains mapping from stage \\u2192 recommended libraries/modules/bundles.\\n   - Returns prioritized list with rationale and adoption prerequisites.\\n\\n3. **LifecycleCeremonyDesigner**\\n   - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).\\n   - Ensures low-tech friendly instructions (clear copy, undo guidance).\\n\\n4. **AI Hooks**\\n   - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).\\n   - Keeps actual LLM integration outside module.\\n\\n---\\n\\n### 5. Managed Bundle (`lifecycle-managed`)\\n\\n**Responsibilities**\\n- Wire modules together.\\n- Provide HTTP/GraphQL handlers (exact transport optional).\\n- Register LifecycleAdvisorAgent via `@lssm/lib.ai-agent`.\\n- LifecycleAdvisorAgent meta: domain `operations`, owners `team-lifecycle`, stability `experimental`, tags `guide/lifecycle/ops` so ops tooling can route incidents quickly.\\n- Emit lifecycle events through `@lssm/lib.bus` + `@lssm/lib.analytics`.\\n- Integrate with `contractspec-studio` packages:\\n  - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).\\n  - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).\\n\\n**APIs**\\n- `POST /lifecycle/assessments`: Accepts metrics + optional questionnaire answers. Returns `LifecycleAssessment`.\\n- `GET /lifecycle/playbooks/:stage`: Returns stage playbook + ceremonies.\\n- `POST /lifecycle/advise`: Invokes LifecycleAdvisorAgent with context.\\n\\n**Events**\\n- `LifecycleAssessmentCreated`\\n- `LifecycleStageChanged`\\n- `LifecycleGuidanceConsumed`\\n\\n---\\n\\n### 6. Library Enhancements\\n\\n| Library | Enhancement |\\n| --- | --- |\\n| `@lssm/lib.analytics` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by `StageSignalCollector`. |\\n| `@lssm/lib.evolution` | Accepts `LifecycleContext` when ranking spec anomalies/suggestions. |\\n| `@lssm/lib.growth` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |\\n| `@lssm/lib.observability` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |\\n\\nEach enhancement must import stage types from `@lssm/lib.lifecycle`.\\n\\n---\\n\\n### 7. Feature Flags & Progressive Delivery\\n\\n- Add new flags in progressive-delivery library:\\n  - `LIFECYCLE_DETECTION_ALPHA`\\n  - `LIFECYCLE_ADVISOR_ALPHA`\\n  - `LIFECYCLE_MANAGED_SERVICE`\\n- Bundles/modules should check flags before enabling workflows.\\n- Flags referenced in docs + Studio UI to avoid accidental exposure.\\n\\n---\\n\\n### 8. Analytics & Telemetry\\n\\n- Events defined in analytics library; consumed by bundle/app:\\n  - `lifecycle_assessment_run`\\n  - `lifecycle_stage_changed`\\n  - `lifecycle_guidance_consumed`\\n- Observability pipeline includes:\\n  - Composite lifecycle health metric (weighted sum of KPIs).\\n  - Drift detection comparing stage predictions over time.\\n  - Alert manager recipes for regression (e.g., PMF drop).\\n\\n---\\n\\n### 9. Testing Strategy\\n\\n1. **Unit**\\n   - StageScorer weight matrix.\\n   - RecommendationEngine mapping.\\n   - Library recommender stage coverage.\\n\\n2. **Contract**\\n   - Adapters: ensure mock adapters satisfy interfaces.\\n   - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.\\n\\n3. **Integration**\\n   - CLI example runs detection + guidance end-to-end on fixture data.\\n   - Dashboard example renders assessments, verifying JSON structures remain stable.\\n\\n---\\n\\n### 10. Implementation Checklist\\n\\n- [ ] Documentation (product, tech, ops, user).\\n- [ ] Library creation (`@lssm/lib.lifecycle`).\\n- [ ] Modules (`lifecycle-core`, `lifecycle-advisor`).\\n- [ ] Bundle (`lifecycle-managed`) + Studio wiring.\\n- [ ] Library enhancements (analytics/evolution/growth/observability).\\n- [ ] Examples (CLI + dashboard).\\n- [ ] Feature flags + telemetry.\\n- [ ] Automated tests + fixtures.\\n\\nKeep this document in sync as modules evolve. When adding new stages or axes, update `@lssm/lib.lifecycle` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch\\n\\n\\n',\n  },\n];\nregisterDocBlocks(tech_lifecycle_stage_system_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,wCAAoD,CAC/D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,QAAQ,yBAAyB;CACxC,MAAM;CACP,CACF;AACD,kBAAkB,sCAAsC"}

package/dist/docs/tech/llm/llm-integration.docblock.d.ts.map

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

package/dist/docs/tech/llm/llm-integration.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"llm-integration.docblock.js","names":["tech_llm_integration_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/llm/llm-integration.docblock.ts"],"sourcesContent":["/**\n * DocBlock: LLM Integration\n *\n * Documentation for ContractSpec's LLM integration features.\n */\n\nimport type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_llm_integration_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.llm.overview',\n    title: 'LLM Integration Overview',\n    summary:\n      'Export specs to LLM-friendly formats, generate implementation guides, and verify implementations.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/llm/overview',\n    tags: ['llm', 'ai', 'export', 'guide', 'verify'],\n    body: `# LLM Integration\n\nContractSpec provides first-class LLM integration to bridge specifications and AI coding agents.\n\n## Core Features\n\n### 1. Multi-Format Export\n\nExport specs to markdown in formats optimized for LLM consumption:\n\n- **Context format**: Summary for understanding (goal, context, acceptance criteria)\n- **Full format**: Complete spec with all details (I/O schemas, policy, events)\n- **Prompt format**: Actionable prompt with implementation instructions\n\n### 2. Implementation Guidance\n\nGenerate agent-specific implementation plans:\n\n- **Claude Code**: Extended thinking mode with structured prompts\n- **Cursor CLI**: Background/composer mode with .mdc rules generation\n- **Generic MCP**: Standard format for any MCP-compatible agent\n\n### 3. Tiered Verification\n\nVerify implementations against specs:\n\n- **Tier 1 (Structure)**: Types, exports, imports validation\n- **Tier 2 (Behavior)**: Scenario coverage, error handling, events\n- **Tier 3 (AI Review)**: Semantic compliance analysis via LLM\n\n## Access Points\n\n| Surface | Commands/Tools |\n|---------|---------------|\n| CLI | \\`contractspec llm export\\`, \\`guide\\`, \\`verify\\`, \\`copy\\` |\n| MCP | \\`llm.export\\`, \\`llm.guide\\`, \\`llm.verify\\` tools |\n| VSCode | Export to LLM, Generate Guide, Verify, Copy commands |\n\n## Quick Start\n\n### CLI Usage\n\n\\`\\`\\`bash\n# Export spec as markdown\ncontractspec llm export path/to/my.spec.ts --format full\n\n# Generate implementation guide\ncontractspec llm guide path/to/my.spec.ts --agent claude-code\n\n# Verify implementation\ncontractspec llm verify path/to/my.spec.ts path/to/impl.ts --tier 2\n\n# Copy spec to clipboard\ncontractspec llm copy path/to/my.spec.ts --format context\n\\`\\`\\`\n\n### MCP Usage\n\n\\`\\`\\`\n# Export spec\nllm.export { specPath: \"path/to/my.spec.ts\", format: \"full\" }\n\n# Generate guide\nllm.guide { specPath: \"path/to/my.spec.ts\", agent: \"cursor-cli\" }\n\n# Verify implementation\nllm.verify { specPath: \"path/to/my.spec.ts\", implementationPath: \"path/to/impl.ts\", tier: \"2\" }\n\\`\\`\\`\n\n### Programmatic Usage\n\n\\`\\`\\`typescript\nimport { specToFullMarkdown, specToAgentPrompt } from '@lssm/lib.contracts/llm';\nimport { createAgentGuideService, createVerifyService } from '@lssm/bundle.contractspec-workspace';\n\n// Export\nconst markdown = specToFullMarkdown(mySpec);\n\n// Generate guide\nconst guideService = createAgentGuideService({ defaultAgent: 'claude-code' });\nconst guide = guideService.generateGuide(mySpec);\n\n// Verify\nconst verifyService = createVerifyService();\nconst result = await verifyService.verify(mySpec, implementationCode, {\n  tiers: ['structure', 'behavior']\n});\n\\`\\`\\`\n`,\n  },\n  {\n    id: 'docs.tech.llm.export-formats',\n    title: 'LLM Export Formats',\n    summary:\n      'Detailed explanation of the three export formats for LLM consumption.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/llm/export-formats',\n    tags: ['llm', 'export', 'markdown'],\n    body: `# LLM Export Formats\n\nContractSpec provides three export formats optimized for different LLM use cases.\n\n## Context Format\n\nBest for: Understanding what a spec does, providing background to LLMs.\n\nIncludes:\n- Spec name, version, type\n- Goal and context\n- Description\n- Acceptance scenarios\n\nExample:\n\n\\`\\`\\`markdown\n# users.createUser (v1)\n\n> Create a new user account with email verification.\n\n**Type:** command | **Stability:** stable\n\n## Goal\nCreate a new user in the system and trigger email verification.\n\n## Context\nPart of the user onboarding flow. Called after signup form submission.\n\n## Acceptance Criteria\n### Happy path\n**Given:** Valid email and password\n**When:** User submits registration\n**Then:** Account is created, verification email is sent\n\\`\\`\\`\n\n## Full Format\n\nBest for: Complete documentation, implementation reference.\n\nIncludes everything:\n- All metadata\n- JSON schemas for I/O\n- Error definitions\n- Policy (auth, rate limits, PII)\n- Events emitted\n- Examples\n- Transport configuration\n\n## Prompt Format\n\nBest for: Feeding directly to coding agents.\n\nIncludes:\n- Task header with clear instructions\n- Full spec context\n- Implementation requirements\n- Task-specific guidance (implement/test/refactor/review)\n- Expected output format\n\nThe prompt format adapts based on task type:\n- **implement**: Full implementation with tests\n- **test**: Test generation for existing code\n- **refactor**: Refactoring while maintaining behavior\n- **review**: Code review against spec\n`,\n  },\n  {\n    id: 'docs.tech.llm.agent-adapters',\n    title: 'Agent Adapters',\n    summary: 'Adapters for different AI coding agents (Claude, Cursor, MCP).',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/llm/agent-adapters',\n    tags: ['llm', 'agents', 'claude', 'cursor', 'mcp'],\n    body: `# Agent Adapters\n\nContractSpec provides specialized adapters for different AI coding agents.\n\n## Claude Code Adapter\n\nOptimized for Anthropic Claude's extended thinking and code generation.\n\nFeatures:\n- Structured markdown with clear sections\n- Checklists for steps and verification\n- Icons for file operations (📝 create, ✏️ modify)\n- System prompt for ContractSpec context\n\nUsage:\n\\`\\`\\`typescript\nconst guideService = createAgentGuideService({ defaultAgent: 'claude-code' });\nconst result = guideService.generateGuide(spec, { agent: 'claude-code' });\n// result.prompt.systemPrompt - Claude system context\n// result.prompt.taskPrompt - Task-specific instructions\n\\`\\`\\`\n\n## Cursor CLI Adapter\n\nOptimized for Cursor's background/composer mode.\n\nFeatures:\n- Compact format for context efficiency\n- .mdc cursor rules generation\n- Integration with Cursor's file system\n- Concise step lists\n\nGenerate Cursor Rules:\n\\`\\`\\`typescript\nconst cursorRules = guideService.generateAgentConfig(spec, 'cursor-cli');\n// Save to .cursor/rules/my-spec.mdc\n\\`\\`\\`\n\n## Generic MCP Adapter\n\nWorks with any MCP-compatible agent (Cline, Aider, etc.).\n\nFeatures:\n- Standard markdown format\n- Table-based metadata\n- JSON resource format support\n- Prompt message format\n\nThe generic adapter is the default and works across all agents.\n\n## Choosing an Adapter\n\n| Agent | Best For | Key Features |\n|-------|----------|--------------|\n| Claude Code | Complex implementations | Extended thinking, detailed steps |\n| Cursor CLI | IDE-integrated work | Cursor rules, compact format |\n| Generic MCP | Any MCP agent | Universal compatibility |\n`,\n  },\n  {\n    id: 'docs.tech.llm.verification',\n    title: 'Implementation Verification',\n    summary: 'Tiered verification of implementations against specifications.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/llm/verification',\n    tags: ['llm', 'verify', 'validation', 'testing'],\n    body: `# Implementation Verification\n\nContractSpec provides tiered verification to check if implementations comply with specs.\n\n## Verification Tiers\n\n### Tier 1: Structure (Fast)\n\nChecks TypeScript structure against spec requirements:\n\n| Check | What it validates |\n|-------|------------------|\n| Handler export | Function is properly exported |\n| Contracts import | Imports from @lssm/lib.contracts |\n| Schema import | Imports from @lssm/lib.schema |\n| No \\`any\\` type | TypeScript strict compliance |\n| Error handling | Error codes are referenced |\n| Event emission | Event patterns exist |\n| Input validation | Validation patterns used |\n| Async patterns | Async/await for commands |\n\n### Tier 2: Behavior (Comprehensive)\n\nChecks implementation coverage of spec behaviors:\n\n| Check | What it validates |\n|-------|------------------|\n| Scenario coverage | Acceptance scenarios implemented |\n| Example coverage | Example I/O values referenced |\n| Error cases | All error conditions handled |\n| Event conditions | Events emitted correctly |\n| Idempotency | Idempotent patterns (if required) |\n\n### Tier 3: AI Review (Deep)\n\nUses LLM for semantic analysis:\n\n- Does the implementation fulfill the spec's intent?\n- Are edge cases properly handled?\n- Is the code quality acceptable?\n- Are there any subtle violations?\n\nRequires AI API key configuration.\n\n## Running Verification\n\n\\`\\`\\`typescript\nconst verifyService = createVerifyService({\n  aiApiKey: process.env.ANTHROPIC_API_KEY, // Optional, for Tier 3\n  aiProvider: 'anthropic',\n});\n\nconst result = await verifyService.verify(spec, implementationCode, {\n  tiers: ['structure', 'behavior'],\n  failFast: false,\n  includeSuggestions: true,\n});\n\nconsole.log(result.passed);  // true/false\nconsole.log(result.score);   // 0-100\nconsole.log(result.summary); // Human-readable summary\n\\`\\`\\`\n\n## Verification Report\n\nThe report includes:\n\n- **passed**: Overall compliance\n- **score**: 0-100 score\n- **issues**: Array of problems found\n- **suggestions**: Recommended fixes\n- **coverage**: Metrics on scenario/error/field coverage\n\nEach issue has:\n- **severity**: error, warning, or info\n- **category**: type, export, import, scenario, error_handling, semantic\n- **message**: Description of the issue\n- **suggestion**: How to fix it\n`,\n  },\n];\n\nregisterDocBlocks(tech_llm_integration_DocBlocks);\n"],"mappings":";;;AASA,MAAaA,iCAA6C;CACxD;EACE,IAAI;EACJ,OAAO;EACP,SACE;EACF,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM;GAAC;GAAO;GAAM;GAAU;GAAS;GAAS;EAChD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyFP;CACD;EACE,IAAI;EACJ,OAAO;EACP,SACE;EACF,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM;GAAC;GAAO;GAAU;GAAW;EACnC,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkEP;CACD;EACE,IAAI;EACJ,OAAO;EACP,SAAS;EACT,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM;GAAC;GAAO;GAAU;GAAU;GAAU;GAAM;EAClD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0DP;CACD;EACE,IAAI;EACJ,OAAO;EACP,SAAS;EACT,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM;GAAC;GAAO;GAAU;GAAc;GAAU;EAChD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+EP;CACF;AAED,kBAAkB,+BAA+B"}

package/dist/docs/tech/mcp-endpoints.docblock.d.ts.map

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

package/dist/docs/tech/mcp-endpoints.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp-endpoints.docblock.js","names":["tech_mcp_endpoints_DocBlocks: DocBlock[]"],"sources":["../../../src/docs/tech/mcp-endpoints.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../registry';\n\nexport const tech_mcp_endpoints_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.mcp.endpoints',\n    title: 'ContractSpec MCP endpoints',\n    summary:\n      'Dedicated MCP servers for docs, CLI usage, and internal development.',\n    kind: 'reference',\n    visibility: 'mixed',\n    route: '/docs/tech/mcp/endpoints',\n    tags: ['mcp', 'docs', 'cli', 'internal'],\n    body: `# ContractSpec MCP endpoints\n\nThree dedicated MCP servers keep AI agents efficient and scoped:\n\n- **Docs MCP**: \\`/api/mcp/docs\\` — exposes DocBlocks as resources + presentations. Tool: \\`docs.search\\`.\n- **CLI MCP**: \\`/api/mcp/cli\\` — surfaces CLI quickstart/reference/README and suggests commands. Tool: \\`cli.suggestCommand\\`.\n- **Internal MCP**: \\`/api/mcp/internal\\` — internal routing hints, playbook, and example registry access. Tool: \\`internal.describe\\`.\n\n### Usage notes\n- Transports are HTTP POST (streamable HTTP); SSE is disabled.\n- Resources are namespaced (\\`docs://*\\`, \\`cli://*\\`, \\`internal://*\\`) and are read-only.\n- Internal MCP also exposes the examples registry via \\`examples://*\\` resources:\n  - \\`examples://list?q=<query>\\`\n  - \\`examples://example/<id>\\`\n- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.\n- GraphQL remains at \\`/graphql\\`; health at \\`/health\\`.\n`,\n  },\n];\n\nregisterDocBlocks(tech_mcp_endpoints_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,+BAA2C,CACtD;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAO;EAAQ;EAAO;EAAW;CACxC,MAAM;;;;;;;;;;;;;;;;;CAiBP,CACF;AAED,kBAAkB,6BAA6B"}

package/dist/docs/tech/presentation-runtime.docblock.d.ts.map

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

package/dist/docs/tech/presentation-runtime.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"presentation-runtime.docblock.js","names":["tech_presentation_runtime_DocBlocks: DocBlock[]"],"sources":["../../../src/docs/tech/presentation-runtime.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../registry';\n\nexport const tech_presentation_runtime_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.presentation-runtime',\n    title: 'Presentation Runtime',\n    summary: 'Cross-platform runtime for list pages and presentation flows.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/presentation-runtime',\n    tags: ['tech', 'presentation-runtime'],\n    body: \"## Presentation Runtime\\n\\nCross-platform runtime for list pages and presentation flows.\\n\\n### Packages\\n\\n- `@lssm/lib.presentation-runtime-core`: shared types and config helpers\\n- `@lssm/lib.presentation-runtime-react`: React hooks (web/native-compatible API)\\n- `@lssm/lib.presentation-runtime-react-native`: Native entrypoint (re-exports React API for now)\\n\\n### Next.js config helper\\n\\n```ts\\n// next.config.mjs\\nimport { withPresentationNextAliases } from '@lssm/lib.presentation-runtime-core/next';\\n\\nconst nextConfig = {\\n  webpack: (config) => withPresentationNextAliases(config),\\n};\\n\\nexport default nextConfig;\\n```\\n\\n### Metro config helper\\n\\n```js\\n// metro.config.js (CJS)\\nconst { getDefaultConfig } = require('expo/metro-config');\\nconst {\\n  withPresentationMetroAliases,\\n} = require('@lssm/lib.presentation-runtime-core/src/metro.cjs');\\n\\nconst projectRoot = __dirname;\\nconst config = getDefaultConfig(projectRoot);\\n\\nmodule.exports = withPresentationMetroAliases(config);\\n```\\n\\n### React hooks\\n\\n- `useListCoordinator`: URL + RHF + derived variables (no fetching)\\n- `usePresentationController`: Same plus `fetcher` integration\\n- `DataViewRenderer` (design-system): render `DataViewSpec` projections (`list`, `table`, `detail`, `grid`) using shared UI atoms\\n\\nBoth accept a `useUrlState` adapter. On web, use `useListUrlState` (design-system) or a Next adapter.\\n\\n### KYC molecules (bundle)\\n\\n- `ComplianceBadge` in `@lssm/bundle.strit/presentation/components/kyc` renders a status badge for KYC/compliance snapshots. It accepts a `state` (missing_core | incomplete | complete | expiring | unknown) and optional localized `labels`. Prefer consuming apps to pass translated labels (e.g., via `useT('appPlatformAdmin')`).\\n\\n### Markdown routes and llms.txt\\n\\n- Each web app exposes `/llms` (and `/llms.txt`, `/llms.md`) via rewrites. See [llmstxt.org](https://llmstxt.org/).\\n- Catch\\u2011all markdown handler lives at `app/[...slug].md/route.ts`. It resolves a page descriptor from `app/.presentations.manifest.json` and renders via the `presentations.v2` engine (target: `markdown`).\\n- Per\\u2011page companion convention: add `app/<route>/ai.ts` exporting a `PresentationDescriptorV2`.\\n- Build\\u2011time tool: `tools/generate-presentations-manifest.mjs <app-root>` populates the manifest.\\n- CI check: `pnpm llms:check` verifies coverage (% of pages with descriptors) and fails if below threshold.\\n\",\n  },\n];\nregisterDocBlocks(tech_presentation_runtime_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,sCAAkD,CAC7D;CACE,IAAI;CACJ,OAAO;CACP,SAAS;CACT,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,QAAQ,uBAAuB;CACtC,MAAM;CACP,CACF;AACD,kBAAkB,oCAAoC"}

package/dist/docs/tech/schema/README.docblock.d.ts.map

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

package/dist/docs/tech/schema/README.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"README.docblock.js","names":["tech_schema_README_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/schema/README.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_schema_README_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.schema.README',\n    title: 'Multi\\u2011File Prisma Schema Conventions (per database)',\n    summary:\n      'We adopt Prisma multi\\u2011file schema (GA \\u2265 v6.7) to organize each database\\u2019s models by domain and to import core LSSM module schemas locally.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/schema/README',\n    tags: ['tech', 'schema', 'README'],\n    body: \"# Multi\\u2011File Prisma Schema Conventions (per database)\\n\\nWe adopt Prisma multi\\u2011file schema (GA \\u2265 v6.7) to organize each database\\u2019s models by domain and to import core LSSM module schemas locally.\\n\\nCanonical layout per DB:\\n\\n```\\nprisma/\\n  schema/\\n    main.prisma             # datasource + generators only\\n    imported/\\n      lssm_sigil/*.prisma   # imported models/enums only (no datasource/generator)\\n      lssm_content/*.prisma # idem\\n    <domain>/*.prisma       # vertical\\u2011specific models split by bounded context\\n```\\n\\nNotes:\\n\\n- Imported files contain only `model` and `enum` blocks (strip `datasource`/`generator`).\\n- Preserve `@@schema(\\\"\\u2026\\\")` annotations to keep tables in their Postgres schemas; we now explicitly list schemas in `main.prisma` to avoid P1012: `schemas = [\\\"public\\\",\\\"lssm_sigil\\\",\\\"lssm_content\\\",\\\"lssm_featureflags\\\",\\\"lssm_ops\\\",\\\"lssm_planning\\\",\\\"lssm_quill\\\",\\\"lssm_geoterro\\\"]`.\\n- Use `@lssm/app.cli-database` CLI: `database import|check|generate|migrate:*|seed` to manage a single DB; `@lssm/app.cli-databases` orchestrates multiple DBs.\\n\\n## Typed merger config\\n\\n- Define imported module list once per DB with a typed config:\\n\\n```ts\\n// prisma-merger.config.ts\\nimport { defineMergedPrismaConfig } from '@lssm/app.cli-database';\\n\\nexport default defineMergedPrismaConfig({\\n  modules: [\\n    '@lssm/app.cli-database-sigil',\\n    '@lssm/app.cli-database-content',\\n    // ...\\n  ],\\n});\\n```\\n\\n- Then run `database import --target .` (no need to pass `--modules`).\\n\\n## Prisma Config (prisma.config.ts)\\n\\nWe use Prisma Config per official docs to point Prisma to the multi-file schema folder and migrations:\\n\\n```ts\\n// prisma.config.ts\\nimport path from 'node:path';\\nimport { defineConfig } from 'prisma/config';\\n\\nexport default defineConfig({\\n  schema: path.join('prisma', 'schema'),\\n  migrations: { path: path.join('prisma', 'migrations') },\\n});\\n```\\n\\nReference: Prisma blog \\u2013 Organize Your Prisma Schema into Multiple Files: https://www.prisma.io/blog/organize-your-prisma-schema-with-multi-file-support\\n\\n---\\n\\n# LSSM Auth (Sigil) \\u2013 Models & Integration\\n\\nThis document tracks the identity models and integration points used by the LSSM Sigil module.\\n\\n## Models (Prisma `lssm_sigil`)\\n\\n- `User` \\u2013 core identity with email, optional phone, role, passkeys, apiKeys\\n- `Session` \\u2013 session tokens and metadata; includes `activeOrganizationId`\\n- `Account` \\u2013 external providers (password, OAuth)\\n- `Organization` \\u2013 tenant boundary; includes `type` additional field\\n- `Member`, `Invitation`, `Team`, `TeamMember` \\u2013 org/teams\\n- `Role`, `Permission`, `PolicyBinding` \\u2013 RBAC\\n- `ApiKey`, `Passkey` \\u2013 programmable access and WebAuthn\\n- `SsoProvider` \\u2013 OIDC/SAML provider configuration (org- or user-scoped)\\n- `OAuthApplication`, `OAuthAccessToken`, `OAuthConsent` \\u2013 first/third-party OAuth\\n\\nThese mirror STRIT additions so Better Auth advanced plugins (admin, organization, apiKey, passkey, genericOAuth) work uniformly across apps.\\n\\n## Better Auth (server)\\n\\nEnabled methods:\\n\\n- Email & password\\n- Phone OTP (Telnyx)\\n- Passkey (WebAuthn)\\n- API keys\\n- Organizations & Teams\\n- Generic OAuth (FranceConnect+ via OIDC with JWE/JWS using JOSE)\\n\\nServer config lives at `packages/lssm/modules/sigil/src/application/services/auth.ts`.\\n\\n## Clients (Expo / React)\\n\\nClient config lives at `packages/lssm/modules/sigil/src/presentation/providers/auth/expo.ts` with plugins for admin, passkey, apiKey, organization, phone, genericOAuth.\\n\\n## Environment Variables\\n\\nTelnyx (phone OTP):\\n\\n- `TELNYX_API_KEY`\\n- `TELNYX_MESSAGING_PROFILE_ID`\\n- `TELNYX_FROM_NUMBER`\\n\\nFranceConnect+ (prefer LSSM*\\u2026 but STRIT*\\u2026 fallbacks are supported):\\n\\n- `LSSM_FRANCECONNECTPLUS_DISCOVERY_URL`\\n- `LSSM_FRANCECONNECTPLUS_CLIENT_ID`\\n- `LSSM_FRANCECONNECTPLUS_CLIENT_SECRET`\\n- `LSSM_FRANCECONNECTPLUS_ENC_PRIVATE_KEY_PEM` (PKCS8; RSA-OAEP-256)\\n\\nGeneric:\\n\\n- `API_URL_IDENTITIES` \\u2013 base URL for Better Auth server\\n- `BETTER_AUTH_SECRET` \\u2013 server secret\\n\\nKeep this in sync with code changes to avoid drift.\\n\\n## HCircle domain splits and auth removal\\n\\n- Auth/identity models are not defined locally anymore. They come from `@lssm/app.cli-database-sigil` under the `lssm_sigil` schema.\\n- `packages/hcircle/libs/database-coliving/prisma/schema/domain/` is split by domain; newsletter/waiting list lives in `newsletter.prisma` and uses `@@map(\\\"waiting_list\\\")`.\\n- To avoid collisions with module names, the local event models were renamed to `SocialEvent`, `SocialEventAttendee`, and `SocialEventRecurrence` with `@@map` pointing to existing table names.\\n\\n---\\n\\n## Vertical profiles (current)\\n\\n### STRIT\\n\\n- prisma-merger modules:\\n  - `@lssm/app.cli-database-sigil`, `@lssm/app.cli-database-content`, `@lssm/app.cli-database-ops`, `@lssm/app.cli-database-planning`, `@lssm/app.cli-database-quill`, `@lssm/app.cli-database-geoterro`\\n- main.prisma schemas:\\n  - `schemas = [\\\"public\\\",\\\"lssm_sigil\\\",\\\"lssm_content\\\",\\\"lssm_ops\\\",\\\"lssm_planning\\\",\\\"lssm_quill\\\",\\\"lssm_geoterro\\\"]`\\n- domain splits (`packages/strit/libs/database/prisma/schema/domain/`):\\n  - `bookings.prisma` (Booking, StritDocument + links to Content `File` and Sigil `Organization`)\\n  - `commerce.prisma` (Wholesale models; `sellerId` linked to Sigil `Organization`)\\n  - `files.prisma` (PublicFile, PublicFileAccessLog; `ownerId`\\u2192Organization, `uploadedBy`\\u2192User)\\n  - `geo.prisma` (PublicCountry, PublicAddress, City; links to Spots/Series)\\n  - `spots.prisma`, `urbanism.prisma`, `analytics.prisma`, `onboarding.prisma`, `referrals.prisma`, `subscriptions.prisma`, `content.prisma`\\n- auth models are imported from Sigil (no local auth tables).\\n- Back-relations for `Organization` (e.g., `files`, seller relations) are declared in the Sigil module to avoid scattering.\\n\\n### ARTISANOS\\n\\n- prisma-merger modules:\\n  - `@lssm/app.cli-database-sigil`, `@lssm/app.cli-database-content`, `@lssm/app.cli-database-featureflags`, `@lssm/app.cli-database-ops`, `@lssm/app.cli-database-planning`, `@lssm/app.cli-database-quill`, `@lssm/app.cli-database-geoterro`\\n- main.prisma schemas:\\n  - `schemas = [\\\"public\\\",\\\"lssm_sigil\\\",\\\"lssm_content\\\",\\\"lssm_featureflags\\\",\\\"lssm_ops\\\",\\\"lssm_planning\\\",\\\"lssm_quill\\\",\\\"lssm_geoterro\\\"]`\\n- domain splits (`packages/artisanos/libs/database-artisan/prisma/schema/domain/`):\\n  - `sales.prisma` (Client, Quote, QuoteTemplate, Invoice, FollowUps)\\n  - `subsidies.prisma` (SubsidyProgram, AidApplication, SupportingDocument)\\n  - `projects.prisma` (Project, ProjectPlanningSettings)\\n  - `crm.prisma` (OrganizationProfessionalProfile, OrganizationCertification)\\n  - `professions.prisma`, `products.prisma`, `templates.prisma`, `analytics.prisma`, `onboarding.prisma`, `referrals.prisma`, `subscriptions.prisma`, `files.prisma`\\n- auth/organization/team models are provided by Sigil; local legacy copies were removed.\\n- Where names collide with Content, local models are prefixed (e.g., `PublicFile`) and use `@@map` to keep existing table names where applicable.\\n\\n## Schema Dictionary: `@lssm/lib.schema`\\n\\n### Purpose\\n\\nDescribe operation I/O once and generate:\\n\\n- zod (runtime validation)\\n- GraphQL (Pothos types/refs)\\n- JSON Schema (via `zod-to-json-schema` or native descriptors)\\n\\n### Primitives\\n\\n- **FieldType<T>**: describes a scalar or composite field and carries:\\n  - `zod` schema for validation\\n  - optional JSON Schema descriptor\\n  - optional GraphQL scalar reference/name\\n- **SchemaModel**: named object model composed of fields. Exposes helpers:\\n  - `getZod(): z.ZodObject<ZodShapeFromFields<Fields>> | z.ZodArray<z.ZodObject<...>>`\\n    - Preserves each field's schema, optionality, and array-ness\\n    - Top-level lists are supported via `config.isArray: true`\\n  - `getJsonSchema(): JSONSchema7` (export for docs, MCP, forms)\\n  - `getPothosInput()` (GraphQL input object name)\\n\\n### Conventions\\n\\n- Name models with PascalCase; suffix with `Input`/`Result` when ambiguous.\\n- Use explicit enums for multi-value constants; reuse the same enum across input/output.\\n- Define domain enums via `defineEnum('Name', [...])` in the relevant domain package (e.g., `packages/strit/libs/contracts-strit/src/enums/`), not in `ScalarTypeEnum`.\\n- Reference those enums in `SchemaModel` fields directly (they expose `getZod`, `getPothos`, `getJsonSchema`).\\n\\n#### Example (STRIT)\\n\\n```ts\\n// packages/strit/libs/contracts-strit/src/enums/recurrence.ts\\nimport { defineEnum } from '@lssm/lib.schema';\\nexport const SpotEnum = {\\n  Weekday: () =>\\n    defineEnum('Weekday', ['MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU'] as const),\\n  RecurrenceFrequency: () =>\\n    defineEnum('RecurrenceFrequency', [\\n      'DAILY',\\n      'WEEKLY',\\n      'MONTHLY',\\n      'YEARLY',\\n    ] as const),\\n} as const;\\n```\\n\\n```ts\\n// usage in contracts\\nfrequency: { type: SpotEnum.RecurrenceFrequency(), isOptional: false },\\nbyWeekday: { type: SpotEnum.Weekday(), isOptional: true, isArray: true },\\n```\\n\\n- Use `Date` type for temporal values and ensure ISO strings in JSON transports where needed.\\n\\n### Mapping rules (summary)\\n\\n- Strings \\u2192 GraphQL `String`\\n- Numbers \\u2192 `Int` if safe 32-bit integer else `Float`\\n- Booleans \\u2192 `Boolean`\\n- Dates \\u2192 custom `Date` scalar\\n- Arrays<T> \\u2192 list of mapped T (set `isArray: true` on the field)\\n- Top-level arrays \\u2192 set `isArray: true` on the model config\\n- Objects \\u2192 input/output object types with stable field order\\n- Unions \\u2192 supported for output; input unions map to JSON (structural input is not supported by GraphQL)\\n\\n### JSON Schema export\\n\\nPrefer `getZod()` + `zod-to-json-schema` for consistency. For advanced cases, provide a custom `getJsonSchema()` on the model.\\n\\n### Example\\n\\n```ts\\nimport { ScalarTypeEnum, SchemaModel } from '@lssm/lib.schema';\\n\\n// Nested model\\nconst Weekday = new SchemaModel({\\n  name: 'Weekday',\\n  fields: {\\n    value: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },\\n  },\\n});\\n\\n// Parent model with array field and nested object\\nconst Rule = new SchemaModel({\\n  name: 'Rule',\\n  fields: {\\n    timezone: { type: ScalarTypeEnum.TimeZone(), isOptional: false },\\n    byWeekday: { type: Weekday, isOptional: true, isArray: true },\\n  },\\n});\\n\\nconst CreateThingInput = new SchemaModel({\\n  name: 'CreateThingInput',\\n  fields: {\\n    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\\n    rule: { type: Rule, isOptional: false },\\n  },\\n});\\n\\n// zod\\nconst z = CreateThingInput.getZod();\\n```\\n\",\n  },\n];\nregisterDocBlocks(tech_schema_README_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,+BAA2C,CACtD;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAQ;EAAU;EAAS;CAClC,MAAM;CACP,CACF;AACD,kBAAkB,6BAA6B"}

package/dist/docs/tech/studio/learning-events.docblock.d.ts.map

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

package/dist/docs/tech/studio/learning-events.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"learning-events.docblock.js","names":["tech_studio_learning_events_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/learning-events.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_learning_events_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.learning-events',\n    title: 'Studio Learning Events',\n    summary:\n      'Studio persists learning/activity events to the database; Sandbox keeps learning local-first and unlogged.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/learning-events',\n    tags: ['studio', 'learning', 'events', 'analytics', 'sandbox'],\n    body: `# Studio Learning Events\n\nStudio emits lightweight **learning/activity events** to support onboarding, ambient coaching, and learning journeys.\n\n## Persistence model\n\n- **Studio**: events are persisted to the database in \\`StudioLearningEvent\\` and are organization-scoped (optionally project-scoped).\n- **Sandbox**: events remain **local-only** (unlogged); they must never be sent to backend services.\n\n## GraphQL API\n\n- \\`recordLearningEvent(input: { name, projectId?, payload? })\\`\n- \\`myLearningEvents(projectId?, limit?)\\`\n- \\`myOnboardingTracks(productId?, includeProgress?)\\`\n- \\`myOnboardingProgress(trackKey)\\`\n- \\`dismissOnboardingTrack(trackKey)\\`\n\n## Common event names (convention)\n\n- \\`module.navigated\\` — user navigated to a Studio module (payload at minimum: \\`{ moduleId }\\`).\n- \\`studio.template.instantiated\\` — created a new Studio project (starter template). Payload commonly includes \\`{ templateId, projectSlug }\\`.\n- \\`spec.changed\\` — created or updated a Studio spec. Payload may include \\`{ action: 'create' | 'update', specId?, specType? }\\`.\n- \\`regeneration.completed\\` — finished a “regen/deploy” action (currently emitted on successful Studio deploy actions).\n- \\`studio.evolution.applied\\` — completed an Evolution session (payload commonly includes \\`{ evolutionSessionId }\\`).\n\nThese events are intentionally minimal and must avoid PII/secrets in payloads.\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_learning_events_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,wCAAoD,CAC/D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAY;EAAU;EAAa;EAAU;CAC9D,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BP,CACF;AAED,kBAAkB,sCAAsC"}

package/dist/docs/tech/studio/learning-journeys.docblock.d.ts.map

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

package/dist/docs/tech/studio/learning-journeys.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"learning-journeys.docblock.js","names":["tech_studio_learning_journeys_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/learning-journeys.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_learning_journeys_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.learning-journeys',\n    title: 'Studio learning journeys (onboarding + coach)',\n    summary:\n      'DB-backed learning journeys tracked per organization: seeded tracks/steps, event-driven progress, XP/streaks, and a Studio coach surface.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/learning-journeys',\n    tags: [\n      'studio',\n      'learning',\n      'onboarding',\n      'journey',\n      'graphql',\n      'database',\n    ],\n    body: `# Studio learning journeys\n\nStudio supports **DB-backed learning journeys** (onboarding tracks + ambient coach tips) that are advanced by **recorded learning events**.\n\n> See also: \\`/docs/tech/studio/learning-events\\` for event naming + payload guardrails.\n\n## Scope (multi-tenancy)\n\n- Progress is tracked **per organization** (tenant/workspace), via a \\`Learner\\` record keyed by \\`(userId, organizationId)\\`.\n- Learning events are stored as \\`StudioLearningEvent\\` under the Studio DB schema, scoped to an organization (optionally a project).\n\n## Persistence model (Prisma)\n\nLearning journey progress lives in the \\`lssm_learning\\` schema:\n\n- \\`Learner\\` — one per \\`(userId, organizationId)\\`\n- \\`OnboardingTrack\\` — seeded track definitions (trackKey, name, metadata)\n- \\`OnboardingStep\\` — seeded step definitions (stepKey, completionCondition, xpReward, metadata)\n- \\`OnboardingProgress\\` — learner × track progress (progress %, xpEarned, completedAt, dismissedAt)\n- \\`OnboardingStepCompletion\\` — append-only completion records (stepKey, status, xpEarned, completedAt)\n\n## Track definition source (spec-first)\n\n- Canonical track specs live in \\`@lssm/example.learning-journey-registry\\`.\n- The Studio API seeds/updates the DB definitions via an idempotent “ensure tracks” routine.\n- The DB is kept aligned with track specs (stale steps are removed) to prevent drift and unblock completion.\n\n## Progress advancement (event-driven)\n\n1) UI records an event via GraphQL \\`recordLearningEvent\\`\n2) Backend creates \\`StudioLearningEvent\\`\n3) Backend advances onboarding by matching the new event against step completion conditions\n4) Backend persists step completions and recomputes:\n   - \\`progress\\` percentage\n   - \\`xpEarned\\` (including streak/completion bonuses when configured)\n   - track completion state (\\`completedAt\\`)\n\n## GraphQL API (Studio)\n\n- \\`myOnboardingTracks(productId?, includeProgress?)\\`\n  - returns all tracks + optional progress for the current learner\n- \\`myOnboardingProgress(trackKey)\\`\n  - returns progress + step completion list for a single track\n- \\`dismissOnboardingTrack(trackKey)\\`\n  - marks a track dismissed for the learner (prevents auto-coach)\n\n## UI routes/surfaces (web)\n\n- \\`/studio/learning\\` — learning hub (track list + progress widget)\n- \\`/studio/learning/{trackKey}\\` — track detail (steps + map)\n- Studio shell mounts a **coach sheet** that can auto-open for incomplete, non-dismissed onboarding.\n\n## Security + data hygiene\n\n- Do not put secrets/PII in \\`payload\\` fields of learning events.\n- Prefer shallow payload filters (small, stable keys).\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_learning_journeys_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,0CAAsD,CACjE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EACJ;EACA;EACA;EACA;EACA;EACA;EACD;CACD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDP,CACF;AAED,kBAAkB,wCAAwC"}

package/dist/docs/tech/studio/platform-admin-panel.docblock.d.ts.map

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

package/dist/docs/tech/studio/platform-admin-panel.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"platform-admin-panel.docblock.js","names":["tech_studio_platform_admin_panel_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/platform-admin-panel.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_platform_admin_panel_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.platform-admin-panel',\n    title: 'Studio Platform Admin Panel',\n    summary:\n      'How PLATFORM_ADMIN organizations manage tenant orgs and integration connections without session switching.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/platform-admin-panel',\n    tags: ['studio', 'admin', 'multi-tenancy', 'integrations', 'better-auth'],\n    body: `# Studio Platform Admin Panel\n\nContractSpec Studio exposes a dedicated **Platform Admin Panel** for users whose **active organization** has:\n\n- \\`Organization.type = PLATFORM_ADMIN\\`\n\nThe UI route is:\n\n- \\`/studio/admin\\`\n\n## Authorization model (no org switching)\n\nPlatform admins **remain in their own organization**. Cross-tenant actions are always explicit and scoped:\n\n- Admin operations require an explicit \\`targetOrganizationId\\`.\n- No session / activeOrganizationId switching is performed as part of admin operations.\n\n## Integrations management\n\nThe admin panel manages the full ContractSpec Integrations system:\n\n- Lists all shipped \\`IntegrationSpec\\` entries (registry built via \\`createDefaultIntegrationSpecRegistry()\\`).\n- CRUD \\`IntegrationConnection\\` records for a selected tenant org.\n\n### Secrets (reference-only + write-only)\n\nThe admin UI supports two modes:\n\n- **Reference-only (BYOK)**: store only \\`secretProvider\\` + \\`secretRef\\`.\n- **Write-only provisioning/rotation**: paste a raw secret payload; server writes to the selected backend and stores the resulting reference. The secret value is **never returned or displayed**.\n\nSupported backends:\n\n- Env overrides (\\`env://...\\`)\n- Google Cloud Secret Manager (\\`gcp://...\\`)\n- AWS Secrets Manager (\\`aws://secretsmanager/...\\`)\n- Scaleway Secret Manager (\\`scw://secret-manager/...\\`)\n\n## Better Auth Admin plugin\n\nThe panel uses the Better Auth **Admin plugin** for user operations (list users, impersonation):\n\n- Client calls use \\`authClient.admin.*\\`.\n- Server-side, ContractSpec enforces that users in a PLATFORM_ADMIN active org have \\`User.role\\` containing \\`admin\\` so Better Auth Admin endpoints authorize.\n\n## GraphQL surface\n\nThe platform-admin GraphQL operations are guarded by the active org type and include:\n\n- \\`platformAdminOrganizations(search, limit, offset)\\`\n- \\`platformAdminIntegrationSpecs\\`\n- \\`platformAdminIntegrationConnections(input: { targetOrganizationId, category?, status? })\\`\n- \\`platformAdminIntegrationConnectionCreate(input)\\`\n- \\`platformAdminIntegrationConnectionUpdate(input)\\`\n- \\`platformAdminIntegrationConnectionDelete(targetOrganizationId, connectionId)\\`\n\n## Key implementation files\n\n- Auth + role enforcement: \\`packages/bundles/contractspec-studio/src/application/services/auth.ts\\`\n- Admin GraphQL module: \\`packages/bundles/contractspec-studio/src/infrastructure/graphql/modules/platform-admin.ts\\`\n- Integrations admin service: \\`packages/bundles/contractspec-studio/src/modules/platform-integrations/index.ts\\`\n- Web route: \\`packages/apps/web-landing/src/app/(app-customer)/studio/admin/*\\`\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_platform_admin_panel_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,6CAAyD,CACpE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAS;EAAiB;EAAgB;EAAc;CACzE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DP,CACF;AAED,kBAAkB,2CAA2C"}

package/dist/docs/tech/studio/project-access-teams.docblock.d.ts.map

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

package/dist/docs/tech/studio/project-access-teams.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"project-access-teams.docblock.js","names":["tech_studio_project_access_teams_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/project-access-teams.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_project_access_teams_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.project-access-teams',\n    title: 'Studio Project Access via Teams',\n    summary:\n      'Projects live under organizations; team sharing refines access with an admin/owner override.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/project-access-teams',\n    tags: ['studio', 'projects', 'teams', 'rbac', 'access-control'],\n    body: `# Studio Project Access via Teams\n\nStudio access control is **organization-first** with optional **team-based sharing**.\n\n## Data model\n\n- \\`Team\\` and \\`TeamMember\\` define team membership inside an organization.\n- \\`StudioProject\\` is owned by an organization.\n- \\`StudioProjectTeam\\` links projects to 0..N teams.\n\n## Access rules\n\n- **Admins/owners**: always have access to all projects in the organization.\n- **Org-wide projects**: if a project has **no team links**, all organization members can access it.\n- **Team-scoped projects**: if a project has **one or more team links**, a user must be a member of at least one linked team.\n\n## GraphQL surfaces\n\n- Read:\\n  - \\`myStudioProjects\\` (returns only projects you can access)\\n  - \\`studioProjectBySlug(slug)\\` (enforces the same access rules)\\n  - \\`myTeams\\`\\n  - \\`projectTeams(projectId)\\`\\n\\n- Write:\\n  - \\`createStudioProject(input.teamIds?)\\` (teamIds optional)\\n  - \\`setProjectTeams(projectId, teamIds)\\` (admin-only)\\n\n## Related\\n+\\n+- Team administration + invitations: see \\`/docs/tech/studio/team-invitations\\`.\\n+\n## Notes\n\nPayloads and events must avoid secrets/PII. For Sandbox, the model remains local-first and unlogged.\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_project_access_teams_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,6CAAyD,CACpE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAY;EAAS;EAAQ;EAAiB;CAC/D,MAAM;;;;;;;;;;;;;;;;;;;;;;;;CAwBP,CACF;AAED,kBAAkB,2CAA2C"}

package/dist/docs/tech/studio/project-routing.docblock.d.ts.map

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

package/dist/docs/tech/studio/project-routing.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"project-routing.docblock.js","names":["tech_studio_project_routing_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/project-routing.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_project_routing_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.project-routing',\n    title: 'Studio Project Routing',\n    summary:\n      'Studio uses slugged, project-first routes: /studio/{projectSlug}/* with canonical slug redirects and soft-deleted projects hidden.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/project-routing',\n    tags: ['studio', 'routing', 'projects', 'slug', 'redirects'],\n    body: `# Studio Project Routing\n\nContractSpec Studio uses a **project-first URL scheme**:\n\n- \\`/studio/projects\\` — create, select, and delete projects.\n- \\`/studio/{projectSlug}/*\\` — project modules (canvas/specs/deploy/integrations/evolution/learning).\n- \\`/studio/learning\\` — learning hub that does not require selecting a project.\n\n## Studio layout shell\n\nStudio routes are wrapped in a dedicated **Studio app shell** (header + footer) that provides in-app navigation (Projects/Learning/Teams), organization switching, and account actions.\n\nProject module routes (\\`/studio/{projectSlug}/*\\`) render their own module shell (\\`WorkspaceProjectShellLayout\\`). When combined with the global Studio header, the project shell uses a **sticky header offset** to avoid overlapping sticky headers.\n\n## Slug behavior (rename-safe)\n\n- Each project has a \\`slug\\` stored in the database (\\`StudioProject.slug\\`).\n- When a project name changes, Studio **updates the slug** and stores the previous slug as an alias (\\`StudioProjectSlugAlias\\`).\n- Requests to an alias slug are **redirected to the canonical slug**.\n\nGraphQL entrypoint:\n\n- \\`studioProjectBySlug(slug: String!)\\` returns:\n  - \\`project\\`\n  - \\`canonicalSlug\\`\n  - \\`wasRedirect\\`\n\n## Deletion behavior (soft delete)\n\nProjects are **soft-deleted**:\n\n- \\`deleteStudioProject(id: String!)\\` sets \\`StudioProject.deletedAt\\`.\n- All listings and access checks filter \\`deletedAt = null\\`.\n- Soft-deleted projects are treated as “not found” in Studio routes and GraphQL access checks.\n\n## Available modules for a selected project\n\nThe following project modules are expected under \\`/studio/{projectSlug}\\`:\n\n- \\`/canvas\\` — Visual builder canvas (stored via overlays and canvas versions).\n- \\`/specs\\` — Spec editor (stored as \\`StudioSpec\\`).\n- \\`/deploy\\` — Deployments history + triggers (stored as \\`StudioDeployment\\`).\n- \\`/integrations\\` — Integrations scoped to project (stored as \\`StudioIntegration\\`).\n- \\`/evolution\\` — Evolution sessions (stored as \\`EvolutionSession\\`).\n- \\`/learning\\` — Project learning activity.\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_project_routing_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,wCAAoD,CAC/D;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAW;EAAY;EAAQ;EAAY;CAC5D,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CP,CACF;AAED,kBAAkB,sCAAsC"}

package/dist/docs/tech/studio/sandbox-unlogged.docblock.d.ts.map

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

package/dist/docs/tech/studio/sandbox-unlogged.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sandbox-unlogged.docblock.js","names":["tech_studio_sandbox_unlogged_DocBlocks: DocBlock[]"],"sources":["../../../../src/docs/tech/studio/sandbox-unlogged.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@lssm/lib.contracts/docs';\nimport { registerDocBlocks } from '../../registry';\n\nexport const tech_studio_sandbox_unlogged_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.tech.studio.sandbox.unlogged',\n    title: 'Sandbox (unlogged) vs Studio (authenticated)',\n    summary:\n      'The sandbox is a lightweight, unlogged surface that mirrors Studio navigation without auth or analytics.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/tech/studio/sandbox-unlogged',\n    tags: ['studio', 'sandbox', 'privacy', 'analytics'],\n    body: `## Sandbox guarantees\n\n- Route: \\`/sandbox\\`\n- **No auth requirement**\n- **No PostHog init**\n- **No Vercel Analytics**\n- Local-only state (in-browser runtime + localStorage where needed)\n\n## What Sandbox is for\n\n- Try templates and feature modules safely\n- Preview specs/builder/evolution/learning\n- Produce copyable CLI commands (no side effects)\n\n## What Sandbox is *not* for\n\n- Persisted projects/workspaces\n- Real deployments\n- Organization-scoped integrations (unless explicitly enabled later)\n`,\n  },\n];\n\nregisterDocBlocks(tech_studio_sandbox_unlogged_DocBlocks);\n"],"mappings":";;;AAGA,MAAaA,yCAAqD,CAChE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAU;EAAW;EAAW;EAAY;CACnD,MAAM;;;;;;;;;;;;;;;;;;;;CAoBP,CACF;AAED,kBAAkB,uCAAuC"}

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

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

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

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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":";;;AAoCA,IAAa,sBAAb,MAAiC;CAC/B,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CAEjB,YAAY,QAAmC;AAC7C,OAAK,WAAW,OAAO;AACvB,OAAK,gBAAgB,OAAO;AAC5B,OAAK,sBAAsB,OAAO;;CAGpC,MAAM,cACJ,SACsC;EACtC,MAAM,aAAa,KAAK,SAAS,IAAI,QAAQ,YAAY,QAAQ,QAAQ;AACzE,MAAI,CAAC,WAAY,QAAO;EAExB,MAAM,UAAU,WAAW,SAAS,MACjC,YAAY,QAAQ,OAAO,WAAW,eACxC;AACD,MAAI,CAAC,QACH,OAAM,IAAI,MACR,cAAc,WAAW,KAAK,KAAK,2BAA2B,WAAW,iBAC1E;AAEH,UAAQ,WAAW,WAAW,MAA9B;GACE,KAAK,SACH,QAAO;IACL,SAAS,KAAK,aACZ,YACA,KAAK,WAAW,SAAS,WAAW,WAAW,KAAK,CACrD;IACD,QAAQ;IACT;GACH,KAAK,SACH,QAAO;IACL,SAAS,KAAK,aACZ,YACA,KAAK,WACH,SACA,WAAW,WAAW,WACtB,WAAW,WAAW,KACvB,CACF;IACD,QAAQ;IACT;GACH,KAAK,YAAY;IACf,MAAM,WAAW,MAAM,KAAK,kBAC1B,YACA,SACA,WAAW,WAAW,MACvB;AACD,QAAI,SACF,QAAO;KACL,SAAS;KACT,QAAQ;KACT;AAEH,QAAI,WAAW,WAAW,aAAa,SACrC,QAAO;KACL,SAAS,KAAK,aAAa,YAAY,KAAK,WAAW,QAAQ,CAAC;KAChE,QAAQ;KACT;AAEH,WAAO;KACL,SAAS;KACT,QAAQ;KACT;;GAEH,QACE,QAAO;IACL,SAAS;IACT,QAAQ;IACT;;;CAIP,AAAQ,aACN,YACA,MACmB;EACnB,MAAM,WAAW,WAAW;EAK5B,MAAM,SAAS,OAJK,SAAS,QAC1B,KAAK,YAAY,OAAO,QAAQ,UAAU,IAC3C,EACD;EAED,IAAI,aAAa;AACjB,OAAK,MAAM,WAAW,UAAU;AAC9B,iBAAc,QAAQ,UAAU;AAChC,OAAI,UAAU,WACZ,QAAO;;AAGX,SAAO,SAAS,SAAS,SAAS;;CAGpC,AAAQ,WAAW,SAA4B,OAAO,IAAY;EAChE,MAAM,OACJ,QAAQ,aACR,QAAQ,UACR,QAAQ,kBACR,GAAG,KAAK,KAAK,CAAC,GAAG,KAAK,QAAQ;AAChC,SAAO,KAAK,mBAAmB,OAAO,KAAK;;CAG7C,AAAQ,WACN,SACA,WACA,OAAO,IACC;EACR,MAAM,QAAQ,QAAQ;AACtB,MAAI,CAAC,MAAO,QAAO,KAAK,WAAW,SAAS,KAAK;AACjD,SAAO,KAAK,mBAAmB,GAAG,MAAM,GAAG,OAAO;;CAGpD,AAAQ,mBAAmB,OAAuB;EAChD,MAAM,OAAO,WAAW,SAAS,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,GAAG,GAAG;AAE1E,SADiB,SAAS,MAAM,GAAG,GAChB,MAAa;;CAGlC,MAAc,kBACZ,YACA,SACA,OACmC;AACnC,OAAK,MAAM,QAAQ,OAAO;AACxB,OAAI,CAAE,MAAM,KAAK,YAAY,MAAM,QAAQ,CAAG;GAC9C,MAAM,UAAU,WAAW,SAAS,MAAM,MAAM,EAAE,OAAO,KAAK,UAAU;AACxE,OAAI,CAAC,QAAS;AACd,OAAI,OAAO,KAAK,eAAe,UAE7B;QADa,KAAK,WAAW,SAAS,QAAQ,KAAK,YAAY,GACpD,KAAK,WACd;;AAGJ,UAAO;;AAET,SAAO;;CAGT,MAAc,YACZ,MACA,SACkB;AAClB,MAAI,KAAK,UAAU,KAAK,eAEtB;OAAI,CADY,MAAM,KAAK,cAAc,KAAK,QAAQ,QAAQ,CAChD,QAAO;;AAEvB,MAAI,KAAK,YAAY;AACnB,OAAI,KAAK,oBACP,QAAO,QAAQ,KAAK,oBAAoB,KAAK,YAAY,QAAQ,CAAC;AAEpE,OAAI;IACF,MAAM,KAAK,IAAI,SAAS,WAAW,WAAW,KAAK,WAAW,IAAI;AAClE,WAAO,QAAQ,GAAG,QAAQ,CAAC;YACpB,QAAQ;AACf,WAAO;;;AAGX,SAAO"}

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

@@ -1 +0,0 @@
-{"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"}