@lssm/lib.contracts 1.2.0

package/dist/data-views.d.ts

@@ -0,0 +1,132 @@
+import { OwnerShipMeta } from "./ownership.js";
+import { ExperimentRef } from "./experiments/spec.js";
+import { EventRef, OpRef, PresentationRef } from "./features.js";
+
+//#region src/data-views.d.ts
+type DataViewKind = 'list' | 'detail' | 'table' | 'grid';
+interface DataViewMeta extends OwnerShipMeta {
+  /** Fully-qualified data view name (e.g., "sigil.spaces.admin_list"). */
+  name: string;
+  /** Version of this data view. Increment on breaking changes. */
+  version: number;
+  /** Canonical entity slug (e.g., "space", "resident"). */
+  entity: string;
+}
+interface DataViewSource {
+  /** Primary query used to fetch items for this view. */
+  primary: OpRef;
+  /** Optional operation used to fetch a single item (detail views). */
+  item?: OpRef;
+  /** Optional record mutation operations (used for inline editing or actions). */
+  mutations?: {
+    create?: OpRef;
+    update?: OpRef;
+    delete?: OpRef;
+  };
+  /** Events that should trigger refresh when emitted. */
+  refreshEvents?: EventRef[];
+}
+type DataViewFieldFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'dateTime' | 'boolean' | 'badge';
+interface DataViewField {
+  /** Unique identifier for the field within the view. */
+  key: string;
+  /** Human-friendly label for headers/tooltips. */
+  label: string;
+  /** Dot-path into the data item (e.g., "address.city"). */
+  dataPath: string;
+  /** Optional description surfaced in tooltips or docs. */
+  description?: string;
+  /** Optional formatting hint for renderers. */
+  format?: DataViewFieldFormat;
+  /** When true, the field can be used for sorting. */
+  sortable?: boolean;
+  /** When true, the field can be used for filtering. */
+  filterable?: boolean;
+  /** Optional width hint for table layouts. */
+  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+  /** Optional presentation override (e.g., card component). */
+  presentation?: PresentationRef;
+}
+interface DataViewFilter {
+  key: string;
+  label: string;
+  field: string;
+  type: 'search' | 'enum' | 'number' | 'date' | 'boolean';
+  options?: {
+    value: string;
+    label: string;
+  }[];
+}
+interface DataViewAction {
+  key: string;
+  label: string;
+  kind: 'navigation' | 'operation';
+  /** Operation invoked when kind === 'operation'. */
+  operation?: OpRef;
+  /** Optional feature flag gating the action. */
+  requiresFlag?: string;
+}
+interface DataViewSections {
+  title?: string;
+  description?: string;
+  fields: string[];
+}
+interface DataViewBaseConfig {
+  kind: DataViewKind;
+  fields: DataViewField[];
+  primaryField?: string;
+  secondaryFields?: string[];
+  filters?: DataViewFilter[];
+  actions?: DataViewAction[];
+}
+interface DataViewListConfig extends DataViewBaseConfig {
+  kind: 'list';
+  layout?: 'card' | 'compact';
+}
+interface DataViewDetailConfig extends DataViewBaseConfig {
+  kind: 'detail';
+  sections?: DataViewSections[];
+}
+interface DataViewTableColumn {
+  field: string;
+  label?: string;
+  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+  align?: 'left' | 'center' | 'right';
+}
+interface DataViewTableConfig extends DataViewBaseConfig {
+  kind: 'table';
+  columns?: DataViewTableColumn[];
+  rowSelectable?: boolean;
+  density?: 'comfortable' | 'compact';
+}
+interface DataViewGridConfig extends DataViewBaseConfig {
+  kind: 'grid';
+  columns?: number;
+}
+type DataViewConfig = DataViewListConfig | DataViewDetailConfig | DataViewTableConfig | DataViewGridConfig;
+interface DataViewStates {
+  empty?: PresentationRef;
+  error?: PresentationRef;
+  loading?: PresentationRef;
+}
+interface DataViewSpec {
+  meta: DataViewMeta;
+  source: DataViewSource;
+  view: DataViewConfig;
+  states?: DataViewStates;
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  experiments?: ExperimentRef[];
+}
+declare class DataViewRegistry {
+  private readonly items;
+  register(spec: DataViewSpec): this;
+  list(): DataViewSpec[];
+  get(name: string, version?: number): DataViewSpec | undefined;
+}
+declare function dataViewKey(spec: DataViewSpec): string;
+//#endregion
+export { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewRegistry, DataViewSections, DataViewSource, DataViewSpec, DataViewStates, DataViewTableColumn, DataViewTableConfig, dataViewKey };
+//# sourceMappingURL=data-views.d.ts.map

package/dist/data-views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-views.d.ts","names":[],"sources":["../src/data-views.ts"],"sourcesContent":[],"mappings":";;;;;KAIY,YAAA;UAEK,YAAA,SAAqB;EAF1B;EAEK,IAAA,EAAA,MAAA;EASA;EAEN,OAAA,EAAA,MAAA;EAEF;EAGI,MAAA,EAAA,MAAA;;AAEA,UATI,cAAA,CASJ;EAGK;EAAQ,OAAA,EAVf,KAUe;EAGd;EAUK,IAAA,CAAA,EArBR,KAqBQ;EAqBA;EAQA,SAAA,CAAA,EAAA;IAUA,MAAA,CAAA,EAzDJ,KAyDI;IAMA,MAAA,CAAA,EA9DJ,KA8DI;IACT,MAAA,CAAA,EA9DK,KA8DL;EACE,CAAA;EAGE;EACA,aAAA,CAAA,EAhEM,QAgEN,EAAA;;AAGK,KAhEL,mBAAA,GAgEwB,MAAQ,GAAA,QAAA,GAAA,UAAkB,GAAA,YAAA,GAAA,MAAA,GAAA,UAAA,GAAA,SAAA,GAAA,OAAA;AAK7C,UA3DA,aAAA,CA2DqB;EAKrB;EAOA,GAAA,EAAA,MAAA;EAOA;EAKL,KAAA,EAAA,MAAA;EACR;EACA,QAAA,EAAA,MAAA;EACA;EACA,WAAA,CAAA,EAAA,MAAA;EAAkB;EAEL,MAAA,CAAA,EA/EN,mBA+EoB;EACrB;EACA,QAAA,CAAA,EAAA,OAAA;EACE;EAAe,UAAA,CAAA,EAAA,OAAA;EAGV;EACT,KAAA,CAAA,EAAA,MAAA,GAAA,IAAA,GAAA,IAAA,GAAA,IAAA,GAAA,IAAA;EACE;EACF,YAAA,CAAA,EAhFS,eAgFT;;AAGQ,UAhFC,cAAA,CAgFD;EAAa,GAAA,EAAA,MAAA;EAOhB,KAAA,EAAA,MAAA;EAGI,KAAA,EAAA,MAAA;EAOP,IAAA,EAAA,QAAA,GAAA,MAAA,GAAA,QAAA,GAAA,MAAA,GAAA,SAAA;EAI6B,OAAA,CAAA,EAAA;IAAY,KAAA,EAAA,MAAA;IAenC,KAAA,EAAA,MAAW;;;UA5GV,cAAA;;;;;cAKH;;;;UAKG,gBAAA;;;;;UAMA,kBAAA;QACT;UACE;;;YAGE;YACA;;UAGK,kBAAA,SAA2B;;;;UAK3B,oBAAA,SAA6B;;aAEjC;;UAGI,mBAAA;;;;;;UAOA,mBAAA,SAA4B;;YAEjC;;;;UAKK,kBAAA,SAA2B;;;;KAKhC,cAAA,GACR,qBACA,uBACA,sBACA;UAEa,cAAA;UACP;UACA;YACE;;UAGK,YAAA;QACT;UACE;QACF;WACG;;;;;gBAEK;;cAOH,gBAAA;;iBAGI;UAOP;uCAI6B;;iBAevB,WAAA,OAAkB"}

package/dist/data-views.js

@@ -0,0 +1,2 @@
+function e(e){return`${e.meta.name}.v${e.meta.version}`}var t=class{items=new Map;register(t){let n=e(t);if(this.items.has(n))throw Error(`Duplicate data view ${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 DataViewRegistry,n as dataViewKey};
+//# sourceMappingURL=data-views.js.map

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,44 @@
+import { OwnerShipMeta } from "./ownership.js";
+
+//#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;;;AAYc,UAZG,SAYH,CAAA,UAZuB,cAYvB,CAAA,CAAA;EAAa;EAIX,IAAA,EAAA,MAAA;EAAsB;EACvB,OAAA,EAAA,MAAA;EAAV;EACQ,WAAA,CAAA,EAAA,MAAA;EAAV;EAAS,GAAA,CAAA,EAAA,MAAA,EAAA;EAIK;EAeL,OAAA,EA3BD,CA2BC;EAEC;cA3BC;;;iBAIE,sBAAsB,mBACjC,UAAU,KACZ,UAAU;UAII;;;;;;;;;;;;WAYN;;KAGC,QAAA;;cAEC,6CAA4C"}

package/dist/events.js

@@ -0,0 +1,2 @@
+import"./schema/src/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":"8BAuBA,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"}