@continuum-dev/contract 0.1.1-alpha.0

package/CONTRACT_REFERENCE.md

@@ -0,0 +1,349 @@
+# Continuum Contract Reference
+
+This is the canonical deep reference for `@continuum-dev/contract`.
+
+`@continuum-dev/contract` is intentionally a zero-dependency package of shared contracts and constants. It defines the type system used by Continuum packages to preserve user state while views evolve.
+
+## Table of Contents
+
+- [Package Surface](#package-surface)
+- [Core Domain Model](#core-domain-model)
+- [Relationship Map](#relationship-map)
+- [Lifecycle Context](#lifecycle-context)
+- [View Contracts AST](#view-contracts-ast)
+- [Data Contracts State](#data-contracts-state)
+- [Interaction and Intent Contracts](#interaction-and-intent-contracts)
+- [Constants](#constants)
+- [Invariants](#invariants)
+- [Import Pattern](#import-pattern)
+
+## Package Surface
+
+Public exports are re-exported from `src/index.ts`:
+
+- `./lib/continuity-snapshot.js`
+- `./lib/view-definition.js`
+- `./lib/data-snapshot.js`
+- `./lib/interactions.js`
+- `./lib/constants.js`
+
+## Core Domain Model
+
+- `ViewDefinition` defines the versioned UI structure.
+- `DataSnapshot` stores user-owned runtime values and lineage.
+- `ContinuitySnapshot` is the atomic pairing of `view` and `data`.
+- `Interaction`, `PendingIntent`, and `Checkpoint` describe events and recoverability.
+- constants in `constants.ts` provide stable vocabularies.
+
+## Relationship Map
+
+How the contracts connect in practice:
+
+```text
+ContinuitySnapshot
+|- view: ViewDefinition
+|  `- nodes: ViewNode[]
+|     |- FieldNode (data-bearing)
+|     |- GroupNode -> children: ViewNode[]
+|     |- CollectionNode -> template: ViewNode
+|     |- RowNode -> children: ViewNode[]
+|     |- GridNode -> children: ViewNode[]
+|     |- ActionNode (intent trigger)
+|     `- PresentationNode (read-only content)
+`- data: DataSnapshot
+   |- values: Record<nodeId, NodeValue>
+   |- detachedValues: Record<nodeId, DetachedValue>
+   |- lineage: SnapshotLineage
+   |- valueLineage: Record<nodeId, ValueLineage>
+   `- viewContext: Record<nodeId, ViewportState>
+
+Checkpoint
+`- snapshot: ContinuitySnapshot
+
+Interaction
+`- type: InteractionType
+
+PendingIntent
+`- status: IntentStatus
+```
+
+Identity rules that make the model work:
+
+- `ViewDefinition.nodes[*].id` is the primary key for `DataSnapshot.values`.
+- `key` is optional at the type level, but should be adopted as a production convention for stable semantic identity across versions/migrations.
+- `viewId` + `version` identify one concrete shape of the view.
+- `DataSnapshot.lineage.viewVersion` ties captured data back to the view revision.
+
+Example of `id` vs `key` in action:
+
+- prior view node: `{ id: "email_input", key: "user.email", type: "field" }`
+- new view node: `{ id: "row_1/email_input", key: "user.email", type: "field" }`
+
+Even though the structural `id` changed, the stable `key` allows continuity logic to carry the existing user value to the new node.
+
+`key` adoption guidance:
+
+- treat `key` as required-by-convention for continuity-critical nodes
+- use stable semantic keys (for example `applicant.fullName`) rather than layout-derived keys
+- keep `key` stable across restructures and only change it when semantics truly change
+- prefer `id` for per-version addressing and `key` for cross-version matching
+
+## Lifecycle Context
+
+Typical runtime sequence:
+
+1. The system receives or generates a `ViewDefinition`.
+2. User edits are stored in `DataSnapshot.values[nodeId]` as `NodeValue`.
+3. Current structure + state are persisted/transferred as one `ContinuitySnapshot`.
+4. User/system actions are recorded as `Interaction` events.
+5. Deferred commands are tracked as `PendingIntent` and moved through `INTENT_STATUS`.
+6. Durable restore points are captured as `Checkpoint` objects.
+7. When the view changes:
+  - compatible values stay in `values`
+  - migrated values are transformed using consumer logic
+  - incompatible or removed values move to `detachedValues` instead of being lost
+
+Why this separation matters:
+
+- the AI can safely mutate layout (`ViewDefinition`) without directly mutating user data
+- user intent remains auditable via lineage and interaction history
+- data survives hallucinated or transient schema changes through detachment/restoration
+
+## View Contracts AST
+
+`ViewDefinition`:
+
+```ts
+interface ViewDefinition {
+  viewId: string;
+  version: string;
+  nodes: ViewNode[];
+}
+```
+
+`ViewNode` is a discriminated union:
+
+```ts
+type ViewNode =
+  | FieldNode
+  | GroupNode
+  | CollectionNode
+  | ActionNode
+  | PresentationNode
+  | RowNode
+  | GridNode;
+```
+
+Shared node shape:
+
+```ts
+interface BaseNode {
+  id: string;
+  type: string;
+  key?: string;
+  hidden?: boolean;
+  hash?: string;
+  migrations?: MigrationRule[];
+}
+```
+
+```ts
+interface FieldOption {
+  value: string;
+  label: string;
+}
+```
+
+BaseNode properties and why they matter:
+
+- `id`: required structural identifier used for per-version addressing.
+- `key`: semantic identity for cross-version matching; optional by type, recommended by convention.
+- `hash`: node fingerprint for compatibility checks when structure or constraints change.
+- `migrations`: allowed hash transitions and strategy hints for safe data transformation.
+
+Traversal helper:
+
+```ts
+function getChildNodes(node: ViewNode): ViewNode[];
+```
+
+## Data Contracts State
+
+```ts
+interface DataSnapshot {
+  values: Record<string, NodeValue>;
+  viewContext?: Record<string, ViewContext>;
+  lineage: SnapshotLineage;
+  valueLineage?: Record<string, ValueLineage>;
+  detachedValues?: Record<string, DetachedValue>;
+}
+```
+
+```ts
+interface NodeValue<T = unknown> {
+  value: T;
+  suggestion?: T;
+  isDirty?: boolean;
+  isValid?: boolean;
+}
+```
+
+```ts
+interface CollectionItemState {
+  values: Record<string, NodeValue>;
+}
+
+interface CollectionNodeState {
+  items: CollectionItemState[];
+}
+```
+
+```ts
+interface ViewportState {
+  scrollX?: number;
+  scrollY?: number;
+  zoom?: number;
+  offsetX?: number;
+  offsetY?: number;
+  isExpanded?: boolean;
+  isFocused?: boolean;
+}
+```
+
+```ts
+type ViewContext = ViewportState;
+```
+
+```ts
+interface DetachedValue {
+  value: unknown;
+  previousNodeType: string;
+  key?: string;
+  detachedAt: number;
+  viewVersion: string;
+  reason: 'node-removed' | 'type-mismatch' | 'migration-failed';
+  pushesSinceDetach?: number;
+}
+```
+
+```ts
+interface DetachedValuePolicy {
+  maxAge?: number;
+  maxCount?: number;
+  pushCount?: number;
+}
+```
+
+```ts
+interface ProposedValue {
+  nodeId: string;
+  proposedValue: NodeValue;
+  currentValue: NodeValue;
+  proposedAt: number;
+  source?: string;
+}
+```
+
+```ts
+interface ActionRegistration {
+  label: string;
+  description?: string;
+  icon?: string;
+}
+```
+
+```ts
+interface ActionContext {
+  intentId: string;
+  snapshot: DataSnapshot;
+  nodeId: string;
+}
+```
+
+```ts
+type ActionHandler = (context: ActionContext) => void | Promise<void>;
+```
+
+How these state types are typically used:
+
+- `ViewportState` tracks UI-only state and is aliased by `ViewContext`.
+- `DetachedValuePolicy` configures cleanup of detached data by age, count, or push count.
+- `ProposedValue` models AI suggestions versus current user values for conflict-aware UX.
+- `ActionRegistration`, `ActionContext`, and `ActionHandler` define action metadata and execution context.
+
+## Interaction and Intent Contracts
+
+```ts
+interface Interaction {
+  interactionId: string;
+  sessionId: string;
+  nodeId: string;
+  type: InteractionType;
+  payload: unknown;
+  timestamp: number;
+  viewVersion: string;
+}
+```
+
+```ts
+interface PendingIntent {
+  intentId: string;
+  nodeId: string;
+  intentName: string;
+  payload: unknown;
+  queuedAt: number;
+  viewVersion: string;
+  status: IntentStatus;
+}
+```
+
+```ts
+interface Checkpoint {
+  checkpointId: string;
+  sessionId: string;
+  snapshot: ContinuitySnapshot;
+  eventIndex: number;
+  timestamp: number;
+  trigger: 'auto' | 'manual';
+}
+```
+
+## Constants
+
+The package exports `as const` vocabularies and derived unions:
+
+- `ISSUE_CODES` / `IssueCode`
+- `DATA_RESOLUTIONS` / `DataResolution`
+- `VIEW_DIFFS` / `ViewDiff`
+- `ISSUE_SEVERITY` / `IssueSeverity`
+- `INTERACTION_TYPES` / `InteractionType`
+- `INTENT_STATUS` / `IntentStatus`
+
+## Invariants
+
+- `DataSnapshot.values` keys should map to active nodes unless detached.
+- `id` is required for all nodes; `key` remains optional in the schema but is recommended for production continuity guarantees.
+- `PendingIntent.status` must be from `INTENT_STATUS`.
+- `DetachedValue.reason` must be one of `node-removed`, `type-mismatch`, `migration-failed`.
+- `ViewNode.type` must match the concrete node shape.
+
+## Import Pattern
+
+Import from the package root only:
+
+```ts
+import {
+  ViewDefinition,
+  DataSnapshot,
+  ContinuitySnapshot,
+  NodeValue,
+  DetachedValue,
+  ISSUE_CODES,
+} from '@continuum-dev/contract';
+```
+
+## Related Docs
+
+- Package overview and examples: `README.md`
+- Source type modules: `src/lib/*.ts`
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CooperContinuum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @continuum-dev/contract
+
+**The foundational type system for AI-generated UI continuity.**
+
+When building agentic UIs, teams eventually hit the re-render problem: when an AI agent streams a new schema or layout, the frontend remounts and local user input gets lost.
+
+`@continuum-dev/contract` defines a strict boundary between **View** (AI-owned structure) and **Data** (user-owned state). This package is zero-dependency and contains the shared TypeScript contracts used across the Continuum ecosystem.
+
+## Installation
+
+```bash
+npm install @continuum-dev/contract
+```
+
+## The Mental Model
+
+Continuum uses three core contracts:
+
+- `ViewDefinition` (AI-owned): a versioned tree describing UI structure.
+- `DataSnapshot` (user-owned): a flat dictionary of user state keyed by node id.
+- `ContinuitySnapshot`: the atomic pairing of `view` and `data`.
+
+Because data is flat and separate from the tree, views can be restructured without losing user input.
+
+## Node Identity Guidance (`id` and `key`)
+
+- `id` is required and is the primary lookup key for `DataSnapshot.values`.
+- `key` is optional in the type system, but should be adopted in production for stable semantic identity across view versions.
+- If AI-generated views can rename or regenerate node ids, `key` is what allows reliable matching and data carry/migration.
+- Recommended practice: include `key` on all data-bearing nodes (`FieldNode`) and on structural nodes that need continuity-aware matching.
+
+## The Secret Sauce: `NodeValue`
+
+In Continuum, values are collaborative, not raw primitives:
+
+```ts
+interface NodeValue<T = unknown> {
+  value: T;
+  suggestion?: T;
+  isDirty?: boolean;
+  isValid?: boolean;
+}
+```
+
+- `suggestion` lets AI propose alternatives.
+- `isDirty` protects user-edited values from accidental overwrite.
+- `isValid` tracks compatibility with current constraints.
+
+## No Data Left Behind: `DetachedValue`
+
+If a view update removes or changes a node incompatibly, data is preserved in `detachedValues`:
+
+```ts
+interface DetachedValue {
+  value: unknown;
+  previousNodeType: string;
+  reason: 'node-removed' | 'type-mismatch' | 'migration-failed';
+}
+```
+
+If the node returns in a compatible form, data can be restored.
+
+## Minimal Example
+
+```ts
+import {
+  ViewDefinition,
+  DataSnapshot,
+  ContinuitySnapshot,
+} from '@continuum-dev/contract';
+
+const view: ViewDefinition = {
+  viewId: 'loan-application',
+  version: '2.1.0',
+  nodes: [
+    {
+      id: 'fullName',
+      type: 'field',
+      dataType: 'string',
+      label: 'Full Name',
+      key: 'applicant.fullName',
+      constraints: { required: true, minLength: 2 },
+    },
+  ],
+};
+
+const data: DataSnapshot = {
+  values: {
+    fullName: {
+      value: 'Jordan Lee',
+      isDirty: true,
+      isValid: true,
+    },
+  },
+  lineage: {
+    timestamp: 1740700800000,
+    sessionId: 'sess-123',
+    viewId: view.viewId,
+    viewVersion: view.version,
+  },
+};
+
+const snapshot: ContinuitySnapshot = {
+  view,
+  data,
+};
+```
+
+## API Quick Reference
+
+Import everything from the package root:
+
+```ts
+import {
+  ViewDefinition,
+  ViewNode,
+  DataSnapshot,
+  ContinuitySnapshot,
+  NodeValue,
+  ProposedValue,
+  DetachedValue,
+  ViewportState,
+  ActionHandler,
+  ActionContext,
+  ISSUE_CODES,
+  DATA_RESOLUTIONS,
+  VIEW_DIFFS,
+  INTERACTION_TYPES,
+  INTENT_STATUS,
+} from '@continuum-dev/contract';
+```
+
+**Core types:**
+
+* `ViewDefinition`: root AST for generated UI.
+* `ViewNode`: discriminated union of supported node types.
+* `DataSnapshot`: user-owned runtime state.
+* `ContinuitySnapshot`: atomic `ViewDefinition + DataSnapshot`.
+
+**State primitives:**
+
+* `NodeValue<T>`: value wrapper with collaboration metadata.
+* `ProposedValue`: models AI suggestions alongside current user values for conflict resolution.
+* `DetachedValue`: preserved state for removed or incompatible nodes.
+* `ViewportState`: UI interaction state (scroll/focus/zoom/offset).
+
+**Actions:**
+
+* `ActionHandler`: execution contract for UI intents (`(context: ActionContext) => void | Promise<void>`).
+* `ActionContext`: runtime context passed to handlers containing the intent ID, node ID, and current snapshot.
+
+**Constants:**
+
+* `ISSUE_CODES`: reconciliation issue taxonomy.
+* `DATA_RESOLUTIONS`: value reconciliation outcomes.
+* `VIEW_DIFFS`: structural diff labels.
+* `INTERACTION_TYPES`: canonical interaction event categories.
+* `INTENT_STATUS`: pending intent lifecycle states.
+
+## Deep Dive Reference
+
+For the complete breakdown of all node types, constraints, constants, and migration contracts, see [Comprehensive Contract Reference](./CONTRACT_REFERENCE.md).
+
+## Ecosystem
+
+This package defines the vocabulary. Other Continuum packages provide runtime behavior:
+
+- `@continuum-dev/runtime`: stateless reconciliation engine.
+- `@continuum-dev/session`: stateful session memory, history, and checkpoints.
+- `@continuum-dev/react`: headless React layer for UI binding.

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/continuity-snapshot.js';
+export * from './lib/view-definition.js';
+export * from './lib/data-snapshot.js';
+export * from './lib/interactions.js';
+export * from './lib/constants.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../packages/contract/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC"}

package/index.js

@@ -0,0 +1,5 @@
+export * from './lib/continuity-snapshot.js';
+export * from './lib/view-definition.js';
+export * from './lib/data-snapshot.js';
+export * from './lib/interactions.js';
+export * from './lib/constants.js';

package/lib/constants.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Canonical issue taxonomy for reconciliation, validation, and view analysis.
+ */
+export declare const ISSUE_CODES: {
+    readonly NO_PRIOR_DATA: "NO_PRIOR_DATA";
+    readonly NO_PRIOR_VIEW: "NO_PRIOR_VIEW";
+    readonly TYPE_MISMATCH: "TYPE_MISMATCH";
+    readonly NODE_REMOVED: "NODE_REMOVED";
+    readonly MIGRATION_FAILED: "MIGRATION_FAILED";
+    readonly UNVALIDATED_CARRY: "UNVALIDATED_CARRY";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly UNKNOWN_NODE: "UNKNOWN_NODE";
+    readonly DUPLICATE_NODE_ID: "DUPLICATE_NODE_ID";
+    readonly DUPLICATE_NODE_KEY: "DUPLICATE_NODE_KEY";
+    readonly VIEW_CHILD_CYCLE_DETECTED: "VIEW_CHILD_CYCLE_DETECTED";
+    readonly VIEW_MAX_DEPTH_EXCEEDED: "VIEW_MAX_DEPTH_EXCEEDED";
+    readonly COLLECTION_CONSTRAINT_VIOLATED: "COLLECTION_CONSTRAINT_VIOLATED";
+    readonly SCOPE_COLLISION: "SCOPE_COLLISION";
+};
+/**
+ * Union of all supported issue code literals.
+ */
+export type IssueCode = (typeof ISSUE_CODES)[keyof typeof ISSUE_CODES];
+/**
+ * Outcomes for how a value was handled during reconciliation.
+ */
+export declare const DATA_RESOLUTIONS: {
+    readonly CARRIED: "carried";
+    readonly MIGRATED: "migrated";
+    readonly DETACHED: "detached";
+    readonly ADDED: "added";
+    readonly RESTORED: "restored";
+};
+/**
+ * Union of all supported data resolution literals.
+ */
+export type DataResolution = (typeof DATA_RESOLUTIONS)[keyof typeof DATA_RESOLUTIONS];
+/**
+ * Node-level structural change classifications between view revisions.
+ */
+export declare const VIEW_DIFFS: {
+    readonly ADDED: "added";
+    readonly REMOVED: "removed";
+    readonly MIGRATED: "migrated";
+    readonly TYPE_CHANGED: "type-changed";
+    readonly RESTORED: "restored";
+};
+/**
+ * Union of all supported view diff literals.
+ */
+export type ViewDiff = (typeof VIEW_DIFFS)[keyof typeof VIEW_DIFFS];
+/**
+ * Severity levels for reported issues.
+ */
+export declare const ISSUE_SEVERITY: {
+    readonly ERROR: "error";
+    readonly WARNING: "warning";
+    readonly INFO: "info";
+};
+/**
+ * Union of all supported issue severity literals.
+ */
+export type IssueSeverity = (typeof ISSUE_SEVERITY)[keyof typeof ISSUE_SEVERITY];
+/**
+ * Canonical interaction categories for event producers/consumers.
+ */
+export declare const INTERACTION_TYPES: {
+    readonly DATA_UPDATE: "data-update";
+    readonly VALUE_CHANGE: "value-change";
+    readonly VIEW_CONTEXT_CHANGE: "view-context-change";
+};
+/**
+ * Union of all supported interaction type literals.
+ */
+export type InteractionType = (typeof INTERACTION_TYPES)[keyof typeof INTERACTION_TYPES];
+/**
+ * Runtime type guard for {@link InteractionType}.
+ */
+export declare function isInteractionType(value: unknown): value is InteractionType;
+/**
+ * Lifecycle states for queued intents.
+ */
+export declare const INTENT_STATUS: {
+    readonly PENDING: "pending";
+    readonly VALIDATED: "validated";
+    readonly STALE: "stale";
+    readonly CANCELLED: "cancelled";
+};
+/**
+ * Union of all supported intent status literals.
+ */
+export type IntentStatus = (typeof INTENT_STATUS)[keyof typeof INTENT_STATUS];
+//# sourceMappingURL=constants.d.ts.map

package/lib/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../packages/contract/src/lib/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;CAed,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAIzF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC"}