@abloatai/ablo 0.25.0 → 0.27.0

package/dist/transactions/replayValidation.js

@@ -0,0 +1,111 @@
+/**
+ * The validation boundary for replaying persisted transactions after a restart.
+ *
+ * Rows read back from the on-disk transaction store may have been written by an
+ * earlier run — possibly by an older version of this package, possibly
+ * corrupted. Rather than trust them, the schemas here validate exactly the
+ * fields the transaction queue and the offline-mutation restore read during
+ * replay. A row that fails to parse is dropped and reported, never replayed as
+ * a malformed commit.
+ *
+ * The same store also holds two kinds of rows that are not replayable
+ * transactions — the offline mutation queue (`type: 'queue'`) and delta-await
+ * markers (`type: 'awaiting_delta'`), each owned by another part of the client.
+ * {@link isNonReplayablePersistedRow} recognizes them so they are skipped
+ * quietly rather than flagged as corruption.
+ */
+import { z } from 'zod';
+import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
+/** The subset of a write's options that is stored with each transaction or queued mutation. */
+const persistedWriteOptionsSchema = z
+    .object({
+    readAt: z.number().nullable().optional(),
+    onStale: z.enum(['reject', 'overwrite', 'notify']).nullable().optional(),
+    idempotencyKey: z.string().optional(),
+    label: z.string().optional(),
+})
+    .loose();
+/**
+ * The shape of a persisted transaction that can be replayed: the fields the
+ * transaction queue reads when it re-enqueues the row — its id, operation type,
+ * model addressing, payload, and identity context. Any remaining bookkeeping is
+ * filled in with defaults when the row is rehydrated by
+ * {@link deserializePersistedTransaction}.
+ */
+export const persistedTransactionSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.enum(['create', 'update', 'delete', 'archive', 'unarchive']),
+    modelName: z.string().min(1),
+    modelId: z.string().min(1),
+    modelKey: z.string().min(1).optional(),
+    data: z.record(z.string(), z.unknown()).optional(),
+    previousData: z.record(z.string(), z.unknown()).nullable().optional(),
+    context: z.object({
+        userId: z.string().min(1),
+        organizationId: z.string().min(1),
+        role: z.string().optional(),
+        teamIds: z.array(z.string()).optional(),
+    }),
+    createdAt: z.number().optional(),
+    batchId: z.string().optional(),
+    writeOptions: persistedWriteOptionsSchema.optional(),
+    localOnly: z.boolean().optional(),
+})
+    .loose();
+/** The `type` values of stored rows that belong to other parts of the client and are not replayable transactions. */
+const NON_REPLAYABLE_TYPES = new Set(['queue', 'awaiting_delta']);
+/**
+ * Reports whether a stored row is one of the non-transaction kinds, so callers
+ * skip it instead of treating it as a corrupt transaction.
+ */
+export function isNonReplayablePersistedRow(row) {
+    return (typeof row === 'object' &&
+        row !== null &&
+        typeof row.type === 'string' &&
+        NON_REPLAYABLE_TYPES.has(row.type));
+}
+/**
+ * Validates one stored row and rehydrates it into a {@link Transaction} ready
+ * to replay, or returns `null` when the row fails validation. Bookkeeping
+ * fields the stored row lacks — status, attempts, priority, timestamp — are
+ * re-derived the same way a freshly staged transaction derives them.
+ */
+export function deserializePersistedTransaction(row) {
+    const parsed = persistedTransactionSchema.safeParse(row);
+    if (!parsed.success)
+        return null;
+    const tx = parsed.data;
+    return {
+        id: tx.id,
+        type: tx.type,
+        modelName: tx.modelName,
+        modelId: tx.modelId,
+        modelKey: tx.modelKey ?? normalizeModelKey(tx.modelName),
+        ...(tx.data !== undefined ? { data: tx.data } : {}),
+        ...(tx.previousData !== undefined ? { previousData: tx.previousData } : {}),
+        context: tx.context,
+        status: 'pending',
+        createdAt: tx.createdAt ?? Date.now(),
+        attempts: 0,
+        priority: 'normal',
+        priorityScore: computePriorityScore(tx.type, tx.modelName),
+        ...(tx.batchId !== undefined ? { batchId: tx.batchId } : {}),
+        ...(tx.writeOptions !== undefined ? { writeOptions: tx.writeOptions } : {}),
+        ...(tx.localOnly !== undefined ? { localOnly: tx.localOnly } : {}),
+    };
+}
+/**
+ * The shape of one entry in the persisted offline mutation queue — an item of
+ * the `'queue'` row's `mutations` array, carrying the fields read when the
+ * queue is restored on reconnect.
+ */
+export const persistedMutationSchema = z
+    .object({
+    type: z.enum(['create', 'update', 'delete', 'archive']),
+    modelData: z.record(z.string(), z.unknown()),
+    modelName: z.string().min(1),
+    timestamp: z.string(),
+    writeOptions: persistedWriteOptionsSchema.optional(),
+})
+    .loose();

package/dist/types/global.d.ts

@@ -1,23 +1,24 @@
 /**
- * Type registration point for SDK consumers.
+ * The single place where you tell the SDK about your application's types.
  *
- * A consumer registers their Schema, Presence, Claims, and UserMeta ONCE by
- * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from the
- * resolved registration. No generics at call sites, no `schema` arg per call.
+ * You register your Schema, Presence, Claims, and UserMeta once by augmenting
+ * the {@link Register} interface. From then on every SDK hook — `useAblo`,
+ * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from that
+ * registration, so you never pass a generic or a `schema` argument at a call
+ * site.
  *
- * Registration is done via **module augmentation** of `@abloatai/ablo` —
- * the same pattern TanStack Router uses for its `Register` interface. The brand
- * lives in the module specifier, so the interface is just `Register` (not a
- * global, not prefixed). It's a language feature, not a library trick: any file
- * in the compilation can augment it and every resolver below picks it up.
+ * Registration uses TypeScript module augmentation: any file in your project
+ * can add an `interface Register` to a `declare module '@abloatai/ablo'`
+ * block, and every resolver below picks it up. Because the name is scoped to
+ * this module, the interface is simply `Register` — not a global and not
+ * prefixed.
  *
- * Consumer example (`npx ablo init` scaffolds this as `ablo/register.ts`, a
- * sibling of `ablo/schema.ts`). It's a regular `.ts` module, NOT a hand-authored
- * `.d.ts`: the top-level `import type { schema }` makes the `declare module`
- * block MERGE (augment) this interface rather than collide with it — the same
- * shape TanStack Router uses in `src/router.tsx`. Any `.ts` file in the
- * `tsconfig` `include` works; it never needs to be imported.
+ * The `npx ablo init` command scaffolds this file as `ablo/register.ts`, next
+ * to `ablo/schema.ts`. Write it as a normal `.ts` module, not a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` is what makes the
+ * `declare module` block merge into this interface rather than collide with it.
+ * Any `.ts` file covered by your `tsconfig` works, and it never needs to be
+ * imported anywhere.
  *
  * ```ts
  * // ablo/register.ts
@@ -34,15 +35,15 @@
  * export {};
  * ```
  *
- * If `Register` is never augmented, every resolver falls back to
- * {@link DefaultSyncShape} — a loose shape that keeps consumers compiling
- * without typed benefits until they opt in.
+ * When `Register` is never augmented, every resolver falls back to
+ * {@link DefaultSyncShape} — a loose shape that keeps your code compiling
+ * without typed results until you opt in.
  */
 /**
- * Default fallback shapes used when the consumer hasn't augmented
- * {@link Register}. `DefaultSyncShape.Schema` is intentionally structural — it
- * carries `{ models: Record<string, unknown> }` so hooks can still validate the
- * model key argument against *something*, just without a typed entity shape.
+ * The fallback shapes the resolvers use when {@link Register} has not been
+ * augmented. `DefaultSyncShape.Schema` is deliberately structural — it carries
+ * `{ models: Record<string, unknown> }` so hooks can still check a model-key
+ * argument against something, just without a typed entity shape behind it.
  */
 export interface DefaultSyncShape {
     readonly Schema: {
@@ -55,20 +56,21 @@ export interface DefaultSyncShape {
     };
 }
 /**
- * The registration interface. Consumers augment it via
- * `declare module '@abloatai/ablo' { interface Register { Schema: ...; … } }`.
- * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
- * when an expected key is absent. Exported from the package root so the module
- * augmentation merges into this declaration.
+ * The registration interface you augment to declare your application's types.
+ * Add keys inside a `declare module '@abloatai/ablo'` block — for example
+ * `interface Register { Schema: ...; Presence: ...; }`. It is empty by default,
+ * so any key you omit falls back to {@link DefaultSyncShape}. It is exported
+ * from the package root so your augmentation merges into this declaration.
  *
- * The `Schema` augmentation key holds the type produced by `defineSchema`, so
- * the same noun reads consistently here and in {@link ResolveSchema}.
+ * The `Schema` key holds the type returned by `defineSchema`, and
+ * {@link ResolveSchema} reads it back out.
  */
 export interface Register {
 }
 /**
- * The consumer's schema, or the default shape if unregistered. Hooks use this
- * to type their model-key argument and infer the entity type returned.
+ * Your registered schema, or the default shape when none is registered. Hooks
+ * read this to type their model-key argument and to infer the entity type they
+ * return.
  */
 export type ResolveSchema = Register extends {
     Schema: infer S;
@@ -76,30 +78,33 @@ export type ResolveSchema = Register extends {
     models: Record<string, unknown>;
 } ? S : DefaultSyncShape['Schema'] : DefaultSyncShape['Schema'];
 /**
- * The consumer's presence shape, or the default if unregistered. Used by
- * `usePresence`. Free-form — any serializable JSON broadcast per session.
+ * Your registered presence shape, or the default when none is registered.
+ * `usePresence` reads it. The shape is free-form — any JSON-serializable value
+ * you broadcast per session.
  */
 export type ResolvePresence = Register extends {
     Presence: infer P;
 } ? P : DefaultSyncShape['Presence'];
 /**
- * The consumer's claim vocabulary, or the default if unregistered. Keys are
- * claim names; values are the claim payload for each claim. Used by
- * `useClaim(claimName)`.
+ * Your registered claim vocabulary, or the default when none is registered.
+ * Each key is a claim name and its value is that claim's payload.
+ * `useClaim(claimName)` reads it.
  */
 export type ResolveClaims = Register extends {
     Claims: infer I;
 } ? I : DefaultSyncShape['Claims'];
 /**
- * The consumer's user-metadata shape, or the default if unregistered. Carries
- * identity info the consumer trusts from their auth layer — not SDK-validated.
+ * Your registered user-metadata shape, or the default when none is registered.
+ * It carries identity information you trust from your own auth layer; the SDK
+ * does not validate it.
  */
 export type ResolveUserMeta = Register extends {
     UserMeta: infer U;
 } ? U : DefaultSyncShape['UserMeta'];
 /**
- * The keys of the consumer's schema models. `useQuery(modelKey)` narrows its
- * first argument to this union, so unknown key literals fail at compile time.
+ * The union of your schema's model names. `useQuery(modelKey)` narrows its
+ * first argument to this union, so a misspelled or unknown model name fails at
+ * compile time.
  */
 export type ResolveModelKey = ResolveSchema extends {
     models: infer M;

package/dist/types/global.js

@@ -1,23 +1,24 @@
 /**
- * Type registration point for SDK consumers.
+ * The single place where you tell the SDK about your application's types.
  *
- * A consumer registers their Schema, Presence, Claims, and UserMeta ONCE by
- * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from the
- * resolved registration. No generics at call sites, no `schema` arg per call.
+ * You register your Schema, Presence, Claims, and UserMeta once by augmenting
+ * the {@link Register} interface. From then on every SDK hook — `useAblo`,
+ * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from that
+ * registration, so you never pass a generic or a `schema` argument at a call
+ * site.
  *
- * Registration is done via **module augmentation** of `@abloatai/ablo` —
- * the same pattern TanStack Router uses for its `Register` interface. The brand
- * lives in the module specifier, so the interface is just `Register` (not a
- * global, not prefixed). It's a language feature, not a library trick: any file
- * in the compilation can augment it and every resolver below picks it up.
+ * Registration uses TypeScript module augmentation: any file in your project
+ * can add an `interface Register` to a `declare module '@abloatai/ablo'`
+ * block, and every resolver below picks it up. Because the name is scoped to
+ * this module, the interface is simply `Register` — not a global and not
+ * prefixed.
  *
- * Consumer example (`npx ablo init` scaffolds this as `ablo/register.ts`, a
- * sibling of `ablo/schema.ts`). It's a regular `.ts` module, NOT a hand-authored
- * `.d.ts`: the top-level `import type { schema }` makes the `declare module`
- * block MERGE (augment) this interface rather than collide with it — the same
- * shape TanStack Router uses in `src/router.tsx`. Any `.ts` file in the
- * `tsconfig` `include` works; it never needs to be imported.
+ * The `npx ablo init` command scaffolds this file as `ablo/register.ts`, next
+ * to `ablo/schema.ts`. Write it as a normal `.ts` module, not a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` is what makes the
+ * `declare module` block merge into this interface rather than collide with it.
+ * Any `.ts` file covered by your `tsconfig` works, and it never needs to be
+ * imported anywhere.
  *
  * ```ts
  * // ablo/register.ts
@@ -34,8 +35,8 @@
  * export {};
  * ```
  *
- * If `Register` is never augmented, every resolver falls back to
- * {@link DefaultSyncShape} — a loose shape that keeps consumers compiling
- * without typed benefits until they opt in.
+ * When `Register` is never augmented, every resolver falls back to
+ * {@link DefaultSyncShape} — a loose shape that keeps your code compiling
+ * without typed results until you opt in.
  */
 export {};

package/dist/types/index.d.ts

@@ -1,13 +1,13 @@
 /**
- * Linear Sync Engine - Core Types
+ * Core type definitions for the model-driven sync layer.
  *
- * Foundational type definitions for the model-driven sync architecture.
- * These types define how properties are tracked, loaded, and synchronized.
+ * These types describe how a model's properties are declared, when their data
+ * is loaded, and how changes are represented on the wire as they synchronize.
  */
 import type { FieldMeta } from '../schema/field.js';
 /**
- * Model Scope - lifecycle filter for queries.
- * Controls whether live, archived, or all entities are returned.
+ * A lifecycle filter for queries: whether to return live entities, archived
+ * ones, or both.
  */
 export declare enum ModelScope {
     live = "live",
@@ -15,43 +15,43 @@ export declare enum ModelScope {
     all = "all"
 }
 /**
- * Property Types - EXACTLY 7 types as per Linear Sync Engine
- * These define how model properties behave in the sync system
+ * The kinds of property a model can declare. Each kind determines how the
+ * property behaves in the sync system — whether it is persisted, how it relates
+ * to other models, and how it is loaded.
  */
 export declare enum PropertyType {
-    /** Standard observable property - owned by model, persisted and synced */
+    /** A standard observable field owned by the model, both persisted and synced. */
     property = "property",
-    /** Property that doesn't persist or sync - runtime only */
+    /** A runtime-only field that is neither persisted nor synced. */
     ephemeralProperty = "ephemeralProperty",
-    /** Foreign key reference - stores ID only */
+    /** A foreign-key reference that stores only the related model's id. */
     reference = "reference",
-    /** Lazy-loaded model reference - getter/setter for model based on ID */
+    /** A single related model resolved on demand from its id, exposed as a getter and setter. */
     referenceModel = "referenceModel",
-    /** Collection of related models - one-to-many relationship */
+    /** A collection of related models — the many side of a one-to-many relationship. */
     referenceCollection = "referenceCollection",
-    /** Back-reference computed property - inverse relationship */
+    /** A computed field that follows a relationship in the inverse direction. */
     backReference = "backReference",
-    /** Array of foreign key references - many-to-many relationship */
+    /** An array of foreign-key ids — a many-to-many relationship. */
     referenceArray = "referenceArray"
 }
 /**
- * Load Strategies - EXACTLY 5 strategies as per Linear Sync Engine
- * Controls when and how model data is loaded from the server
+ * When and how a model's data is loaded from the server.
  */
 export declare enum LoadStrategy {
-    /** Load immediately into ObjectPool during bootstrap - for critical models */
+    /** Loaded during startup, before it is first used — for models needed right away. */
     instant = "instant",
-    /** Load all at once when first needed - for secondary models */
+    /** Loaded all at once the first time it is needed — for secondary models. */
     lazy = "lazy",
-    /** Load on demand in subsets - for large collections */
+    /** Loaded on demand in subsets — for large collections. */
     partial = "partial",
-    /** Only load when explicitly requested - for optional data */
+    /** Loaded only when the application asks for it — for optional data. */
     explicitlyRequested = "explicitlyRequested",
-    /** Never sync with server, local only - for client-side state */
+    /** Never synced with the server; kept only on the client — for local-only state. */
     local = "local"
 }
 /**
- * Property Metadata - Configuration for decorated properties
+ * The resolved configuration for a single model property.
  */
 export interface PropertyMetadata {
     type: PropertyType;
@@ -61,31 +61,32 @@ export interface PropertyMetadata {
     defaultValue?: unknown;
     loadStrategy?: LoadStrategy;
     /**
-     * MobX observability annotation for this property. Controls how deeply
-     * MobX wraps the value when `M1` registers the model.
+     * How deeply the reactivity layer wraps this property's value when the model
+     * is registered. The engine uses MobX, so the choice maps directly to MobX's
+     * observability modes.
      *
-     * - `'deep'` (default): full recursive observability. Every nested
-     *   object/array becomes its own atom. Correct for scalar fields and
-     *   small structured values where consumers subscribe to inner
-     *   properties.
-     * - `'shallow'`: track the reference and array/map/set operations, but
-     *   do NOT recurse into element internals. Right for collections whose
+     * - `'deep'` (the default): full recursive observability, where every nested
+     *   object or array becomes its own reactive node. Correct for scalar fields
+     *   and small structured values whose inner properties are read directly.
+     * - `'shallow'`: track the reference and array, map, and set operations, but
+     *   do not recurse into element internals. Right for collections whose
      *   elements are replaced wholesale.
-     * - `'ref'`: track ONLY reassignment. Right for opaque JSON blobs
-     *   (chart specs, ProseMirror docs, style maps) that are treated as
-     *   immutable values — consumers always read the whole blob and pass
-     *   it to a renderer. Deep enhancement on these produces a microtask
-     *   storm with no benefit.
+     * - `'ref'`: track only reassignment of the value. Right for opaque JSON
+     *   blobs — chart specs, rich-text documents, style maps — that are treated
+     *   as immutable values and always read whole before being handed to a
+     *   renderer. Deep-wrapping these produces many needless reactions for no
+     *   benefit.
      *
-     * Schema-driven registration auto-sets this to `'ref'` for fields with
-     * wire type `'json'`, which is the right default for the blob pattern.
+     * Schema-driven registration sets this to `'ref'` automatically for fields
+     * whose wire type is `'json'`, the right default for the blob pattern.
      */
     observability?: 'deep' | 'shallow' | 'ref';
 }
-/** Model constructor type for reference metadata */
+/** The constructor type of a model class, used by reference metadata to point at the related model. */
 type ModelConstructor = abstract new (...args: never[]) => unknown;
 /**
- * Reference Metadata - Configuration for reference properties
+ * The configuration for a reference property — which model it points to and how
+ * the relationship behaves.
  */
 export interface ReferenceMetadata {
     referencedModel: () => ModelConstructor;
@@ -94,7 +95,7 @@ export interface ReferenceMetadata {
     nullable?: boolean;
 }
 /**
- * Model Metadata - Configuration for model classes
+ * The resolved configuration for a model class.
  */
 export interface ModelMetadata {
     loadStrategy: LoadStrategy;
@@ -104,45 +105,35 @@ export interface ModelMetadata {
     usedForPartialIndexes?: boolean;
     schemaVersion?: number;
     /**
-     * Schema-declared fields for this model, keyed by field name. Drives
-     * commit payload projection (filter to declared fields + stringify
-     * JSON-typed values) inside the transaction queue.
+     * The schema-declared fields for this model, keyed by field name. When a
+     * change is committed, the transaction queue uses this to project the payload
+     * down to the declared fields and to serialize JSON-typed values.
      *
-     * Populated by `registerModelsFromSchema`. Each entry carries the
-     * sync-engine type tag (the canonical {@link FieldMeta.type} union),
-     * which tells the wire serializer how to handle the value. Missing →
-     * projection becomes identity pass-through (back-compat for models
-     * registered outside the schema path).
-     *
-     * Narrowed to the canonical union via `Pick` rather than re-declared —
-     * a hand-rolled copy silently drifts when a new field type lands.
+     * Each entry carries the field's {@link FieldMeta.type} tag, which tells the
+     * wire serializer how to encode the value. When this is absent — a model
+     * registered without a schema — the payload is passed through unchanged.
      */
     fields?: Readonly<Record<string, Pick<FieldMeta, 'type'>>>;
     /**
-     * Fields to back-fill from the sync client identity when missing
-     * during IndexedDB self-healing. Populated from
-     * `ModelOptions.autoFill` in the schema. Each entry maps a field on
-     * this model to one of the identity values held by `SyncClient`
-     * (`organizationId` or `userId`).
-     *
-     * Used by `SyncClient.healModelRecord` to keep the engine
-     * product-neutral: the engine no longer hardcodes which models carry
-     * `organizationId` / `createdBy` — the consumer's schema declares it.
+     * Fields to fill in from the signed-in identity when they are missing from a
+     * stored row during self-healing. Each entry maps a field on this model to
+     * one of the identity values the client holds — `organizationId` or `userId`.
+     * Declaring it in the schema keeps the engine product-neutral: it does not
+     * assume which models carry an organization or owner field.
      */
-    autoFill?: ReadonlyArray<{
+    autoFill?: readonly {
         field: string;
         from: 'organizationId' | 'userId';
-    }>;
+    }[];
     /**
-     * Fields whose absence makes a stored row orphaned. When healing
-     * encounters a record missing any of these fields, it returns `null`
-     * to signal the caller to skip the row. Populated from
-     * `ModelOptions.requiredFields` in the schema.
+     * Fields a stored row must have to be usable. During self-healing, a row
+     * missing any of these is treated as orphaned and skipped rather than loaded.
      */
     requiredFields?: readonly string[];
 }
 /**
- * Model Options - Options for @ClientModel decorator
+ * The options accepted when declaring a model — its load strategy, optional
+ * sync group, and optional table name.
  */
 export interface ModelOptions {
     loadStrategy: LoadStrategy;
@@ -150,7 +141,7 @@ export interface ModelOptions {
     tableName?: string;
 }
 /**
- * Property Options - Options for @Property decorator
+ * The options accepted when declaring a model property.
  */
 export interface PropertyOptions {
     indexed?: boolean;
@@ -159,21 +150,22 @@ export interface PropertyOptions {
     ephemeral?: boolean;
 }
 /**
- * Reference Options - Options for @Reference decorator
+ * The options accepted when declaring a reference property.
  */
 export interface ReferenceOptions {
     indexed?: boolean;
     nullable?: boolean;
 }
 /**
- * GraphQL Mutation Interface
+ * A GraphQL mutation: its query text and the variables to run it with.
  */
 export interface GraphQLMutation {
     mutationText: string;
     variables: Record<string, unknown>;
 }
 /**
- * Load Request Interface
+ * A request to load model rows by an indexed key. When the load completes,
+ * `resolve` is called with the matching rows.
  */
 export interface LoadRequest {
     modelName: string;
@@ -182,11 +174,11 @@ export interface LoadRequest {
     resolve?: (value: unknown[]) => void;
 }
 /**
- * Sync Action Types - Complete Linear specification
+ * The one-letter code identifying what kind of change a sync action carries.
  */
 export type SyncActionType = 'I' | 'U' | 'A' | 'D' | 'C' | 'G' | 'S' | 'V';
 /**
- * Sync Action Interface - Linear format
+ * A single change to one model row, as carried on the sync stream.
  */
 export interface SyncAction {
     id: number;
@@ -197,22 +189,24 @@ export interface SyncAction {
     __class: 'SyncAction';
 }
 /**
- * Delta Packet - Array of sync actions
+ * A batch of sync actions delivered together.
  */
 export type DeltaPacket = SyncAction[];
 /**
- * Bootstrap Types
+ * The kind of initial data load performed when a client starts: a full load, a
+ * partial subset, or local-only.
  */
 export type BootstrapType = 'full' | 'partial' | 'local';
 /**
- * Bootstrap Metadata
+ * The metadata returned with a bootstrap: the last sync id seen and the sync
+ * groups the client is subscribed to.
  */
 export interface BootstrapMetadata {
     lastSyncId: number;
     subscribedSyncGroups: string[];
 }
 /**
- * Database Metadata - Sync engine state tracking
+ * The locally tracked sync state that lets a client resume where it left off.
  */
 export interface DatabaseMetadata {
     lastSyncId: number;
@@ -222,7 +216,7 @@ export interface DatabaseMetadata {
     updatedAt: Date;
 }
 /**
- * Mutation operation types for batch mutations.
+ * The operation a batch mutation performs on a model row.
  */
 export declare enum MutationOperationType {
     ARCHIVE = "ARCHIVE",
@@ -232,7 +226,7 @@ export declare enum MutationOperationType {
     UPDATE = "UPDATE"
 }
 /**
- * Partial Index Information - For complex querying
+ * Describes a partial index used to load subsets of a large model.
  */
 export interface PartialIndexInfo {
     modelName: string;
@@ -240,4 +234,4 @@ export interface PartialIndexInfo {
     depth: number;
     path: string[];
 }
-export * from "./streams.js";
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind, ParticipantRef, JsonValue, ConfirmationState, AgentDelta, Snapshot, ContextChange, ClaimTarget, PresenceTarget, PresenceStream, Activity, Peer, PresenceUpdatePayload, ClaimLeaseOptions, Duration, ClaimOptions, ClaimStream, ClaimLost, ClaimStatus, ClaimWaitOptions, Claim, HeldClaim, } from './streams.js';