@abloatai/ablo 0.34.0 → 0.35.0

package/dist/transaction/observability.js

@@ -0,0 +1,19 @@
+/**
+ * The observability the settlement core reports on its own behalf.
+ *
+ * Coordination outcomes — a claim changing state, a stale-write collision that
+ * notified instead of aborting — happen with no UI and no local store anywhere,
+ * so the core must be able to report them without depending on the consumer's
+ * full provider (ADR 0016).
+ *
+ * This is deliberately the narrow set the core actually calls today. Widening it
+ * later is non-breaking; the reactive engine's `ObservabilityProvider` extends
+ * this interface, so a single implementation still satisfies both.
+ */
+/** The no-op default — what the transport reports through when nothing is wired. */
+export const noopSocketObservability = {
+    breadcrumb() { },
+    captureWebSocketError() { },
+    captureClaim() { },
+    captureConflict() { },
+};

package/dist/transaction/plugin.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The plugin contract (ADR 0016).
+ *
+ * The core is `commit` · `get`/`list` · `observe` · `claim` · auth. Everything
+ * else a caller might want — a local materialised copy, presence rendering,
+ * batching, framework bindings — is a plugin declared in one list, so a server
+ * or an agent installs only what it asked for.
+ *
+ * Every plugin has the same shape on purpose. Uniformity is what makes the list
+ * composable and the types inferable; bespoke plugins would reproduce today's
+ * nineteen export subpaths with extra ceremony.
+ *
+ * Where this shape came from, and the field-by-field reasoning behind it, is
+ * recorded in ADR 0016 — the contract itself only states what each field does.
+ */
+import type { ParticipantKind } from './types/participant.js';
+import type { ErrorCodeSpec } from './errorCodes.js';
+import type { Logger } from './logger.js';
+import type { CoordinationObservability } from './observability.js';
+import type { WsTransport } from './transport/wsTransport.js';
+/**
+ * A string type that keeps literal inference alive: `id: 'humans'` stays the
+ * literal `'humans'` through object-literal inference instead of widening to
+ * `string`, which is what lets {@link InstalledSurface} key a plugin list's
+ * surface by id.
+ */
+export type LiteralString = '' | (string & Record<never, never>);
+/**
+ * The ordered stages a delta passes through on its way from the feed into
+ * whatever is watching. A plugin names the one it attaches to.
+ *
+ * The order is not a convention — it is a correctness constraint. `acknowledge`
+ * must follow `persist`, because acknowledging the input range rather than the
+ * persisted high-water mark advances the server's cursor past deltas that never
+ * committed, and the next catch-up then answers "you're up to date" for a delta
+ * that was lost. Declaring the stage keeps that ordering out of array position,
+ * where it would be load-bearing and undocumented.
+ */
+export type PipelineStage = 
+/** Deltas arrive from `observe()` and are queued. */
+'receive'
+/** Per-entity collapse of the queued batch. */
+ | 'dedupe'
+/** The batch is written to durable local storage. */
+ | 'persist'
+/** Persisted results land in the in-memory graph. */
+ | 'apply'
+/** The cursor advances — gated on `persist`, never on the input range. */
+ | 'acknowledge'
+/** Anything downstream reacts: re-render, presence, subscribers. */
+ | 'notify';
+/** Canonical order. A plugin runner must run stages in this sequence. */
+export declare const PIPELINE_STAGES: readonly PipelineStage[];
+/**
+ * What a capability needs from whatever transport was selected.
+ *
+ * Transport is a slot the caller fills, not a packaging axis, so a capability
+ * states its requirement and an incompatible pairing fails when the client is
+ * configured — with a typed error naming the plugin — rather than at runtime
+ * with a subscription that silently never delivers.
+ */
+export interface TransportCapabilities {
+    /**
+     * Requires a transport the server can initiate frames on. Live subscriptions,
+     * presence, and claim grants need this; commit and point-in-time reads do not.
+     */
+    readonly duplex?: boolean;
+}
+/**
+ * The core surface a plugin is handed at construction.
+ *
+ * Generic over the client's options type: the host instantiates it with its
+ * own options bag, so a plugin reads configuration without this package
+ * naming any consumer's types. Alongside the raw options, the context
+ * carries the values the host has already resolved (`participant`,
+ * `syncGroups`), so a plugin never re-derives identity.
+ */
+export interface PluginContext<Options = unknown> {
+    readonly logger: Logger;
+    readonly observability?: CoordinationObservability;
+    /** The client's own options bag, as the host received it. */
+    readonly options?: Options;
+    /**
+     * The live duplex connection. The host builds it during construction, so a
+     * plugin holds the thing rather than a function that fetches it: the
+     * connection object is stable for the client's lifetime — identity and
+     * read scope are seeded into it when they resolve, and reconnects replace
+     * only the socket inside it, never the object. Absent on a
+     * request-response client, which is what `requires: { duplex: true }`
+     * guards.
+     */
+    readonly transport?: WsTransport;
+    /** The participant this client runs as, when known at construction. */
+    readonly participant?: {
+        readonly id: string;
+        readonly kind: ParticipantKind;
+    };
+    /** The connection's initial read scope (sync groups). */
+    readonly syncGroups?: readonly string[];
+}
+/**
+ * One installed capability.
+ *
+ * @typeParam Surface - what `init` contributes to the client. The plugin list's
+ * element types are what let the installed surface be inferred rather than
+ * declared.
+ */
+export interface AbloPlugin<Surface = unknown> {
+    /** Stable identity — deduplication, diagnostics, and error attribution.
+     *  Literal-typed so a list's installed surface can be keyed by it. */
+    readonly id: LiteralString;
+    /** The plugin's own version, for diagnostics. */
+    readonly version?: string;
+    /** What this plugin needs from the transport. Checked at configuration time. */
+    readonly requires?: TransportCapabilities;
+    /**
+     * Whether this plugin keeps a local copy of rows.
+     *
+     * This is ADR 0013 §4's membership test as a declared, checkable property
+     * rather than a rule someone has to remember: a stateless caller can assert
+     * that nothing in its list materialises, and CI can assert the core's own
+     * list is uniformly `false`.
+     */
+    readonly materialises: boolean;
+    /**
+     * Error codes this plugin may raise, folded into the registry.
+     *
+     * Registration is part of the contract because the error catalog is
+     * generated — a plugin that invents untyped errors would silently punch a
+     * hole in the published reference.
+     */
+    readonly errorCodes?: Readonly<Record<string, ErrorCodeSpec>>;
+    /** Which pipeline stage this plugin attaches to, if it observes deltas. */
+    readonly stage?: PipelineStage;
+    /** Build the plugin's contribution to the client surface. */
+    init(context: PluginContext): Surface;
+}
+/** The surface a plugin list contributes, keyed by plugin id. */
+export type InstalledSurface<Plugins extends readonly AbloPlugin[]> = {
+    [P in Plugins[number] as P['id']]: P extends AbloPlugin<infer S> ? S : never;
+};
+/**
+ * The plugin with the given id in a list, or `never` when absent. Sound
+ * because ids are literal ({@link LiteralString}); a list typed only as
+ * `AbloPlugin[]` has widened ids and resolves to `never`, so write plugin
+ * lists inline for the client type to follow them.
+ */
+export type PluginById<Plugins extends readonly AbloPlugin[], Id extends string> = Extract<Plugins[number], {
+    id: Id;
+}>;
+/** Collapses a union into an intersection, member by member. */
+type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (member: infer I) => void ? I : never;
+/**
+ * Every surface in a plugin list, folded into the one shape that merges onto
+ * the client: `[a(), b()]` contributes `ASurface & BSurface`. An empty list
+ * contributes nothing (`unknown`), so intersecting it changes no type.
+ */
+export type MergedSurface<Plugins extends readonly AbloPlugin[]> = [
+    Plugins[number]
+] extends [never] ? unknown : UnionToIntersection<Plugins[number] extends AbloPlugin<infer Surface> ? Surface : never>;
+/** What the selected transport can actually do, for checking `requires`. */
+export interface TransportProfile {
+    readonly duplex: boolean;
+}
+/**
+ * Check a plugin list against the selected transport and build its surface.
+ *
+ * Both failures are configuration mistakes, so they surface here — while the
+ * client is being constructed and the stack still points at the caller's own
+ * setup — rather than later as a subscription that never delivers.
+ */
+export declare function resolvePlugins<const Plugins extends readonly AbloPlugin[], Options = unknown>(plugins: Plugins, transport: TransportProfile, context: PluginContext<Options>): InstalledSurface<Plugins>;
+/**
+ * Lays every installed plugin surface over a built client, so a plugin's
+ * contributions are reachable as client members. The base always wins — a
+ * plugin cannot shadow `dispose`, a model accessor, or any other member the
+ * client itself defines; contributions only fill what the base leaves
+ * undefined. With nothing installed the base is returned untouched.
+ *
+ * The second half of {@link resolvePlugins}: that call turns a list into a
+ * surface, this one merges the surface onto the client the host built.
+ */
+export declare function layerPluginSurface<T extends object>(base: T, installed: Record<string, unknown>): T;
+/**
+ * The plugins attached to one pipeline stage, in declaration order.
+ *
+ * Stage order across the pipeline is fixed by {@link PIPELINE_STAGES}; this
+ * returns the members of a single stage, where declaration order is the caller's
+ * to choose and carries no correctness weight.
+ */
+export declare function pluginsForStage(plugins: readonly AbloPlugin[], stage: PipelineStage): readonly AbloPlugin[];
+export {};

package/dist/transaction/plugin.js

@@ -0,0 +1,87 @@
+/**
+ * The plugin contract (ADR 0016).
+ *
+ * The core is `commit` · `get`/`list` · `observe` · `claim` · auth. Everything
+ * else a caller might want — a local materialised copy, presence rendering,
+ * batching, framework bindings — is a plugin declared in one list, so a server
+ * or an agent installs only what it asked for.
+ *
+ * Every plugin has the same shape on purpose. Uniformity is what makes the list
+ * composable and the types inferable; bespoke plugins would reproduce today's
+ * nineteen export subpaths with extra ceremony.
+ *
+ * Where this shape came from, and the field-by-field reasoning behind it, is
+ * recorded in ADR 0016 — the contract itself only states what each field does.
+ */
+import { AbloValidationError } from './errors.js';
+/** Canonical order. A plugin runner must run stages in this sequence. */
+export const PIPELINE_STAGES = [
+    'receive',
+    'dedupe',
+    'persist',
+    'apply',
+    'acknowledge',
+    'notify',
+];
+/**
+ * Check a plugin list against the selected transport and build its surface.
+ *
+ * Both failures are configuration mistakes, so they surface here — while the
+ * client is being constructed and the stack still points at the caller's own
+ * setup — rather than later as a subscription that never delivers.
+ */
+export function resolvePlugins(plugins, transport, context) {
+    const surface = {};
+    const seen = new Set();
+    for (const plugin of plugins) {
+        if (seen.has(plugin.id)) {
+            throw new AbloValidationError(`The ${plugin.id} plugin is listed twice. Remove the duplicate; a plugin is installed once per client.`, { code: 'invalid_options', param: 'plugins' });
+        }
+        seen.add(plugin.id);
+        if (plugin.requires?.duplex && !transport.duplex) {
+            throw new AbloValidationError(`The ${plugin.id} plugin needs a connection the server can send on, and this client is set up for request-response only. Switch the transport to 'websocket', or drop the plugin.`, { code: 'invalid_options', param: 'plugins' });
+        }
+        surface[plugin.id] = plugin.init(context);
+    }
+    return surface;
+}
+/**
+ * Lays every installed plugin surface over a built client, so a plugin's
+ * contributions are reachable as client members. The base always wins — a
+ * plugin cannot shadow `dispose`, a model accessor, or any other member the
+ * client itself defines; contributions only fill what the base leaves
+ * undefined. With nothing installed the base is returned untouched.
+ *
+ * The second half of {@link resolvePlugins}: that call turns a list into a
+ * surface, this one merges the surface onto the client the host built.
+ */
+export function layerPluginSurface(base, installed) {
+    const contributions = {};
+    for (const surface of Object.values(installed)) {
+        if (surface && typeof surface === 'object') {
+            Object.assign(contributions, surface);
+        }
+    }
+    if (Object.keys(contributions).length === 0)
+        return base;
+    return new Proxy(base, {
+        get(target, prop, receiver) {
+            const own = Reflect.get(target, prop, receiver);
+            if (own !== undefined)
+                return own;
+            return typeof prop === 'string' && prop in contributions
+                ? contributions[prop]
+                : own;
+        },
+    });
+}
+/**
+ * The plugins attached to one pipeline stage, in declaration order.
+ *
+ * Stage order across the pipeline is fixed by {@link PIPELINE_STAGES}; this
+ * returns the members of a single stage, where declaration order is the caller's
+ * to choose and carries no correctness weight.
+ */
+export function pluginsForStage(plugins, stage) {
+    return plugins.filter((plugin) => plugin.stage === stage);
+}

package/dist/{policy → transaction/policy}/types.d.ts

@@ -10,7 +10,7 @@
  * the two; switch on `kind` to narrow it.
  */
 import type { ParticipantRef } from '../types/participant.js';
-import type { OnStaleMode } from '../coordination/schema.js';
+import type { CommitOperationType, OnStaleMode } from '../coordination/schema.js';
 export type ConflictKind = 'stale_context' | 'claim_held';
 /** Fields shared by every conflict shape. */
 interface ConflictBase {
@@ -23,7 +23,7 @@ interface ConflictBase {
 export interface ConflictOperation {
     readonly model: string;
     readonly id: string;
-    readonly type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
+    readonly type: CommitOperationType;
     readonly input?: Readonly<Record<string, unknown>>;
 }
 export interface StaleContextConflict extends ConflictBase {
@@ -48,7 +48,7 @@ export interface StaleContextConflict extends ConflictBase {
      * else rejects. A custom policy may override this. When absent, it is treated
      * as `'reject'`, the default for an unguarded write.
      */
-    readonly requestedMode?: 'reject' | 'overwrite' | 'notify';
+    readonly requestedMode?: OnStaleMode;
 }
 export interface ClaimHeldConflict extends ConflictBase {
     readonly kind: 'claim_held';

package/dist/{policy → transaction/policy}/types.js

@@ -77,6 +77,8 @@ export const capabilityPreemptPolicy = (conflict) => {
     }
     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

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

@@ -0,0 +1,266 @@
+/**
+ * Shared resource types for the typed clients and private HTTP transport.
+ * the commit and claim shapes, the session-mint params and resource, and the
+ * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
+ * imports.
+ */
+import type { OnStaleMode, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ClientCommitReceipt, CommitWait } from '../wire/commit.js';
+export type { CommitWait };
+import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
+export type { ModelTarget, ModelClaim };
+import type { ResolveClaimMeta } from '../types/global.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { SyncGroupInput } from '../schema/roles.js';
+import type { CapabilityCan, CapabilityOperation, CapabilityScope } from '../auth/capability.js';
+import type { Claim, ClaimStream, ClaimWaitOptions, Duration, HeldClaim } from '../types/streams.js';
+import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod } from './modelOperations.js';
+/**
+ * The operations available on each model in the sync engine:
+ *   `retrieve({ id })` — an async single-row server read
+ *   `list({ where })` — an async collection server read
+ *   `local.retrieve(id)` / `local.list(...)` / `local.count(...)` — synchronous local reads
+ *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
+ *   `claim({ id })` — a durable claim handle for coordinated writes
+ */
+export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+export type IfClaimedPolicy = 'return' | 'fail';
+export interface ClaimedOptions {
+    /**
+     * What to do when another participant has claimed the target: `return` lets
+     * the read proceed; `fail` throws `AbloClaimedError`. Inspect claim state via
+     * `ablo.<model>.claim.state({ id })`. Waiting is a claim-side concern — take
+     * `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
+     */
+    readonly ifClaimed?: IfClaimedPolicy;
+}
+export type { ClaimWaitOptions } from '../types/streams.js';
+export interface ModelReadOptions extends ClaimedOptions {
+}
+/**
+ * The target a caller names when creating a claim: {@link ModelTarget} with its
+ * one caller-authored member typed — `meta` is the shape declared on
+ * `Register`'s `ClaimMeta` slot, the same declaration every reader of the claim
+ * is given back.
+ *
+ * Derived rather than restated, and narrowed only here: `modelTargetSchema`
+ * keeps parsing `meta` as an open record, because a peer on a newer build must
+ * still be understood. The wire stays permissive; the DTO the caller writes
+ * does not.
+ */
+export type ModelTargetInput = Omit<ModelTarget, 'meta'> & {
+    readonly meta?: ResolveClaimMeta;
+};
+export interface ClaimCreateOptions {
+    readonly target: ModelTargetInput;
+    /** Peer-visible description of the work — the same field on every claim
+     *  surface. Defaults to `'editing'` when omitted. */
+    readonly description?: string;
+    readonly ttl?: Duration;
+    /**
+     * Join the server's fair FIFO queue when the target is already claimed,
+     * rather than failing immediately. `create` then resolves only once the
+     * lease is actually ours (the server pushes `claim_acquired` if the target
+     * was free, or `claim_granted` when we reach the head of the line). Without
+     * this, a contended claim throws. Used by `ablo.<model>.claim` so writers
+     * serialize instead of racing.
+     */
+    readonly queue?: boolean;
+    /** Cap on how long to wait for a queued grant before rejecting. */
+    readonly waitTimeoutMs?: number;
+    /**
+     * Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of
+     * waiting if the queue is already `>= maxQueueDepth` when we join.
+     */
+    readonly maxQueueDepth?: number;
+}
+export interface CommitOperationInput {
+    readonly action: ModelOperationAction;
+    /** The model name — matches `ablo.<model>` and the schema's `model()`. */
+    readonly model: string;
+    readonly id?: string | null;
+    readonly data?: Record<string, unknown> | null;
+    readonly transactionId?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    /** Fencing token (Option B) from the batch's claim handle; server-validated. */
+    readonly fenceToken?: number | null;
+}
+export interface CommitCreateOptions {
+    readonly idempotencyKey?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    /**
+     * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
+     * surface). Same vocabulary as the per-model writes: the handle's
+     * snapshot watermark becomes the batch `readAt` default and `onStale`
+     * defaults to `'reject'`, so a commit that follows a claim is guarded
+     * against concurrent edits without re-stating the watermark by hand.
+     * Explicit `readAt`/`onStale` on the options win.
+     */
+    readonly claim?: Claim | null;
+    /** One atomic batch. Use a one-element array for a single operation. */
+    readonly operations: readonly CommitOperationInput[];
+    readonly wait?: CommitWait;
+    /**
+     * The batch premise — the "did anything I looked at change?" guard.
+     * Declare the rows (`{ model, id, readAt, fields? }`) or sync groups
+     * (`{ group, readAt }`, for example `report:abc`) this batch was premised on; the
+     * server checks that none moved since `readAt` and fires the entry's `onStale`
+     * over the batch. This is distinct from the write-target `readAt`: it guards what
+     * you read, not what you write.
+     */
+    readonly reads?: readonly ReadDependency[] | null;
+    /**
+     * Durable premises to register as part of this batch — the persisted
+     * sibling of `reads`. Where `reads` guards only this commit, a `track` entry
+     * (`{ model, id, readAt? }` for a row or `{ group, readAt? }` for a sync group)
+     * lives on past it: a later matching change rides back on a future receipt's
+     * `notifications`. A track-only batch (just `track`, an empty `operations`) is
+     * the batch form of `ablo.<model>.track()`.
+     */
+    readonly track?: readonly TrackDependency[] | null;
+}
+/** Public projection inferred from the canonical runtime schema. */
+export type CommitReceipt = ClientCommitReceipt;
+export interface CommitResource {
+    create(options: CommitCreateOptions): Promise<CommitReceipt>;
+}
+export interface ClaimResource extends ClaimStream {
+    create(options: ClaimCreateOptions): Promise<Claim>;
+    list(target?: Partial<ModelTarget>): readonly ModelClaim[];
+    waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
+}
+export interface ModelMutationOptions extends ClaimedOptions {
+    readonly claimRef?: string | {
+        readonly id: string;
+    } | null;
+    readonly idempotencyKey?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    readonly wait?: CommitWait;
+    readonly claim?: Claim | ClaimOptions | null;
+    /** Fencing token (Option B) from the claim; server-validated at commit. */
+    readonly fenceToken?: number | null;
+}
+/**
+ * The stateless HTTP claim surface. Most code puts a `claim` directly on the write
+ * (`update({ id, data, claim })`) and lets the SDK release it; reach for this
+ * namespace for multi-step handles and coordination screens.
+ *
+ * It is the same surface as the reactive claim API, but because every read is a
+ * server round-trip, `state`, `queue`, and `reorder` are awaited here. The
+ * WebSocket client resolves those synchronously from its local cache, which is what
+ * lets it read a claim's state inside a React render; a stateless client has no
+ * cache to read, so the promise is unavoidable.
+ *
+ * It is derived from `ClaimReadApi` through {@link AwaitedClaimMethod} so the two
+ * transports cannot drift: the only difference is the promise wrapper that
+ * statelessness forces. `claim({ id })` is identical on both (already async);
+ * `state`, `queue`, `reorder`, and `release` are the awaited form.
+ */
+export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<HeldClaim<T>>) & {
+    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
+};
+/** A single data operation a scoped **agent** session may perform on a model.
+ *  The SDK-facing name for {@link CapabilityOperation}; the vocabulary itself is
+ *  declared once, as a schema, in `auth/capability.ts`. */
+export type SessionOperation = CapabilityOperation;
+/** Parameters for minting an end-user session — full data authority within the
+ *  organization. Mints an `ek_` token. `user.id` is your end user's id from your
+ *  own identity provider and becomes the session's `participantId`; Ablo does not
+ *  model your users, so it is treated as an opaque string at the trust boundary. */
+export interface CreateUserSessionParams {
+    /** Your end user. `id` becomes the token's `participantId`. */
+    user: {
+        id: string;
+    };
+    /** Mint the session into this organization instead of the key's own — for a
+     *  platform that serves many tenants from one backend. Requires the `sk_` key to
+     *  carry the `ephemeral:mint-any-org` scope; omit it for the normal
+     *  single-tenant case. */
+    organizationId?: string;
+    /** Sync groups this session may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
+     *  `@abloatai/ablo/schema`). Omit for the server default:
+     *  `[org:<your org>, user:<user.id>]`. */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.user`. */
+    userMeta?: Record<string, unknown>;
+    agent?: never;
+    can?: never;
+}
+/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
+ *  gated to exactly the operations named in `can`. `can` is typed off your
+ *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Report: ['read'] }`
+ *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
+export interface CreateAgentSessionParams<S extends SchemaRecord> {
+    /** Your agent. `id` becomes the token's `participantId`. */
+    agent: {
+        id: string;
+    };
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: CapabilityCan<S>;
+    /** Sync groups this session may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
+     *  `@abloatai/ablo/schema`). Omit for the server default: the org
+     *  anchor (`org:<your org>`) + the agent's own anchor. */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.agent`. */
+    userMeta?: Record<string, unknown>;
+    user?: never;
+}
+/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
+ *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
+ *  for a scoped agent session (`rk_`). */
+export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
+/** Params for {@link Ablo.agents}.create — a flattened agent descriptor (no
+ *  `{ agent }` discriminator: `agents.create` only ever mints an agent). Unlike
+ *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
+ *  client rather than a raw token. */
+export interface CreateAgentClientParams<S extends SchemaRecord> {
+    /** The wire participant identity (`agent:<id>`) that claim exclusion and the
+     *  FIFO queue gate on. Omit it to get a fresh random id — a distinct, independent
+     *  participant, which is the default and what you want for concurrent agents.
+     *  Pass a stable string only when one logical agent must re-attach to its own
+     *  held claims across reconnects or restarts. */
+    id?: string;
+    /** A human-readable label for logs and attribution (carried in `userMeta.name`).
+     *  It is independent of `id`: two agents that share a `name` still receive
+     *  distinct ids and coordinate as separate participants — `name` never derives or
+     *  collapses identity. */
+    name?: string;
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: CapabilityCan<S>;
+    /** Sync groups this agent may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`). Omit for the server default (org anchor + the
+     *  agent's own anchor). */
+    syncGroups?: readonly SyncGroupInput[];
+    /** Token lifetime in seconds. Defaults to 900 (15 minutes); the returned client
+     *  re-mints before expiry, so a long-running agent never handles rotation
+     *  itself. */
+    ttlSeconds?: number;
+    /** Extra opaque identity blob echoed on the session scope. Merged with
+     *  `name` (the `name` param wins if you also set `userMeta.name`). */
+    userMeta?: Record<string, unknown>;
+}
+/** A minted session. `token` is the secret the holder presents as its bearer. */
+export interface AbloSession {
+    object: 'session';
+    /** Stable id of the minted credential (for revocation). */
+    id: string;
+    /** The short-lived session token — `ek_` for a `{ user }` session, `rk_`
+     *  for an `{ agent }` session. Hand this to the participant's runtime. */
+    token: string;
+    /** ISO-8601 expiry. */
+    expiresAt: string;
+    organizationId: string;
+    /** The grant this token carries, on both axes — the same shape the key row
+     *  stores and the gates enforce. */
+    scope: CapabilityScope;
+    userMeta: Record<string, unknown>;
+}

package/dist/transaction/resources/httpResources.js

@@ -0,0 +1,7 @@
+/**
+ * Shared resource types for the typed clients and private HTTP transport.
+ * the commit and claim shapes, the session-mint params and resource, and the
+ * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
+ * imports.
+ */
+export {};