Glossary¶

Comprehensive reference of Verity terminology and concepts

This glossary defines key terms used throughout Verity's documentation. Terms are organized alphabetically within conceptual categories.

Core Concepts¶

Truth-State¶

Server-owned authoritative state that multiple clients must agree on. Originates from the server, fetched by Verity, and never modified locally.

Examples: User profiles, todo items, order status, inventory counts, permissions

Opposite: View-state

See: Truth-State vs View-State

View-State¶

Client-owned ephemeral UI state that is local to one client and never persists server-side. Managed by the view layer (React state, Alpine data, etc.).

Examples: Which menu is open, selected tab, form input values (before submission), scroll position

Opposite: Truth-state

See: Truth-State vs View-State

Registry¶

The core Verity instance that manages all truth-state caching, fetching, and directive processing. Created via createRegistry().

Responsibilities: - Cache management - Request coalescing - Directive application - SSE connection management - Type/collection registration

See: Core API Reference

Directive¶

A semantic message from the server that describes what truth-state changed and needs to be refreshed. Directives decouple the server from view structure.

Types: - refresh_collection - Invalidate and refetch a collection - refresh_item - Invalidate and refetch an item - invalidate - Group multiple directives

Example:

{
  "op": "refresh_item",
  "name": "todo",
  "id": 42
}

See: Directives Concept | Directive API Reference

Data Types¶

Collection¶

A parameterized list of items from the server. Collections support filtering via params and return { items: [], meta: {} }.

Examples: - todos with params { status: "active" } - users with params { page: 1, role: "admin" }

Registration:

registry.registerCollection('todos', {
  fetch: async (params) => { /* ... */ }
})

See: Core API Reference

Item / Type¶

A single record identified by parameters (usually an ID). Items are registered as "types" and accessed via item().

Examples: - user with params { userId: 123 } - app_settings with params {}

Registration:

registry.registerType('user', {
  fetch: async ({ userId }) => { /* ... */ }
})

See: Core API Reference

Level¶

A detail level for an item, representing different amounts of data fetched from the server.

Examples: - simplified - ID, title, status - expanded - + description, assignee - full - + comments, attachments, history

Use case: List views fetch simplified, detail views fetch full

See: Levels & Conversions

Level Conversion¶

A transformation function that derives one level from another without a network call.

Example:

registry.registerConversion('todo', 'full', 'expanded', (full) => {
  const { comments, attachments, ...expanded } = full
  return expanded
})

Benefit: Client holds full, needs expanded → no fetch, just conversion

See: Levels & Conversions

Cache & Staleness¶

Staleness¶

The age-based freshness of cached data. Items are fresh within stalenessMs, then become stale (but still usable).

Fresh: Recently fetched, within staleness window
Stale: Older than stalenessMs, eligible for refetch

Configuration:

registry.registerCollection('todos', {
  fetch: /* ... */,
  stalenessMs: 30000  // 30 seconds
})

See: State Model

Cache Key¶

A unique identifier for a cached collection/item, combining name and serialized params.

Examples: - todos:{"status":"active"} - user:{"userId":123}

Custom keys:

registry.registerCollection('todos', {
  key: (params) => `todos:${params.status || 'all'}`
})

Coalescing¶

Batching multiple identical requests into a single network call. If multiple components request the same data simultaneously, Verity makes one fetch and shares the result.

Configuration:

registry.createRegistry({
  bulk: { delayMs: 50 }  // Wait 50ms to collect requests
})

See: Core API Reference

Directives & Invalidation¶

Directive Source¶

The client ID that originated a mutation, used to prevent double-application of directives.

Flow: 1. Client A mutates data 2. Server returns directives with source: "client-a" 3. Server emits same directives over SSE 4. Client A ignores SSE (source matches) 5. Client B applies SSE (source doesn't match)

Header: X-Verity-Client-ID: client-abc123

Idempotency Key¶

A unique identifier for a directive to prevent duplicate processing. Verity tracks recent keys and ignores duplicates.

Example:

{
  "op": "refresh_collection",
  "name": "todos",
  "idempotency_key": "bulk-complete-abc123"
}

Use case: Bulk operations, unreliable transports

See: Directive API Reference

Audience¶

A scoping mechanism for SSE messages, routing directives to specific users, teams, or contexts.

Examples: - "global" - All clients - "user-123" - Specific user - "team-abc" - Specific team

Server:

emit_directives(directives, audience='user-123')

Client:

const registry = createRegistry({
  sse: { audience: 'user-123' }
})

See: Directive API Reference

Sequence Number (seq)¶

An incrementing counter for SSE messages to detect gaps (missed messages).

Behavior: - Server increments sequence per audience - Client tracks expected next sequence - If gap detected (expected 42, got 44), client triggers resync

See: Directive API Reference | Devtools SSE Panel

Resync¶

A forced refetch of all active collections, triggered when SSE sequence gap detected or manually invoked.

Trigger:

await registry.resync()

Use case: Recovery from missed SSE messages

Transport & Communication¶

SSE (Server-Sent Events)¶

A unidirectional push protocol from server to client for real-time directive delivery.

Endpoint: /api/events (default)

Configuration:

const registry = createRegistry({
  sse: {
    url: '/api/events',
    audience: 'global',
    withCredentials: true
  }
})

See: Core API Reference | Devtools SSE Panel

Pull Path¶

Directives returned directly in a mutation response for immediate local updates.

Example:

const res = await fetch('/api/todos/42', { method: 'PUT', ... })
const { directives } = await res.json()
await registry.applyDirectives(directives)

See: Directive Transport

Push Path¶

Directives emitted over SSE for fan-out to other clients/tabs/devices.

Server:

emit_directives(directives, audience='global')

Client: Automatically applies directives (if source doesn't match)

See: Directive Transport

Framework Integration¶

Adapter¶

A thin bridge between Verity's core registry and a UI framework (Alpine, React, Vue, Svelte). Adapters expose framework-idiomatic APIs.

Available Adapters: - Alpine.js: $verity magic - React: useVerityCollection(), useVerityItem() - Vue 3: useVerityCollection(), useVerityItem() - Svelte: collectionStore(), itemStore()

See: Framework Adapters Reference

Handle¶

A reactive reference to cached data with state, methods, and metadata.

Collection Handle:

{
  state: {
    loading: boolean
    error: Error | null
    items: any[]
    meta: any
  }
  refresh(): Promise<void>
  setParams(params: any): void
  remove(): void
}

Item Handle:

{
  state: {
    loading: boolean
    error: Error | null
    value: any | null
  }
  refresh(): Promise<void>
  remove(): void
}

UX Patterns¶

Skeleton¶

A placeholder UI shown when data doesn't exist yet (first load, before any fetch completes).

Usage:

<template x-if="!state.items">
  <div class="skeleton"></div>
</template>

Philosophy: Honest indicator that data isn't available yet

See: UX Patterns

Spinner¶

An activity indicator shown while a fetch is in progress.

Usage:

<template x-if="state.loading">
  <div class="spinner"></div>
</template>

Philosophy: Honest indicator that work is happening

See: UX Patterns

Optimistic Update¶

A local speculation about server response before confirmation. Verity explicitly avoids this pattern in favor of server-truth.

Why avoid: - Creates temporary lies - Can mismatch server reality - Causes flicker on rollback - Breaks trust

Alternative: Build fast endpoints that return truth quickly

See: Philosophy

Development & Debugging¶

Devtools¶

A visual debugging overlay that shows live truth-state, events, directives, and SSE status.

Installation:

<link rel="stylesheet" href=".../devtools.css">
<script src=".../devtools.js"></script>

Toggle: Ctrl+Shift+D (or Cmd+Shift+D on Mac)

Panels: - Truth: Live cache snapshot - Events: Timeline of fetch/directive/SSE events - SSE: Connection status and messages - Config: Registry settings

See: Devtools Reference

Client ID¶

A unique identifier for a Verity registry instance, used for directive source tracking.

Access:

console.log(registry.clientId)  // "client-abc123xyz"

Usage: Include in mutation headers to tag directives

Architecture Terms¶

Backend of the Frontend¶

Verity's positioning as the data layer that sits between the server (backend) and the view layer (frontend). It handles concerns traditionally split between them.

Responsibilities: - Fetching (traditionally view layer concern) - Caching (traditionally backend concern) - Invalidation (traditionally app-defined glue) - Real-time sync (traditionally complex infrastructure)

See: Architecture

Latest-Wins¶

A concurrency guarantee that prevents stale network responses from clobbering newer state.

Example: 1. Request A starts for todo:42 2. Request B starts for todo:42 (newer) 3. Request B completes → cache updated 4. Request A completes (stale) → cache NOT updated

See: Concurrency Model

Protocol-Agnostic¶

Verity's design principle of not being tied to any specific transport (REST, GraphQL, gRPC, WebSocket, etc.).

Fetchers: Any async function that returns data
Directives: Transport via SSE, WebSocket, GraphQL subscriptions, polling, etc.

See: Philosophy

Framework-Agnostic¶

Verity's design principle of not being tied to any specific UI framework.

Core: Pure JavaScript, no framework dependencies
Adapters: Thin bridges to Alpine, React, Vue, Svelte

See: Philosophy

Terms by Category¶

State Management¶

Truth-State
View-State
Collection
Item / Type
Level
Staleness
Cache Key

Directives¶

Directive
Directive Source
Idempotency Key
Audience
Sequence Number
Pull Path
Push Path

Architecture¶

Registry
Backend of the Frontend
Latest-Wins
Protocol-Agnostic
Framework-Agnostic
Coalescing

Framework Integration¶

Adapter
Handle

UX¶

Skeleton
Spinner
Optimistic Update (anti-pattern)

Development¶

Devtools
Client ID
Resync

Quick Reference¶

If you want to...	Look for...
Understand core philosophy	Truth-State, View-State, Backend of the Frontend
Set up data fetching	Registry, Collection, Item/Type
Handle server updates	Directive, Pull Path, Push Path
Optimize performance	Coalescing, Level, Level Conversion, Staleness
Debug issues	Devtools, Resync, Client ID
Build UI	Adapter, Handle, Skeleton, Spinner
Scale to many clients	SSE, Audience, Sequence Number

Glossary¶

Core Concepts¶

Truth-State¶

View-State¶

Registry¶

Directive¶

Data Types¶

Collection¶

Item / Type¶

Level¶

Level Conversion¶

Cache & Staleness¶

Staleness¶

Cache Key¶

Coalescing¶

Directives & Invalidation¶

Directive Source¶

Idempotency Key¶

Audience¶

Sequence Number (seq)¶

Resync¶

Transport & Communication¶

SSE (Server-Sent Events)¶

Pull Path¶

Push Path¶

Framework Integration¶

Adapter¶

Handle¶

UX Patterns¶

Skeleton¶

Spinner¶

Optimistic Update¶

Development & Debugging¶

Devtools¶

Client ID¶

Architecture Terms¶

Backend of the Frontend¶

Latest-Wins¶

Protocol-Agnostic¶

Framework-Agnostic¶

Terms by Category¶

State Management¶

Directives¶

Architecture¶

Framework Integration¶

UX¶

Development¶

Quick Reference¶

See Also¶