Spec pack

Data Fetching is one spec-first protocol with an in-house engine.

Queries, caching, offline, and conflict resolution collapse into a single canonical protocol in contracts-spec, carried by one Transport port and executed by the in-house engine in contracts-runtime-core — no `@tanstack/*`, no second cache model to drift from.

Packages and roles

• @lssm-tech/lib.contracts-spec — I/O-free protocol primitives (/query, /results).

• @lssm-tech/lib.contracts-runtime-core — framework-neutral engine + Transport/Storage/reachability ports (+ /storage/indexeddb, /storage/async-storage, /observability).

• @lssm-tech/lib.contracts-runtime-client-react — thin React binding: ContractDataEngineProvider, useContractQuery, useContractMutation.

• @lssm-tech/lib.contracts-runtime-server-rest / -server-mcp — REST and MCP Transport adapters carrying ContractResult<QueryResultEnvelope>.

• @lssm-tech/lib.design-system — QueryState-aware, I/O-free UI components.

The canonical QueryState

Design-system components consume this render-ready shape directly. The engine produces it; the React hooks return it verbatim.

1// One canonical state, three orthogonal axes — never collapse them.
2type QueryStatus = 'idle' | 'loading' | 'success' | 'error' | 'auth-expired';
3type QueryFetchStatus = 'idle' | 'fetching';
4
5interface QueryState<TData> {
6  status: QueryStatus;          // data lifecycle
7  fetchStatus: QueryFetchStatus; // in-flight network (revalidation = 'fetching' while 'success')
8  data?: TData;
9  error?: ContractProblem;
10  cacheStatus?: 'fresh' | 'stale' | 'warm' | 'offline' | 'empty' | 'conflict';
11  isStale: boolean;
12  isOffline: boolean;           // offline is a FIELD, not a status
13  conflict?: QueryConflict<TData>; // conflict is a FIELD, not a status
14  versionToken?: VersionToken;  // server-issued etag
15}

Client quick-start

1import {
2  ContractDataEngineProvider,
3  useContractQuery,
4  useContractMutation,
5} from '@lssm-tech/lib.contracts-runtime-client-react';
6import { createDataEngine } from '@lssm-tech/lib.contracts-runtime-core';
7import { createRestTransport } from '@lssm-tech/lib.contracts-runtime-server-rest/rest-transport';
8
9const engine = createDataEngine({
10  transport: createRestTransport({ baseUrl: 'https://api.example.com' }),
11});
12
13function EntityList() {
14  // The hook returns the canonical QueryState VERBATIM (+ refetch) — zero adapter into the DS.
15  const state = useContractQuery<readonly { id: string; name: string }[]>({
16    operation: { key: 'workspace.entities.list', version: '1.0.0' },
17    input: { limit: 20 },
18  });
19  if (state.status === 'loading') return null;
20  return <ul>{state.data?.map((e) => <li key={e.id}>{e.name}</li>)}</ul>;
21}
22
23export const App = () => (
24  <ContractDataEngineProvider engine={engine}>
25    <EntityList />
26  </ContractDataEngineProvider>
27);

`useContractMutation({ ctx? })` returns `{ status, data, problem, conflictOutcome, isPending, mutate }`; pass `optimistic` writes to `mutate` and the engine handles the durable offline queue, replay-on-reconnect, etag conflict resolution, and rollback.

Engine, transport, and storage

• `createDataEngine({ transport, localOffline, env?, flag?, advanced?: { storage, reachability } })` exposes query / getState / subscribe / invalidateTags / refresh / emitConflict / mutate / drain / resume / dispose. `localOffline` selects online-only, memory-cache, or offline-capable semantics; `env`/`flag` are the host on/off trigger (precedence flag > env > default), and `createDataEngineFromEnv` reads `CONTRACTSPEC_LOCAL_OFFLINE` from the host `process.env` in one call.

• REST and MCP are interchangeable Transport adapters; MCP decodes `structuredContent` first. The version token doubles as the realtime invalidation token on the `subscribe()` seam.

• Durable storage (`/storage/indexeddb` web, `/storage/async-storage` native) is secure-by-default: secret-bearing fields are redacted before persistence, with an encryption seam for at-rest data.

• Auth: the principal is carried through `ctx` unstripped; `auth-expired` pauses the offline queue, refreshes, and resumes. Enforcement of `policy.auth` stays in authos/identity-rbac — front the operation registry with a default-deny PDP.

Rendering with design-system

`DataViewList`, `EntityDetailPanel`, and `RelationshipSection` are I/O-free and `QueryState`-aware: pass the hook result straight into the `queryState` prop and they render loading / error / offline / stale / empty / conflict / auth-expired / retry — they never fetch.