@lssm/lib.contracts-spec 17.3.2

package/dist/data-views/index.js

@@ -0,0 +1 @@
+export{ANNOTATION_DEFAULT_COLOR,ANNOTATION_DELETE_CONFLICT_WINDOW_MS,ANNOTATION_EDIT_WINDOW_MS,ANNOTATION_SOFT_DELETE_TTL_MS,annotationDoc}from"./annotation.js";export{resolveDataViewEditForm}from"./edit-form-resolution.js";export{filterSetToClauses,pruneDataViewFilterClauses,resolveDataViewFilters,sanitizeDataViewFilterSet}from"./filter-scope.js";export{graphExportDoc}from"./graph-export.js";export{decodeFilterFromUrl,encodeFilterToUrl,graphFilterCodecDoc}from"./graph-filter-codec.js";export{graphFilterSpecDoc}from"./graph-filter-spec.js";export{graphSubscriptionDoc,graphSubscriptionEventDoc,isGraphSubscriptionEvent}from"./graph-subscription.js";export{isSyncLayout,layoutSpecDoc}from"./layout-spec.js";export{DataViewRegistry,dataViewKey}from"./registry.js";export{deserializeSavedView,isValidSavedView,MAX_ZOOM,MIN_ZOOM,SAVED_VIEW_PARAM,savedViewDoc,serializeSavedView}from"./saved-view.js";export{defineDataView}from"./spec.js";export{storySlideDoc}from"./story-slide.js";

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

@@ -0,0 +1,140 @@
+/** Flow direction for hierarchical, dag, tree, and swimlane layouts. */
+export type LayoutDirection = 'TB' | 'BT' | 'LR' | 'RL';
+/** Fields shared across all LayoutSpec variants. */
+export interface BaseLayoutConfig {
+    /** Node alignment within its rank/slot. Default: `'center'`. */
+    readonly align?: 'start' | 'center' | 'end';
+    /** Outer padding in pixels around the laid-out bounding box. Default: `16`. */
+    readonly padding?: number;
+    /** Primary flow direction. Ignored by force/radial/time-axis. Default: `'TB'`. */
+    readonly direction?: LayoutDirection;
+}
+/** A single named lane in a SwimlaneLayoutSpec. */
+export interface Lane {
+    /** Unique lane id — must match a value in node metadata. */
+    readonly id: string;
+    /** Display label for the lane header. Defaults to `id`. */
+    readonly label?: string;
+    /** Minimum pixel size (width or height) reserved for this lane. */
+    readonly minSize?: number;
+}
+/**
+ * Force-directed layout (d3-force). Best for exploratory relationship graphs.
+ * Engine: d3-force chunk (web ≤20 KB gz); d3-force eager (native).
+ */
+export interface ForceLayoutSpec extends BaseLayoutConfig {
+    readonly kind: 'force';
+    /** Node repulsion strength (negative = push apart). Default: `-100`. */
+    readonly strength?: number;
+    /** Simulation cooling rate per tick [0, 1]. Default: `0.0228`. */
+    readonly alphaDecay?: number;
+    /** Collision avoidance radius per node in pixels. Default: `20`. */
+    readonly collisionRadius?: number;
+    /** Desired edge length in pixels. Default: `80`. */
+    readonly linkDistance?: number;
+    /** Ticks to run before the static position snapshot. Default: `300`. */
+    readonly iterations?: number;
+}
+/**
+ * DAG hierarchical layout (elkjs LAYERED / Sugiyama). Best for workflows.
+ * Engine: elkjs chunk (web ≤250 KB gz); dagre eager (native).
+ */
+export interface DagLayoutSpec extends BaseLayoutConfig {
+    readonly kind: 'dag';
+    /** Centre-to-centre distance between rank layers in pixels. Default: `100`. */
+    readonly rankSep?: number;
+    /** Centre-to-centre distance between sibling nodes in pixels. Default: `60`. */
+    readonly nodeSep?: number;
+}
+/**
+ * Radial (concentric ring) layout (d3-hierarchy). Best for ego-networks.
+ * Engine: d3-hierarchy chunk (web ≤15 KB gz); d3-hierarchy eager (native).
+ */
+export interface RadialLayoutSpec extends BaseLayoutConfig {
+    readonly kind: 'radial';
+    /** Innermost ring radius in pixels. Default: `80`. */
+    readonly innerRadius?: number;
+    /** Outermost ring radius in pixels. Default: computed from innerRadius + depth × 80. */
+    readonly outerRadius?: number;
+    /** Angular sweep in radians (2π = full circle). Default: `2π`. */
+    readonly angularRange?: number;
+}
+/**
+ * Tidy tree layout (d3-hierarchy Reingold–Tilford). Best for strict hierarchies.
+ * Engine: d3-hierarchy chunk (web ≤15 KB gz); d3-hierarchy eager (native).
+ */
+export interface TreeLayoutSpec extends BaseLayoutConfig {
+    readonly kind: 'tree';
+    /** Sibling node spacing in pixels. Default: `40`. */
+    readonly nodeSep?: number;
+    /** Parent-to-child level spacing in pixels. Default: `80`. */
+    readonly levelSep?: number;
+    /**
+     * Tree orientation. Overrides `BaseLayoutConfig.direction`.
+     * Default: `'vertical'` (root at top).
+     */
+    readonly orientation?: 'horizontal' | 'vertical';
+}
+/**
+ * Swimlane layout (elkjs BOX). Best for workflow stages and Kanban views.
+ * Engine: elkjs chunk (web ≤250 KB gz); dag fallback on native.
+ */
+export interface SwimlaneLayoutSpec extends BaseLayoutConfig {
+    readonly kind: 'swimlane';
+    /** REQUIRED — node metadata key whose value determines lane assignment. */
+    readonly laneBy: string;
+    /** Explicit lane order + labels. Unlisted lanes appended alphabetically. */
+    readonly lanes?: readonly Lane[];
+    /** Lane stacking axis. Default: `'horizontal'` (lanes top-to-bottom). */
+    readonly laneDirection?: 'horizontal' | 'vertical';
+    /** Pixel padding inside each lane. Default: `20`. */
+    readonly lanePadding?: number;
+    /** Pixel size of the lane header bar / column. Default: `32`. */
+    readonly laneHeaderSize?: number;
+}
+/**
+ * Time-axis layout (pure TypeScript). Best for event timelines and audit trails.
+ * Engine: base bundle — synchronous, zero async cost on all platforms.
+ */
+export interface TimeAxisLayoutSpec extends BaseLayoutConfig {
+    readonly kind: 'time-axis';
+    /** REQUIRED — node metadata key holding an epoch-ms number or ISO-8601 string. */
+    readonly xField: string;
+    /** Time scale. Default: `'time'` (calendar-aware). */
+    readonly scale?: 'linear' | 'log' | 'time';
+    /** Extra ms added to each side of the [min, max] domain. Default: `0`. */
+    readonly domainPadding?: number;
+    /** Optional metadata key for multi-lane rows (e.g. `'author'`). */
+    readonly laneBy?: string;
+    /** Pixel height of each lane row. Default: `80`. */
+    readonly laneHeight?: number;
+    /** When true, out-of-range nodes are excluded from layout output. Default: `false`. */
+    readonly clampToViewport?: boolean;
+}
+/** M3 layout specification — discriminated union over all supported algorithms. */
+export type LayoutSpec = ForceLayoutSpec | DagLayoutSpec | RadialLayoutSpec | TreeLayoutSpec | SwimlaneLayoutSpec | TimeAxisLayoutSpec;
+/** Discriminant string union for LayoutSpec. */
+export type LayoutKind = LayoutSpec['kind'];
+/**
+ * Layout kinds that trigger a dynamic chunk fetch on web first use.
+ * Budgets (gzipped): dag/swimlane → elkjs ≤250 KB; force → d3-force ≤20 KB;
+ * radial/tree → d3-hierarchy ≤15 KB.
+ */
+export type LazyLayoutKind = 'force' | 'dag' | 'radial' | 'tree' | 'swimlane';
+/** Layout kinds that run synchronously from the base bundle (no async chunk). */
+export type SyncLayoutKind = 'time-axis';
+/**
+ * Returns `true` if the spec uses the synchronous base-bundle path.
+ * No async chunk will be loaded for this layout kind.
+ */
+export declare function isSyncLayout(spec: LayoutSpec): spec is TimeAxisLayoutSpec;
+export declare const layoutSpecDoc: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};

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

@@ -0,0 +1,2 @@
+export function isSyncLayout(e){return e.kind==="time-axis"}export const layoutSpecDoc={id:"docs.contracts-spec.data-views.layout-spec",title:"LayoutSpec \u2014 M3 layout discriminated union",summary:"Six-variant discriminated union replacing M2 GraphLayoutKind. Variants: force, dag, radial, tree, swimlane, time-axis.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/layout-spec",tags:["graph","layout","spec","m3","elkjs","d3","discriminated-union"],body:["# LayoutSpec","","Discriminated union replacing `GraphLayoutKind` from M2.","","| kind | Key config | Engine (web / native) | Async chunk |","| --- | --- | --- | --- |","| `force` | strength, alphaDecay, collisionRadius | d3-force | d3-force.chunk \u226420 KB gz |","| `dag` | rankSep, nodeSep, direction | elkjs LAYERED / dagre | elkjs-layout-engine.chunk \u2264250 KB gz |","| `radial` | innerRadius, outerRadius, angularRange | d3-hierarchy | d3-hierarchy.chunk \u226415 KB gz |","| `tree` | nodeSep, levelSep, orientation | d3-hierarchy tidy | d3-hierarchy.chunk \u226415 KB gz |","| `swimlane` | laneBy (req), lanes | elkjs BOX / dag fallback | elkjs-layout-engine.chunk \u2264250 KB gz |","| `time-axis` | xField (req), scale | pure TS | base bundle (sync) |","","## Migration from M2","","```ts","import { layoutKindToSpec } from '@lssm/lib.contracts-spec/data-views/layout-spec';","layoutKindToSpec('dag') // \u2192 { kind: 'dag' }","```","","Remove `layoutKindToSpec` shim in P10 alongside `GraphLayoutKind` removal."].join(`
+`)};

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

@@ -0,0 +1,67 @@
+import type { DataViewDatabaseBinding, DataViewFilterClause, DataViewSpec } from '../data-views/index.js';
+import type { QueryEnvelope, QueryPagination } from '../query/index.js';
+export interface DataViewQueryParams {
+    filters?: Record<string, unknown>;
+    sort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    } | {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+    pagination?: {
+        mode?: 'offset' | 'cursor';
+        page?: number;
+        pageSize?: number;
+        cursor?: string;
+        limit?: number;
+        direction?: 'forward' | 'backward';
+    };
+    search?: string;
+    cache?: QueryEnvelope['cache'];
+}
+export interface DataViewQuery {
+    operationName: string;
+    input: Record<string, unknown>;
+    meta: {
+        pagination: QueryPagination;
+        canonical: QueryEnvelope;
+        sorting?: {
+            field: string;
+            direction: 'asc' | 'desc';
+        };
+        database?: DataViewDatabaseQueryDescriptor;
+    };
+}
+export interface DataViewDatabaseQueryDescriptor {
+    operationRef: {
+        key: 'database.query.readonly';
+        version: '2.0.0';
+    };
+    sourceKey: string;
+    resource: DataViewDatabaseBinding['resource'];
+    select: DataViewDatabaseBinding['fields'];
+    filters: DataViewFilterClause[];
+    sort: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+    pagination: {
+        mode?: 'offset';
+        skip: number;
+        take: number;
+    } | {
+        mode: 'cursor';
+        cursor?: string;
+        limit: number;
+        direction?: 'forward' | 'backward';
+    };
+    policyRefs?: DataViewDatabaseBinding['policyRefs'];
+    provenance?: DataViewDatabaseBinding['provenance'];
+}
+export declare class DataViewQueryGenerator {
+    private spec;
+    constructor(spec: DataViewSpec);
+    generate(params: DataViewQueryParams): DataViewQuery;
+    validateParams(params: DataViewQueryParams): string[];
+}

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

@@ -0,0 +1 @@
+export class DataViewQueryGenerator{spec;constructor(e){this.spec=e}generate(e){const{primary:r}=this.spec.source,t=e.pagination?.mode==="cursor"?"cursor":"offset",i=Math.max(1,e.pagination?.page??1),n=e.pagination?.pageSize??e.pagination?.limit??k(this.spec.view)??20,s=(i-1)*n,c=n,o=Array.isArray(e.sort)?e.sort:e.sort?[e.sort]:[],a=t==="cursor"?{mode:"cursor",cursor:e.pagination?.cursor,limit:c,direction:e.pagination?.direction??"forward"}:{mode:"offset",offset:s,limit:c,page:i,pageSize:n},d=a.mode==="cursor"?{skip:s,take:c,cursor:a.cursor,limit:a.limit,...e.filters}:{skip:s,take:c,...e.filters};if(e.search)d.search=e.search;if(o.length)d.orderBy=Object.fromEntries(o.map((u)=>[u.field,u.direction]));const l={operation:{key:r.key,version:r.version},search:e.search?.trim()||void 0,filters:Object.entries(e.filters??{}).map(([u,y])=>({field:u,operator:"eq",value:b(y)})),sort:o,pagination:a,cache:e.cache};return{operationName:r.key,input:d,meta:{pagination:a,canonical:l,sorting:o[0],database:p(this.spec.source.database,e,a)}}}validateParams(e){const r=[];if(e.filters&&this.spec.view.filters)for(const i of Object.keys(e.filters)){const n=this.spec.view.filters.find((c)=>c.key===i);if(!n){r.push(`Unknown filter key: ${i}`);continue}const s=m(n,e.filters[i]);if(s)r.push(s)}const t=Array.isArray(e.sort)?e.sort:e.sort?[e.sort]:[];for(const i of t){const n=this.spec.view.fields.find((s)=>s.key===i.field);if(!n)r.push(`Unknown sort field: ${i.field}`);else if(n.sortable===!1)r.push(`Field is not sortable: ${i.field}`)}return r}}function p(e,r,t){if(!e)return;const i=[...e.defaultFilters??[],...Object.entries(r.filters??{}).flatMap(([o,a])=>a===void 0?[]:[{filterKey:o,field:o,operator:"eq",value:w(a)}])],n=Array.isArray(r.sort)?r.sort:r.sort?[r.sort]:void 0,s=n?n:(e.defaultSort??[]).map((o)=>({field:o.field,direction:o.direction})),c=g(s,e);return{operationRef:{key:"database.query.readonly",version:"2.0.0"},sourceKey:e.sourceKey,resource:e.resource,select:e.fields.filter((o)=>o.select!==!1),filters:i,sort:t.mode==="cursor"?c:s,pagination:t.mode==="cursor"?{mode:"cursor",cursor:t.cursor,limit:t.limit,direction:t.direction??"forward"}:{mode:"offset",skip:t.offset,take:t.limit},policyRefs:e.policyRefs,provenance:e.provenance}}function g(e,r){if(r.pagination?.mode!=="cursor")return e;const t=[...e],i=r.pagination.cursorField;if(i&&!t.some((n)=>n.field===i))t.push({field:i,direction:"asc"});return t}function w(e){if(f(e))return e;if(typeof e==="string"||typeof e==="number"||typeof e==="boolean")return{kind:"single",value:e};return{kind:"single",value:String(e)}}function b(e){return typeof e==="string"||typeof e==="number"||typeof e==="boolean"||e===null?e:String(e)}function k(e){if(e.kind==="detail"||e.kind==="timeline"||e.kind==="timeline-graph")return;return e.collection?.pagination?.pageSize}function m(e,r){if(r==null)return;const t=D(r);switch(e.type){case"number":case"percent":case"currency":case"duration":return V(e.key,t);case"boolean":return typeof t==="boolean"?void 0:`Filter must be boolean: ${e.key}`;case"date":case"time":case"datetime":return h(e.key,t);case"search":case"enum":default:return}}function D(e){if(!f(e))return e;switch(e.kind){case"single":return e.value;case"multi":return e.values;case"range":return[e.from,e.to].filter((r)=>r!=null);case"composite":return}}function f(e){return typeof e==="object"&&e!=null&&"kind"in e&&typeof e.kind==="string"}function V(e,r){return(Array.isArray(r)?r:[r]).every((i)=>typeof i==="number")?void 0:`Filter must be numeric: ${e}`}function h(e,r){return(Array.isArray(r)?r:[r]).every((i)=>typeof i==="string"||typeof i==="number")?void 0:`Filter must be comparable: ${e}`}

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

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

package/dist/data-views/registry.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as t}from"../registry.js";export function dataViewKey(e){return`${e.meta.key}.v${e.meta.version}`}export class DataViewRegistry extends t{constructor(e){super("data-view",e)}}

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

@@ -0,0 +1,89 @@
+/**
+ * Data view for the contract verification status table rendered in reports.
+ */
+import type { DocBlock } from '../../docs/types.js';
+export declare const ContractVerificationTableDataView: {
+    readonly meta: {
+        readonly key: "report.contractVerificationTable";
+        readonly title: "Contract Verification Table";
+        readonly version: "1.0.0";
+        readonly description: "Table view of per-contract verification status for the impact report.";
+        readonly domain: "report";
+        readonly owners: ["platform.core"];
+        readonly tags: ["report", "data-view", "verification"];
+        readonly stability: "experimental";
+        readonly entity: "contract-verification";
+    };
+    readonly source: {
+        primary: {
+            key: string;
+            version: string;
+        };
+    };
+    readonly view: {
+        readonly kind: "table";
+        readonly fields: [{
+            readonly key: "name";
+            readonly label: "field.name.label";
+            readonly dataPath: "name";
+        }, {
+            readonly key: "timeSinceVerified";
+            readonly label: "field.timeSinceVerified.label";
+            readonly dataPath: "lastVerifiedDate";
+        }, {
+            readonly key: "driftMismatches";
+            readonly label: "field.driftMismatches.label";
+            readonly dataPath: "driftMismatches";
+            readonly format: "number";
+            readonly sortable: true;
+        }, {
+            readonly key: "surfaces";
+            readonly label: "field.surfaces.label";
+            readonly dataPath: "surfaces";
+            readonly format: "badge";
+        }, {
+            readonly key: "lastVerifiedSha";
+            readonly label: "field.lastVerifiedSha.label";
+            readonly dataPath: "lastVerifiedSha";
+            readonly width: "sm";
+        }];
+        readonly primaryField: "name";
+        readonly secondaryFields: ["driftMismatches", "timeSinceVerified"];
+        readonly columns: [{
+            readonly field: "name";
+            readonly width: "lg";
+        }, {
+            readonly field: "lastVerifiedSha";
+            readonly width: "sm";
+        }, {
+            readonly field: "timeSinceVerified";
+            readonly width: "sm";
+        }, {
+            readonly field: "surfaces";
+            readonly width: "md";
+        }, {
+            readonly field: "driftMismatches";
+            readonly width: "xs";
+            readonly align: "right";
+        }];
+    };
+    readonly policy: {
+        flags: [];
+        pii: [];
+    };
+} & {
+    meta: {
+        readonly key: "report.contractVerificationTable";
+        readonly title: "Contract Verification Table";
+        readonly version: "1.0.0";
+        readonly description: "Table view of per-contract verification status for the impact report.";
+        readonly domain: "report";
+        readonly owners: ["platform.core"];
+        readonly tags: ["report", "data-view", "verification"];
+        readonly stability: "experimental";
+        readonly entity: "contract-verification";
+    } & {
+        translationKey: "report.contractVerificationTable.i18n";
+    };
+};
+export declare const reportVerificationTableDocBlocks: DocBlock[];

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

@@ -0,0 +1,29 @@
+import{GetContractVerificationStatusQuery as e}from"../../operations/report/getContractVerificationStatus.js";import{StabilityEnum as t}from"../../ownership.js";import{defineTranslation as i}from"../../translations/index.js";import{defineDataView as a}from"../spec.js";const r=i({meta:{key:"report.contractVerificationTable.i18n",version:"1.0.0",domain:"report",owners:["platform.core"]},locale:"en",messages:{"field.name.label":{value:"Contract / Endpoint / Event"},"field.timeSinceVerified.label":{value:"Time since verified"},"field.driftMismatches.label":{value:"Drift debt"},"field.surfaces.label":{value:"Surfaces covered"},"field.lastVerifiedSha.label":{value:"Last verified commit"}}});export const ContractVerificationTableDataView=a(r,{meta:{key:"report.contractVerificationTable",title:"Contract Verification Table",version:"1.0.0",description:"Table view of per-contract verification status for the impact report.",domain:"report",owners:["platform.core"],tags:["report","data-view","verification"],stability:t.Experimental,entity:"contract-verification"},source:{primary:{key:e.meta.key,version:e.meta.version}},view:{kind:"table",fields:[{key:"name",label:"field.name.label",dataPath:"name"},{key:"timeSinceVerified",label:"field.timeSinceVerified.label",dataPath:"lastVerifiedDate"},{key:"driftMismatches",label:"field.driftMismatches.label",dataPath:"driftMismatches",format:"number",sortable:!0},{key:"surfaces",label:"field.surfaces.label",dataPath:"surfaces",format:"badge"},{key:"lastVerifiedSha",label:"field.lastVerifiedSha.label",dataPath:"lastVerifiedSha",width:"sm"}],primaryField:"name",secondaryFields:["driftMismatches","timeSinceVerified"],columns:[{field:"name",width:"lg"},{field:"lastVerifiedSha",width:"sm"},{field:"timeSinceVerified",width:"sm"},{field:"surfaces",width:"md"},{field:"driftMismatches",width:"xs",align:"right"}]},policy:{flags:[],pii:[]}});export const reportVerificationTableDocBlocks=[{id:"docs.tech.report-verification-table",title:"Contract Verification Table",summary:"How the impact report renders per-contract verification status.",kind:"how",visibility:"public",route:"/docs/tech/report/verification-table",tags:["report","drift","verification","impact"],owners:["platform.core"],domain:"report",body:`# Contract Verification Table
+
+The impact report includes an optional per-contract verification table that summarises the health of each contract at a glance.
+
+## Columns
+
+| Column | Description |
+|--------|-------------|
+| Contract / Endpoint / Event | Fully qualified contract name (e.g. \`user.create\`) |
+| Drift debt | Number of mismatches currently detected |
+| Time since verified | Human-friendly elapsed time (e.g. "23 days") or "Never" |
+| Surfaces covered | Comma-separated list (API, runtime validation, UI form, docs/examples, permissions) |
+| Last verified commit | Short SHA of the last drift-free commit |
+
+## Data flow
+
+1. The drift detector produces per-contract mismatch counts.
+2. \`.contractspec/verified.json\` records the last clean commit per contract.
+3. The report script reads both sources and renders the Markdown table.
+
+## Backward compatibility
+
+When \`contracts\` is absent from the report JSON, the table is skipped and the existing report sections render unchanged.
+
+## Contracts
+
+- Query: \`report.getContractVerificationStatus\` (v1.0.0)
+- Data view: \`report.contractVerificationTable\` (v1.0.0)
+`}];

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

@@ -0,0 +1,25 @@
+import { DataViewRegistry, type DataViewSpec } from '../data-views/index.js';
+import { OperationSpecRegistry } from '../operations/index.js';
+import type { HandlerCtx } from '../types.js';
+export interface DataViewRuntimeConfig {
+    registry: DataViewRegistry;
+    operationRegistry: OperationSpecRegistry;
+}
+export interface DataViewResult<T = unknown> {
+    data: T[];
+    total: number;
+    loading: boolean;
+    error?: Error;
+}
+export 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;
+}

package/dist/data-views/runtime.js

@@ -0,0 +1 @@
+export class DataViewRuntime{config;cache=new Map;subscriptions=new Map;constructor(t){this.config=t}register(t){this.config.registry.register(t)}getSpec(t,r){return this.config.registry.get(t,r)}async executeQuery(t,r,s){const n=this.getSpec(t);if(!n)throw Error(`DataView spec not found: ${t}`);const i=n.source.primary;if(!i)throw Error(`DataView spec ${t} missing primary source`);try{const e=await this.config.operationRegistry.execute(i.key,i.version,r,s);if(Array.isArray(e))return{data:e,total:e.length,loading:!1};if(a(e))return{data:e.items,total:e.total??e.items.length,loading:!1};return{data:[e],total:1,loading:!1}}catch(e){return{data:[],total:0,loading:!1,error:e instanceof Error?e:Error(String(e))}}}invalidate(t){this.cache.delete(t);this.notifySubscribers(t)}subscribe(t,r){if(!this.subscriptions.has(t))this.subscriptions.set(t,new Set);this.subscriptions.get(t)?.add(r);return()=>{this.subscriptions.get(t)?.delete(r)}}notifySubscribers(t){this.subscriptions.get(t)?.forEach((r)=>r())}}function a(t){return typeof t==="object"&&t!==null&&"items"in t&&Array.isArray(t.items)}

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

@@ -0,0 +1,56 @@
+import type { GraphFilterSpec } from './graph-filter-spec.js';
+/** Pan + zoom state of the graph canvas. */
+export interface SavedViewport {
+    readonly x: number;
+    readonly y: number;
+    readonly zoom: number;
+}
+/** Serialisable snapshot of graph state saved by the user. */
+export interface SavedView {
+    readonly id: string;
+    readonly name: string;
+    readonly viewport: SavedViewport;
+    /** Optional filter snapshot — absent means no active filter. */
+    readonly filter?: GraphFilterSpec;
+    /** Layout kind key (e.g. 'force', 'dag', 'radial'). */
+    readonly layout?: string;
+    /** ISO 8601 creation timestamp. */
+    readonly savedAt: string;
+}
+/** URL search param key used to encode a SavedView. */
+export declare const SAVED_VIEW_PARAM = "gv";
+/** Minimum zoom level accepted on restore (prevents invisible graph). */
+export declare const MIN_ZOOM = 0.05;
+/** Maximum zoom level accepted on restore (prevents extreme over-zoom). */
+export declare const MAX_ZOOM = 10;
+/**
+ * Encode a `SavedView` to a URL-safe base64 string.
+ *
+ * The result can be placed directly in `?gv=<value>`.
+ */
+export declare function serializeSavedView(view: SavedView): string;
+/**
+ * Decode a base64 string back to a `SavedView`.
+ *
+ * Returns `null` when the input is not valid base64, is not valid JSON,
+ * or does not satisfy the `SavedView` shape.
+ * Zoom is clamped to `[MIN_ZOOM, MAX_ZOOM]` on restore.
+ */
+export declare function deserializeSavedView(encoded: string): SavedView | null;
+/**
+ * Type guard for `SavedView`.
+ *
+ * Validates the required fields; optional `filter` and `layout` are
+ * accepted as-is when present (no deep schema validation).
+ */
+export declare function isValidSavedView(raw: unknown): raw is SavedView;
+export declare const savedViewDoc: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};

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

@@ -0,0 +1 @@
+export const SAVED_VIEW_PARAM="gv";export const MIN_ZOOM=0.05;export const MAX_ZOOM=10;export function serializeSavedView(n){return btoa(unescape(encodeURIComponent(JSON.stringify(n))))}export function deserializeSavedView(n){try{const e=decodeURIComponent(escape(atob(n))),t=JSON.parse(e);if(!isValidSavedView(t))return null;return{...t,viewport:{...t.viewport,zoom:Math.max(0.05,Math.min(10,t.viewport.zoom))}}}catch{return null}}export function isValidSavedView(n){if(typeof n!=="object"||n===null)return!1;const e=n;if(typeof e.id!=="string"||e.id.length===0)return!1;if(typeof e.name!=="string")return!1;if(typeof e.savedAt!=="string"||e.savedAt.length===0)return!1;const t=e.viewport;if(typeof t!=="object"||t===null)return!1;const r=t;if(typeof r.x!=="number")return!1;if(typeof r.y!=="number")return!1;if(typeof r.zoom!=="number")return!1;return!0}export const savedViewDoc={id:"docs.contracts-spec.data-views.saved-view",title:"SavedView \u2014 serialisable graph viewport + filter + layout snapshot",summary:"Encodes graph viewport, active filter, and layout as a base64 URL param (?gv=). Use serializeSavedView / deserializeSavedView to persist and restore. useSavedViewRestore reads ?gv= on mount and applies the snapshot.",kind:"reference",visibility:"public",route:"/docs/contracts-spec/data-views/saved-view",tags:["graph","saved-view","url","restore","viewport","m3"],body:"# SavedView\n\nSerialisable snapshot of the current graph state stored in `?gv=<base64>`.\n\n## Fields\n\n| Field | Type | Description |\n|---|---|---|\n| `id` | `string` | Unique view identifier |\n| `name` | `string` | Human-readable label |\n| `viewport` | `SavedViewport` | Pan + zoom state |\n| `filter` | `GraphFilterSpec?` | Active filter snapshot |\n| `layout` | `string?` | Layout kind key |\n| `savedAt` | `string` | ISO 8601 timestamp |\n\n## URL encoding\n\nZoom is clamped to `[0.05, 10]` on decode. Invalid or absent `?gv=` always yields `null`.\n"};

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

@@ -0,0 +1,63 @@
+import type { DocBlock } from '../docs/types.js';
+import type { ExperimentRef } from '../experiments/spec.js';
+import type { DataViewRef } from '../features/types.js';
+import type { SurfacePolicyRequirement } from '../policy/requirements.js';
+import type { TranslationSpec } from '../translations/spec.js';
+import type { DataViewGraphSpec } from './graph-spec.js';
+import type { DisplayKeyConstraint, MessageKeyOf } from './i18n-constraint.js';
+import type { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from './types.js';
+export type { DisplayKeyConstraint, MessageKeyOf } from './i18n-constraint.js';
+export type { DataViewGraphSpec, DataViewRef };
+/**
+ * Complete specification for a standard data view (list | detail | table | grid | timeline).
+ *
+ * For graph or timeline-graph views, use {@link DataViewGraphSpec} instead.
+ * Both types are accepted by {@link defineDataView}.
+ */
+export interface DataViewSpec {
+    meta: DataViewMeta;
+    source: DataViewSource;
+    view: DataViewConfig;
+    states?: DataViewStates;
+    policy?: SurfacePolicyRequirement;
+    experiments?: ExperimentRef[];
+}
+/**
+ * Helper to define a data view spec with compile-checked i18n keys.
+ *
+ * Accepts both {@link DataViewSpec} (list | detail | table | grid | timeline)
+ * and {@link DataViewGraphSpec} (graph | timeline-graph). The runtime
+ * discriminator is `view.kind`:
+ * - `'graph' | 'timeline-graph'` → `DataViewGraphSpec` branch
+ * - `'list' | 'detail' | 'table' | 'grid' | 'timeline'` → `DataViewSpec` branch
+ *
+ * **i18n contract (D1/D2/D4).** The first argument is a translation `bundle`
+ * (a {@link TranslationSpec} authored with the literal-preserving
+ * `defineTranslation`). Every display-text leaf under `spec.view` (field /
+ * filter / option / action / confirmation / section / relationship / column /
+ * lane / header / paginationSummary / sort / actionGroup / metricField labels,
+ * descriptions, placeholders, titles, and `viewModes.labels` record values)
+ * is statically constrained to be a member of `keyof bundle.messages` via
+ * {@link DisplayKeyConstraint} — a typo is a `tsc` error at the offending leaf.
+ * Specs author BARE message keys (e.g. `label: 'field.name'`); the factory
+ * STAMPS `meta.translationKey = bundle.meta.key` so the renderer can build the
+ * qualified `${translationKey}::${messageKey}` resolver key. `DataViewSpec`
+ * itself stays NON-generic (D2): all read-only consumers are unaffected.
+ *
+ * ⚠️ LITERAL-PRESERVATION RULE (hand this to every callsite author): the
+ * `bundle` MUST typecheck as a valid {@link TranslationSpec}. If any bundle
+ * field is malformed, `const` inference widens `keyof bundle.messages` to
+ * `string`, and ALL leaf checks silently pass (no compile error on typos).
+ * A green bundle is the precondition for the whole safety property.
+ */
+export declare function defineDataView<const B extends TranslationSpec, const Spec extends DataViewSpec>(bundle: B, spec: Spec & DisplayKeyConstraint<Spec, MessageKeyOf<B>>): Spec & {
+    meta: Spec['meta'] & {
+        translationKey: B['meta']['key'];
+    };
+};
+export declare function defineDataView<const B extends TranslationSpec, const Spec extends DataViewGraphSpec>(bundle: B, spec: Spec & DisplayKeyConstraint<Spec, MessageKeyOf<B>>): Spec & {
+    meta: Spec['meta'] & {
+        translationKey: B['meta']['key'];
+    };
+};
+export declare const tech_contracts_data_views_DocBlocks: DocBlock[];

package/dist/data-views/spec.js

@@ -0,0 +1,23 @@
+export function defineDataView(t,e){return{...e,meta:{...e.meta,translationKey:t.meta.key}}}export 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, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/data-views",tags:["tech","contracts","data-views"],body:`# DataViewSpec Overview
+
+## Purpose
+
+\`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, filter, paginate, pin records, and optionally compose adaptive entity-management command centers.
+
+## Schema Highlights
+
+- **DataViewMeta**: ownership metadata plus an entity slug.
+- **DataViewSource**: primary/item operation refs, mutation operation refs, refresh events, and optional database binding.
+- **DataViewConfig**: list/detail/table/grid definitions with fields, filters, actions, collection preferences, and optional \`view.management\` metadata.
+- **DataViewAction**: declarative actions with optional placement, intent, selection scope, approval/destructive boundary, and operation refs.
+- **DataViewConfig.management**: optional command-center metadata for header copy, master-detail layout, toolbar groups, selection/bulk actions, detail empty states, personalization keys, and RoleMorph refs.
+- **DataViewSections**: detail-view sections discriminated by \`kind\` (default \`'fields'\`). A \`'relationship'\` section carries a \`relationship: DataViewSectionRelationship\` (\`key\`, \`cardinality\`, \`dataPath?\`/\`source?\`/\`specKey?\`/inline \`fields?\`, \`displayMode?\`, \`limit?\`, \`emptyState?\`) and renders a related-record collection. The declared relation \`OpRef\` is host-executed; the design-system performs no I/O.
+
+## Authoring Guidelines
+
+1. Keep fetching logic inside contract operations; DataViewSpec only references them via \`source\`.
+2. Use \`view.management\` for entity-management projection metadata only.
+3. Keep persistence, validation, modal flow, destructive confirmations, and network side effects host-owned or FormSpec-owned.
+4. Prefer additive metadata and version specs deliberately when field membership, ordering, or semantics change.
+5. Declare relationships via a \`kind: 'relationship'\` section; supply related records embedded (\`dataPath\`) or host-supplied \u2014 the design-system never executes the relation \`OpRef\`.
+`}];