@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/contract-registry/schemas.d.ts

@@ -0,0 +1,124 @@
+import { ContractRegistryItem, ContractRegistryManifest } from "./types.js";
+import z from "zod";
+
+//#region src/contract-registry/schemas.d.ts
+declare const ContractRegistryItemTypeSchema: z.ZodEnum<{
+  "contractspec:operation": "contractspec:operation";
+  "contractspec:event": "contractspec:event";
+  "contractspec:presentation": "contractspec:presentation";
+  "contractspec:form": "contractspec:form";
+  "contractspec:feature": "contractspec:feature";
+  "contractspec:workflow": "contractspec:workflow";
+  "contractspec:template": "contractspec:template";
+  "contractspec:integration": "contractspec:integration";
+  "contractspec:data-view": "contractspec:data-view";
+  "contractspec:migration": "contractspec:migration";
+  "contractspec:telemetry": "contractspec:telemetry";
+  "contractspec:experiment": "contractspec:experiment";
+  "contractspec:app-config": "contractspec:app-config";
+  "contractspec:knowledge": "contractspec:knowledge";
+}>;
+declare const ContractRegistryFileSchema: z.ZodObject<{
+  path: z.ZodString;
+  type: z.ZodString;
+  content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ContractRegistryItemSchema: z.ZodObject<{
+  key: z.ZodString;
+  type: z.ZodEnum<{
+    "contractspec:operation": "contractspec:operation";
+    "contractspec:event": "contractspec:event";
+    "contractspec:presentation": "contractspec:presentation";
+    "contractspec:form": "contractspec:form";
+    "contractspec:feature": "contractspec:feature";
+    "contractspec:workflow": "contractspec:workflow";
+    "contractspec:template": "contractspec:template";
+    "contractspec:integration": "contractspec:integration";
+    "contractspec:data-view": "contractspec:data-view";
+    "contractspec:migration": "contractspec:migration";
+    "contractspec:telemetry": "contractspec:telemetry";
+    "contractspec:experiment": "contractspec:experiment";
+    "contractspec:app-config": "contractspec:app-config";
+    "contractspec:knowledge": "contractspec:knowledge";
+  }>;
+  version: z.ZodString;
+  title: z.ZodString;
+  description: z.ZodString;
+  meta: z.ZodObject<{
+    stability: z.ZodEnum<{
+      deprecated: "deprecated";
+      idea: "idea";
+      in_creation: "in_creation";
+      experimental: "experimental";
+      beta: "beta";
+      stable: "stable";
+    }>;
+    owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>;
+  dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  registryDependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  files: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  schema: z.ZodOptional<z.ZodObject<{
+    input: z.ZodOptional<z.ZodUnknown>;
+    output: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const ContractRegistryManifestSchema: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodString>;
+  name: z.ZodString;
+  homepage: z.ZodOptional<z.ZodString>;
+  items: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodEnum<{
+      "contractspec:operation": "contractspec:operation";
+      "contractspec:event": "contractspec:event";
+      "contractspec:presentation": "contractspec:presentation";
+      "contractspec:form": "contractspec:form";
+      "contractspec:feature": "contractspec:feature";
+      "contractspec:workflow": "contractspec:workflow";
+      "contractspec:template": "contractspec:template";
+      "contractspec:integration": "contractspec:integration";
+      "contractspec:data-view": "contractspec:data-view";
+      "contractspec:migration": "contractspec:migration";
+      "contractspec:telemetry": "contractspec:telemetry";
+      "contractspec:experiment": "contractspec:experiment";
+      "contractspec:app-config": "contractspec:app-config";
+      "contractspec:knowledge": "contractspec:knowledge";
+    }>;
+    version: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    meta: z.ZodObject<{
+      stability: z.ZodEnum<{
+        deprecated: "deprecated";
+        idea: "idea";
+        in_creation: "in_creation";
+        experimental: "experimental";
+        beta: "beta";
+        stable: "stable";
+      }>;
+      owners: z.ZodDefault<z.ZodArray<z.ZodString>>;
+      tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    registryDependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    files: z.ZodArray<z.ZodObject<{
+      path: z.ZodString;
+      type: z.ZodString;
+      content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    schema: z.ZodOptional<z.ZodObject<{
+      input: z.ZodOptional<z.ZodUnknown>;
+      output: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ContractRegistryItemParsed = z.infer<typeof ContractRegistryItemSchema> & ContractRegistryItem;
+type ContractRegistryManifestParsed = z.infer<typeof ContractRegistryManifestSchema> & ContractRegistryManifest;
+//#endregion
+export { ContractRegistryFileSchema, ContractRegistryItemParsed, ContractRegistryItemSchema, ContractRegistryItemTypeSchema, ContractRegistryManifestParsed, ContractRegistryManifestSchema };

package/dist/contract-registry/schemas.js

@@ -0,0 +1,61 @@
+import { StabilityEnum } from "../ownership.js";
+import z from "zod";
+
+//#region src/contract-registry/schemas.ts
+const ContractRegistryItemTypeValues = [
+	"contractspec:operation",
+	"contractspec:event",
+	"contractspec:presentation",
+	"contractspec:form",
+	"contractspec:feature",
+	"contractspec:workflow",
+	"contractspec:template",
+	"contractspec:integration",
+	"contractspec:data-view",
+	"contractspec:migration",
+	"contractspec:telemetry",
+	"contractspec:experiment",
+	"contractspec:app-config",
+	"contractspec:knowledge"
+];
+const ContractRegistryItemTypeSchema = z.enum(ContractRegistryItemTypeValues);
+const ContractRegistryFileSchema = z.object({
+	path: z.string().min(1),
+	type: z.string().min(1),
+	content: z.string().optional()
+});
+const ContractRegistryItemSchema = z.object({
+	key: z.string().min(1),
+	type: ContractRegistryItemTypeSchema,
+	version: z.string(),
+	title: z.string().min(1),
+	description: z.string().min(1),
+	meta: z.object({
+		stability: z.enum([
+			StabilityEnum.Idea,
+			StabilityEnum.InCreation,
+			StabilityEnum.Experimental,
+			StabilityEnum.Beta,
+			StabilityEnum.Stable,
+			StabilityEnum.Deprecated
+		]),
+		owners: z.array(z.string().min(1)).default([]),
+		tags: z.array(z.string().min(1)).default([])
+	}),
+	dependencies: z.array(z.string().min(1)).optional(),
+	registryDependencies: z.array(z.string().min(1)).optional(),
+	files: z.array(ContractRegistryFileSchema).min(1),
+	schema: z.object({
+		input: z.unknown().optional(),
+		output: z.unknown().optional()
+	}).optional()
+});
+const ContractRegistryManifestSchema = z.object({
+	$schema: z.string().min(1).optional(),
+	name: z.string().min(1),
+	homepage: z.string().min(1).optional(),
+	items: z.array(ContractRegistryItemSchema)
+});
+
+//#endregion
+export { ContractRegistryFileSchema, ContractRegistryItemSchema, ContractRegistryItemTypeSchema, ContractRegistryManifestSchema };

package/dist/contract-registry/types.d.ts

@@ -0,0 +1,46 @@
+import { Owner, Stability, Tag } from "../ownership.js";
+
+//#region src/contract-registry/types.d.ts
+type ContractRegistryItemType = 'contractspec:operation' | 'contractspec:event' | 'contractspec:presentation' | 'contractspec:form' | 'contractspec:feature' | 'contractspec:workflow' | 'contractspec:template' | 'contractspec:integration' | 'contractspec:data-view' | 'contractspec:migration' | 'contractspec:telemetry' | 'contractspec:experiment' | 'contractspec:app-config' | 'contractspec:knowledge';
+type JsonSchema = unknown;
+interface ContractRegistryFile {
+  /** Path relative to the registry project root */
+  path: string;
+  /**
+   * File classification (kept open-ended to remain ejectable and compatible
+   * with multiple consumers).
+   *
+   * Examples: 'registry:component', 'contractspec:spec', 'registry:lib'
+   */
+  type: string;
+  /** Optional inline content (if serving without file hosting) */
+  content?: string;
+}
+interface ContractRegistryItem {
+  key: string;
+  type: ContractRegistryItemType;
+  version: string;
+  title: string;
+  description: string;
+  meta: {
+    stability: Stability;
+    owners: Owner[];
+    tags: Tag[];
+  };
+  dependencies?: string[];
+  registryDependencies?: string[];
+  files: ContractRegistryFile[];
+  schema?: {
+    input?: JsonSchema;
+    output?: JsonSchema;
+  };
+}
+interface ContractRegistryManifest {
+  /** Optional JSON-schema reference for tooling */
+  $schema?: string;
+  name: string;
+  homepage?: string;
+  items: ContractRegistryItem[];
+}
+//#endregion
+export { ContractRegistryFile, ContractRegistryItem, ContractRegistryItemType, ContractRegistryManifest, JsonSchema };

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

@@ -0,0 +1,5 @@
+import { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewSections, DataViewSource, DataViewStates, DataViewTableColumn, DataViewTableConfig } from "./types.js";
+import { DataViewRef, DataViewSpec, defineDataView } from "./spec.js";
+import { DataViewRegistry, dataViewKey } from "./registry.js";
+import "./index.js";
+export { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewRef, DataViewRegistry, DataViewSections, DataViewSource, DataViewSpec, DataViewStates, DataViewTableColumn, DataViewTableConfig, dataViewKey, defineDataView };

package/dist/data-views/data-views.js

@@ -0,0 +1,5 @@
+import { defineDataView } from "./spec.js";
+import { DataViewRegistry, dataViewKey } from "./registry.js";
+import "./index.js";
+
+export { DataViewRegistry, dataViewKey, defineDataView };

package/dist/data-views/docs/data-views.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/data-views/docs/data-views.docblock.d.ts
+declare const tech_contracts_data_views_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_data_views_DocBlocks };

package/dist/data-views/docs/data-views.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../docs/registry.js";
+
+//#region src/data-views/docs/data-views.docblock.ts
+const tech_contracts_data_views_DocBlocks = [{
+	id: "docs.tech.contracts.data-views",
+	title: "DataViewSpec Overview",
+	summary: "`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/data-views",
+	tags: [
+		"tech",
+		"contracts",
+		"data-views"
+	],
+	body: "# DataViewSpec Overview\n\n## Purpose\n\n`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, and filter records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.\n\n## Location\n\n- Type definitions and registry: `packages/libs/contracts/src/data-views.ts`\n- React renderers: `packages/libs/design-system/src/components/data-view`\n- CLI scaffolding: `contractspec create --type data-view`\n\n## Schema Highlights\n\n```ts\nexport interface DataViewSpec {\n  meta: DataViewMeta;       // ownership meta + { name, version, entity }\n  source: DataViewSource;   // contract operations and refresh events\n  view: DataViewConfig;     // union of list/detail/table/grid definitions\n  states?: DataViewStates;  // optional empty/error/loading presentations\n  policy?: { flags?: string[]; pii?: string[] };\n}\n```\n\n- **DataViewMeta**: `name`, `version`, `entity`, ownership metadata (title, description, domain, owners, tags, stability).\n- **DataViewSource**:\n  - `primary`: required query operation (`OpRef`) for fetching collections.\n  - `item`: optional detail query (recommended for `detail` views).\n  - `mutations`: optional create/update/delete operation refs.\n  - `refreshEvents`: events that should trigger refresh.\n- **DataViewConfig** (union):\n  - `list`: card/compact list, `primaryField`, `secondaryFields`.\n  - `table`: column configuration (`columns`, alignments, density).\n  - `detail`: sections of fields for record inspection.\n  - `grid`: multi-column grid (rendered as card list today).\n- **DataViewField**: `key`, `label`, `dataPath`, formatting hints (`format`), sort/filter toggles, optional presentation override.\n- **DataViewFilter**: describes filter inputs (search, enum, number, date, boolean).\n- **DataViewAction**: simple declarative actions (`navigation` or `operation`).\n\n## Registry Usage\n\n```ts\nimport { DataViewRegistry } from '@contractspec/lib.contracts/data-views';\nimport { ResidentsDataView } from './data-views/residents.data-view';\n\nconst registry = new DataViewRegistry();\nregistry.register(ResidentsDataView);\n\nconst listView = registry.get('residents.admin.list');\n```\n\nRegistries guard against duplicate `(name, version)` pairs and make latest-version lookup trivial.\n\n## Rendering\n\n```tsx\nimport { DataViewRenderer } from '@contractspec/lib.design-system';\nimport { ResidentsDataView } from '../contracts/data-views/residents.data-view';\n\nfunction ResidentsTable({ rows }: { rows: Record<string, unknown>[] }) {\n  return (\n    <DataViewRenderer\n      spec={ResidentsDataView}\n      items={rows}\n      onRowClick={(row) => console.log('Selected', row)}\n    />\n  );\n}\n```\n\nFor more control, use specific components:\n\n- `DataViewList` – friendly cards/rows\n- `DataViewTable` – tabular presentation with optional header/footers\n- `DataViewDetail` – two-column grouped layout for record inspection\n\nRenderers rely on the field definitions (`dataPath`, `format`) to extract values and render them consistently.\n\n## CLI Scaffolding\n\n```bash\n# Interactive wizard\ncontractspec create --type data-view\n\n# Generates packages/.../data-views/<name>.data-view.ts\n\n# Optional renderer scaffold\ncontractspec build path/to/<name>.data-view.ts\n# → produces <name>.renderer.tsx that wraps DataViewRenderer with sensible props\n```\n\nWizard prompts:\n- name (dot notation), version, entity\n- kind (`list`, `table`, `detail`, `grid`)\n- primary query operation (required) and optional item query\n- fields (label, data path, format, sorting/filtering)\n\n## Authoring Guidelines\n\n1. **Separation of data & presentation**: keep fetching logic inside contract operations; DataViewSpec only references them via `source`.\n2. **Versioning**: bump `meta.version` when field membership, ordering, or semantics change.\n3. **Consistency**: reuse common field keys across modules to enable shared renderers and filters.\n4. **States**: reference `PresentationRef` for empty/error/loader states to ensure consistent UX.\n5. **Actions**: prefer referencing contract operations instead of embedding business logic in the UI.\n\n## Roadmap\n\n- Derived filters from `fields.filterable` (auto-generated UI).\n- Table density presets per platform.\n- Bridge to PolicySpec for field-level visibility (Phase 2 policy expansion).\n- Automated docs/LLM sync via CLI.\n\n"
+}];
+registerDocBlocks(tech_contracts_data_views_DocBlocks);
+
+//#endregion
+export { tech_contracts_data_views_DocBlocks };

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

@@ -0,0 +1,4 @@
+import { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewSections, DataViewSource, DataViewStates, DataViewTableColumn, DataViewTableConfig } from "./types.js";
+import { DataViewRef, DataViewSpec, defineDataView } from "./spec.js";
+import { DataViewRegistry, dataViewKey } from "./registry.js";
+export { type DataViewAction, type DataViewBaseConfig, type DataViewConfig, type DataViewDetailConfig, type DataViewField, type DataViewFieldFormat, type DataViewFilter, type DataViewGridConfig, type DataViewKind, type DataViewListConfig, type DataViewMeta, type DataViewRef, DataViewRegistry, type DataViewSections, type DataViewSource, type DataViewSpec, type DataViewStates, type DataViewTableColumn, type DataViewTableConfig, dataViewKey, defineDataView };

package/dist/data-views/index.js

@@ -0,0 +1,4 @@
+import { defineDataView } from "./spec.js";
+import { DataViewRegistry, dataViewKey } from "./registry.js";
+
+export { DataViewRegistry, dataViewKey, defineDataView };

package/dist/data-views/query-generator.d.ts

@@ -0,0 +1,40 @@
+import { DataViewSpec } from "./spec.js";
+import "./index.js";
+
+//#region src/data-views/query-generator.d.ts
+interface DataViewQueryParams {
+  filters?: Record<string, unknown>;
+  sort?: {
+    field: string;
+    direction: 'asc' | 'desc';
+  };
+  pagination?: {
+    page: number;
+    pageSize: number;
+  };
+  search?: string;
+}
+interface DataViewQuery {
+  operationName: string;
+  input: Record<string, unknown>;
+  meta: {
+    pagination: {
+      page: number;
+      pageSize: number;
+      skip: number;
+      take: number;
+    };
+    sorting?: {
+      field: string;
+      direction: 'asc' | 'desc';
+    };
+  };
+}
+declare class DataViewQueryGenerator {
+  private spec;
+  constructor(spec: DataViewSpec);
+  generate(params: DataViewQueryParams): DataViewQuery;
+  validateParams(params: DataViewQueryParams): string[];
+}
+//#endregion
+export { DataViewQuery, DataViewQueryGenerator, DataViewQueryParams };

package/dist/data-views/query-generator.js

@@ -0,0 +1,48 @@
+//#region src/data-views/query-generator.ts
+var DataViewQueryGenerator = class {
+	constructor(spec) {
+		this.spec = spec;
+	}
+	generate(params) {
+		const { primary } = this.spec.source;
+		const page = params.pagination?.page ?? 1;
+		const pageSize = params.pagination?.pageSize ?? 20;
+		const skip = (page - 1) * pageSize;
+		const take = pageSize;
+		const input = {
+			skip,
+			take,
+			...params.filters
+		};
+		if (params.search) input.search = params.search;
+		if (params.sort) input.orderBy = { [params.sort.field]: params.sort.direction };
+		return {
+			operationName: primary.key,
+			input,
+			meta: {
+				pagination: {
+					page,
+					pageSize,
+					skip,
+					take
+				},
+				sorting: params.sort
+			}
+		};
+	}
+	validateParams(params) {
+		const errors = [];
+		if (params.filters && this.spec.view.filters) {
+			for (const key of Object.keys(params.filters)) if (!this.spec.view.filters.find((f) => f.key === key)) errors.push(`Unknown filter key: ${key}`);
+		}
+		if (params.sort) {
+			const field = this.spec.view.fields.find((f) => f.key === params.sort?.field);
+			if (!field) errors.push(`Unknown sort field: ${params.sort.field}`);
+			else if (field.sortable === false) errors.push(`Field is not sortable: ${params.sort.field}`);
+		}
+		return errors;
+	}
+};
+
+//#endregion
+export { DataViewQueryGenerator };

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

@@ -0,0 +1,17 @@
+import { DataViewSpec } from "./spec.js";
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/data-views/registry.d.ts
+
+/**
+ * Generate a unique key for a data view spec.
+ */
+declare function dataViewKey(spec: DataViewSpec): string;
+/**
+ * Registry for managing data view specifications.
+ */
+declare class DataViewRegistry extends SpecContractRegistry<'data-view', DataViewSpec> {
+  constructor(items?: DataViewSpec[]);
+}
+//#endregion
+export { DataViewRegistry, dataViewKey };

package/dist/data-views/registry.js

@@ -0,0 +1,20 @@
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/data-views/registry.ts
+/**
+* Generate a unique key for a data view spec.
+*/
+function dataViewKey(spec) {
+	return `${spec.meta.key}.v${spec.meta.version}`;
+}
+/**
+* Registry for managing data view specifications.
+*/
+var DataViewRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("data-view", items);
+	}
+};
+
+//#endregion
+export { DataViewRegistry, dataViewKey };

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

@@ -0,0 +1,32 @@
+import { OperationSpecRegistry } from "../operations/registry.js";
+import "../operations/index.js";
+import { DataViewSpec } from "./spec.js";
+import { DataViewRegistry } from "./registry.js";
+import "./index.js";
+import { HandlerCtx } from "../types.js";
+
+//#region src/data-views/runtime.d.ts
+interface DataViewRuntimeConfig {
+  registry: DataViewRegistry;
+  operationRegistry: OperationSpecRegistry;
+}
+interface DataViewResult<T = unknown> {
+  data: T[];
+  total: number;
+  loading: boolean;
+  error?: Error;
+}
+declare class DataViewRuntime {
+  private config;
+  private cache;
+  private subscriptions;
+  constructor(config: DataViewRuntimeConfig);
+  register(spec: DataViewSpec): void;
+  getSpec(name: string, version?: string): DataViewSpec | undefined;
+  executeQuery(specName: string, params: unknown, ctx: HandlerCtx): Promise<DataViewResult>;
+  invalidate(specName: string): void;
+  subscribe(specName: string, callback: () => void): () => void;
+  private notifySubscribers;
+}
+//#endregion
+export { DataViewResult, DataViewRuntime, DataViewRuntimeConfig };

package/dist/data-views/runtime.js

@@ -0,0 +1,68 @@
+import "../operations/index.js";
+import "./index.js";
+
+//#region src/data-views/runtime.ts
+function isPaginatedResult(value) {
+	return typeof value === "object" && value !== null && "items" in value && Array.isArray(value.items);
+}
+var DataViewRuntime = class {
+	cache = /* @__PURE__ */ new Map();
+	subscriptions = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.config = config;
+	}
+	register(spec) {
+		this.config.registry.register(spec);
+	}
+	getSpec(name, version) {
+		return this.config.registry.get(name, version);
+	}
+	async executeQuery(specName, params, ctx) {
+		const spec = this.getSpec(specName);
+		if (!spec) throw new Error(`DataView spec not found: ${specName}`);
+		const opRef = spec.source.primary;
+		if (!opRef) throw new Error(`DataView spec ${specName} missing primary source`);
+		try {
+			const result = await this.config.operationRegistry.execute(opRef.key, opRef.version, params, ctx);
+			if (Array.isArray(result)) return {
+				data: result,
+				total: result.length,
+				loading: false
+			};
+			if (isPaginatedResult(result)) return {
+				data: result.items,
+				total: result.total ?? result.items.length,
+				loading: false
+			};
+			return {
+				data: [result],
+				total: 1,
+				loading: false
+			};
+		} catch (error) {
+			return {
+				data: [],
+				total: 0,
+				loading: false,
+				error: error instanceof Error ? error : new Error(String(error))
+			};
+		}
+	}
+	invalidate(specName) {
+		this.cache.delete(specName);
+		this.notifySubscribers(specName);
+	}
+	subscribe(specName, callback) {
+		if (!this.subscriptions.has(specName)) this.subscriptions.set(specName, /* @__PURE__ */ new Set());
+		this.subscriptions.get(specName)?.add(callback);
+		return () => {
+			this.subscriptions.get(specName)?.delete(callback);
+		};
+	}
+	notifySubscribers(specName) {
+		this.subscriptions.get(specName)?.forEach((cb) => cb());
+	}
+};
+
+//#endregion
+export { DataViewRuntime };

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

@@ -0,0 +1,32 @@
+import { ExperimentRef } from "../experiments/spec.js";
+import { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from "./types.js";
+
+//#region src/data-views/spec.d.ts
+
+/**
+ * Complete specification for a data view.
+ */
+interface DataViewSpec {
+  meta: DataViewMeta;
+  source: DataViewSource;
+  view: DataViewConfig;
+  states?: DataViewStates;
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  experiments?: ExperimentRef[];
+}
+/**
+ * Reference to a data view spec.
+ */
+interface DataViewRef {
+  key: string;
+  version: string;
+}
+/**
+ * Helper to define a data view spec with type safety.
+ */
+declare function defineDataView(spec: DataViewSpec): DataViewSpec;
+//#endregion
+export { DataViewRef, DataViewSpec, defineDataView };

package/dist/data-views/spec.js

@@ -0,0 +1,10 @@
+//#region src/data-views/spec.ts
+/**
+* Helper to define a data view spec with type safety.
+*/
+function defineDataView(spec) {
+	return spec;
+}
+
+//#endregion
+export { defineDataView };