@abloatai/ablo 0.35.0 → 0.37.0

package/dist/utils/mobxSetup.js

@@ -1,330 +0,0 @@
-/**
- * Wires a model instance into MobX so its schema-defined fields become
- * observable and its mutations are tracked. This module reads the property
- * metadata generated from a schema and applies the matching MobX annotation to
- * each field, leaving any hand-written getter or setter in place.
- */
-import { observable, makeObservable, action, computed, observe, } from 'mobx';
-import { PropertyType } from '../transaction/types/index.js';
-import { getContext } from '../context.js';
-/**
- * Makes a model instance's schema-defined properties observable with MobX. For
- * each field it reads the {@link PropertyMetadata} and applies the matching MobX
- * annotation — a plain observable for stored values, a computed for derived
- * getters, and an action for mutating methods — while leaving any field that
- * already declares its own getter and setter untouched. If the model provides
- * its own `setupObservability` or sets `_hasCustomObservability`, this function
- * defers to it and does nothing.
- */
-export function M1(target, propertyMetadata, referenceMetadata) {
-    // MobX accepts an annotations map keyed by PropertyKey. We build it
-    // from the runtime metadata, so the keys are strings — not
-    // statically derivable from `keyof T`.
-    const annotations = {};
-    // Helper to check if property has a getter
-    const hasGetter = (propName) => {
-        let obj = target;
-        while (obj) {
-            const descriptor = Object.getOwnPropertyDescriptor(obj, propName);
-            if (descriptor?.get)
-                return true;
-            obj = Object.getPrototypeOf(obj);
-            if (obj === Object.prototype)
-                break;
-        }
-        return false;
-    };
-    // Helper to check if property has a setter
-    const hasSetter = (propName) => {
-        let obj = target;
-        while (obj) {
-            const descriptor = Object.getOwnPropertyDescriptor(obj, propName);
-            if (descriptor?.set)
-                return true;
-            obj = Object.getPrototypeOf(obj);
-            if (obj === Object.prototype)
-                break;
-        }
-        return false;
-    };
-    // Skip if target has its own observability setup
-    // This allows models like Task to handle their own MobX setup
-    if (target.setupObservability || target._hasCustomObservability) {
-        getContext().modelDebugLogger?.logDebug(`${target.constructor.name} has custom observability, skipping M1`);
-        return;
-    }
-    // Process each property based on its type
-    for (const [propName, metadata] of propertyMetadata) {
-        const hasCustomGetter = hasGetter(propName);
-        const hasCustomSetter = hasSetter(propName);
-        // If property has custom getter/setter, respect it
-        if (hasCustomGetter && hasCustomSetter) {
-            // Property is fully managed, skip it
-            continue;
-        }
-        switch (metadata.type) {
-            case PropertyType.property:
-            case PropertyType.ephemeralProperty:
-                if (hasCustomGetter) {
-                    // Has getter but no setter - mark as computed
-                    annotations[propName] = computed;
-                }
-                else {
-                    // Pick the cheapest observability that still captures
-                    // reactivity at the granularity consumers subscribe to. Default
-                    // `observable` is deep, which on JSON-blob fields produces a
-                    // recursive atom tree (catastrophic on chart specs, ProseMirror
-                    // docs, style maps) — see PropertyMetadata.observability docs.
-                    switch (metadata.observability) {
-                        case 'ref':
-                            annotations[propName] = observable.ref;
-                            break;
-                        case 'shallow':
-                            annotations[propName] = observable.shallow;
-                            break;
-                        case 'deep':
-                        case undefined:
-                        default:
-                            annotations[propName] = observable;
-                            break;
-                    }
-                }
-                break;
-            case PropertyType.reference:
-                // Foreign key ID property
-                const idPropName = propName.endsWith('Id') ? propName : `${propName}Id`;
-                if (!hasGetter(idPropName) && !hasSetter(idPropName)) {
-                    annotations[idPropName] = observable;
-                }
-                break;
-            case PropertyType.referenceModel:
-                // Computed getter for referenced model
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = computed;
-                }
-                break;
-            case PropertyType.referenceCollection:
-                // Observable collection
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = observable;
-                }
-                break;
-            case PropertyType.backReference:
-                // Computed back-reference
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = computed;
-                }
-                break;
-            case PropertyType.referenceArray:
-                // Observable array of IDs
-                if (!propName.endsWith('Ids')) {
-                    const idsPropName = `${propName}Ids`;
-                    if (!hasGetter(idsPropName) && !hasSetter(idsPropName)) {
-                        annotations[idsPropName] = observable;
-                    }
-                }
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = observable;
-                }
-                break;
-        }
-    }
-    // Add standard model properties only if they don't exist
-    if (!hasGetter('id') && !hasSetter('id')) {
-        annotations.id = observable;
-    }
-    if (!hasGetter('createdAt') && !hasSetter('createdAt')) {
-        annotations.createdAt = observable;
-    }
-    if (!hasGetter('updatedAt') && !hasSetter('updatedAt')) {
-        annotations.updatedAt = observable;
-    }
-    if (!hasGetter('modifiedProperties') && !hasSetter('modifiedProperties')) {
-        // Track map membership, but keep change payloads as plain values. These
-        // entries are replaced rather than mutated and later cross IndexedDB's
-        // structured-clone boundary, where MobX's deep proxies are invalid.
-        annotations.modifiedProperties = observable.shallow;
-    }
-    // Add actions only if methods exist and aren't already actions.
-    // `Reflect.get` keeps the read typed without an index-signature
-    // cast — `target` is `M1Target`, which deliberately doesn't index
-    // by arbitrary string (we don't want to sneak random fields in).
-    const actionMethods = [
-        'propertyChanged',
-        'markAsPersisted',
-        'clearChanges',
-        'consumeModifiedFields',
-        'updateFromData',
-        'applyChanges',
-    ];
-    for (const methodName of actionMethods) {
-        if (typeof Reflect.get(target, methodName) === 'function') {
-            annotations[methodName] = action;
-        }
-    }
-    // Log setup for debugging
-    const modelName = target.constructor.name;
-    const observableProps = Object.keys(annotations).filter((k) => annotations[k] === observable);
-    const computedProps = Object.keys(annotations).filter((k) => annotations[k] === computed);
-    getContext().modelDebugLogger?.logObservableSetup(modelName, observableProps, computedProps);
-    // Merge any extra annotations declared by the model (e.g., computed for query getters)
-    if (target._extraMobxAnnotations && typeof target._extraMobxAnnotations === 'object') {
-        Object.assign(annotations, target._extraMobxAnnotations);
-    }
-    // Apply MobX decorators
-    try {
-        // Only apply if we have annotations to apply
-        if (Object.keys(annotations).length > 0) {
-            makeObservable(target, annotations);
-            // Bridge MobX's observable setter to `propertyChanged()` so a direct
-            // assignment like `layer.position = newPos` still records a change for the
-            // transaction queue, and the update reaches the server. Product code
-            // assigns model properties directly in many places (drag, resize,
-            // formatting, keyboard nudge, AI tools), so those writes must sync.
-            //
-            // `observe()` attaches a post-set listener without replacing MobX's
-            // accessors, so the observable keeps its normal reactivity and we get a
-            // synchronous change event to forward to `propertyChanged()`. Only
-            // persisted fields (`PropertyType.property`) are observed, so ephemeral UI
-            // state and computed or reference fields do not leak into
-            // `modifiedProperties`.
-            //
-            // Construction-time writes (the constructor's initial field
-            // population from wire data) also fire `observe` — so we gate with
-            // `target._isNew` and a transient `_isConstructing` flag: any change
-            // that happens before the model is marked persisted is an initial
-            // hydration, not a user edit.
-            if (!target._hasCustomObservability) {
-                for (const [propName, metadata] of propertyMetadata) {
-                    if (metadata.type !== PropertyType.property)
-                        continue;
-                    // Only entries annotated as `observable` are safe to `observe()`. Do
-                    // not gate on
-                    // `Object.getOwnPropertyDescriptor(target, propName).get/set`:
-                    // `makeObservable(target, annotations)` has already installed its own
-                    // getter/setter by this point, so that descriptor check flags every
-                    // field as custom and silently skips every observer. That mistake left
-                    // `modifiedProperties` empty for dynamic models, so the transaction
-                    // queue found no changes to send and the server acked a no-op
-                    // mutation.
-                    if (!(propName in annotations))
-                        continue;
-                    // Accept any flavor of `observable` (deep, ref, shallow). `observe()`
-                    // works on all three — the listener fires on the property
-                    // reassignment, regardless of how the value is enhanced
-                    // internally. Crucially, this lets `propertyChanged()` (and the
-                    // transaction queue) still see writes to JSON-blob fields
-                    // annotated as `observable.ref`. Gating on the bare `observable`
-                    // constant alone would silently drop those writes — see the
-                    // `input: {}` regression captured in the comment above for the
-                    // same failure mode.
-                    const ann = annotations[propName];
-                    if (ann !== observable && ann !== observable.ref && ann !== observable.shallow)
-                        continue;
-                    try {
-                        // Cross the runtime/static boundary: propName is a string
-                        // from the propertyMetadata Map iteration. At runtime it's
-                        // guaranteed to be a key on `target` (we just wrote the
-                        // annotation entry for it via makeObservable above). The
-                        // cast to `keyof T` reflects that runtime invariant —
-                        // it's not "I don't know," it's "I know but TS can't see
-                        // the proof from here." MobX's IValueDidChange<T[K]>
-                        // gives the change parameter a concrete typed value.
-                        const key = propName;
-                        observe(target, key, (change) => {
-                            // Only track updates, not add/delete. For scalar observables,
-                            // MobX emits `{ type: 'update', oldValue, newValue }`.
-                            if (change.type !== 'update')
-                                return;
-                            // Skip initial hydration writes. `_isNew` stays true until
-                            // the model is `markAsPersisted()`, and the first wave of
-                            // setters runs during construction BEFORE this observer
-                            // would exist (observers are installed now, on this line);
-                            // but defensively still gate, because callers that
-                            // pre-construct models with partial data then bulk-assign
-                            // would otherwise spuriously fill `modifiedProperties`.
-                            if (target._isConstructing)
-                                return;
-                            if (typeof target.propertyChanged === 'function') {
-                                target.propertyChanged(propName, change.oldValue, change.newValue);
-                            }
-                        });
-                    }
-                    catch {
-                        // If a property isn't observable for any reason (e.g. it
-                        // was filtered out by the annotations logic but still shows
-                        // up in metadata), silently skip — propertyChanged tracking
-                        // is best-effort, not a correctness guarantee.
-                    }
-                }
-            }
-        }
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        getContext().modelDebugLogger?.logError(modelName, 'OBSERVABLE_SETUP', errorMessage, {
-            annotations: Object.keys(annotations),
-            target: Object.keys(target),
-        });
-        throw error;
-    }
-}
-/**
- * Wraps a model class so every instance is made observable at construction time
- * by calling {@link M1}. A class that manages its own observability — one whose
- * prototype declares `setupObservability` or `_hasCustomObservability` — is
- * returned unchanged. The wrapper preserves the original class name and its
- * static members.
- */
-export function makeModelObservable(modelClass, propertyMetadata, referenceMetadata) {
-    // Check if class already handles observability
-    if (modelClass.prototype.setupObservability || modelClass.prototype._hasCustomObservability) {
-        return modelClass;
-    }
-    // Create wrapper class
-    const WrappedClass = class extends modelClass {
-        constructor(...args) {
-            super(...args);
-            M1(this, propertyMetadata, referenceMetadata);
-        }
-    };
-    // Preserve class name
-    Object.defineProperty(WrappedClass, 'name', {
-        value: modelClass.name,
-        configurable: true,
-    });
-    // Copy static properties
-    Object.setPrototypeOf(WrappedClass, modelClass);
-    return WrappedClass;
-}
-/**
- * Reports whether a named property is one that {@link M1} makes observable —
- * that is, a stored value, an ephemeral value, a reference collection, or a
- * reference array. Returns `false` for an unknown property and for a computed
- * reference.
- */
-export function isObservableProperty(target, propName, propertyMetadata) {
-    const metadata = propertyMetadata.get(propName);
-    if (!metadata)
-        return false;
-    return [
-        PropertyType.property,
-        PropertyType.ephemeralProperty,
-        PropertyType.referenceCollection,
-        PropertyType.referenceArray,
-    ].includes(metadata.type);
-}
-/**
- * Returns the names of the properties that {@link M1} treats as computed: the
- * referenced-model and back-reference fields derived from a foreign key.
- */
-export function getComputedProperties(propertyMetadata) {
-    const computed = [];
-    for (const [propName, metadata] of propertyMetadata) {
-        if (metadata.type === PropertyType.referenceModel ||
-            metadata.type === PropertyType.backReference) {
-            computed.push(propName);
-        }
-    }
-    return computed;
-}

package/dist/webhooks/events.d.ts

@@ -1,43 +0,0 @@
-/**
- * A webhook event delivered to a customer's endpoint, representing a single
- * committed change to a row. {@link deltaToWebhookEvent} produces it, and the
- * recipient verifies the delivery signature before trusting its contents.
- */
-export interface AbloWebhookEvent {
-    /** A stable, unique event identifier equal to `String(syncId)`. Use it to
-     *  deduplicate deliveries. */
-    readonly id: string;
-    /** The event type, formatted as `<model>.<verb>`, such as `"report.updated"`.
-     *  Branch on this to route the event. */
-    readonly type: string;
-    /** The name of the model whose row changed, such as `"Report"`. */
-    readonly model: string;
-    /** The identifier of the row that changed. */
-    readonly objectId: string;
-    /** The change's position in the transaction log, increasing monotonically.
-     *  Order events by this value. */
-    readonly syncId: number;
-    /** The row as it stands after the change, or `null` when the change was a
-     *  delete. */
-    readonly data: Record<string, unknown> | null;
-    /** The time the change was committed, as an ISO 8601 timestamp. */
-    readonly createdAt: string;
-}
-/** The minimal delta shape {@link deltaToWebhookEvent} reads; a full server-side
- *  delta record satisfies it. */
-export interface WebhookSourceDelta {
-    readonly id: number;
-    readonly actionType: string;
-    readonly modelName: string;
-    readonly modelId: string;
-    /** The row payload: an already-parsed object, a raw JSON string, or `null`. */
-    readonly data: Record<string, unknown> | string | null;
-    readonly createdAt: string;
-}
-/**
- * Converts a committed delta into an {@link AbloWebhookEvent}. Returns `null`
- * when the delta records an internal permission or group change rather than a
- * row-level change, in which case the caller emits no webhook. The mapping is
- * deterministic: the event id and timestamp come directly from the delta.
- */
-export declare function deltaToWebhookEvent(delta: WebhookSourceDelta): AbloWebhookEvent | null;

package/dist/webhooks/events.js

@@ -1,42 +0,0 @@
-/**
- * Maps each delta action code to the verb that appears in an event type. Only
- * the row-level create, update, delete, archive, and unarchive actions produce a
- * webhook. The remaining action codes describe internal permission and
- * visibility changes and are deliberately absent, so {@link deltaToWebhookEvent}
- * returns `null` for them.
- */
-const ACTION_VERB = {
-    I: 'created',
-    U: 'updated',
-    D: 'deleted',
-    A: 'archived',
-    V: 'unarchived',
-};
-function parseRow(data) {
-    if (data == null)
-        return null;
-    if (typeof data === 'string') {
-        return data === '' ? null : JSON.parse(data);
-    }
-    return data;
-}
-/**
- * Converts a committed delta into an {@link AbloWebhookEvent}. Returns `null`
- * when the delta records an internal permission or group change rather than a
- * row-level change, in which case the caller emits no webhook. The mapping is
- * deterministic: the event id and timestamp come directly from the delta.
- */
-export function deltaToWebhookEvent(delta) {
-    const verb = ACTION_VERB[delta.actionType];
-    if (!verb)
-        return null; // an internal permission or group change, not a customer event
-    return {
-        id: String(delta.id),
-        type: `${delta.modelName.toLowerCase()}.${verb}`,
-        model: delta.modelName,
-        objectId: delta.modelId,
-        syncId: delta.id,
-        data: parseRow(delta.data),
-        createdAt: delta.createdAt,
-    };
-}

package/dist/webhooks/index.d.ts

@@ -1,8 +0,0 @@
-/**
- * The public entry point for webhooks. Import {@link AbloWebhookEvent} to type
- * your event handler, and use {@link deltaToWebhookEvent} to turn a committed
- * change from the transaction log into an event to deliver. This module does not
- * verify signatures and ships no cryptography; recipients verify deliveries with
- * a standard webhooks library.
- */
-export { deltaToWebhookEvent, type AbloWebhookEvent, type WebhookSourceDelta, } from './events.js';

package/dist/webhooks/index.js

@@ -1,8 +0,0 @@
-/**
- * The public entry point for webhooks. Import {@link AbloWebhookEvent} to type
- * your event handler, and use {@link deltaToWebhookEvent} to turn a committed
- * change from the transaction log into an event to deliver. This module does not
- * verify signatures and ships no cryptography; recipients verify deliveries with
- * a standard webhooks library.
- */
-export { deltaToWebhookEvent, } from './events.js';

package/dist/wire/index.d.ts

@@ -1 +0,0 @@
-export * from '../transaction/wire/index.js';

package/dist/wire/index.js

@@ -1,8 +0,0 @@
-// Moved to @ablo/transaction (ADR 0013 — the settlement core extraction).
-// This shim re-exports it at the original path so in-package importers of
-// `wire/index.js` keep working; rewire to `@ablo/transaction/wire`
-// and delete this shim once the core package is fully wired.
-//
-// Line comments on purpose: tsc copies a leading JSDoc block into the
-// published `.d.ts`, and this note names a package npm has never heard of.
-export * from '../transaction/wire/index.js';

package/docs/interaction-model.md

@@ -1,99 +0,0 @@
-# Interaction Model
-
-> The one write path every actor shares: load, claim, update, confirm.
-
-When two agents, a server action, and a person can all write to the same row, you
-need one write path that stops them from clobbering each other. Ablo gives you
-exactly one: load the row, claim it while you work, update it, and wait for
-confirmation. This page walks through that path and the few primitives behind it.
-
-Here's the whole path in one block — claim a row, update it inside the claim, and
-let the claim release when your callback returns:
-
-```ts
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-
-await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
-await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' }, wait: 'confirmed' });
-```
-
-Claims don't lock. If another writer holds the row, `claim` waits for them,
-re-reads the fresh row, then hands it to you — so two writers serialize instead
-of clobbering.
-
-## Primitives
-
-| Primitive | Plane | Purpose |
-|---|---|---|
-| `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async reads), `local.retrieve`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
-| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral — never persisted. |
-| `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
-| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
-
-### Why each primitive is separate
-
-Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
-does a job the others can't. If you're coming from Replicache or Yjs you'd
-expect just `Commit`; here's what the other two buy you over that minimum:
-
-- **`Claim` is not a read lock.** Reads stay open. Claims serialize
-  acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
-  from fresh state.
-- **`Receipt` is not a `200 OK`.** It's the durable artifact a commit
-  produced — accepted commit id, server-assigned timestamps, stale-check
-  outcome — addressable after the fact and replayable into a different
-  client. A status code can't be re-read by a sub-agent that wasn't on
-  the original call.
-
-## Run Loop
-
-A normal schema-backed run is:
-
-```ts
-const report = await ablo.weatherReports.retrieve({ id });
-const active = ablo.weatherReports.claim.state({ id });
-await using claim = await ablo.weatherReports.claim({ id });
-await ablo.weatherReports.update({ id: claim.data.id, data: patch, wait: 'confirmed' });
-```
-
-`retrieve({ id })` is an async server read (await it). `claim.state({ id })` is a
-synchronous local read of who currently holds the row — it never blocks.
-
-## Coordination
-
-> Loop view only. Full claim reference — methods, the claim-state object, the
-> `claim.queue`, errors — is [Coordination](./coordination.md).
-
-Claims broadcast across the org. Call `claim({ id })`, do your writes with the
-normal `update` inside the `await using` scope, and the claim releases
-automatically when the scope exits:
-
-```ts
-await using claim = await ablo.weatherReports.claim({
-  id: 'report_stockholm',
-  description: 'editing',
-});
-await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
-```
-
-`ablo.weatherReports.claim.state({ id: 'report_stockholm' })` reads the live claim (or
-`null`) without blocking. Claims don't lock: if another participant holds the
-row, `claim` waits for them to finish, re-reads, and then hands you the fresh
-row. The same signal is visible to every schema client through `claim.state({ id })`
-and the live claim stream.
-
-## Conflict resolution
-
-Schema updates can carry `readAt` and `onStale`. If the state advanced past
-`readAt`, Ablo applies the `onStale` policy:
-
-- `reject` — fail the commit (first writer wins).
-- `notify` — accept the write, but flag it for product review.
-- `overwrite` — apply the write unconditionally.
-
-The choice is per-commit. No CRDT default; the policy is explicit.
-
-## The contract in one sentence
-
-Declare schema, load state, coordinate a claim, update the model, and wait for confirmation.