@lssm-tech/lib.contracts-spec

The core library for defining what your application can do. Unified specifications for Operations, Events, Presentations, and Features.

Installation

bun add @lssm-tech/lib.contracts-spec @lssm-tech/lib.schema

What lives where

• @lssm-tech/lib.contracts-spec (root): The core contracts definitions (OperationSpec, PresentationSpec, Registry).
• @lssm-tech/lib.contracts-runtime-client-react: Browser-safe helpers (React renderers, client SDK). Import this for web/React Native.
• @lssm-tech/lib.contracts-runtime-server-rest: HTTP/MCP adapters, registries, integrations (Node-only).
• @lssm-tech/lib.schema: Schema dictionary (SchemaModel, FieldType) for I/O definitions.

Data table contract example

The canonical account-grid example starts here in @lssm-tech/lib.contracts-spec. The contract declares table execution mode, selection, pinning, resizing, row expansion, and initial state before any renderer is chosen.

import { defineDataView } from '@lssm-tech/lib.contracts-spec/data-views';
import { ListDataGridShowcaseRowsQuery } from '@lssm-tech/example.data-grid-showcase/contracts/data-grid-showcase.operation';

export const DataGridShowcaseDataView = defineDataView({
  meta: {
    key: 'examples.data-grid-showcase.table',
    version: '1.0.0',
    entity: 'account',
    title: 'Data Grid Showcase Table',
    description:
      'Declarative DataViewSpec for the ContractSpec table showcase.',
    domain: 'examples',
    owners: ['@platform.core'],
    tags: ['examples', 'table', 'data-grid'],
    stability: 'experimental',
  },
  source: {
    primary: {
      key: ListDataGridShowcaseRowsQuery.meta.key,
      version: ListDataGridShowcaseRowsQuery.meta.version,
    },
  },
  view: {
    kind: 'table',
    executionMode: 'client',
    selection: 'multiple',
    columnVisibility: true,
    columnResizing: true,
    columnPinning: true,
    rowExpansion: {
      fields: ['notes', 'renewalDate', 'lastActivityAt'],
    },
    initialState: {
      pageSize: 4,
      hiddenColumns: ['notes'],
      pinnedColumns: {
        left: ['account'],
      },
      sorting: [{ field: 'arr', desc: true }],
    },
    fields: [
      { key: 'account', label: 'Account', dataPath: 'account', sortable: true },
      { key: 'owner', label: 'Owner', dataPath: 'owner', sortable: true },
      { key: 'status', label: 'Status', dataPath: 'status', sortable: true },
      { key: 'notes', label: 'Notes', dataPath: 'notes' },
    ],
  },
});

See the live version in /docs/examples/data-grid-showcase.

Core Concepts

• OperationSpec: Immutable description of an operation (Command or Query). Defines I/O, policy, and metadata.
• OperationSpecRegistry: Registry of specs + handlers. Use installOp to attach a handler.
• CapabilitySpec: Canonical capability declaration (requires/provides).
• PolicySpec: Declarative policy rules (ABAC/ReBAC, rate limits).
• TelemetrySpec: Analytics definitions and privacy levels.
• PresentationSpec (V2): Describes how data is rendered (Web Components, Markdown, Data).
• DataViewSpec: Declarative list, table, grid, and detail contracts that the table showcase uses as its canonical account-grid example.

Lifecycle

1. Define the spec (I/O via SchemaModel or Zod).
2. Register it: installOp(registry, spec, handler).
3. Expose it via an adapter (REST, GraphQL, MCP).
4. Validate at runtime automatically.

Adapters

• server/rest-next-app: Next.js App Router adapter
• server/provider-mcp: Model Context Protocol (MCP) for AI agents
• server/graphql-pothos: GraphQL schema generator