@lssm/lib.contracts-spec 17.3.2

package/dist/node/examples/schema.js

@@ -0,0 +1 @@
+import{z as e}from"zod";export const ExampleKindSchema=e.enum(["template","workflow","integration","knowledge","blueprint","ui","script","library"]),ExampleVisibilitySchema=e.enum(["public","internal","experimental"]),ExampleSandboxModeSchema=e.enum(["playground","specs","builder","markdown","evolution"]),StabilitySchema=e.enum(["idea","in_creation","experimental","beta","stable","deprecated"]),ExampleDocumentationSchema=e.object({rootDocId:e.string().optional(),goalDocId:e.string().optional(),usageDocId:e.string().optional(),referenceDocId:e.string().optional(),constraintsDocId:e.string().optional()}),ExampleSandboxSupportSchema=e.object({enabled:e.boolean(),modes:e.array(ExampleSandboxModeSchema)}),ExampleStudioSupportSchema=e.object({enabled:e.boolean(),installable:e.boolean()}),ExampleMcpSupportSchema=e.object({enabled:e.boolean()}),ExampleSurfacesSchema=e.object({templates:e.boolean(),sandbox:ExampleSandboxSupportSchema,studio:ExampleStudioSupportSchema,mcp:ExampleMcpSupportSchema}),ExampleEntrypointsSchema=e.object({packageName:e.string().min(1),feature:e.string().optional(),blueprint:e.string().optional(),presentations:e.string().optional(),contracts:e.string().optional(),handlers:e.string().optional(),ui:e.string().optional(),docs:e.string().optional()}),ExampleMetaSchema=e.object({version:e.string(),key:e.string().min(1),title:e.string().optional(),description:e.string().min(1),domain:e.string().optional(),stability:StabilitySchema,owners:e.array(e.string()),tags:e.array(e.string()),docId:e.array(e.string()).optional(),kind:ExampleKindSchema,visibility:ExampleVisibilitySchema,summary:e.string().optional()}),SpecPointerSchema=e.object({key:e.string().min(1),version:e.string().optional()}),FeatureRefSchema=e.object({key:e.string().min(1)}),ExampleSpecSchema=e.object({meta:ExampleMetaSchema,docs:ExampleDocumentationSchema.optional(),surfaces:ExampleSurfacesSchema,entrypoints:ExampleEntrypointsSchema,blueprint:e.union([e.record(e.string(),e.unknown()),SpecPointerSchema]).optional(),features:e.array(e.union([e.record(e.string(),e.unknown()),FeatureRefSchema])).optional()});export function parseExampleSpec(n){return ExampleSpecSchema.parse(n)}export function safeParseExampleSpec(n){return ExampleSpecSchema.safeParse(n)}export function parseExampleMeta(n){return ExampleMetaSchema.parse(n)}export function parseExampleSurfaces(n){return ExampleSurfacesSchema.parse(n)}export function parseExampleEntrypoints(n){return ExampleEntrypointsSchema.parse(n)}export function parseExampleDocumentation(n){return ExampleDocumentationSchema.parse(n)}

package/dist/node/examples/types.js

@@ -0,0 +1 @@
+export const ExampleKindEnum={Template:"template",Workflow:"workflow",Integration:"integration",Knowledge:"knowledge",Blueprint:"blueprint",UI:"ui",Script:"script",Library:"library"},ExampleVisibilityEnum={Public:"public",Internal:"internal",Experimental:"experimental"},ExampleSandboxModeEnum={Playground:"playground",Specs:"specs",Builder:"builder",Markdown:"markdown",Evolution:"evolution"};export function isSpecPointer(e){if(!e)return!1;return"key"in e&&!("meta"in e)}export function isFeatureRef(e){return"key"in e&&!("meta"in e)}export function isExampleKind(e){return typeof e==="string"&&Object.values(ExampleKindEnum).includes(e)}export function isExampleVisibility(e){return typeof e==="string"&&Object.values(ExampleVisibilityEnum).includes(e)}

package/dist/node/examples/validation.js

@@ -0,0 +1 @@
+import{safeParseExampleSpec as n}from"./schema.js";export function validateExample(e){const a=[],s=[],t=n(e);if(!t.success){for(const r of t.error.issues)a.push({exampleKey:e?.meta?.key,message:r.message,path:r.path.join("."),code:r.code});return{valid:!1,errors:a,warnings:s}}const i=t.data;l(i,a,s);return{valid:a.length===0,errors:a,warnings:s}}function l(e,a,s){const t=e.meta.key;if(!e.entrypoints.packageName.startsWith("@"))s.push({exampleKey:t,message:"Package name should be scoped (e.g., @lssm/example.name)",path:"entrypoints.packageName"});if(e.surfaces.studio.installable&&!e.surfaces.studio.enabled)a.push({exampleKey:t,message:"Studio installable requires studio.enabled to be true",path:"surfaces.studio",code:"STUDIO_INSTALLABLE_REQUIRES_ENABLED"});if(e.surfaces.sandbox.enabled&&e.surfaces.sandbox.modes.length===0)s.push({exampleKey:t,message:"Sandbox is enabled but has no modes configured",path:"surfaces.sandbox.modes"});if(e.features&&e.features.length>0&&!e.entrypoints.feature)s.push({exampleKey:t,message:"Example has features but no feature entrypoint in entrypoints.feature",path:"entrypoints.feature"});if(e.blueprint&&!e.entrypoints.blueprint)s.push({exampleKey:t,message:"Example has blueprint but no blueprint entrypoint in entrypoints.blueprint",path:"entrypoints.blueprint"});if(e.meta.visibility==="public"&&e.meta.stability==="idea")s.push({exampleKey:t,message:'Public examples should not be in "idea" stability',path:"meta.stability"})}export function validateExamples(e){const a=[],s=new Set,t=[];for(const i of e){if(s.has(i.meta.key)){a.push({exampleKey:i.meta.key,message:`Duplicate example key: ${i.meta.key}`,code:"DUPLICATE_KEY"});continue}s.add(i.meta.key);const r=validateExample(i);if(!r.valid)a.push(...r.errors);else t.push(i)}if(a.length>0)return{ok:!1,errors:a};return{ok:!0,examples:t}}export function validateExampleReferences(e,a){const s=[],t=[],i=e.meta.key;if(a.packageNames&&!a.packageNames.has(e.entrypoints.packageName))t.push({exampleKey:i,message:`Package "${e.entrypoints.packageName}" not found in workspace`,path:"entrypoints.packageName"});if(e.features&&a.featureKeys){for(const r of e.features)if("key"in r&&!("meta"in r)){if(!a.featureKeys.has(r.key))t.push({exampleKey:i,message:`Feature "${r.key}" not found in registry`,path:"features"})}}if(e.blueprint&&a.blueprintKeys){if("key"in e.blueprint&&!("meta"in e.blueprint)){if(!a.blueprintKeys.has(e.blueprint.key))t.push({exampleKey:i,message:`Blueprint "${e.blueprint.key}" not found in registry`,path:"blueprint"})}}return{valid:s.length===0,errors:s,warnings:t}}

package/dist/node/experience-coverage/index.js

@@ -0,0 +1 @@
+export{scoreExperienceFeature}from"./scoring.js";export{defineExperienceCoverage,EXPERIENCE_COVERAGE_CONTRACT_KEY,EXPERIENCE_COVERAGE_CONTRACT_VERSION}from"./types.js";export{validateExperienceCoverage}from"./validation.js";

package/dist/node/experience-coverage/scoring.js

@@ -0,0 +1 @@
+export function scoreExperienceFeature(n){if(n.applicability==="not_applicable")return a("not_applicable",100,[],[]);const o=[...new Set(n.requiredEvidence)],r=o.filter((t)=>l(n,t)),i=o.filter((t)=>!r.includes(t)),c=o.length===0?0:Math.round(r.length/o.length*100);if(n.blockers.some((t)=>t.kind==="external"&&t.status==="open"))return a("blocked_external",c,r,i);const s=n.blockers.some((t)=>t.status==="open"),e=n.evidence.length>0&&n.evidence.every((t)=>t.mode==="fixture"||t.state!=="verified");if(n.visibility==="internal_read_only"&&e)return a("fixture_only",c,r,i);const d=n.providerRefs.length===0||r.includes("production_canary");if(i.length===0&&o.length>0&&d&&!s&&n.qualificationStatus!=="unqualified")return a("live_verified",100,r,i);if(r.includes("implementation"))return a("implemented_unverified",c,r,i);if(r.includes("contract"))return a("contract_only",c,r,i);return a("stub",c,r,i)}function l(n,o){const r=n.evidence.filter((e)=>e.layer===o&&e.mode==="real"),i=r.filter((e)=>e.observedAt!==void 0);if(i.length===0)return r.some((e)=>e.state==="verified");const c=i.map((e)=>({item:e,observedAt:Date.parse(e.observedAt)}));if(c.some((e)=>!Number.isFinite(e.observedAt)))return!1;const s=Math.max(...c.map((e)=>e.observedAt));return c.filter((e)=>e.observedAt===s).every((e)=>e.item.state==="verified")}function a(n,o,r,i){return{status:n,completionPercent:o,verifiedLayers:r,missingLayers:i}}

package/dist/node/experience-coverage/types.js

@@ -0,0 +1 @@
+export const EXPERIENCE_COVERAGE_CONTRACT_KEY="contractspec.experience.coverage",EXPERIENCE_COVERAGE_CONTRACT_VERSION="1.0.0";export function defineExperienceCoverage(e){return e}

package/dist/node/experience-coverage/validation.js

@@ -0,0 +1 @@
+export function validateExperienceCoverage(e){const i=[],n=d(e.modules,"modules",i),s=d(e.features,"features",i),r=d(e.journeys,"journeys",i);for(const o of e.modules)for(const t of o.featureIds)a(s,t,`modules.${o.id}.featureIds`,i);for(const o of e.features){a(n,o.moduleId,`features.${o.id}.moduleId`,i);for(const t of o.journeyRefs)a(r,t,`features.${o.id}.journeyRefs`,i);c(o,e,i)}for(const o of e.journeys)for(const t of o.featureRefs)a(s,t,`journeys.${o.id}.featureRefs`,i);return i}function c(e,i,n){if(e.exposure&&!e.authModes||!e.exposure&&e.authModes)n.push({code:"invalid_actor_context",path:`features.${e.id}.authModes`,message:"Structured exposure and authModes must be declared together."});if(e.exposure&&e.authModes){const o=e.exposure==="customer"?["anonymous","authenticated_customer"]:e.exposure==="system"?["service"]:["operator"];if(e.authModes.length===0||e.authModes.some((t)=>!o.includes(t)))n.push({code:"invalid_actor_context",path:`features.${e.id}.authModes`,message:`${e.exposure} exposure has incompatible authentication modes.`});for(const t of i.journeys.filter((u)=>e.journeyRefs.includes(u.id)))if(t.exposure!==e.exposure||JSON.stringify(t.authModes)!==JSON.stringify(e.authModes))n.push({code:"invalid_actor_context",path:`journeys.${t.id}.authModes`,message:"Journey actor semantics must match the feature projection."})}if(e.qualificationStatus==="qualified"&&e.deliveryStage!=="qualified"||e.deliveryStage==="qualified"&&e.qualificationStatus!=="qualified")n.push({code:"invalid_qualification_status",path:`features.${e.id}.qualificationStatus`,message:"Qualified experience status must match its delivery stage."});for(const o of e.routes)if(!o.startsWith("/"))n.push({code:"invalid_route",path:`features.${e.id}.routes`,message:`Route ${o} must start with '/'.`});if(e.actionable&&e.visibility==="internal_read_only")n.push({code:"fixture_mutation",path:`features.${e.id}.visibility`,message:"Actionable features cannot be internal read-only fixtures."});if(e.providerRefs.length>0&&!e.requiredEvidence.includes("production_canary"))n.push({code:"provider_canary_missing",path:`features.${e.id}.requiredEvidence`,message:"Provider-backed features must require production-canary evidence."});const s=new Set(i.journeys.filter((o)=>e.journeyRefs.includes(o.id)).map((o)=>o.variant)),r=e.actionable?["happy","recovery","denial"]:["happy"];for(const o of r)if(!s.has(o))n.push({code:"missing_journey_variant",path:`features.${e.id}.journeyRefs`,message:`Feature ${e.id} requires a ${o} journey.`})}function d(e,i,n){const s=new Set;for(const r of e){if(s.has(r.id))n.push({code:"duplicate_id",path:i,message:`Duplicate id ${r.id}.`});s.add(r.id)}return s}function a(e,i,n,s){if(!e.has(i))s.push({code:"unknown_reference",path:n,message:`Unknown reference ${i}.`})}

package/dist/node/experiments/evaluator.js

@@ -0,0 +1 @@
+export class ExperimentEvaluator{registry;policyChecker;expressionEvaluator;constructor(t){this.registry=t.registry;this.policyChecker=t.policyChecker;this.expressionEvaluator=t.expressionEvaluator}async chooseVariant(t){const e=this.registry.get(t.experiment,t.version);if(!e)return null;const r=e.variants.find((n)=>n.id===e.controlVariant);if(!r)throw Error(`Experiment ${e.meta.key} missing control variant ${e.controlVariant}`);switch(e.allocation.type){case"random":return{variant:this.pickByWeight(e,this.randomSeed(t,e.allocation.salt)),reason:"random"};case"sticky":return{variant:this.pickByWeight(e,this.stickySeed(t,e.allocation.attribute,e.allocation.salt)),reason:"sticky"};case"targeted":{const n=await this.evaluateTargeting(e,t,e.allocation.rules);if(n)return{variant:n,reason:"targeted"};if(e.allocation.fallback==="random")return{variant:this.pickByWeight(e,this.randomSeed(t)),reason:"random"};return{variant:r,reason:"control"}}default:return{variant:r,reason:"control"}}}pickByWeight(t,e){const r=t.variants,n=r.reduce((o,s)=>o+(s.weight??1),0),a=e*n;let i=0;for(const o of r){i+=o.weight??1;if(a<=i)return o}return r[r.length-1]}randomSeed(t,e=""){const r=t.sessionId??t.userId??t.organizationId??`${Date.now()}-${Math.random()}`;return this.hashToUnitInterval(r+e)}stickySeed(t,e,r=""){const n=t[e];if(!n)return this.randomSeed(t,r);return this.hashToUnitInterval(`${n}-${r}`)}hashToUnitInterval(t){let e=2166136261;for(let n=0;n<t.length;n+=1){e^=t.charCodeAt(n);e=Math.imul(e,16777619)}return(e>>>0)%1e6/1e6}async evaluateTargeting(t,e,r){for(const n of r){if(!await this.matchesRule(n,e))continue;const a=t.variants.find((i)=>i.id===n.variantId);if(!a)continue;if(typeof n.percentage==="number"){if(this.randomSeed(e,`rule-${n.variantId}`)>n.percentage)continue}return a}return null}async matchesRule(t,e){if(t.policy&&this.policyChecker){if(!await this.policyChecker(t.policy,e))return!1}if(t.expression){if(this.expressionEvaluator)return Boolean(this.expressionEvaluator(t.expression,e));try{const r=Function("context",`return (${t.expression});`);return Boolean(r(e))}catch(r){return!1}}return!0}}

package/dist/node/experiments/spec.js

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

package/dist/node/feature-hubs/federation.js

@@ -0,0 +1 @@
+export const HUB_FEDERATION_CANONICALIZATION="RFC8785";

package/dist/node/feature-hubs/index.js

@@ -0,0 +1 @@
+export*from"./federation.js";export*from"./policy.js";export*from"./ports.js";export*from"./registry.js";export*from"./social-media.js";export*from"./types.js";

package/dist/node/feature-hubs/social-provider-v2.js

@@ -0,0 +1,14 @@
+export const SocialProviderV2DocBlock={id:"docs.tech.social-provider-v2",title:"Scoped social publication providers",summary:"Versioned provider execution carries tenant identity and durable local publication keys.",visibility:"public",kind:"reference",route:"/docs/tech/social-provider-v2",tags:["social","marketing"],body:`# Scoped social publication providers
+
+V2 publication and status ports require tenant identity, account identity and a durable
+local idempotency key. Native API idempotency support is independent of that local key.
+Integrations must bind content, credentials and provider resources to the requested tenant
+before dispatch. Partial or uncertain publication remains ambiguous. Multi-part adapters receive the
+named publishing grant and recheck it before every part. Optional resume crosses fresh
+authority and a fenced canonical continuation claim; status never publishes pending work.
+
+The social runtime supports an explicit providersV2 map while preserving its legacy
+providers map. V2 takes precedence when configured; failures do not fall back to another
+publisher. Resolve legacy ambiguous receipts before switching provider implementations,
+or supply an explicitly authorized compatibility reader. Draft-only remains the default.
+`};

package/dist/node/feature-hubs/social-scheduling-operations.js

@@ -0,0 +1,17 @@
+import{fromZod as e}from"@lssm/lib.schema";import{z as t}from"zod";import{defineFeature as d}from"../features/index.js";import{defineCommand as a,defineQuery as l}from"../operations/index.js";import{SocialScheduleBatchResultSchema as m,SocialScheduleInputSchema as h,SocialScheduleRecordSchema as r,SocialScheduleScopeSchema as u}from"./social-scheduling.js";const c=(o,s)=>({key:o,title:s,version:"1.0.0",description:s,goal:s,context:"Durable LinkedIn/X scheduling reuses canonical social publication grants, intents and recovery.",owners:["@platform/social"],tags:["social","scheduling"],domain:"social-media",stability:"experimental"});export const SocialScheduleLookupSchema=t.strictObject({scope:u,id:t.string().min(1).max(200)}),SocialScheduleCancelSchema=SocialScheduleLookupSchema.extend({version:t.number().int().positive()}),SocialScheduleDueSchema=t.strictObject({scope:u,limit:t.number().int().min(1).max(100)});const i=e(r,{name:"SocialScheduleRecordV1"}),n=e(SocialScheduleLookupSchema,{name:"SocialScheduleLookupV1"});export const SocialScheduleCreateCommand=a({meta:c("social-media.schedule.create","Schedule an approved social revision"),io:{input:e(h,{name:"SocialScheduleInputV1"}),output:i},policy:{auth:"user"},execution:{effects:["write"],approval:{required:!0}},transport:{rest:{method:"POST",path:"/marketing/social/schedules"},mcp:{toolName:"marketing_schedule_social"}}}),SocialScheduleCancelCommand=a({meta:c("social-media.schedule.cancel","Cancel an unclaimed social schedule"),io:{input:e(SocialScheduleCancelSchema,{name:"SocialScheduleCancelV1"}),output:i},policy:{auth:"user"},execution:{effects:["write"]},transport:{rest:{method:"POST",path:"/marketing/social/schedules/cancel"},mcp:{toolName:"marketing_cancel_social_schedule"}}}),SocialScheduleDispatchCommand=a({meta:c("social-media.schedule.dispatch","Dispatch due social targets under current authority"),io:{input:n,output:i},policy:{auth:"user"},execution:{effects:["write","external-side-effect"],approval:{required:!0}},transport:{rest:{method:"POST",path:"/marketing/social/schedules/dispatch"},mcp:{toolName:"marketing_dispatch_social_schedule"}}}),SocialScheduleContinueCommand=a({meta:c("social-media.schedule.continue","Continue an interrupted schedule through canonical publication intents"),io:{input:n,output:i},policy:{auth:"user"},execution:{effects:["write","external-side-effect"],approval:{required:!0}},transport:{rest:{method:"POST",path:"/marketing/social/schedules/continue"},mcp:{toolName:"marketing_continue_social_schedule"}}}),SocialScheduleReconcileCommand=a({meta:c("social-media.schedule.reconcile","Read-reconcile scheduled publication outcomes"),io:{input:n,output:i},policy:{auth:"user"},execution:{effects:["read","write"]},transport:{rest:{method:"POST",path:"/marketing/social/schedules/reconcile"},mcp:{toolName:"marketing_reconcile_social_schedule"}}}),SocialScheduleGetQuery=l({meta:c("social-media.schedule.get","Read a scoped social schedule"),io:{input:n,output:i},policy:{auth:"user"},execution:{effects:["read"]},transport:{rest:{method:"POST",path:"/marketing/social/schedules/get"},mcp:{toolName:"marketing_get_social_schedule"}}}),SocialScheduleDueQuery=l({meta:c("social-media.schedule.due","Read due schedules in one scope"),io:{input:e(SocialScheduleDueSchema,{name:"SocialScheduleDueV1"}),output:e(t.array(r).max(100),{name:"SocialScheduleDueResultV1"})},policy:{auth:"user"},execution:{effects:["read"]},transport:{rest:{method:"POST",path:"/marketing/social/schedules/due"},mcp:{toolName:"marketing_due_social_schedules"}}}),SocialScheduleRunDueCommand=a({meta:c("social-media.schedule.run-due","Run a bounded scoped batch of due publications"),io:{input:e(SocialScheduleDueSchema,{name:"SocialScheduleBatchInputV1"}),output:e(m,{name:"SocialScheduleBatchResultV1"})},policy:{auth:"user"},execution:{effects:["read","write","external-side-effect"],approval:{required:!0}},transport:{rest:{method:"POST",path:"/marketing/social/schedules/run-due"},mcp:{toolName:"marketing_run_due_social_schedules"}}}),socialSchedulingOperations=[SocialScheduleRunDueCommand,SocialScheduleCreateCommand,SocialScheduleCancelCommand,SocialScheduleDispatchCommand,SocialScheduleContinueCommand,SocialScheduleReconcileCommand,SocialScheduleGetQuery,SocialScheduleDueQuery],SocialSchedulingFeature=d({meta:{key:"social-media.scheduling-v1",version:"1.0.0",title:"Durable social scheduling",description:"Reviewed LinkedIn/X schedules backed by canonical publication intents.",domain:"social-media",owners:["@platform/social"],tags:["social"],stability:"experimental"},operations:socialSchedulingOperations.map((o)=>({key:o.meta.key,version:o.meta.version}))}),SocialSchedulingDocBlock={id:"docs.tech.social-scheduling",title:"Durable social scheduling",summary:"Reviewed LinkedIn/X scheduling with canonical publication intents and SQL recovery.",visibility:"public",kind:"reference",route:"/docs/tech/social-scheduling",tags:["social","marketing"],body:`# Durable social scheduling
+
+The feature-hubs/social-scheduling contracts add immutable LinkedIn/X schedules.
+Eight operations cover scheduling, cancellation, due scans, dispatch, continuation,
+reconciliation, scoped reads and bounded worker batches. Publication stays behind the
+existing SocialPublicationRuntime and its grant, digest, policy and effect gates.
+The default remains draft-only until a host explicitly configures publication authority.
+
+SQL adapters preserve schedules, canonical publication intents, append-only history
+and fenced recovery leases. Cancellation cannot erase a claimed publication. Expired
+windows do not dispatch, and confirmed outcomes remain immutable. Interrupted workers
+may continue under fresh authority while canonical idempotency prevents duplicate posts.
+
+Register workers through the existing lifecycle scheduler and persist batch outcomes
+through the supplied host observer. Native LinkedIn/X provider and account qualification,
+real media publication and application cutover remain separate acceptance requirements.
+`};

package/dist/node/feature-hubs/social-scheduling.js

@@ -0,0 +1 @@
+import{z as t}from"zod";const o=t.string().trim().min(1).max(200);export const SocialScheduleScopeSchema=t.strictObject({tenantId:o,workspaceId:o,brandId:o}),SocialScheduleTargetSchema=t.strictObject({platform:t.enum(["linkedin","x"]),accountId:o}),SocialScheduleInputSchema=t.strictObject({id:o,scope:SocialScheduleScopeSchema,contentRevisionId:o.describe("One canonical publication per revision/account; a repost requires a new reviewed revision."),contentDigest:t.string().regex(/^sha256:[a-f0-9]{64}$/),grantRef:o,targets:t.array(SocialScheduleTargetSchema).min(1).max(20),publishAt:t.iso.datetime(),expiresAt:t.iso.datetime(),timeZone:t.string().min(1).refine((e)=>{try{new Intl.DateTimeFormat("en",{timeZone:e});return!0}catch{return!1}})}).superRefine((e,i)=>{if(Date.parse(e.expiresAt)<=Date.parse(e.publishAt))i.addIssue({code:"custom",message:"Publication window is empty."});if(new Set(e.targets.map((a)=>JSON.stringify(a))).size!==e.targets.length)i.addIssue({code:"custom",message:"Publication targets are duplicated."})}),SocialScheduledOutcomeSchema=SocialScheduleTargetSchema.extend({state:t.enum(["pending","dispatching","confirmed","failed","reconciliation_required"]),idempotencyKey:o,replayRef:o,providerRequestId:o.optional(),reasonCode:o.optional()}),SocialScheduleRecordSchema=t.strictObject({schemaVersion:t.literal(1),input:SocialScheduleInputSchema,version:t.number().int().positive(),state:t.enum(["scheduled","dispatching","confirmed","failed","partial","reconciliation_required","cancelled","expired"]),outcomes:t.array(SocialScheduledOutcomeSchema).max(20),createdAt:t.iso.datetime(),updatedAt:t.iso.datetime()}).superRefine((e,i)=>{const a=e.outcomes.length===e.input.targets.length,n=e.outcomes.filter((c)=>c.state==="confirmed").length,s=e.outcomes.filter((c)=>c.state==="failed").length;if(["scheduled","cancelled","expired"].includes(e.state)&&e.outcomes.length!==0||e.state==="failed"&&(!a||s!==e.outcomes.length)||e.state==="partial"&&(!a||!n||!s||n+s!==e.outcomes.length))i.addIssue({code:"custom",message:"Schedule state does not match its per-target outcomes."});const l=e.outcomes.map((c)=>`${c.platform}:${c.accountId}`);if(new Set(l).size!==l.length||e.outcomes.some((c)=>!e.input.targets.some((r)=>r.platform===c.platform&&r.accountId===c.accountId)))i.addIssue({code:"custom",message:"Outcome target binding is invalid."});if(e.state==="confirmed"&&(e.outcomes.length!==e.input.targets.length||e.outcomes.some((c)=>c.state!=="confirmed")))i.addIssue({code:"custom",message:"All targets must confirm before a schedule is confirmed."})}),SocialScheduleBatchResultSchema=t.array(t.strictObject({id:o,state:t.enum([...SocialScheduleRecordSchema.shape.state.options,"blocked"]),reasonCode:o.optional()})).max(100);

package/dist/node/feature-hubs/types.js

@@ -0,0 +1 @@
+export const FEATURE_HUB_PROTOCOL_VERSION="1.0.0";

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

@@ -0,0 +1 @@
+export{installFeature}from"./install.js";export{FeatureRegistry}from"./registry.js";export{defineFeature}from"./types.js";export{validateBundleRequires}from"./validate-bundle-requires.js";export{assertFeatureSpecValid,FeatureValidationError,validateFeatureSpec,validateFeatureTargetsV2}from"./validation.js";

package/dist/node/features/index.js

@@ -0,0 +1 @@
+export{installFeature}from"./install.js";export{FeatureRegistry}from"./registry.js";export{defineFeature}from"./types.js";export{validateBundleRequires}from"./validate-bundle-requires.js";export{assertFeatureSpecValid,FeatureValidationError,validateFeatureSpec,validateFeatureTargetsV2}from"./validation.js";

package/dist/node/features/install.js

@@ -0,0 +1 @@
+export function installFeature(e,i){if(i.ops&&e.operations){for(const o of e.operations)if(!i.ops.get(o.key,o.version))throw Error(`installFeature: operation not found ${o.key}.v${o.version}`)}if(i.presentations&&e.presentations){for(const o of e.presentations)if(!i.presentations.get(o.key,o.version))throw Error(`installFeature: presentation not found ${o.key}.v${o.version}`)}if(e.presentationsTargets&&i.descriptors)for(const o of e.presentationsTargets){const t=i.descriptors.find((r)=>r.meta.key===o.key&&r.meta.version===o.version);if(!t)throw Error(`installFeature: V2 descriptor not found ${o.key}.v${o.version}`);for(const r of o.targets)if(!t.targets.includes(r))throw Error(`installFeature: descriptor ${o.key}.v${o.version} missing target ${r}`)}if(e.opToPresentation&&e.opToPresentation.length>0)for(const o of e.opToPresentation){if(i.ops){if(!i.ops.get(o.op.key,o.op.version))throw Error(`installFeature: linked op not found ${o.op.key}.v${o.op.version}`)}if(i.presentations){if(!i.presentations.get(o.pres.key,o.pres.version))throw Error(`installFeature: linked presentation not found ${o.pres.key}.v${o.pres.version}`)}}if(i.capabilities&&e.capabilities?.provides){for(const o of e.capabilities.provides)if(!i.capabilities.get(o.key,o.version))throw Error(`installFeature: capability not registered ${o.key}.v${o.version}`)}if(e.capabilities?.requires?.length){if(!i.capabilities)throw Error(`installFeature: capability registry required to validate capability requirements for ${e.meta.key}`);const o=e.capabilities.provides??[];for(const t of e.capabilities.requires)if(!i.capabilities.satisfies(t,o))throw Error(`installFeature: capability requirement not satisfied ${t.key}${t.version?`.v${t.version}`:""}`)}if(i.dataViews&&e.dataViews){for(const o of e.dataViews)if(!i.dataViews.get(o.key,o.version))throw Error(`installFeature: data view not found ${o.key}.v${o.version}`)}if(i.visualizations&&e.visualizations){for(const o of e.visualizations)if(!i.visualizations.get(o.key,o.version))throw Error(`installFeature: visualization not found ${o.key}.v${o.version}`)}if(i.visualScenarios&&e.visualScenarios){for(const o of e.visualScenarios)if(!i.visualScenarios.get(o.key,o.version))throw Error(`installFeature: visual scenario not found ${o.key}.v${o.version}`)}if(i.forms&&e.forms){for(const o of e.forms)if(!i.forms.get(o.key,o.version))throw Error(`installFeature: form not found ${o.key}.v${o.version}`)}if(i.workflows&&e.workflows){for(const o of e.workflows)if(!i.workflows.get(o.key,o.version))throw Error(`installFeature: workflow not found ${o.key}.v${o.version}`)}if(i.knowledge&&e.knowledge){for(const o of e.knowledge)if(!i.knowledge.get(o.key,o.version))throw Error(`installFeature: knowledge space not found ${o.key}.v${o.version}`)}if(i.telemetry&&e.telemetry){for(const o of e.telemetry)if(!i.telemetry.get(o.key,o.version))throw Error(`installFeature: telemetry spec not found ${o.key}.v${o.version}`)}if(i.policies&&e.policies){for(const o of e.policies)if(!i.policies.get(o.key,o.version))throw Error(`installFeature: policy not found ${o.key}.v${o.version}`)}if(i.integrations&&e.integrations){for(const o of e.integrations)if(!i.integrations.get(o.key,o.version))throw Error(`installFeature: integration not found ${o.key}.v${o.version}`)}if(i.jobs&&e.jobs){for(const o of e.jobs)if(!i.jobs.get(o.key,o.version))throw Error(`installFeature: job not found ${o.key}.v${o.version}`)}if(i.translations&&e.translations)for(const o of e.translations){const t=i.translations.listLocales(o.key);if(t.length===0)throw Error(`installFeature: translation not found ${o.key}.v${o.version}`);if(o.locale&&!t.includes(o.locale))throw Error(`installFeature: translation locale ${o.locale} not found for ${o.key}.v${o.version}`)}i.features.register(e);return i.features}

package/dist/node/features/registry.js

@@ -0,0 +1 @@
+import{filterBy as r,getUniqueTags as i,groupBy as s}from"../registry-utils.js";function u(e){return e.meta.key}export class FeatureRegistry{items=new Map;register(e){const t=u(e);if(this.items.has(t))throw Error(`Duplicate feature ${t}`);this.items.set(t,e);return this}list(){return[...this.items.values()]}get(e){return this.items.get(e)}filter(e){return r(this.list(),e)}listByTag(e){return this.list().filter((t)=>t.meta.tags?.includes(e))}listByOwner(e){return this.list().filter((t)=>t.meta.owners?.includes(e))}groupBy(e){return s(this.list(),e)}getUniqueTags(){return i(this.list())}}

package/dist/node/features/types.js

@@ -0,0 +1,62 @@
+export const defineFeature=(e)=>e,tech_contracts_ops_to_presentation_linking_DocBlocks=[{id:"docs.tech.contracts.ops-to-presentation-linking",title:"Ops ↔ Presentation linking (V2)",summary:"This document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/ops-to-presentation-linking",tags:["tech","contracts","ops-to-presentation-linking"],body:`### Ops to Presentation Linking (V2)
+
+This document explains how operations (\`OperationSpec\`) are linked to presentations (\`PresentationSpec\`) via feature modules.
+
+- Location: \`packages/libs/contracts-spec/src/features/types.ts\`
+- Field: \`FeatureModuleSpec.opToPresentation?: { op: OpRef; pres: PresentationRef }[]\`
+- Validation:
+  - \`validateFeatureSpec()\` checks that linked refs are declared in the feature itself
+  - \`installFeature()\` checks that declared refs exist in the provided registries
+  - \`validateFeatureTargetsV2()\` checks descriptor target support
+
+Example:
+
+\`\`\`ts
+import { defineFeature, FeatureRegistry } from '@lssm/lib.contracts-spec/features';
+
+export const WidgetsFeature = defineFeature({
+  meta: {
+    key: 'myapp.widgets.linkage',
+    version: '1.0.0',
+    title: 'Widgets (linked)',
+    description: 'Links create and update operations to UI presentations.',
+    domain: 'widgets',
+    owners: ['platform.widgets'],
+    tags: ['widgets', 'linkage'],
+    stability: 'beta',
+  },
+  operations: [
+    { key: 'widgets.create', version: '1.0.0' },
+    { key: 'widgets.update', version: '1.0.0' },
+  ],
+  presentations: [
+    { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+  ],
+  opToPresentation: [
+    {
+      op: { key: 'widgets.create', version: '1.0.0' },
+      pres: { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+    },
+    {
+      op: { key: 'widgets.update', version: '1.0.0' },
+      pres: { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+    },
+  ],
+  presentationsTargets: [
+    {
+      key: 'myapp.widgets.editor.page',
+      version: '1.0.0',
+      targets: ['react', 'markdown'],
+    },
+  ],
+});
+
+const features = new FeatureRegistry().register(WidgetsFeature);
+\`\`\`
+
+Notes:
+
+- This enables traceability: the UI flow that realizes an operation is discoverable via the feature catalog.
+- Presentations can target multiple outputs (\`react\`, \`markdown\`, \`application/json\`, \`application/xml\`).
+- Use \`renderFeaturePresentation()\` to render a descriptor to a given target with a component map.
+`}];

package/dist/node/features/validate-bundle-requires.d.js

@@ -0,0 +1 @@
+export{};

package/dist/node/features/validate-bundle-requires.js

@@ -0,0 +1 @@
+export function validateBundleRequires(s,o){const r=[],t=[];for(const e of s){const n=o.get(e.key);if(!n){t.push({key:e.key,version:e.version});r.push(`Required feature "${e.key}" not found in registry`);continue}const i=n.meta.version;if(i&&e.version&&i!==e.version)r.push(`Feature "${e.key}" version mismatch: required ${e.version}, registered ${i}`)}return{valid:r.length===0,errors:r,missing:t}}

package/dist/node/features/validation.js

@@ -0,0 +1 @@
+export class FeatureValidationError extends Error{issues;constructor(e,t){super(e);this.issues=t;this.name="FeatureValidationError"}}export function validateFeatureTargetsV2(e,t){if(!e.presentationsTargets||e.presentationsTargets.length===0)return!0;for(const n of e.presentationsTargets){const r=t.find((a)=>a.meta.key===n.key&&a.meta.version===n.version);if(!r)throw Error(`V2 descriptor not found ${n.key}.v${n.version}`);for(const a of n.targets)if(!r.targets.includes(a))throw Error(`Descriptor ${n.key}.v${n.version} missing target ${a}`)}return!0}export function validateFeatureSpec(e){const t=[];d(e,t);g(e,t);v(e,t);p(e,t);h(e,t);return{valid:t.every((n)=>n.level!=="error"),issues:t}}export function assertFeatureSpecValid(e){const t=validateFeatureSpec(e);if(!t.valid)throw new FeatureValidationError(`Feature ${e.meta.key}.v${e.meta.version} is invalid`,t.issues)}function d(e,t){u(e.meta.key,"Feature must have a non-empty key","meta.key",t);u(e.meta.version,"Feature must have a non-empty version","meta.version",t);u(e.meta.description,"Feature must have a non-empty description","meta.description",t);if(!e.meta.stability)t.push({level:"error",message:"Feature must declare a stability level",path:"meta.stability"});if(!e.meta.owners.length)t.push({level:"error",message:"Feature must declare at least one owner",path:"meta.owners"});if(!e.meta.tags.length)t.push({level:"error",message:"Feature must declare at least one tag",path:"meta.tags"})}function v(e,t){if(Boolean(e.operations?.length)||Boolean(e.events?.length)||Boolean(e.presentations?.length)||Boolean(e.experiments?.length)||Boolean(e.capabilities?.provides?.length)||Boolean(e.capabilities?.requires?.length)||Boolean(e.opToPresentation?.length)||Boolean(e.presentationsTargets?.length)||Boolean(e.implementations?.length)||Boolean(e.dataViews?.length)||Boolean(e.visualizations?.length)||Boolean(e.visualScenarios?.length)||Boolean(e.forms?.length)||Boolean(e.workflows?.length)||Boolean(e.knowledge?.length)||Boolean(e.telemetry?.length)||Boolean(e.policies?.length)||Boolean(e.integrations?.length)||Boolean(e.jobs?.length)||Boolean(e.translations?.length)||Boolean(e.docs?.length))return;t.push({level:"warning",message:"Feature declares only metadata; add refs, docs, or implementations to make it actionable",path:"meta"})}function g(e,t){i(e.operations,"operations",t);i(e.events,"events",t);i(e.presentations,"presentations",t);i(e.experiments,"experiments",t);i(e.capabilities?.provides,"capabilities.provides",t);m(e.capabilities?.requires,t);i(e.dataViews,"dataViews",t);i(e.visualizations,"visualizations",t);i(e.visualScenarios,"visualScenarios",t);i(e.forms,"forms",t);i(e.workflows,"workflows",t);i(e.knowledge,"knowledge",t);i(e.telemetry,"telemetry",t);i(e.policies,"policies",t);i(e.integrations,"integrations",t);i(e.jobs,"jobs",t);f(e.translations,t);c(e.docs,"docs",t)}function p(e,t){const n=new Set((e.operations??[]).map((a)=>`${a.key}.v${a.version}`)),r=new Set((e.presentations??[]).map((a)=>`${a.key}.v${a.version}`));e.opToPresentation?.forEach((a,o)=>{const s=`opToPresentation[${o}]`;if(!n.has(`${a.op.key}.v${a.op.version}`))t.push({level:"error",message:`Linked operation ${a.op.key}.v${a.op.version} is not declared in feature.operations`,path:`${s}.op`});if(!r.has(`${a.pres.key}.v${a.pres.version}`))t.push({level:"error",message:`Linked presentation ${a.pres.key}.v${a.pres.version} is not declared in feature.presentations`,path:`${s}.pres`})})}function h(e,t){const n=new Set((e.presentations??[]).map((a)=>`${a.key}.v${a.version}`)),r=new Set;e.presentationsTargets?.forEach((a,o)=>{const s=`presentationsTargets[${o}]`,l=`${a.key}.v${a.version}`;if(r.has(l))t.push({level:"error",message:`Duplicate presentation target requirement for ${l}`,path:s});r.add(l);if(!n.has(l))t.push({level:"error",message:`Presentation target requirement ${l} is not declared in feature.presentations`,path:s});if(!a.targets.length)t.push({level:"error",message:`Presentation target requirement ${l} must declare at least one target`,path:`${s}.targets`})})}function i(e,t,n){if(!e?.length)return;const r=new Set;e.forEach((a,o)=>{const s=`${a.key}.v${a.version??"*"}`;if(r.has(s))n.push({level:"error",message:`Duplicate reference ${s} in ${t}`,path:`${t}[${o}]`});r.add(s)})}function m(e,t){if(!e?.length)return;const n=new Set;e.forEach((r,a)=>{const o=`${r.key}.v${r.version??"*"}`;if(n.has(o))t.push({level:"error",message:`Duplicate capability requirement ${o}`,path:`capabilities.requires[${a}]`});n.add(o)})}function f(e,t){if(!e?.length)return;const n=new Set;e.forEach((r,a)=>{const o=`${r.key}.v${r.version}:${r.locale??"*"}`;if(n.has(o))t.push({level:"error",message:`Duplicate translation reference ${o}`,path:`translations[${a}]`});n.add(o)})}function c(e,t,n){if(!e?.length)return;const r=new Set;e.forEach((a,o)=>{if(r.has(a))n.push({level:"error",message:`Duplicate value "${a}" in ${t}`,path:`${t}[${o}]`});r.add(a)})}function u(e,t,n,r){if(e?.trim())return;r.push({level:"error",message:t,path:n})}

package/dist/node/forms/entity-bound-forms.js

@@ -0,0 +1,30 @@
+export const entityBoundFormsMigrationNotes={packageSubpath:"@lssm/lib.contracts-spec/forms",compatibility:"breaking-allowed",publicExport:"@lssm/lib.contracts-spec/forms/entity-bound",principles:["Entities own canonical identity; forms are renderable projections.","Permissive capture records completion debt instead of blocking intake.","Strict readiness is a separate check from capture acceptance.","Entity relations use EdgeSpec; form parts use form-specific bindings.","Communication intake maps messages to form intake payloads without UI or AI extraction."]},tech_contracts_forms_entity_bound_DocBlocks=[{id:"docs.tech.contracts.forms.entityBound",title:"Contracts: Entity-bound Form Projections",summary:"How to model entity-first form projections, completion debt, and message intake without overloading entity edges.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/forms/entity-bound",tags:["tech","contracts","forms","entities","intake"],body:`# Entity-bound form projections
+
+Entity-bound forms treat the business entity as the stable semantic anchor and the form as a renderable projection. A customer, appointment, or other entity can expose quick, full, edit, intake, or part projections without turning each projection into a new entity type.
+
+## Authoring model
+
+- Keep canonical entity identity and true entity-to-entity cardinality on entity contracts.
+- Keep renderable fields, layout, policy, and actions on \`FormSpec\`.
+- Bind a form projection to an entity with metadata such as entity key, projection kind, version, and field/path mappings.
+- Use form-part bindings for identity, address, contact, and other sub-capture surfaces when they are parts of one entity.
+- Use \`EdgeSpec\` only for real entity relations, such as customer-to-appointment, not for field-group containment.
+
+## Capture versus readiness
+
+Capture acceptance and completion readiness are intentionally separate:
+
+1. **Capture accepted** means the user or message provided enough information to preserve a draft/intake payload.
+2. **Completion debt** records skipped or missing fields with path/profile metadata.
+3. **Strict readiness** can later require a full profile without invalidating the original capture.
+
+This keeps quick creation and message intake permissive while still giving downstream workflows explicit quality gates.
+
+## Communication intake boundary
+
+Communication runtime may map a normalized message/request into an entity-bound intake payload, but it should stay deterministic and adapter-free. The first-pass hook should carry source references such as message id, thread id, and channel, then return accepted values plus completion debt. Full AI extraction, persistence, and CommunicationOS UI remain downstream concerns.
+
+## Package exports
+
+Consumers should import the form projection documentation surface from \`@lssm/lib.contracts-spec/forms/entity-bound\` and implementation primitives from \`@lssm/lib.contracts-spec/forms\` unless a narrower subpath is introduced with matching package exports and tests.
+`}];

package/dist/node/forms/entity-bound.js

@@ -0,0 +1 @@
+export*from"./entity-bound-forms.js";

package/dist/node/forms/forms.d.js

@@ -0,0 +1 @@
+export{};

package/dist/node/forms/forms.js

@@ -0,0 +1 @@
+import{compareVersions as P}from"compare-versions";import{evaluatePredicateSpec as w}from"../decisioning/predicate-evaluation.js";export function responsiveFormColumns(e,t={}){const n=t.breakpoint??"md";return{base:t.base??1,[n]:e}}export function isFieldReadOnly(e){return e.readOnly??e.computeFrom?.readOnly??!1}export function normalizeFieldSpec(e){const t=e.layout??(e.wrapper?.orientation?{orientation:e.wrapper.orientation}:void 0),n=e.readOnly==null&&e.computeFrom?.readOnly!=null?{...e,layout:t,readOnly:e.computeFrom.readOnly}:{...e,layout:t};if(n.kind==="group")return{...n,fields:n.fields.map((r)=>normalizeFieldSpec(r))};if(n.kind==="array")return{...n,of:normalizeFieldSpec(n.of)};return n}function x(e,t){const n=e.name?t?`${t}.${e.name}`:e.name:t??"";if(e.kind==="group")return e.fields.flatMap((r)=>x(r,n));if(e.kind==="array")return x(e.of,n);if(e.kind!=="phone")return[];return[n,e.output?.countryCodeName,e.output?.countryIso2Name,e.output?.nationalNumberName,e.output?.e164Name].filter((r)=>Boolean(r))}function C(e,t){const n=t.flatMap((i)=>x(i));if(!n.length)return e;const r=[...new Set([...e?.pii??[],...n])];return{...e,pii:r}}export function normalizeFormSpec(e){const t=e.fields.map((n)=>normalizeFieldSpec(n));return{...e,fields:t,policy:C(e.policy,t)}}function j(e){return e==null||typeof e==="string"&&e.trim().length===0||Array.isArray(e)&&e.length===0}function I(e,t){const n=e.projection?.completionProfiles??[];if(t)return n.find((r)=>r.key===t);return n[0]}function O(e){if(!e)return[];return[...(e.requiredPaths??[]).map((n)=>({path:n,severity:"required"})),...e.requirements??[]]}export function evaluateFormCompletion(e,t,n={}){const r=I(e,n.profileKey),i=O(r).flatMap((s)=>{if(s.requiredWhen&&!evalPredicate(t,s.requiredWhen))return[];const m=S(t,s.path);if(!j(m))return[];return[{path:s.path,profileKey:r?.key,reason:s.requiredWhen?"requiredWhen":"missing",severity:s.severity??"required",labelI18n:s.labelI18n,message:s.reason}]});return{status:i.some((s)=>s.severity==="required")?"incomplete":"complete",profileKey:r?.key,debt:i}}export function captureFormIntake(e,t,n={}){const r=n.profileKey??e.projection?.intake?.completionProfileKey,i=evaluateFormCompletion(e,t,{profileKey:r});return{accepted:!0,values:t,projection:e.projection,completion:i}}function K(e){return`${e.key}.v${e.version}`}function f(e){return e.projection?.version??e.meta.version}function F(e,t,n){return`${e}#${t}.v${n}`}function R(e){if(!e.projection)return;return F(e.projection.entity.entityKey,e.projection.kind,f(e))}export function findFormProjection(e,t){let n;for(const r of e){if(r.projection?.entity.entityKey!==t.entityKey)continue;if(r.projection.kind!==t.projectionKind)continue;const i=f(r);if(t.version!=null){if(i!==t.version)continue;if(n)throw Error(`Duplicate form projection ${F(t.entityKey,t.projectionKind,t.version)}`);n=r;continue}if(!n||P(i,f(n))>0)n=r;else if(P(i,f(n))===0)throw Error(`Duplicate form projection ${F(t.entityKey,t.projectionKind,i)}`)}return n}export class FormRegistry{items=new Map;projectionItems=new Map;register(e){const t=K(e.meta);if(this.items.has(t))throw Error(`Duplicate form ${t}`);const n=R(e);if(n&&this.projectionItems.has(n))throw Error(`Duplicate form projection ${n}`);this.items.set(t,e);if(n)this.projectionItems.set(n,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[r,i]of this.items.entries()){if(i.meta.key!==e)continue;if(!n||P(i.meta.version,n.meta.version)>0)n=i}return n}getByEntityProjection(e,t,n){if(n!=null)return this.projectionItems.get(F(e,t,n));return findFormProjection(this.projectionItems.values(),{entityKey:e,projectionKind:t})}findProjection(e){return this.getByEntityProjection(e.entityKey,e.projectionKind,e.version)}filter(e){const{filterBy:t}=require("../registry-utils");return t(this.list(),e)}listByTag(e){return this.list().filter((t)=>t.meta.tags?.includes(e))}listByOwner(e){return this.list().filter((t)=>t.meta.owners?.includes(e))}groupBy(e){const{groupBy:t}=require("../registry-utils");return t(this.list(),e)}getUniqueTags(){const{getUniqueTags:e}=require("../registry-utils");return e(this.list())}}function S(e,t){if(!t)return;const n=t.replace(/\[(\d+)\]/g,".$1").split(".").filter(Boolean);let r=e;for(const i of n){if(r==null)return;if(r&&typeof r==="object"&&i in r)r=r[i];else return}return r}function b(e,t=[]){let n=0;return e.replace(/\$index/g,()=>{const r=t[n];n+=1;return r==null?"$index":String(r)})}function u(e){return e.split(".").filter(Boolean).map((t)=>/^\d+$/.test(t)?Number(t):t)}export function evalPredicate(e,t,n=[]){if(!t)return!0;return w(t,e,(r)=>b(r,n)).matched}export function buildZodWithRelations(e,t){const n=normalizeFormSpec(e);return n.model.getZod().superRefine((i,s)=>{const m=(o,l,c=[])=>{const k=o.name?l?`${l}.${o.name}`:o.name:l??"",p=b(k,c);if(o.requiredWhen){if(evalPredicate(i,o.requiredWhen,c)){const d=S(i,p);if(d==null||typeof d==="string"&&d.trim().length===0||Array.isArray(d)&&d.length===0)s.addIssue({code:"custom",path:u(p),message:"required"})}}if(o.kind==="array"||o.kind==="multi-select"){const a=S(i,p),d=o.kind==="array"?o.min:o.minSelections,g=o.kind==="array"?o.max:o.maxSelections;if(d!=null&&Array.isArray(a)&&a.length<d)s.addIssue({code:"custom",path:u(p),message:`min:${d}`});if(g!=null&&Array.isArray(a)&&a.length>g)s.addIssue({code:"custom",path:u(p),message:`max:${g}`});if(o.kind==="array"&&Array.isArray(a))a.forEach((h,y)=>{m(o.of,`${p}.${y}`,[...c,y])});if(o.kind==="multi-select"&&Array.isArray(a)){const h="kind"in o.options?o.options.kind==="static"?o.options.options??[]:[]:o.options;if(h.length&&a.some((y)=>!h.some((v)=>Object.is(v.value,y))))s.addIssue({code:"custom",path:u(p),message:"invalid-option"})}}else if(o.kind==="group")for(const a of o.fields)m(a,p,c)};for(const o of n.fields)m(o);if(n.constraints&&t)for(const o of n.constraints){const l=t[o.key];if(!l)continue;const c=l(i,o.paths,o.args);if(!c.ok)s.addIssue({code:"custom",path:u(c.path??o.paths[0]??""),message:c.message??o.messageI18n})}})}export function defineFormSpec(e){return e}export const tech_contracts_forms_DocBlocks=[{id:"docs.tech.contracts.forms",title:"Contracts: FormSpec",summary:"This document defines the canonical contracts for declarative forms.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/forms",tags:["tech","contracts","forms"],body:"# Contracts: FormSpec\n\nThis document defines the canonical contracts for declarative forms.\n\n## Overview\n\n- `FormSpec` (in `@lssm/lib.contracts-spec/forms`) declares:\n  - `meta` (extends `OwnerShipMeta`) + `key`/`version` for stability.\n  - `model` (`@lssm/lib.schema` `SchemaModel`) as the single source of truth.\n  - `fields` built from `FieldSpec` kinds: `text`, `email`, `textarea`, `select`, `checkbox`, `radio`, `switch`, `autocomplete`, `address`, `phone`, `number`, `percent`, `currency`, `date`, `time`, `datetime`, `duration`, `group`, `array`.\n  - `text.password` for masked current/new password fields with password-manager hints.\n  - field-level `readOnly` support that preserves submitted values.\n  - Optional `layout`, `layout.flow`, `actions`, `policy.flags`, `constraints` and `renderHints`.\n- Relations DSL provides `visibleWhen`, `enabledWhen`, `requiredWhen` based on predicates.\n- Entity-bound projections use `projection.parts` for form-to-entity-path\n  part bindings and `projection.relatedEdges` for references to actual\n  entity `EdgeSpec` relations. Part bindings do not own graph cardinality.\n- `FormRegistry.getByEntityProjection(entityKey, projectionKind, version?)`\n  deterministically resolves quick/full/intake/edit/part forms by entity\n  projection metadata instead of by renderable form key only.\n- `buildZodWithRelations(spec)` augments the base zod with conditional rules and constraints.\n- Entity-bound projections are declared with optional `projection` metadata:\n  `quick`, `full`, `intake`, `edit`, and `part` forms remain normal\n  renderable `FormSpec` objects while `FormProjectionSpec.entity` binds them\n  to a canonical `ContractEntitySpec.meta.key`.\n- `captureFormIntake(spec, values)` is permissive by design: it returns\n  `accepted: true` for partial values and records missing completion debt.\n- `evaluateFormCompletion(spec, values)` is the strict readiness companion:\n  it reports missing `FormCompletionDebt` for a completion profile without\n  invalidating the permissive capture result.\n- React adapter renders with React Hook Form + driver API for UI components.\n\n## Rich field contracts\n\n- `autocomplete` supports local filtering or resolver-backed search, including debounce/min-query hints and configurable submit-value mapping.\n- Resolver-backed autocomplete stays runtime-neutral: forms declare `resolverKey`, dependency paths, and optional args while host renderers provide the actual fetcher.\n- `email` represents one string email-address field; schema validation remains model-owned while renderers supply email input affordances.\n- `address` uses the canonical `AddressFormValue` object shape.\n- `phone` uses the canonical `PhoneFormValue` object shape.\n- `number`, `percent`, and `currency` map numeric schema intent to native input controls while preserving locale, precision, rounding, and currency-display metadata.\n- `date`, `time`, `datetime`, and `duration` map temporal schema intent to native controls while preserving locale, timezone, unit, and display metadata.\n- `array` remains the canonical dynamic-field primitive and can repeat grouped item layouts.\n- `text` can declare `password.purpose` as `current` or `new`; renderers map those to masked controls and `current-password` / `new-password` autocomplete hints.\n\n## Progressive form layout\n\n- `layout.flow.kind: \"sections\"` groups existing fields into accessible sections while keeping all sections visible.\n- `layout.flow.kind: \"steps\"` uses the same section metadata for progressive, one-section-at-a-time rendering.\n- `FormSectionSpec.fieldNames` references existing immediate field names; field definitions stay in `FormSpec.fields`.\n- Unlisted fields remain visible so flow metadata cannot accidentally drop required model inputs.\n- `text` and `textarea` can declare portable `inputGroup` addons for text and host-resolved icons.\n\n## Entity-bound projections and intake\n\n- Entity-bound form work is entity-first: canonical identity and true entity-to-entity relations stay on entity contracts.\n- Forms remain renderable projections. Quick, full, edit, intake, and part forms should be discoverable by entity key, projection kind, and optional version.\n- Form part bindings describe sub-capture surfaces such as identity or address. They must not overload `EdgeSpec`, which remains reserved for real entity graph relations and cardinality.\n- Capture acceptance and strict readiness are separate. Quick or message intake can accept partial values and return completion debt; stricter profiles can later report missing fields without rejecting the original capture.\n- Communication runtime intake hooks should map normalized messages into entity-bound intake payloads with source refs and completion debt. They should not implement full AI extraction, database persistence, or CommunicationOS UI.\n- The public documentation/migration subpath for this first-pass guidance is `@lssm/lib.contracts-spec/forms/entity-bound`.\n- Form configuration chrome is a design-system concern: reuse `FormConfigShell`, `FormConfigMenuBar`, and `FormConfigPanel` from `@lssm/lib.design-system/forms` instead of forking configuration panels in examples or apps.\n- FormSpec and FormConfig docs describe render/config metadata only. Persistence of drafts, submissions, credentials, or tenant state remains host-owned and approval-gated; examples should expose deterministic proof maps, not storage guarantees.\n\n## Layout and Groups\n\n- `FormSpec.layout` and `group.layout` can declare 1-4 responsive columns, gap size, and default field orientation.\n- `field.layout.colSpan` lets fields span one or more grid columns or the full row.\n- `wrapper.orientation` remains a compatibility alias for `layout.orientation`.\n- `group.legendI18n` renders as the semantic legend, falling back to `labelI18n`.\n\n## Driver API (UI-agnostic)\n\nHost apps supply a driver mapping slots to components:\n\n- Required: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Autocomplete`, `AddressField`, `PhoneField`, `NumberField`, `PercentField`, `CurrencyField`, `DateField`, `TimeField`, `DateTimeField`, `DurationField`, `Button`.\n- Optional: `FieldContent`, `FieldGroup`, `FieldSet`, `FieldLegend`, `FieldSeparator`, `InputGroup`, `InputGroupAddon`, `InputGroupInput`, `InputGroupTextarea`, `InputGroupText`, `InputGroupIcon`, and `PasswordInput`.\n- Autocomplete drivers should accept optional `loading`, `error`, `emptyText`, `loadingText`, and `errorText` props so resolver-backed fields can expose async state without embedding transport details in the contract.\n\nUse `createFormRenderer({ driver })` to obtain a `render(spec)` function.\n\n## Arrays and Groups\n\n- `array` items are rendered with `useFieldArray`, honoring `min`/`max` and add/remove controls.\n- `array.of` can repeat grouped multi-field rows.\n- `group` composes nested fields and provides optional legend/description/layout.\n\n## Feature Flags\n\n- Declare `policy.flags` on forms to signal gating. Gate usage at host boundary; avoid scattering flags across individual fields.\n\n## Example\n\nUse the exported `RichFieldsShowcaseForm` as the canonical reference for readonly, password, autocomplete, address, phone, temporal, layout, and input-group field authoring.\n"}];

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

@@ -0,0 +1 @@
+export*from"./entity-bound-forms.js";export*from"./forms.js";export*from"./marketing.forms.js";export*from"./platform-capability.js";export*from"./platform-compiler.js";export*from"./platform-decision-graph.js";export*from"./platform-docs.js";export*from"./platform-document.js";export*from"./platform-document-doc.js";export*from"./platform-ecosystem-operations.js";export*from"./platform-features.js";export*from"./platform-form-spec-serialization.js";export*from"./platform-form-spec-validation.js";export*from"./platform-operation-catalog.js";export*from"./platform-operation-errors.js";export*from"./platform-operations.js";export*from"./platform-product.js";export*from"./platform-registry.js";export*from"./platform-response-extension.js";export*from"./platform-validation.js";export*from"./richFieldsShowcase.form.js";

package/dist/node/forms/index.js

@@ -0,0 +1 @@
+export*from"./entity-bound-forms.js";export*from"./forms.js";export*from"./marketing.forms.js";export*from"./platform-capability.js";export*from"./platform-compiler.js";export*from"./platform-decision-graph.js";export*from"./platform-docs.js";export*from"./platform-document.js";export*from"./platform-document-doc.js";export*from"./platform-ecosystem-operations.js";export*from"./platform-features.js";export*from"./platform-form-spec-serialization.js";export*from"./platform-form-spec-validation.js";export*from"./platform-operation-catalog.js";export*from"./platform-operation-errors.js";export*from"./platform-operations.js";export*from"./platform-product.js";export*from"./platform-registry.js";export*from"./platform-response-extension.js";export*from"./platform-validation.js";export*from"./richFieldsShowcase.form.js";

package/dist/node/forms/marketing.forms.js

@@ -0,0 +1 @@
+import{BillingEstimateIntakeInput as r,BillingEstimatePrepareQuery as i,MarketingEstimateCalculateInput as o,MarketingEstimateCalculateQuery as a,MarketingLeadCaptureCommand as n,MarketingLeadCaptureInput as m}from"../operations/index.js";import{defineFormSpec as e,responsiveFormColumns as t}from"./forms.js";export const MarketingLeadCaptureFormSpec=e({meta:{key:"marketing.lead.capture.form",version:"1.0.0",title:"Marketing lead capture form",description:"Generic marketing lead capture FormSpec; hosts own copy, provider logic, and operation handlers.",domain:"marketing",owners:["@contractspec-core"],tags:["marketing","forms","lead-capture"],stability:"experimental"},model:m,layout:{columns:t(2),gap:"md"},fields:[{kind:"email",name:"email",labelI18n:"Email",layout:{colSpan:"full"}},{kind:"text",name:"name",labelI18n:"Name"},{kind:"text",name:"company",labelI18n:"Company"},{kind:"textarea",name:"message",labelI18n:"Message",layout:{colSpan:"full"}}],actions:[{key:"submit",labelI18n:"Submit",op:{name:n.meta.key,version:n.meta.version}}],renderHints:{ui:"shadcn",form:"react-hook-form"}}),MarketingEstimateInputFormSpec=e({meta:{key:"marketing.estimate.input.form",version:"1.0.0",title:"Marketing estimate input form",description:"Generic marketing estimate input FormSpec. Pricing math is supplied by host OperationSpec handlers.",domain:"marketing",owners:["@contractspec-core"],tags:["marketing","forms","pricing","estimate"],stability:"experimental"},model:o,layout:{columns:t(2),gap:"md"},fields:[{kind:"number",name:"primaryQuantity",labelI18n:"Primary quantity",min:0,step:1,inputMode:"numeric"},{kind:"number",name:"secondaryQuantity",labelI18n:"Secondary quantity",min:0,step:1,inputMode:"numeric"},{kind:"radio",name:"bundleKey",labelI18n:"Bundle",layout:{colSpan:"full"},options:{kind:"static",options:[{value:"starter",labelI18n:"Starter"},{value:"growth",labelI18n:"Growth"},{value:"scale",labelI18n:"Scale"}]}}],actions:[{key:"estimate",labelI18n:"Estimate",op:{name:a.meta.key,version:a.meta.version}}],renderHints:{ui:"shadcn",form:"react-hook-form"}}),BillingEstimateIntakeFormSpec=e({meta:{key:"billing.estimate.intake.form",version:"1.0.0",title:"Billing estimate intake form",description:"Side-effect-free billing estimate intake FormSpec. Hosts provide estimate handlers; no payment execution is implied.",domain:"billing",owners:["@contractspec-core"],tags:["billing","forms","estimate"],stability:"experimental"},model:r,layout:{columns:t(2),gap:"md"},fields:[{kind:"number",name:"accountCount",labelI18n:"Account count",min:0,step:1,inputMode:"numeric"},{kind:"number",name:"documentCount",labelI18n:"Document count",min:0,step:1,inputMode:"numeric"},{kind:"text",name:"bundleKey",labelI18n:"Bundle key",layout:{colSpan:"full"}}],actions:[{key:"prepare",labelI18n:"Prepare estimate",op:{name:i.meta.key,version:i.meta.version}}],renderHints:{ui:"shadcn",form:"react-hook-form"}}),MarketingFormsDocBlock={id:"docs.contracts-spec.forms.marketing",title:"Marketing & BillingOS-adjacent FormSpecs",summary:"Contract-first FormSpecs for form-like marketing/BillingOS UI; rendering goes through the design-system FormSpec renderer and submission binds to OperationSpecs.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/forms/marketing",tags:["marketing","billing","forms","lead-capture","estimate"],body:"# Marketing & BillingOS-adjacent FormSpecs\n\nThree generic, reusable FormSpecs make form-like marketing/BillingOS UI\ncontract-first. Each binds its action to an OperationSpec by `key`+`version`;\nhosts own copy, option catalogs, provider logic, and handlers.\n\n- `marketing.lead.capture.form` (`MarketingLeadCaptureFormSpec`) → action binds\n  to `marketing.lead.capture` (command).\n- `marketing.estimate.input.form` (`MarketingEstimateInputFormSpec`) → action\n  binds to `marketing.estimate.calculate` (query). Bundle options are\n  illustrative defaults; hosts override them.\n- `billing.estimate.intake.form` (`BillingEstimateIntakeFormSpec`) → action binds\n  to `billing.estimate.prepare` (query, **side-effect-free**).\n\nThese specs are schema/layout/action metadata only. The design system renders\nfields and an operation/host-provided result; it never computes pricing, calls a\nprovider, payment, CRM, or invoice path. Live billing execution stays host-owned.\n\nRelationship to `marketing/forms.ts`: `MarketingStudioDemoRequestForm` +\n`marketingFormRegistry` are the Studio-specific demo-CTA form and its registry;\nthe specs here are the generic, reusable lead/estimate/billing forms."};

package/dist/node/forms/platform-ai-validation.js

@@ -0,0 +1 @@
+import{FORM_AI_GENERATED_QUESTION_HARD_LIMIT as a}from"./platform-document.js";export function validateFormAiPolicy(s,o){const t=s.ai,n=new Set(s.questions.map(({id:e})=>e)),m=new Set([...n,...Object.keys(s.formSpec?.modelFields??{})]);if((t.maxGeneratedQuestions??t.staticLimit??0)>a||(t.maxModelCalls??0)>a)o.push({code:"ai_limit_exceeded",path:"ai",message:`AI calls and questions cannot exceed ${a}`});if(t.mode==="static-limit"&&(!t.staticLimit||t.staticLimit<1))o.push({code:"ai_static_limit_required",path:"ai.staticLimit",message:"Static AI mode requires a positive limit"});for(const[e,i]of[["maxModelCalls",t.maxModelCalls],["tokenBudget",t.tokenBudget],["costBudgetMinor",t.costBudgetMinor],["timeoutMs",t.timeoutMs]])if(i!==void 0&&(!Number.isInteger(i)||i<1))o.push({code:"ai_budget_invalid",path:`ai.${e}`,message:`${e} must be a positive integer`});for(const[e,i,d]of[["approvedQuestionIds",t.approvedQuestionIds,n],["allowedInputQuestionIds",t.allowedInputQuestionIds,m]])if(i?.some((u)=>!d.has(u)))o.push({code:"ai_question_unknown",path:`ai.${e}`,message:`${e} contains an unknown question ID`})}

package/dist/node/forms/platform-capability.js

@@ -0,0 +1 @@
+import{defineCapability as r}from"../capabilities/index.js";import{formPlatformEvents as s}from"./platform-ecosystem-operations.js";import{formPlatformOperations as e}from"./platform-operation-catalog.js";export const FORM_PLATFORM_MILESTONE_FLAGS=["forms.v0","forms.v0_1","forms.v0_2","forms.v0_3","forms.v0_4","forms.v0_5","forms.v0_6"],FORM_PLATFORM_PERMISSIONS=["forms.create","forms.edit","forms.publish","forms.responses.read","forms.export.redacted","forms.export.sensitive","forms.ai.configure","forms.integrations.manage"],FormsPlatformCapability=r({meta:{key:"forms.platform",version:"1.0.0",kind:"api",title:"Shared Forms Platform",description:"Portable form authoring, publication, response, verification, AI, and ecosystem contracts.",domain:"forms",owners:["platform.core"],tags:["forms","survey","i18n"],stability:"experimental"},provides:[...e.map((o)=>({surface:"operation",key:o.meta.key,version:o.meta.version})),...s.map((o)=>({surface:"event",key:o.meta.key,version:o.meta.version}))]});

package/dist/node/forms/platform-compiler.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as t,SchemaModel as c}from"@lssm/lib.schema";import{OwnersEnum as p,StabilityEnum as d,TagsEnum as y}from"../ownership.js";import{FormDocumentValidationError as h,validateFormDocument as f}from"./platform-validation.js";function o(e){return(e??[]).map((n)=>({labelI18n:n.labelKey,value:n.value,descriptionI18n:n.descriptionKey}))}function S(e){const n={name:e.name,labelI18n:e.labelKey,descriptionI18n:e.descriptionKey,placeholderI18n:e.placeholderKey,required:e.required,readOnly:e.readOnly,visibleWhen:e.visibleWhen,enabledWhen:e.enabledWhen,requiredWhen:e.requiredWhen};switch(e.kind){case"short-text":return{...n,kind:"text",minLength:e.minLength,maxLength:e.maxLength};case"long-text":return{...n,kind:"textarea",minLength:e.minLength,maxLength:e.maxLength};case"email":return{...n,kind:"email",minLength:e.minLength,maxLength:e.maxLength};case"phone":return{...n,kind:"phone",output:{mode:"e164"}};case"number":return{...n,kind:"number",min:e.min,max:e.max};case"date":return{...n,kind:"date"};case"time":return{...n,kind:"time"};case"single-choice":return{...n,kind:"radio",options:o(e.options)};case"multi-select":return{...n,kind:"multi-select",options:o(e.options),minSelections:e.min,maxSelections:e.max};case"dropdown":return{...n,kind:"select",options:o(e.options)};case"consent":return{...n,kind:"checkbox"}}}function F(e){return{type:e.kind==="email"?t.EmailAddress():e.kind==="phone"?t.PhoneNumber():e.kind==="number"?t.Float_unsecure():e.kind==="date"?t.Date():e.kind==="time"?t.Time():e.kind==="consent"?t.Boolean():t.String_unsecure(),isOptional:!e.required,...e.kind==="multi-select"?{isArray:!0}:{}}}function g(e){return{type:e.type==="email"?t.EmailAddress():e.type==="phone"?t.PhoneNumber():e.type==="number"?t.Float_unsecure():e.type==="integer"?t.Int_unsecure():e.type==="boolean"?t.Boolean():e.type==="date"?t.Date():e.type==="time"?t.Time():e.type==="datetime"?t.DateTime():e.type==="json"?t.JSONObject():t.String_unsecure(),isOptional:e.optional,...e.array?{isArray:!0}:{}}}export function compileFormDocument(e){const n=f(e);if(n.length)throw new h(n);const a=new Map(e.questions.map((r)=>[r.id,r])),m=e.pages.map((r)=>({key:r.id,titleI18n:r.titleKey,descriptionI18n:r.descriptionKey,fieldNames:r.questionIds.map((i)=>a.get(i)?.name).filter((i)=>Boolean(i))})),s=Object.fromEntries(e.formSpec?Object.entries(e.formSpec.modelFields).map(([r,i])=>[r,g(i)]):e.questions.map((r)=>[r.name,F(r)])),l=[{key:"submit",labelI18n:e.afterDestination?.labelKey??"forms.action.submit",...e.afterDestination?.kind==="https"?{success:{navigateTo:e.afterDestination.href}}:{}}];return{meta:{key:`forms.platform.${e.id}`,version:e.version,title:e.titleKey,description:e.descriptionKey??e.titleKey,domain:"forms",owners:[p.PlatformCore],tags:[y.I18n],stability:d.Experimental},model:new c({name:e.formSpec?.modelName??`FormDocument_${e.id.replace(/[^A-Za-z0-9_]/g,"_")}`,fields:s}),fields:e.formSpec?[...e.formSpec.fields]:e.questions.map(S),layout:e.formSpec?.layout??{flow:{kind:e.pages.length>1?"steps":"sections",sections:m}},actions:e.formSpec?.actions?[...e.formSpec.actions]:l,entityBinding:e.formSpec?.entityBinding,completion:e.formSpec?.completion,constraints:e.formSpec?.constraints?[...e.formSpec.constraints]:void 0,projection:e.formSpec?.projection,policy:e.formSpec?.policy,renderHints:e.formSpec?.renderHints}}

package/dist/node/forms/platform-decision-graph.js

@@ -0,0 +1 @@
+import{assertDecisionGraphValid as s}from"../decisioning/index.js";const d="form-outcome:submitted";function r(t,e){return t.edges.filter((i)=>i.from===e).sort((i,n)=>(n.priority??0)-(i.priority??0)||i.id.localeCompare(n.id))}export function formDocumentToDecisionGraph(t){return{key:`forms.branching.${t.id}`,version:t.version,entryNodeId:t.pages[0]?.id??"",nodes:[...t.pages.map((e)=>({id:e.id,kind:"branch",labelI18n:e.titleKey})),{id:d,kind:"outcome",outcomeKey:"submitted"}],edges:t.pages.flatMap((e,i)=>{const n=(e.nextPageRules??[]).map((o,a)=>({id:o.id,from:e.id,to:o.nextPageId,predicate:o.when,priority:(e.nextPageRules?.length??0)-a})),c=e.defaultNextPageId??t.pages[i+1]?.id??d;return[...n,{id:`${e.id}:default`,from:e.id,to:c}]}),policy:{requireTotalBranches:!0},localeCatalogs:t.content.catalogs,defaultLocale:t.content.defaultLocale}}function u(t,e){const i=r(e,t.id),n=i.filter((o)=>o.predicate),c=i.find((o)=>!o.predicate&&!o.subgraphOutcomeKey);return{...t,nextPageRules:n.map((o)=>({id:o.id,when:o.predicate,nextPageId:o.to})),defaultNextPageId:c&&e.nodes.some((o)=>o.id===c.to&&o.kind!=="outcome")?c.to:void 0}}export function decisionGraphToFormDocument(t,e){s(e.document);if(e.document.entryNodeId!==t.pages[0]?.id)throw Error("Decision graph entry must match the first form page.");const i=new Set(t.pages.map((n)=>n.id));for(const n of t.pages)for(const c of r(e.document,n.id)){const o=e.document.nodes.find((a)=>a.id===c.to);if(!o||o.kind!=="outcome"&&!i.has(o.id))throw Error(`Decision edge ${c.id} cannot be represented by this form.`)}return{...t,pages:t.pages.map((n)=>u(n,e.document)),decisionGraph:{key:e.graphKey,revision:e.revision,digest:e.digest}}}

package/dist/node/forms/platform-docs.js

@@ -0,0 +1 @@
+import{docId as o}from"../docs/registry.js";export const formsOperationsDocIds=[o("forms-platform-operations")],formsEventsDocIds=[o("forms-platform-events")],formPlatformOperationsDocBlock={id:"forms-platform-operations",title:"Shared Forms operations",body:"Versioned creator and public operations. Creator ownership is derived from authenticated server context; public operations accept opaque tokens and never tenant authority. This experimental foundation does not claim product-host availability until its adapters pass Connect review.",kind:"reference",route:"/docs/specs/forms/platform-operations",visibility:"public"},formPlatformEventsDocBlock={id:"forms-platform-events",title:"Shared Forms events",body:"PII-free lifecycle receipts for definition, response, and verification transitions. Raw answers, contact destinations, and verification codes are never event payloads.",kind:"reference",route:"/docs/specs/forms/platform-events",visibility:"public"};

package/dist/node/forms/platform-document-doc.js

@@ -0,0 +1 @@
+export const formPlatformDocumentDocBlock={id:"forms-platform-document",title:"Shared Forms Platform Document",body:"Portable Forms contracts for Pactena, CompanyOS, and CommunicationOS. Published revisions are immutable, responses pin a revision, creator logic is declarative, AI is off and redacted by default, and product hosts retain authority and storage ownership.",kind:"reference",route:"/docs/specs/forms/platform-document",visibility:"public"};

package/dist/node/forms/platform-document.js

@@ -0,0 +1 @@
+export const FORM_PLATFORM_VERSION="1.0.0",FORM_AI_GENERATED_QUESTION_HARD_LIMIT=10,FORM_AI_FULL_DATA_CONSENT_NOTICE_VERSION="forms-ai-full-data-v1";

package/dist/node/forms/platform-ecosystem-operations.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as s,SchemaModel as I}from"@lssm/lib.schema";import{defineEvent as v}from"../events.js";import{defineCommand as O,defineQuery as h}from"../operations/index.js";import{formsEventsDocIds as S,formsOperationsDocIds as u}from"./platform-docs.js";import{formsOperationErrors as y}from"./platform-operation-errors.js";const g={key:"forms.platform",version:"1.0.0"},p=["platform.core"],m=["forms","survey","i18n"];function e(r,o){return new I({name:r,fields:o})}const t={type:s.ID(),isOptional:!1},d={type:s.ID(),isOptional:!1},x={type:s.ID(),isOptional:!1},n={type:s.JSONObject(),isOptional:!1},c={type:s.String_unsecure(),isOptional:!0},R=e("FormsReceiptOutput",{receiptId:{type:s.ID(),isOptional:!1},status:{type:s.NonEmptyString(),isOptional:!1}}),C=e("FormsResponseOutput",{response:n});function f(r,o,i,a=R){return O({meta:{key:r,title:o,version:"1.0.0",description:o,goal:o,context:"Shared Forms platform operation with server-derived scope.",domain:"forms",owners:[...p],tags:[...m],stability:"experimental",docId:[...u]},capability:g,io:{input:i,output:a,errors:y},policy:{auth:"user",pii:[]}})}function l(r,o,i,a,F=[]){return h({meta:{key:r,title:o,version:"1.0.0",description:o,goal:o,context:"Shared Forms results query with server-derived scope.",domain:"forms",owners:[...p],tags:[...m],stability:"experimental",docId:[...u]},capability:g,io:{input:i,output:a,errors:y},policy:{auth:"user",pii:F}})}export const FormResponsesListQuery=l("forms.responses.list","List form responses",e("FormResponsesListInput",{definitionId:t,cursor:c,status:c}),e("FormResponsesListOutput",{page:n}),["page.responses.answers"]),FormResponseGetQuery=l("forms.response.get","Get form response",e("FormResponseGetInput",{definitionId:t,responseId:d}),C,["response.answers"]),FormResponsesExportQuery=l("forms.responses.export","Export form responses",e("FormResponsesExportInput",{definitionId:t,cursor:c,includeSensitive:{type:s.Boolean(),isOptional:!0}}),e("FormResponsesExportOutput",{export:n}),["export.answers"]),FormResponseEraseCommand=f("forms.response.erase","Erase form response",e("FormResponseEraseInput",{definitionId:t,responseId:d})),FormAiAnalysisRequestCommand=f("forms.ai-analysis.request","Request form response analysis",e("FormAiAnalysisRequestInput",{definitionId:t}),e("FormAiAnalysisRequestOutput",{analysis:n})),FormIntegrationConfigureCommand=f("forms.integration.configure","Configure form integration",e("FormIntegrationConfigureInput",{definitionId:t,configuration:n}),e("FormIntegrationConfigureOutput",{integration:n}));const A=e("FormPlatformEventPayload",{definitionId:t,revisionId:{...x,isOptional:!0},responseId:{...d,isOptional:!0},occurredAt:{type:s.DateTime(),isOptional:!1},receiptId:{type:s.ID(),isOptional:!0}}),E=[["forms.definition.created","Form definition created"],["forms.draft.saved","Form draft saved"],["forms.definition.published","Form definition published"],["forms.definition.closed","Form definition closed"],["forms.definition.archived","Form definition archived"],["forms.response.submitted","Form response submitted"],["forms.response.erased","Form response erased"],["forms.verification.completed","Form verification completed"]];export const formPlatformEvents=E.map(([r,o])=>v({meta:{key:r,title:o,version:"1.0.0",description:o,owners:[...p],tags:[...m],stability:"experimental",docId:[...S]},payload:A,pii:[]}));

package/dist/node/forms/platform-features.js

@@ -0,0 +1 @@
+import{defineFeature as r}from"../features/index.js";import{FORM_PLATFORM_MILESTONE_FLAGS as o}from"./platform-capability.js";function t(e){return r({meta:{key:e,version:"1.0.0",title:`Forms milestone ${e.slice(6)}`,description:`Independently deployable and reversible ${e} Forms milestone.`,domain:"forms",owners:["platform.core"],tags:["forms","feature-flag"],stability:"experimental"},capabilities:{provides:[{key:e,version:"1.0.0"}]}})}export const FormsMilestoneFeatures=o.map(t);

package/dist/node/forms/platform-form-spec-serialization.js

@@ -0,0 +1 @@
+function t(r){if(r.kind==="email")return"email";if(r.kind==="phone")return"phone";if(["number","percent","currency","duration"].includes(r.kind))return"number";if(["checkbox","switch"].includes(r.kind))return"boolean";if(r.kind==="date")return"date";if(r.kind==="time")return"time";if(r.kind==="datetime")return"datetime";if(r.kind==="group"||r.kind==="array")return"json";return"string"}export function serializePortableFormSpec(r){const n=r.fields.filter((e)=>Boolean(e.name));return structuredClone({modelName:`FormSpec_${r.meta.key.replace(/[^A-Za-z0-9_]/g,"_")}`,modelFields:Object.fromEntries(n.map((e)=>[e.name,{type:t(e),optional:!e.required,...e.kind==="array"||e.kind==="multi-select"?{array:!0}:{}}])),fields:r.fields,entityBinding:r.entityBinding,completion:r.completion,layout:r.layout,actions:r.actions,constraints:r.constraints,projection:r.projection,policy:r.policy,renderHints:r.renderHints})}

package/dist/node/forms/platform-form-spec-validation.js

@@ -0,0 +1 @@
+export function flattenPortableFormFields(o){return o.flatMap((e)=>e.kind==="group"?[e,...flattenPortableFormFields(e.fields)]:e.kind==="array"?[e,...flattenPortableFormFields([e.of])]:[e])}export function portableFormAnswerFields(o){return o.flatMap((e)=>e.kind==="group"?e.name?[e]:portableFormAnswerFields(e.fields):[e])}function s(o){return o&&typeof o==="object"&&"kind"in o&&o.kind==="resolver"?o.resolverKey:void 0}function c(o){if(o.kind==="autocomplete"&&o.source.kind==="resolver")return[o.source.resolverKey];if(o.kind==="select"||o.kind==="multi-select"||o.kind==="radio")return[s(o.options)].filter((e)=>Boolean(e));if(o.kind==="address"||o.kind==="phone")return[s(o.countryOptions)].filter((e)=>Boolean(e));return[]}function i(o,e,n,a){for(const r of e)if(!n.includes(r))a.push({code:`form_spec_${o}_not_allowed`,path:"formSpec",message:`FormSpec ${o} ${r} is not allowlisted`})}export function validatePortableFormSpec(o,e){const n=o.formSpec;if(!n)return;try{structuredClone(n);const t=JSON.stringify(n);if(!t||t.length>1e6)throw Error("size")}catch{e.push({code:"form_spec_not_serializable",path:"formSpec",message:"FormSpec metadata must be portable JSON without functions"});return}const a=flattenPortableFormFields(n.fields),r=o.integrations;i("resolver",a.flatMap(c),r?.allowedResolverKeys??[],e);i("computation",a.flatMap((t)=>t.computeFrom?[t.computeFrom.computeKey]:[]),r?.allowedComputationKeys??[],e);i("constraint",(n.constraints??[]).map(({key:t})=>t),r?.allowedConstraintKeys??[],e);i("action",(n.actions??[]).map(({key:t})=>t),r?.allowedActionKeys??[],e)}