@abloatai/ablo 0.26.0 → 0.28.0

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?: 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;

package/dist/types/index.js

@@ -1,12 +1,12 @@
 /**
- * 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.
  */
 /**
- * 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 var ModelScope;
 (function (ModelScope) {
@@ -15,45 +15,45 @@ export var ModelScope;
     ModelScope["all"] = "all";
 })(ModelScope || (ModelScope = {}));
 /**
- * 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 var PropertyType;
 (function (PropertyType) {
-    /** Standard observable property - owned by model, persisted and synced */
+    /** A standard observable field owned by the model, both persisted and synced. */
     PropertyType["property"] = "property";
-    /** Property that doesn't persist or sync - runtime only */
+    /** A runtime-only field that is neither persisted nor synced. */
     PropertyType["ephemeralProperty"] = "ephemeralProperty";
-    /** Foreign key reference - stores ID only */
+    /** A foreign-key reference that stores only the related model's id. */
     PropertyType["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. */
     PropertyType["referenceModel"] = "referenceModel";
-    /** Collection of related models - one-to-many relationship */
+    /** A collection of related models — the many side of a one-to-many relationship. */
     PropertyType["referenceCollection"] = "referenceCollection";
-    /** Back-reference computed property - inverse relationship */
+    /** A computed field that follows a relationship in the inverse direction. */
     PropertyType["backReference"] = "backReference";
-    /** Array of foreign key references - many-to-many relationship */
+    /** An array of foreign-key ids — a many-to-many relationship. */
     PropertyType["referenceArray"] = "referenceArray";
 })(PropertyType || (PropertyType = {}));
 /**
- * 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 var LoadStrategy;
 (function (LoadStrategy) {
-    /** Load immediately into ObjectPool during bootstrap - for critical models */
+    /** Loaded during startup, before it is first used — for models needed right away. */
     LoadStrategy["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. */
     LoadStrategy["lazy"] = "lazy";
-    /** Load on demand in subsets - for large collections */
+    /** Loaded on demand in subsets — for large collections. */
     LoadStrategy["partial"] = "partial";
-    /** Only load when explicitly requested - for optional data */
+    /** Loaded only when the application asks for it — for optional data. */
     LoadStrategy["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. */
     LoadStrategy["local"] = "local";
 })(LoadStrategy || (LoadStrategy = {}));
 /**
- * Mutation operation types for batch mutations.
+ * The operation a batch mutation performs on a model row.
  */
 export var MutationOperationType;
 (function (MutationOperationType) {

package/dist/types/modelData.d.ts

@@ -1,12 +1,10 @@
 /**
- * ModelData — the generic record shape for model payloads.
+ * The generic record shape for a model's data — a map from field name to value.
  *
- * Lives in its own dependency-free leaf so BOTH `BaseSyncedStore` and
- * `SyncClient` can import it without importing each other. (The alias
- * used to live in BaseSyncedStore.ts, which made SyncClient.ts and
- * BaseSyncedStore.ts a mutual type cycle: the store needs the SyncClient
- * class type, and SyncClient needed this alias back from the store.)
- * `BaseSyncedStore` re-exports it, so existing importers are unchanged.
+ * Because the values are typed as `unknown`, read the data as the
+ * schema-inferred entity type rather than accessing fields off this shape
+ * directly. It has no imports of its own, so any module can depend on it
+ * without creating an import cycle.
  */
-/** Generic record type for model data */
+/** A record mapping each model field name to its value. */
 export type ModelData = Record<string, unknown>;

package/dist/types/modelData.js

@@ -1,11 +1,9 @@
 /**
- * ModelData — the generic record shape for model payloads.
+ * The generic record shape for a model's data — a map from field name to value.
  *
- * Lives in its own dependency-free leaf so BOTH `BaseSyncedStore` and
- * `SyncClient` can import it without importing each other. (The alias
- * used to live in BaseSyncedStore.ts, which made SyncClient.ts and
- * BaseSyncedStore.ts a mutual type cycle: the store needs the SyncClient
- * class type, and SyncClient needed this alias back from the store.)
- * `BaseSyncedStore` re-exports it, so existing importers are unchanged.
+ * Because the values are typed as `unknown`, read the data as the
+ * schema-inferred entity type rather than accessing fields off this shape
+ * directly. It has no imports of its own, so any module can depend on it
+ * without creating an import cycle.
  */
 export {};

package/dist/types/participant.d.ts

@@ -1,19 +1,18 @@
 /**
- * Participant identity — a zero-import leaf of the type graph.
+ * The identity of a participant — a person's session, an AI agent, or a system
+ * actor — in the coordination protocol.
  *
- * `ParticipantRef` (and the participant-kind literals it carries) is the one
- * identity shape shared by the streams surface (`types/streams.ts`) and the
- * conflict-policy layer (`policy/types.ts`). It lives in its own leaf module —
- * importing nothing — so both layers can depend on it without forming the
- * foundation triangle `types/streams → schema/model → policy/types →
- * types/streams`. The runtime validator for the same literals stays in
- * `coordination/schema.ts` (`participantKindSchema`).
+ * {@link ParticipantRef} is the single identity shape shared by the streams
+ * types and the conflict-policy types. It has no imports of its own, so both
+ * can depend on it without creating an import cycle. The runtime validator for
+ * the same participant kinds lives alongside the other coordination schemas.
  */
-/** The participant-kind vocabulary: human session, AI agent, or system actor. */
+/** The kind of actor a participant is: a human session, an AI agent, or a system actor. */
 export type ParticipantKind = 'user' | 'agent' | 'system';
 /**
- * Identity reference for an actor / on-behalf-of slot. Generic
- * protocol vocabulary; works for sessions, agents, and system roles.
+ * A reference to one participant: its {@link ParticipantKind} and its id. Used
+ * both for the actor performing an action and for the participant it acts on
+ * behalf of.
  */
 export interface ParticipantRef {
     kind: ParticipantKind;

package/dist/types/participant.js

@@ -1,12 +1,10 @@
 /**
- * Participant identity — a zero-import leaf of the type graph.
+ * The identity of a participant — a person's session, an AI agent, or a system
+ * actor — in the coordination protocol.
  *
- * `ParticipantRef` (and the participant-kind literals it carries) is the one
- * identity shape shared by the streams surface (`types/streams.ts`) and the
- * conflict-policy layer (`policy/types.ts`). It lives in its own leaf module —
- * importing nothing — so both layers can depend on it without forming the
- * foundation triangle `types/streams → schema/model → policy/types →
- * types/streams`. The runtime validator for the same literals stays in
- * `coordination/schema.ts` (`participantKindSchema`).
+ * {@link ParticipantRef} is the single identity shape shared by the streams
+ * types and the conflict-policy types. It has no imports of its own, so both
+ * can depend on it without creating an import cycle. The runtime validator for
+ * the same participant kinds lives alongside the other coordination schemas.
  */
 export {};