@lssm/lib.contracts-spec 17.3.2

package/dist/node/knowledge/knowledge.capability.js

@@ -0,0 +1 @@
+import{defineCapability as t}from"../capabilities/index.js";import{StabilityEnum as e}from"../ownership.js";export const KnowledgeCapability=t({meta:{key:"knowledge",version:"1.0.0",kind:"data",stability:e.Experimental,description:"Knowledge base and content management capability",owners:["@platform.content"],tags:["knowledge","content","data"]}});

package/dist/node/knowledge/knowledge.feature.js

@@ -0,0 +1 @@
+import{defineFeature as e}from"../features/index.js";export const KnowledgeFeature=e({meta:{key:"platform.knowledge",version:"1.0.0",title:"Knowledge Sources",description:"Manage knowledge source bindings for ingestion (e.g., Notion, uploads)",domain:"platform",owners:["@platform.knowledge"],tags:["knowledge","sources","platform","ingestion"],stability:"experimental"},operations:[{key:"knowledge.source.create",version:"1.0.0"},{key:"knowledge.source.update",version:"1.0.0"},{key:"knowledge.source.delete",version:"1.0.0"},{key:"knowledge.source.list",version:"1.0.0"},{key:"knowledge.source.triggerSync",version:"1.0.0"},{key:"knowledge.mutation.evaluateGovernance",version:"1.0.0"}],events:[],presentations:[],opToPresentation:[],presentationsTargets:[],capabilities:{provides:[{key:"knowledge",version:"1.0.0"}],requires:[{key:"identity",version:"1.0.0"}]}});

package/dist/node/knowledge/operation-models.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as t}from"@lssm/lib.schema";export const KnowledgeSyncSchedule=new t({name:"KnowledgeSyncSchedule",fields:{enabled:{type:e.Boolean(),isOptional:!1},cron:{type:e.String_unsecure(),isOptional:!0},intervalMs:{type:e.Int_unsecure(),isOptional:!0}}}),KnowledgeSourceRecord=new t({name:"KnowledgeSourceRecord",fields:{id:{type:e.ID(),isOptional:!1},tenantId:{type:e.ID(),isOptional:!1},spaceKey:{type:e.NonEmptyString(),isOptional:!1},spaceVersion:{type:e.String_unsecure(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!1},sourceType:{type:e.String_unsecure(),isOptional:!1},syncSchedule:{type:KnowledgeSyncSchedule,isOptional:!0},lastSyncStatus:{type:e.String_unsecure(),isOptional:!0},lastSyncAt:{type:e.DateTime(),isOptional:!0},itemsProcessed:{type:e.Int_unsecure(),isOptional:!0},createdAt:{type:e.DateTime(),isOptional:!0},updatedAt:{type:e.DateTime(),isOptional:!0}}}),CreateKnowledgeSourceInput=new t({name:"CreateKnowledgeSourceInput",fields:{tenantId:{type:e.ID(),isOptional:!1},spaceKey:{type:e.NonEmptyString(),isOptional:!1},spaceVersion:{type:e.String_unsecure(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!1},sourceType:{type:e.NonEmptyString(),isOptional:!1},config:{type:e.JSONObject(),isOptional:!1},syncSchedule:{type:KnowledgeSyncSchedule,isOptional:!0}}}),UpdateKnowledgeSourceInput=new t({name:"UpdateKnowledgeSourceInput",fields:{sourceId:{type:e.ID(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!0},config:{type:e.JSONObject(),isOptional:!0},syncSchedule:{type:KnowledgeSyncSchedule,isOptional:!0}}}),DeleteKnowledgeSourceInput=new t({name:"DeleteKnowledgeSourceInput",fields:{sourceId:{type:e.ID(),isOptional:!1}}}),DeleteKnowledgeSourceOutput=new t({name:"DeleteKnowledgeSourceOutput",fields:{success:{type:e.Boolean(),isOptional:!1}}}),ListKnowledgeSourcesInput=new t({name:"ListKnowledgeSourcesInput",fields:{tenantId:{type:e.ID(),isOptional:!1},spaceKey:{type:e.NonEmptyString(),isOptional:!0}}}),ListKnowledgeSourcesOutput=new t({name:"ListKnowledgeSourcesOutput",fields:{sources:{type:KnowledgeSourceRecord,isOptional:!1,isArray:!0}}}),TriggerKnowledgeSyncInput=new t({name:"TriggerKnowledgeSyncInput",fields:{sourceId:{type:e.ID(),isOptional:!1}}}),TriggerKnowledgeSyncOutput=new t({name:"TriggerKnowledgeSyncOutput",fields:{success:{type:e.Boolean(),isOptional:!1},itemsProcessed:{type:e.Int_unsecure(),isOptional:!0},error:{type:e.String_unsecure(),isOptional:!0}}}),EvaluateKnowledgeMutationGovernanceInput=new t({name:"EvaluateKnowledgeMutationGovernanceInput",fields:{operation:{type:e.NonEmptyString(),isOptional:!1},sourceId:{type:e.ID(),isOptional:!0},dryRun:{type:e.Boolean(),isOptional:!0},requiresApproval:{type:e.Boolean(),isOptional:!0},outboundSend:{type:e.Boolean(),isOptional:!0},idempotencyKey:{type:e.String_unsecure(),isOptional:!0},auditEvidenceRef:{type:e.String_unsecure(),isOptional:!0},approvalRefIds:{type:e.String_unsecure(),isOptional:!0,isArray:!0},outboundSendGateStatus:{type:e.String_unsecure(),isOptional:!0}}}),EvaluateKnowledgeMutationGovernanceOutput=new t({name:"EvaluateKnowledgeMutationGovernanceOutput",fields:{status:{type:e.String_unsecure(),isOptional:!1},allowed:{type:e.Boolean(),isOptional:!1},dryRun:{type:e.Boolean(),isOptional:!1},reasons:{type:e.String_unsecure(),isOptional:!1,isArray:!0},requiredEvidence:{type:e.String_unsecure(),isOptional:!1,isArray:!0},auditEvidenceRef:{type:e.String_unsecure(),isOptional:!0},idempotencyKey:{type:e.String_unsecure(),isOptional:!0},decidedAt:{type:e.DateTime(),isOptional:!1}}});

package/dist/node/knowledge/operations.js

@@ -0,0 +1 @@
+import{defineCommand as e,defineQuery as n}from"../operations/index.js";import{CreateKnowledgeSourceInput as r,DeleteKnowledgeSourceInput as i,DeleteKnowledgeSourceOutput as a,EvaluateKnowledgeMutationGovernanceInput as l,EvaluateKnowledgeMutationGovernanceOutput as s,KnowledgeSourceRecord as o,ListKnowledgeSourcesInput as d,ListKnowledgeSourcesOutput as g,TriggerKnowledgeSyncInput as u,TriggerKnowledgeSyncOutput as c,UpdateKnowledgeSourceInput as p}from"./operation-models.js";export const CreateKnowledgeSource=e({meta:{key:"knowledge.source.create",title:"Create Knowledge Source",version:"1.0.0",description:"Create a knowledge source binding for a tenant.",goal:"Onboard a new knowledge ingestion source such as Notion or uploads.",context:"Used by Ops and App Studio to configure knowledge ingestion per tenant and space.",owners:["@platform.knowledge"],tags:["knowledge","sources"],stability:"experimental"},io:{input:r,output:o},policy:{auth:"admin",policies:[{key:"platform.knowledge.manage",version:"1.0.0"}]}}),UpdateKnowledgeSource=e({meta:{key:"knowledge.source.update",title:"Update Knowledge Source",version:"1.0.0",description:"Update metadata or configuration for a knowledge source.",goal:"Allow rotation of credentials, sync schedules, and labels.",context:"Supports editing how a tenant ingests knowledge (e.g., toggling sync cadence).",owners:["@platform.knowledge"],tags:["knowledge","sources"],stability:"experimental"},io:{input:p,output:o},policy:{auth:"admin",policies:[{key:"platform.knowledge.manage",version:"1.0.0"}]}}),DeleteKnowledgeSource=e({meta:{key:"knowledge.source.delete",title:"Delete Knowledge Source",version:"1.0.0",description:"Delete a knowledge source binding for a tenant.",goal:"Remove obsolete or compromised knowledge ingestion paths.",context:"Ensures ephemeral or external sources can be removed cleanly without leaving residual bindings.",owners:["@platform.knowledge"],tags:["knowledge","sources"],stability:"experimental"},io:{input:i,output:a},policy:{auth:"admin",policies:[{key:"platform.knowledge.manage",version:"1.0.0"}]}}),ListKnowledgeSources=n({meta:{key:"knowledge.source.list",title:"List Knowledge Sources",version:"1.0.0",description:"List knowledge sources configured for a tenant.",goal:"Provide visibility into knowledge ingest configuration and schedules.",context:"Used by App Studio and Ops flows to surface knowledge sources and their health.",owners:["@platform.knowledge"],tags:["knowledge","sources"],stability:"experimental"},io:{input:d,output:g},policy:{auth:"admin",policies:[{key:"platform.knowledge.read",version:"1.0.0"}]}}),TriggerKnowledgeSourceSync=e({meta:{key:"knowledge.source.triggerSync",title:"Trigger Knowledge Source Sync",version:"1.0.0",description:"Trigger an immediate sync for a knowledge source.",goal:"Support manual or automated sync retries for knowledge ingestion.",context:"Invoked by Ops tooling or monitors when knowledge content must be refreshed or reprocessed.",owners:["@platform.knowledge"],tags:["knowledge","sources"],stability:"experimental"},io:{input:u,output:c},policy:{auth:"admin",policies:[{key:"platform.knowledge.manage",version:"1.0.0"}]}}),EvaluateKnowledgeMutationGovernance=e({meta:{key:"knowledge.mutation.evaluateGovernance",title:"Evaluate Knowledge Mutation Governance",version:"1.0.0",description:"Evaluate dry-run, approval, idempotency, audit, and outbound-send evidence before mutating an external knowledge provider.",goal:"Create an auditable decision envelope for governed knowledge mutations.",context:"Used by runtime flows before sending email, changing Drive permissions, or mutating provider-backed knowledge sources.",owners:["@platform.knowledge"],tags:["knowledge","governance","mutation"],stability:"experimental"},io:{input:l,output:s},policy:{auth:"admin",policies:[{key:"platform.knowledge.manage",version:"1.0.0"}]}}),knowledgeContracts={CreateKnowledgeSource,UpdateKnowledgeSource,DeleteKnowledgeSource,ListKnowledgeSources,TriggerKnowledgeSourceSync,EvaluateKnowledgeMutationGovernance};export function registerKnowledgeContracts(t){return t.register(CreateKnowledgeSource).register(UpdateKnowledgeSource).register(DeleteKnowledgeSource).register(ListKnowledgeSources).register(TriggerKnowledgeSourceSync).register(EvaluateKnowledgeMutationGovernance)}

package/dist/node/knowledge/registry.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as t}from"../registry.js";export class KnowledgeSpaceRegistry extends t{constructor(e){super("knowledge-space",e)}getByCategory(e){return this.list().filter((o)=>o.meta.category===e)}}

package/dist/node/knowledge/source.js

@@ -0,0 +1 @@
+export function isKnowledgeSourceAvailableForBinding(e,n,t){if(e.tombstone)return!1;if(e.meta.spaceKey!==n.spaceKey)return!1;if(n.spaceVersion!=null&&e.meta.spaceVersion!==n.spaceVersion)return!1;if(n.source?.sourceIds?.length&&!n.source.sourceIds.includes(e.meta.id))return!1;if(n.source?.integrationConnectionId!=null&&e.meta.integrationConnectionId!==n.source.integrationConnectionId)return!1;if(e.meta.environment!=null&&e.meta.environment!==t.environment)return!1;if(e.access?.visibility==="shared"||e.access?.visibility==="global"){if(!n.source?.allowShared)return!1;return Boolean(e.access.policyRef||e.access.aclSnapshotRef)}return e.meta.tenantId===t.tenantId}

package/dist/node/knowledge/spaces/email-threads.js

@@ -0,0 +1 @@
+import{StabilityEnum as t}from"../../ownership.js";export const emailThreadsKnowledgeSpace={meta:{key:"knowledge.email-threads",version:"1.0.0",category:"operational",title:"Operational Email Threads",description:"Indexed copies of operational email threads used for support, onboarding, and workflows.",domain:"operations",owners:["platform.operations"],tags:["email","operations"],stability:t.Beta},retention:{ttlDays:365},access:{policy:{key:"knowledge.access.email-threads",version:"1.0.0"},trustLevel:"medium",automationWritable:!0},indexing:{embeddingModel:"mistral-embed",chunkSize:600,vectorDbIntegration:"vectordb.qdrant"},description:"Operational email threads synchronized from Gmail to support automations and contextual assistance."};export function registerEmailThreadsKnowledgeSpace(e){return e.register(emailThreadsKnowledgeSpace)}

package/dist/node/knowledge/spaces/financial-docs.js

@@ -0,0 +1 @@
+import{StabilityEnum as n}from"../../ownership.js";export const financialDocsKnowledgeSpace={meta:{key:"knowledge.financial-docs",version:"1.0.0",category:"canonical",title:"Household Financial Documents",description:"Invoices, bills, and contracts powering Pocket Family Office financial automation.",domain:"finance",owners:["platform.finance"],tags:["finance","documents"],stability:n.Beta},retention:{ttlDays:null},access:{policy:{key:"knowledge.access.financial-docs",version:"1.0.0"},trustLevel:"high",automationWritable:!0},indexing:{embeddingModel:"mistral-embed",chunkSize:700,vectorDbIntegration:"vectordb.qdrant"},description:"Normalized financial documents enabling bill pay automation, reminders, and summaries."};export function registerFinancialDocsKnowledgeSpace(e){return e.register(financialDocsKnowledgeSpace)}

package/dist/node/knowledge/spaces/financial-overview.js

@@ -0,0 +1 @@
+import{StabilityEnum as a}from"../../ownership.js";export const financialOverviewKnowledgeSpace={meta:{key:"knowledge.financial-overview",version:"1.0.0",category:"operational",title:"Derived Financial Summaries",description:"Aggregated cashflow summaries, category breakdowns, and balance trends derived from open banking data.",domain:"finance",owners:["platform.finance"],tags:["open-banking","summaries","cashflow"],stability:a.Experimental},retention:{ttlDays:180},access:{policy:{key:"knowledge.access.financial-overview",version:"1.0.0"},trustLevel:"medium",automationWritable:!0},indexing:{embeddingModel:"mistral-embed",chunkSize:600,vectorDbIntegration:"vectordb.qdrant"},description:"Derived knowledge space containing weekly/monthly cashflow rollups and account health summaries. Raw transactions are excluded to respect privacy guardrails."};export function registerFinancialOverviewKnowledgeSpace(e){return e.register(financialOverviewKnowledgeSpace)}

package/dist/node/knowledge/spaces/index.js

@@ -0,0 +1 @@
+export*from"./email-threads.js";export*from"./financial-docs.js";export*from"./financial-overview.js";export*from"./product-canon.js";export*from"./support-faq.js";export*from"./uploaded-docs.js";

package/dist/node/knowledge/spaces/product-canon.js

@@ -0,0 +1 @@
+import{StabilityEnum as t}from"../../ownership.js";export const productCanonKnowledgeSpace={meta:{key:"knowledge.product-canon",version:"1.0.0",category:"canonical",title:"Product Canon Knowledge Space",description:"Authoritative product knowledge covering strategy, roadmap, and delivery canon.",domain:"product",owners:["platform.product"],tags:["knowledge","product"],stability:t.Stable},retention:{ttlDays:null},access:{policy:{key:"knowledge.access.product-canon",version:"1.0.0"},trustLevel:"high",automationWritable:!1},indexing:{embeddingModel:"text-embedding-3-large",chunkSize:800,vectorDbIntegration:"vectordb.qdrant"},description:"Single source of truth for product canon, principles, and strategic narratives."};export function registerProductCanonKnowledgeSpace(e){return e.register(productCanonKnowledgeSpace)}

package/dist/node/knowledge/spaces/support-faq.js

@@ -0,0 +1 @@
+import{StabilityEnum as t}from"../../ownership.js";export const supportFaqKnowledgeSpace={meta:{key:"knowledge.support-faq",version:"1.0.0",category:"operational",title:"Support & Success FAQ",description:"Operational knowledge base for customer support and success.",domain:"support",owners:["platform.support"],tags:["knowledge","support"],stability:t.Beta},retention:{ttlDays:365,archiveAfterDays:180},access:{policy:{key:"knowledge.access.support",version:"1.0.0"},trustLevel:"medium",automationWritable:!0},indexing:{embeddingModel:"text-embedding-3-small",chunkSize:700,vectorDbIntegration:"vectordb.qdrant"},description:"Operational FAQs, runbooks, and customer success playbooks augmented with automation updates."};export function registerSupportFaqKnowledgeSpace(e){return e.register(supportFaqKnowledgeSpace)}

package/dist/node/knowledge/spaces/uploaded-docs.js

@@ -0,0 +1 @@
+import{StabilityEnum as o}from"../../ownership.js";export const uploadedDocsKnowledgeSpace={meta:{key:"knowledge.uploaded-docs",version:"1.0.0",category:"external",title:"Uploaded Knowledge Assets",description:"Documents uploaded by households, including invoices, contracts, and reference files.",domain:"operations",owners:["platform.operations"],tags:["documents","storage"],stability:o.Beta},retention:{ttlDays:null},access:{policy:{key:"knowledge.access.uploaded-docs",version:"1.0.0"},trustLevel:"medium",automationWritable:!0},indexing:{embeddingModel:"mistral-embed",chunkSize:900,vectorDbIntegration:"vectordb.qdrant"},description:"User-provided documents normalized and embedded for retrieval augmented workflows."};export function registerUploadedDocsKnowledgeSpace(e){return e.register(uploadedDocsKnowledgeSpace)}

package/dist/node/knowledge/spec.d.js

@@ -0,0 +1 @@
+export{KnowledgeSpaceRegistry}from"./registry.js";

package/dist/node/knowledge/spec.js

@@ -0,0 +1,172 @@
+export{KnowledgeSpaceRegistry}from"./registry.js";export function makeKnowledgeSpaceKey(e){return`${e.key}.v${e.version}`}export const tech_contracts_knowledge_DocBlocks=[{id:"docs.tech.contracts.knowledge",title:"Knowledge Layer",summary:"The knowledge layer turns unstructured inputs (uploads, email threads,",kind:"reference",visibility:"public",route:"/docs/tech/contracts/knowledge",tags:["tech","contracts","knowledge"],body:`# Knowledge Layer
+
+The knowledge layer turns unstructured inputs (uploads, email threads,
+notes) into searchable context for agents and workflows. The Pocket
+Family Office vertical ships a minimal but production-ready stack that
+covers ingestion, indexing, querying, and guardrails.
+
+## Knowledge Spaces
+
+Knowledge is organised via \`KnowledgeSpaceSpec\` definitions under
+\`packages/libs/contracts-spec/src/knowledge/spaces\`:
+
+- \`knowledge.financial-docs\` – canonical invoices, bills, and contracts.
+- \`knowledge.email-threads\` – operational Gmail threads.
+- \`knowledge.support-faq\` / \`knowledge.product-canon\` – reusable shared
+  spaces available to any vertical.
+
+Each space defines:
+
+- Ownership metadata (domain, owners, stability tags).
+- Retention policy (TTL/archival).
+- Access policy (trust level, automation write permissions).
+- Indexing configuration (embedding model, chunk size, vector DB slot).
+
+## Sources & Bindings
+
+- \`KnowledgeSourceConfig\` records tenant-specific connections (bucket,
+  Gmail labels, sync cadence). Pocket Family Office provides sample
+  configs in \`knowledge/sources.sample.ts\`.
+- \`AppKnowledgeBinding\` associates spaces with workflows/agents and adds
+  per-tenant constraints (rate limits, scopes).
+
+Validation ensures that:
+
+- All referenced spaces exist in the registry.
+- At least one source is configured per binding.
+- External/ephemeral spaces trigger warnings for policy-sensitive flows.
+
+## Ingestion Pipeline
+
+Implemented in \`@lssm/lib.knowledge/ingestion\`:
+
+1. **DocumentProcessor** – pluggable MIME extractors producing
+   \`DocumentFragment\`s.
+2. **EmbeddingService** – batches fragments through an \`EmbeddingProvider\`
+   (Mistral in the reference implementation).
+3. **VectorIndexer** – upserts fragments into a \`VectorStoreProvider\`
+   (Qdrant in production, with in-memory implementations for tests) and
+   persists canonical \`payload.text\` content alongside fragment metadata
+   so retrieval and query flows can reuse indexed text directly.
+4. **Adapters**
+   - \`GmailIngestionAdapter\`: list threads → convert to raw documents →
+     index.
+   - \`StorageIngestionAdapter\`: fetch object from storage provider →
+     index.
+
+Background jobs (see \`@lssm/lib.jobs\`) orchestrate ingestion via
+Cloud Tasks / Pub/Sub or in-memory workers. Handlers:
+
+- \`storage-document-handler\` – resolves storage object + indexes.
+- \`gmail-sync-handler\` – syncs threads based on label/date filters.
+
+## Query Service
+
+\`KnowledgeQueryService\` performs retrieval-augmented generation:
+
+1. Embed the user query using the configured provider.
+2. Search the vector store for top-k matches.
+3. Compose prompts combining system instructions + indexed contextual
+   snippets from \`payload.text\` (falling back to legacy \`payload.content\`
+   when needed).
+4. Invoke the LLM provider (Mistral) and return the answer plus
+   references and token usage.
+
+The service is designed for tooling: workflows can execute it directly
+or through custom operations (see \`pfo.summary.generate\` contract).
+
+## Guardrails
+
+- Automation can only write to spaces where \`automationWritable\` is true.
+- Canonical spaces default to high trust; external/ephemeral spaces are
+  flagged during validation.
+- Provider-free knowledge flows must block stale runbook or low-confidence
+  evidence before action, and non-dry-run knowledge mutations require approval
+  or audit references before execution.
+- Telemetry captures query volumes per tenant + space.
+
+## Extending
+
+1. Define a new \`KnowledgeSpaceSpec\` with indexing/retention policies.
+2. Add sources pointing to storage providers or APIs.
+3. Register adapters if ingestion requires bespoke logic.
+4. Reference the space in blueprints (\`AppKnowledgeBinding\`) and update
+   workflows/agents accordingly.
+
+The Pocket Family Office tests (\`tests/pocket-family-office.test.ts\`)
+show how to wire the ingestion pipeline, index a document, and run an
+end-to-end knowledge query using in-memory providers.
+## Knowledge Spaces & Guardrails
+
+Knowledge surfaces (\`KnowledgeSpaceSpec\`) describe curated corpora that agents and workflows can consult. Tenant bindings (\`AppKnowledgeBinding\`) declare which spaces are active, who can use them, and optional usage constraints.
+
+### Binding recap
+
+- \`spaceKey\` / \`spaceVersion\`: pointer to the \`KnowledgeSpaceSpec\`
+- \`scope.workflows\` / \`scope.agents\`: explicit allow-lists for consumers
+- \`constraints.maxTokensPerQuery\` & \`constraints.maxQueriesPerMinute\`: throttling knobs for LLM-backed search
+- \`required\`: mark the binding as blocking (defaults to \`true\`)
+
+At runtime, \`ResolvedAppConfig.knowledge\` contains \`ResolvedKnowledge\` entries with the bound space, active sources, and the binding metadata above.
+
+### KnowledgeAccessGuard
+
+\`KnowledgeAccessGuard\` (\`@lssm/lib.knowledge/access/guard\`) centralises the access checks that must run before any workflow/agent reads or mutates a knowledge space.
+
+\`\`\`ts
+import { KnowledgeAccessGuard } from '@lssm/lib.knowledge/access/guard';
+
+const guard = new KnowledgeAccessGuard({
+  disallowWriteCategories: ['external', 'ephemeral'], // default
+  requireWorkflowBinding: true,
+  requireAgentBinding: false,
+});
+
+const result = guard.checkAccess(resolvedKnowledge, {
+  tenantId,
+  appId,
+  workflowName: 'order-processing',
+  operation: 'read', // or 'write' / 'search'
+}, resolvedAppConfig);
+
+if (!result.allowed) {
+  throw new Error(result.reason);
+}
+\`\`\`
+
+Key behaviours:
+
+- **Binding**: rejects access when the space is not present in the resolved tenant config.
+- **Category guardrails**: blocks writes to \`external\` and \`ephemeral\` spaces by default; allows reads but emits warnings for \`ephemeral\`.
+- **Workflow/agent scoping**: when \`requireWorkflowBinding\` or \`requireAgentBinding\` is enabled, only explicitly authorised consumers may access the space.
+
+Use the guard inside workflow operations or agent resolvers to guarantee multi-tenant isolation and honour data governance rules.
+
+## Agent memory tools and ephemeral spaces
+
+Ephemeral spaces (\`category: 'ephemeral'\`) are the canonical home for agent memory storage (scratchpads, session context, drafts). Agent memory tools (Anthropic \`memory_20250818\`, custom operation-backed) can use ephemeral spaces as storage when configured with \`memoryTools.spaceKey\`.
+
+### Enabling agent memory writes
+
+By default, \`KnowledgeAccessGuard\` blocks writes to ephemeral spaces (\`disallowWriteCategories: ['external', 'ephemeral']\`). To allow agent memory tools to write:
+
+1. Configure \`disallowWriteCategories: ['external']\` (allow ephemeral writes).
+2. Ensure \`AppKnowledgeBinding.scope.agents\` includes the agent key when using knowledge-backed storage.
+3. Set \`requireAgentBinding: true\` so only explicitly bound agents can write.
+
+See \`@lssm/lib.ai-agent\` memory tools and \`AgentMemoryStore\` for implementation details.
+`},{id:"docs.tech.contracts.knowledge-provider-backed",title:"Provider-backed knowledge",summary:"Provider-backed knowledge syncs Gmail and Google Drive through explicit provider delta and mutation governance evidence.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/knowledge-provider-backed",tags:["tech","contracts","knowledge","integrations"],body:`# Provider-backed knowledge
+
+Provider-backed knowledge starts from the same \`KnowledgeSpaceSpec\` and
+\`KnowledgeSourceConfig\` surfaces, then adds explicit provider delta and
+mutation governance evidence before runtime sync begins.
+
+Gmail and Google Drive ingestion should persist \`ProviderDeltaSyncState\` per
+source so leases, cursors, webhook channel expiry, provider event IDs,
+dedupe/idempotency keys, replay checkpoints, and tombstones survive retries.
+
+External mutations should route through
+\`knowledge.mutation.evaluateGovernance\` or
+\`@lssm/lib.knowledge/governance\` so dry-runs, approval refs,
+idempotency keys, audit evidence, and outbound-send gates are recorded before
+provider writes happen.`}];

package/dist/node/llm/exporters.js

@@ -0,0 +1,9 @@
+import{jsonSchemaForSpec as a}from"../jsonschema.js";import{isEmitDeclRef as l}from"../operations/index.js";const r={format:"full",includeSchemas:!0,includeScenarios:!0,includeExamples:!0,includePolicy:!0,includeSideEffects:!0},c={...r,includeRelatedSpecs:!0,includeRelatedEvents:!0,includeRelatedPresentations:!0,includeRelatedVisualizations:!0,includeRelatedVisualScenarios:!0};export function operationSpecToContextMarkdown(e){const n=e.meta,t=[];t.push(`# ${n.key} (v${n.version})`);t.push("");t.push(`> ${n.description}`);t.push("");t.push(`**Type:** ${n.kind} | **Stability:** ${n.stability}`);t.push("");t.push("## Goal");t.push("");t.push(n.goal);t.push("");t.push("## Context");t.push("");t.push(n.context);t.push("");if(e.acceptance?.scenarios?.length){t.push("## Acceptance Criteria");t.push("");for(const p of e.acceptance.scenarios){t.push(`### ${p.key}`);t.push("");t.push("**Given:**");for(const s of p.given)t.push(`- ${s}`);t.push("");t.push("**When:**");for(const s of p.when)t.push(`- ${s}`);t.push("");t.push("**Then:**");for(const s of p.then)t.push(`- ${s}`);t.push("")}}return t.join(`
+`)}export function operationSpecToFullMarkdown(e,n={}){const t={...r,...n},p=e.meta,s=[];s.push(`# ${p.key}.v${p.version}`);s.push("");s.push(`> ${p.description}`);s.push("");s.push("## Metadata");s.push("");s.push("| Field | Value |");s.push("|-------|-------|");s.push(`| Kind | ${p.kind} |`);s.push(`| Stability | ${p.stability} |`);s.push(`| Owners | ${p.owners.join(", ")} |`);s.push(`| Tags | ${p.tags.join(", ")} |`);s.push("");s.push("## Goal");s.push("");s.push(p.goal);s.push("");s.push("## Context");s.push("");s.push(p.context);s.push("");if(t.includeSchemas){s.push("## Input/Output");s.push("");if(e.io.input){s.push("### Input Schema");s.push("");s.push("```json");try{const i=a(e);s.push(JSON.stringify(i.input??{},null,2))}catch{s.push("// Schema generation not available")}s.push("```");s.push("")}s.push("### Output Schema");s.push("");s.push("```json");try{const i=a(e);s.push(JSON.stringify(i.output??{},null,2))}catch{s.push("// Schema generation not available")}s.push("```");s.push("");if(e.io.errors&&Object.keys(e.io.errors).length){s.push("### Error Codes");s.push("");s.push("| Code | HTTP | Description | When |");s.push("|------|------|-------------|------|");for(const[i,o]of Object.entries(e.io.errors))s.push(`| \`${i}\` | ${o.http??400} | ${o.description} | ${o.when} |`);s.push("")}}if(t.includePolicy){s.push("## Policy");s.push("");s.push(`- **Auth Required:** ${e.policy.auth}`);s.push(`- **Idempotent:** ${e.policy.idempotent??p.kind==="query"}`);if(e.policy.rateLimit)s.push(`- **Rate Limit:** ${e.policy.rateLimit.rpm} rpm per ${e.policy.rateLimit.key}`);if(e.policy.flags?.length)s.push(`- **Feature Flags:** ${e.policy.flags.join(", ")}`);if(e.policy.pii?.length)s.push(`- **PII Fields:** ${e.policy.pii.join(", ")}`);if(e.policy.escalate)s.push(`- **Escalation:** ${e.policy.escalate}`);s.push("")}if(t.includeSideEffects&&e.sideEffects){if(e.sideEffects.emits?.length){s.push("## Events Emitted");s.push("");for(const i of e.sideEffects.emits)if(l(i))s.push(`- \`${i.ref.key}.v${i.ref.version}\` — ${i.when}`);else s.push(`- \`${i.key}.v${i.version}\` — ${i.when}`);s.push("")}if(e.sideEffects.analytics?.length){s.push("## Analytics Events");s.push("");for(const i of e.sideEffects.analytics)s.push(`- ${i}`);s.push("")}}if(t.includeScenarios&&e.acceptance?.scenarios?.length){s.push("## Acceptance Scenarios");s.push("");for(const i of e.acceptance.scenarios){s.push(`### ${i.key}`);s.push("");s.push("**Given:**");for(const o of i.given)s.push(`- ${o}`);s.push("");s.push("**When:**");for(const o of i.when)s.push(`- ${o}`);s.push("");s.push("**Then:**");for(const o of i.then)s.push(`- ${o}`);s.push("")}}if(t.includeExamples&&e.acceptance?.examples?.length){s.push("## Examples");s.push("");for(const i of e.acceptance.examples){s.push(`### ${i.key}`);s.push("");s.push("**Input:**");s.push("```json");s.push(JSON.stringify(i.input,null,2));s.push("```");s.push("");s.push("**Output:**");s.push("```json");s.push(JSON.stringify(i.output,null,2));s.push("```");s.push("")}}if(e.transport){s.push("## Transport Configuration");s.push("");if(e.transport.rest)s.push(`- **REST:** ${e.transport.rest.method??"POST"} ${e.transport.rest.path??"auto"}`);if(e.transport.gql)s.push(`- **GraphQL:** ${e.transport.gql.field??"auto"}`);if(e.transport.mcp)s.push(`- **MCP Tool:** ${e.transport.mcp.toolName??"auto"}`);s.push("")}return s.join(`
+`)}export function operationSpecToAgentPrompt(e,n){const t=n?.taskType??"implement",p=e.meta,s=[],i={implement:"Implement",test:"Write tests for",refactor:"Refactor",review:"Review"}[t];s.push(`# Task: ${i} ${p.key}.v${p.version}`);s.push("");s.push("## Context");s.push("");s.push(`You are working on a ContractSpec-driven codebase. This spec defines a ${p.kind} operation.`);s.push("");s.push(`**Goal:** ${p.goal}`);s.push("");s.push(`**Background:** ${p.context}`);s.push("");s.push("## Specification");s.push("");s.push(operationSpecToFullMarkdown(e));s.push("");s.push("## Instructions");s.push("");if(t==="implement"){s.push("Implement this specification following these requirements:");s.push("");s.push("1. **Type Safety**: Use TypeScript with strict typing. No `any` types.");s.push("2. **Input Validation**: Validate input against the schema before processing.");s.push("3. **Error Handling**: Implement all error cases defined in the spec.");s.push("4. **Events**: Emit events as specified in sideEffects.emits.");s.push("5. **Policy**: Respect auth, rate limits, and feature flags.");s.push("6. **Idempotency**: "+(e.policy.idempotent?"This operation MUST be idempotent.":"This operation may have side effects."));s.push("");if(e.policy.pii?.length){s.push("**PII Handling**: The following fields contain PII and must be handled carefully:");for(const o of e.policy.pii)s.push(`- ${o}`);s.push("")}}else if(t==="test"){s.push("Write comprehensive tests for this specification:");s.push("");s.push("1. Test all acceptance scenarios defined in the spec.");s.push("2. Test all error cases with appropriate assertions.");s.push("3. Test edge cases and boundary conditions.");s.push("4. Verify events are emitted correctly.");s.push('5. Use descriptive test names following the pattern: "should [behavior] when [condition]"');s.push("")}else if(t==="refactor"){s.push("Refactor this implementation while preserving all behavior:");s.push("");s.push("1. Maintain compliance with the specification.");s.push("2. Improve code clarity and maintainability.");s.push("3. Reduce complexity where possible.");s.push("4. Ensure all existing tests still pass.");s.push("")}else if(t==="review"){s.push("Review this implementation against the specification:");s.push("");s.push("1. Verify input/output types match the schema.");s.push("2. Check all error cases are handled.");s.push("3. Verify events are emitted as specified.");s.push("4. Check policy compliance (auth, rate limits).");s.push("5. Report any deviations from the spec.");s.push("")}if(n?.existingCode){s.push("## Existing Code");s.push("");s.push("```typescript");s.push(n.existingCode);s.push("```");s.push("")}s.push("## Expected Output");s.push("");if(t==="implement"||t==="refactor"){s.push("Provide a complete TypeScript implementation. Include:");s.push("- Type definitions for input/output");s.push("- Handler function with proper error handling");s.push("- JSDoc comments explaining the implementation")}else if(t==="test")s.push("Provide a complete test file using the testing framework available (prefer Vitest).");else if(t==="review"){s.push("Provide a structured review with:");s.push("- Compliance status (pass/fail for each requirement)");s.push("- Issues found with severity (error/warning/info)");s.push("- Suggestions for improvement")}s.push("");return s.join(`
+`)}export function featureToMarkdown(e,n,t={}){const p={...c,...t},s=e.meta,i=[];i.push(`# Feature: ${s.title??s.key}`);i.push("");if(s.description){i.push(`> ${s.description}`);i.push("")}i.push("## Overview");i.push("");i.push(`- **Key:** \`${s.key}\``);i.push(`- **Stability:** ${s.stability}`);i.push(`- **Owners:** ${s.owners.join(", ")}`);if(s.tags?.length)i.push(`- **Tags:** ${s.tags.join(", ")}`);i.push("");if(e.operations?.length){i.push("## Operations");i.push("");i.push("| Name | Version | Type |");i.push("|------|---------|------|");for(const o of e.operations){const h=n?.specs?.get(o.key,o.version)?.meta.kind??"unknown";i.push(`| ${o.key} | v${o.version} | ${h} |`)}i.push("");if(p.includeRelatedSpecs&&n?.specs){i.push("### Operation Details");i.push("");for(const o of e.operations){const u=n.specs.get(o.key,o.version);if(u){i.push("---");i.push("");i.push(operationSpecToFullMarkdown(u,p))}}}}if(e.events?.length){i.push("## Events");i.push("");i.push("| Name | Version |");i.push("|------|---------|");for(const o of e.events)i.push(`| ${o.key} | v${o.version} |`);i.push("")}if(e.presentations?.length){i.push("## Presentations");i.push("");i.push("| Name | Version |");i.push("|------|---------|");for(const o of e.presentations)i.push(`| ${o.key} | v${o.version} |`);i.push("");if(p.includeRelatedPresentations&&n?.presentations){i.push("### Presentation Details");i.push("");for(const o of e.presentations){const u=n.presentations.get(o.key,o.version);if(u){i.push(`#### ${o.key}.v${o.version}`);i.push("");i.push(`- **Type:** ${u.source.type}`);if(u.source.type==="component")i.push(`- **Component:** ${u.source.componentKey}`);i.push("")}}}}if(e.visualizations?.length){i.push("## Visualizations");i.push("");i.push("| Name | Version | Kind |");i.push("|------|---------|------|");for(const o of e.visualizations){const u=n?.visualizations?.get(o.key,o.version);i.push(`| ${o.key} | v${o.version} | ${u?.visualization.kind??"unknown"} |`)}i.push("");if(p.includeRelatedVisualizations&&n?.visualizations){i.push("### Visualization Details");i.push("");for(const o of e.visualizations){const u=n.visualizations.get(o.key,o.version);if(u){i.push(visualizationToMarkdown(u));i.push("")}}}}if(e.visualScenarios?.length){i.push("## Visual Scenarios");i.push("");i.push("| Name | Version | Surface | Cases |");i.push("|------|---------|---------|-------|");for(const o of e.visualScenarios){const u=n?.visualScenarios?.get(o.key,o.version);i.push(`| ${o.key} | v${o.version} | ${u?.surface??"unknown"} | ${u?.cases.length??"unknown"} |`)}i.push("")}if(e.capabilities){if(e.capabilities.provides?.length){i.push("## Capabilities Provided");i.push("");for(const o of e.capabilities.provides)i.push(`- \`${o.key}.v${o.version}\``);i.push("")}if(e.capabilities.requires?.length){i.push("## Capabilities Required");i.push("");for(const o of e.capabilities.requires)i.push(`- \`${o.key}\`${o.version?`.v${o.version}`:""} (${o.optional?"optional":"required"})`);i.push("")}}return i.join(`
+`)}export function presentationToMarkdown(e){const n=e.meta,t=[];t.push(`# Presentation: ${n.key}.v${n.version}`);t.push("");if(n.description){t.push(`> ${n.description}`);t.push("")}t.push("## Metadata");t.push("");t.push(`- **Name:** ${n.key}`);t.push(`- **Version:** ${n.version}`);if(n.stability)t.push(`- **Stability:** ${n.stability}`);if(n.owners?.length)t.push(`- **Owners:** ${n.owners.join(", ")}`);if(n.tags?.length)t.push(`- **Tags:** ${n.tags.join(", ")}`);t.push("");t.push("## Source");t.push("");t.push(`- **Type:** ${e.source.type}`);if(e.source.type==="component"){t.push(`- **Framework:** ${e.source.framework}`);t.push(`- **Component Key:** ${e.source.componentKey}`)}t.push("");t.push("## Supported Targets");t.push("");for(const p of e.targets)t.push(`- ${p}`);t.push("");if(e.policy){t.push("## Policy");t.push("");if(e.policy.flags?.length)t.push(`- **Feature Flags:** ${e.policy.flags.join(", ")}`);if(e.policy.pii?.length)t.push(`- **PII Fields:** ${e.policy.pii.join(", ")}`);t.push("")}return t.join(`
+`)}export function visualizationToMarkdown(e){const{meta:n,visualization:t}=e,p=[];p.push(`# Visualization: ${n.key}.v${n.version}`);p.push("");p.push(`> ${n.description}`);p.push("");p.push(`- **Kind:** ${t.kind}`);if("variant"in t&&t.variant)p.push(`- **Variant:** ${t.variant}`);p.push(`- **Goal:** ${n.goal}`);p.push(`- **Context:** ${n.context}`);p.push("");if(t.dimensions?.length){p.push("## Dimensions");p.push("");for(const s of t.dimensions)p.push(`- \`${s.key}\` (${s.type??"category"}) -> ${s.dataPath}`);p.push("")}if(t.measures?.length){p.push("## Measures");p.push("");for(const s of t.measures)p.push(`- \`${s.key}\` -> ${s.dataPath}`);p.push("")}return p.join(`
+`)}export function eventToMarkdown(e){const n=[];n.push(`# Event: ${e.meta.key}.v${e.meta.version}`);n.push("");n.push("## Metadata");n.push("");n.push(`- **Name:** ${e.meta.key}`);n.push(`- **Version:** ${e.meta.version}`);if(e.meta.description)n.push(`- **Description:** ${e.meta.description}`);n.push("");n.push("## Payload Schema");n.push("");n.push("```json");try{const t=e.payload.getZod();if("shape"in t&&t.shape){const p=t.shape,s=Object.keys(p);n.push(JSON.stringify({fields:s},null,2))}else n.push("// Payload schema available at runtime")}catch{n.push("// Schema details available at runtime")}n.push("```");n.push("");return n.join(`
+`)}export function docBlockToMarkdown(e){const n=[];n.push(`# ${e.title}`);n.push("");if(e.summary){n.push(`> ${e.summary}`);n.push("")}n.push("## Metadata");n.push("");n.push(`- **ID:** ${e.id}`);n.push(`- **Kind:** ${e.kind??"reference"}`);n.push(`- **Visibility:** ${e.visibility??"public"}`);if(e.tags?.length)n.push(`- **Tags:** ${e.tags.join(", ")}`);if(e.owners?.length)n.push(`- **Owners:** ${e.owners.join(", ")}`);if(e.domain)n.push(`- **Domain:** ${e.domain}`);n.push("");n.push("## Content");n.push("");n.push(e.body);n.push("");if(e.links?.length){n.push("## Related Links");n.push("");for(const t of e.links)n.push(`- [${t.label}](${t.href})`);n.push("")}return n.join(`
+`)}export function exportSpec(e,n={}){const t=n.format??"full";let p;switch(t){case"context":p=operationSpecToContextMarkdown(e);break;case"prompt":p=operationSpecToAgentPrompt(e);break;case"full":default:p=operationSpecToFullMarkdown(e,n);break}return{spec:e,markdown:p,format:t,meta:{specName:e.meta.key,specVersion:e.meta.version,exportedAt:new Date().toISOString(),wordCount:p.split(/\s+/).length}}}export function exportFeature(e,n,t={}){const p=t.format??"full",s=featureToMarkdown(e,n,t);return{feature:e,markdown:s,format:p,includedSpecs:e.operations?.map((i)=>`${i.key}.v${i.version}`)??[],includedEvents:e.events?.map((i)=>`${i.key}.v${i.version}`)??[],includedPresentations:e.presentations?.map((i)=>`${i.key}.v${i.version}`)??[],includedVisualizations:e.visualizations?.map((i)=>`${i.key}.v${i.version}`)??[],includedVisualScenarios:e.visualScenarios?.map((i)=>`${i.key}.v${i.version}`)??[]}}

package/dist/node/llm/index.js

@@ -0,0 +1 @@
+export{docBlockToMarkdown,eventToMarkdown,exportFeature,exportSpec,featureToMarkdown,operationSpecToAgentPrompt,operationSpecToContextMarkdown,operationSpecToFullMarkdown,presentationToMarkdown}from"./exporters.js";export{AGENT_SYSTEM_PROMPTS,formatPlanForAgent,generateFixViolationsPrompt,generateImplementationPlan,generateImplementationPrompt,generateReviewPrompt,generateTestPrompt,generateVerificationPrompt}from"./prompts.js";

package/dist/node/llm/prompts.js

@@ -0,0 +1,237 @@
+import{operationSpecToAgentPrompt as u,operationSpecToFullMarkdown as l}from"./exporters.js";export const AGENT_SYSTEM_PROMPTS={"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.`};export function generateImplementationPrompt(e,n,i){const t=AGENT_SYSTEM_PROMPTS[n],r=l(e);let o;if(n==="claude-code")o=`## Implementation Task
+
+Implement the following ContractSpec operation:
+
+${r}
+
+${i?.targetPath?`**Target file:** \`${i.targetPath}\`
+`:""}
+${i?.existingCode?`**Existing code to modify:**
+\`\`\`typescript
+${i.existingCode}
+\`\`\`
+`:""}
+
+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.`;else if(n==="cursor-cli")o=`Implement this ContractSpec operation.
+
+${r}
+
+${i?.targetPath?`Target: ${i.targetPath}
+`:""}
+
+Requirements:
+- TypeScript with strict types
+- Handle all error cases
+- Emit specified events
+- Follow acceptance scenarios`;else o=u(e,{taskType:"implement",existingCode:i?.existingCode});return{agent:n,systemPrompt:t,taskPrompt:o}}export function generateTestPrompt(e,n,i){const t=i?.testFramework??"vitest",o=`## Test Generation Task
+
+Generate comprehensive tests for this specification:
+
+${l(e)}
+
+${i?.implementationCode?`**Implementation:**
+\`\`\`typescript
+${i.implementationCode}
+\`\`\`
+`:""}
+
+**Test Framework:** ${t}
+
+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:n,systemPrompt:AGENT_SYSTEM_PROMPTS[n],taskPrompt:o}}export function generateReviewPrompt(e,n,i){const r=`## Code Review Task
+
+Review this implementation against its specification:
+
+**Specification:**
+${l(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:n,systemPrompt:AGENT_SYSTEM_PROMPTS[n],taskPrompt:r}}export function generateVerificationPrompt(e,n){return{agent:"generic-mcp",taskPrompt:`## Semantic Verification Task
+
+Verify that this implementation fulfills the specification's intent.
+
+**Specification:**
+${l(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"
+}
+\`\`\``}}export function generateImplementationPlan(e,n){const i=e.meta,t=[],r=n?.projectRoot??"src",o=i.key.replace(/\./g,"/");if(i.kind==="command"||i.kind==="query")t.push({path:`${r}/${o}/handler.ts`,purpose:"Main handler implementation",type:"create"},{path:`${r}/${o}/types.ts`,purpose:"Type definitions",type:"create"},{path:`${r}/${o}/handler.test.ts`,purpose:"Handler tests",type:"create"});const s=[];let 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((a)=>a.key)??["Operation completes successfully for valid input"]});if(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(([a,d])=>`Handle ${a}: ${d.when}`)});if(e.sideEffects?.emits?.length)s.push({order:c++,title:"Implement Event Emission",description:"Emit events as specified",acceptanceCriteria:e.sideEffects.emits.map((a)=>{if("ref"in a)return`Emit ${a.ref.key}.v${a.ref.version} when ${a.when}`;return`Emit ${a.key}.v${a.version} when ${a.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"]});const p={policy:[],security:[],pii:[]};p.policy.push(`Auth level: ${e.policy.auth}`);if(e.policy.idempotent!==void 0)p.policy.push(`Idempotent: ${e.policy.idempotent}`);if(e.policy.rateLimit)p.policy.push(`Rate limit: ${e.policy.rateLimit.rpm} rpm per ${e.policy.rateLimit.key}`);if(e.policy.flags?.length)p.policy.push(`Feature flags required: ${e.policy.flags.join(", ")}`);if(e.policy.escalate)p.security.push(`Escalation required: ${e.policy.escalate}`);if(e.policy.pii?.length)p.pii=e.policy.pii;const m=["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"];return{target:{type:"spec",key:i.key,version:i.version},context:{goal:i.goal,description:i.description,background:i.context},specMarkdown:l(e),fileStructure:t,steps:s,constraints:p,verificationChecklist:m}}export function formatPlanForAgent(e,n){let i;if(n==="claude-code")i=`## Implementation Plan: ${e.target.key}.v${e.target.version}
+
+### Context
+**Goal:** ${e.context.goal}
+
+**Background:** ${e.context.background}
+
+### Specification
+${e.specMarkdown}
+
+### File Structure
+${e.fileStructure.map((t)=>`- \`${t.path}\` (${t.type}): ${t.purpose}`).join(`
+`)}
+
+### Implementation Steps
+${e.steps.map((t)=>`
+#### Step ${t.order}: ${t.title}
+${t.description}
+
+**Acceptance Criteria:**
+${t.acceptanceCriteria.map((r)=>`- [ ] ${r}`).join(`
+`)}
+`).join(`
+`)}
+
+### Constraints
+${e.constraints.policy.length?`**Policy:**
+${e.constraints.policy.map((t)=>`- ${t}`).join(`
+`)}
+`:""}
+${e.constraints.security.length?`**Security:**
+${e.constraints.security.map((t)=>`- ${t}`).join(`
+`)}
+`:""}
+${e.constraints.pii.length?`**PII Handling:**
+${e.constraints.pii.map((t)=>`- ${t}`).join(`
+`)}
+`:""}
+
+### Verification Checklist
+${e.verificationChecklist.map((t)=>`- [ ] ${t}`).join(`
+`)}
+
+Implement this plan step by step.`;else if(n==="cursor-cli")i=`# ${e.target.key}.v${e.target.version}
+
+${e.context.goal}
+
+## Spec
+${e.specMarkdown}
+
+## Files to create
+${e.fileStructure.map((t)=>`${t.type}: ${t.path}`).join(`
+`)}
+
+## Steps
+${e.steps.map((t)=>`${t.order}. ${t.title}`).join(`
+`)}`;else i=`Implementation plan for ${e.target.key}.v${e.target.version}
+
+${e.specMarkdown}
+
+Steps:
+${e.steps.map((t)=>`${t.order}. ${t.title}: ${t.description}`).join(`
+`)}`;return{agent:n,systemPrompt:AGENT_SYSTEM_PROMPTS[n],taskPrompt:i}}export function generateFixViolationsPrompt(e,n,i){const t=l(e),r=i.map((s,c)=>`${c+1}. ${s.message}${s.suggestion?`
+   Suggestion: ${s.suggestion}`:""}`).join(`
+`);return{agent:"generic-mcp",taskPrompt:`## Fix Specification Violations
+
+The following implementation has violations against its specification:
+
+**Specification:**
+${t}
+
+**Current Implementation:**
+\`\`\`typescript
+${n}
+\`\`\`
+
+**Violations Found:**
+${r}
+
+Fix ALL violations while maintaining existing functionality.
+Provide the corrected implementation.`}}

package/dist/node/markdown.js

@@ -0,0 +1,3 @@
+import{isEmitDeclRef as r}from"./operations/index.js";export function operationsToMarkdown(p,i){const e=[];for(const s of p.list()){const o=s.meta;e.push(`# ${o.key}.v${o.version}`);e.push("");e.push(`**Kind:** ${o.kind} | **Stability:** ${o.stability} | **Owners:** ${o.owners.join(", ")}`);e.push("");e.push(`**Description:** ${o.description}`);e.push("");e.push("## Goal");e.push(o.goal);e.push("");e.push("## Context");e.push(o.context);e.push("");e.push("## Policy");e.push(`- Auth: ${s.policy.auth}`);e.push(`- Idempotent: ${!!s.policy.idempotent}`);if(s.policy.rateLimit)e.push(`- Rate Limit: ${s.policy.rateLimit.rpm}/min by ${s.policy.rateLimit.key}`);if(s.policy.flags?.length)e.push(`- Flags: ${s.policy.flags.join(", ")}`);if(s.policy.pii?.length)e.push(`- PII: ${s.policy.pii.join(", ")}`);e.push("");if(s.sideEffects?.emits?.length){e.push("## Emits Events");for(const t of s.sideEffects.emits)if(r(t))e.push(`- \`${t.ref.key}.v${t.ref.version}\` — ${t.when}`);else e.push(`- \`${t.key}.v${t.version}\` — ${t.when}`);e.push("")}if(s.io.errors&&Object.keys(s.io.errors).length){e.push("## Errors");for(const[t,n]of Object.entries(s.io.errors))e.push(`- \`${t}\` (${n.http??400}) — ${n.description} (when: ${n.when})`);e.push("")}if(s.acceptance?.scenarios?.length){e.push("## Acceptance Scenarios");for(const t of s.acceptance.scenarios){e.push(`### ${t.key}`);e.push(`- **Given:** ${t.given.join("; ")}`);e.push(`- **When:** ${t.when.join("; ")}`);e.push(`- **Then:** ${t.then.join("; ")}`);e.push("")}}if(s.acceptance?.examples?.length){e.push("## Examples");for(const t of s.acceptance.examples){e.push(`- **${t.key}**`);e.push("  - Input:");e.push("    ```json");e.push(JSON.stringify(t.input,null,2));e.push("    ```");e.push("  - Output:");e.push("    ```json");e.push(JSON.stringify(t.output,null,2));e.push("    ```");e.push("")}}e.push("---");e.push("")}return e.join(`
+`)}export function docsToMarkdown(p,i){const e=[];e.push(operationsToMarkdown(p,i));if(i.presentations){e.push("# Presentations");e.push("");for(const s of i.presentations.list()){e.push(`## ${s.meta.key}.v${s.meta.version}`);e.push("");e.push(`- Type: ${s.source.type}`);if(s.source.type==="component"){e.push(`- Framework: ${s.source.framework}`);e.push(`- Component Key: ${s.source.componentKey}`)}e.push(`- Targets: ${s.targets.join(", ")}`);e.push("")}e.push("")}if(i.features){e.push("# Features");e.push("");for(const s of i.features.list()){e.push(`## ${s.meta.title} (${s.meta.key})`);if(s.meta.description)e.push(s.meta.description);e.push("");if(s.operations?.length){e.push("- Operations:");for(const o of s.operations)e.push(`  - ${o.key}.v${o.version}`)}if(s.events?.length){e.push("- Events:");for(const o of s.events)e.push(`  - ${o.key}.v${o.version}`)}if(s.presentations?.length){e.push("- Presentations:");for(const o of s.presentations)e.push(`  - ${o.key}.v${o.version}`)}e.push("")}}return e.join(`
+`)}

package/dist/node/marketing/fixtures.js

@@ -0,0 +1 @@
+export const representativeMarketingPageContract={id:"contractspec-studio-marketing",route:"/studio",kind:"product-overview",title:"ContractSpec Studio",narrative:{dominantQuestion:"How does ContractSpec Studio turn semantic contracts into governed product surfaces?",arc:"architecture-capabilities-proof-cta",intents:[{intent:"orient",priority:"primary"},{intent:"prove",priority:"secondary"},{intent:"convert",priority:"tertiary"}]},densityBudget:{level:"standard",dataDepth:"standard",estimatedReadSeconds:180,maxVisibleSections:10,maxCardsPerSection:4,maxBulletsPerSection:4,defaultDisclosure:"route"},ctas:[{id:"book-demo",label:"Book a Studio demo",href:"/contact",priority:"primary"},{id:"watch-proof",label:"Watch the proof walkthrough",href:"/studio/proof-video",priority:"secondary"}],sections:[{id:"launch-announcement",kind:"hero",intent:"establish-context",priority:"secondary",title:"Contract-first marketing is live",ctaRefs:["book-demo"],disclosure:{mode:"none"},presentation:{bindingId:"studio.announcement",renderTargetHint:"MarketingAnnouncementBar",payload:{message:"New: regenerative marketing pages from semantic contracts.",ctaRef:"book-demo",tone:"brand"}}},{id:"studio-hero",kind:"hero",intent:"make-claim",priority:"primary",title:"Build governed product stories from contracts",summary:"ContractSpec Studio keeps semantic contracts, proof data, and presentation output in one regenerative loop.",ctaRefs:["book-demo","watch-proof"],disclosure:{mode:"none"},presentation:{bindingId:"studio.hero",renderTargetHint:"MarketingHero",payload:{eyebrow:"ContractSpec Studio",headline:"Regenerate marketing surfaces from contract truth.",subheadline:"Author the semantics once, then normalize and render the right proof-backed components everywhere.",primaryCtaRef:"book-demo",secondaryCtaRef:"watch-proof"}}},{id:"capability-icons",kind:"capability-grid",intent:"explain",priority:"secondary",title:"The regenerative loop",cards:[{title:"Validate",description:"Reject unsupported primitives early."},{title:"Normalize",description:"Create serializable render descriptors."},{title:"Render",description:"Map descriptors to governed components."}],disclosure:{mode:"route",targetHref:"/studio/architecture"},presentation:{bindingId:"studio.icon-grid",renderTargetHint:"MarketingIconGrid",payload:{columns:3,density:"standard"}}},{id:"feature-tabs",kind:"feature-grid",intent:"explain",priority:"secondary",title:"ContractSpec authoring modes",disclosure:{mode:"accordion",label:"Compare authoring modes"},presentation:{bindingId:"studio.feature-tabs",renderTargetHint:"MarketingFeatureTabs",payload:{tabs:[{id:"semantic",label:"Semantic",title:"Intent-first contracts",description:"Describe the buyer journey without naming React components."},{id:"registry",label:"Registry",title:"Direct render targets",description:"Attach optional component hints for deterministic rendering."}]}}},{id:"delivery-timeline",kind:"process",intent:"explain",priority:"secondary",title:"From contract to campaign",disclosure:{mode:"route",targetHref:"/studio/process"},presentation:{bindingId:"studio.timeline",renderTargetHint:"MarketingTimeline",payload:{milestones:[{title:"Author",description:"Write the semantic page contract."},{title:"Validate",description:"Check primitive payloads and CTAs."},{title:"Ship",description:"Render through the shared registry."}]}}},{id:"studio-proof-video",kind:"proof",intent:"prove",priority:"secondary",title:"Watch the Studio proof loop",ctaRefs:["watch-proof"],evidenceRefs:["studio-proof"],disclosure:{mode:"drawer",label:"Open video transcript"},presentation:{bindingId:"studio.video",renderTargetHint:"MarketingVideo",payload:{src:"/videos/studio-proof.mp4",title:"ContractSpec Studio proof walkthrough",accessibleLabel:"Video walkthrough showing ContractSpec Studio rendering a marketing contract.",transcriptHref:"/studio/proof-video/transcript"}}},{id:"trust-badges",kind:"trust",intent:"reduce-risk",priority:"secondary",title:"Proof-ready by design",evidenceRefs:["studio-proof"],disclosure:{mode:"route",targetHref:"/studio/trust"},presentation:{bindingId:"studio.trust-badges",renderTargetHint:"MarketingTrustBadges",payload:{badges:[{label:"Typed contracts",summary:"Public contract shapes are typed."},{label:"Validator gated",summary:"Unsupported primitives fail fast."}]}}},{id:"lead-capture",kind:"final-cta",intent:"convert",priority:"primary",title:"Bring ContractSpec Studio into your marketing stack",ctaRefs:["book-demo"],disclosure:{mode:"none"},presentation:{bindingId:"studio.lead-capture",renderTargetHint:"MarketingLeadCapture",payload:{formId:"studio-demo-request",submitLabel:"Request a demo",successMessage:"We will follow up with a Studio proof walkthrough.",privacyHref:"/privacy"}}}]},representativeMarketingSiteContract={id:"contractspec-studio-site",productKey:"contractspec-studio",name:"ContractSpec Studio",category:"developer platform",coreLine:"Semantic contracts regenerate governed product surfaces.",wedge:"Contract-first presentation mapping",entryPoint:"studio",strategicDirection:"contract-first regenerative marketing",audienceSegments:["product","marketing","engineering"],navigation:[{label:"Studio",href:"/studio"}],globalCtas:representativeMarketingPageContract.ctas,evidence:[{id:"studio-proof",label:"Studio proof",summary:"The Studio page renders from a validated marketing contract."}],presentationBindings:[{id:"studio.announcement",sectionKind:"hero",primitive:"announcement-bar",renderTargetHint:"MarketingAnnouncementBar"},{id:"studio.hero",sectionKind:"hero",primitive:"hero",renderTargetHint:"MarketingHero"},{id:"studio.icon-grid",sectionKind:"capability-grid",primitive:"icon-grid",renderTargetHint:"MarketingIconGrid"},{id:"studio.feature-tabs",sectionKind:"feature-grid",primitive:"feature-tabs",renderTargetHint:"MarketingFeatureTabs"},{id:"studio.timeline",sectionKind:"process",primitive:"timeline",renderTargetHint:"MarketingTimeline"},{id:"studio.video",sectionKind:"proof",primitive:"video",renderTargetHint:"MarketingVideo"},{id:"studio.trust-badges",sectionKind:"trust",primitive:"trust-badges",renderTargetHint:"MarketingTrustBadges"},{id:"studio.lead-capture",sectionKind:"final-cta",primitive:"lead-capture",formRef:"marketing.lead.capture.form",operationRef:{key:"marketing.lead.capture",version:"1.0.0"},hostExecutionBoundary:"host-owned-operation",renderTargetHint:"MarketingLeadCapture"}],pages:[representativeMarketingPageContract]};

package/dist/node/marketing/forms.js

@@ -0,0 +1 @@
+import{defineFormSpec as o,FormRegistry as t,responsiveFormColumns as a}from"../forms/index.js";import{MarketingDemoBookCommand as e,MarketingDemoBookInput as n}from"../operations/index.js";export const MarketingStudioDemoRequestForm=o({meta:{key:"studio-demo-request",version:"1.0.0",title:"Studio demo request",description:"Collect qualified ContractSpec Studio demo interest.",domain:"marketing",owners:["@contractspec-core"],tags:["marketing","forms","lead-capture","demo"],stability:"experimental"},model:n,layout:{columns:a(2),gap:"md"},fields:[{kind:"email",name:"email",labelI18n:"Email",layout:{colSpan:"full"}},{kind:"text",name:"name",labelI18n:"Name"},{kind:"text",name:"company",labelI18n:"Company"},{kind:"datetime",name:"preferredAt",labelI18n:"Preferred time",layout:{colSpan:"full"}},{kind:"textarea",name:"message",labelI18n:"Message",layout:{colSpan:"full"}}],actions:[{key:"submit",labelI18n:"Request a demo",op:{name:e.meta.key,version:e.meta.version},success:{toastI18n:"We will follow up with a Studio proof walkthrough."}}],renderHints:{ui:"shadcn",form:"react-hook-form"}}),marketingFormRegistry=new t().register(MarketingStudioDemoRequestForm);

package/dist/node/marketing/index.js

@@ -0,0 +1 @@
+export*from"./fixtures.js";export*from"./forms.js";export*from"./types.js";export*from"./validation.js";

package/dist/node/marketing/validation.js

@@ -0,0 +1,3 @@
+const v=new Set(["route","drawer","agent-assisted"]),b=new Set(["announcement-bar","hero","icon-grid","cta-band","prose","feature-tabs","lead-capture","timeline","trust-badges","video"]),k={"announcement-bar":["message"],"feature-tabs":["tabs"],"lead-capture":["formId","submitLabel"],timeline:["milestones"],"trust-badges":["badges"],video:["src","title","accessibleLabel","transcriptHref"]},I=new Set(["announcement-bar","cta-band","lead-capture"]),P=new Set(["lead-capture"]),S=new Set(["render-only","host-owned-operation"]),M=new Set(["lead-capture"]),w=(e)=>typeof e==="object"&&e!==null&&!Array.isArray(e);function d(e){return typeof e==="string"&&e.trim().length>0}function x(e){return Array.isArray(e)&&e.length>0}function R(e,s){const t=e[s];return Array.isArray(t)?x(t):d(t)}function C(e){if(!e)return[];return["ctaRef","primaryCtaRef","secondaryCtaRef"].flatMap((s)=>{const t=e[s];return d(t)?[t]:[]})}export const defaultMarketingSectionKindsByPageKind={home:["hero","problem","promise","value-proposition","workflow-example","capability-grid","proof","routing","final-cta"],"product-overview":["hero","architecture","capability-grid","feature-grid","process","proof","trust","final-cta"],"solution-index":["hero","problem","workflow-example","capability-grid","routing","proof","final-cta"],"solution-detail":["hero","workflow-example","process","capability-grid","proof","objection-handling","routing","final-cta"],platform:["hero","architecture","capability-grid","trust","proof","process","routing","final-cta"],feature:["hero","feature-grid","capability-grid","process","proof","final-cta"],"pricing-access":["hero","comparison","objection-handling","faq","proof","final-cta"],vision:["hero","promise","value-proposition","architecture","proof","routing","final-cta"],about:["hero","promise","trust","proof","final-cta"],contact:["hero","routing","faq","final-cta"],proof:["hero","proof","evidence","trust","final-cta"],comparison:["hero","comparison","proof","objection-handling","final-cta"],conversion:["hero","proof","objection-handling","faq","final-cta"]};export function validateMarketingSiteContract(e){const s=[],t=new Set;for(const r of e.pages){if(t.has(r.route))s.push({code:"duplicate_page_route",message:`Duplicate marketing page route "${r.route}".`,pageId:r.id,ref:r.route});t.add(r.route);s.push(...validateMarketingPageContract(r,e).issues)}return{valid:s.length===0,issues:s}}export function validateMarketingPageContract(e,s={presentationBindings:[],evidence:[]}){const t=[],r=new Set(e.ctas.map((i)=>i.id)),m=new Set(s.evidence.map((i)=>i.id)),f=new Map(s.presentationBindings.map((i)=>[i.id,i])),c=e.narrative.intents.filter((i)=>i.priority==="primary").length,u=e.ctas.filter((i)=>i.priority==="primary").length;if(!e.narrative.dominantQuestion.trim())t.push({code:"missing_dominant_question",message:`Marketing page "${e.id}" must declare a dominant question.`,pageId:e.id});if(c!==1)t.push({code:"invalid_primary_intent_count",message:`Marketing page "${e.id}" must declare exactly one primary intent; found ${c}.`,pageId:e.id});if(u!==1)t.push({code:"invalid_primary_cta_count",message:`Marketing page "${e.id}" must declare exactly one primary CTA; found ${u}.`,pageId:e.id});const p=e.sections.filter((i)=>i.visible!==!1).length;if(e.kind==="home"&&e.densityBudget.maxVisibleSections!==void 0&&p>e.densityBudget.maxVisibleSections)t.push({code:"homepage_over_density_budget",message:`Homepage "${e.id}" has ${p} visible sections but budget allows ${e.densityBudget.maxVisibleSections}.`,pageId:e.id});const _=new Set(defaultMarketingSectionKindsByPageKind[e.kind]??[]);for(const i of e.sections){if(!i.kind)t.push({code:"missing_section_kind",message:`Section "${i.id}" must declare a semantic kind.`,pageId:e.id,sectionId:i.id});if(!i.disclosure?.mode)t.push({code:"missing_disclosure_strategy",message:`Section "${i.id}" must declare a disclosure strategy.`,pageId:e.id,sectionId:i.id});if(i.kind&&!_.has(i.kind))t.push({code:"unsupported_section_kind_for_page_kind",message:`Section kind "${i.kind}" is not supported for page kind "${e.kind}".`,pageId:e.id,sectionId:i.id,ref:i.kind});const n=f.get(i.presentation.bindingId);if(!n)t.push({code:"missing_presentation_binding",message:`Section "${i.id}" references missing presentation binding "${i.presentation.bindingId}".`,pageId:e.id,sectionId:i.id,ref:i.presentation.bindingId});else{if(n.sectionKind!==i.kind)t.push({code:"missing_presentation_binding",message:`Presentation binding "${n.id}" is for "${n.sectionKind}", not section kind "${i.kind}".`,pageId:e.id,sectionId:i.id,ref:n.id});if(n.supportedPageKinds&&!n.supportedPageKinds.includes(e.kind))t.push({code:"missing_presentation_binding",message:`Presentation binding "${n.id}" does not support page kind "${e.kind}".`,pageId:e.id,sectionId:i.id,ref:n.id});if(!b.has(n.primitive))t.push({code:"unsupported_presentation_primitive",message:`Presentation binding "${n.id}" uses unsupported primitive "${n.primitive}".`,pageId:e.id,sectionId:i.id,ref:n.primitive});const o=w(i.presentation.payload)?i.presentation.payload:void 0,l=k[n.primitive]??[];if(l.length>0&&!o)t.push({code:"missing_presentation_payload",message:`Section "${i.id}" must provide payload data for primitive "${n.primitive}".`,pageId:e.id,sectionId:i.id,ref:n.primitive});if(o){for(const a of l)if(!R(o,a))t.push({code:"missing_presentation_payload_field",message:`Section "${i.id}" primitive "${n.primitive}" is missing payload field "${a}".`,pageId:e.id,sectionId:i.id,ref:a})}if(P.has(n.primitive)&&!n.formRef)t.push({code:"missing_form_ref_for_form_primitive",message:`Form-like presentation binding "${n.id}" for primitive "${n.primitive}" must declare a formRef.`,pageId:e.id,sectionId:i.id,ref:n.id});if(M.has(n.primitive)&&!n.operationRef)t.push({code:"missing_operation_ref_for_executable_binding",message:`Executable presentation binding "${n.id}" for primitive "${n.primitive}" must declare an operationRef.`,pageId:e.id,sectionId:i.id,ref:n.id});if(n.hostExecutionBoundary!==void 0&&!S.has(n.hostExecutionBoundary))t.push({code:"invalid_host_execution_boundary",message:`Presentation binding "${n.id}" declares an unsupported hostExecutionBoundary "${String(n.hostExecutionBoundary)}"; expected "render-only" or "host-owned-operation".`,pageId:e.id,sectionId:i.id,ref:n.id});else if(n.operationRef&&n.hostExecutionBoundary==="render-only")t.push({code:"invalid_host_execution_boundary",message:`Presentation binding "${n.id}" declares an operationRef but a "render-only" hostExecutionBoundary; executable bindings must declare "host-owned-operation".`,pageId:e.id,sectionId:i.id,ref:n.id});const g=C(o);if(I.has(n.primitive)&&(i.ctaRefs?.length??0)===0&&g.length===0)t.push({code:"missing_presentation_cta",message:`Section "${i.id}" primitive "${n.primitive}" must declare a CTA reference.`,pageId:e.id,sectionId:i.id,ref:n.primitive});for(const a of g)if(!r.has(a))t.push({code:"missing_presentation_cta_ref",message:`Section "${i.id}" presentation payload references missing CTA "${a}".`,pageId:e.id,sectionId:i.id,ref:a});if(n.primitive==="video"&&o){if(!(d(o.accessibleLabel)&&d(o.transcriptHref)))t.push({code:"invalid_video_accessibility_metadata",message:`Video section "${i.id}" must include accessibleLabel and transcriptHref payload metadata.`,pageId:e.id,sectionId:i.id,ref:n.primitive})}}const y=e.densityBudget.maxCardsPerSection!==void 0&&(i.cards?.length??0)>e.densityBudget.maxCardsPerSection,h=e.densityBudget.maxBulletsPerSection!==void 0&&(i.bullets?.length??0)>e.densityBudget.maxBulletsPerSection;if((i.dataDepth==="deep"||y||h)&&!v.has(i.disclosure.mode))t.push({code:"dense_section_without_route_disclosure",message:`Dense or over-budget section "${i.id}" must disclose by route, drawer, or agent-assisted mode.`,pageId:e.id,sectionId:i.id});for(const o of i.ctaRefs??[])if(!r.has(o))t.push({code:"missing_cta_ref",message:`Section "${i.id}" references missing CTA "${o}".`,pageId:e.id,sectionId:i.id,ref:o});for(const o of i.evidenceRefs??[])if(!m.has(o))t.push({code:"missing_evidence_ref",message:`Section "${i.id}" references missing evidence "${o}".`,pageId:e.id,sectionId:i.id,ref:o})}return{valid:t.length===0,issues:t}}export function assertValidMarketingSiteContract(e){const s=validateMarketingSiteContract(e);if(!s.valid)throw Error(`Invalid marketing site contract:
+${s.issues.map((t)=>`- ${t.code}: ${t.message}`).join(`
+`)}`);return e}