@lssm/lib.contracts-spec 17.3.2

package/dist/node/shared-entities/team.js

@@ -0,0 +1,12 @@
+import{defineContractEntity as e}from"../entities/defineContractEntity.js";export const TeamEntity=e({meta:{key:"team",version:"1.0.0",description:"A group of persons organized around a shared purpose.",title:"Team",domain:"shared",stability:"stable",owners:["platform.core"],tags:["team","shared","cross-domain"]},edges:[{id:"team-to-person",from:"team",to:"person",relation:"has-member",cardinality:"many-to-many",directed:!0,label:"Members",inverse:"person-to-team"},{id:"team-to-project",from:"team",to:"project",relation:"owns",cardinality:"one-to-many",directed:!0,label:"Projects",inverse:"project-to-team"},{id:"team-to-resource",from:"team",to:"resource",relation:"manages",cardinality:"one-to-many",directed:!0,label:"Resources"}]}),shared_entities_team_DocBlocks=[{id:"docs.tech.contracts.shared-entities.team",title:"TeamEntity — Cross-Domain Team Contract Entity",summary:"`TeamEntity` is the canonical cross-domain entity for a group of persons. Layer 1: `team` slug with edges to person, project, resource.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/team",tags:["tech","contracts","shared-entities","team"],body:`# TeamEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'team'\`.
+
+## Edges
+
+| ID | From | To | Relation | Cardinality |
+|----|----|----|----|----|  
+| \`team-to-person\` | team | person | has-member | many-to-many |
+| \`team-to-project\` | team | project | owns | one-to-many |
+| \`team-to-resource\` | team | resource | manages | one-to-many |
+`}];

package/dist/node/sop/generation-sources.js

@@ -0,0 +1,5 @@
+export const SopGenerationSourcesDocBlock={id:"doc:sop.generation-sources",title:"Living SOP generation source snapshots",body:`Living SOP generation consumes canonical, serializable source contributions rather than provider objects or delivery-matrix state.
+
+Each contribution names an immutable source revision, validity window, and opaque evidence references. Source providers must never place raw answers, message bodies, contact data, prompts, or secrets in identity or evidence references. The runtime copies only the declared semantic fields, applies kind-specific freshness ceilings, canonicalizes ordering, and computes a content-addressed snapshot. Live generation revalidates source expiry against the current clock; historical projection is replay-only. Product adapters derive authority from authenticated server context; generation intent never carries tenant, workspace, actor, policy, or capability authority.
+
+Capability availability comes from the deployed runtime source. Delivery and qualification matrices may be recorded as documentation evidence, but never decide executable availability. Operation contributions resolve aliases to canonical registered key and version before snapshotting. The snapshot executes no effects; Workflow and Connect retain effect authority.`,tags:["sop","generation","provenance","security"]};

package/dist/node/sop/index.js

@@ -0,0 +1 @@
+export*from"./generation-sources.js";export*from"./operations.js";export*from"./sop.feature.js";export*from"./types.js";export*from"./validation.js";

package/dist/node/sop/operations.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,SchemaModel as o}from"@lssm/lib.schema";import{defineCommand as l,defineQuery as O}from"../operations/index.js";const f=new o({name:"SopRevisionOperationInputV1",fields:{sopRef:{type:e.ID(),isOptional:!1},revision:{type:e.Int_unsecure(),isOptional:!1}}}),y=new o({name:"SopMutationOperationInputV1",fields:{sopRef:{type:e.ID(),isOptional:!1},revision:{type:e.Int_unsecure(),isOptional:!1},evidenceRef:{type:e.ID(),isOptional:!0},idempotencyKey:{type:e.ID(),isOptional:!1}}}),d=new o({name:"SopGenerationOperationInputV1",fields:{requestRef:{type:e.ID(),isOptional:!1},mode:{type:e.String_unsecure(),isOptional:!1},locale:{type:e.String_unsecure(),isOptional:!1},sourceWatermark:{type:e.String_unsecure(),isOptional:!1},idempotencyKey:{type:e.ID(),isOptional:!1}}}),a=new o({name:"SopPackOperationInputV1",fields:{packRef:{type:e.ID(),isOptional:!1},digest:{type:e.String_unsecure(),isOptional:!0},idempotencyKey:{type:e.ID(),isOptional:!0}}}),r=new o({name:"SopOperationOutputV1",fields:{status:{type:e.String_unsecure(),isOptional:!1},resourceRef:{type:e.String_unsecure(),isOptional:!0},receiptRef:{type:e.String_unsecure(),isOptional:!0},result:{type:e.JSONObject(),isOptional:!0}}}),u=(n,t)=>({key:n,version:"1.0.0",title:t,description:t,goal:t,context:"SOP generation, publication, qualification, and execution are separate governed lifecycles.",domain:"operations",owners:["platform.core"],tags:["sop","workflow","evidence"],stability:"experimental"}),c={SOP_NOT_FOUND:{description:"The pinned SOP revision was not found.",http:404},INVALID_SOP:{description:"The SOP failed deterministic validation.",http:422},QUALIFICATION_REQUIRED:{description:"The SOP is not qualified for execution.",http:403},DIGEST_MISMATCH:{description:"The pinned evidence digest does not match.",http:409}},i=(n,t,p=y)=>l({meta:u(n,t),io:{input:p,output:r,errors:c},policy:{auth:"user",pii:[]}}),s=(n,t,p=f)=>O({meta:u(n,t),io:{input:p,output:r,errors:c},policy:{auth:"user",pii:[]}});export const sopOperations=[i("sop.generate","Generate SOP proposal",d),s("sop.validate","Validate SOP"),s("sop.simulate","Simulate SOP"),i("sop.publish","Publish SOP revision"),i("sop.qualify","Qualify SOP revision"),i("sop.revoke","Revoke SOP revision"),i("sop.run","Run SOP revision"),s("sop.compare","Compare SOP revisions"),i("sop.import","Import SOP pack",a),s("sop.export","Export SOP pack",a)];

package/dist/node/sop/sop.feature.js

@@ -0,0 +1,3 @@
+import{defineFeature as i}from"../features/index.js";import{SopGenerationSourcesDocBlock as o}from"./generation-sources.js";import{sopOperations as t}from"./operations.js";export const LivingSopsDocBlock={id:"living-sops-v1",title:"Living SOPs v1",summary:"Evidence-bound, generated, simulated, qualified, and revision-pinned operational procedures.",kind:"reference",visibility:"public",route:"/docs/platform/living-sops-v1",tags:["sop","knowledge","workflow","health"],body:`# Living SOPs v1
+
+SOP generation, publication, and execution are separate lifecycles. Generated revisions freeze their evidence and compile into WorkflowSpec for effects.`},LivingSopsFeature=i({meta:{key:"living-sops-v1",version:"1.0.0",title:"Living SOPs v1",description:"Layered SOP catalogs with deterministic and AI-assisted generation.",domain:"operations",owners:["platform.core"],tags:["sop","workflow","knowledge","health"],stability:"experimental"},operations:t.map((e)=>({key:e.meta.key,version:e.meta.version})),docs:[LivingSopsDocBlock.id,o.id]});

package/dist/node/sop/validation.js

@@ -0,0 +1 @@
+import{validatePredicateSpec as p}from"../decisioning/index.js";export function validateSopDocument(e){const i=[];if(e.steps.length===0)i.push(n("missing-step","steps","An SOP requires at least one step."));if(e.sourceEvidence.length===0)i.push(n("missing-evidence","sourceEvidence","An SOP requires source evidence."));const a=new Set;for(const[s,t]of e.steps.entries()){if(a.has(t.id))i.push(n("duplicate-step",`steps[${s}].id`,`Duplicate step ${t.id}.`));a.add(t.id);if(t.when)for(const o of p(t.when))i.push(n("invalid-predicate",`steps[${s}].${o.path}`,o.message));if(t.kind==="wait"&&!t.durationMs&&!t.signalKey)i.push(n("invalid-wait",`steps[${s}]`,"Wait steps require a duration or signal."));if(e.risk==="critical"&&t.kind==="operation"&&!t.compensationOperation)i.push(n("uncompensated-critical-operation",`steps[${s}]`,"Critical operation steps require compensation."))}if(!e.localeCatalogs[e.defaultLocale])i.push(n("missing-locale","defaultLocale","Default locale catalog is missing."));const r=new Set([e.titleI18n,e.goalI18n]);for(const s of e.steps){r.add(s.titleI18n);if(s.descriptionI18n)r.add(s.descriptionI18n);if(s.kind==="instruction")r.add(s.contentI18n)}for(const[s,t]of Object.entries(e.localeCatalogs))for(const o of r)if(!(o in t))i.push(n("missing-locale",`localeCatalogs.${s}.${o}`,`Locale ${s} is missing ${o}.`));return i}export function validateSopGenerationProposal(e){const i=validateSopDocument(e.document);if(!e.requestDigest.trim())i.push(n("missing-evidence","requestDigest","Generated proposals require an input digest."));if(!e.provenance.sourceWatermark.trim())i.push(n("missing-evidence","provenance.sourceWatermark","Generated proposals require a source watermark."));if(e.provenance.dataMode==="full-with-consent"&&!e.provenance.consentReceiptRef)i.push(n("missing-evidence","provenance.consentReceiptRef","Full-context AI proposals require a verified consent receipt."));if(e.modelRef&&!e.promptRef)i.push(n("missing-evidence","promptRef","AI proposals require a prompt reference."));return i}export function qualifiesForBoundedAutonomy(e){return e.status==="passed"&&e.evaluationCount>=100&&e.safeOutcomeRate>=0.98&&e.groundednessRate>=0.95&&e.criticalFailureCount===0&&e.rollbackDrillPassed}function n(e,i,a){return{code:e,path:i,message:a}}

package/dist/node/structured-data/derive.js

@@ -0,0 +1 @@
+const a=(e)=>{if(!e)return;const t=e.filter((r)=>r.trim().length>0);return t.length>0?t:void 0};export function deriveOrganization(e){const t={"@type":"Organization",name:e.name};if(e.url)t.url=e.url;if(e.logo)t.logo=e.logo;if(e.description)t.description=e.description;const r=a(e.sameAs);if(r)t.sameAs=r;return t}export function deriveWebSite(e){const t=e.url?.trim();if(!t)return;const r={"@type":"WebSite",name:e.name,url:t,publisher:deriveOrganization(e)};if(e.description)r.description=e.description;if(e.inLanguage)r.inLanguage=e.inLanguage;return r}export function deriveSoftwareApplication(e){const t={"@type":"SoftwareApplication",name:e.name};if(e.url)t.url=e.url;if(e.description)t.description=e.description;if(e.applicationCategory)t.applicationCategory=e.applicationCategory;if(e.operatingSystem)t.operatingSystem=e.operatingSystem;return t}export function deriveStructuredData(e,t){switch(e){case"Organization":return deriveOrganization(t);case"WebSite":return deriveWebSite(t);case"SoftwareApplication":return deriveSoftwareApplication(t)}}export function resolveStructuredDataRef(e,t){return e.mode==="inline"?e.data:deriveStructuredData(e.kind,t)}export function deriveSiteStructuredData(e){const t=[deriveOrganization(e)],r=deriveWebSite(e);if(r)t.push(r);return t}

package/dist/node/structured-data/index.d.js

@@ -0,0 +1 @@
+export*from"./derive.js";export*from"./kinds.js";export*from"./validate.js";

package/dist/node/structured-data/index.js

@@ -0,0 +1 @@
+export*from"./derive.js";export*from"./kinds.js";export*from"./validate.js";

package/dist/node/structured-data/kinds.js

@@ -0,0 +1 @@
+export const STRUCTURED_DATA_KINDS=["Organization","WebSite","SoftwareApplication","Product","FAQPage","Article","BreadcrumbList"],DERIVABLE_STRUCTURED_DATA_KINDS=["Organization","WebSite","SoftwareApplication"],StructuredDataDocBlock={id:"docs.contracts-spec.structured-data",title:"Structured data (schema.org / JSON-LD)",summary:"Typed schema.org shapes + StructuredDataRef for route-level and derived JSON-LD.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/structured-data",tags:["structured-data","seo","json-ld"],body:"# Structured data\n\nTyped schema.org shapes for marketing surfaces. `@context` is added at emission\n(the Next lane); shapes here carry only `@type` + fields.\n\n- **Derivable** (`Organization`, `WebSite`, `SoftwareApplication`) come from\n  branding + app metadata via `structured-data/derive.ts`.\n- **Authored** (`Product`, `FAQPage`, `Article`, `BreadcrumbList`) are supplied\n  inline on a route via `route.seo.schemaOrg`.\n\nA `StructuredDataRef` is either `{ mode: 'inline', kind, data }` (kind↔shape\ncorrelated) or `{ mode: 'derive', kind }` for the derivable kinds."};

package/dist/node/structured-data/validate.js

@@ -0,0 +1 @@
+import{STRUCTURED_DATA_KINDS as E}from"./kinds.js";const y=(a)=>typeof a==="object"&&a!==null&&!Array.isArray(a),i=(a,e,t)=>{if(typeof a!=="string")t.push({path:e,code:"INVALID_TYPE",message:`${e} must be a string.`})},n=(a,e,t)=>{if(typeof a!=="string"){t.push({path:e,code:"INVALID_TYPE",message:`${e} must be a string.`});return}if(a.trim().length===0)t.push({path:e,code:"EMPTY_VALUE",message:`${e} must not be empty.`})},d=n,O=(a,e,t)=>{if(typeof a!=="number"||!Number.isFinite(a))t.push({path:e,code:"INVALID_TYPE",message:`${e} must be a number.`})},f=(a,e,t)=>{if(typeof a==="string")return;if(Array.isArray(a)){a.forEach((r,o)=>i(r,`${e}[${o}]`,t));return}t.push({path:e,code:"INVALID_TYPE",message:`${e} must be a string or string[].`})},b=(a,e,t)=>{if(!Array.isArray(a)){t.push({path:e,code:"INVALID_TYPE",message:`${e} must be an array.`});return}a.forEach((r,o)=>n(r,`${e}[${o}]`,t))};function g(a,e,t,r){const o=t?`${t}.@type`:"@type";if(a["@type"]!==e.type)r.push({path:o,code:"TYPE_MISMATCH",message:`Expected @type "${e.type}".`});for(const[s,p]of Object.entries(e.props)){const l=t?`${t}.${s}`:s,S=a[s];if(S===void 0||S===null){if(p.required)r.push({path:l,code:"MISSING_REQUIRED",message:`Missing required property "${l}".`});continue}p.validate(S,l,r)}for(const s of Object.keys(a)){if(s==="@type")continue;if(!(s in e.props))r.push({path:t?`${t}.${s}`:s,code:"UNKNOWN_PROPERTY",message:`Unknown property "${s}" for ${e.type}.`})}}const u=(a)=>(e,t,r)=>{if(!y(e)){r.push({path:t,code:"INVALID_TYPE",message:`${t} must be an object.`});return}g(e,a,t,r)},m=(a)=>(e,t,r)=>{if(typeof e==="string")return;if(y(e)){g(e,a,t,r);return}r.push({path:t,code:"INVALID_TYPE",message:`${t} must be a string or ${a.type} object.`})},I=(a,e=1)=>(t,r,o)=>{if(!Array.isArray(t)){o.push({path:r,code:"INVALID_TYPE",message:`${r} must be an array.`});return}if(t.length<e)o.push({path:r,code:"MISSING_REQUIRED",message:`${r} must have at least ${e} item(s).`});t.forEach((s,p)=>u(a)(s,`${r}[${p}]`,o))},v=(a)=>(e,t,r)=>{if(Array.isArray(e)){e.forEach((o,s)=>u(a)(o,`${t}[${s}]`,r));return}u(a)(e,t,r)},T={type:"PostalAddress",props:{streetAddress:{validate:i},addressLocality:{validate:i},addressRegion:{validate:i},postalCode:{validate:i},addressCountry:{validate:i}}},A={type:"Offer",props:{price:{validate:i},priceCurrency:{validate:i},url:{validate:d},availability:{validate:i}}},c={type:"Organization",props:{name:{required:!0,validate:n},url:{validate:d},logo:{validate:d},description:{validate:i},email:{validate:i},telephone:{validate:i},sameAs:{validate:b},address:{validate:u(T)}}},N={type:"WebSite",props:{name:{required:!0,validate:n},url:{required:!0,validate:d},description:{validate:i},inLanguage:{validate:f},publisher:{validate:u(c)}}},D={type:"SoftwareApplication",props:{name:{required:!0,validate:n},applicationCategory:{validate:i},operatingSystem:{validate:i},url:{validate:d},description:{validate:i},offers:{validate:v(A)}}},P={type:"Product",props:{name:{required:!0,validate:n},description:{validate:i},image:{validate:f},brand:{validate:m(c)},url:{validate:d},offers:{validate:v(A)}}},_={type:"Answer",props:{text:{required:!0,validate:n}}},R={type:"Question",props:{name:{required:!0,validate:n},acceptedAnswer:{required:!0,validate:u(_)}}},V={type:"FAQPage",props:{mainEntity:{required:!0,validate:I(R)}}},j={type:"Article",props:{headline:{required:!0,validate:n},description:{validate:i},author:{validate:m(c)},datePublished:{validate:i},dateModified:{validate:i},image:{validate:f},url:{validate:d}}},L={type:"ListItem",props:{position:{required:!0,validate:O},name:{required:!0,validate:n},item:{validate:d}}},h={type:"BreadcrumbList",props:{itemListElement:{required:!0,validate:I(L)}}},Y={Organization:c,WebSite:N,SoftwareApplication:D,Product:P,FAQPage:V,Article:j,BreadcrumbList:h};export function validateStructuredData(a){const e=[];if(!y(a))return{valid:!1,issues:[{path:"",code:"NOT_OBJECT",message:"Structured data must be an object."}]};const t=a["@type"];if(typeof t!=="string"||t.length===0)return{valid:!1,issues:[{path:"@type",code:"MISSING_TYPE",message:'Missing "@type".'}]};const r=Y[t];if(!r)return{valid:!1,issues:[{path:"@type",code:"UNKNOWN_TYPE",message:`Unknown @type "${t}". Allowed: ${E.join(", ")}.`}]};g(a,r,"",e);return{valid:e.length===0,issues:e}}export function validateStructuredDataList(a){const e=[];a.forEach((t,r)=>{const o=validateStructuredData(t);for(const s of o.issues)e.push({...s,path:`[${r}]${s.path?`.${s.path}`:""}`})});return{valid:e.length===0,issues:e}}

package/dist/node/telemetry/anomaly.js

@@ -0,0 +1 @@
+export class TelemetryAnomalyMonitor{onAnomaly;samples=new Map;constructor(e={}){this.onAnomaly=e.onAnomaly}observe(e){const t=e.definition.anomalyDetection;if(!t?.enabled)return;if(!t.thresholds?.length)return;const n=`${e.name}.v${e.version}`,i=(this.samples.get(n)??0)+1;this.samples.set(n,i);if(typeof t.minimumSample==="number"&&i<t.minimumSample)return;for(const o of t.thresholds){const m=this.extractMetric(e,o.metric);if(typeof m!=="number")continue;if(typeof o.min==="number"&&m<o.min)this.emit(e,t,o.metric,m,"min");if(typeof o.max==="number"&&m>o.max)this.emit(e,t,o.metric,m,"max")}}extractMetric(e,t){const n=e.properties[t];if(typeof n==="number")return n;if(typeof n==="object"&&n!==null&&"value"in n){const r=n.value;return typeof r==="number"?r:void 0}return}emit(e,t,n,r,i){this.onAnomaly?.({dispatch:e,threshold:t,metric:n,value:r,type:i})}reset(){this.samples.clear()}}

package/dist/node/telemetry/delivery-v2.js

@@ -0,0 +1 @@
+import{defineTelemetrySpecV2 as o}from"./v2.js";const a={tenantGroup:{type:"string",required:!0,classification:"pseudonymous",handling:"hmac_sha256",description:"HMAC-pseudonymized tenant group"},workspaceGroup:{type:"string",required:!0,classification:"pseudonymous",handling:"hmac_sha256",description:"HMAC-pseudonymized workspace group"},subjectGroup:{type:"string",required:!1,classification:"pseudonymous",handling:"hmac_sha256",description:"Optional HMAC-pseudonymized actor or agent group"},deliveryPlanDigest:{type:"digest",required:!0,classification:"internal",handling:"allow",description:"Exact provider-neutral delivery plan digest"},evidenceRef:{type:"ref",required:!0,classification:"internal",handling:"allow",description:"Sanitized durable evidence reference"},status:{type:"string",required:!0,classification:"internal",handling:"allow",description:"Stable lifecycle status code"},durationMs:{type:"number",required:!1,classification:"internal",handling:"allow",description:"Bounded elapsed duration in milliseconds"},costUsd:{type:"number",required:!1,classification:"internal",handling:"allow",description:"Evidence-backed estimated or actual USD cost"}},r=[["delivery.intent.accepted","A product intent entered the governed delivery loop"],["builder.run.completed","Builder completed one governed candidate run"],["connect.decision.issued","Connect issued a packet-level authority decision"],["quality.plan.created","Connect-derived quality requirements became immutable"],["quality.check.completed","One typed quality check reached a terminal state"],["quality.run.completed","The exact quality plan reached a terminal state"],["release.staged","Exact artifacts were staged without changing latest"],["release.promoted","Staged artifacts were promoted under a permit"],["deployment.completed","A signed deployment work order completed"],["rollback.completed","A deployment rollback completed and emitted evidence"],["outcome.observed","An observation window emitted a measured outcome"],["evolution.proposed","Evidence produced a governed evolution proposal"]],s=r.map(([e,n])=>({key:e,version:"1.0.0",signal:"analytics",semantics:{what:n,why:"Measure safety, quality, speed, cost, and outcomes without granting authority"},properties:a,requiredEvidenceRelations:["delivery_plan",c(e)],retentionDays:90}));export const ContractSpecDeliveryTelemetryV2=o({schemaVersion:"contractspec.telemetry.spec.v2",id:"telemetry.contractspec.engineering.delivery",version:"2.0.0",ownerBindingRefs:["owner.contractspec.outcome","owner.contractspec.quality"],events:s,ports:{logs:t("logs"),metrics:t("metrics"),traces:t("traces"),analytics:{mode:"enabled",portRef:"telemetry.analytics.privacy-aware",exportPolicyRef:"telemetry.export.contractspec-engineering"},flags:t("flags"),experiments:t("experiments"),errors:t("errors")},consent:{mode:"not_required",policyRef:"telemetry.consent.engineering-operational",deniedBehavior:"drop",rationaleRef:"telemetry.rationale.non-personal-engineering-evidence"},residency:{policyRef:"telemetry.residency.lssm-eu",allowedRegionRefs:["region.eu"],crossRegionBehavior:"deny"},pseudonymization:{algorithm:"hmac_sha256",keyManagementPolicyRef:"telemetry.keys.lssm-managed",groupBindings:[i("tenant","tenantGroup"),i("workspace","workspaceGroup"),i("subject","subjectGroup")]},sampling:{strategy:"deterministic_hash",rate:1,unit:"workspace",seedRef:"telemetry.sampling.contractspec-engineering"},budgets:{cardinality:{maximumEventKeys:r.length,maximumDistinctValuesPerProperty:1e4},ingestion:{maximumEventsPerMinute:5000,maximumBytesPerMinute:2000000},cost:{currency:"USD",maximumMonthlyAmount:30,evidenceRef:"budget.contractspec.telemetry.monthly"}},redaction:{policyRef:"telemetry.redaction.delivery-v2",failureBehavior:"drop_event",forbiddenData:["raw_secret","raw_prompt","raw_payload","chain_of_thought","direct_personal_identifier"]},evidenceLinks:{allowedRelations:["delivery_plan","builder_receipt","connect_decision","quality_receipt","release_receipt","deployment_receipt","runtime_evidence","outcome_observation","evolution_proposal"],requiredRelations:["delivery_plan"],maximumLinksPerEvent:5,sanitizationPolicyRef:"telemetry.evidence.sanitization.delivery-v2"}});function t(e){return{mode:"disabled",reasonRef:`telemetry.port.${e}.disabled`}}function i(e,n){return{kind:e,propertyKey:n,keyRef:`telemetry.hmac.${e}`,rotationPolicyRef:`telemetry.rotation.${e}`}}function c(e){if(e.startsWith("builder."))return"builder_receipt";if(e.startsWith("connect."))return"connect_decision";if(e.startsWith("quality."))return"quality_receipt";if(e.startsWith("release."))return"release_receipt";if(e==="deployment.completed")return"deployment_receipt";if(e==="outcome.observed")return"outcome_observation";if(e==="evolution.proposed")return"evolution_proposal";return"runtime_evidence"}export const ContractSpecDeliveryTelemetryV2DocBlock={id:"contractspec-delivery-telemetry-v2",title:"ContractSpec engineering delivery telemetry V2",body:"The canonical delivery event taxonomy projects sanitized, HMAC-grouped operational evidence into the dedicated ContractSpec Engineering analytics project. Every event binds a delivery-plan digest and durable evidence reference. This projection measures the governed loop but can never authorize mutation, promotion, release, deployment, or evolution.",kind:"reference",route:"/docs/contracts/telemetry/delivery-v2",visibility:"public"};

package/dist/node/telemetry/index.d.js

@@ -0,0 +1 @@
+export*from"./anomaly.js";export*from"./delivery-v2.js";export*from"./spec.js";export*from"./tracker.js";export*from"./v2.js";

package/dist/node/telemetry/index.js

@@ -0,0 +1 @@
+export*from"./anomaly.js";export*from"./delivery-v2.js";export*from"./spec.js";export*from"./tracker.js";export*from"./v2.js";

package/dist/node/telemetry/spec.js

@@ -0,0 +1 @@
+const i=(e)=>`${e.key}.v${e.version}`;import{compareVersions as o}from"compare-versions";import{SpecContractRegistry as s}from"../registry.js";export class TelemetryRegistry extends s{eventsByKey=new Map;specByEventKey=new Map;constructor(e){super("telemetry",e);if(e)e.forEach((t)=>this.indexEvents(t))}register(e){super.register(e);this.indexEvents(e);return this}indexEvents(e){for(const t of e.events){this.eventsByKey.set(`${t.key}.v${t.version}`,t);this.specByEventKey.set(`${t.key}.v${t.version}`,e)}}findEventDef(e,t){if(t!=null)return this.eventsByKey.get(`${e}.v${t}`);let n;for(const r of this.eventsByKey.values()){if(r.key!==e)continue;if(!n||o(r.version,n.version)>0)n=r}return n}getSpecForEvent(e,t){return this.specByEventKey.get(`${e}.v${t}`)}}export function makeTelemetryKey(e){return i(e)}export const tech_contracts_telemetry_DocBlocks=[{id:"docs.tech.contracts.telemetry",title:"TelemetrySpec",summary:"Telemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/telemetry",tags:["tech","contracts","telemetry"],body:"## TelemetrySpec\n\nTelemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.\n\n- **File location**: `packages/libs/contracts/src/telemetry/spec.ts`\n- **Runtime tracker**: `packages/libs/contracts/src/telemetry/tracker.ts`\n- **Anomaly monitor**: `packages/libs/contracts/src/telemetry/anomaly.ts`\n\n### Core concepts\n\n```ts\nexport interface TelemetrySpec {\n  meta: TelemetryMeta;\n  events: TelemetryEventDef[];\n  config?: TelemetryConfig;\n}\n```\n\n- `meta`: ownership + identifiers (`name`, `version`, `domain`)\n- `events`: per-event semantics, property definitions, privacy level, retention, sampling, anomaly rules\n- `config`: defaults and provider configuration\n- `TelemetryRegistry`: registers specs, resolves latest version, finds event definitions by name/version\n\n### An example\n\n```ts\nexport const SigilTelemetry: TelemetrySpec = {\n  meta: {\n    name: 'sigil.telemetry',\n    version: '1.0.0',\n    title: 'Sigil telemetry',\n    description: 'Core Sigil product telemetry',\n    domain: 'sigil',\n    owners: ['@team.analytics'],\n    tags: ['telemetry'],\n    stability: StabilityEnum.Experimental,\n  },\n  config: {\n    defaultRetentionDays: 30,\n    defaultSamplingRate: 1,\n    providers: [\n      { type: 'posthog', config: { projectApiKey: process.env.POSTHOG_KEY } },\n    ],\n  },\n  events: [\n    {\n      name: 'sigil.telemetry.workflow_step',\n      version: '1.0.0',\n      semantics: {\n        what: 'Workflow step executed',\n        who: 'Actor executing the workflow',\n      },\n      privacy: 'internal',\n      properties: {\n        workflow: { type: 'string', required: true },\n        step: { type: 'string', required: true },\n        durationMs: { type: 'number' },\n        userId: { type: 'string', pii: true, redact: true },\n      },\n      anomalyDetection: {\n        enabled: true,\n        minimumSample: 10,\n        thresholds: [\n          { metric: 'durationMs', max: 1500 },\n        ],\n        actions: ['alert', 'trigger_regen'],\n      },\n    },\n  ],\n};\n```\n\n### Tracking events at runtime\n\n`TelemetryTracker` performs sampling, PII redaction, provider dispatch, and anomaly detection.\n\n```ts\nconst tracker = new TelemetryTracker({\n  registry: telemetryRegistry,\n  providers: [\n    {\n      id: 'posthog',\n      async send(dispatch) {\n        posthog.capture({\n          event: dispatch.name,\n          properties: dispatch.properties,\n          distinctId: dispatch.context.userId ?? dispatch.context.sessionId,\n        });\n      },\n    },\n  ],\n  anomalyMonitor: new TelemetryAnomalyMonitor({\n    onAnomaly(event) {\n      console.warn('Telemetry anomaly detected', event);\n    },\n  }),\n});\n\nawait tracker.track('sigil.telemetry.workflow_step', 1, {\n  workflow: 'onboarding',\n  step: 'verify_email',\n  durationMs: 2100,\n  userId: 'user-123',\n});\n```\n\n- Sampling obeys the event-specific rate (fallback to spec defaults)\n- Properties flagged with `pii` or `redact` are masked before dispatch\n- Anomaly monitor evaluates thresholds and triggers actions (e.g., log, alert, regeneration)\n\n### Spec integration\n\n- `ContractSpec.telemetry` allows operations to emit success/failure events automatically\n- `OperationSpecRegistry.execute()` uses the tracker when `ctx.telemetry` is provided\n- `WorkflowRunner` (Phase 4 follow-up) will emit telemetry during step transitions\n- `TelemetrySpec` events should reuse `EventSpec` names/versions to keep analytics/contract parity\n\n### CLI workflow\n\n```\ncontracts-cli create telemetry\n```\n\n- Interactive wizard prompts for meta, providers, events, properties, retention, anomaly rules\n- Output: `*.telemetry.ts` file using `TelemetrySpec`\n\n### Best practices\n\n- Prefer `internal` privacy for non-PII; mark PII properties explicitly with `pii` + `redact`\n- Keep sampling ≥0.05 except for high-volume events\n- Configure anomaly detection on key metrics (duration, error count, conversion)\n- Check telemetry into source control alongside contracts; regenerate via CLI when specs change\n\n### Next steps\n\n- Phase 5: Regenerator monitors telemetry anomalies to propose spec improvements\n- Phase 6: Studio surfaces telemetry controls per tenant via `TenantAppConfig`\n\n"}];

package/dist/node/telemetry/tracker.js

@@ -0,0 +1 @@
+function m(){return globalThis.crypto?.randomUUID?.()??`id_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,10)}`}const l=(e)=>{if(e==null)return e;if(typeof e==="string")return"REDACTED";if(typeof e==="number")return 0;if(typeof e==="boolean")return!1;if(Array.isArray(e))return e.map(()=>"REDACTED");if(typeof e==="object")return Object.fromEntries(Object.keys(e).map((t)=>[t,"REDACTED"]));return"REDACTED"};export class TelemetryTracker{providers=new Map;registry;anomalyMonitor;random;clock;constructor(e){this.registry=e.registry;this.anomalyMonitor=e.anomalyMonitor;this.random=e.random??Math.random;this.clock=e.clock??(()=>new Date);for(const t of e.providers??[])this.providers.set(t.id,t)}registerProvider(e){this.providers.set(e.id,e)}unregisterProvider(e){this.providers.delete(e)}async track(e,t,i,o={}){const r=this.registry.findEventDef(e,t);if(!r)return!1;const n=this.registry.getSpecForEvent(r.key,r.version);if(!n)return!1;if(!this.shouldSample(r.sampling??n.config?.defaultSamplingRate))return!1;const a=this.redactProperties(r,i),s={id:m(),name:r.key,version:r.version,occurredAt:this.clock().toISOString(),properties:a,privacy:r.privacy,context:o,tags:r.tags,spec:n,definition:r};await Promise.all([...this.providers.values()].map((c)=>c.send(s)));this.anomalyMonitor?.observe(s);return!0}shouldSample(e){if(typeof e==="number")return this.random()<e;if(!e)return!0;return this.random()<e.rate}redactProperties(e,t){const i={};for(const[o,r]of Object.entries(t)){const n=e.properties[o];if(!n){i[o]=r;continue}if(n.redact||n.pii||e.privacy==="sensitive")i[o]=l(r);else i[o]=r}return i}}

package/dist/node/telemetry/v2-primitives.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{deliveryDigestSchema as o,deliveryRefSchema as r,deliveryTimestampSchema as n}from"../delivery/primitives.js";export const TELEMETRY_SIGNAL_KINDS_V2=["logs","metrics","traces","analytics","flags","experiments","errors"],telemetrySignalKindV2Schema=e.enum(TELEMETRY_SIGNAL_KINDS_V2),telemetryDataClassV2Schema=e.enum(["public","internal","pseudonymous","personal","sensitive"]),telemetryPropertyHandlingV2Schema=e.enum(["allow","hmac_sha256","drop"]),telemetryPropertyDefV2Schema=e.object({type:e.enum(["string","number","boolean","timestamp","digest","ref"]),required:e.boolean(),classification:telemetryDataClassV2Schema,handling:telemetryPropertyHandlingV2Schema,description:e.string().trim().min(1).max(300),enumValues:e.array(e.string().min(1)).optional(),maximumLength:e.number().int().positive().optional()}).strict().superRefine((t,i)=>{if((t.classification==="personal"||t.classification==="pseudonymous")&&t.handling==="allow")i.addIssue({code:"custom",path:["handling"],message:"Personal and pseudonymous values cannot pass through raw"});if(t.classification==="sensitive"&&t.handling!=="drop")i.addIssue({code:"custom",path:["handling"],message:"Sensitive values must be dropped at the contract boundary"});if(t.enumValues&&t.type!=="string"&&t.type!=="ref")i.addIssue({code:"custom",path:["enumValues"],message:"Enum values are supported only for string or ref properties"})}),TELEMETRY_EVIDENCE_RELATIONS_V2=["delivery_plan","builder_receipt","connect_decision","quality_receipt","release_receipt","infrastructure_receipt","deployment_receipt","runtime_evidence","economic_evidence","outcome_observation","evolution_proposal"],telemetryEvidenceRelationV2Schema=e.enum(TELEMETRY_EVIDENCE_RELATIONS_V2),telemetryEvidenceLinkV2Schema=e.object({relation:telemetryEvidenceRelationV2Schema,ref:r,digest:o,observedAt:n}).strict(),telemetryPortBindingV2Schema=e.discriminatedUnion("mode",[e.object({mode:e.literal("enabled"),portRef:r,exportPolicyRef:r}).strict(),e.object({mode:e.literal("disabled"),reasonRef:r}).strict()]),telemetryConsentV2Schema=e.discriminatedUnion("mode",[e.object({mode:e.literal("required"),policyRef:r,deniedBehavior:e.literal("drop"),proofRefKind:r}).strict(),e.object({mode:e.literal("not_required"),policyRef:r,deniedBehavior:e.literal("drop"),rationaleRef:r}).strict()]),telemetryResidencyV2Schema=e.object({policyRef:r,allowedRegionRefs:e.array(r).min(1),crossRegionBehavior:e.enum(["deny","policy_bound"]),transferPolicyRef:r.optional()}).strict().superRefine((t,i)=>{if(t.crossRegionBehavior==="policy_bound"&&!t.transferPolicyRef)i.addIssue({code:"custom",path:["transferPolicyRef"],message:"Policy-bound transfer requires an explicit policy reference"});if(t.crossRegionBehavior==="deny"&&t.transferPolicyRef)i.addIssue({code:"custom",path:["transferPolicyRef"],message:"Denied cross-region transfer cannot name a transfer policy"})});

package/dist/node/telemetry/v2-validation.js

@@ -0,0 +1 @@
+import{addDeliveryDuplicateIssue as n}from"../delivery/primitives.js";export function validateTelemetrySpecV2(i,o){n(i.ownerBindingRefs,["ownerBindingRefs"],o);const t=i.events.map((e)=>`${e.key}@${e.version}`);n(t,["events"],o);const d=i.pseudonymization.groupBindings;n(d.map((e)=>e.kind),["pseudonymization","groupBindings"],o);for(const e of i.events){if(i.ports[e.signal].mode!=="enabled")o.addIssue({code:"custom",path:["ports",e.signal],message:`Signal port is disabled for ${e.key}`});for(const s of e.requiredEvidenceRelations)if(!i.evidenceLinks.allowedRelations.includes(s))o.addIssue({code:"custom",path:["events"],message:`Event requires disallowed evidence relation ${s}`});for(const s of d){const r=e.properties[s.propertyKey];if(r&&r.handling!=="hmac_sha256")o.addIssue({code:"custom",path:["events"],message:`Group property ${s.propertyKey} must be HMAC pseudonymized`})}}for(const e of i.evidenceLinks.requiredRelations)if(!i.evidenceLinks.allowedRelations.includes(e))o.addIssue({code:"custom",path:["evidenceLinks","requiredRelations"],message:`Required evidence relation is not allowed: ${e}`});n(i.redaction.forbiddenData,["redaction","forbiddenData"],o)}

package/dist/node/telemetry/v2.d.js

@@ -0,0 +1 @@
+export*from"./v2-primitives.js";export{validateTelemetrySpecV2}from"./v2-validation.js";

package/dist/node/telemetry/v2.js

@@ -0,0 +1 @@
+import{sha256Hex as l}from"@lssm/lib.crypto-utils";import{z as e}from"zod";import{addDeliveryDuplicateIssue as d,deliveryDigestSchema as y,deliveryRefSchema as r}from"../delivery/primitives.js";import{canonicalJsonString as u}from"../rich-reference/canonical-serializer.js";import{telemetryConsentV2Schema as f,telemetryEvidenceRelationV2Schema as a,telemetryPortBindingV2Schema as i,telemetryPropertyDefV2Schema as g,telemetryResidencyV2Schema as h,telemetrySignalKindV2Schema as v}from"./v2-primitives.js";import{validateTelemetrySpecV2 as s}from"./v2-validation.js";export const TELEMETRY_SPEC_V2="contractspec.telemetry.spec.v2",TELEMETRY_FORBIDDEN_DATA_V2=["raw_secret","raw_prompt","raw_payload","chain_of_thought","direct_personal_identifier"];const o=e.string().regex(/^[a-z][A-Za-z0-9_.]{0,127}$/).refine((t)=>!/(password|passphrase|secret|token|cookie|authorization|prompt|payload|reasoning|chainOfThought|email|phone|fullName)/i.test(t),"Property names cannot represent prohibited raw data");export const telemetryEventDefV2Schema=e.object({key:r,version:e.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/),signal:v,semantics:e.object({what:e.string().trim().min(1).max(300),why:e.string().trim().min(1).max(300)}).strict(),properties:e.record(o,g),requiredEvidenceRelations:e.array(a).min(1),retentionDays:e.number().int().positive()}).strict().superRefine((t,n)=>{if(Object.keys(t.properties).length===0)n.addIssue({code:"custom",path:["properties"],message:"Telemetry events require an explicit property contract"});d(t.requiredEvidenceRelations,["requiredEvidenceRelations"],n)});const c={schemaVersion:e.literal(TELEMETRY_SPEC_V2),id:r,version:e.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/),ownerBindingRefs:e.array(r).min(1),events:e.array(telemetryEventDefV2Schema).min(1),ports:e.object({logs:i,metrics:i,traces:i,analytics:i,flags:i,experiments:i,errors:i}).strict(),consent:f,residency:h,pseudonymization:e.object({algorithm:e.literal("hmac_sha256"),keyManagementPolicyRef:r,groupBindings:e.array(e.object({kind:e.enum(["tenant","workspace","subject"]),propertyKey:o,keyRef:r,rotationPolicyRef:r}).strict()).length(3)}).strict(),sampling:e.object({strategy:e.literal("deterministic_hash"),rate:e.number().min(0).max(1),unit:e.enum(["event","tenant","workspace","subject"]),seedRef:r}).strict(),budgets:e.object({cardinality:e.object({maximumEventKeys:e.number().int().positive(),maximumDistinctValuesPerProperty:e.number().int().positive()}).strict(),ingestion:e.object({maximumEventsPerMinute:e.number().int().positive(),maximumBytesPerMinute:e.number().int().positive()}).strict(),cost:e.object({currency:e.string().regex(/^[A-Z]{3}$/),maximumMonthlyAmount:e.number().finite().nonnegative(),evidenceRef:r}).strict()}).strict(),redaction:e.object({policyRef:r,failureBehavior:e.literal("drop_event"),forbiddenData:e.array(e.enum(TELEMETRY_FORBIDDEN_DATA_V2)).length(TELEMETRY_FORBIDDEN_DATA_V2.length)}).strict(),evidenceLinks:e.object({allowedRelations:e.array(a).min(1),requiredRelations:e.array(a).min(1),maximumLinksPerEvent:e.number().int().positive(),sanitizationPolicyRef:r}).strict()};export const telemetrySpecV2MaterialSchema=e.object(c).strict().superRefine(s),telemetrySpecV2Schema=e.object({...c,digest:y}).strict().superRefine((t,n)=>{s(t,n);const{digest:m,...p}=t;if(m!==digestTelemetrySpecV2(p))n.addIssue({code:"custom",path:["digest"],message:"Telemetry spec digest does not match canonical material"})});export function digestTelemetrySpecV2(t){return`sha256:${l(u(t))}`}export function defineTelemetrySpecV2(t){return telemetrySpecV2Schema.parse({...t,digest:digestTelemetrySpecV2(t)})}export const telemetrySpecV2DocBlock={id:"contractspec-telemetry-spec-v2",title:"Strict telemetry specification V2",body:"TelemetrySpecV2 is a provider-neutral, content-addressed contract for separate logs, metrics, traces, analytics, flags, experiments, and errors ports. It requires typed properties, consent, residency, deterministic sampling, HMAC-pseudonymized tenant/workspace/subject groups, cardinality/ingestion/cost budgets, sanitized evidence links, and fail-closed redaction. Raw secrets, prompts, payloads, reasoning, chain of thought, and direct personal identifiers are non-waivable forbidden data. Telemetry remains evidence projection, never promotion authority.",kind:"reference",route:"/docs/contracts/telemetry/spec-v2",visibility:"public"};export*from"./v2-primitives.js";export{validateTelemetrySpecV2}from"./v2-validation.js";

package/dist/node/tests/index.js

@@ -0,0 +1 @@
+export*from"./runner.js";export*from"./spec.js";

package/dist/node/tests/runner.js

@@ -0,0 +1 @@
+import{deepStrictEqual as l}from"assert";export class TestRunner{config;constructor(e){this.config=e}async run(e){const t=[];let r=0,s=0;for(const n of e.scenarios){await this.config.beforeEach?.(n);const o=await this.runScenario(e,n);t.push(o);if(o.status==="passed")r+=1;else s+=1;await this.config.afterEach?.(n,o)}return{spec:e,scenarios:t,passed:r,failed:s}}async runScenario(e,t){const r=[];try{const s=await this.createContext(),n=[...e.fixtures??[],...t.given??[]],o=[];for(const a of n)await this.executeOperation(a,s,o);const i=await this.executeOperation(t.when,s,o),u=t.then??[];for(const a of u){const p=this.evaluateAssertion(a,i,o);r.push(p)}const c=r.some((a)=>a.status==="failed");return{scenario:t,status:c?"failed":"passed",assertionResults:r}}catch(s){return{scenario:t,status:"failed",error:s,assertionResults:r}}}async createContext(){return{...await this.config.createContext?.()??{}}}async executeOperation(e,t,r){const s={...t,eventPublisher:async(n)=>{r.push({key:n.key,version:n.version,payload:n.payload});await t.eventPublisher?.(n)}};try{return{output:await this.config.registry.execute(e.operation.key,e.operation.version,e.input??null,s),events:r}}catch(n){return{error:n,events:r}}}evaluateAssertion(e,t,r){switch(e.type){case"expectOutput":return this.evaluateOutputAssertion(e,t);case"expectError":return this.evaluateErrorAssertion(e,t);case"expectEvents":return this.evaluateEventsAssertion(e,r);default:return{assertion:e,status:"failed",message:`Unknown assertion type ${e.type}`}}}evaluateOutputAssertion(e,t){if(t.error)return{assertion:e,status:"failed",message:`Expected output but operation threw error: ${t.error.message}`};try{l(t.output,e.match);return{assertion:e,status:"passed"}}catch(r){return{assertion:e,status:"failed",message:r instanceof Error?r.message:"Output assertion failed"}}}evaluateErrorAssertion(e,t){if(!t.error)return{assertion:e,status:"failed",message:"Expected an error but operation completed successfully"};if(e.messageIncludes&&!t.error.message.includes(e.messageIncludes))return{assertion:e,status:"failed",message:`Error message "${t.error.message}" did not include expected substring "${e.messageIncludes}"`};return{assertion:e,status:"passed"}}evaluateEventsAssertion(e,t){const r=[];for(const s of e.events){const o=t.filter((i)=>i.key===s.key&&i.version===s.version).length;if(typeof s.min==="number"&&o<s.min||typeof s.max==="number"&&o>s.max)r.push(`Event ${s.key}.v${s.version} occurred ${o} times (expected ${s.min??0} - ${s.max??"∞"})`);else if(typeof s.min>"u"&&typeof s.max>"u"&&o===0)r.push(`Event ${s.key}.v${s.version} did not occur`)}if(r.length>0)return{assertion:e,status:"failed",message:r.join("; ")};return{assertion:e,status:"passed"}}}

package/dist/node/tests/spec.js

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

package/dist/node/themes.d.js

@@ -0,0 +1 @@
+export{assertThemeSpecValid,ThemeValidationError,validateThemeSpec}from"./themes.validation.js";

package/dist/node/themes.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as a}from"./registry.js";export{assertThemeSpecValid,ThemeValidationError,validateThemeSpec}from"./themes.validation.js";export class ThemeRegistry extends a{constructor(e){super("theme",e)}}export function makeThemeRef(e){return{key:e.meta.key,version:e.meta.version}}export const defineTheme=(e)=>e,ContractSpecEditorialTheme=defineTheme({meta:{key:"contractspec.editorial",version:"1.0.0",title:"ContractSpec Editorial",description:"Warm paper, rust, amber, and slate-blue tokens shared by the public landing and CompanyOS light surfaces.",domain:"design-system",owners:["platform.design"],tags:["theme","marketing","companyos"],stability:"stable",scopes:["global","tenant"]},tokens:{colors:{paper:{value:"#f7f0e6",format:"hex",usage:"palette",description:"Warm paper canvas."},paperMuted:{value:"#efe4d3",format:"hex",usage:"palette",description:"Muted paper surface."},paperPanel:{value:"#fbf7f0",format:"hex",usage:"palette",description:"Raised panel surface."},ink:{value:"#1d1b18",format:"hex",usage:"palette",description:"Primary editorial text."},inkSoft:{value:"#5e564d",format:"hex",usage:"palette",description:"Secondary editorial text."},line:{value:"#d2c3ae",format:"hex",usage:"palette",description:"Warm separator line."},rust:{value:"#a24f2a",format:"hex",usage:"palette",description:"Primary brand action."},rustStrong:{value:"#854120",format:"hex",usage:"palette",description:"Primary hover/action emphasis."},amber:{value:"#d8a24a",format:"hex",usage:"palette",description:"Warm proof accent."},blue:{value:"#255678",format:"hex",usage:"palette",description:"Cool editorial accent."},success:{value:"#2d6a4f",format:"hex",usage:"palette",description:"Positive state accent."},background:{value:"#f7f0e6",format:"hex",usage:"semantic"},foreground:{value:"#1d1b18",format:"hex",usage:"semantic"},card:{value:"#fbf7f0",format:"hex",usage:"semantic"},cardForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},popover:{value:"#fbf7f0",format:"hex",usage:"semantic"},popoverForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},primary:{value:"#a24f2a",format:"hex",usage:"semantic"},primaryForeground:{value:"#fff8f0",format:"hex",usage:"semantic"},secondary:{value:"#efe4d3",format:"hex",usage:"semantic"},secondaryForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},muted:{value:"color-mix(in srgb, #efe4d3 78%, #ffffff 22%)",format:"css",usage:"semantic"},mutedForeground:{value:"#5e564d",format:"hex",usage:"semantic"},accent:{value:"#255678",format:"hex",usage:"semantic"},accentForeground:{value:"#eef7fb",format:"hex",usage:"semantic"},destructive:{value:"#b9372f",format:"hex",usage:"semantic"},destructiveForeground:{value:"#fff5f2",format:"hex",usage:"semantic"},successForeground:{value:"#f4faf6",format:"hex",usage:"semantic"},warning:{value:"#905a18",format:"hex",usage:"semantic"},warningForeground:{value:"#fff8f0",format:"hex",usage:"semantic"},info:{value:"#2b6688",format:"hex",usage:"semantic"},infoForeground:{value:"#eef7fb",format:"hex",usage:"semantic"},border:{value:"#d2c3ae",format:"hex",usage:"semantic"},input:{value:"color-mix(in srgb, #fbf7f0 70%, #ffffff 30%)",format:"css",usage:"semantic"},ring:{value:"color-mix(in srgb, #a24f2a 60%, #ffffff 40%)",format:"css",usage:"semantic"},chart1:{value:"#a24f2a",format:"hex",usage:"semantic"},chart2:{value:"#255678",format:"hex",usage:"semantic"},chart3:{value:"#d8a24a",format:"hex",usage:"semantic"},chart4:{value:"#7b4d2b",format:"hex",usage:"semantic"},chart5:{value:"#446b55",format:"hex",usage:"semantic"},sidebar:{value:"#fbf7f0",format:"hex",usage:"semantic"},sidebarForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},sidebarPrimary:{value:"#a24f2a",format:"hex",usage:"semantic"},sidebarPrimaryForeground:{value:"#fff8f0",format:"hex",usage:"semantic"},sidebarAccent:{value:"#efe4d3",format:"hex",usage:"semantic"},sidebarAccentForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},sidebarBorder:{value:"#d2c3ae",format:"hex",usage:"semantic"},sidebarRing:{value:"color-mix(in srgb, #255678 55%, #ffffff 45%)",format:"css",usage:"semantic"}},radii:{xs:{value:4,description:"Dense indicators, inner affordances, and precise low-emphasis geometry."},sm:{value:8,description:"Compact controls, chips, and assertive small surfaces."},md:{value:12,description:"Standard calm controls and interactive elements."},lg:{value:16,description:"Cards with editorial softness and approachable tone."},xl:{value:24,description:"Large panels, overlays, and low-pressure reading contexts."},full:{value:9999,description:"Capsules, avatars, pills, and status dots."},default:{value:20,description:"1.25rem editorial base radius preserved for existing --radius consumers."},control:{value:12,description:"Semantic alias for standard interactive controls."},card:{value:16,description:"Semantic alias for editorial cards and grouped content."},panel:{value:20,description:"Semantic alias for elevated panels and application chrome."},overlay:{value:24,description:"Semantic alias for modals, sheets, and preview overlays."},pill:{value:9999,description:"Semantic alias for explicit capsule forms."}}},modes:{dark:{description:"Landing-aligned dark mode overlay.",tokens:{colors:{background:{value:"#161412",format:"hex",usage:"semantic"},foreground:{value:"#f5ede2",format:"hex",usage:"semantic"},card:{value:"#211d19",format:"hex",usage:"semantic"},cardForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},popover:{value:"#211d19",format:"hex",usage:"semantic"},popoverForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},primary:{value:"#c46c43",format:"hex",usage:"semantic"},primaryForeground:{value:"#161412",format:"hex",usage:"semantic"},secondary:{value:"#2c2723",format:"hex",usage:"semantic"},secondaryForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},muted:{value:"#322c27",format:"hex",usage:"semantic"},mutedForeground:{value:"#cfbeb0",format:"hex",usage:"semantic"},accent:{value:"#79a8c6",format:"hex",usage:"semantic"},accentForeground:{value:"#101418",format:"hex",usage:"semantic"},destructive:{value:"#d75950",format:"hex",usage:"semantic"},destructiveForeground:{value:"#161412",format:"hex",usage:"semantic"},success:{value:"#6bbf99",format:"hex",usage:"semantic"},successForeground:{value:"#0d1f17",format:"hex",usage:"semantic"},warning:{value:"#e0a44a",format:"hex",usage:"semantic"},warningForeground:{value:"#2a1c08",format:"hex",usage:"semantic"},info:{value:"#7fb4d6",format:"hex",usage:"semantic"},infoForeground:{value:"#0a1820",format:"hex",usage:"semantic"},border:{value:"#433a34",format:"hex",usage:"semantic"},input:{value:"#2b2622",format:"hex",usage:"semantic"},ring:{value:"#c46c43",format:"hex",usage:"semantic"},sidebar:{value:"#1c1916",format:"hex",usage:"semantic"},sidebarForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},sidebarPrimary:{value:"#c46c43",format:"hex",usage:"semantic"},sidebarPrimaryForeground:{value:"#161412",format:"hex",usage:"semantic"},sidebarAccent:{value:"#2b2622",format:"hex",usage:"semantic"},sidebarAccentForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},sidebarBorder:{value:"#433a34",format:"hex",usage:"semantic"},sidebarRing:{value:"#79a8c6",format:"hex",usage:"semantic"}}}}}}),ContractSpecEditorialThemeCssVariables={"--paper":"#f7f0e6","--paper-muted":"#efe4d3","--paper-panel":"#fbf7f0","--ink":"#1d1b18","--ink-soft":"#5e564d","--line":"#d2c3ae","--rust":"#a24f2a","--rust-strong":"#854120","--amber":"#d8a24a","--blue":"#255678","--success":"#2d6a4f","--success-foreground":"#f4faf6","--warning":"#905a18","--warning-foreground":"#fff8f0","--info":"#2b6688","--info-foreground":"#eef7fb","--background":"var(--paper)","--foreground":"var(--ink)","--card":"var(--paper-panel)","--card-foreground":"var(--ink)","--popover":"var(--paper-panel)","--popover-foreground":"var(--ink)","--primary":"var(--rust)","--primary-foreground":"#fff8f0","--secondary":"var(--paper-muted)","--secondary-foreground":"var(--ink)","--muted":"color-mix(in srgb, var(--paper-muted) 78%, #ffffff 22%)","--muted-foreground":"var(--ink-soft)","--accent":"var(--blue)","--accent-foreground":"#eef7fb","--destructive":"#b9372f","--destructive-foreground":"#fff5f2","--border":"var(--line)","--input":"color-mix(in srgb, var(--paper-panel) 70%, #ffffff 30%)","--ring":"color-mix(in srgb, var(--rust) 60%, #ffffff 40%)","--chart-1":"var(--rust)","--chart-2":"var(--blue)","--chart-3":"var(--amber)","--chart-4":"#7b4d2b","--chart-5":"#446b55","--radius":"1.25rem","--radius-xs":"0.25rem","--radius-sm":"0.5rem","--radius-md":"0.75rem","--radius-lg":"1rem","--radius-xl":"1.5rem","--radius-full":"9999px","--radius-control":"var(--radius-md)","--radius-card":"var(--radius-lg)","--radius-panel":"var(--radius)","--radius-overlay":"var(--radius-xl)","--radius-pill":"var(--radius-full)","--sidebar":"var(--paper-panel)","--sidebar-foreground":"var(--ink)","--sidebar-primary":"var(--rust)","--sidebar-primary-foreground":"#fff8f0","--sidebar-accent":"var(--paper-muted)","--sidebar-accent-foreground":"var(--ink)","--sidebar-border":"var(--line)","--sidebar-ring":"color-mix(in srgb, var(--blue) 55%, #ffffff 45%)"},ContractSpecEditorialThemeDarkCssVariables={"--background":"#161412","--foreground":"#f5ede2","--card":"#211d19","--card-foreground":"#f5ede2","--popover":"#211d19","--popover-foreground":"#f5ede2","--primary":"#c46c43","--primary-foreground":"#161412","--secondary":"#2c2723","--secondary-foreground":"#f5ede2","--muted":"#322c27","--muted-foreground":"#cfbeb0","--accent":"#79a8c6","--accent-foreground":"#101418","--destructive":"#d75950","--destructive-foreground":"#161412","--success":"#6bbf99","--success-foreground":"#0d1f17","--warning":"#e0a44a","--warning-foreground":"#2a1c08","--info":"#7fb4d6","--info-foreground":"#0a1820","--border":"#433a34","--input":"#2b2622","--ring":"#c46c43","--sidebar":"#1c1916","--sidebar-foreground":"#f5ede2","--sidebar-primary":"#c46c43","--sidebar-primary-foreground":"#161412","--sidebar-accent":"#2b2622","--sidebar-accent-foreground":"#f5ede2","--sidebar-border":"#433a34","--sidebar-ring":"#79a8c6"},ContractSpecEditorialThemeHslVariables={"--background":"35 52% 94%","--foreground":"36 9% 10%","--card":"38 58% 96%","--card-foreground":"36 9% 10%","--popover":"38 58% 96%","--popover-foreground":"36 9% 10%","--primary":"19 59% 40%","--primary-foreground":"32 100% 97%","--secondary":"36 47% 88%","--secondary-foreground":"36 9% 10%","--muted":"35 48% 91%","--muted-foreground":"32 10% 34%","--accent":"205 53% 31%","--accent-foreground":"198 62% 96%","--destructive":"3 59% 45%","--destructive-foreground":"14 100% 97%","--success":"153 40% 30%","--success-foreground":"150 33% 97%","--warning":"33 71% 33%","--warning-foreground":"33 100% 97%","--info":"202 52% 35%","--info-foreground":"200 60% 96%","--border":"35 29% 75%","--input":"37 57% 97%","--ring":"18 39% 64%"},ContractSpecEditorialThemeDarkHslVariables={"--background":"30 10% 8%","--foreground":"35 49% 92%","--card":"30 14% 11%","--card-foreground":"35 49% 92%","--popover":"30 14% 11%","--popover-foreground":"35 49% 92%","--primary":"19 52% 52%","--primary-foreground":"30 10% 8%","--secondary":"27 11% 15%","--secondary-foreground":"35 49% 92%","--muted":"27 12% 17%","--muted-foreground":"27 24% 75%","--accent":"203 40% 63%","--accent-foreground":"210 20% 8%","--destructive":"4 63% 58%","--destructive-foreground":"30 10% 8%","--success":"153 40% 58%","--success-foreground":"156 40% 9%","--warning":"36 71% 58%","--warning-foreground":"36 68% 10%","--info":"203 51% 67%","--info-foreground":"206 53% 8%","--border":"24 13% 23%","--input":"27 12% 15%","--ring":"19 52% 52%"},ContractSpecEditorialThemeBodyBackground="linear-gradient(180deg, #f8f2e8 0%, #f7f0e6 38%, #f9f4ec 100%)",tech_contracts_themes_DocBlocks=[{id:"docs.tech.contracts.themes",title:"ThemeSpec Overview",summary:"`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts-spec`, making them accessible to generators, docs, and runtime tooling.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/themes",tags:["tech","contracts","themes"],body:'# ThemeSpec Overview\n\n## Purpose\n\n`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files.\n\n## Location\n\n- Types, helper, registry, and validation: `packages/libs/contracts-spec/src/themes.ts` and `packages/libs/contracts-spec/src/themes.validation.ts`\n- Design tokens bridge: `packages/libs/design-system/src/theme/*`\n\n## Schema\n\n```ts\nexport interface ThemeSpec {\n  meta: ThemeMeta;            // ownership metadata + { key, version, extends?, scopes? }\n  tokens: ThemeTokens;\n  components?: ComponentVariantSpec[];\n  overrides?: ThemeOverride[];\n  modes?: Record<string, ThemeModeSpec>; // use keys like "light" and "dark"\n}\n```\n\n- **ThemeMeta**\n  - `key`: fully-qualified identifier (for example `design.pastel`)\n  - `version`: semver string such as `1.0.0`\n  - `extends?`: optional `ThemeRef` to a base theme\n  - `scopes?`: default scopes where the theme applies (`global`, `tenant`, `user`)\n- **ThemeTokens**\n  - `colors`, `radii`, `space`, `typography`, `shadows`, `motion`\n  - each entry is a map of `{ value, description? }`\n  - the ContractSpec editorial radius taxonomy is additive and public: scale keys `xs/sm/md/lg/xl/full/default` plus semantic aliases `control/card/panel/overlay/pill`. Smaller radii communicate precision or higher action gravity; `md/control` is the normal control default; `lg/card`, `default/panel`, and `xl/overlay` provide progressively softer editorial surfaces; `full/pill` is reserved for capsules, avatars, and dots.\n  - persona-aware or RoleMorph-selected radius profiles are a future documentation hook only. This theme does not switch radius at runtime by persona, role, tone, or density.\n- **ComponentVariantSpec**\n  - `component`: design-system component key (for example `Button`, `NavMain`)\n  - `variants`: map of variant names to `{ props?, tokens? }`\n- **ThemeOverride**\n  - `scope`: `\'global\' | \'tenant\' | \'user\'`\n  - `target`: scoped identifier such as `tenant:artisanos` or `user:123`\n  - `tokens?` / `components?`: partial overrides for that target\n\n## Authoring\n\n```ts\nimport { defineTheme } from \'@lssm/lib.contracts-spec/themes\';\n\nexport const PastelTheme = defineTheme({\n  meta: {\n    key: \'design.pastel\',\n    version: \'1.0.0\',\n    title: \'Pastel\',\n    description: \'Soft pastel palette for marketing surfaces.\',\n    domain: \'design-system\',\n    owners: [\'platform.design\'],\n    tags: [\'theme\', \'marketing\'],\n    stability: \'experimental\',\n    scopes: [\'tenant\'],\n  },\n  tokens: {\n    colors: {\n      background: { value: \'#fdf2f8\', format: \'hex\', usage: \'semantic\' },\n      primary: {\n        value: \'oklch(0.72 0.11 221.19)\',\n        format: \'oklch\',\n        usage: \'semantic\',\n      },\n    },\n  },\n  modes: {\n    dark: {\n      tokens: {\n        colors: {\n          background: {\n            value: \'oklch(0.24 0.03 255)\',\n            format: \'oklch\',\n            usage: \'semantic\',\n          },\n          primary: {\n            value: \'oklch(0.64 0.15 246)\',\n            format: \'oklch\',\n            usage: \'semantic\',\n          },\n        },\n      },\n    },\n  },\n});\n```\n\n`tokens` stays the default/light-compatible token bag. Use `modes.dark.tokens` to overlay dark-mode values and preserve full CSS color strings such as OKLCH.\n\nUse `validateThemeSpec()` or `assertThemeSpecValid()` in CI and setup flows to catch duplicate overrides, empty targets, self-referential inheritance, invalid mode keys, and missing ownership metadata before publish time.\n\n## Registry Usage\n\n```ts\nimport { ThemeRegistry } from \'@lssm/lib.contracts-spec/themes\';\n\nconst themes = new ThemeRegistry();\nthemes.register(PastelTheme);\n\nconst theme = themes.get(\'design.pastel\', \'1.0.0\');\nconst tenantVariant = theme?.overrides?.find(\n  (override) => override.target === \'tenant:artisanos\'\n);\n```\n\nThe registry guarantees `key + version` uniqueness and exposes `list()` for discovery tooling.\n\n## Rendering\n\nThe design system consumes specs through adapters you provide:\n\n1. Resolve the base theme plus applicable overrides.\n2. Merge default tokens plus the selected light/dark mode token map using `ThemeTokens`.\n3. Feed the result into `mapTokensForPlatform` or the Tailwind bridge in `@lssm/lib.design-system`.\n\n```ts\nfunction resolveTokens(\n  registry: ThemeRegistry,\n  ref: ThemeRef,\n  ctx: { tenant?: string; user?: string }\n) {\n  const spec = registry.get(ref.key, ref.version);\n  if (!spec) throw new Error(\'Theme not found\');\n\n  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));\n  return mapTokensForPlatform(tokens);\n}\n```\n\n## CLI\n\n```\ncontractspec create theme\n```\n\nUse the theme wizard to scaffold a `.theme.ts` file that already imports and calls `defineTheme(...)`.\n'}];

package/dist/node/themes.platform-validation.js

@@ -0,0 +1 @@
+const l=/(?:https?:|data:|url\s*\(|@font-face|javascript:|<\/?(?:script|style))/i,m=/^\d+(?:\.\d+)?m?s$/;export function validatePlatformTokenGroups(e,s){const r=[];for(const[o,t]of Object.entries(e.fonts??{})){const n=t.value;if(!n?.web?.trim()||!n?.native?.trim()||l.test(n.web)||l.test(n.native))r.push(u(`${s}.fonts.${o}.value`,"Font tokens require local, non-executable web and native family names."))}for(const[o,t]of Object.entries(e.motion??{}))if(!m.test(t.value))r.push(u(`${s}.motion.${o}.value`,"Motion durations must be static ms or s values."));for(const[o,t]of Object.entries(e.density??{}))if(!c(t.value?.spacing)||!c(t.value?.size))r.push(u(`${s}.density.${o}.value`,"Density spacing and size must be positive finite numbers."));for(const[o,t]of Object.entries(e.elevation??{})){const n=t.value,i=n?.native;if(!n?.web?.trim()||l.test(n.web)||!i?.shadowColor?.trim()||!f(i.shadowOpacity)||!f(i.shadowRadius)||!f(i.elevation)||!a(i.shadowOffset?.width)||!a(i.shadowOffset?.height))r.push(u(`${s}.elevation.${o}.value`,"Elevation tokens require static web shadow text and a numeric native shadow descriptor."))}return r}function a(e){return typeof e==="number"&&Number.isFinite(e)}function c(e){return a(e)&&e>0}function f(e){return a(e)&&e>=0}function u(e,s){return{level:"error",message:s,path:e}}

package/dist/node/themes.validation.js

@@ -0,0 +1 @@
+import{validatePlatformTokenGroups as k}from"./themes.platform-validation.js";const y=new Set(["hex","rgb","hsl","oklch","css"]);export class ThemeValidationError extends Error{issues;constructor(t,e){super(t);this.issues=e;this.name="ThemeValidationError"}}export function validateThemeSpec(t){const e=[];b(t,e);S(t,e);d(t.tokens,e,"tokens");p(t.components,e,"components");g(t.modes,e,"modes");w(t.overrides,e);return{valid:e.every((n)=>n.level!=="error"),issues:e}}export function assertThemeSpecValid(t){const e=validateThemeSpec(t);if(!e.valid)throw new ThemeValidationError(`Theme ${t.meta.key}.v${t.meta.version} is invalid`,e.issues)}function b(t,e){const{meta:n}=t;l(n.key,"Theme must have a non-empty key","meta.key",e);l(n.version,"Theme must have a non-empty version","meta.version",e);l(n.title,"Theme must have a non-empty title","meta.title",e);l(n.description,"Theme must have a non-empty description","meta.description",e);l(n.domain,"Theme must have a non-empty domain","meta.domain",e);if(!n.stability)e.push({level:"error",message:"Theme must declare a stability level",path:"meta.stability"});if(!n.owners.length)e.push({level:"error",message:"Theme must declare at least one owner",path:"meta.owners"});if(!n.tags.length)e.push({level:"error",message:"Theme must declare at least one tag",path:"meta.tags"});if(n.extends&&n.extends.key===n.key&&n.extends.version===n.version)e.push({level:"error",message:"Theme cannot extend itself",path:"meta.extends"})}function S(t,e){if(u(t.tokens)||f(t.components)||T(t.modes)||O(t.overrides))return;e.push({level:"error",message:"Theme must declare tokens, components, or overrides with material configuration",path:"tokens"})}function d(t,e,n){if(!t)return;e.push(...k(t,n));for(const[o,r]of Object.entries(t)){if(r&&Object.keys(r).length===0)e.push({level:"warning",message:`Theme token group "${o}" is empty`,path:`${n}.${o}`});V(r,o,e,`${n}.${o}`)}}function V(t,e,n,o){if(!t||typeof t!=="object")return;const r=t;for(const[a,s]of Object.entries(r))if(e==="colors"&&s?.format&&!y.has(s.format))n.push({level:"warning",message:`Theme color token "${a}" declares unknown format "${s.format}"`,path:`${o}.${a}.format`})}function g(t,e,n){if(!t)return;for(const[o,r]of Object.entries(t)){const a=`${n}.${o}`;if(!o.trim()){e.push({level:"error",message:"Theme mode keys must be non-empty",path:n});continue}if(!v(r))e.push({level:"warning",message:`Theme mode "${o}" does not declare tokens or components`,path:a});d(r.tokens,e,`${a}.tokens`);p(r.components,e,`${a}.components`)}}function p(t,e,n){if(!t?.length)return;const o=new Set,r=new Map;t.forEach((a,s)=>{const h=`${n}[${s}]`,i=a.component.trim();if(!i){e.push({level:"error",message:"Theme component entries must declare a non-empty component key",path:`${h}.component`});return}if(o.has(i))e.push({level:"error",message:`Duplicate component "${i}" in theme`,path:`${h}.component`});o.add(i);const c=r.get(i)??new Set;for(const m of Object.keys(a.variants)){if(c.has(m))e.push({level:"error",message:`Duplicate variant "${m}" for component "${i}"`,path:`${h}.variants.${m}`});c.add(m);d(a.variants[m]?.tokens,e,`${h}.variants.${m}.tokens`)}r.set(i,c)})}function w(t,e){if(!t?.length)return;const n=new Set;t.forEach((o,r)=>{const a=`overrides[${r}]`,s=`${o.scope}:${o.target}`;if(!o.target.trim()){e.push({level:"error",message:"Theme override targets must be non-empty",path:`${a}.target`});return}if(n.has(s))e.push({level:"error",message:`Duplicate override for ${o.scope}:${o.target}`,path:a});n.add(s);if(M(o.scope,o.target))e.push({level:"warning",message:`Override target "${o.target}" does not look scoped for ${o.scope} overrides`,path:`${a}.target`});d(o.tokens,e,`${a}.tokens`);p(o.components,e,`${a}.components`);g(o.modes,e,`${a}.modes`)})}function u(t){if(!t)return!1;return Object.values(t).some((e)=>e!==void 0&&Object.keys(e).length>0)}function f(t){return Boolean(t?.length)}function v(t){return u(t?.tokens)||f(t?.components)}function T(t){return Boolean(Object.values(t??{}).some(v))}function O(t){return Boolean(t?.some((e)=>u(e.tokens)||f(e.components)||T(e.modes)))}function M(t,e){if(t==="global")return!1;return!e.startsWith(`${t}:`)}function l(t,e,n,o){if(t?.trim())return;o.push({level:"error",message:e,path:n})}

package/dist/node/translations/diagnostics.js

@@ -0,0 +1 @@
+import{findMissingTranslations as k,validateICUFormat as v,validateTranslationSpec as I}from"./validation.js";const _="en";export function analyzeTranslationCatalogGroup(a){return analyzeTranslationCatalogGroups([a])}export function analyzeTranslationCatalogGroups(a){const e=[];let t=0,o=0;for(const n of a){const r=S(n),l=x(n,e);t+=l.length;o+=l.reduce((c,m)=>c+Object.keys(m.messages).length,0);const i=r.expectedLocales??[...new Set(l.map((c)=>c.locale))].sort();L(l,i,n,e);z(l,n,e);P(l,n,e);w(l,n,e,r);C(l,n,e,r);M(l,n,e,r)}e.sort(A);const s=R(a.length,t,o,e);return{ok:s.errors===0&&(!a.some((n)=>n.strict)||s.warnings===0),summary:s,issues:e}}function S(a){return{baseLocale:a.baseLocale??_,expectedLocales:a.expectedLocales,allowExtraKeys:a.allowExtraKeys??!1,checkPlaceholders:a.checkPlaceholders??!0,checkIcu:a.checkIcu??!0,strict:a.strict??!1,checkMissingTranslation:a.checkMissingTranslation??!0,missingTranslationAllowlist:new Set(a.missingTranslationAllowlist??[])}}function x(a,e){return a.catalogs.flatMap((t,o)=>{const s=`${u(a)}catalogs[${o}]`;if(!d(t)){e.push({code:"invalid_catalog_shape",level:"error",path:s,message:"Translation catalog must be an object",context:g(a)});return[]}if(!d(t.meta)||typeof t.locale!=="string"||!d(t.messages)){e.push({code:"invalid_catalog_shape",level:"error",path:s,message:"Translation catalog must include object meta, string locale, and object messages",context:g(a)});return[]}const n={};for(const[r,l]of Object.entries(t.messages)){const i=`${s}.messages.${r}`;if(!d(l)||typeof l.value!=="string"){e.push({code:"invalid_message_shape",level:"error",specKey:typeof t.meta.key==="string"?t.meta.key:void 0,messageKey:r,locale:t.locale,path:i,message:`Message "${r}" must be an object with a string value`,context:g(a)});continue}if(!l.value.trim())e.push({code:"missing_value",level:"error",specKey:typeof t.meta.key==="string"?t.meta.key:void 0,messageKey:r,locale:t.locale,path:`${i}.value`,message:`Message "${r}" has an empty value`,context:g(a)});n[r]=l}return[{...t,messages:n}]})}function L(a,e,t,o){const s=new Set(a.map((n)=>n.locale));for(const n of e){if(s.has(n))continue;o.push({code:"missing_catalog",level:"error",locale:n,path:u(t),message:`Missing ${n} translation catalog`,context:g(t)})}if(e.length>0&&s.size!==e.length)o.push({code:"locale_non_parity",level:"error",path:u(t),message:`Catalog group has locales ${[...s].sort().join(", ")||"(none)"} but expected ${e.join(", ")}`,context:{...g(t),expectedLocales:e,actualLocales:[...s].sort()}})}function w(a,e,t,o){for(const s of a){const n=I(s);for(const r of n.issues){const l=r.message.includes("invalid ICU"),i=D(r.path);if(l&&(!o.checkIcu||j(s,i)))continue;t.push({code:K(r.path,l),level:r.level,specKey:s.meta.key,messageKey:i,locale:s.locale,path:`${u(e)}${s.meta.key}:${s.locale}.${r.path??""}`,message:r.message,context:g(e)})}}}function D(a){if(!a?.startsWith("messages."))return;return a.slice(9).replace(/\.(value|placeholders|variants|description).*$/,"")}function K(a,e){if(e)return"invalid_icu";if(a?.startsWith("messages."))return"invalid_message_shape";return"invalid_catalog_shape"}function C(a,e,t,o){const s=new Map;for(const n of a){const r=s.get(n.meta.key)??[];r.push(n);s.set(n.meta.key,r)}for(const[n,r]of s){const l=T(r,o.baseLocale);if(!l)continue;for(const i of r){if(i.locale===o.baseLocale)continue;for(const c of k(l,i))t.push({code:"missing_key",level:"error",specKey:n,messageKey:c.messageKey,locale:l.locale,targetLocale:i.locale,path:`${u(e)}${n}:${i.locale}.messages.${c.messageKey}`,message:`${i.locale} is missing translation key "${c.messageKey}" from ${l.locale}`,context:g(e)});for(const c of Object.keys(i.messages)){if(l.messages[c])continue;t.push({code:"extra_key",level:o.allowExtraKeys?"warning":"error",specKey:n,messageKey:c,locale:l.locale,targetLocale:i.locale,path:`${u(e)}${n}:${i.locale}.messages.${c}`,message:`${i.locale} has extra translation key "${c}" absent from ${l.locale}`,context:g(e)})}if(o.checkPlaceholders)O(l,i,e,t)}}}function M(a,e,t,o){if(!o.checkMissingTranslation)return;const s=new Map;for(const n of a){const r=s.get(n.meta.key)??[];r.push(n);s.set(n.meta.key,r)}for(const[n,r]of s){const l=T(r,o.baseLocale);if(!l)continue;for(const i of r){if(i.locale===o.baseLocale)continue;for(const[c,m]of Object.entries(l.messages)){const f=i.messages[c];if(!f)continue;const y=m.value.trim(),b=f.value.trim();if(y!==b)continue;if(G(c,y,o))continue;t.push({code:"missing_translation",level:"info",specKey:n,messageKey:c,locale:l.locale,targetLocale:i.locale,path:`${u(e)}${n}:${i.locale}.messages.${c}.value`,message:`${i.locale} value for "${c}" is identical to ${l.locale} — likely an untranslated English stub`,context:g(e)})}}}}function G(a,e,t){const o=t.missingTranslationAllowlist;if(o.has(a)||o.has(e))return!0;if(e.length===0)return!0;if(/^[\d\s\p{P}\p{S}]+$/u.test(e))return!0;if(/^https?:\/\/\S+$/u.test(e))return!0;return!1}function O(a,e,t,o){for(const[s,n]of Object.entries(a.messages)){const r=e.messages[s];if(!r)continue;const l=h(n),i=h(r);if(E(l,i))continue;o.push({code:"placeholder_non_parity",level:"error",specKey:a.meta.key,messageKey:s,locale:a.locale,targetLocale:e.locale,path:`${u(t)}${a.meta.key}:${e.locale}.messages.${s}.value`,message:`${e.locale} placeholders for "${s}" do not match ${a.locale}`,context:{...g(t),baseVariables:[...l].sort(),targetVariables:[...i].sort()}})}}function P(a,e,t){const o=new Set;for(const s of a){const n=`${s.meta.key}:${s.locale}:${s.meta.version}`;if(!o.has(n)){o.add(n);continue}t.push({code:"duplicate_bundle_identity",level:"error",specKey:s.meta.key,locale:s.locale,path:`${u(e)}${n}`,message:`Duplicate translation catalog identity ${n}`,context:g(e)})}}function z(a,e,t){const o=new Map;for(const s of a){const n=o.get(s.meta.key)??{present:new Set,claimed:new Set};n.present.add(s.locale);for(const r of s.supportedLocales??[])n.claimed.add(r);o.set(s.meta.key,n)}for(const[s,{present:n,claimed:r}]of o)for(const l of r)if(!n.has(l))t.push({code:"unsupported_locale_claim",level:"error",specKey:s,locale:l,path:`${u(e)}${s}:supportedLocales`,message:`Spec "${s}" claims to support locale "${l}" but no catalog exists for it`,context:g(e)})}export function validateManifestCatalogDrift(a,e){const t=e instanceof Set?e:new Set(e),o=[];for(const s of a)for(const n of s.specKeys)if(!t.has(n))o.push({code:"manifest_spec_key_missing",level:"error",specKey:n,path:`manifest:${s.route}:${n}`,message:`Manifest route "${s.route}" references specKey "${n}" which has no registered catalog`,context:{route:s.route}});return o}function h(a){const e=a.placeholders?.map((o)=>o.name)??[];if(e.length>0)return new Set(e);const t=v(a.value);return new Set([...t.placeholders,...t.plurals,...t.selects,...t.selectOrdinals])}function j(a,e){if(!e)return!1;const t=a.messages[e];if(!t)return!1;return/\{[^{}]*(,|:|"|'|\n)[^{}]*\}/.test(t.value)}function T(a,e){return a.find((t)=>t.locale===e)}function R(a,e,t,o){return{packages:a,catalogs:e,keys:t,errors:o.filter((s)=>s.level==="error").length,warnings:o.filter((s)=>s.level==="warning").length,infos:o.filter((s)=>s.level==="info").length}}function A(a,e){return p(a.path,e.path)||p(a.specKey,e.specKey)||p(a.messageKey,e.messageKey)||p(a.locale,e.locale)||p(a.targetLocale,e.targetLocale)||a.code.localeCompare(e.code)}function p(a,e){return(a??"").localeCompare(e??"")}function E(a,e){if(a.size!==e.size)return!1;for(const t of a)if(!e.has(t))return!1;return!0}function u(a){const e=[a.packagePath,a.catalogDir].filter(Boolean);return e.length>0?`${e.join("/")}:`:""}function g(a){return{packagePath:a.packagePath,catalogDir:a.catalogDir}}function d(a){return typeof a==="object"&&a!==null&&!Array.isArray(a)}

package/dist/node/translations/i18n-factory-snapshot.js

@@ -0,0 +1,20 @@
+export const I18N_FACTORY_HYDRATION_KIND="contractspec.i18n-factory.hydration",I18N_FACTORY_HYDRATION_VERSION=1;export function collectLocaleScopedCatalogs(a,t,s,i){const c=a.filter((o)=>o.meta.key===t),e=new Set,n=[s];if(i)n.push(i);while(n.length>0){const o=n.shift();if(!o||e.has(o))continue;e.add(o);for(const r of c){if(r.locale!==o)continue;if(r.fallback)n.push(r.fallback);for(const l of r.fallbacks??[])n.push(l);if(r.defaultLocale)n.push(r.defaultLocale)}}return c.filter((o)=>e.has(o.locale))}export function buildI18nFactorySnapshot(a){return{specKey:a.specKey,locale:a.locale,catalogs:collectLocaleScopedCatalogs(a.catalogs,a.specKey,a.locale,a.fallbackLocale)}}function y(a){return parseI18nFactorySnapshot(serializeI18nFactorySnapshot(a))}export function serializeI18nFactorySnapshot(a){return JSON.stringify(a)}export function parseI18nFactorySnapshot(a){return JSON.parse(a)}export function createI18nFactoryHydrationPayload(a){return{kind:I18N_FACTORY_HYDRATION_KIND,version:I18N_FACTORY_HYDRATION_VERSION,snapshot:y(a)}}export function serializeI18nFactoryHydrationPayload(a){return JSON.stringify(a)}export function validateI18nFactorySnapshot(a){const t=[];if(!a)return["i18n factory snapshot is missing."];if(!a.specKey)t.push("i18n factory snapshot specKey is missing.");if(!a.locale)t.push("i18n factory snapshot locale is missing.");if(!Array.isArray(a.catalogs))t.push("i18n factory snapshot catalogs must be an array.");return t}export function validateI18nFactoryHydrationPayload(a){const t=[];if(!a||a.kind!==I18N_FACTORY_HYDRATION_KIND)t.push("i18n factory hydration payload kind is invalid.");if(a?.version!==I18N_FACTORY_HYDRATION_VERSION)t.push("i18n factory hydration payload version is unsupported.");t.push(...validateI18nFactorySnapshot(a?.snapshot));return t}export function parseI18nFactoryHydrationPayload(a){const t=JSON.parse(a),s=validateI18nFactoryHydrationPayload(t);if(s.length>0)throw Error(s.join("; "));return createI18nFactoryHydrationPayload(t.snapshot)}export const I18nFactorySnapshotDocBlock={id:"docs.tech.translations.i18n-factory.snapshot",title:"i18n factory snapshot & hydration",summary:"Additive snapshot/serialization/hydration surface for the createI18nFactory stack.",kind:"reference",visibility:"public",route:"/docs/tech/translations/i18n-factory/snapshot",tags:["i18n","translations","ssr","hydration"],body:`# i18n factory snapshot & hydration
+
+The canonical, additive (behavior-compatible) snapshot/hydration surface on the
+\`createI18nFactory\` stack.
+
+- \`buildI18nFactorySnapshot\` produces a **locale-scoped** snapshot containing
+  only the catalogs needed to reproduce identical \`t()\` results for the locale
+  (the locale plus its declared fallback chain).
+- \`createI18nFactoryHydrationPayload\` wraps a snapshot in a versioned envelope
+  (\`kind\` = \`${I18N_FACTORY_HYDRATION_KIND}\`, \`version\` =
+  \`${I18N_FACTORY_HYDRATION_VERSION}\`) for SSR -> client transport.
+- \`parseI18nFactoryHydrationPayload\` validates and re-clones the payload.
+
+Reconstruct a factory from a snapshot or payload with
+\`createI18nFactoryFromSnapshot\` / \`createI18nFactoryFromHydrationPayload\`
+(see the \`i18n-factory\` module).
+
+Compatibility classification: **ADDITIVE**. No existing exported symbol or
+resolution behavior changes.
+`};

package/dist/node/translations/i18n-factory.js

@@ -0,0 +1 @@
+import{buildI18nFactorySnapshot as u,createI18nFactoryHydrationPayload as l,parseI18nFactoryHydrationPayload as I,validateI18nFactoryHydrationPayload as f}from"./i18n-factory-snapshot.js";import{TranslationRegistry as h}from"./registry.js";export const DEFAULT_LOCALE="en",SUPPORTED_LOCALES=["en","fr","es"];export function resolveLocale(t,r){const o=r??t??DEFAULT_LOCALE;if(isSupportedLocale(o))return o;const n=o.split("-")[0];if(n&&isSupportedLocale(n))return n;return DEFAULT_LOCALE}export function isSupportedLocale(t){return SUPPORTED_LOCALES.includes(t)}export function resolveLocaleWithin(t,r,o,n){const a=n??o??r;if(t.includes(a))return a;const e=a.split("-")[0];if(e&&t.includes(e))return e;return r}export function interpolate(t,r){if(!r)return t;return t.replace(/\{(\w+)\}/g,(o,n)=>{if(n in r)return String(r[n]);return o})}export function createI18nFactory(t){let r=null;const o=t.supportedLocales??SUPPORTED_LOCALES,n=t.defaultLocale??DEFAULT_LOCALE;function a(){if(!r)r=new h(t.catalogs);return r}const e={create(s,i){const c=resolveLocaleWithin(o,n,s,i),d=a();return{locale:c,t(y,g){const p=d.getValue(t.specKey,y,c,y);return interpolate(p,g)},snapshot(){return u({specKey:t.specKey,catalogs:t.catalogs,locale:c,fallbackLocale:n})},hydrationPayload(){return l(this.snapshot())}}},getDefault(){return e.create(n)},resetRegistry(){r=null},snapshot(s,i){return e.create(s,i).snapshot()},hydrationPayload(s,i){return e.create(s,i).hydrationPayload()}};return e}export function createI18nFactoryFromSnapshot(t){return createI18nFactory({specKey:t.specKey,catalogs:[...t.catalogs]})}export function createI18nFactoryFromHydrationPayload(t){if(typeof t==="string")return createI18nFactoryFromSnapshot(I(t).snapshot);const r=f(t);if(r.length>0)throw Error(r.join("; "));return createI18nFactoryFromSnapshot(l(t.snapshot).snapshot)}export const I18nFactoryDocBlock={id:"docs.tech.translations.i18n-factory",title:"i18n factory",summary:"Package-scoped i18n factory with additive snapshot/hydration support.",kind:"reference",visibility:"public",route:"/docs/tech/translations/i18n-factory",tags:["i18n","translations"],body:"# i18n factory\n\n`createI18nFactory` removes the per-package i18n boilerplate (interpolation,\nregistry management, locale resolution, `t()` wiring).\n\nInstances and factories additionally expose `snapshot()` and\n`hydrationPayload()`, and the module exports\n`createI18nFactoryFromSnapshot` / `createI18nFactoryFromHydrationPayload`\nto rebuild a factory on the client. These additions are **ADDITIVE** and do not\nchange resolution behavior for existing consumers.\n"};

package/dist/node/translations/index.d.js

@@ -0,0 +1 @@
+export*from"./diagnostics.js";export*from"./i18n-factory.js";export*from"./i18n-factory-snapshot.js";export*from"./locale.js";export*from"./registry.js";export*from"./spec.js";export*from"./tenant.js";export*from"./validation.js";

package/dist/node/translations/index.js

@@ -0,0 +1 @@
+export*from"./diagnostics.js";export*from"./i18n-factory.js";export*from"./i18n-factory-snapshot.js";export*from"./locale.js";export*from"./registry.js";export*from"./spec.js";export*from"./tenant.js";export*from"./validation.js";

package/dist/node/translations/locale.js

@@ -0,0 +1 @@
+export function canonicalizeTranslationLocale(a){const o=a.trim();if(!o)return{input:a,valid:!1,error:"Locale is empty"};try{const e=Intl.getCanonicalLocales(o)[0];return e?{input:a,locale:e,valid:!0}:{input:a,valid:!1,error:"Locale did not canonicalize"}}catch(e){return{input:a,valid:!1,error:e instanceof Error?e.message:"Invalid BCP 47 locale"}}}export function isValidTranslationLocale(a){return canonicalizeTranslationLocale(a).valid}

package/dist/node/translations/registry.js

@@ -0,0 +1 @@
+export class TranslationRegistry{specs=new Map;latestByLocale=new Map;locales=new Set;domains=new Set;constructor(e){if(e)for(const t of e)this.register(t)}register(e){const t=this.makeKey(e.meta.key,e.meta.version,e.locale);this.specs.set(t,e);const s=`${e.meta.key}:${e.locale}`,a=this.latestByLocale.get(s);if(!a||this.isNewerVersion(e.meta.version,a.meta.version))this.latestByLocale.set(s,e);this.locales.add(e.locale);this.domains.add(e.meta.domain)}get(e,t,s){return this.specs.get(this.makeKey(e,t,s))}getLatest(e,t){return this.latestByLocale.get(`${e}:${t}`)}getMessage(e,t,s,a){const n=a?this.get(e,a,s):this.getLatest(e,s);if(!n)return;return n.messages[t]}getWithFallback(e,t,s,a,n){const i=n?this.get(e,n,s):this.getLatest(e,s);if(i){const r=i.messages[t];if(r)return{spec:i,message:r,locale:s,fromFallback:!1};a=a??i.fallback}if(a&&a!==s){const r=n?this.get(e,n,a):this.getLatest(e,a);if(r){const o=r.messages[t];if(o)return{spec:r,message:o,locale:a,fromFallback:!0}}}return}getWithFallbackChain(e,t,s,a){const n=s[0];for(const i of s){const r=a?this.get(e,a,i):this.getLatest(e,i),o=r?.messages[t];if(r&&o)return{spec:r,message:o,locale:i,fromFallback:i!==n}}return}getValue(e,t,s,a){return this.getWithFallback(e,t,s)?.message.value??a??t}listLocales(e){const t=[];for(const[s,a]of this.specs.entries())if(s.startsWith(`${e}:`)){if(!t.includes(a.locale))t.push(a.locale)}return t}list(){return[...this.specs.values()]}listByLocale(e){return[...this.specs.values()].filter((t)=>t.locale===e)}listByDomain(e){return[...this.specs.values()].filter((t)=>t.meta.domain===e)}has(e,t,s){if(s)return this.specs.has(this.makeKey(e,s,t));return this.latestByLocale.has(`${e}:${t}`)}getLocales(){return this.locales}getDomains(){return this.domains}getStats(){let e=0;for(const t of this.specs.values())e+=Object.keys(t.messages).length;return{totalSpecs:this.specs.size,locales:[...this.locales],domains:[...this.domains],totalMessages:e}}clear(){this.specs.clear();this.latestByLocale.clear();this.locales.clear();this.domains.clear()}makeKey(e,t,s){return`${e}:${t}:${s}`}isNewerVersion(e,t){const s=(i)=>{const r=i.split(".").map(Number);return{major:r[0]??0,minor:r[1]??0,patch:r[2]??0}},a=s(e),n=s(t);if(a.major!==n.major)return a.major>n.major;if(a.minor!==n.minor)return a.minor>n.minor;return a.patch>n.patch}}

package/dist/node/translations/spec.js

@@ -0,0 +1 @@
+export function defineTranslation(e){return e}

package/dist/node/translations/validation.js

@@ -0,0 +1 @@
+import{parse as L,TYPE as d}from"@formatjs/icu-messageformat-parser";export function validateTranslationSpec(e){const n=[];x(e,n);S(e,n);y(e,"metadata",n);w(e,n);k(e,n);return{valid:n.filter((a)=>a.level==="error").length===0,issues:n}}function x(e,n){const{meta:a}=e;if(!a.key?.trim())n.push({level:"error",message:"Translation spec must have a non-empty key",path:"meta.key"});if(!a.version?.trim())n.push({level:"error",message:"Translation spec must have a non-empty version",path:"meta.version"});if(!a.domain?.trim())n.push({level:"error",message:"Translation spec must have a non-empty domain",path:"meta.domain"});if(!a.owners?.length)n.push({level:"warning",message:"Translation spec should specify owners",path:"meta.owners"})}function S(e,n){if(!e.locale?.trim())n.push({level:"error",message:"Translation spec must specify a locale",path:"locale"});else m(e.locale,"locale",n);if(e.fallback)m(e.fallback,"fallback",n);if(e.fallback===e.locale)n.push({level:"warning",message:"Fallback locale is the same as primary locale",path:"fallback"});for(const[a,t]of(e.fallbacks??[]).entries())m(t,`fallbacks[${a}]`,n);if(e.defaultLocale)m(e.defaultLocale,"defaultLocale",n);for(const[a,t]of(e.supportedLocales??[]).entries())m(t,`supportedLocales[${a}]`,n);O(e,n)}function w(e,n){const{messages:a}=e;if(!a||Object.keys(a).length===0){n.push({level:"warning",message:"Translation spec has no messages",path:"messages"});return}for(const[t,r]of Object.entries(a)){const l=`messages.${t}`;y(r,l,n);if(!r.value?.trim())n.push({level:"error",message:`Message "${t}" has an empty value`,path:`${l}.value`});const s=validateICUFormat(r.value),i=s.placeholders,c=r.placeholders??[];for(const o of c)if(!i.includes(o.name))n.push({level:"warning",message:`Placeholder "${o.name}" is defined but not used in message "${t}"`,path:`${l}.placeholders`});if(r.placeholders!==void 0){for(const o of i)if(!c.find((u)=>u.name===o))n.push({level:"info",message:`Placeholder "{${o}}" used in message "${t}" but not declared`,path:`${l}.placeholders`})}if(!s.valid)n.push({level:"error",message:`Message "${t}" has invalid ICU format: ${s.error}`,path:`${l}.value`});if(r.variants?.length){const o=new Set;for(const g of r.variants){const u=`${g.type}:${g.key}`;if(o.has(u))n.push({level:"warning",message:`Duplicate variant "${u}" in message "${t}"`,path:`${l}.variants`});o.add(u);if(!g.value?.trim())n.push({level:"error",message:`Variant "${u}" has an empty value in message "${t}"`,path:`${l}.variants`})}}if(r.maxLength!==void 0){if(r.maxLength<=0)n.push({level:"error",message:`Message "${t}" has invalid maxLength (must be positive)`,path:`${l}.maxLength`});else if(r.value.length>r.maxLength)n.push({level:"warning",message:`Message "${t}" value exceeds maxLength (${r.value.length} > ${r.maxLength})`,path:`${l}.value`})}}}function y(e,n,a){f(e.channels,`${n}.channels`,a);f(e.audience?.segments,`${n}.audience.segments`,a);f(e.audience?.personas,`${n}.audience.personas`,a);f(e.audience?.roles,`${n}.audience.roles`,a);f(e.audience?.tiers,`${n}.audience.tiers`,a);if(e.modality?.primary!==void 0)p(e.modality.primary,`${n}.modality.primary`,a);f(e.modality?.supported,`${n}.modality.supported`,a);if(e.safety?.redaction==="none"&&e.safety.containsSensitiveData)a.push({level:"warning",message:'Sensitive translation metadata should not declare redaction strategy "none"',path:`${n}.safety.redaction`});if(e.safety?.degradedFallbackKey!==void 0)p(e.safety.degradedFallbackKey,`${n}.safety.degradedFallbackKey`,a);if(e.rendering?.maxLength!==void 0){if(e.rendering.maxLength<=0)a.push({level:"error",message:"Translation rendering maxLength must be positive",path:`${n}.rendering.maxLength`})}if(e.rendering?.surface!==void 0)p(e.rendering.surface,`${n}.rendering.surface`,a);if(e.rendering?.target!==void 0)p(e.rendering.target,`${n}.rendering.target`,a)}function f(e,n,a){if(!e)return;for(const[t,r]of e.entries())p(r,`${n}[${t}]`,a)}function p(e,n,a){if(!e.trim())a.push({level:"error",message:"Translation metadata string values must be non-empty",path:n})}function k(e,n){if(!e.pluralRules?.length)return;for(let a=0;a<e.pluralRules.length;a++){const t=e.pluralRules[a];if(!t)continue;const r=`pluralRules[${a}]`;if(!t.variable?.trim())n.push({level:"error",message:"Plural rule must specify a variable name",path:`${r}.variable`});if(!t.rules?.length)n.push({level:"error",message:"Plural rule must have at least one category",path:`${r}.rules`});else if(!t.rules.some((s)=>s.category==="other"))n.push({level:"error",message:`Plural rule "${t.variable}" must have an "other" category`,path:`${r}.rules`})}}export function validateICUFormat(e){const n=I(e);if(n)return b(n);try{return M(L(e,{ignoreTag:!0,requiresOtherClause:!0,shouldParseSkeletons:!0}))}catch(a){return b(a instanceof Error?a.message:"Unknown error")}}function M(e){const n=new Set,a=new Set,t=new Set,r=new Set,l=(s)=>{for(const i of s){if("value"in i&&V(i.type))n.add(i.value);if("value"in i&&i.type===d.select)t.add(i.value);if("value"in i&&i.type===d.plural){n.add(i.value);if(i.pluralType==="ordinal")r.add(i.value);else a.add(i.value)}if("options"in i)for(const c of Object.values(i.options))l(c.value)}};l(e);return{valid:!0,placeholders:[...n],plurals:[...a],selects:[...t],selectOrdinals:[...r]}}function V(e){return e===d.argument||e===d.number||e===d.date||e===d.time||e===d.select||e===d.plural}function b(e){return{valid:!1,error:R(e),placeholders:[],plurals:[],selects:[],selectOrdinals:[]}}function R(e){if(e.includes("EXPECT_ARGUMENT_CLOSING_BRACE"))return"Unbalanced opening brace";if(e.includes("MISSING_OTHER_CLAUSE"))return'Plural/select/selectordinal messages must include an "other" branch';return e}function I(e){let n=0,a=!1;for(let t=0;t<e.length;t++){const r=e[t],l=t+1<e.length?e[t+1]:"";if(r==="'"){if(l==="'"){t++;continue}a=!a;continue}if(a)continue;if(r==="{")n++;if(r==="}"){n--;if(n<0)return"Unbalanced closing brace"}}return}export function findMissingTranslations(e,n){const a=[];for(const[t,r]of Object.entries(e.messages))if(!n.messages[t])a.push({messageKey:t,sourceLocale:e.locale,targetLocale:n.locale,sourceMessage:r});return a}export function findAllMissingTranslations(e,n,a){const t=new Map,r=e.getLatest(n,a);if(!r)return t;const l=e.listLocales(n);for(const s of l){if(s===a)continue;const i=e.getLatest(n,s);if(i){const c=findMissingTranslations(r,i);if(c.length>0)t.set(s,c)}}return t}export function validateTranslationRegistry(e){const n=[];for(const a of e.list()){const t=validateTranslationSpec(a);n.push(...t.issues.map((r)=>({...r,path:`${a.meta.key}.v${a.meta.version}:${a.locale}${r.path?`.${r.path}`:""}`})))}return{valid:n.filter((a)=>a.level==="error").length===0,issues:n}}export class TranslationValidationError extends Error{issues;constructor(e,n){super(e);this.issues=n;this.name="TranslationValidationError"}}export function assertTranslationSpecValid(e){const n=validateTranslationSpec(e);if(!n.valid)throw new TranslationValidationError(`Translation ${e.meta.key}.v${e.meta.version}:${e.locale} is invalid`,n.issues)}export function analyzeReadability(e,n){const a=n?.minSentenceWords??1,t=E(e).filter((h)=>F(h)>=a),r=v(e),l=Math.max(t.length,1),s=Math.max(r.length,1),i=r.reduce((h,T)=>h+P(T),0),c=s/l,o=i/s,g=206.835-1.015*c-84.6*o,u=parseFloat(Math.min(100,Math.max(0,g)).toFixed(2));return{fleschScore:u,gradeLabel:C(u),wordCount:s,sentenceCount:l,syllableCount:i,avgWordsPerSentence:parseFloat(c.toFixed(2)),avgSyllablesPerWord:parseFloat(o.toFixed(2))}}function C(e){if(e>=90)return"Very Easy";if(e>=80)return"Easy";if(e>=70)return"Fairly Easy";if(e>=60)return"Standard";if(e>=50)return"Fairly Difficult";if(e>=30)return"Difficult";return"Very Difficult"}function E(e){return e.split(/[.!?]+/).map((n)=>n.trim()).filter((n)=>n.length>0)}function v(e){return e.toLowerCase().replace(/[^a-z'\-\s]/gu," ").split(/\s+/).filter((n)=>n.length>0)}function F(e){return v(e).length}function P(e){const n=e.toLowerCase().replace(/[^a-z]/gu,"");if(n.length===0)return 0;if(n.length<=3)return 1;const a=n.endsWith("e")&&n.length>2?n.slice(0,-1):n;let t=0,r=!1;for(const l of a){const s="aeiouy".includes(l);if(s&&!r)t++;r=s}return Math.max(1,t)}export function checkKeywordDensity(e,n){const a=v(e),t=a.length;if(t===0)return{totalWords:0,entries:n.map((l)=>({keyword:l,count:0,density:0}))};const r=n.map((l)=>{const s=l.toLowerCase().trim(),i=a.filter((o)=>o===s).length,c=parseFloat((i/t*100).toFixed(2));return{keyword:l,count:i,density:c}});return{totalWords:t,entries:r}}export function canonicalizeLocale(e){if(K(e))return;try{return Intl.getCanonicalLocales(e)[0]}catch{return}}function K(e){return["arabic","chinese","english","french","japanese","spanish"].includes(e.trim().toLowerCase())}export function isValidLocaleFormat(e){return Boolean(canonicalizeLocale(e))}function m(e,n,a){const t=canonicalizeLocale(e);if(!t){a.push({level:"error",message:`Locale "${e}" is not a valid BCP 47 language tag`,path:n});return}if(t!==e)a.push({level:"info",message:`Locale "${e}" canonicalizes to "${t}"`,path:n,context:{canonical:t}})}function O(e,n){const a=canonicalizeLocale(e.locale)??e.locale,t=e.meta.key,r=a.replace(/-/g,"[-_.]");if(new RegExp(`(^|[-_.])${r}$`,"i").test(t))n.push({level:"warning",message:"Translation spec key appears to include the locale. Prefer a stable bundle key and keep locale in the locale field.",path:"meta.key",context:{locale:a}})}

package/dist/node/types.js

@@ -0,0 +1 @@
+export const CONTRACT_SPEC_TYPES=["operation","event","presentation","feature","capability","data-view","visualization","visual-scenario","form","agent","migration","workflow","experiment","integration","theme","design-pack","knowledge","telemetry","example","app-config","product-intent","policy","test-spec","harness-scenario","harness-suite","type","knowledge-space","job","translation","pwa-app","entity","edge"];const r=new Set(CONTRACT_SPEC_TYPES);export function isContractSpecType(e){return r.has(e)}

package/dist/node/utils/safe-json.js

@@ -0,0 +1 @@
+export function safeParseJson(e){try{return{ok:!0,data:JSON.parse(e)}}catch(r){return{ok:!1,error:r instanceof Error?r:Error(String(r))}}}

package/dist/node/versioning/index.d.js

@@ -0,0 +1 @@
+export*from"./refs.js";export*from"./release-types.js";export*from"./release-utils.js";export*from"./schema.js";export*from"./types.js";export*from"./utils.js";

package/dist/node/versioning/index.js

@@ -0,0 +1 @@
+export*from"./refs.js";export*from"./release-types.js";export*from"./release-utils.js";export*from"./schema.js";export*from"./types.js";export*from"./utils.js";

package/dist/node/versioning/refs.js

@@ -0,0 +1 @@
+export function isVersionedSpecRef(e){return typeof e==="object"&&e!==null&&"key"in e&&typeof e.key==="string"&&e.key.length>0&&"version"in e&&typeof e.version==="string"&&e.version.length>0}export function isOptionalVersionedSpecRef(e){if(typeof e!=="object"||e===null)return!1;if(!("key"in e))return!1;if(typeof e.key!=="string"||e.key.length===0)return!1;if("version"in e&&e.version!=null)return typeof e.version==="string";return!0}export function isSpecKeyRef(e){return typeof e==="object"&&e!==null&&"key"in e&&typeof e.key==="string"&&e.key.length>0}export function createVersionedRef(e,n){if(!e||e.trim().length===0)throw Error("Spec key cannot be empty");if(!n||n.trim().length===0)throw Error("Spec version cannot be empty");return{key:e.trim(),version:n.trim()}}export function createOptionalRef(e,n){if(!e||e.trim().length===0)throw Error("Spec key cannot be empty");const t={key:e.trim()};if(n!=null&&n.trim().length>0)t.version=n.trim();return t}export function createKeyRef(e){if(!e||e.trim().length===0)throw Error("Spec key cannot be empty");return{key:e.trim()}}export function formatVersionedRefKey(e){return`${e.key}.v${e.version}`}export function parseVersionedRefKey(e){const n=e.match(/^(.+)\.v(\d+\.\d+\.\d+(?:-.+)?)$/);if(!n)return;const t=n[1],r=n[2];if(!t||!r)return;return{key:t,version:r}}

package/dist/node/versioning/release-utils.js

@@ -0,0 +1 @@
+import{compareVersions as i}from"./utils.js";function o(n){if(n.version)return n.version;const r=n.packages.map((e)=>e.version).filter((e)=>typeof e==="string");if(r.length===0)return null;return r.reduce((e,t)=>i(t,e)===1?t:e)}export function sortReleaseManifest(n){return[...n.releases].sort((r,e)=>{const t=new Date(e.date).getTime()-new Date(r.date).getTime();if(t!==0)return t;const a=o(r),s=o(e);if(a&&s)return i(s,a);if(a)return-1;if(s)return 1;return r.slug.localeCompare(e.slug)})}export function countUpgradePlanStepLevels(n){return n.reduce((r,e)=>{r[e.level]+=1;return r},{auto:0,assisted:0,manual:0})}export function dedupeUpgradePlanSteps(n){const r=new Map;for(const e of n){const t=r.get(e.id);if(!t){r.set(e.id,{...e,instructions:[...e.instructions],packages:e.packages?[...e.packages]:void 0,autofixes:e.autofixes?[...e.autofixes]:void 0});continue}t.instructions=Array.from(new Set([...t.instructions,...e.instructions]));t.packages=Array.from(new Set([...t.packages??[],...e.packages??[]]));t.autofixes=Array.from(new Map([...t.autofixes??[],...e.autofixes??[]].map((a)=>[a.id,a])).values())}return Array.from(r.values())}export function createAgentPromptBundles(n,r,e){return r.map((t)=>({agent:t,title:`Upgrade guide for ${t}`,prompt:e(t,n)}))}

package/dist/node/versioning/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";export const VersionBumpTypeSchema=e.enum(["patch","minor","major"]),AgentTargetSchema=e.enum(["codex","opencode","claude-code"]),ReleaseEnforceOnSchema=e.enum(["release-branch","always","never"]),ReleaseAudienceKindSchema=e.enum(["maintainer","customer","integrator","agent"]),UpgradeStepLevelSchema=e.enum(["auto","assisted","manual"]),UpgradeAutofixKindSchema=e.enum(["package-json","contractsrc","import-rewrite","codemod"]),ReleaseImpactAudienceSchema=e.object({kind:ReleaseAudienceKindSchema,summary:e.string(),affectedPackages:e.array(e.string()).optional(),affectedRuntimes:e.array(e.string()).optional(),affectedFrameworks:e.array(e.string()).optional()}).strict(),ReleaseCapsulePackageSchema=e.object({name:e.string(),releaseType:VersionBumpTypeSchema,version:e.string().optional(),previousVersion:e.string().optional()}).strict(),MigrationInstructionSchema=e.object({id:e.string(),title:e.string(),summary:e.string(),required:e.boolean().default(!0),when:e.string().optional(),steps:e.array(e.string()).default([])}).strict(),UpgradeAutofixSchema=e.object({id:e.string(),kind:UpgradeAutofixKindSchema,title:e.string(),summary:e.string(),path:e.string().optional(),packageName:e.string().optional(),dependencyType:e.enum(["dependencies","devDependencies","peerDependencies"]).optional(),from:e.string().optional(),to:e.string().optional(),configPath:e.string().optional(),value:e.unknown().optional(),codemodId:e.string().optional()}),UpgradePlanStepSchema=e.object({id:e.string(),title:e.string(),summary:e.string(),level:UpgradeStepLevelSchema,instructions:e.array(e.string()).default([]),packages:e.array(e.string()).optional(),autofixes:e.array(UpgradeAutofixSchema).optional()}),AgentPromptBundleSchema=e.object({agent:AgentTargetSchema,title:e.string(),prompt:e.string()}),ReleaseCapsuleValidationSchema=e.object({commands:e.array(e.string()).default([]),evidence:e.array(e.string()).default([])}).strict(),ReleaseCapsuleSchema=e.object({schemaVersion:e.literal("1").default("1"),slug:e.string(),summary:e.string(),isBreaking:e.boolean().default(!1),packages:e.array(ReleaseCapsulePackageSchema).default([]),affectedRuntimes:e.array(e.string()).default([]),affectedFrameworks:e.array(e.string()).default([]),audiences:e.array(ReleaseImpactAudienceSchema).default([]),deprecations:e.array(e.string()).default([]),migrationInstructions:e.array(MigrationInstructionSchema).default([]),upgradeSteps:e.array(UpgradePlanStepSchema).default([]),validation:ReleaseCapsuleValidationSchema.default({commands:[],evidence:[]}),prompts:e.record(AgentTargetSchema,e.string()).optional()}).strict(),UpgradePackageTargetSchema=e.object({name:e.string(),currentVersion:e.string().optional(),targetVersion:e.string().optional()}),GeneratedReleaseManifestEntrySchema=e.object({slug:e.string(),version:e.string(),summary:e.string(),date:e.string(),isBreaking:e.boolean(),packages:e.array(ReleaseCapsulePackageSchema).default([]),affectedRuntimes:e.array(e.string()).default([]),affectedFrameworks:e.array(e.string()).default([]),audiences:e.array(ReleaseImpactAudienceSchema).default([]),deprecations:e.array(e.string()).default([]),migrationInstructions:e.array(MigrationInstructionSchema).default([]),upgradeSteps:e.array(UpgradePlanStepSchema).default([]),validation:ReleaseCapsuleValidationSchema.default({commands:[],evidence:[]})}),GeneratedReleaseManifestSchema=e.object({generatedAt:e.string(),releases:e.array(GeneratedReleaseManifestEntrySchema).default([])}),ReleaseIndexEntrySchema=e.object({slug:e.string(),version:e.string(),summary:e.string(),date:e.string(),isBreaking:e.boolean(),packageCount:e.number(),changeCount:e.number()}),ReleaseIndexSchema=e.object({generatedAt:e.string(),releases:e.array(ReleaseIndexEntrySchema).default([])}),ReleaseDetailSchema=GeneratedReleaseManifestEntrySchema,UpgradePlanSchema=e.object({generatedAt:e.string(),targetPackages:e.array(UpgradePackageTargetSchema).default([]),releases:e.array(GeneratedReleaseManifestEntrySchema).default([]),steps:e.array(UpgradePlanStepSchema).default([]),autofixCount:e.number().default(0),manualCount:e.number().default(0),assistedCount:e.number().default(0),agentPrompts:e.array(AgentPromptBundleSchema).default([])});

package/dist/node/versioning/types.js

@@ -0,0 +1 @@
+export function isChangelogDocBlock(e){return e.kind==="changelog"&&"specKey"in e&&"entries"in e}export function isVersionBumpType(e){return e==="patch"||e==="minor"||e==="major"}export function isChangeType(e){return typeof e==="string"&&["added","changed","fixed","removed","deprecated","breaking","security"].includes(e)}

package/dist/node/versioning/utils.js

@@ -0,0 +1 @@
+const a=/^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?(?:\+([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*))?$/;export function parseVersion(r){const e=r.trim().match(a);if(!e)return null;const n=e[1],t=e[2],o=e[3],i=e[4],s=e[5];if(!n||!t||!o)return null;return{major:parseInt(n,10),minor:parseInt(t,10),patch:parseInt(o,10),...i&&{prerelease:i},...s&&{build:s}}}export function parseVersionStrict(r){const e=parseVersion(r);if(!e)throw Error(`Invalid semantic version: "${r}"`);return e}export function formatVersion(r){let e=`${r.major}.${r.minor}.${r.patch}`;if(r.prerelease)e+=`-${r.prerelease}`;if(r.build)e+=`+${r.build}`;return e}export function compareVersions(r,e){const n=parseVersionStrict(r),t=parseVersionStrict(e);if(n.major!==t.major)return n.major>t.major?1:-1;if(n.minor!==t.minor)return n.minor>t.minor?1:-1;if(n.patch!==t.patch)return n.patch>t.patch?1:-1;if(n.prerelease&&!t.prerelease)return-1;if(!n.prerelease&&t.prerelease)return 1;if(n.prerelease&&t.prerelease)return n.prerelease<t.prerelease?-1:n.prerelease>t.prerelease?1:0;return 0}export function isVersionGreater(r,e){return compareVersions(r,e)===1}export function isVersionLess(r,e){return compareVersions(r,e)===-1}export function isVersionEqual(r,e){return compareVersions(r,e)===0}export function bumpVersion(r,e){const n=parseVersionStrict(r);switch(e){case"major":return formatVersion({major:n.major+1,minor:0,patch:0});case"minor":return formatVersion({major:n.major,minor:n.minor+1,patch:0});case"patch":return formatVersion({major:n.major,minor:n.minor,patch:n.patch+1})}}export function determineBumpType(r,e){if(r)return"major";if(e)return"minor";return"patch"}export function getBumpTypePriority(r){switch(r){case"major":return 3;case"minor":return 2;case"patch":return 1}}export function getMaxBumpType(r){if(r.length===0)return null;return r.reduce((e,n)=>getBumpTypePriority(n)>getBumpTypePriority(e)?n:e)}export function isValidVersion(r){return parseVersion(r)!==null}export function validateVersion(r){const e=[];if(!r||typeof r!=="string"){e.push("Version must be a non-empty string");return e}const n=r.trim();if(n!==r)e.push("Version should not have leading or trailing whitespace");if(!parseVersion(n))e.push(`Invalid semantic version format: "${r}". Expected format: MAJOR.MINOR.PATCH[-prerelease][+build]`);return e}

package/dist/node/visual-scenarios/index.js

@@ -0,0 +1 @@
+export{PlatformStorybookFeature,VisualTestingCapability}from"./platform.js";export{VisualScenarioRegistry}from"./registry.js";export{defineVisualScenario,VisualScenarioSpecDocBlock}from"./spec.js";export{validateVisualScenario}from"./validation.js";

package/dist/node/visual-scenarios/platform.js

@@ -0,0 +1 @@
+import{defineCapability as i}from"../capabilities/index.js";import{defineFeature as t}from"../features/index.js";import{VisualScenarioSpecDocBlock as o}from"./spec.js";export const VisualTestingCapability=i({meta:{key:"ui.visual-testing",version:"1.0.0",kind:"ui",title:"Visual testing",description:"Provider-neutral visual scenarios, component documentation, deterministic lifecycle and interaction bindings, accessibility policy, and snapshot intent.",domain:"ui-platform",owners:["platform.core"],tags:["ui","visual-testing","storybook"],stability:"experimental"}}),PlatformStorybookFeature=t({meta:{key:"platform.storybook",version:"1.0.0",title:"Storybook visual development platform",description:"Installs the provider-neutral capability consumed by Storybook integrations.",domain:"ui-platform",owners:["platform.core"],tags:["ui","visual-testing","storybook"],stability:"experimental"},capabilities:{provides:[{key:"ui.visual-testing",version:"1.0.0"}]},docs:[o.id]});

package/dist/node/visual-scenarios/registry.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as i}from"../registry.js";export class VisualScenarioRegistry extends i{constructor(e){super("visual-scenario",e)}}

package/dist/node/visual-scenarios/spec.js

@@ -0,0 +1 @@
+export function defineVisualScenario(e){return e}export const VisualScenarioSpecDocBlock={id:"docs.tech.contracts.visual-scenarios",title:"Visual scenario contracts",summary:"Provider-neutral, deterministic UI cases linked to React presentations.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/visual-scenarios",tags:["contracts","presentations","visual-testing"],body:"# Visual scenario contracts\n\nVisual scenarios describe named, deterministic UI cases independently of Storybook or any visual-diff provider. Each scenario references a React presentation and a stable product surface. Args, globals, and parameters remain JSON-compatible and may contain nested `{ $binding: string }` references resolved by a host-owned binding registry. Non-serializable components, decorators, setup hooks, and interactions are referenced by package-owned binding names.\n\nEvery scenario classifies captured data as `synthetic` or `sanitized`. A snapshot policy with `publish: true` is valid only when `capture.external` is explicitly `true`; omission always fails closed. Modes and render bindings are references and must resolve when their registries are supplied to validation.\n"};

package/dist/node/visual-scenarios/validation-authoring.js

@@ -0,0 +1 @@
+const c=new Set(["centered","fullscreen","padded"]);export function validateVisualAuthoring(i,e,n){s(i.componentBinding,e,"componentBinding",n);s(i.setupBinding,e,"setupBinding",n);f(i.decoratorBindings,e,"decoratorBindings",n);a(i.globals,e,"globals",n);a(i.parameters,e,"parameters",n);l(i.tags,"tags",n);g(i.layout,"layout",n);m(i,e,n);for(const[t,r]of i.cases.entries()){const o=`cases[${t}]`;s(r.setupBinding,e,`${o}.setupBinding`,n);s(r.interactionBinding,e,`${o}.interactionBinding`,n);f(r.decoratorBindings,e,`${o}.decoratorBindings`,n);a(r.globals,e,`${o}.globals`,n);a(r.parameters,e,`${o}.parameters`,n);l(r.tags,`${o}.tags`,n);g(r.layout,`${o}.layout`,n)}}function m(i,e,n){if(i.docs?.description!==void 0&&!i.docs.description.trim())n("Visual documentation description must not be empty","docs.description");const t=new Set;for(const[r,o]of(i.docs?.subcomponents??[]).entries()){const u=`docs.subcomponents[${r}]`;if(!o.name.trim())n("Subcomponent name must not be empty",`${u}.name`);else if(t.has(o.name))n(`Duplicate subcomponent ${o.name}`,u);t.add(o.name);s(o.binding,e,`${u}.binding`,n)}}function l(i,e,n){if(!i)return;if(new Set(i).size!==i.length)n("Visual tags must be unique",e);for(const[t,r]of i.entries()){if(!r.trim())n("Visual tag must not be empty",`${e}[${t}]`);if(r==="ai-generated")n("The ai-generated Storybook tag is forbidden",`${e}[${t}]`)}}function g(i,e,n){if(i!==void 0&&!c.has(i))n(`Unsupported visual layout ${i}`,e)}function f(i,e,n,t){if(!i)return;if(new Set(i).size!==i.length)t("Visual binding references must be unique",n);i.forEach((r,o)=>s(r,e,`${n}[${o}]`,t))}function a(i,e,n,t){if(!i)return;d(i,n,(r,o)=>s(r,e,o,t))}function d(i,e,n){if(i===null||typeof i!=="object")return;if("$binding"in i&&typeof i.$binding==="string"){n(i.$binding,`${e}.$binding`);return}if(Array.isArray(i)){i.forEach((t,r)=>d(t,`${e}[${r}]`,n));return}for(const[t,r]of Object.entries(i))d(r,`${e}.${t}`,n)}function s(i,e,n,t){if(i===void 0)return;if(!i.trim()){t("Visual binding must not be empty",n);return}if(!e.bindings)return;const r=e.bindings;if(!(typeof r.has==="function"?r.has(i):e.bindings.includes(i)))t(`Unresolved visual binding ${i}`,n)}