@abloatai/ablo 0.35.0 → 0.37.0

package/dist/transaction/policy/types.d.ts

@@ -1,217 +0,0 @@
-/**
- * The conflict types a policy decides on. The engine detects a conflict and
- * hands it to your {@link ConflictPolicy}, which returns a
- * {@link ConflictDecision}.
- *
- * There are two conflict shapes. A {@link StaleContextConflict} is a write
- * whose `readAt` watermark is older than the latest delta on the target row. A
- * {@link ClaimHeldConflict} is a participant trying to claim a target that
- * someone else already holds. {@link Conflict} is the discriminated union of
- * the two; switch on `kind` to narrow it.
- */
-import type { ParticipantRef } from '../types/participant.js';
-import type { CommitOperationType, OnStaleMode } from '../coordination/schema.js';
-export type ConflictKind = 'stale_context' | 'claim_held';
-/** Fields shared by every conflict shape. */
-interface ConflictBase {
-    readonly committer: ParticipantRef;
-    readonly organizationId: string;
-    /** Human at the root of the committer's delegation chain (if any). */
-    readonly delegationChainRootUserId?: string | null;
-}
-/** The operation whose write conflicts. */
-export interface ConflictOperation {
-    readonly model: string;
-    readonly id: string;
-    readonly type: CommitOperationType;
-    readonly input?: Readonly<Record<string, unknown>>;
-}
-export interface StaleContextConflict extends ConflictBase {
-    readonly kind: 'stale_context';
-    readonly operation: ConflictOperation;
-    /** Watermark the committer reasoned against. */
-    readonly readAt: number;
-    /** Most recent delta id on the target. */
-    readonly observedSyncId: number;
-    /**
-     * The fields whose concurrent change triggered this conflict — the
-     * intersection of the fields the committer wrote and the columns a newer
-     * delta touched. An empty array means the conflicting delta was a
-     * whole-entity change, such as a create or delete, which conflicts with any
-     * write. A policy can use this to decide at field granularity — for example,
-     * allowing the write when the only overlap is on a cosmetic field.
-     */
-    readonly conflictingFields?: readonly string[];
-    /**
-     * The committer's declared `onStale` intent for this operation. The default
-     * policy honors it: `'notify'` holds the write and notifies, and anything
-     * else rejects. A custom policy may override this. When absent, it is treated
-     * as `'reject'`, the default for an unguarded write.
-     */
-    readonly requestedMode?: OnStaleMode;
-}
-export interface ClaimHeldConflict extends ConflictBase {
-    readonly kind: 'claim_held';
-    readonly heldBy: ParticipantRef;
-    readonly claimId: string;
-    readonly entityType: string;
-    readonly entityId: string;
-    /** Holder's claim expiry (ms since epoch). */
-    readonly expiresAt: number;
-    /**
-     * The capability operations granted to the committer — the allowlist carried
-     * by its key. A policy decides purely from the conflict it is given, so this
-     * is the only place it can read the committer's privileges. It lets a policy
-     * express a rule such as "preempt only if the committer holds `claim.preempt`"
-     * (see {@link capabilityPreemptPolicy}). Empty for a human session that
-     * carries no allowlist.
-     */
-    readonly committerOperations: readonly string[];
-}
-/**
- * The discriminated union the policy receives. Switch on `.kind` to
- * narrow to the variant.
- */
-export type Conflict = StaleContextConflict | ClaimHeldConflict;
-/** What the policy returns. */
-export type ConflictDecision = {
-    readonly action: 'reject';
-    readonly reason?: string;
-} | {
-    readonly action: 'allow';
-    readonly note?: string;
-}
-/**
- * Evict the current holder and grant the target to the committer. This is
- * only meaningful for a `claim_held` conflict raised at claim time: the
- * holder receives a `claim_lost` notification with reason `'preempted'`, and
- * the committer takes the lease ahead of anyone already waiting in line for
- * it. Return it only for a committer you consider higher priority — for
- * example, a supervisor over its own sub-agents, or an identity that holds a
- * preempt capability. At commit time there is no holder to evict, so a
- * `preempt` decision is treated as `allow`.
- */
- | {
-    readonly action: 'preempt';
-    readonly reason?: string;
-}
-/**
- * Hold the write instead of aborting it. This is only meaningful for a
- * `stale_context` conflict. The engine withholds the conflicting operation
- * and returns a `StaleNotification` carrying the current value, so the actor
- * — an agent or a human — can reconcile and re-commit. The rest of the batch
- * still commits. It maps from `onStale: 'notify'`.
- *
- * The monotonic `sync_id` landing order decides who yields: the stale
- * committer always recomputes against the newer value, an asymmetry that
- * prevents two notifying writers from looping against each other. Retries are
- * bounded by the client's reconciliation retry cap.
- */
- | {
-    readonly action: 'notify';
-    readonly reason?: string;
-};
-/**
- * The function that decides a conflict. It receives a {@link Conflict} and
- * returns a {@link ConflictDecision}, either synchronously or as a promise.
- * Register your implementation with the engine; the example below allows a
- * cosmetic "linter" writer and defers everything else to {@link defaultPolicy}.
- *
- * ```ts
- * const policy: ConflictPolicy = (conflict) => {
- *   if (conflict.committer.id.startsWith('linter:')) {
- *     return { action: 'allow', note: 'cosmetic writer' };
- *   }
- *   return defaultPolicy(conflict);
- * };
- * ```
- */
-export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
-/**
- * The conflict policy the engine uses when you do not supply your own. It
- * favors people: a human is never blocked, while agents and automated writers
- * yield to a claim someone else holds.
- *
- * For a `claim_held` conflict, the decision follows the committer's kind:
- *
- *   • `user`   → `allow`  — a human is never blocked by a claim. A claim is a
- *                           coordination hint among agents, not a lock on
- *                           people.
- *   • `agent`  → `reject` — an agent yields to a claim held by someone else.
- *                           The one sanctioned exception is the privileged
- *                           `claim.preempt` capability; see
- *                           {@link capabilityPreemptPolicy}.
- *   • `system` → `reject` — automated and backend writers serialize through
- *                           claims the same way agents do, so a server job
- *                           cannot silently overwrite a held row. Declare the
- *                           model's conflict axis to overwrite if you want that.
- *
- * Allowing only `user` by default is deliberate: a backend key is a
- * full-access credential, and claim serialization depends on those writers
- * respecting claims unless a model opts out.
- *
- * For a `stale_context` conflict, the decision honors the committer's declared
- * `onStale` intent: `'notify'` holds the write and notifies the actor to
- * resolve it, and anything else (including `'reject'` or an absent value)
- * rejects. An `onStale` of `'overwrite'` never reaches a policy — it is a hard
- * opt-out resolved before the conflict is detected.
- *
- * To change this behavior for a model, declare its conflict axis in the schema;
- * a declared axis overrides this default.
- */
-export declare const defaultPolicy: (conflict: Conflict) => ConflictDecision;
-/**
- * A ready-made policy that grants capability-gated preemption. When the
- * committer's capability allowlist includes the `claim.preempt` operation, a
- * `claim_held` conflict is preempted: the current holder is evicted and the
- * committer takes the lease. Every other conflict falls back to
- * {@link defaultPolicy}, which rejects. Register it as your conflict policy to
- * let a privileged identity take over a held entity without writing a bespoke
- * policy. The authorization rests on holding the capability, not on any
- * particular identity string.
- */
-export declare const capabilityPreemptPolicy: ConflictPolicy;
-/**
- * A model's declared conflict disposition, keyed by the kind of committer. You
- * set it in the model's schema, for example
- * `conflict: { user: 'overwrite', agent: 'reject' }`, and the engine applies it
- * at commit time. It is plain data using the same `'reject' | 'overwrite' |
- * 'notify'` vocabulary as the write guards, so it travels through the schema
- * registry to the server without naming any application model.
- *
- * Each key is the committer's participant kind, which the server derives and a
- * client cannot forge; an omitted kind falls back to the engine default. So
- * `{ user: 'overwrite', agent: 'reject' }` reads as "a human's write wins, an
- * agent's write yields," and `system`, being unlisted, takes the default.
- */
-export interface ConflictAxis {
-    /** What happens when a human (`user` session) commits into a conflict. */
-    readonly user?: OnStaleMode;
-    /** What happens when an AI `agent` commits into a conflict. */
-    readonly agent?: OnStaleMode;
-    /** What happens when a `system` / automation actor commits into a conflict. */
-    readonly system?: OnStaleMode;
-}
-/**
- * Resolves a declared {@link ConflictAxis} into a {@link ConflictDecision} for
- * one concrete conflict. It is pure and synchronous, doing no I/O, so it can
- * run on either the client or the server. It reads the committer's kind from
- * the conflict and maps the declared mode:
- *
- *   - undefined   → the engine default, {@link defaultPolicy}: a human is
- *                   allowed, an agent or system committer is rejected on a
- *                   `claim_held`, and a stale write honors `onStale: 'notify'`.
- *   - `overwrite` → `allow`; the write wins and the committer is never blocked.
- *   - `reject`    → `reject`; the committer yields.
- *   - `notify`    → on a `stale_context` conflict, hold the write and notify so
- *                   the committer re-reads and re-applies; on a `claim_held`
- *                   conflict there is no held write to reconcile (see
- *                   {@link ConflictDecision} `notify`), so it degrades to
- *                   `reject` rather than silently writing to a claimed row.
- *
- * This is only the generic interpretation. Stronger server-side rules — such as
- * an agent never bypassing a claim held by someone else — are enforced where
- * the decision is applied, not here.
- */
-export declare function interpretConflictAxis(axis: ConflictAxis, conflict: Conflict): ConflictDecision;
-export {};

package/dist/transaction/policy/types.js

@@ -1,126 +0,0 @@
-/**
- * The conflict types a policy decides on. The engine detects a conflict and
- * hands it to your {@link ConflictPolicy}, which returns a
- * {@link ConflictDecision}.
- *
- * There are two conflict shapes. A {@link StaleContextConflict} is a write
- * whose `readAt` watermark is older than the latest delta on the target row. A
- * {@link ClaimHeldConflict} is a participant trying to claim a target that
- * someone else already holds. {@link Conflict} is the discriminated union of
- * the two; switch on `kind` to narrow it.
- */
-/**
- * The conflict policy the engine uses when you do not supply your own. It
- * favors people: a human is never blocked, while agents and automated writers
- * yield to a claim someone else holds.
- *
- * For a `claim_held` conflict, the decision follows the committer's kind:
- *
- *   • `user`   → `allow`  — a human is never blocked by a claim. A claim is a
- *                           coordination hint among agents, not a lock on
- *                           people.
- *   • `agent`  → `reject` — an agent yields to a claim held by someone else.
- *                           The one sanctioned exception is the privileged
- *                           `claim.preempt` capability; see
- *                           {@link capabilityPreemptPolicy}.
- *   • `system` → `reject` — automated and backend writers serialize through
- *                           claims the same way agents do, so a server job
- *                           cannot silently overwrite a held row. Declare the
- *                           model's conflict axis to overwrite if you want that.
- *
- * Allowing only `user` by default is deliberate: a backend key is a
- * full-access credential, and claim serialization depends on those writers
- * respecting claims unless a model opts out.
- *
- * For a `stale_context` conflict, the decision honors the committer's declared
- * `onStale` intent: `'notify'` holds the write and notifies the actor to
- * resolve it, and anything else (including `'reject'` or an absent value)
- * rejects. An `onStale` of `'overwrite'` never reaches a policy — it is a hard
- * opt-out resolved before the conflict is detected.
- *
- * To change this behavior for a model, declare its conflict axis in the schema;
- * a declared axis overrides this default.
- */
-// Typed by its real synchronous shape with `satisfies`, rather than the
-// async-permissive `ConflictPolicy` alias, so synchronous callers such as
-// `interpretConflictAxis` and `capabilityPreemptPolicy` receive a plain
-// `ConflictDecision` rather than `ConflictDecision | Promise<…>`. It remains
-// assignable to `ConflictPolicy` wherever it is used as one.
-export const defaultPolicy = ((conflict) => {
-    if (conflict.kind === 'claim_held') {
-        // A human (`user`) is never blocked; agents and system actors yield.
-        // Keeping every non-`user` kind on `reject` here ensures an agent cannot
-        // bypass a claim even on this default resolution path, which — unlike the
-        // declared-axis path — has no separate agent guard of its own.
-        return conflict.committer.kind === 'user'
-            ? { action: 'allow', note: 'principal:not-blocked' }
-            : { action: 'reject', reason: 'claim_conflict' };
-    }
-    return conflict.requestedMode === 'notify'
-        ? { action: 'notify', reason: 'stale_notify_hold' }
-        : { action: 'reject', reason: 'stale_context' };
-});
-/**
- * A ready-made policy that grants capability-gated preemption. When the
- * committer's capability allowlist includes the `claim.preempt` operation, a
- * `claim_held` conflict is preempted: the current holder is evicted and the
- * committer takes the lease. Every other conflict falls back to
- * {@link defaultPolicy}, which rejects. Register it as your conflict policy to
- * let a privileged identity take over a held entity without writing a bespoke
- * policy. The authorization rests on holding the capability, not on any
- * particular identity string.
- */
-export const capabilityPreemptPolicy = (conflict) => {
-    if (conflict.kind === 'claim_held' &&
-        conflict.committerOperations.includes('claim.preempt')) {
-        return { action: 'preempt', reason: 'capability:claim.preempt' };
-    }
-    return defaultPolicy(conflict);
-};
-const _conflictAxisPinned = [true, true];
-void _conflictAxisPinned;
-/**
- * Resolves a declared {@link ConflictAxis} into a {@link ConflictDecision} for
- * one concrete conflict. It is pure and synchronous, doing no I/O, so it can
- * run on either the client or the server. It reads the committer's kind from
- * the conflict and maps the declared mode:
- *
- *   - undefined   → the engine default, {@link defaultPolicy}: a human is
- *                   allowed, an agent or system committer is rejected on a
- *                   `claim_held`, and a stale write honors `onStale: 'notify'`.
- *   - `overwrite` → `allow`; the write wins and the committer is never blocked.
- *   - `reject`    → `reject`; the committer yields.
- *   - `notify`    → on a `stale_context` conflict, hold the write and notify so
- *                   the committer re-reads and re-applies; on a `claim_held`
- *                   conflict there is no held write to reconcile (see
- *                   {@link ConflictDecision} `notify`), so it degrades to
- *                   `reject` rather than silently writing to a claimed row.
- *
- * This is only the generic interpretation. Stronger server-side rules — such as
- * an agent never bypassing a claim held by someone else — are enforced where
- * the decision is applied, not here.
- */
-export function interpretConflictAxis(axis, conflict) {
-    const mode = axis[conflict.committer.kind];
-    if (mode === undefined)
-        return defaultPolicy(conflict);
-    switch (mode) {
-        case 'overwrite':
-            return { action: 'allow', note: 'conflict:overwrite' };
-        case 'reject':
-            return {
-                action: 'reject',
-                reason: conflict.kind === 'claim_held' ? 'claim_conflict' : 'stale_context',
-            };
-        case 'notify':
-            return conflict.kind === 'stale_context'
-                ? { action: 'notify', reason: 'stale_notify_hold' }
-                : { action: 'reject', reason: 'claim_conflict' };
-        default: {
-            // Exhaustiveness backstop: a future `OnStaleMode` member surfaces as a
-            // localized compile error here, not a missing-return at the signature.
-            const _exhaustive = mode;
-            return _exhaustive;
-        }
-    }
-}

package/dist/transaction/resources/functionalUpdate.d.ts

@@ -1,79 +0,0 @@
-/**
- * The functional update — `ablo.<model>.update(id, current => next)`.
- *
- * This is the surface that just works under contention. You express only your
- * intent — given the latest row, here is the next state — and the client does
- * the rest: it reads the fresh row and its watermark, runs your updater, writes
- * the result as a compare-and-swap against that watermark, and on any concurrent
- * write it re-reads, recomputes, and retries. No claim, no identity, no transport
- * awareness, and no `stale_context` or `claim_*` error codes ever reach the
- * caller. The write either lands or, at the extreme, throws a single
- * {@link AbloContentionError} once the reconcile budget is spent.
- *
- * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
- * (optimistic concurrency, or compare-and-swap), not from participant identity.
- * That is why it is immune to the shared-credential silent-overwrite hazard and
- * behaves identically on both transports: the HTTP and WebSocket clients inject
- * the same two functions ({@link ReconcileTransport}) into the shared loop below,
- * so the guarantee cannot drift between them — only the mechanism differs.
- *
- * The mental model is React's `setState(prev => next)`: pass a function of the
- * current state and the runtime owns reconciliation.
- */
-import { AbloContentionError } from '../errors.js';
-/**
- * The functional form of an update: given the freshly-read row, return the
- * fields to write. Return `null` or `undefined` to make no write — a no-op the
- * caller chose after seeing the latest state (for example, "already done").
- */
-export type ModelUpdater<T> = (current: T) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
-/** Tuning for the functional update's internal reconcile loop. */
-export interface ContentionOptions {
-    /**
-     * Max reconcile rounds under contention before throwing
-     * {@link AbloContentionError}. Each round re-reads the latest row and re-runs
-     * your updater. Defaults to {@link DEFAULT_CONTENTION_RETRIES}.
-     */
-    readonly retries?: number;
-    /** Abort the reconcile loop (e.g. the request was cancelled). */
-    readonly signal?: AbortSignal;
-}
-/** Reconcile rounds before a hot row is declared permanently contended. */
-export declare const DEFAULT_CONTENTION_RETRIES = 16;
-/**
- * Reports whether a thrown error means "another writer moved the row — re-read
- * and retry" rather than a genuine failure to surface. These are the
- * optimistic-concurrency signals the functional update reconciles against:
- *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
- *   - `claim_queued`  — a holder is actively editing the row right now
- */
-export declare function isReconcilableConflict(err: unknown): boolean;
-/**
- * The transport-specific read and write that the shared loop drives. Each client
- * injects its own pair — the one thing that differs between the HTTP and
- * WebSocket transports.
- */
-export interface ReconcileTransport<T, R> {
-    readonly model: string;
-    readonly id: string;
-    /** Read the latest row and its watermark from the authoritative store. */
-    readFresh: () => Promise<{
-        readonly data: T | null | undefined;
-        readonly stamp: number;
-    }>;
-    /**
-     * Write the computed patch as a compare-and-swap against `readAt`. It must
-     * throw a reconcilable conflict (`stale_context` or `claim_*`) when the
-     * watermark was overtaken — that rejection is what drives the next reconcile
-     * round.
-     */
-    writeNext: (patch: Partial<T>, readAt: number) => Promise<R>;
-}
-/**
- * Run the read-fresh → compute → compare-and-swap → reconcile loop. Shared by
- * both transports so the guarantee is provably identical. Returns the write's
- * result, or `undefined` when the updater opted out of writing.
- */
-export declare function reconcileFunctionalUpdate<T, R>(updater: ModelUpdater<T>, options: ContentionOptions | undefined, transport: ReconcileTransport<T, R>): Promise<R | undefined>;
-export { AbloContentionError };

package/dist/transaction/resources/functionalUpdate.js

@@ -1,87 +0,0 @@
-/**
- * The functional update — `ablo.<model>.update(id, current => next)`.
- *
- * This is the surface that just works under contention. You express only your
- * intent — given the latest row, here is the next state — and the client does
- * the rest: it reads the fresh row and its watermark, runs your updater, writes
- * the result as a compare-and-swap against that watermark, and on any concurrent
- * write it re-reads, recomputes, and retries. No claim, no identity, no transport
- * awareness, and no `stale_context` or `claim_*` error codes ever reach the
- * caller. The write either lands or, at the extreme, throws a single
- * {@link AbloContentionError} once the reconcile budget is spent.
- *
- * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
- * (optimistic concurrency, or compare-and-swap), not from participant identity.
- * That is why it is immune to the shared-credential silent-overwrite hazard and
- * behaves identically on both transports: the HTTP and WebSocket clients inject
- * the same two functions ({@link ReconcileTransport}) into the shared loop below,
- * so the guarantee cannot drift between them — only the mechanism differs.
- *
- * The mental model is React's `setState(prev => next)`: pass a function of the
- * current state and the runtime owns reconciliation.
- */
-import { AbloError, AbloNotFoundError, AbloStaleContextError, AbloClaimedError, AbloContentionError, } from '../errors.js';
-/** Reconcile rounds before a hot row is declared permanently contended. */
-export const DEFAULT_CONTENTION_RETRIES = 16;
-/**
- * Reports whether a thrown error means "another writer moved the row — re-read
- * and retry" rather than a genuine failure to surface. These are the
- * optimistic-concurrency signals the functional update reconciles against:
- *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
- *   - `claim_queued`  — a holder is actively editing the row right now
- */
-export function isReconcilableConflict(err) {
-    if (err instanceof AbloStaleContextError)
-        return true;
-    if (err instanceof AbloClaimedError) {
-        return err.code === 'claim_lost' || err.code === 'claim_queued';
-    }
-    return false;
-}
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/**
- * Jittered backoff so N reconcilers retrying at once don't lock-step straight
- * back into the same collision. Bounded; grows mildly with the attempt.
- */
-function backoffMs(attempt) {
-    return 60 + attempt * 40 + Math.floor(Math.random() * 60);
-}
-/**
- * Run the read-fresh → compute → compare-and-swap → reconcile loop. Shared by
- * both transports so the guarantee is provably identical. Returns the write's
- * result, or `undefined` when the updater opted out of writing.
- */
-export async function reconcileFunctionalUpdate(updater, options, transport) {
-    const retries = options?.retries ?? DEFAULT_CONTENTION_RETRIES;
-    let lastConflict;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-        if (options?.signal?.aborted) {
-            throw new AbloError(`Update of ${transport.model}/${transport.id} was aborted before it landed.`, { code: 'update_aborted' });
-        }
-        const { data, stamp } = await transport.readFresh();
-        if (data == null) {
-            throw new AbloNotFoundError(`Cannot update ${transport.model}/${transport.id}: it does not exist (or is ` +
-                `outside this credential's scope).`, [transport.id]);
-        }
-        const patch = await updater(data);
-        if (patch == null)
-            return undefined; // updater opted out after reading fresh
-        try {
-            return await transport.writeNext(patch, stamp);
-        }
-        catch (err) {
-            if (!isReconcilableConflict(err))
-                throw err; // genuine failure — surface it
-            lastConflict = err;
-            if (attempt < retries)
-                await sleep(backoffMs(attempt));
-        }
-    }
-    throw new AbloContentionError(transport.model, transport.id, retries + 1, {
-        cause: lastConflict,
-    });
-}
-// Re-exported so call sites import the loop and its terminal error from one
-// place; the class itself lives with the rest of the error hierarchy.
-export { AbloContentionError };