@lssm/lib.contracts-spec 17.3.2

package/dist/examples/validation.d.ts

@@ -0,0 +1,61 @@
+import type { ExampleSpec } from './types.js';
+export interface ExampleValidationError {
+    /** Example key if available */
+    exampleKey?: string;
+    /** Error message */
+    message: string;
+    /** Path within the spec where error occurred */
+    path?: string;
+    /** Error code for programmatic handling */
+    code?: string;
+}
+export interface ExampleValidationWarning {
+    /** Example key if available */
+    exampleKey?: string;
+    /** Warning message */
+    message: string;
+    /** Path within the spec where warning applies */
+    path?: string;
+}
+export type ValidateExamplesResult = {
+    ok: true;
+    examples: ExampleSpec[];
+} | {
+    ok: false;
+    errors: ExampleValidationError[];
+};
+export interface ValidateExampleResult {
+    valid: boolean;
+    errors: ExampleValidationError[];
+    warnings: ExampleValidationWarning[];
+}
+/**
+ * Validate a single ExampleSpec.
+ *
+ * @param example - The example to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateExample(example: unknown): ValidateExampleResult;
+/**
+ * Validate multiple examples, checking for duplicates.
+ *
+ * @param examples - Array of examples to validate
+ * @returns Validation result with all valid examples or errors
+ */
+export declare function validateExamples(examples: ExampleSpec[]): ValidateExamplesResult;
+export interface CrossValidationContext {
+    /** Available feature keys */
+    featureKeys?: Set<string>;
+    /** Available blueprint keys */
+    blueprintKeys?: Set<string>;
+    /** Available package names in workspace */
+    packageNames?: Set<string>;
+}
+/**
+ * Validate example references against external registries.
+ *
+ * @param example - Example to validate
+ * @param context - External context for cross-reference validation
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateExampleReferences(example: ExampleSpec, context: CrossValidationContext): ValidateExampleResult;

package/dist/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/experience-coverage/index.d.ts

@@ -0,0 +1,3 @@
+export { type ExperienceFeatureScore, scoreExperienceFeature, } from './scoring.js';
+export { defineExperienceCoverage, EXPERIENCE_COVERAGE_CONTRACT_KEY, EXPERIENCE_COVERAGE_CONTRACT_VERSION, type ExperienceBlockerRef, type ExperienceCoverageSpec, type ExperienceCoverageStatus, type ExperienceEvidenceLayer, type ExperienceEvidenceRef, type ExperienceFeatureSpec, type ExperienceJourneySpec, type ExperienceJourneyStep, type ExperienceJourneyVariant, type ExperienceModuleSpec, type ExperienceOwnerScope, type ExperiencePlatform, type ExperienceProductId, } from './types.js';
+export { type ExperienceCoverageIssue, validateExperienceCoverage, } from './validation.js';

package/dist/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/experience-coverage/scoring.d.ts

@@ -0,0 +1,9 @@
+import type { ExperienceCoverageStatus, ExperienceEvidenceLayer, ExperienceFeatureSpec } from './types.js';
+export interface ExperienceFeatureScore {
+    readonly status: ExperienceCoverageStatus;
+    readonly completionPercent: number;
+    readonly verifiedLayers: readonly ExperienceEvidenceLayer[];
+    readonly missingLayers: readonly ExperienceEvidenceLayer[];
+}
+/** Derive truthful completion from applicable, real evidence gates. */
+export declare function scoreExperienceFeature(feature: ExperienceFeatureSpec): ExperienceFeatureScore;

package/dist/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/experience-coverage/types.d.ts

@@ -0,0 +1,94 @@
+/** Stable identifier for the experience-coverage contract family. */
+export declare const EXPERIENCE_COVERAGE_CONTRACT_KEY: 'contractspec.experience.coverage';
+/** Initial additive release of the experience-coverage contract. */
+export declare const EXPERIENCE_COVERAGE_CONTRACT_VERSION: '1.0.0';
+export type ExperienceProductId = 'companyos' | 'opa' | 'communicationos' | (string & {});
+export type ExperienceJourneyVariant = 'happy' | 'recovery' | 'denial';
+export type ExperienceCoverageStatus = 'live_verified' | 'implemented_unverified' | 'fixture_only' | 'contract_only' | 'stub' | 'blocked_external' | 'not_applicable';
+export type ExperienceEvidenceLayer = 'contract' | 'implementation' | 'unit' | 'integration' | 'e2e' | 'accessibility' | 'security' | 'migration' | 'performance' | 'resilience' | 'production_canary' | 'manual_acceptance';
+export type ExperiencePlatform = 'companyos_web' | 'standalone_web' | 'pwa' | 'expo_ios' | 'expo_android' | 'tauri_macos' | 'tauri_windows' | 'tauri_linux' | (string & {});
+export type ExperienceOwnerScope = 'individual' | 'team' | 'workspace' | 'organization' | (string & {});
+export type ExperienceExposure = 'customer' | 'operator' | 'admin' | 'system';
+export type ExperienceAuthMode = 'anonymous' | 'authenticated_customer' | 'operator' | 'service';
+export type ExperienceDeliveryStage = 'missing' | 'contract_only' | 'scaffolded' | 'implemented_local' | 'integrated' | 'qualified';
+export interface ExperienceEvidenceRef {
+    readonly id: string;
+    readonly layer: ExperienceEvidenceLayer;
+    readonly ref: string;
+    readonly mode: 'real' | 'fixture';
+    readonly state: 'verified' | 'failed' | 'stale' | 'missing';
+    readonly observedAt?: string;
+    readonly expiresAt?: string;
+}
+export interface ExperienceBlockerRef {
+    readonly id: string;
+    readonly kind: 'external' | 'product' | 'technical' | 'security';
+    readonly summary: string;
+    readonly status: 'open' | 'resolved';
+    readonly owner?: string;
+}
+export interface ExperienceFeatureSpec {
+    readonly id: string;
+    readonly moduleId: string;
+    readonly title: string;
+    readonly description: string;
+    readonly actionable: boolean;
+    readonly visibility: 'public' | 'internal_read_only';
+    readonly exposure?: ExperienceExposure;
+    readonly authModes?: readonly ExperienceAuthMode[];
+    readonly deliveryStage?: ExperienceDeliveryStage;
+    readonly qualificationStatus?: 'unqualified' | 'qualified';
+    readonly applicability?: 'applicable' | 'not_applicable';
+    readonly routes: readonly string[];
+    readonly capabilityRefs: readonly string[];
+    readonly personas: readonly string[];
+    readonly ownerScopes: readonly ExperienceOwnerScope[];
+    readonly platforms: readonly ExperiencePlatform[];
+    readonly providerRefs: readonly string[];
+    readonly requiredEvidence: readonly ExperienceEvidenceLayer[];
+    readonly evidence: readonly ExperienceEvidenceRef[];
+    readonly journeyRefs: readonly string[];
+    readonly blockers: readonly ExperienceBlockerRef[];
+}
+export interface ExperienceModuleSpec {
+    readonly id: string;
+    readonly productId: ExperienceProductId;
+    readonly title: string;
+    readonly description: string;
+    readonly featureIds: readonly string[];
+}
+export interface ExperienceJourneyStep {
+    readonly id: string;
+    readonly intent: string;
+    readonly expectedOutcome: string;
+}
+export interface ExperienceJourneySpec {
+    readonly id: string;
+    readonly title: string;
+    readonly variant: ExperienceJourneyVariant;
+    readonly featureRefs: readonly string[];
+    readonly personas: readonly string[];
+    readonly ownerScopes: readonly ExperienceOwnerScope[];
+    readonly platforms: readonly ExperiencePlatform[];
+    readonly exposure?: ExperienceExposure;
+    readonly authModes?: readonly ExperienceAuthMode[];
+    readonly preconditions: readonly string[];
+    readonly steps: readonly ExperienceJourneyStep[];
+    readonly assertions: readonly string[];
+    readonly evidenceRefs: readonly string[];
+}
+export interface ExperienceCoverageSpec {
+    readonly meta: {
+        readonly key: typeof EXPERIENCE_COVERAGE_CONTRACT_KEY;
+        readonly version: typeof EXPERIENCE_COVERAGE_CONTRACT_VERSION;
+        readonly title: string;
+        readonly description: string;
+        readonly owners: readonly string[];
+        readonly generatedAt?: string;
+    };
+    readonly modules: readonly ExperienceModuleSpec[];
+    readonly features: readonly ExperienceFeatureSpec[];
+    readonly journeys: readonly ExperienceJourneySpec[];
+}
+/** Identity helper that preserves literal types for coverage manifests. */
+export declare function defineExperienceCoverage<const T extends ExperienceCoverageSpec>(spec: T): T;

package/dist/experience-coverage/types.js

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

package/dist/experience-coverage/validation.d.ts

@@ -0,0 +1,8 @@
+import type { ExperienceCoverageSpec } from './types.js';
+export interface ExperienceCoverageIssue {
+    readonly code: 'duplicate_id' | 'unknown_reference' | 'missing_journey_variant' | 'invalid_route' | 'invalid_actor_context' | 'invalid_qualification_status' | 'fixture_mutation' | 'provider_canary_missing';
+    readonly path: string;
+    readonly message: string;
+}
+/** Validate cross-references and production-truth invariants. */
+export declare function validateExperienceCoverage(spec: ExperienceCoverageSpec): readonly ExperienceCoverageIssue[];

package/dist/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/experiments/evaluator.d.ts

@@ -0,0 +1,33 @@
+import type { PolicyRef } from '../policy/spec.js';
+import type { ExperimentRegistry, ExperimentVariant } from './spec.js';
+export interface ExperimentContext {
+    experiment: string;
+    version?: string;
+    userId?: string | null;
+    organizationId?: string | null;
+    sessionId?: string | null;
+    attributes?: Record<string, unknown>;
+    flags?: string[];
+}
+export interface ExperimentEvaluation {
+    variant: ExperimentVariant;
+    reason: 'control' | 'random' | 'sticky' | 'targeted';
+}
+export interface ExperimentEvaluatorConfig {
+    registry: ExperimentRegistry;
+    policyChecker?: (policy: PolicyRef, context: ExperimentContext) => Promise<boolean> | boolean;
+    expressionEvaluator?: (expression: string, context: ExperimentContext) => boolean;
+}
+export declare class ExperimentEvaluator {
+    private readonly registry;
+    private readonly policyChecker?;
+    private readonly expressionEvaluator?;
+    constructor(config: ExperimentEvaluatorConfig);
+    chooseVariant(context: ExperimentContext): Promise<ExperimentEvaluation | null>;
+    private pickByWeight;
+    private randomSeed;
+    private stickySeed;
+    private hashToUnitInterval;
+    private evaluateTargeting;
+    private matchesRule;
+}

package/dist/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/experiments/spec-resolver.d.ts

@@ -0,0 +1,12 @@
+import type { AnySchemaModel } from '@lssm/lib.schema';
+import type { OperationSpec, OpKind } from '../operations/index.js';
+import type { ResourceRefDescriptor } from '../resources.js';
+import type { HandlerCtx } from '../types.js';
+export type RuntimeContract = OperationSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+export interface SpecVariantResolver {
+    resolve(operation: {
+        name: string;
+        version: string;
+        kind: OpKind;
+    }, ctx: HandlerCtx): Promise<RuntimeContract | undefined> | RuntimeContract | undefined;
+}

package/dist/experiments/spec.d.ts

@@ -0,0 +1,81 @@
+/** Metadata for an experiment spec. */
+import type { DocBlock } from '../docs/types.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { PolicyRef } from '../policy/spec.js';
+import { SpecContractRegistry } from '../registry.js';
+import type { TelemetryEventDef } from '../telemetry/spec.js';
+import type { OptionalVersionedSpecRef } from '../versioning/index.js';
+export type ExperimentMeta = OwnerShipMeta;
+/**
+ * Reference to an experiment spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+export type ExperimentRef = OptionalVersionedSpecRef;
+export type ExperimentOverrideType = 'dataView' | 'workflow' | 'theme' | 'policy' | 'presentation';
+export interface ExperimentOverride {
+    type: ExperimentOverrideType;
+    /** Target spec meta name (e.g., DataViewspec.meta.key). */
+    target: string;
+    /** Target version. Optional; evaluator may choose latest when omitted. */
+    version?: string;
+    /** Optional configuration applied when this variant is active. */
+    config?: Record<string, unknown>;
+}
+export interface ExperimentVariant {
+    id: string;
+    key: string;
+    description?: string;
+    /** Relative weight for random allocation (defaults to 1). */
+    weight?: number;
+    overrides?: ExperimentOverride[];
+    /** Optional metadata for downstream analytics/UI. */
+    metadata?: Record<string, unknown>;
+}
+export interface TargetingRule {
+    /** Variant to assign when rule matches. */
+    variantId: string;
+    /** Optional percentage of matching traffic (0-1). If omitted, 100%. */
+    percentage?: number;
+    /** Policies that must allow the assignment. */
+    policy?: PolicyRef;
+    /** Expression evaluated against context (see evaluator for details). */
+    expression?: string;
+}
+export type AllocationStrategy = {
+    type: 'random';
+    /** Optional salt for deterministic hashing. */
+    salt?: string;
+} | {
+    type: 'sticky';
+    /** Which attribute to hash for sticky assignment. */
+    attribute: 'userId' | 'organizationId' | 'sessionId';
+    salt?: string;
+} | {
+    type: 'targeted';
+    rules: TargetingRule[];
+    fallback?: 'control' | 'random';
+};
+export type MetricAggregation = 'count' | 'avg' | 'p75' | 'p90' | 'p95' | 'p99';
+export interface SuccessMetric {
+    key: string;
+    telemetryEvent: {
+        key: TelemetryEventDef['key'];
+        version: string;
+    };
+    aggregation: MetricAggregation;
+    target?: number;
+}
+export interface ExperimentSpec {
+    meta: ExperimentMeta;
+    /** Identifier of the control variant (must exist in variants array). */
+    controlVariant: string;
+    variants: ExperimentVariant[];
+    allocation: AllocationStrategy;
+    successMetrics?: SuccessMetric[];
+    tags?: string[];
+}
+export declare class ExperimentRegistry extends SpecContractRegistry<'experiment', ExperimentSpec> {
+    constructor(items?: ExperimentSpec[]);
+}
+export declare function makeExperimentKey(meta: ExperimentMeta): string;
+export declare const tech_contracts_experiments_DocBlocks: DocBlock[];

package/dist/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/feature-hubs/federation.d.ts

@@ -0,0 +1,44 @@
+import type { HubPolicyEvaluation } from './policy.js';
+export declare const HUB_FEDERATION_CANONICALIZATION: 'RFC8785';
+export interface HubFederationParty {
+    readonly tenantId: string;
+    readonly systemId: string;
+}
+export interface HubFederationActor {
+    readonly actorId: string;
+    readonly actorType: 'user' | 'service' | 'agent';
+    readonly agentId?: string;
+}
+export interface HubFederationScope {
+    readonly capabilityIds: readonly string[];
+    readonly toolIds: readonly string[];
+    readonly resourceRefs: readonly string[];
+    readonly maxCostUnits: number;
+    readonly maxDurationMs: number;
+}
+export interface HubFederationEnvelope {
+    readonly issuer: HubFederationParty;
+    readonly audience: HubFederationParty;
+    readonly originalActor: HubFederationActor;
+    readonly keyId: string;
+    readonly algorithm: 'EdDSA' | 'ES256';
+    readonly issuedAt: string;
+    readonly notBefore: string;
+    readonly expiresAt: string;
+    readonly jti: string;
+    readonly scope: HubFederationScope;
+    readonly policyRef: string;
+    readonly correlationId: string;
+    readonly payloadDigest: string;
+    readonly signature: string;
+}
+export interface HubFederationVerificationContext {
+    readonly now: string;
+    readonly expectedAudience: HubFederationParty;
+    readonly requestedScope: HubFederationScope;
+    readonly actorCurrentScope: HubFederationScope;
+    readonly exposedScope: HubFederationScope;
+    readonly localPolicy: HubPolicyEvaluation;
+    readonly clockSkewSeconds?: number;
+}
+export type HubFederationDenialReason = 'expired' | 'not_yet_valid' | 'replayed' | 'revoked' | 'wrong_audience' | 'unknown_key' | 'tenant_mismatch' | 'digest_mismatch' | 'over_scoped' | 'policy_denied';

package/dist/feature-hubs/federation.js

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

package/dist/feature-hubs/index.d.ts

@@ -0,0 +1,6 @@
+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/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/feature-hubs/policy.d.ts

@@ -0,0 +1,30 @@
+export type HubPolicyDecision = 'allow' | 'deny' | 'require_approval';
+export type HubPolicyObligation = {
+    readonly kind: 'redact';
+    readonly fieldPaths: readonly string[];
+} | {
+    readonly kind: 'session_only';
+    readonly sessionId: string;
+} | {
+    readonly kind: 'reason';
+    readonly code: string;
+} | {
+    readonly kind: 'reevaluate';
+    readonly conditionRef: string;
+};
+export interface HubPolicyEvaluation {
+    readonly decision: HubPolicyDecision;
+    readonly obligations: readonly HubPolicyObligation[];
+    readonly policyRef: string;
+    readonly evaluatedAt: string;
+}
+export type LegacyHubPolicyEffect = 'allow' | 'deny' | 'require-approval' | 'redact' | 'allow-session-only' | 'disabled-with-reason' | 'conditional';
+export interface LegacyHubPolicyInput {
+    readonly effect: string;
+    readonly policyRef: string;
+    readonly evaluatedAt: string;
+    readonly fieldPaths?: readonly string[];
+    readonly sessionId?: string;
+    readonly reasonCode?: string;
+    readonly conditionRef?: string;
+}

package/dist/feature-hubs/ports.d.ts

@@ -0,0 +1,69 @@
+export interface HubIntentBinding {
+    readonly operation: string;
+    readonly payloadDigest: string;
+    readonly resourceRefs: Readonly<Record<string, string>>;
+}
+export interface HubIntentCreate {
+    readonly intentId: string;
+    readonly idempotencyKey: string;
+    readonly tenantId: string;
+    readonly state: 'pending';
+    readonly createdAt: string;
+    readonly binding: HubIntentBinding;
+}
+export interface HubIntentTransition {
+    readonly intentId: string;
+    readonly state: 'pending' | 'dispatching' | 'confirmed' | 'failed' | 'reconciliation_required';
+    readonly providerRequestId?: string;
+    readonly evidenceRef?: string;
+}
+export interface HubIntentRecord extends HubIntentTransition {
+    readonly binding: HubIntentBinding;
+    readonly idempotencyKey: string;
+    readonly tenantId: string;
+    readonly version: number;
+    readonly updatedAt: string;
+}
+export interface HubAtomicIntentPort {
+    createIfAbsent(input: HubIntentCreate): Promise<'created' | 'already_exists'>;
+    get(input: {
+        readonly intentId: string;
+    }): Promise<HubIntentRecord | undefined>;
+    queryRecoveryCandidates(input: {
+        readonly states: readonly ('dispatching' | 'reconciliation_required')[];
+        readonly before: string;
+        readonly limit: number;
+    }): Promise<readonly HubIntentRecord[]>;
+    claimRecovery(input: {
+        readonly intentId: string;
+        readonly expectedVersion: number;
+        readonly leaseId: string;
+        readonly fencingToken: number;
+    }): Promise<HubIntentRecord | undefined>;
+    transition(input: HubIntentTransition & {
+        readonly expectedVersion: number;
+    }): Promise<HubIntentRecord>;
+}
+export interface HubReplayProtectionPort {
+    consumeIfUnused(input: {
+        readonly namespace: string;
+        readonly key: string;
+        readonly expiresAt: string;
+    }): Promise<'consumed' | 'replayed'>;
+}
+export interface HubLeaseGrant {
+    readonly leaseId: string;
+    readonly fencingToken: number;
+    readonly expiresAt: string;
+}
+export interface HubLeasePort {
+    acquire(input: {
+        readonly resourceId: string;
+        readonly holderId: string;
+        readonly ttlMs: number;
+    }): Promise<HubLeaseGrant | undefined>;
+    renew(input: HubLeaseGrant & {
+        readonly ttlMs: number;
+    }): Promise<boolean>;
+    release(input: Pick<HubLeaseGrant, 'leaseId' | 'fencingToken'>): Promise<void>;
+}