@lssm/lib.contracts 0.0.0-canary-20251120170226

package/dist/data-views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-views.js","names":["candidate: DataViewSpec | undefined"],"sources":["../src/data-views.ts"],"sourcesContent":["import type { OwnerShipMeta } from './ownership';\nimport type { OpRef, EventRef, PresentationRef } from './features';\nimport type { ExperimentRef } from './experiments/spec';\n\nexport type DataViewKind = 'list' | 'detail' | 'table' | 'grid';\n\nexport interface DataViewMeta extends OwnerShipMeta {\n  /** Fully-qualified data view name (e.g., \"sigil.spaces.admin_list\"). */\n  name: string;\n  /** Version of this data view. Increment on breaking changes. */\n  version: number;\n  /** Canonical entity slug (e.g., \"space\", \"resident\"). */\n  entity: string;\n}\n\nexport interface DataViewSource {\n  /** Primary query used to fetch items for this view. */\n  primary: OpRef;\n  /** Optional operation used to fetch a single item (detail views). */\n  item?: OpRef;\n  /** Optional record mutation operations (used for inline editing or actions). */\n  mutations?: {\n    create?: OpRef;\n    update?: OpRef;\n    delete?: OpRef;\n  };\n  /** Events that should trigger refresh when emitted. */\n  refreshEvents?: EventRef[];\n}\n\nexport type DataViewFieldFormat =\n  | 'text'\n  | 'number'\n  | 'currency'\n  | 'percentage'\n  | 'date'\n  | 'dateTime'\n  | 'boolean'\n  | 'badge';\n\nexport interface DataViewField {\n  /** Unique identifier for the field within the view. */\n  key: string;\n  /** Human-friendly label for headers/tooltips. */\n  label: string;\n  /** Dot-path into the data item (e.g., \"address.city\"). */\n  dataPath: string;\n  /** Optional description surfaced in tooltips or docs. */\n  description?: string;\n  /** Optional formatting hint for renderers. */\n  format?: DataViewFieldFormat;\n  /** When true, the field can be used for sorting. */\n  sortable?: boolean;\n  /** When true, the field can be used for filtering. */\n  filterable?: boolean;\n  /** Optional width hint for table layouts. */\n  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';\n  /** Optional presentation override (e.g., card component). */\n  presentation?: PresentationRef;\n}\n\nexport interface DataViewFilter {\n  key: string;\n  label: string;\n  field: string;\n  type: 'search' | 'enum' | 'number' | 'date' | 'boolean';\n  options?: { value: string; label: string }[];\n}\n\nexport interface DataViewAction {\n  key: string;\n  label: string;\n  kind: 'navigation' | 'operation';\n  /** Operation invoked when kind === 'operation'. */\n  operation?: OpRef;\n  /** Optional feature flag gating the action. */\n  requiresFlag?: string;\n}\n\nexport interface DataViewSections {\n  title?: string;\n  description?: string;\n  fields: string[];\n}\n\nexport interface DataViewBaseConfig {\n  kind: DataViewKind;\n  fields: DataViewField[];\n  primaryField?: string;\n  secondaryFields?: string[];\n  filters?: DataViewFilter[];\n  actions?: DataViewAction[];\n}\n\nexport interface DataViewListConfig extends DataViewBaseConfig {\n  kind: 'list';\n  layout?: 'card' | 'compact';\n}\n\nexport interface DataViewDetailConfig extends DataViewBaseConfig {\n  kind: 'detail';\n  sections?: DataViewSections[];\n}\n\nexport interface DataViewTableColumn {\n  field: string;\n  label?: string;\n  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';\n  align?: 'left' | 'center' | 'right';\n}\n\nexport interface DataViewTableConfig extends DataViewBaseConfig {\n  kind: 'table';\n  columns?: DataViewTableColumn[];\n  rowSelectable?: boolean;\n  density?: 'comfortable' | 'compact';\n}\n\nexport interface DataViewGridConfig extends DataViewBaseConfig {\n  kind: 'grid';\n  columns?: number;\n}\n\nexport type DataViewConfig =\n  | DataViewListConfig\n  | DataViewDetailConfig\n  | DataViewTableConfig\n  | DataViewGridConfig;\n\nexport interface DataViewStates {\n  empty?: PresentationRef;\n  error?: PresentationRef;\n  loading?: PresentationRef;\n}\n\nexport interface DataViewSpec {\n  meta: DataViewMeta;\n  source: DataViewSource;\n  view: DataViewConfig;\n  states?: DataViewStates;\n  policy?: { flags?: string[]; pii?: string[] };\n  experiments?: ExperimentRef[];\n}\n\nfunction keyOf(spec: DataViewSpec) {\n  return `${spec.meta.name}.v${spec.meta.version}`;\n}\n\nexport class DataViewRegistry {\n  private readonly items = new Map<string, DataViewSpec>();\n\n  register(spec: DataViewSpec): this {\n    const key = keyOf(spec);\n    if (this.items.has(key)) throw new Error(`Duplicate data view ${key}`);\n    this.items.set(key, spec);\n    return this;\n  }\n\n  list(): DataViewSpec[] {\n    return [...this.items.values()];\n  }\n\n  get(name: string, version?: number): DataViewSpec | undefined {\n    if (version != null) return this.items.get(`${name}.v${version}`);\n    let candidate: DataViewSpec | undefined;\n    let max = -Infinity;\n    for (const spec of this.items.values()) {\n      if (spec.meta.name !== name) continue;\n      if (spec.meta.version > max) {\n        max = spec.meta.version;\n        candidate = spec;\n      }\n    }\n    return candidate;\n  }\n}\n\nexport function dataViewKey(spec: DataViewSpec) {\n  return keyOf(spec);\n}\n\n"],"mappings":"AAgJA,SAAS,EAAM,EAAoB,CACjC,MAAO,GAAG,EAAK,KAAK,KAAK,IAAI,EAAK,KAAK,UAGzC,IAAa,EAAb,KAA8B,CAC5B,MAAyB,IAAI,IAE7B,SAAS,EAA0B,CACjC,IAAM,EAAM,EAAM,EAAK,CACvB,GAAI,KAAK,MAAM,IAAI,EAAI,CAAE,MAAU,MAAM,uBAAuB,IAAM,CAEtE,OADA,KAAK,MAAM,IAAI,EAAK,EAAK,CAClB,KAGT,MAAuB,CACrB,MAAO,CAAC,GAAG,KAAK,MAAM,QAAQ,CAAC,CAGjC,IAAI,EAAc,EAA4C,CAC5D,GAAI,GAAW,KAAM,OAAO,KAAK,MAAM,IAAI,GAAG,EAAK,IAAI,IAAU,CACjE,IAAIA,EACA,EAAM,KACV,IAAK,IAAM,KAAQ,KAAK,MAAM,QAAQ,CAChC,EAAK,KAAK,OAAS,GACnB,EAAK,KAAK,QAAU,IACtB,EAAM,EAAK,KAAK,QAChB,EAAY,GAGhB,OAAO,IAIX,SAAgB,EAAY,EAAoB,CAC9C,OAAO,EAAM,EAAK"}

package/dist/events.d.ts

@@ -0,0 +1,45 @@
+import { OwnerShipMeta } from "./ownership.js";
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/events.d.ts
+
+/**
+ * Typed event specification. Declare once, validate payloads at publish time,
+ * and guard emissions via the contracts runtime.
+ */
+interface EventSpec<T extends AnySchemaModel> {
+  /** Fully-qualified event name, e.g. "sigil.magic_link.created". */
+  name: string;
+  /** Event payload version. Bump on any breaking payload change. */
+  version: number;
+  /** Short human-friendly summary. */
+  description?: string;
+  /** JSON-like paths to redact from logs/exports. */
+  pii?: string[];
+  /** Event payload schema from @lssm/lib.schema. */
+  payload: T;
+  /** Optional ownership metadata for governance and docs. */
+  ownership?: OwnerShipMeta;
+}
+/** Identity function to keep type inference when declaring events. */
+declare function defineEvent<T extends AnySchemaModel>(e: EventSpec<T>): EventSpec<T>;
+interface EventEnvelope<T> {
+  /** Unique identifier for the published event (UUID recommended). */
+  id: string;
+  /** ISO timestamp when the event occurred. */
+  occurredAt: string;
+  /** Optional trace identifier for correlating across services. */
+  traceId?: string;
+  /** Event name as published (should match spec.name). */
+  name: string;
+  /** Event version as published (should match spec.version). */
+  version: number;
+  /** Validated payload. */
+  payload: T;
+}
+type EventKey = `${string}.v${number}`;
+/** Build a stable string key for an event name/version pair. */
+declare const eventKey: (name: string, version: number) => EventKey;
+//#endregion
+export { EventEnvelope, EventKey, EventSpec, defineEvent, eventKey };
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","names":[],"sources":["../src/events.ts"],"sourcesContent":[],"mappings":";;;;;;;AAOA;;AAUW,UAVM,SAUN,CAAA,UAV0B,cAU1B,CAAA,CAAA;EAEG;EAAa,IAAA,EAAA,MAAA;EAIX;EAAsB,OAAA,EAAA,MAAA;EACvB;EAAV,WAAA,CAAA,EAAA,MAAA;EACQ;EAAV,GAAA,CAAA,EAAA,MAAA,EAAA;EAAS;EAIK,OAAA,EAZN,CAYM;EAeL;EAEC,SAAA,CAAA,EA3BC,aA2B2C;;;iBAvBzC,sBAAsB,mBACjC,UAAU,KACZ,UAAU;UAII;;;;;;;;;;;;WAYN;;KAGC,QAAA;;cAEC,6CAA4C"}

package/dist/events.js

@@ -0,0 +1,2 @@
+import"./schema/dist/index.js";function e(e){return e}const t=(e,t)=>`${e}.v${t}`;export{e as defineEvent,t as eventKey};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","names":[],"sources":["../src/events.ts"],"sourcesContent":["import { type AnySchemaModel } from '@lssm/lib.schema';\nimport type { OwnerShipMeta } from './ownership';\n\n/**\n * Typed event specification. Declare once, validate payloads at publish time,\n * and guard emissions via the contracts runtime.\n */\nexport interface EventSpec<T extends AnySchemaModel> {\n  /** Fully-qualified event name, e.g. \"sigil.magic_link.created\". */\n  name: string;\n  /** Event payload version. Bump on any breaking payload change. */\n  version: number;\n  /** Short human-friendly summary. */\n  description?: string;\n  /** JSON-like paths to redact from logs/exports. */\n  pii?: string[];\n  /** Event payload schema from @lssm/lib.schema. */\n  payload: T;\n  /** Optional ownership metadata for governance and docs. */\n  ownership?: OwnerShipMeta;\n}\n\n/** Identity function to keep type inference when declaring events. */\nexport function defineEvent<T extends AnySchemaModel>(\n  e: EventSpec<T>\n): EventSpec<T> {\n  return e;\n}\n\nexport interface EventEnvelope<T> {\n  /** Unique identifier for the published event (UUID recommended). */\n  id: string;\n  /** ISO timestamp when the event occurred. */\n  occurredAt: string;\n  /** Optional trace identifier for correlating across services. */\n  traceId?: string;\n  /** Event name as published (should match spec.name). */\n  name: string;\n  /** Event version as published (should match spec.version). */\n  version: number;\n  /** Validated payload. */\n  payload: T;\n}\n\nexport type EventKey = `${string}.v${number}`;\n/** Build a stable string key for an event name/version pair. */\nexport const eventKey = (name: string, version: number): EventKey =>\n  `${name}.v${version}`;\n"],"mappings":"+BAuBA,SAAgB,EACd,EACc,CACd,OAAO,EAoBT,MAAa,GAAY,EAAc,IACrC,GAAG,EAAK,IAAI"}

package/dist/experiments/evaluator.d.ts

@@ -0,0 +1,38 @@
+import { PolicyRef } from "../policy/spec.js";
+import { ExperimentRegistry, ExperimentVariant } from "./spec.js";
+
+//#region src/experiments/evaluator.d.ts
+interface ExperimentContext {
+  experiment: string;
+  version?: number;
+  userId?: string | null;
+  organizationId?: string | null;
+  sessionId?: string | null;
+  attributes?: Record<string, unknown>;
+  flags?: string[];
+}
+interface ExperimentEvaluation {
+  variant: ExperimentVariant;
+  reason: 'control' | 'random' | 'sticky' | 'targeted';
+}
+interface ExperimentEvaluatorConfig {
+  registry: ExperimentRegistry;
+  policyChecker?: (policy: PolicyRef, context: ExperimentContext) => Promise<boolean> | boolean;
+  expressionEvaluator?: (expression: string, context: ExperimentContext) => boolean;
+}
+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;
+}
+//#endregion
+export { ExperimentContext, ExperimentEvaluation, ExperimentEvaluator, ExperimentEvaluatorConfig };
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/experiments/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","names":[],"sources":["../../src/experiments/evaluator.ts"],"sourcesContent":[],"mappings":";;;;UAIiB,iBAAA;;EAAA,OAAA,CAAA,EAAA,MAAA;EAUA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;EAKA,cAAA,CAAA,EAAA,MAAA,GAAA,IAAyB;EAC9B,SAAA,CAAA,EAAA,MAAA,GAAA,IAAA;EACe,UAAA,CAAA,EAXZ,MAWY,CAAA,MAAA,EAAA,OAAA,CAAA;EAAoB,KAAA,CAAA,EAAA,MAAA,EAAA;;AACO,UARrC,oBAAA,CAQqC;EAAiB,OAAA,EAP5D,iBAO4D;EAG1D,MAAA,EAAA,SAAA,GAAA,QAAmB,GAAA,QAAA,GAAA,UAAA;;AAWD,UAjBd,yBAAA,CAiBc;EAA4B,QAAA,EAhB/C,kBAgB+C;EAAR,aAAA,CAAA,EAAA,CAAA,MAAA,EAfxB,SAewB,EAAA,OAAA,EAfJ,iBAeI,EAAA,GAfkB,OAelB,CAAA,OAAA,CAAA,GAAA,OAAA;EAAO,mBAAA,CAAA,EAAA,CAAA,UAAA,EAAA,MAAA,EAAA,OAAA,EAdJ,iBAcI,EAAA,GAAA,OAAA;;cAX7C,mBAAA;;;;sBAKS;yBAMS,oBAAoB,QAAQ"}

package/dist/experiments/evaluator.js

@@ -0,0 +1,2 @@
+import{createHash as e}from"node:crypto";var t=class{registry;policyChecker;expressionEvaluator;constructor(e){this.registry=e.registry,this.policyChecker=e.policyChecker,this.expressionEvaluator=e.expressionEvaluator}async chooseVariant(e){let t=this.registry.get(e.experiment,e.version);if(!t)return null;let n=t.variants.find(e=>e.id===t.controlVariant);if(!n)throw Error(`Experiment ${t.meta.name} missing control variant ${t.controlVariant}`);switch(t.allocation.type){case`random`:return{variant:this.pickByWeight(t,this.randomSeed(e,t.allocation.salt)),reason:`random`};case`sticky`:return{variant:this.pickByWeight(t,this.stickySeed(e,t.allocation.attribute,t.allocation.salt)),reason:`sticky`};case`targeted`:{let r=await this.evaluateTargeting(t,e,t.allocation.rules);return r?{variant:r,reason:`targeted`}:t.allocation.fallback===`random`?{variant:this.pickByWeight(t,this.randomSeed(e)),reason:`random`}:{variant:n,reason:`control`}}default:return{variant:n,reason:`control`}}}pickByWeight(e,t){let n=e.variants,r=t*n.reduce((e,t)=>e+(t.weight??1),0),i=0;for(let e of n)if(i+=e.weight??1,r<=i)return e;return n[n.length-1]}randomSeed(e,t=``){let n=e.sessionId??e.userId??e.organizationId??`${Date.now()}-${Math.random()}`;return this.hashToUnitInterval(n+t)}stickySeed(e,t,n=``){let r=e[t];return r?this.hashToUnitInterval(`${r}-${n}`):this.randomSeed(e,n)}hashToUnitInterval(t){let n=e(`sha256`).update(t).digest(`hex`).slice(0,15);return parseInt(n,16)%1e6/1e6}async evaluateTargeting(e,t,n){for(let r of n){if(!await this.matchesRule(r,t))continue;let n=e.variants.find(e=>e.id===r.variantId);if(n&&!(typeof r.percentage==`number`&&this.randomSeed(t,`rule-${r.variantId}`)>r.percentage))return n}return null}async matchesRule(e,t){if(e.policy&&this.policyChecker&&!await this.policyChecker(e.policy,t))return!1;if(e.expression){if(this.expressionEvaluator)return!!this.expressionEvaluator(e.expression,t);try{return!!Function(`context`,`return (${e.expression});`)(t)}catch{return!1}}return!0}};export{t as ExperimentEvaluator};
+//# sourceMappingURL=evaluator.js.map

package/dist/experiments/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","names":[],"sources":["../../src/experiments/evaluator.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport type { PolicyRef } from '../policy/spec';\nimport type { ExperimentRegistry, ExperimentSpec, ExperimentVariant, TargetingRule } from './spec';\n\nexport interface ExperimentContext {\n  experiment: string;\n  version?: number;\n  userId?: string | null;\n  organizationId?: string | null;\n  sessionId?: string | null;\n  attributes?: Record<string, unknown>;\n  flags?: string[];\n}\n\nexport interface ExperimentEvaluation {\n  variant: ExperimentVariant;\n  reason: 'control' | 'random' | 'sticky' | 'targeted';\n}\n\nexport interface ExperimentEvaluatorConfig {\n  registry: ExperimentRegistry;\n  policyChecker?: (policy: PolicyRef, context: ExperimentContext) => Promise<boolean> | boolean;\n  expressionEvaluator?: (expression: string, context: ExperimentContext) => boolean;\n}\n\nexport class ExperimentEvaluator {\n  private readonly registry: ExperimentRegistry;\n  private readonly policyChecker?: ExperimentEvaluatorConfig['policyChecker'];\n  private readonly expressionEvaluator?: ExperimentEvaluatorConfig['expressionEvaluator'];\n\n  constructor(config: ExperimentEvaluatorConfig) {\n    this.registry = config.registry;\n    this.policyChecker = config.policyChecker;\n    this.expressionEvaluator = config.expressionEvaluator;\n  }\n\n  async chooseVariant(context: ExperimentContext): Promise<ExperimentEvaluation | null> {\n    const experiment = this.registry.get(context.experiment, context.version);\n    if (!experiment) return null;\n\n    const control = experiment.variants.find((variant) => variant.id === experiment.controlVariant);\n    if (!control) throw new Error(`Experiment ${experiment.meta.name} missing control variant ${experiment.controlVariant}`);\n\n    switch (experiment.allocation.type) {\n      case 'random':\n        return {\n          variant: this.pickByWeight(experiment, this.randomSeed(context, experiment.allocation.salt)),\n          reason: 'random',\n        };\n      case 'sticky':\n        return {\n          variant: this.pickByWeight(\n            experiment,\n            this.stickySeed(context, experiment.allocation.attribute, experiment.allocation.salt)\n          ),\n          reason: 'sticky',\n        };\n      case 'targeted':\n        {\n          const targeted = await this.evaluateTargeting(experiment, context, experiment.allocation.rules);\n          if (targeted) {\n            return {\n              variant: targeted,\n              reason: 'targeted',\n            };\n          }\n          if (experiment.allocation.fallback === 'random') {\n            return {\n              variant: this.pickByWeight(experiment, this.randomSeed(context)),\n              reason: 'random',\n            };\n          }\n          return {\n            variant: control,\n            reason: 'control',\n          };\n        }\n      default:\n        return {\n          variant: control,\n          reason: 'control',\n        };\n    }\n  }\n\n  private pickByWeight(experiment: ExperimentSpec, seed: number): ExperimentVariant {\n    const variants = experiment.variants;\n    const totalWeight = variants.reduce((sum, variant) => sum + (variant.weight ?? 1), 0);\n    const target = seed * totalWeight;\n    let cumulative = 0;\n    for (const variant of variants) {\n      cumulative += variant.weight ?? 1;\n      if (target <= cumulative) {\n        return variant;\n      }\n    }\n    return variants[variants.length - 1]!;\n  }\n\n  private randomSeed(context: ExperimentContext, salt = ''): number {\n    const base =\n      context.sessionId ??\n      context.userId ??\n      context.organizationId ??\n      `${Date.now()}-${Math.random()}`;\n    return this.hashToUnitInterval(base + salt);\n  }\n\n  private stickySeed(context: ExperimentContext, attribute: 'userId' | 'organizationId' | 'sessionId', salt = ''): number {\n    const value = context[attribute];\n    if (!value) return this.randomSeed(context, salt);\n    return this.hashToUnitInterval(`${value}-${salt}`);\n  }\n\n  private hashToUnitInterval(value: string): number {\n    const hash = createHash('sha256').update(value).digest('hex').slice(0, 15);\n    const intValue = parseInt(hash, 16);\n    return (intValue % 1_000_000) / 1_000_000;\n  }\n\n  private async evaluateTargeting(\n    experiment: ExperimentSpec,\n    context: ExperimentContext,\n    rules: TargetingRule[]\n  ): Promise<ExperimentVariant | null> {\n    for (const rule of rules) {\n      if (!(await this.matchesRule(rule, context))) continue;\n      const variant = experiment.variants.find((v) => v.id === rule.variantId);\n      if (!variant) continue;\n      if (typeof rule.percentage === 'number') {\n        const seed = this.randomSeed(context, `rule-${rule.variantId}`);\n        if (seed > rule.percentage) {\n          continue;\n        }\n      }\n      return variant;\n    }\n    return null;\n  }\n\n  private async matchesRule(rule: TargetingRule, context: ExperimentContext): Promise<boolean> {\n    if (rule.policy && this.policyChecker) {\n      const allowed = await this.policyChecker(rule.policy, context);\n      if (!allowed) return false;\n    }\n    if (rule.expression) {\n      if (this.expressionEvaluator) {\n        return Boolean(this.expressionEvaluator(rule.expression, context));\n      }\n      try {\n        const fn = new Function('context', `return (${rule.expression});`);\n        return Boolean(fn(context));\n      } catch (_error) {\n        return false;\n      }\n    }\n    return true;\n  }\n}\n\n"],"mappings":"yCAyBA,IAAa,EAAb,KAAiC,CAC/B,SACA,cACA,oBAEA,YAAY,EAAmC,CAC7C,KAAK,SAAW,EAAO,SACvB,KAAK,cAAgB,EAAO,cAC5B,KAAK,oBAAsB,EAAO,oBAGpC,MAAM,cAAc,EAAkE,CACpF,IAAM,EAAa,KAAK,SAAS,IAAI,EAAQ,WAAY,EAAQ,QAAQ,CACzE,GAAI,CAAC,EAAY,OAAO,KAExB,IAAM,EAAU,EAAW,SAAS,KAAM,GAAY,EAAQ,KAAO,EAAW,eAAe,CAC/F,GAAI,CAAC,EAAS,MAAU,MAAM,cAAc,EAAW,KAAK,KAAK,2BAA2B,EAAW,iBAAiB,CAExH,OAAQ,EAAW,WAAW,KAA9B,CACE,IAAK,SACH,MAAO,CACL,QAAS,KAAK,aAAa,EAAY,KAAK,WAAW,EAAS,EAAW,WAAW,KAAK,CAAC,CAC5F,OAAQ,SACT,CACH,IAAK,SACH,MAAO,CACL,QAAS,KAAK,aACZ,EACA,KAAK,WAAW,EAAS,EAAW,WAAW,UAAW,EAAW,WAAW,KAAK,CACtF,CACD,OAAQ,SACT,CACH,IAAK,WACH,CACE,IAAM,EAAW,MAAM,KAAK,kBAAkB,EAAY,EAAS,EAAW,WAAW,MAAM,CAa/F,OAZI,EACK,CACL,QAAS,EACT,OAAQ,WACT,CAEC,EAAW,WAAW,WAAa,SAC9B,CACL,QAAS,KAAK,aAAa,EAAY,KAAK,WAAW,EAAQ,CAAC,CAChE,OAAQ,SACT,CAEI,CACL,QAAS,EACT,OAAQ,UACT,CAEL,QACE,MAAO,CACL,QAAS,EACT,OAAQ,UACT,EAIP,aAAqB,EAA4B,EAAiC,CAChF,IAAM,EAAW,EAAW,SAEtB,EAAS,EADK,EAAS,QAAQ,EAAK,IAAY,GAAO,EAAQ,QAAU,GAAI,EAAE,CAEjF,EAAa,EACjB,IAAK,IAAM,KAAW,EAEpB,GADA,GAAc,EAAQ,QAAU,EAC5B,GAAU,EACZ,OAAO,EAGX,OAAO,EAAS,EAAS,OAAS,GAGpC,WAAmB,EAA4B,EAAO,GAAY,CAChE,IAAM,EACJ,EAAQ,WACR,EAAQ,QACR,EAAQ,gBACR,GAAG,KAAK,KAAK,CAAC,GAAG,KAAK,QAAQ,GAChC,OAAO,KAAK,mBAAmB,EAAO,EAAK,CAG7C,WAAmB,EAA4B,EAAsD,EAAO,GAAY,CACtH,IAAM,EAAQ,EAAQ,GAEtB,OADK,EACE,KAAK,mBAAmB,GAAG,EAAM,GAAG,IAAO,CAD/B,KAAK,WAAW,EAAS,EAAK,CAInD,mBAA2B,EAAuB,CAChD,IAAM,EAAO,EAAW,SAAS,CAAC,OAAO,EAAM,CAAC,OAAO,MAAM,CAAC,MAAM,EAAG,GAAG,CAE1E,OADiB,SAAS,EAAM,GAAG,CAChB,IAAa,IAGlC,MAAc,kBACZ,EACA,EACA,EACmC,CACnC,IAAK,IAAM,KAAQ,EAAO,CACxB,GAAI,CAAE,MAAM,KAAK,YAAY,EAAM,EAAQ,CAAG,SAC9C,IAAM,EAAU,EAAW,SAAS,KAAM,GAAM,EAAE,KAAO,EAAK,UAAU,CACnE,QACD,OAAO,EAAK,YAAe,UAChB,KAAK,WAAW,EAAS,QAAQ,EAAK,YAAY,CACpD,EAAK,YAIlB,OAAO,EAET,OAAO,KAGT,MAAc,YAAY,EAAqB,EAA8C,CAC3F,GAAI,EAAK,QAAU,KAAK,eAElB,CADY,MAAM,KAAK,cAAc,EAAK,OAAQ,EAAQ,CAChD,MAAO,GAEvB,GAAI,EAAK,WAAY,CACnB,GAAI,KAAK,oBACP,MAAO,EAAQ,KAAK,oBAAoB,EAAK,WAAY,EAAQ,CAEnE,GAAI,CAEF,MAAO,EADQ,SAAS,UAAW,WAAW,EAAK,WAAW,IAAI,CAChD,EAAQ,MACX,CACf,MAAO,IAGX,MAAO"}

package/dist/experiments/spec.d.ts

@@ -0,0 +1,90 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { PolicyRef } from "../policy/spec.js";
+import { TelemetryEventDef } from "../telemetry/spec.js";
+
+//#region src/experiments/spec.d.ts
+interface ExperimentMeta extends OwnerShipMeta {
+  /** Fully-qualified experiment name (e.g., "sigil.onboarding.variant"). */
+  name: string;
+  /** Version of the experiment; bump when allocation or variants change materially. */
+  version: number;
+  /** Domain/bounded context (e.g., "onboarding"). */
+  domain: string;
+}
+interface ExperimentRef {
+  name: string;
+  version?: number;
+}
+type ExperimentOverrideType = 'dataView' | 'workflow' | 'theme' | 'policy' | 'presentation';
+interface ExperimentOverride {
+  type: ExperimentOverrideType;
+  /** Target spec meta name (e.g., DataViewSpec.meta.name). */
+  target: string;
+  /** Target version. Optional; evaluator may choose latest when omitted. */
+  version?: number;
+  /** Optional configuration applied when this variant is active. */
+  config?: Record<string, unknown>;
+}
+interface ExperimentVariant {
+  id: string;
+  name: 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>;
+}
+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;
+}
+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';
+};
+type MetricAggregation = 'count' | 'avg' | 'p75' | 'p90' | 'p95' | 'p99';
+interface SuccessMetric {
+  name: string;
+  telemetryEvent: {
+    name: TelemetryEventDef['name'];
+    version: number;
+  };
+  aggregation: MetricAggregation;
+  target?: number;
+}
+interface ExperimentSpec {
+  meta: ExperimentMeta;
+  /** Identifier of the control variant (must exist in variants array). */
+  controlVariant: string;
+  variants: ExperimentVariant[];
+  allocation: AllocationStrategy;
+  successMetrics?: SuccessMetric[];
+  tags?: string[];
+}
+declare class ExperimentRegistry {
+  private readonly items;
+  register(spec: ExperimentSpec): this;
+  list(): ExperimentSpec[];
+  get(name: string, version?: number): ExperimentSpec | undefined;
+}
+declare function makeExperimentKey(meta: ExperimentMeta): string;
+//#endregion
+export { AllocationStrategy, ExperimentMeta, ExperimentOverride, ExperimentOverrideType, ExperimentRef, ExperimentRegistry, ExperimentSpec, ExperimentVariant, MetricAggregation, SuccessMetric, TargetingRule, makeExperimentKey };
+//# sourceMappingURL=spec.d.ts.map

package/dist/experiments/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../src/experiments/spec.ts"],"sourcesContent":[],"mappings":";;;;;UAIiB,cAAA,SAAuB;;EAAvB,IAAA,EAAA,MAAA;EASA;EAKL,OAAA,EAAA,MAAA;EAOK;EAUA,MAAA,EAAA,MAAA;AAWjB;AAWY,UA5CK,aAAA,CA4Ca;EAkBlB,IAAA,EAAA,MAAA;EAEK,OAAA,CAAA,EAAA,MAAa;AAO9B;AACQ,KAnEI,sBAAA,GAmEJ,UAAA,GAAA,UAAA,GAAA,OAAA,GAAA,QAAA,GAAA,cAAA;AAGI,UA/DK,kBAAA,CA+DL;EACE,IAAA,EA/DN,sBA+DM;EACK;EAAa,MAAA,EAAA,MAAA;EAMnB;EAGI,OAAA,CAAA,EAAA,MAAA;EASP;EAI6B,MAAA,CAAA,EAhF5B,MAgF4B,CAAA,MAAA,EAAA,OAAA,CAAA;;AAiBvB,UA9FC,iBAAA,CA8FgB;;;;;;cAxFnB;;aAED;;UAGI,aAAA;;;;;;WAMN;;;;KAKC,kBAAA;;;;;;;;;;;SAcC;;;KAID,iBAAA;UAEK,aAAA;;;UAES;;;eACX;;;UAIE,cAAA;QACT;;;YAGI;cACE;mBACK;;;cAMN,kBAAA;;iBAGI;UASP;uCAI6B;;iBAiBvB,iBAAA,OAAwB"}

package/dist/experiments/spec.js

@@ -0,0 +1,2 @@
+const e=e=>`${e.name}.v${e.version}`;var t=class{items=new Map;register(t){let n=e(t.meta);if(this.items.has(n))throw Error(`Duplicate experiment ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n,r=-1/0;for(let t of this.items.values())t.meta.name===e&&t.meta.version>r&&(r=t.meta.version,n=t);return n}};function n(t){return e(t)}export{t as ExperimentRegistry,n as makeExperimentKey};
+//# sourceMappingURL=spec.js.map

package/dist/experiments/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","names":["latest: ExperimentSpec | undefined"],"sources":["../../src/experiments/spec.ts"],"sourcesContent":["import type { OwnerShipMeta } from '../ownership';\nimport type { PolicyRef } from '../policy/spec';\nimport type { TelemetryEventDef } from '../telemetry/spec';\n\nexport interface ExperimentMeta extends OwnerShipMeta {\n  /** Fully-qualified experiment name (e.g., \"sigil.onboarding.variant\"). */\n  name: string;\n  /** Version of the experiment; bump when allocation or variants change materially. */\n  version: number;\n  /** Domain/bounded context (e.g., \"onboarding\"). */\n  domain: string;\n}\n\nexport interface ExperimentRef {\n  name: string;\n  version?: number;\n}\n\nexport type ExperimentOverrideType =\n  | 'dataView'\n  | 'workflow'\n  | 'theme'\n  | 'policy'\n  | 'presentation';\n\nexport interface ExperimentOverride {\n  type: ExperimentOverrideType;\n  /** Target spec meta name (e.g., DataViewSpec.meta.name). */\n  target: string;\n  /** Target version. Optional; evaluator may choose latest when omitted. */\n  version?: number;\n  /** Optional configuration applied when this variant is active. */\n  config?: Record<string, unknown>;\n}\n\nexport interface ExperimentVariant {\n  id: string;\n  name: string;\n  description?: string;\n  /** Relative weight for random allocation (defaults to 1). */\n  weight?: number;\n  overrides?: ExperimentOverride[];\n  /** Optional metadata for downstream analytics/UI. */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface TargetingRule {\n  /** Variant to assign when rule matches. */\n  variantId: string;\n  /** Optional percentage of matching traffic (0-1). If omitted, 100%. */\n  percentage?: number;\n  /** Policies that must allow the assignment. */\n  policy?: PolicyRef;\n  /** Expression evaluated against context (see evaluator for details). */\n  expression?: string;\n}\n\nexport type AllocationStrategy =\n  | {\n      type: 'random';\n      /** Optional salt for deterministic hashing. */\n      salt?: string;\n    }\n  | {\n      type: 'sticky';\n      /** Which attribute to hash for sticky assignment. */\n      attribute: 'userId' | 'organizationId' | 'sessionId';\n      salt?: string;\n    }\n  | {\n      type: 'targeted';\n      rules: TargetingRule[];\n      fallback?: 'control' | 'random';\n    };\n\nexport type MetricAggregation = 'count' | 'avg' | 'p75' | 'p90' | 'p95' | 'p99';\n\nexport interface SuccessMetric {\n  name: string;\n  telemetryEvent: { name: TelemetryEventDef['name']; version: number };\n  aggregation: MetricAggregation;\n  target?: number;\n}\n\nexport interface ExperimentSpec {\n  meta: ExperimentMeta;\n  /** Identifier of the control variant (must exist in variants array). */\n  controlVariant: string;\n  variants: ExperimentVariant[];\n  allocation: AllocationStrategy;\n  successMetrics?: SuccessMetric[];\n  tags?: string[];\n}\n\nconst experimentKey = (meta: ExperimentMeta) => `${meta.name}.v${meta.version}`;\n\nexport class ExperimentRegistry {\n  private readonly items = new Map<string, ExperimentSpec>();\n\n  register(spec: ExperimentSpec): this {\n    const key = experimentKey(spec.meta);\n    if (this.items.has(key)) {\n      throw new Error(`Duplicate experiment ${key}`);\n    }\n    this.items.set(key, spec);\n    return this;\n  }\n\n  list(): ExperimentSpec[] {\n    return [...this.items.values()];\n  }\n\n  get(name: string, version?: number): ExperimentSpec | undefined {\n    if (version != null) {\n      return this.items.get(`${name}.v${version}`);\n    }\n    let latest: ExperimentSpec | undefined;\n    let maxVersion = -Infinity;\n    for (const spec of this.items.values()) {\n      if (spec.meta.name !== name) continue;\n      if (spec.meta.version > maxVersion) {\n        maxVersion = spec.meta.version;\n        latest = spec;\n      }\n    }\n    return latest;\n  }\n}\n\nexport function makeExperimentKey(meta: ExperimentMeta) {\n  return experimentKey(meta);\n}\n\n"],"mappings":"AA8FA,MAAM,EAAiB,GAAyB,GAAG,EAAK,KAAK,IAAI,EAAK,UAEtE,IAAa,EAAb,KAAgC,CAC9B,MAAyB,IAAI,IAE7B,SAAS,EAA4B,CACnC,IAAM,EAAM,EAAc,EAAK,KAAK,CACpC,GAAI,KAAK,MAAM,IAAI,EAAI,CACrB,MAAU,MAAM,wBAAwB,IAAM,CAGhD,OADA,KAAK,MAAM,IAAI,EAAK,EAAK,CAClB,KAGT,MAAyB,CACvB,MAAO,CAAC,GAAG,KAAK,MAAM,QAAQ,CAAC,CAGjC,IAAI,EAAc,EAA8C,CAC9D,GAAI,GAAW,KACb,OAAO,KAAK,MAAM,IAAI,GAAG,EAAK,IAAI,IAAU,CAE9C,IAAIA,EACA,EAAa,KACjB,IAAK,IAAM,KAAQ,KAAK,MAAM,QAAQ,CAChC,EAAK,KAAK,OAAS,GACnB,EAAK,KAAK,QAAU,IACtB,EAAa,EAAK,KAAK,QACvB,EAAS,GAGb,OAAO,IAIX,SAAgB,EAAkB,EAAsB,CACtD,OAAO,EAAc,EAAK"}

package/dist/features.d.ts

@@ -0,0 +1,88 @@
+import { OwnerShipMeta } from "./ownership.js";
+import { CapabilityRef, CapabilityRegistry, CapabilityRequirement } from "./capabilities.js";
+import { PresentationRegistry } from "./presentations.js";
+import { PresentationDescriptorV2, PresentationTarget } from "./presentations.v2.js";
+import { ExperimentRef } from "./experiments/spec.js";
+import { SpecRegistry } from "./registry.js";
+
+//#region src/features.d.ts
+/** Minimal metadata to identify and categorize a feature module. */
+interface FeatureModuleMeta extends OwnerShipMeta {
+  /** Stable slug key used to identify this feature (e.g., "weekly_pulse"). */
+  key: string;
+}
+interface OpRef {
+  /** Operation name (ContractSpec.meta.name). */
+  name: string;
+  /** Operation version (ContractSpec.meta.version). */
+  version: number;
+}
+interface EventRef {
+  /** Event name. */
+  name: string;
+  /** Event version. */
+  version: number;
+}
+interface PresentationRef {
+  /** Presentation name. */
+  name: string;
+  /** Presentation version. */
+  version: number;
+}
+/** Group operations/events/presentations into an installable feature. */
+interface FeatureModuleSpec {
+  meta: FeatureModuleMeta;
+  /** Contract operations included in this feature. */
+  operations?: OpRef[];
+  /** Events declared/emitted by this feature. */
+  events?: EventRef[];
+  /** Presentations associated to this feature. */
+  presentations?: PresentationRef[];
+  /** Experiments related to this feature. */
+  experiments?: ExperimentRef[];
+  /** Capability bindings exposed/required by this feature. */
+  capabilities?: {
+    provides?: CapabilityRef[];
+    requires?: CapabilityRequirement[];
+  };
+  /** Optional: link ops to presentations for traceability (e.g., ui for op) */
+  opToPresentation?: {
+    op: OpRef;
+    pres: PresentationRef;
+  }[];
+  /** Optional: declare per-presentation target requirements (V2 descriptors) */
+  presentationsTargets?: {
+    /** Presentation name. */
+    name: string;
+    /** Presentation version. */
+    version: number;
+    /** Required targets that must be supported by the descriptor. */
+    targets: PresentationTarget[];
+  }[];
+}
+interface FeatureRef {
+  key: string;
+}
+/** In-memory registry for FeatureModuleSpec. */
+declare class FeatureRegistry {
+  private items;
+  /** Register a feature module. Throws when the key already exists. */
+  register(f: FeatureModuleSpec): this;
+  /** List all registered feature modules. */
+  list(): FeatureModuleSpec[];
+  /** Get a feature by its key (slug). */
+  get(key: string): FeatureModuleSpec | undefined;
+}
+/** Validate and register a feature against optional registries/descriptors. */
+declare function installFeature(feature: FeatureModuleSpec, deps: {
+  features: FeatureRegistry;
+  ops?: SpecRegistry;
+  presentations?: PresentationRegistry;
+  descriptorsV2?: PresentationDescriptorV2[];
+  capabilities?: CapabilityRegistry;
+}): FeatureRegistry;
+/** Ensure declared target requirements exist on the provided descriptors. */
+declare function validateFeatureTargetsV2(feature: FeatureModuleSpec, descriptors: PresentationDescriptorV2[]): boolean;
+//#endregion
+export { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FeatureRegistry, OpRef, PresentationRef, installFeature, validateFeatureTargetsV2 };
+//# sourceMappingURL=features.d.ts.map

package/dist/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","names":[],"sources":["../src/features.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAaiB,iBAAA,SAA0B;;;AAA3C;AAKiB,UAAA,KAAA,CAAK;EAOL;EAOA,IAAA,EAAA,MAAA;EAQA;EACT,OAAA,EAAA,MAAA;;AAIG,UApBM,QAAA,CAoBN;EAEO;EAEF,IAAA,EAAA,MAAA;EAGD;EACA,OAAA,EAAA,MAAA;;AAGyB,UAxBvB,eAAA,CAwBuB;EAQ3B;EAAkB,IAAA,EAAA,MAAA;EAId;EASJ,OAAA,EAAA,MAAA;;;AAiBO,UAtDH,iBAAA,CAsDG;EAAiB,IAAA,EArD7B,iBAqD6B;EAMrB;EACL,UAAA,CAAA,EA1DI,KA0DJ,EAAA;EAEG;EAAe,MAAA,CAAA,EA1DlB,QA0DkB,EAAA;EACc;EAEvB,aAAA,CAAA,EA3DF,eA2DE,EAAA;EACD;EAChB,WAAA,CAAA,EA3Da,aA2Db,EAAA;EAAA;EAwFa,YAAA,CAAA,EAAA;eAhJD;eACA;;;;QAGY;UAAa;;;;;;;;;aAQ3B;;;UAII,UAAA;;;;cASJ,eAAA;;;cAIC;;UAQJ;;oBAKU;;;iBAMJ,cAAA,UACL;YAEG;QAAe;kBACc;kBAEvB;iBACD;IAChB;;iBAwFa,wBAAA,UACL,gCACI"}

package/dist/features.js

@@ -0,0 +1,2 @@
+function e(e){return e.meta.key}var t=class{items=new Map;register(t){let n=e(t);if(this.items.has(n))throw Error(`Duplicate feature ${n}`);return this.items.set(n,t),this}list(){return[...this.items.values()]}get(e){return this.items.get(e)}};function n(e,t){if(t.ops&&e.operations){for(let n of e.operations)if(!t.ops.getSpec(n.name,n.version))throw Error(`installFeature: operation not found ${n.name}.v${n.version}`)}if(t.presentations&&e.presentations){for(let n of e.presentations)if(!t.presentations.get(n.name,n.version))throw Error(`installFeature: presentation not found ${n.name}.v${n.version}`)}if(e.presentationsTargets&&t.descriptorsV2)for(let n of e.presentationsTargets){let e=t.descriptorsV2.find(e=>e.meta.name===n.name&&e.meta.version===n.version);if(!e)throw Error(`installFeature: V2 descriptor not found ${n.name}.v${n.version}`);for(let t of n.targets)if(!e.targets.includes(t))throw Error(`installFeature: descriptor ${n.name}.v${n.version} missing target ${t}`)}if(e.opToPresentation&&e.opToPresentation.length>0)for(let n of e.opToPresentation){if(t.ops&&!t.ops.getSpec(n.op.name,n.op.version))throw Error(`installFeature: linked op not found ${n.op.name}.v${n.op.version}`);if(t.presentations&&!t.presentations.get(n.pres.name,n.pres.version))throw Error(`installFeature: linked presentation not found ${n.pres.name}.v${n.pres.version}`)}if(t.capabilities&&e.capabilities?.provides){for(let n of e.capabilities.provides)if(!t.capabilities.get(n.key,n.version))throw Error(`installFeature: capability not registered ${n.key}.v${n.version}`)}if(e.capabilities?.requires?.length){if(!t.capabilities)throw Error(`installFeature: capability registry required to validate capability requirements for ${e.meta.key}`);let n=e.capabilities.provides??[];for(let r of e.capabilities.requires)if(!t.capabilities.satisfies(r,n))throw Error(`installFeature: capability requirement not satisfied ${r.key}${r.version?`.v${r.version}`:``}`)}return t.features.register(e),t.features}function r(e,t){if(!e.presentationsTargets||e.presentationsTargets.length===0)return!0;for(let n of e.presentationsTargets){let e=t.find(e=>e.meta.name===n.name&&e.meta.version===n.version);if(!e)throw Error(`V2 descriptor not found ${n.name}.v${n.version}`);for(let t of n.targets)if(!e.targets.includes(t))throw Error(`Descriptor ${n.name}.v${n.version} missing target ${t}`)}return!0}export{t as FeatureRegistry,n as installFeature,r as validateFeatureTargetsV2};
+//# sourceMappingURL=features.js.map

package/dist/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","names":[],"sources":["../src/features.ts"],"sourcesContent":["import type {\n  PresentationTarget,\n  PresentationDescriptorV2,\n} from './presentations.v2';\nimport type { OwnerShipMeta } from './ownership';\nimport type {\n  CapabilityRef,\n  CapabilityRequirement,\n  CapabilityRegistry,\n} from './capabilities';\nimport type { ExperimentRef } from './experiments/spec';\n\n/** Minimal metadata to identify and categorize a feature module. */\nexport interface FeatureModuleMeta extends OwnerShipMeta {\n  /** Stable slug key used to identify this feature (e.g., \"weekly_pulse\"). */\n  key: string;\n}\n\nexport interface OpRef {\n  /** Operation name (ContractSpec.meta.name). */\n  name: string;\n  /** Operation version (ContractSpec.meta.version). */\n  version: number;\n}\n\nexport interface EventRef {\n  /** Event name. */\n  name: string;\n  /** Event version. */\n  version: number;\n}\n\nexport interface PresentationRef {\n  /** Presentation name. */\n  name: string;\n  /** Presentation version. */\n  version: number;\n}\n\n/** Group operations/events/presentations into an installable feature. */\nexport interface FeatureModuleSpec {\n  meta: FeatureModuleMeta;\n  /** Contract operations included in this feature. */\n  operations?: OpRef[];\n  /** Events declared/emitted by this feature. */\n  events?: EventRef[];\n  /** Presentations associated to this feature. */\n  presentations?: PresentationRef[];\n  /** Experiments related to this feature. */\n  experiments?: ExperimentRef[];\n  /** Capability bindings exposed/required by this feature. */\n  capabilities?: {\n    provides?: CapabilityRef[];\n    requires?: CapabilityRequirement[];\n  };\n  /** Optional: link ops to presentations for traceability (e.g., ui for op) */\n  opToPresentation?: { op: OpRef; pres: PresentationRef }[];\n  /** Optional: declare per-presentation target requirements (V2 descriptors) */\n  presentationsTargets?: {\n    /** Presentation name. */\n    name: string;\n    /** Presentation version. */\n    version: number;\n    /** Required targets that must be supported by the descriptor. */\n    targets: PresentationTarget[];\n  }[];\n}\n\nexport interface FeatureRef {\n  key: string;\n}\n\nfunction keyOf(f: FeatureModuleSpec) {\n  return f.meta.key;\n}\n\n/** In-memory registry for FeatureModuleSpec. */\nexport class FeatureRegistry {\n  private items = new Map<string, FeatureModuleSpec>();\n\n  /** Register a feature module. Throws when the key already exists. */\n  register(f: FeatureModuleSpec): this {\n    const key = keyOf(f);\n    if (this.items.has(key)) throw new Error(`Duplicate feature ${key}`);\n    this.items.set(key, f);\n    return this;\n  }\n\n  /** List all registered feature modules. */\n  list(): FeatureModuleSpec[] {\n    return [...this.items.values()];\n  }\n\n  /** Get a feature by its key (slug). */\n  get(key: string): FeatureModuleSpec | undefined {\n    return this.items.get(key);\n  }\n}\n\n/** Validate and register a feature against optional registries/descriptors. */\nexport function installFeature(\n  feature: FeatureModuleSpec,\n  deps: {\n    features: FeatureRegistry;\n    ops?: import('./registry').SpecRegistry;\n    presentations?: import('./presentations').PresentationRegistry;\n    descriptorsV2?: PresentationDescriptorV2[];\n    capabilities?: CapabilityRegistry;\n  }\n) {\n  // Validate referenced ops exist if registry provided\n  if (deps.ops && feature.operations) {\n    for (const o of feature.operations) {\n      const s = deps.ops.getSpec(o.name, o.version);\n      if (!s)\n        throw new Error(\n          `installFeature: operation not found ${o.name}.v${o.version}`\n        );\n    }\n  }\n  // Validate referenced presentations exist if registry provided\n  if (deps.presentations && feature.presentations) {\n    for (const p of feature.presentations) {\n      const pres = deps.presentations.get(p.name, p.version);\n      if (!pres)\n        throw new Error(\n          `installFeature: presentation not found ${p.name}.v${p.version}`\n        );\n    }\n  }\n  // Validate V2 target requirements if provided\n  if (feature.presentationsTargets && deps.descriptorsV2) {\n    for (const req of feature.presentationsTargets) {\n      const d = deps.descriptorsV2.find(\n        (x) => x.meta.name === req.name && x.meta.version === req.version\n      );\n      if (!d)\n        throw new Error(\n          `installFeature: V2 descriptor not found ${req.name}.v${req.version}`\n        );\n      for (const t of req.targets) {\n        if (!d.targets.includes(t))\n          throw new Error(\n            `installFeature: descriptor ${req.name}.v${req.version} missing target ${t}`\n          );\n      }\n    }\n  }\n  // Validate op→presentation links\n  if (feature.opToPresentation && feature.opToPresentation.length > 0) {\n    for (const link of feature.opToPresentation) {\n      if (deps.ops) {\n        const s = deps.ops.getSpec(link.op.name, link.op.version);\n        if (!s)\n          throw new Error(\n            `installFeature: linked op not found ${link.op.name}.v${link.op.version}`\n          );\n      }\n      if (deps.presentations) {\n        const pres = deps.presentations.get(link.pres.name, link.pres.version);\n        if (!pres)\n          throw new Error(\n            `installFeature: linked presentation not found ${link.pres.name}.v${link.pres.version}`\n          );\n      }\n    }\n  }\n  // Validate capability bindings when registry provided\n  if (deps.capabilities && feature.capabilities?.provides) {\n    for (const cap of feature.capabilities.provides) {\n      const spec = deps.capabilities.get(cap.key, cap.version);\n      if (!spec)\n        throw new Error(\n          `installFeature: capability not registered ${cap.key}.v${cap.version}`\n        );\n    }\n  }\n  if (feature.capabilities?.requires?.length) {\n    if (!deps.capabilities)\n      throw new Error(\n        `installFeature: capability registry required to validate capability requirements for ${feature.meta.key}`\n      );\n    const provided = feature.capabilities.provides ?? [];\n    for (const req of feature.capabilities.requires) {\n      const satisfied = deps.capabilities.satisfies(req, provided);\n      if (!satisfied)\n        throw new Error(\n          `installFeature: capability requirement not satisfied ${req.key}${req.version ? `.v${req.version}` : ''}`\n        );\n    }\n  }\n  deps.features.register(feature);\n  return deps.features;\n}\n\n/** Ensure declared target requirements exist on the provided descriptors. */\nexport function validateFeatureTargetsV2(\n  feature: FeatureModuleSpec,\n  descriptors: PresentationDescriptorV2[]\n) {\n  if (\n    !feature.presentationsTargets ||\n    feature.presentationsTargets.length === 0\n  )\n    return true;\n  for (const req of feature.presentationsTargets) {\n    const d = descriptors.find(\n      (x) => x.meta.name === req.name && x.meta.version === req.version\n    );\n    if (!d)\n      throw new Error(`V2 descriptor not found ${req.name}.v${req.version}`);\n    for (const t of req.targets)\n      if (!d.targets.includes(t))\n        throw new Error(\n          `Descriptor ${req.name}.v${req.version} missing target ${t}`\n        );\n  }\n  return true;\n}\n"],"mappings":"AAwEA,SAAS,EAAM,EAAsB,CACnC,OAAO,EAAE,KAAK,IAIhB,IAAa,EAAb,KAA6B,CAC3B,MAAgB,IAAI,IAGpB,SAAS,EAA4B,CACnC,IAAM,EAAM,EAAM,EAAE,CACpB,GAAI,KAAK,MAAM,IAAI,EAAI,CAAE,MAAU,MAAM,qBAAqB,IAAM,CAEpE,OADA,KAAK,MAAM,IAAI,EAAK,EAAE,CACf,KAIT,MAA4B,CAC1B,MAAO,CAAC,GAAG,KAAK,MAAM,QAAQ,CAAC,CAIjC,IAAI,EAA4C,CAC9C,OAAO,KAAK,MAAM,IAAI,EAAI,GAK9B,SAAgB,EACd,EACA,EAOA,CAEA,GAAI,EAAK,KAAO,EAAQ,gBACjB,IAAM,KAAK,EAAQ,WAEtB,GAAI,CADM,EAAK,IAAI,QAAQ,EAAE,KAAM,EAAE,QAAQ,CAE3C,MAAU,MACR,uCAAuC,EAAE,KAAK,IAAI,EAAE,UACrD,CAIP,GAAI,EAAK,eAAiB,EAAQ,mBAC3B,IAAM,KAAK,EAAQ,cAEtB,GAAI,CADS,EAAK,cAAc,IAAI,EAAE,KAAM,EAAE,QAAQ,CAEpD,MAAU,MACR,0CAA0C,EAAE,KAAK,IAAI,EAAE,UACxD,CAIP,GAAI,EAAQ,sBAAwB,EAAK,cACvC,IAAK,IAAM,KAAO,EAAQ,qBAAsB,CAC9C,IAAM,EAAI,EAAK,cAAc,KAC1B,GAAM,EAAE,KAAK,OAAS,EAAI,MAAQ,EAAE,KAAK,UAAY,EAAI,QAC3D,CACD,GAAI,CAAC,EACH,MAAU,MACR,2CAA2C,EAAI,KAAK,IAAI,EAAI,UAC7D,CACH,IAAK,IAAM,KAAK,EAAI,QAClB,GAAI,CAAC,EAAE,QAAQ,SAAS,EAAE,CACxB,MAAU,MACR,8BAA8B,EAAI,KAAK,IAAI,EAAI,QAAQ,kBAAkB,IAC1E,CAKT,GAAI,EAAQ,kBAAoB,EAAQ,iBAAiB,OAAS,EAChE,IAAK,IAAM,KAAQ,EAAQ,iBAAkB,CAC3C,GAAI,EAAK,KAEH,CADM,EAAK,IAAI,QAAQ,EAAK,GAAG,KAAM,EAAK,GAAG,QAAQ,CAEvD,MAAU,MACR,uCAAuC,EAAK,GAAG,KAAK,IAAI,EAAK,GAAG,UACjE,CAEL,GAAI,EAAK,eAEH,CADS,EAAK,cAAc,IAAI,EAAK,KAAK,KAAM,EAAK,KAAK,QAAQ,CAEpE,MAAU,MACR,iDAAiD,EAAK,KAAK,KAAK,IAAI,EAAK,KAAK,UAC/E,CAKT,GAAI,EAAK,cAAgB,EAAQ,cAAc,cACxC,IAAM,KAAO,EAAQ,aAAa,SAErC,GAAI,CADS,EAAK,aAAa,IAAI,EAAI,IAAK,EAAI,QAAQ,CAEtD,MAAU,MACR,6CAA6C,EAAI,IAAI,IAAI,EAAI,UAC9D,CAGP,GAAI,EAAQ,cAAc,UAAU,OAAQ,CAC1C,GAAI,CAAC,EAAK,aACR,MAAU,MACR,wFAAwF,EAAQ,KAAK,MACtG,CACH,IAAM,EAAW,EAAQ,aAAa,UAAY,EAAE,CACpD,IAAK,IAAM,KAAO,EAAQ,aAAa,SAErC,GAAI,CADc,EAAK,aAAa,UAAU,EAAK,EAAS,CAE1D,MAAU,MACR,wDAAwD,EAAI,MAAM,EAAI,QAAU,KAAK,EAAI,UAAY,KACtG,CAIP,OADA,EAAK,SAAS,SAAS,EAAQ,CACxB,EAAK,SAId,SAAgB,EACd,EACA,EACA,CACA,GACE,CAAC,EAAQ,sBACT,EAAQ,qBAAqB,SAAW,EAExC,MAAO,GACT,IAAK,IAAM,KAAO,EAAQ,qBAAsB,CAC9C,IAAM,EAAI,EAAY,KACnB,GAAM,EAAE,KAAK,OAAS,EAAI,MAAQ,EAAE,KAAK,UAAY,EAAI,QAC3D,CACD,GAAI,CAAC,EACH,MAAU,MAAM,2BAA2B,EAAI,KAAK,IAAI,EAAI,UAAU,CACxE,IAAK,IAAM,KAAK,EAAI,QAClB,GAAI,CAAC,EAAE,QAAQ,SAAS,EAAE,CACxB,MAAU,MACR,cAAc,EAAI,KAAK,IAAI,EAAI,QAAQ,kBAAkB,IAC1D,CAEP,MAAO"}

package/dist/forms.d.ts

@@ -0,0 +1,259 @@
+import { OwnerShipMeta } from "./ownership.js";
+import { AnySchemaModel, ZodSchemaModel } from "@lssm/lib.schema";
+
+//#region src/forms.d.ts
+type PredicateOp = 'equals' | 'notEquals' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte' | 'truthy' | 'empty' | 'lengthGt' | 'lengthGte' | 'lengthLt' | 'lengthLte';
+interface WhenClause {
+  /** Dot path in form values; arrays may use `$index` within array context. */
+  path: string;
+  op?: PredicateOp;
+  value?: unknown;
+}
+interface Predicate {
+  when?: WhenClause;
+  all?: Predicate[];
+  any?: Predicate[];
+  not?: Predicate;
+}
+interface FormOption {
+  labelI18n: string;
+  value: string | number | boolean;
+  descriptionI18n?: string;
+  disabled?: boolean;
+}
+type OptionsSource = {
+  kind: 'static';
+  options: readonly FormOption[];
+} | {
+  kind: 'resolver';
+  resolverKey: string;
+  /** Dot paths in form values to watch */
+  deps: string[];
+  args?: Record<string, unknown>;
+};
+interface BaseFieldSpec {
+  /** Field kind discriminator. */
+  kind: 'text' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'switch' | 'group' | 'array';
+  /** Field name (dot path relative to the form root or parent context). */
+  name?: string;
+  labelI18n?: string;
+  descriptionI18n?: string;
+  placeholderI18n?: string;
+  required?: boolean;
+  /** Conditional UI behavior */
+  visibleWhen?: Predicate;
+  enabledWhen?: Predicate;
+  requiredWhen?: Predicate;
+  /** UI hints */
+  uiKey?: string;
+  uiProps?: Record<string, unknown>;
+  wrapper?: {
+    orientation?: 'horizontal' | 'vertical';
+  };
+  /** HTML/Native autofill token (supports custom tokens) */
+  autoComplete?: string;
+  /** Keyboard/adaptation hints (web/native). Shape mirrors design-system KeyboardOptions but stays decoupled. */
+  keyboard?: {
+    kind?: string;
+    autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters';
+    autoComplete?: string;
+    autoCorrect?: boolean;
+    enterKeyHint?: 'enter' | 'done' | 'go' | 'next' | 'search' | 'send';
+  };
+  /** Optional computed value hook, provided by host computations map */
+  computeFrom?: {
+    computeKey: string;
+    deps: string[];
+    mode?: 'change' | 'blur-xs' | 'submit';
+    readOnly?: boolean;
+  };
+}
+interface TextFieldSpec extends BaseFieldSpec {
+  kind: 'text';
+  name: string;
+  inputMode?: 'text' | 'email' | 'tel' | 'url' | 'numeric' | 'decimal' | 'search';
+  autoComplete?: string;
+  maxLength?: number;
+  minLength?: number;
+}
+interface TextareaFieldSpec extends BaseFieldSpec {
+  kind: 'textarea';
+  name: string;
+  rows?: number;
+  maxLength?: number;
+  minLength?: number;
+}
+interface SelectFieldSpec extends BaseFieldSpec {
+  kind: 'select';
+  name: string;
+  options: OptionsSource | readonly FormOption[];
+}
+interface CheckboxFieldSpec extends BaseFieldSpec {
+  kind: 'checkbox';
+  name: string;
+}
+interface RadioFieldSpec extends BaseFieldSpec {
+  kind: 'radio';
+  name: string;
+  options: OptionsSource | readonly FormOption[];
+}
+interface SwitchFieldSpec extends BaseFieldSpec {
+  kind: 'switch';
+  name: string;
+}
+interface GroupFieldSpec extends BaseFieldSpec {
+  kind: 'group';
+  /** Optional legend/label at group level */
+  labelI18n?: string;
+  fields: FieldSpec[];
+}
+interface ArrayFieldSpec extends BaseFieldSpec {
+  kind: 'array';
+  /** Root-level field that is an array in the model (e.g., "emails") */
+  name: string;
+  /** Child field spec for each item (e.g., address inside emails[i].address). */
+  of: Exclude<FieldSpec, ArrayFieldSpec | GroupFieldSpec>;
+  min?: number;
+  max?: number;
+}
+type FieldSpec = TextFieldSpec | TextareaFieldSpec | SelectFieldSpec | CheckboxFieldSpec | RadioFieldSpec | SwitchFieldSpec | GroupFieldSpec | ArrayFieldSpec;
+interface FormAction {
+  key: string;
+  labelI18n: string;
+  op?: {
+    name: string;
+    version: number;
+  };
+  success?: {
+    navigateTo?: string;
+    toastI18n?: string;
+  };
+}
+interface ConstraintDecl {
+  key: string;
+  messageI18n: string;
+  paths: string[];
+  args?: Record<string, unknown>;
+}
+type FormValuesFor<M extends AnySchemaModel> = ZodSchemaModel<M>;
+interface FormSpec<M extends AnySchemaModel = AnySchemaModel> {
+  meta: OwnerShipMeta & {
+    key: string;
+    version: number;
+  };
+  /** Canonical form data shape */
+  model: M;
+  /** Flat list or tree using groups/arrays */
+  fields: FieldSpec[];
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  actions?: FormAction[];
+  renderHints?: {
+    ui: 'shadcn' | 'custom';
+    form: 'react-hook-form';
+  };
+  constraints?: ConstraintDecl[];
+}
+declare class FormRegistry {
+  private items;
+  register(spec: FormSpec): this;
+  list(): FormSpec[];
+  get(key: string, version?: number): FormSpec<AnySchemaModel> | undefined;
+}
+declare function evalPredicate(values: unknown, pred?: Predicate): boolean;
+type ConstraintHandler = (values: Record<string, unknown>, paths: string[], args?: Record<string, unknown>) => {
+  ok: true;
+} | {
+  ok: false;
+  message?: string;
+  path?: string;
+};
+/**
+ * Wrap the base zod schema with relation-driven refinements (requiredWhen, array min/max)
+ * and optional custom constraints. Call this when wiring RHF resolver.
+ */
+declare function buildZodWithRelations(spec: FormSpec, handlers?: Record<string, ConstraintHandler>): any;
+interface AnyFieldLike {
+  kind: string;
+  name?: string;
+  fields?: readonly AnyFieldLike[];
+  of?: AnyFieldLike;
+}
+type TopLevelNames<F extends readonly AnyFieldLike[]> = F[number] extends {
+  name: infer N extends string;
+} ? N : never;
+type ArrayChildren<F extends readonly AnyFieldLike[]> = F[number] extends {
+  kind: 'array';
+  name: infer N extends string;
+  of: infer C;
+} ? C extends {
+  name: infer CN extends string;
+} ? `${N}.$index.${CN}` : never : never;
+type GroupTopLevelNames<F extends readonly AnyFieldLike[]> = F[number] extends {
+  kind: 'group';
+  fields: infer G extends readonly AnyFieldLike[];
+} ? TopLevelNames<G> : never;
+type GroupArrayChildren<F extends readonly AnyFieldLike[]> = F[number] extends {
+  kind: 'group';
+  fields: infer G extends readonly AnyFieldLike[];
+} ? ArrayChildren<G> : never;
+type PathOfFields<F extends readonly AnyFieldLike[]> = TopLevelNames<F> | ArrayChildren<F> | GroupTopLevelNames<F> | GroupArrayChildren<F>;
+interface TypedWhenClause<P extends string> {
+  path: P;
+  op?: PredicateOp;
+  value?: unknown;
+}
+interface TypedPredicate<P extends string> {
+  when?: TypedWhenClause<P>;
+  all?: TypedPredicate<P>[];
+  any?: TypedPredicate<P>[];
+  not?: TypedPredicate<P>;
+}
+type TypedOptionsSource<P extends string> = {
+  kind: 'static';
+  options: readonly FormOption[];
+} | {
+  kind: 'resolver';
+  resolverKey: string;
+  deps: P[];
+  args?: Record<string, unknown>;
+};
+type EnhanceFields<F extends readonly AnyFieldLike[], P extends string> = { [K in keyof F]: F[K] & {
+  visibleWhen?: TypedPredicate<P>;
+  enabledWhen?: TypedPredicate<P>;
+  requiredWhen?: TypedPredicate<P>;
+} & (F[K] extends {
+  kind: 'select';
+} ? {
+  options: TypedOptionsSource<P> | readonly FormOption[];
+} : {}) & (F[K] extends {
+  kind: 'radio';
+} ? {
+  options: TypedOptionsSource<P> | readonly FormOption[];
+} : {}) & {
+  computeFrom?: {
+    computeKey: string;
+    deps: P[];
+    mode?: 'change' | 'blur-xs' | 'submit';
+    readOnly?: boolean;
+  };
+} };
+declare function defineFormSpec<M extends AnySchemaModel, F extends readonly AnyFieldLike[]>(spec: {
+  meta: FormSpec<M>['meta'];
+  model: M;
+  fields: EnhanceFields<F, PathOfFields<F>>;
+  policy?: FormSpec<M>['policy'];
+  actions?: FormSpec<M>['actions'];
+  renderHints?: FormSpec<M>['renderHints'];
+  constraints?: {
+    key: string;
+    messageI18n: string;
+    paths: PathOfFields<F>[];
+    args?: Record<string, unknown>;
+  }[];
+}): FormSpec<M>;
+//#endregion
+export { ArrayFieldSpec, BaseFieldSpec, CheckboxFieldSpec, ConstraintDecl, ConstraintHandler, EnhanceFields, FieldSpec, FormAction, FormOption, FormRegistry, FormSpec, FormValuesFor, GroupFieldSpec, OptionsSource, Predicate, PredicateOp, RadioFieldSpec, SelectFieldSpec, SwitchFieldSpec, TextFieldSpec, TextareaFieldSpec, TypedOptionsSource, TypedPredicate, TypedWhenClause, WhenClause, buildZodWithRelations, defineFormSpec, evalPredicate };
+//# sourceMappingURL=forms.d.ts.map