@lssm/lib.contracts 1.11.1 → 1.41.1

package/dist/llm/prompts.js

@@ -0,0 +1,220 @@
+import{specToAgentPrompt as e,specToFullMarkdown as t}from"./exporters.js";const n={"claude-code":`You are an expert TypeScript developer working with ContractSpec, a spec-first development framework.
+
+Your code follows these principles:
+- Type-safe with comprehensive TypeScript types (no \`any\`)
+- Well-documented with JSDoc comments
+- Production-ready with proper error handling
+- Following SOLID principles and clean code practices
+- Modular and testable
+
+When implementing specs:
+1. Validate input against the schema before processing
+2. Handle all error cases defined in the spec
+3. Emit events as specified in sideEffects
+4. Respect policy constraints (auth, rate limits, PII handling)
+5. Follow the acceptance scenarios as your implementation guide
+
+Generate clean, idiomatic TypeScript that exactly matches the specification.`,"cursor-cli":`You are implementing features for a ContractSpec-driven codebase.
+
+ContractSpec is a spec-first framework where specifications define:
+- Operations (commands and queries) with typed I/O
+- Events that operations emit
+- Presentations for UI components
+- Features that group related specs
+
+When working with specs:
+- Read the spec carefully before implementing
+- Match the input/output types exactly
+- Implement all error cases
+- Follow the acceptance scenarios
+- Respect policy constraints
+
+Use the project's existing patterns and conventions.`,"generic-mcp":`You are a code generation assistant working with ContractSpec specifications.
+
+ContractSpec specs define:
+- meta: name, version, kind (command/query), description, goal, context
+- io: input schema, output schema, error definitions
+- policy: auth level, rate limits, feature flags, PII handling
+- sideEffects: events to emit, analytics, audit
+- acceptance: scenarios and examples
+
+Your task is to generate or modify code that complies with the given specification.
+Follow the spec exactly and handle all defined cases.`};function r(r,i,a){let o=n[i],s=t(r),c;return c=i===`claude-code`?`## Implementation Task
+
+Implement the following ContractSpec operation:
+
+${s}
+
+${a?.targetPath?`**Target file:** \`${a.targetPath}\`\n`:``}
+${a?.existingCode?`**Existing code to modify:**\n\`\`\`typescript\n${a.existingCode}\n\`\`\`\n`:``}
+
+Generate a complete, production-ready TypeScript implementation that:
+1. Exports a handler function matching the spec signature
+2. Validates input using the schema
+3. Handles all defined error cases
+4. Emits events as specified
+5. Includes JSDoc documentation
+
+Provide ONLY the TypeScript code.`:i===`cursor-cli`?`Implement this ContractSpec operation.
+
+${s}
+
+${a?.targetPath?`Target: ${a.targetPath}\n`:``}
+
+Requirements:
+- TypeScript with strict types
+- Handle all error cases
+- Emit specified events
+- Follow acceptance scenarios`:e(r,{taskType:`implement`,existingCode:a?.existingCode}),{agent:i,systemPrompt:o,taskPrompt:c}}function i(e,r,i){let a=i?.testFramework??`vitest`,o=`## Test Generation Task
+
+Generate comprehensive tests for this specification:
+
+${t(e)}
+
+${i?.implementationCode?`**Implementation:**\n\`\`\`typescript\n${i.implementationCode}\n\`\`\`\n`:``}
+
+**Test Framework:** ${a}
+
+Generate tests that:
+1. Cover all acceptance scenarios from the spec
+2. Test all defined error cases
+3. Verify input validation
+4. Check event emissions
+5. Test edge cases
+
+Use descriptive test names: "should [behavior] when [condition]"
+
+Provide a complete test file.`;return{agent:r,systemPrompt:n[r],taskPrompt:o}}function a(e,r,i){let a=`## Code Review Task
+
+Review this implementation against its specification:
+
+**Specification:**
+${t(e)}
+
+**Implementation:**
+\`\`\`typescript
+${i}
+\`\`\`
+
+Provide a structured review:
+
+### Compliance Check
+- [ ] Input types match spec
+- [ ] Output types match spec
+- [ ] All error cases handled
+- [ ] Events emitted correctly
+- [ ] Policy constraints respected
+
+### Issues Found
+List any issues with severity (error/warning/info)
+
+### Suggestions
+List improvements and recommendations
+
+Be thorough and precise. Focus on spec compliance first, then code quality.`;return{agent:r,systemPrompt:n[r],taskPrompt:a}}function o(e,n){return{agent:`generic-mcp`,taskPrompt:`## Semantic Verification Task
+
+Verify that this implementation fulfills the specification's intent.
+
+**Specification:**
+${t(e)}
+
+**Implementation:**
+\`\`\`typescript
+${n}
+\`\`\`
+
+Analyze and respond with JSON:
+
+\`\`\`json
+{
+  "passed": true/false,
+  "score": 0-100,
+  "compliance": {
+    "inputTypes": { "match": true/false, "issues": [] },
+    "outputTypes": { "match": true/false, "issues": [] },
+    "errorHandling": { "coverage": "full/partial/none", "missing": [] },
+    "eventEmission": { "correct": true/false, "issues": [] },
+    "policyCompliance": { "auth": true/false, "rateLimit": true/false, "pii": true/false }
+  },
+  "scenarios": [
+    { "name": "scenario name", "covered": true/false, "notes": "" }
+  ],
+  "issues": [
+    { "severity": "error/warning/info", "category": "type/export/import/scenario/error_handling/semantic", "message": "", "suggestion": "" }
+  ],
+  "summary": "Brief summary of verification results"
+}
+\`\`\``}}function s(e,n){let r=e.meta,i=[],a=n?.projectRoot??`src`,o=r.name.replace(/\./g,`/`);(r.kind===`command`||r.kind===`query`)&&i.push({path:`${a}/${o}/handler.ts`,purpose:`Main handler implementation`,type:`create`},{path:`${a}/${o}/types.ts`,purpose:`Type definitions`,type:`create`},{path:`${a}/${o}/handler.test.ts`,purpose:`Handler tests`,type:`create`});let s=[],c=1;s.push({order:c++,title:`Define Types`,description:`Create TypeScript types for input, output, and internal data structures`,acceptanceCriteria:[`Input type matches spec schema exactly`,`Output type matches spec schema exactly`,`Error types defined for all error cases`]}),s.push({order:c++,title:`Implement Input Validation`,description:`Add validation logic for the input payload`,acceptanceCriteria:[`All required fields are validated`,`Type constraints are enforced`,`Validation errors return appropriate error codes`]}),s.push({order:c++,title:`Implement Core Logic`,description:`Implement the main business logic of the operation`,acceptanceCriteria:e.acceptance?.scenarios?.map(e=>e.name)??[`Operation completes successfully for valid input`]}),e.io.errors&&Object.keys(e.io.errors).length>0&&s.push({order:c++,title:`Implement Error Handling`,description:`Handle all defined error cases`,acceptanceCriteria:Object.entries(e.io.errors).map(([e,t])=>`Handle ${e}: ${t.when}`)}),e.sideEffects?.emits?.length&&s.push({order:c++,title:`Implement Event Emission`,description:`Emit events as specified`,acceptanceCriteria:e.sideEffects.emits.map(e=>`ref`in e?`Emit ${e.ref.name}.v${e.ref.version} when ${e.when}`:`Emit ${e.name}.v${e.version} when ${e.when}`)}),s.push({order:c++,title:`Write Tests`,description:`Create comprehensive test suite`,acceptanceCriteria:[`All acceptance scenarios covered`,`All error cases tested`,`Edge cases handled`,`Events verified`]});let l={policy:[],security:[],pii:[]};return l.policy.push(`Auth level: ${e.policy.auth}`),e.policy.idempotent!==void 0&&l.policy.push(`Idempotent: ${e.policy.idempotent}`),e.policy.rateLimit&&l.policy.push(`Rate limit: ${e.policy.rateLimit.rpm} rpm per ${e.policy.rateLimit.key}`),e.policy.flags?.length&&l.policy.push(`Feature flags required: ${e.policy.flags.join(`, `)}`),e.policy.escalate&&l.security.push(`Escalation required: ${e.policy.escalate}`),e.policy.pii?.length&&(l.pii=e.policy.pii),{target:{type:`spec`,name:r.name,version:r.version},context:{goal:r.goal,description:r.description,background:r.context},specMarkdown:t(e),fileStructure:i,steps:s,constraints:l,verificationChecklist:[`Input validation works for all cases`,`Output matches expected schema`,`All error cases return correct codes`,`Events are emitted with correct payloads`,`Auth requirements are enforced`,`Rate limiting is applied (if applicable)`,`PII fields are handled correctly`,`All acceptance scenarios pass`,`Tests provide adequate coverage`]}}function c(e,t){let r;return r=t===`claude-code`?`## Implementation Plan: ${e.target.name}.v${e.target.version}
+
+### Context
+**Goal:** ${e.context.goal}
+
+**Background:** ${e.context.background}
+
+### Specification
+${e.specMarkdown}
+
+### File Structure
+${e.fileStructure.map(e=>`- \`${e.path}\` (${e.type}): ${e.purpose}`).join(`
+`)}
+
+### Implementation Steps
+${e.steps.map(e=>`
+#### Step ${e.order}: ${e.title}
+${e.description}
+
+**Acceptance Criteria:**
+${e.acceptanceCriteria.map(e=>`- [ ] ${e}`).join(`
+`)}
+`).join(`
+`)}
+
+### Constraints
+${e.constraints.policy.length?`**Policy:**\n${e.constraints.policy.map(e=>`- ${e}`).join(`
+`)}\n`:``}
+${e.constraints.security.length?`**Security:**\n${e.constraints.security.map(e=>`- ${e}`).join(`
+`)}\n`:``}
+${e.constraints.pii.length?`**PII Handling:**\n${e.constraints.pii.map(e=>`- ${e}`).join(`
+`)}\n`:``}
+
+### Verification Checklist
+${e.verificationChecklist.map(e=>`- [ ] ${e}`).join(`
+`)}
+
+Implement this plan step by step.`:t===`cursor-cli`?`# ${e.target.name}.v${e.target.version}
+
+${e.context.goal}
+
+## Spec
+${e.specMarkdown}
+
+## Files to create
+${e.fileStructure.map(e=>`${e.type}: ${e.path}`).join(`
+`)}
+
+## Steps
+${e.steps.map(e=>`${e.order}. ${e.title}`).join(`
+`)}`:`Implementation plan for ${e.target.name}.v${e.target.version}
+
+${e.specMarkdown}
+
+Steps:
+${e.steps.map(e=>`${e.order}. ${e.title}: ${e.description}`).join(`
+`)}`,{agent:t,systemPrompt:n[t],taskPrompt:r}}function l(e,n,r){return{agent:`generic-mcp`,taskPrompt:`## Fix Specification Violations
+
+The following implementation has violations against its specification:
+
+**Specification:**
+${t(e)}
+
+**Current Implementation:**
+\`\`\`typescript
+${n}
+\`\`\`
+
+**Violations Found:**
+${r.map((e,t)=>`${t+1}. ${e.message}${e.suggestion?`\n   Suggestion: ${e.suggestion}`:``}`).join(`
+`)}
+
+Fix ALL violations while maintaining existing functionality.
+Provide the corrected implementation.`}}export{n as AGENT_SYSTEM_PROMPTS,c as formatPlanForAgent,l as generateFixViolationsPrompt,s as generateImplementationPlan,r as generateImplementationPrompt,a as generateReviewPrompt,i as generateTestPrompt,o as generateVerificationPrompt};

package/dist/onboarding-base.js

@@ -1 +1 @@
-import{l as e}from"./schema/dist/ScalarTypeEnum.js";import{t}from"./schema/dist/SchemaModel.js";import"./schema/dist/index.js";import{defineCommand as n,defineQuery as r}from"./spec.js";import{OwnersEnum as i,StabilityEnum as a}from"./ownership.js";const o=new t({name:`SaveOnboardingDraftInput`,description:`Input for saving onboarding draft`,fields:{data:{type:e.JSON(),isOptional:!1}}}),s=new t({name:`SaveOnboardingDraftOutput`,description:`Output for saving onboarding draft`,fields:{id:{type:e.ID(),isOptional:!1},organizationId:{type:e.ID(),isOptional:!1}}}),c=n({meta:{name:`base.onboarding.saveDraft`,version:1,stability:a.Beta,owners:[i.PlatformSigil],tags:[`onboarding`,`draft`],description:`Save or update onboarding draft for active organization`,goal:`Persist onboarding progress incrementally for resumption and safety`,context:`Auto-saves every few seconds during onboarding; enables users to leave and resume`},io:{input:o,output:s},policy:{auth:`user`,escalate:null},transport:{gql:{field:`saveOnboardingDraft`},rest:{method:`POST`}}}),l=new t({name:`GetOnboardingDraftOutput`,description:`Onboarding draft payload`,fields:{id:{type:e.ID(),isOptional:!0},organizationId:{type:e.ID(),isOptional:!0},data:{type:e.JSON(),isOptional:!0},createdAt:{type:e.DateTime(),isOptional:!0},updatedAt:{type:e.DateTime(),isOptional:!0}}}),u=r({meta:{name:`base.onboarding.getDraft`,version:1,stability:a.Beta,owners:[i.PlatformSigil],tags:[`onboarding`,`draft`],description:`Get onboarding draft for active organization`,goal:`Retrieve saved onboarding progress`,context:`Called on mount to restore in-progress onboarding`},io:{input:null,output:l},policy:{auth:`user`,escalate:null},transport:{gql:{field:`getOnboardingDraft`},rest:{method:`GET`}}}),d=new t({name:`DeleteOnboardingDraftOutput`,description:`Result of delete operation`,fields:{ok:{type:e.Boolean(),isOptional:!1}}}),f=n({meta:{name:`base.onboarding.deleteDraft`,version:1,stability:a.Beta,owners:[i.PlatformSigil],tags:[`onboarding`,`draft`],description:`Delete onboarding draft for active organization`,goal:`Clear draft after completion or if user wants to restart`,context:`Called after successful onboarding or explicit user reset`},io:{input:null,output:d},policy:{auth:`user`,escalate:null},transport:{gql:{field:`deleteOnboardingDraft`},rest:{method:`POST`}}}),p=new t({name:`CompleteOnboardingBaseInput`,description:`Input for completing onboarding`,fields:{data:{type:e.JSON(),isOptional:!1}}}),m=new t({name:`CompleteOnboardingBaseOutput`,description:`Result of onboarding completion`,fields:{success:{type:e.Boolean(),isOptional:!1},userId:{type:e.ID(),isOptional:!0},organizationId:{type:e.ID(),isOptional:!0}}}),h=n({meta:{name:`base.onboarding.complete`,version:1,stability:a.Beta,owners:[i.PlatformSigil],tags:[`onboarding`],description:`Complete onboarding and finalize user/organization setup`,goal:`Transition from draft to active profile`,context:`Validates all required fields, creates/updates entities, marks onboarding complete`},io:{input:p,output:m},policy:{auth:`user`,escalate:null},transport:{gql:{field:`completeOnboarding`},rest:{method:`POST`}}});export{p as CompleteOnboardingBaseInput,m as CompleteOnboardingBaseOutput,h as CompleteOnboardingBaseSpec,f as DeleteOnboardingDraftBaseSpec,d as DeleteOnboardingDraftOutput,u as GetOnboardingDraftBaseSpec,l as GetOnboardingDraftOutput,c as SaveOnboardingDraftBaseSpec,o as SaveOnboardingDraftInput,s as SaveOnboardingDraftOutput};
+import{defineCommand as e,defineQuery as t}from"./spec.js";import{OwnersEnum as n,StabilityEnum as r}from"./ownership.js";import{ScalarTypeEnum as i,SchemaModel as a}from"@lssm/lib.schema";const o=new a({name:`SaveOnboardingDraftInput`,description:`Input for saving onboarding draft`,fields:{data:{type:i.JSON(),isOptional:!1}}}),s=new a({name:`SaveOnboardingDraftOutput`,description:`Output for saving onboarding draft`,fields:{id:{type:i.ID(),isOptional:!1},organizationId:{type:i.ID(),isOptional:!1}}}),c=e({meta:{name:`base.onboarding.saveDraft`,version:1,stability:r.Beta,owners:[n.PlatformSigil],tags:[`onboarding`,`draft`],description:`Save or update onboarding draft for active organization`,goal:`Persist onboarding progress incrementally for resumption and safety`,context:`Auto-saves every few seconds during onboarding; enables users to leave and resume`},io:{input:o,output:s},policy:{auth:`user`,escalate:null},transport:{gql:{field:`saveOnboardingDraft`},rest:{method:`POST`}}}),l=new a({name:`GetOnboardingDraftOutput`,description:`Onboarding draft payload`,fields:{id:{type:i.ID(),isOptional:!0},organizationId:{type:i.ID(),isOptional:!0},data:{type:i.JSON(),isOptional:!0},createdAt:{type:i.DateTime(),isOptional:!0},updatedAt:{type:i.DateTime(),isOptional:!0}}}),u=t({meta:{name:`base.onboarding.getDraft`,version:1,stability:r.Beta,owners:[n.PlatformSigil],tags:[`onboarding`,`draft`],description:`Get onboarding draft for active organization`,goal:`Retrieve saved onboarding progress`,context:`Called on mount to restore in-progress onboarding`},io:{input:null,output:l},policy:{auth:`user`,escalate:null},transport:{gql:{field:`getOnboardingDraft`},rest:{method:`GET`}}}),d=new a({name:`DeleteOnboardingDraftOutput`,description:`Result of delete operation`,fields:{ok:{type:i.Boolean(),isOptional:!1}}}),f=e({meta:{name:`base.onboarding.deleteDraft`,version:1,stability:r.Beta,owners:[n.PlatformSigil],tags:[`onboarding`,`draft`],description:`Delete onboarding draft for active organization`,goal:`Clear draft after completion or if user wants to restart`,context:`Called after successful onboarding or explicit user reset`},io:{input:null,output:d},policy:{auth:`user`,escalate:null},transport:{gql:{field:`deleteOnboardingDraft`},rest:{method:`POST`}}}),p=new a({name:`CompleteOnboardingBaseInput`,description:`Input for completing onboarding`,fields:{data:{type:i.JSON(),isOptional:!1}}}),m=new a({name:`CompleteOnboardingBaseOutput`,description:`Result of onboarding completion`,fields:{success:{type:i.Boolean(),isOptional:!1},userId:{type:i.ID(),isOptional:!0},organizationId:{type:i.ID(),isOptional:!0}}}),h=e({meta:{name:`base.onboarding.complete`,version:1,stability:r.Beta,owners:[n.PlatformSigil],tags:[`onboarding`],description:`Complete onboarding and finalize user/organization setup`,goal:`Transition from draft to active profile`,context:`Validates all required fields, creates/updates entities, marks onboarding complete`},io:{input:p,output:m},policy:{auth:`user`,escalate:null},transport:{gql:{field:`completeOnboarding`},rest:{method:`POST`}}});export{p as CompleteOnboardingBaseInput,m as CompleteOnboardingBaseOutput,h as CompleteOnboardingBaseSpec,f as DeleteOnboardingDraftBaseSpec,d as DeleteOnboardingDraftOutput,u as GetOnboardingDraftBaseSpec,l as GetOnboardingDraftOutput,c as SaveOnboardingDraftBaseSpec,o as SaveOnboardingDraftInput,s as SaveOnboardingDraftOutput};

package/dist/openapi.js

@@ -0,0 +1 @@
+import{defaultRestPath as e,jsonSchemaForSpec as t}from"./jsonschema.js";function n(e,t){return`${e.replace(/\./g,`_`)}_v${t}`}function r(e,t,r){return`${e}_${n(t,r)}`}function i(e,t){return(t??(e===`query`?`GET`:`POST`)).toLowerCase()}function a(t){let n=t.transport?.rest?.path??e(t.meta.name,t.meta.version);return n.startsWith(`/`)?n:`/${n}`}function o(e,o={}){let s=e.listSpecs().filter(e=>e.meta.kind===`command`||e.meta.kind===`query`).slice().sort((e,t)=>{let n=e.meta.name.localeCompare(t.meta.name);return n===0?e.meta.version-t.meta.version:n}),c={openapi:`3.1.0`,info:{title:o.title??`ContractSpec API`,version:o.version??`0.0.0`,...o.description?{description:o.description}:{}},...o.servers?{servers:o.servers}:{},paths:{},components:{schemas:{}}};for(let e of s){let o=t(e),s=i(e.meta.kind,e.transport?.rest?.method),l=a(e),u=n(e.meta.name,e.meta.version),d=c.paths[l]??={},f={operationId:u,summary:e.meta.description??e.meta.name,description:e.meta.description,tags:e.meta.tags??[],"x-contractspec":{name:e.meta.name,version:e.meta.version,kind:e.meta.kind},responses:{}};if(o.input){let t=r(`Input`,e.meta.name,e.meta.version);c.components.schemas[t]=o.input,f.requestBody={required:!0,content:{"application/json":{schema:{$ref:`#/components/schemas/${t}`}}}}}let p={};if(o.output){let t=r(`Output`,e.meta.name,e.meta.version);c.components.schemas[t]=o.output,p[200]={description:`OK`,content:{"application/json":{schema:{$ref:`#/components/schemas/${t}`}}}}}else p[200]={description:`OK`};f.responses=p,d[s]=f}return c}export{o as openApiForRegistry};

package/dist/openbanking/docs/openbanking.docblock.js

@@ -0,0 +1,109 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.openbanking`,title:`Open Banking (Powens) Overview`,summary:`The Pocket Family Office vertical now supports read-only open banking capabilities powered by Powens. This doc summarises the contract surfaces, canonical data models, workflows, telemetry, and guardrails introduced to make Powens a first-class integration.`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/openbanking`,tags:[`tech`,`contracts`,`openbanking`],body:`# Open Banking (Powens) Overview
+
+The Pocket Family Office vertical now supports read-only open banking capabilities powered by Powens. This doc summarises the contract surfaces, canonical data models, workflows, telemetry, and guardrails introduced to make Powens a first-class integration.
+
+## Integration Spec
+
+Powens is registered under \`openbanking.powens\` with category \`open-banking\` and currently supports the BYOK ownership mode. The spec exposes three read-only capabilities:
+
+- \`openbanking.accounts.read\`
+- \`openbanking.transactions.read\`
+- \`openbanking.balances.read\`
+
+Configuration and secrets are separated:
+
+| Config Field | Description |
+| --- | --- |
+| \`environment\` | Powens environment (\`sandbox\` \\| \`production\`) |
+| \`baseUrl?\` | Optional API base URL override |
+| \`region?\` | Optional Powens region identifier |
+| \`pollingIntervalMs?\` | Optional custom sync cadence |
+
+| Secret Field | Description |
+| --- | --- |
+| \`clientId\` | Powens OAuth client identifier |
+| \`clientSecret\` | Powens OAuth client secret |
+| \`apiKey?\` | Optional supplemental Powens API key |
+| \`webhookSecret?\` | Optional webhook signing secret |
+
+## Canonical Data Models
+
+Canonical schemas live in \`@lssm/lib.contracts/integrations/openbanking/models\`:
+
+- \`BankAccountRecord\` – account metadata (institution, IBAN/BIC, masked numbers, balances, sync timestamps)
+- \`BankTransactionRecord\` – transaction ledger (amounts, categories, counterparty, status)
+- \`AccountBalanceRecord\` – balance snapshots per account and balance type
+
+These schemas power the vertical contracts and workflows, ensuring downstream features never use raw Powens payloads directly.
+
+## Provider Implementation
+
+\`PowensOpenBankingProvider\` wraps \`PowensClient\` which handles OAuth token management, request retries, and error mapping. The provider maps Powens payloads to the canonical interfaces exported from \`integrations/providers/openbanking\`.
+
+Factory support lives in \`IntegrationProviderFactory.createOpenBankingProvider\`, which validates configuration, loads BYOK secrets, and instantiates the provider.
+
+## Contracts
+
+Command/query contracts exist under \`integrations/openbanking/contracts\`:
+
+- \`openbanking.accounts.sync\` & \`openbanking.accounts.list\`
+- \`openbanking.transactions.sync\` & \`openbanking.transactions.list\`
+- \`openbanking.balances.refresh\` & \`openbanking.balances.get\`
+
+The Pocket Family Office bundle also exposes \`pfo.openbanking.generate-overview\`, which aggregates balances and transactions into a derived knowledge document.
+
+## Workflows
+
+New workflow specs (all requiring the \`primaryOpenBanking\` slot) orchestrate the sync flows:
+
+- \`pfo.workflow.sync-openbanking-accounts\`
+- \`pfo.workflow.sync-openbanking-transactions\`
+- \`pfo.workflow.refresh-openbanking-balances\`
+- \`pfo.workflow.generate-openbanking-overview\`
+
+Each workflow runs against the Powens provider, persists canonical records, and emits telemetry.
+
+## Knowledge & LLM Exposure
+
+Raw Powens payloads are never stored in knowledge spaces. Instead, \`knowledge.financial-overview\` captures derived summaries (cashflow, category breakdowns, balance trends) produced by \`pfo.openbanking.generate-overview\`. The space is \`operational\` category with 180-day retention and automation write access.
+
+When exposing data to LLMs or analytics:
+
+- Use derived summaries only.
+- Redact PII fields using \`redactOpenBankingTelemetryPayload\`.
+- Never emit IBANs, unmasked account numbers, or counterparty detail in telemetry/logs.
+
+## Telemetry
+
+Telemetry constants live in \`integrations/openbanking/telemetry\`. Key events:
+
+- \`openbanking.accounts.synced\`
+- \`openbanking.transactions.synced\`
+- \`openbanking.balances.refreshed\`
+- \`openbanking.overview.generated\`
+
+All events require tenant/app/blueprint/config metadata, and sensitive properties are flagged to avoid accidental leakage.
+
+## Guardrails
+
+\`ensurePrimaryOpenBankingIntegration\` verifies \`primaryOpenBanking\` is bound and healthy before workflows proceed. Runtime pre-flight checks already block workflows when the connection is disconnected or in error status.
+
+## Blueprint & Tenant Defaults
+
+\`pocketFamilyOfficeBlueprint\` now includes:
+
+- \`primaryOpenBanking\` slot (required, BYOK)
+- \`openbanking.*.read\` capabilities enabled by default
+- Workflow bindings for the new sync flows
+
+Sample tenant bindings (\`tenant.sample.ts\`) reference \`conn-powens-primary\` and bind the new knowledge space.
+
+---
+
+Follow this doc when extending open banking support (e.g., adding payment initiation, additional providers, or expanded analytics) to keep the integration consistent and audited.
+
+
+
+
+
+`}];e(t);export{t as tech_contracts_openbanking_DocBlocks};

package/dist/policy/docs/policy.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.policy`,title:`PolicySpec & PolicyEngine`,summary:"`PolicySpec` gives a declarative, typed home for access-control logic covering:",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/policy`,tags:[`tech`,`contracts`,`policy`],body:"# PolicySpec & PolicyEngine\n\n## Purpose\n\n`PolicySpec` gives a declarative, typed home for access-control logic covering:\n- **Who** can perform an action (ABAC/ReBAC style rules)\n- **What** they can access (resources + optional field-level overrides)\n- **When** special conditions apply (contextual expressions)\n- **How** PII should be handled (consent/retention hints)\n\n`PolicyEngine` evaluates one or more policies and returns an `allow`/`deny` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (`SpecRegistry` → `ctx.decide`).\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/policy/spec.ts`\n- Runtime evaluation: `packages/libs/contracts/src/policy/engine.ts`\n- Tests: `packages/.../policy/engine.test.ts`\n\n## `PolicySpec`\n\n```ts\nexport interface PolicySpec {\n  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }\n  rules: PolicyRule[];       // allow/deny rules for actions\n  fieldPolicies?: FieldPolicyRule[];\n  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };\n  relationships?: RelationshipDefinition[];\n  consents?: ConsentDefinition[];\n  rateLimits?: RateLimitDefinition[];\n  opa?: { package: string; decision?: string };\n}\n```\n\n- `PolicyRule`\n  - `effect`: `'allow' | 'deny'`\n  - `actions`: e.g., `['read', 'write', 'delete']` (string namespace is flexible)\n  - `subject`: `{ roles?: string[]; attributes?: { attr: matcher } }`\n  - `resource`: `{ type: string; fields?: string[]; attributes?: {...} }`\n  - `relationships`: `{ relation, objectId?, objectType? }[]` → ReBAC checks (use `objectId: '$resource'` to target the current resource)\n  - `requiresConsent`: `['consent_id']` → references spec-level consent definitions\n  - `flags`: feature flags that must be enabled (`DecisionContext.flags`)\n  - `rateLimit`: string reference to `rateLimits` entry or inline object `{ rpm, key?, windowSeconds?, burst? }`\n  - `escalate`: `'human_review' | null` to indicate manual approval\n  - `conditions`: optional expression snippets evaluated against `{ subject, resource, context }`\n- `FieldPolicyRule`\n  - `field`: dot-path string (e.g., `contact.email`)\n  - `actions`: subset of `['read', 'write']`\n  - Same `subject` / `resource` / `conditions` shape\n  - Useful for redacting specific fields, even when the global action is allowed\n- `RelationshipDefinition`\n  - Canonical tuples for relationship graph (`subjectType`, `relation`, `objectType`, `transitive?`)\n- `ConsentDefinition`\n  - `{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }`\n- `RateLimitDefinition`\n  - `{ id, rpm, key?, windowSeconds?, burst? }`\n- `PolicyRef`\n  - `{ name: string; version: number }` → attach to contract specs / workflows\n\n## Registry\n\n```ts\nconst registry = new PolicyRegistry();\nregistry.register(CorePolicySpec);\nconst spec = registry.get('core.default', 1);\n```\n\nGuarantees uniqueness per `(name, version)` and exposes helpers to resolve highest versions.\n\n## Engine\n\n```ts\nconst engine = new PolicyEngine(policyRegistry);\n\nconst decision = engine.decide({\n  action: 'read',\n  subject: { roles: ['admin'] },\n  resource: { type: 'resident', fields: ['contact.email'] },\n  policies: [{ name: 'core.default', version: 1 }],\n});\n/*\n{\n  effect: 'allow',\n  reason: 'core.default',\n  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],\n  pii: { fields: ['contact.email'], consentRequired: true }\n}\n*/\n```\n\n- First matching **deny** wins; otherwise the first **allow** is returned.\n- Field policies are aggregated across referenced policies:\n  - Later denies override earlier allows for a given field.\n  - Returned as `fieldDecisions` to simplify downstream masking.\n- PII metadata is surfaced when defined to help adapt logging/telemetry.\n\n### Expression Support\n\nConditions accept small JS snippets (e.g., `subject.attributes.orgId === context.orgId`). The engine runs them in a constrained scope (`subject`, `resource`, `context`) without access to global state.\n\n### ReBAC & Relationships\n\n- Provide relationship tuples via `PolicySpec.relationships` for documentation/validation.\n- Reference them inside rules with `relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]`.\n- The execution context must populate `subject.relationships` (`[{ relation, object, objectType }]`) for the engine to evaluate ReBAC guards.\n\n### Consent & Rate Limits\n\n- Declare reusable consent definitions under `consents`. Rules list the IDs they require; if a user session lacks the consent (`DecisionContext.consents`), the engine returns `effect: 'deny'` with `reason: 'consent_required'` and enumerates missing consents.\n- Attach rate limits either inline or via `rateLimits` references. When a rule matches, the engine surfaces `{ rpm, key, windowSeconds?, burst? }` so callers can feed it to shared limiters.\n\n### OPA Adapter\n\n- `OPAPolicyAdapter` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (`effect`, `reason`, `fieldDecisions`, `requiredConsents`).\n- Use when migrating to OPA policies or running defense-in-depth: call `engine.decide()`, then pass the preliminary decision to `adapter.evaluate(...)`. The adapter marks merged decisions with `evaluatedBy: 'opa'`.\n- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.\n\n## Contract Integration\n\n`ContractSpec.policy` now supports:\n\n```ts\npolicy: {\n  auth: 'anonymous' | 'user' | 'admin';\n  ...\n  policies?: PolicyRef[];                // policies evaluated before execution\n  fieldPolicies?: {                      // field hints (read/write) per policy\n    field: string;\n    actions: ('read' | 'write')[];\n    policy?: PolicyRef;\n  }[];\n}\n```\n\nAdapters can resolve refs through a shared `PolicyEngine` and populate `ctx.decide` so `SpecRegistry.execute` benefits from centralized enforcement.\n\n## Authoring Guidelines\n\n1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).\n2. Keep rule scopes narrow (per feature/operation) and compose multiple `PolicyRef`s when necessary.\n3. Store PII field lists here to avoid duplication across logs/telemetry.\n4. Use explicit rule reasons for auditability and better developer feedback.\n5. Treat versioning seriously; bump `meta.version` whenever behavior changes.\n\n## Future Enhancements\n\n- Richer expression language (composable predicates, time-based conditions).\n- Multi-tenant relationship graph services (store/resolve relationships at scale).\n- Tooling that auto-generates docs/tests for policies referenced in specs.\n\n"}];e(t);export{t as tech_contracts_policy_DocBlocks};

package/dist/presentations/docs/presentations-conventions.docblock.js

@@ -0,0 +1,8 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.presentations-conventions`,title:`Presentations Conventions (A11y & i18n)`,summary:"- Always provide `meta.description` (≥ 3 chars) — used by a11y/docs/agents.",kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/presentations-conventions`,tags:[`tech`,`contracts`,`presentations-conventions`],body:`## Presentations Conventions (A11y & i18n)
+
+- Always provide \`meta.description\` (≥ 3 chars) — used by a11y/docs/agents.
+- Prefer source = BlockNote for rich guides; use component key for interactive flows.
+- i18n strings belong in host apps; descriptors carry keys/defaults only.
+- Target selection: include only what you intend to support to avoid drift.
+- PII: declare JSON-like paths under \`policy.pii\`; engine redacts in outputs.
+`}];e(t);export{t as tech_contracts_presentations_conventions_DocBlocks};

package/dist/presentations.js

@@ -1 +1 @@
-import e from"zod";function t(e){return`${e.meta.name}.v${e.meta.version}`}var n=class{items=new Map;register(e){let n=t(e);if(this.items.has(n))throw Error(`Duplicate presentation ${n}`);return this.items.set(n,e),this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.items.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}};function r(t){let n={meta:{name:t.meta.name,version:t.meta.version,stability:t.meta.stability??`stable`,tags:t.meta.tags??[],description:t.meta.description??``},kind:t.content.kind};return t.content.kind===`web_component`?{...n,framework:t.content.framework,componentKey:t.content.componentKey,props:e.toJSONSchema(t.content.props.getZod())}:t.content.kind===`markdown`?{...n,content:t.content.content,resourceUri:t.content.resourceUri}:{...n,mimeType:t.content.mimeType,model:e.toJSONSchema(t.content.model.getZod())}}export{n as PresentationRegistry,r as jsonSchemaForPresentation};
+import e from"zod";function t(e){return`${e.meta.name}.v${e.meta.version}`}var n=class{items=new Map;constructor(e){e&&e.forEach(e=>this.register(e))}register(e){let n=t(e);if(this.items.has(n))throw Error(`Duplicate presentation ${n}`);return this.items.set(n,e),this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.items.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}};function r(t){let n={meta:{name:t.meta.name,version:t.meta.version,stability:t.meta.stability??`stable`,tags:t.meta.tags??[],description:t.meta.description??``},kind:t.content.kind};return t.content.kind===`web_component`?{...n,framework:t.content.framework,componentKey:t.content.componentKey,props:e.toJSONSchema(t.content.props.getZod())}:t.content.kind===`markdown`?{...n,content:t.content.content,resourceUri:t.content.resourceUri}:{...n,mimeType:t.content.mimeType,model:e.toJSONSchema(t.content.model.getZod())}}export{n as PresentationRegistry,r as jsonSchemaForPresentation};

package/dist/presentations.v2.js

@@ -1 +1,7 @@
-var e=class{renderers=new Map;validators=[];register(e){let t=this.renderers.get(e.target)??[];return t.push(e),this.renderers.set(e.target,t),this}addValidator(e){return this.validators.push(e),this}async render(e,t,n){if(!t.targets.includes(e))throw Error(`Target ${e} not declared for ${t.meta.name}.v${t.meta.version}`);for(let r of this.validators)await r.validate(t,e,n);let r=this.renderers.get(e)??[];for(let e of r)try{return await e.render(t,n)}catch{}throw Error(`No renderer available for ${e}`)}};function t(){let t=new e,n=(e,t)=>{let n=JSON.parse(JSON.stringify(t)),r=e.policy?.pii??[],i=(e,t)=>{let n=t.replace(/^\//,``).replace(/\[(\d+)\]/g,`.$1`).split(`.`).filter(Boolean),r=e;for(let e=0;e<n.length-1;e++){let t=n[e];if(r&&typeof r==`object`&&t in r)r=r[t];else return}let i=n[n.length-1];r&&typeof r==`object`&&i&&i in r&&(r[i]=`[REDACTED]`)};for(let e of r)i(n,e);return n};return t.register({target:`markdown`,async render(e){if(e.source.type===`blocknotejs`){let t=n(e,{text:typeof e.source.docJson==`string`?e.source.docJson:JSON.stringify(e.source.docJson)});return{mimeType:`text/markdown`,body:String(t.text)}}if(e.source.type===`component`)return{mimeType:`text/markdown`,body:`${`# ${e.meta.name} v${e.meta.version}`}${e.meta.description?`\n\n${e.meta.description}`:``}${e.meta.tags&&e.meta.tags.length?`\n\nTags: ${e.meta.tags.join(`, `)}`:``}${e.meta.owners&&e.meta.owners.length?`\n\nOwners: ${e.meta.owners.join(`, `)}`:``}${`\n\nComponent: \`${e.source.componentKey}\``}${e.policy?.pii?.length?`\n\nRedacted paths: ${e.policy.pii.map(e=>`\`${e}\``).join(`, `)}`:``}`};throw Error(`unsupported`)}}),t.register({target:`application/json`,async render(e){let t=n(e,{meta:e.meta,source:e.source});return{mimeType:`application/json`,body:JSON.stringify(t,null,2)}}}),t.register({target:`application/xml`,async render(e){let t=n(e,{meta:e.meta,source:e.source});return{mimeType:`application/xml`,body:`<presentation name="${e.meta.name}" version="${e.meta.version}"><json>${encodeURIComponent(JSON.stringify(t))}</json></presentation>`}}}),t}function n(e){return e.register({target:`react`,async render(e){if(e.source.type===`component`){let t=e.source.props&&e.source.props.getZod().safeParse({}).success?{}:void 0;return{kind:`react_component`,componentKey:e.source.componentKey,props:t}}return{kind:`blocknotejs`,docJson:e.source.docJson,blockConfig:e.source.blockConfig}}}),e}function r(e){return e.addValidator({validate(e){if(!e.meta.description||e.meta.description.length<3)throw Error(`Presentation ${e.meta.name}.v${e.meta.version} missing meta.description`)}}),e}export{e as TransformEngine,t as createDefaultTransformEngine,r as registerBasicValidation,n as registerDefaultReactRenderer};
+import{schemaToMarkdown as e}from"./schema-to-markdown.js";import t from"react";import n from"turndown";const r=new n;function i(e){let t=e.text??``;return!e.marks||e.marks.length===0?t:e.marks.reduce((e,t)=>{switch(t.type){case`bold`:return`**${e}**`;case`italic`:return`*${e}*`;case`underline`:return`__${e}__`;case`strike`:return`~~${e}~~`;case`code`:return`\`${e}\``;case`link`:{let n=t.attrs?.href??``;return n?`[${e}](${n})`:e}default:return e}},t)}function a(e){return e?.length?e.map(e=>s(e)).join(``):``}function o(e,t=!1){if(!e?.length)return``;let n=1;return e.map(e=>{let r=a(e.content??[]);return r?`${t?`${n++}. `:`- `}${r}`:``}).filter(Boolean).join(`
+`)}function s(e){switch(e.type){case`doc`:return a(e.content);case`paragraph`:{let t=a(e.content);return t.trim().length?t:``}case`heading`:{let t=Math.min(Math.max(e.attrs?.level??1,1),6);return`${`#`.repeat(t)} ${a(e.content)}`.trim()}case`bullet_list`:return o(e.content,!1);case`ordered_list`:return o(e.content,!0);case`list_item`:return a(e.content);case`blockquote`:return a(e.content).split(`
+`).map(e=>`> ${e}`).join(`
+`);case`code_block`:{let t=a(e.content);return t?`\`\`\`\n${t}\n\`\`\``:``}case`horizontal_rule`:return`---`;case`hard_break`:return`
+`;case`text`:return i(e);default:return e.text?i(e):``}}function c(e){if(typeof e==`string`)return e;if(e&&typeof e==`object`&&`html`in e){let t=String(e.html);return r.turndown(t)}let t=e;if(t?.type===`doc`||t?.content)return(t.content??[]).map(e=>s(e)).filter(Boolean).join(`
+
+`).trim();try{return JSON.stringify(e,null,2)}catch{return String(e)}}var l=class{renderers=new Map;validators=[];register(e){let t=this.renderers.get(e.target)??[];return t.push(e),this.renderers.set(e.target,t),this}prependRegister(e){let t=this.renderers.get(e.target)??[];return t.unshift(e),this.renderers.set(e.target,t),this}addValidator(e){return this.validators.push(e),this}async render(e,t,n){if(!t.targets.includes(e))throw Error(`Target ${e} not declared for ${t.meta.name}.v${t.meta.version}`);for(let r of this.validators)await r.validate(t,e,n);let r=this.renderers.get(e)??[];for(let e of r)try{return await e.render(t,n)}catch{}throw Error(`No renderer available for ${e}`)}};function u(){let t=new l,n=(e,t)=>{let n=JSON.parse(JSON.stringify(t)),r=e.policy?.pii??[],i=(e,t)=>{let n=t.replace(/^\//,``).replace(/\[(\d+)\]/g,`.$1`).split(`.`).filter(Boolean),r=e;for(let e=0;e<n.length-1;e++){let t=n[e];if(r&&typeof r==`object`&&t in r)r=r[t];else return}let i=n[n.length-1];r&&typeof r==`object`&&i&&i in r&&(r[i]=`[REDACTED]`)};for(let e of r)i(n,e);return n};return t.register({target:`markdown`,async render(t,r){let i=r?.data;if(!i&&r?.fetchData&&(i=await r.fetchData()),t.source.type===`component`&&t.source.props&&i!==void 0){let n=Array.isArray(i),r=!n&&typeof i==`object`&&!!i&&!Object.values(i).some(e=>Array.isArray(e)||typeof e==`object`&&!!e);if(n||r)return{mimeType:`text/markdown`,body:e(t.source.props,i,{title:t.meta.description??t.meta.name,description:`${t.meta.name} v${t.meta.version}`})};throw Error(`Complex data structure for ${t.meta.name} - expecting custom renderer`)}if(t.source.type===`blocknotejs`){let e=n(t,{text:c(t.source.docJson)});return{mimeType:`text/markdown`,body:String(e.text)}}if(t.source.type===`component`&&i!==void 0)throw Error(`No schema (source.props) available for ${t.meta.name} - expecting custom renderer`);if(t.source.type===`component`)return{mimeType:`text/markdown`,body:`${`# ${t.meta.name} v${t.meta.version}`}${t.meta.description?`\n\n${t.meta.description}`:``}${t.meta.tags&&t.meta.tags.length?`\n\nTags: ${t.meta.tags.join(`, `)}`:``}${t.meta.owners&&t.meta.owners.length?`\n\nOwners: ${t.meta.owners.join(`, `)}`:``}${`\n\nComponent: \`${t.source.componentKey}\``}${t.policy?.pii?.length?`\n\nRedacted paths: ${t.policy.pii.map(e=>`\`${e}\``).join(`, `)}`:``}`};throw Error(`unsupported`)}}),t.register({target:`application/json`,async render(e){let t=n(e,{meta:e.meta,source:e.source});return{mimeType:`application/json`,body:JSON.stringify(t,null,2)}}}),t.register({target:`application/xml`,async render(e){let t=n(e,{meta:e.meta,source:e.source});return{mimeType:`application/xml`,body:`<presentation name="${e.meta.name}" version="${e.meta.version}"><json>${encodeURIComponent(JSON.stringify(t))}</json></presentation>`}}}),t}function d(e){return e.register({target:`react`,async render(e){if(e.source.type===`component`){let t=e.source.props&&e.source.props.getZod().safeParse({}).success?{}:void 0;return{kind:`react_component`,componentKey:e.source.componentKey,props:t}}return{kind:`blocknotejs`,docJson:e.source.docJson,blockConfig:e.source.blockConfig}}}),e}function f(e){return e.addValidator({validate(e){if(!e.meta.description||e.meta.description.length<3)throw Error(`Presentation ${e.meta.name}.v${e.meta.version} missing meta.description`)}}),e}function p(e,r){let i=new n({headingStyle:`atx`,codeBlockStyle:`fenced`,bulletListMarker:`-`});return i.addRule(`link`,{filter:`a`,replacement:(e,t)=>{let n=t.href;return n&&e?`[${e}](${n})`:e||``}}),e.prependRegister({target:`markdown`,async render(e,n){if(e.source.type!==`component`)throw Error(`React-to-markdown renderer only handles component presentations`);let{renderToStaticMarkup:a}=await import(`react-dom/server`),o=r[e.source.componentKey];if(!o)throw Error(`Component ${e.source.componentKey} not found in componentMap`);let s;try{s=a(t.createElement(o,e.source.props?{}:void 0))}catch(t){throw Error(`Failed to render component ${e.source.componentKey}: ${t instanceof Error?t.message:`Unknown error`}`)}let c;try{c=i.turndown(s)}catch(e){throw Error(`Failed to convert HTML to markdown: ${e instanceof Error?e.message:`Unknown error`}`)}return e.policy?.pii&&e.policy.pii.length>0?{mimeType:`text/markdown`,body:c.replace(/\[REDACTED\]/g,`[REDACTED]`)}:{mimeType:`text/markdown`,body:c}}}),e}export{l as TransformEngine,u as createDefaultTransformEngine,f as registerBasicValidation,d as registerDefaultReactRenderer,p as registerReactToMarkdownRenderer};

package/dist/prompt.js

@@ -1 +1 @@
-import{z as e}from"zod";function t(e){return e}export{t as definePrompt};
+import"zod";function e(e){return e}export{e as definePrompt};

package/dist/promptRegistry.js

@@ -1 +1 @@
-import{z as e}from"zod";var t=class{prompts=new Map;register(e){let t=`${e.meta.name}.v${e.meta.version}`;if(this.prompts.has(t))throw Error(`Duplicate prompt ${t}`);return this.prompts.set(t,e),this}list(){return[...this.prompts.values()]}get(e,t){if(t!=null)return this.prompts.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.prompts.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}};export{t as PromptRegistry};
+import"zod";var e=class{prompts=new Map;register(e){let t=`${e.meta.name}.v${e.meta.version}`;if(this.prompts.has(t))throw Error(`Duplicate prompt ${t}`);return this.prompts.set(t,e),this}list(){return[...this.prompts.values()]}get(e,t){if(t!=null)return this.prompts.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.prompts.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}};export{e as PromptRegistry};

package/dist/regenerator/docs/regenerator.docblock.js

@@ -0,0 +1,184 @@
+import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{id:`docs.tech.contracts.regenerator`,title:`Regenerator Service`,summary:`The Regenerator daemon observes telemetry, error, and behavior streams, then suggests spec-level changes (not code patches) that can be reviewed and applied through the App Studio.`,kind:`reference`,visibility:`public`,route:`/docs/tech/contracts/regenerator`,tags:[`tech`,`contracts`,`regenerator`],body:`## Regenerator Service
+
+The Regenerator daemon observes telemetry, error, and behavior streams, then suggests spec-level changes (not code patches) that can be reviewed and applied through the App Studio.
+
+- Runtime entrypoint: \`packages/libs/contracts/src/regenerator/service.ts\`
+- Types/interfaces: \`packages/libs/contracts/src/regenerator/types.ts\`
+- Signal adapters: \`packages/libs/contracts/src/regenerator/adapters.ts\`
+
+### Architecture
+
+\`\`\`text
+Signal Adapters ──► RegeneratorService ──► Rules ──► ProposalSink
+          ▲                                       │
+          │                                       ▼
+     Telemetry / Errors / Behavior         Spec change proposals
+\`\`\`
+
+1. **Signal adapters** pull batches of telemetry, error logs, or behavior metrics for each \`RegenerationContext\`.
+2. \`RegeneratorService\` schedules polling (\`resolveAppConfig\` + \`composeAppConfig\` provide context).
+3. **Rules** implement domain heuristics and emit \`SpecChangeProposal\` objects.
+4. **Proposal sinks** persist or forward proposals for human review.
+
+### Key types
+
+\`\`\`ts
+export interface RegenerationContext {
+  id: string;
+  blueprint: AppBlueprintSpec;
+  tenantConfig: TenantAppConfig;
+  resolved: ResolvedAppConfig;
+}
+
+export interface RegeneratorRule {
+  id: string;
+  description: string;
+  evaluate(
+    context: RegenerationContext,
+    signals: RegeneratorSignal[]
+  ): Promise<SpecChangeProposal[]>;
+}
+
+export interface SpecChangeProposal {
+  id: string;
+  title: string;
+  summary: string;
+  confidence: 'low' | 'medium' | 'high';
+  target: ProposalTarget;
+  actions: ProposalAction[];
+  blockers?: ProposalBlocker[];
+  signalIds: string[];
+  createdAt: Date;
+}
+\`\`\`
+
+- Signals are normalized envelopes: telemetry (\`count\`, anomaly score), errors, and behavior trends.
+- Proposals reference blueprint or tenant specs via \`ProposalTarget\`.
+- Actions encode what the automation should perform (update blueprint, run tests/migrations, trigger regeneration).
+
+### Providing signals
+
+Implement \`TelemetrySignalProvider\`, \`ErrorSignalProvider\`, or \`BehaviorSignalProvider\`:
+
+\`\`\`ts
+const service = new RegeneratorService({
+  contexts,
+  adapters: {
+    telemetry: new PosthogTelemetryAdapter(),
+    errors: new SentryErrorAdapter(),
+  },
+  rules: [new WorkflowFailureRule(), new DataViewUsageRule()],
+  sink: new ProposalQueueSink(),
+  pollIntervalMs: 60_000,
+});
+\`\`\`
+
+Adapters receive the full \`RegenerationContext\`, making it easy to scope queries per tenant/app.
+
+### Authoring rules
+
+Rules focus on signals → proposals:
+
+\`\`\`ts
+class WorkflowFailureRule implements RegeneratorRule {
+  id = 'workflow-failure';
+  description = 'Suggest splitting workflows that exceed failure thresholds';
+
+  async evaluate(context, signals) {
+    const failures = signals.filter(
+      (signal) =>
+        signal.type === 'telemetry' &&
+        signal.signal.eventName === 'workflow.failure' &&
+        signal.signal.count >= 10
+    );
+
+    if (failures.length === 0) return [];
+
+    return [
+      {
+        id: \`\${this.id}-\${context.id}\`,
+        title: 'Split onboarding workflow',
+        summary: 'Step 3 fails consistently; propose dedicated remediation branch.',
+        confidence: 'medium',
+        rationale: ['Failure count ≥ 10 within last window'],
+        target: {
+          specType: 'workflow',
+          reference: { name: 'onboarding.workflow', version: 1 },
+          tenantScoped: true,
+        },
+        actions: [
+          { kind: 'update_tenant_config', summary: 'Add alternate fallback path' },
+          { kind: 'run_tests', tests: ['workflows/onboarding.spec.ts'] },
+        ],
+        signalIds: failures.map((f) => f.signal.eventName),
+        createdAt: new Date(),
+      },
+    ];
+  }
+}
+\`\`\`
+
+### Reviewing proposals
+
+Proposals flow to a \`ProposalSink\` (queue, DB, messaging bus). The Studio will surface:
+
+1. Signal evidence (telemetry counts, error metadata)
+2. Proposed spec diffs and required actions (tests/migrations)
+3. Approval workflow (approve → write spec diff → run automation)
+
+### CLI driver
+
+Run the regenerator daemon from the CLI:
+
+\`\`\`bash
+bunx contracts regenerator ./app.blueprint.ts ./tenant.config.ts ./regenerator.rules.ts auto \\
+  --executor ./regenerator.executor.ts \\
+  --poll-interval 60000 \\
+  --batch-duration 300000 \\
+  --dry-run
+\`\`\`
+
+- Expects modules exporting default \`AppBlueprintSpec\`, \`TenantAppConfig\`, and one or more \`RegenerationRule\`s.
+- Pass a sink module path, or use the special \`auto\` value with \`--executor <module>\` to instantiate an \`ExecutorProposalSink\`.
+- Executor modules can export a \`ProposalExecutor\` instance, a factory, or a plain dependency object for the executor constructor. Optional exports: \`sinkOptions\`, \`logger\`, \`onResult\`, \`dryRun\`.
+- Optionally provide \`--contexts ./contexts.ts\` to load custom context arrays (advanced multi-tenant scenarios).
+- Use \`--dry-run\` to preview actions without mutating specs/configs, and \`--once\` for CI smoke tests.
+
+### Proposal executor
+
+\`ProposalExecutor\` + \`ExecutorProposalSink\` orchestrate follow-up actions once a proposal is approved:
+
+- Interfaces for applying blueprint or tenant-config updates (\`BlueprintUpdater\`, \`TenantConfigUpdater\`).
+- Hooks for running contract tests and migrations (\`TestExecutor\`, \`MigrationExecutor\`).
+- Optional trigger to recompose the runtime (\`RegenerationTrigger\`).
+- Built-in \`dryRun\` mode to preview outcomes.
+- Pluggable result logging/forwarding via \`ExecutorSinkOptions\`.
+
+\`\`\`ts
+import {
+  ProposalExecutor,
+  ExecutorProposalSink,
+} from '@lssm/lib.contracts/regenerator';
+
+const executor = new ProposalExecutor({
+  tenantConfigUpdater,
+  testExecutor,
+  migrationExecutor,
+  regenerationTrigger,
+});
+
+const sink = new ExecutorProposalSink(executor, {
+  dryRun: false,
+  onResult: ({ result }) => console.log(result.status),
+});
+\`\`\`
+
+Execution results include per-action status (\`success\`, \`skipped\`, \`failed\`) plus aggregated proposal status (\`success\`, \`partial\`, \`failed\`). Missing dependencies mark actions as \`skipped\`, making it easy to plug into partial automation flows today and extend later.
+
+### Next steps
+
+- Build adapters for existing telemetry/error providers.
+- Encode canonical rules (workflow failure, feature under-use, high latency).
+- Integrate with App Studio proposal inbox and automate acceptance (write spec diff, run tests, queue migrations).
+
+`}];e(t);export{t as tech_contracts_regenerator_DocBlocks};

package/dist/registry.js

@@ -1 +1 @@
-import{eventKey as e}from"./events.js";import{isEmitDeclRef as t}from"./spec.js";function n(e,t){return`${e}.v${t}`}var r=class{specs=new Map;handlers=new Map;register(e){let t=n(e.meta.name,e.meta.version);if(this.specs.has(t))throw Error(`Duplicate spec ${t}`);return this.specs.set(t,e),this}bind(e,t){let r=n(e.meta.name,e.meta.version);if(!this.specs.has(r))throw Error(`Cannot bind; spec not found: ${r}`);if(this.handlers.has(r))throw Error(`Handler already bound for ${r}`);return this.handlers.set(r,t),this}getSpec(e,t){if(t!=null)return this.specs.get(n(e,t));let r,i=-1/0;for(let[t,n]of this.specs.entries())t.startsWith(`${e}.v`)&&n.meta.version>i&&(i=n.meta.version,r=n);return r}getHandler(e,t){let r=this.getSpec(e,t);if(r)return this.handlers.get(n(r.meta.name,r.meta.version))}listSpecs(){return[...this.specs.values()]}listBound(){let e=[];for(let[t,n]of this.specs.entries()){let r=this.handlers.get(t);r&&e.push({spec:n,handler:r})}return e}async execute(r,i,a,o){let s=this.getSpec(r,i);if(!s)throw Error(`Spec not found for ${r}${i?`.v${i}`:``}`);let c=await o.specVariantResolver?.resolve({name:s.meta.name,version:s.meta.version,kind:s.meta.kind},o)??s,l=n(c.meta.name,c.meta.version),u=this.handlers.get(l);if(!u){let e=n(s.meta.name,s.meta.version);u=this.handlers.get(e),l=e}if(!u)throw Error(`No handler bound for ${l}`);let d=c.io.input?.getZod().parse(a);if(o.decide){let[e,t]=c.meta.name.split(`.`),n=await o.decide({service:e,command:t,version:c.meta.version,actor:o.actor??`anonymous`,channel:o.channel,roles:o.roles,organizationId:o.organizationId,userId:o.userId,flags:[]});if(n.effect===`deny`)throw Error(`PolicyDenied: ${c.meta.name}.v${c.meta.version}`);if(n.rateLimit&&o.rateLimit){let e=n.rateLimit.key??`default`,t=n.rateLimit.rpm??60;await o.rateLimit(e,1,t)}}let f=new Map;if(c.sideEffects?.emits)for(let e of c.sideEffects.emits)t(e)?f.set(`${e.ref.name}.v${e.ref.version}`,e.ref.payload):f.set(`${e.name}.v${e.version}`,e.payload);let p=async(t,r,i)=>{let a=e(t,r),s=f.get(a);if(!s)throw Error(`UndeclaredEvent: ${a} not allowed by ${n(c.meta.name,c.meta.version)}`);let l=s.getZod().parse(i);await o.eventPublisher?.({name:t,version:r,payload:l,traceId:o.traceId})};o.appConfig&&(o.branding||=o.appConfig.branding,o.translation?o.translation.config||(o.translation={...o.translation,config:o.appConfig.translation}):o.translation={config:o.appConfig.translation});let m=o.telemetry,h=async(e,t)=>{if(!(!m||!e?.event))try{let n=e.properties?.(t)??{};await m.track(e.event.name,e.event.version??1,n,{tenantId:o.organizationId??void 0,organizationId:o.organizationId,userId:o.userId,actor:o.actor,channel:o.channel,metadata:o.traceId?{traceId:o.traceId}:void 0})}catch{}},g;try{g=await u(d,{...o,__emitGuard__:p})}catch(e){throw c.telemetry?.failure&&await h(c.telemetry.failure,{input:d??a,error:e}),e}c.telemetry?.success&&await h(c.telemetry.success,{input:d??a,output:g});let _=c.io.output;return _?.getZod?_.getZod().parse(g):g}};export{r as SpecRegistry,n as opKey};
+import{eventKey as e}from"./events.js";import{isEmitDeclRef as t}from"./spec.js";import{defaultDocRegistry as n,docId as r,registerDocBlocks as i}from"./docs/registry.js";function a(e,t){return`${e}.v${t}`}var o=class{specs=new Map;handlers=new Map;register(e){let t=a(e.meta.name,e.meta.version);if(this.specs.has(t))throw Error(`Duplicate spec ${t}`);return this.specs.set(t,e),this}bind(e,t){let n=a(e.meta.name,e.meta.version);if(!this.specs.has(n))throw Error(`Cannot bind; spec not found: ${n}`);if(this.handlers.has(n))throw Error(`Handler already bound for ${n}`);return this.handlers.set(n,t),this}getSpec(e,t){if(t!=null)return this.specs.get(a(e,t));let n,r=-1/0;for(let[t,i]of this.specs.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}getHandler(e,t){let n=this.getSpec(e,t);if(n)return this.handlers.get(a(n.meta.name,n.meta.version))}listSpecs(){return[...this.specs.values()]}listBound(){let e=[];for(let[t,n]of this.specs.entries()){let r=this.handlers.get(t);r&&e.push({spec:n,handler:r})}return e}async execute(n,r,i,o){let s=this.getSpec(n,r);if(!s)throw Error(`Spec not found for ${n}${r?`.v${r}`:``}`);let c=await o.specVariantResolver?.resolve({name:s.meta.name,version:s.meta.version,kind:s.meta.kind},o)??s,l=a(c.meta.name,c.meta.version),u=this.handlers.get(l);if(!u){let e=a(s.meta.name,s.meta.version);u=this.handlers.get(e),l=e}if(!u)throw Error(`No handler bound for ${l}`);let d=c.io.input?.getZod().parse(i);if(o.decide){let[e,t]=c.meta.name.split(`.`),n=await o.decide({service:e,command:t,version:c.meta.version,actor:o.actor??`anonymous`,channel:o.channel,roles:o.roles,organizationId:o.organizationId,userId:o.userId,flags:[]});if(n.effect===`deny`)throw Error(`PolicyDenied: ${c.meta.name}.v${c.meta.version}`);if(n.rateLimit&&o.rateLimit){let e=n.rateLimit.key??`default`,t=n.rateLimit.rpm??60;await o.rateLimit(e,1,t)}}let f=new Map;if(c.sideEffects?.emits)for(let e of c.sideEffects.emits)t(e)?f.set(`${e.ref.name}.v${e.ref.version}`,e.ref.payload):f.set(`${e.name}.v${e.version}`,e.payload);let p=async(t,n,r)=>{let i=e(t,n),s=f.get(i);if(!s)throw Error(`UndeclaredEvent: ${i} not allowed by ${a(c.meta.name,c.meta.version)}`);let l=s.getZod().parse(r);await o.eventPublisher?.({name:t,version:n,payload:l,traceId:o.traceId})};o.appConfig&&(o.branding||=o.appConfig.branding,o.translation?o.translation.config||(o.translation={...o.translation,config:o.appConfig.translation}):o.translation={config:o.appConfig.translation});let m=o.telemetry,h=async(e,t)=>{if(!(!m||!e?.event))try{let n=e.properties?.(t)??{};await m.track(e.event.name,e.event.version??1,n,{tenantId:o.organizationId??void 0,organizationId:o.organizationId,userId:o.userId,actor:o.actor,channel:o.channel,metadata:o.traceId?{traceId:o.traceId}:void 0})}catch{}},g;try{g=await u(d,{...o,__emitGuard__:p})}catch(e){throw c.telemetry?.failure&&await h(c.telemetry.failure,{input:d??i,error:e}),e}c.telemetry?.success&&await h(c.telemetry.success,{input:d??i,output:g});let _=c.io.output;return _?.getZod?_.getZod().parse(g):g}};export{o as SpecRegistry,n as defaultDocRegistry,r as docId,a as opKey,i as registerDocBlocks};

package/dist/resources.js

@@ -1 +1 @@
-import{z as e}from"zod";function t(e){return e}var n=class{templates=[];register(e){return this.templates.push(e),this}listTemplates(){return[...this.templates]}match(e){for(let t of this.templates){let n=RegExp(`^`+t.meta.uriTemplate.replace(/\{[^}]+\}/g,`([^/]+)`)+`$`),r=e.match(n);if(!r)continue;let i=[...t.meta.uriTemplate.matchAll(/\{([^}]+)\}/g)].map(e=>e[1]),a={};return i.forEach((e,t)=>a[e]=decodeURIComponent(r[t+1])),{tmpl:t,params:a}}}};function r(e,t){return{kind:`resource_ref`,uriTemplate:e,varName:t.varName??`id`,graphQLType:t.graphQLType,many:t.many}}function i(e){let t=e;return!!t&&t.kind===`resource_ref`&&typeof t.uriTemplate==`string`}export{n as ResourceRegistry,t as defineResourceTemplate,i as isResourceRef,r as resourceRef};
+import"zod";function e(e){return e}var t=class{templates=[];register(e){return this.templates.push(e),this}listTemplates(){return[...this.templates]}match(e){for(let t of this.templates){let n=RegExp(`^`+t.meta.uriTemplate.replace(/\{[^}]+\}/g,`([^/]+)`)+`$`),r=e.match(n);if(!r)continue;let i=[...t.meta.uriTemplate.matchAll(/\{([^}]+)\}/g)].map(e=>e[1]),a={};return i.forEach((e,t)=>a[e]=decodeURIComponent(r[t+1])),{tmpl:t,params:a}}}};function n(e,t){return{kind:`resource_ref`,uriTemplate:e,varName:t.varName??`id`,graphQLType:t.graphQLType,many:t.many}}function r(e){let t=e;return!!t&&t.kind===`resource_ref`&&typeof t.uriTemplate==`string`}export{t as ResourceRegistry,e as defineResourceTemplate,r as isResourceRef,n as resourceRef};