@abloatai/ablo 0.16.3 → 0.18.0

package/dist/client/Ablo.d.ts

@@ -133,6 +133,22 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @default 'websocket'
      */
     transport?: 'websocket' | 'http' | undefined;
+    /**
+     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims requested / queued / granted / released, agent
+     * handovers, connection state — so you can SEE the human+agent coordination
+     * you built while debugging. Omitted/`false` keeps the quiet default (only
+     * warnings + errors). For a middle ground use {@link logLevel}. Env override:
+     * `ABLO_LOG_LEVEL`. Ignored if a custom logger is supplied.
+     */
+    debug?: boolean | undefined;
+    /**
+     * Log threshold for the default `[Ablo]` logger (takes precedence over
+     * {@link debug}). `'info'` = coordination + connection events without the
+     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
+     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
     /**
      * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
      * deployments may pass a bearer token minted by their own auth layer.
@@ -242,8 +258,24 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * `apiKey` only; the server handles capability issuance.
      */
     capabilityToken?: string;
-    /** Custom logger (default: console) */
+    /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
     logger?: SyncLogger;
+    /**
+     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
+     * coordination trace — claims acquired / queued / granted / released, agent
+     * handovers, connection state — plus internal lifecycle, so you can SEE the
+     * human+agent coordination you built. Omitted/`false` keeps the quiet default
+     * (only warnings + errors). For a middle ground use {@link logLevel}.
+     * Env override: `ABLO_LOG_LEVEL`. Ignored if a custom {@link logger} is passed.
+     */
+    debug?: boolean;
+    /**
+     * Log threshold for the default `[Ablo]` logger (takes precedence over
+     * {@link debug}). `'info'` = coordination + connection events without the
+     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
+     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
     /** ObjectPool size limit (default: 10000) */
     maxPoolSize?: number;
     /**

package/dist/client/Ablo.js

@@ -518,17 +518,44 @@ function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed,
     }
     return ModelClass;
 }
-// ── Default console logger ────────────────────────────────────────────────
-const consoleLogger = {
-    debug: (...args) => { if (typeof console !== 'undefined')
-        console.debug('[sync]', ...args); },
-    info: (...args) => { if (typeof console !== 'undefined')
-        console.info('[sync]', ...args); },
-    warn: (...args) => { if (typeof console !== 'undefined')
-        console.warn('[sync]', ...args); },
-    error: (...args) => { if (typeof console !== 'undefined')
-        console.error('[sync]', ...args); },
-};
+const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+function resolveLogLevel(opts) {
+    if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK)
+        return opts.logLevel;
+    if (opts?.debug === true)
+        return 'debug';
+    // `globalThis.process` guard keeps this safe in browser/edge runtimes that
+    // have no `process` binding — there we fall through to the default.
+    const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
+    const normalized = raw?.toLowerCase();
+    if (normalized && normalized in LOG_LEVEL_RANK)
+        return normalized;
+    return 'warn';
+}
+/**
+ * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
+ * with a console full of other tools' logs can see at a glance what's ours.
+ */
+function createConsoleLogger(level) {
+    const threshold = LOG_LEVEL_RANK[level];
+    const emit = (lvl, fn, args) => {
+        if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold)
+            return;
+        fn('[Ablo]', ...args);
+    };
+    return {
+        debug: (...args) => emit('debug', console.debug, args),
+        info: (...args) => emit('info', console.info, args),
+        warn: (...args) => emit('warn', console.warn, args),
+        error: (...args) => emit('error', console.error, args),
+    };
+}
 // `readProcessEnv` lives in `./auth` alongside the other resolvers
 // that read it. Re-exported there for use elsewhere in the file.
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
@@ -712,7 +739,10 @@ export function Ablo(options) {
         databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
-    const { logger = consoleLogger } = internalOptions;
+    // Custom logger wins; otherwise build the default `[Ablo]` logger at the level
+    // resolved from `debug`/`logLevel`/`ABLO_LOG_LEVEL` (default `warn`).
+    const logger = internalOptions.logger ??
+        createConsoleLogger(resolveLogLevel({ debug: options.debug, logLevel: options.logLevel }));
     // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
     // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
     warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));

package/dist/client/auth.js

@@ -83,7 +83,7 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
     if (warn)
         warn(message);
     else if (typeof console !== 'undefined')
-        console.warn('[sync]', message);
+        console.warn('[Ablo]', message);
 }
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;

package/dist/core/StoreManager.js

@@ -274,7 +274,9 @@ export class StoreManager {
      * Clear all stores
      */
     async clearAllStores() {
-        getContext().logger.warn('Clearing all stores');
+        // Lifecycle chatter (logout / identity switch / reset) — NOT a warning.
+        // `debug` so it's silent under the default `warn` threshold.
+        getContext().logger.debug('Clearing all stores');
         const promises = Array.from(this.stores.values()).map((store) => store.clear());
         await Promise.all(promises);
         getContext().logger.info('All stores cleared');

package/dist/errors.d.ts

@@ -77,6 +77,15 @@ export declare class AbloError extends Error {
         request_id?: string;
         [key: string]: unknown;
     };
+    /**
+     * A single, leak-proof line for logs and `String(err)` / template
+     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     *
+     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+     * makes `console.error(richError)` an unreadable wall of text. The structured
+     * payload stays available via {@link toJSON}; this is the human one-liner.
+     */
+    toString(): string;
 }
 /**
  * Map a stable error `code` to its docs URL — the one place the convention

package/dist/errors.js

@@ -91,6 +91,20 @@ export class AbloError extends Error {
             ...(this.details ?? {}),
         };
     }
+    /**
+     * A single, leak-proof line for logs and `String(err)` / template
+     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     *
+     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+     * makes `console.error(richError)` an unreadable wall of text. The structured
+     * payload stays available via {@link toJSON}; this is the human one-liner.
+     */
+    toString() {
+        const code = this.code ? ` [${this.code}]` : '';
+        const docs = this.docUrl ? ` (see ${this.docUrl})` : '';
+        const req = this.requestId ? ` [request_id: ${this.requestId}]` : '';
+        return `${this.name}${code}: ${this.message}${docs}${req}`;
+    }
 }
 /**
  * Map a stable error `code` to its docs URL — the one place the convention

package/dist/index.d.ts

@@ -62,6 +62,8 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
+export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
+export type { ErrorEnvelope } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 export type { Environment, KeyPrefixEnvironment } from './environment.js';

package/dist/index.js

@@ -85,6 +85,11 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+// Canonical wire-egress contract (dependency-free): the error envelope shape +
+// the AbloError-subclass→HTTP-status table. Re-exported so server consumers
+// (e.g. apps/sync-server, which keeps its own self-contained copy) can assert
+// against the ONE source instead of silently drifting. See wire/errorEnvelope.ts.
+export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 // THE write-options contract — the one Zod schema for the option bag every

package/dist/policy/types.d.ts

@@ -122,18 +122,32 @@ export type ConflictDecision = {
  */
 export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
 /**
- * Default policy.
+ * Default policy — **Law 7 (the human is the principal) is the engine-wide
+ * default, not an opt-in.**
  *
- * `claim_held` conflicts always reject (a foreign claim is honored unless a
- * privileged policy preempts). `stale_context` conflicts honor the committer's
- * declared `onStale` intent:
+ * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
+ * construction, identical to `coordination(humansOverwrite(), agentsReject())`
+ * applied to every model — so a developer who wants different behaviour just
+ * declares the conflict axis on that model (`humansReject()`, `humansNotify()`,
+ * …) and it wins. The default and the override speak the same vocabulary; the
+ * default is the one you get for free.
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
+ *                           coordination hint among agents, not a lock on people)
+ *   • `system` → `allow`  — automation principals at the root of a trust chain
+ *                           behave like humans here (matches `mayBypassClaims`)
+ *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
+ *                           invariant; the ONLY sanctioned agent override is the
+ *                           privileged `claim.preempt` capability seam, see
+ *                           {@link capabilityPreemptPolicy})
+ *
+ * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
  *   • `'notify'` → notify + hold (op withheld; the actor resolves)
  *   • anything else (incl. `'reject'`, absent) → reject
  *
- * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
- * detection. This preserves the legacy always-reject default for callers that
- * don't opt into `notify`.
+ * `'overwrite'` never reaches a policy on the stale path — it's a hard opt-out
+ * resolved before detection.
  */
 export declare const defaultPolicy: (conflict: Conflict) => ConflictDecision;
 /**
@@ -172,8 +186,9 @@ export interface ConflictAxis {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: reject; honor
- *                   `onStale: 'notify'` on a stale write)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human/system
+ *                   committer is allowed (never blocked), an agent rejects on a
+ *                   `claim_held`; on a stale write, honor `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/policy/types.js

@@ -7,18 +7,32 @@
  * Adding new shapes is additive on the discriminated union.
  */
 /**
- * Default policy.
+ * Default policy — **Law 7 (the human is the principal) is the engine-wide
+ * default, not an opt-in.**
  *
- * `claim_held` conflicts always reject (a foreign claim is honored unless a
- * privileged policy preempts). `stale_context` conflicts honor the committer's
- * declared `onStale` intent:
+ * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
+ * construction, identical to `coordination(humansOverwrite(), agentsReject())`
+ * applied to every model — so a developer who wants different behaviour just
+ * declares the conflict axis on that model (`humansReject()`, `humansNotify()`,
+ * …) and it wins. The default and the override speak the same vocabulary; the
+ * default is the one you get for free.
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
+ *                           coordination hint among agents, not a lock on people)
+ *   • `system` → `allow`  — automation principals at the root of a trust chain
+ *                           behave like humans here (matches `mayBypassClaims`)
+ *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
+ *                           invariant; the ONLY sanctioned agent override is the
+ *                           privileged `claim.preempt` capability seam, see
+ *                           {@link capabilityPreemptPolicy})
+ *
+ * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
  *   • `'notify'` → notify + hold (op withheld; the actor resolves)
  *   • anything else (incl. `'reject'`, absent) → reject
  *
- * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
- * detection. This preserves the legacy always-reject default for callers that
- * don't opt into `notify`.
+ * `'overwrite'` never reaches a policy on the stale path — it's a hard opt-out
+ * resolved before detection.
  */
 // Typed by its real SYNCHRONOUS shape (via `satisfies`) rather than the
 // async-permissive `ConflictPolicy` alias, so sync callers like
@@ -26,8 +40,14 @@
 // `ConflictDecision` back (not `… | Promise<…>`). Still assignable to
 // `ConflictPolicy` everywhere it's used as a policy.
 export const defaultPolicy = ((conflict) => {
-    if (conflict.kind !== 'stale_context') {
-        return { action: 'reject', reason: 'claim_conflict' };
+    if (conflict.kind === 'claim_held') {
+        // Law 7 universal default: principals (human / system) are never blocked;
+        // agents yield. Keeping `agent → reject` here is what makes the no-bypass
+        // invariant hold even on the registry/default resolution path (which, unlike
+        // the declared-axis path, has no separate agent-degradation guard).
+        return conflict.committer.kind === 'agent'
+            ? { action: 'reject', reason: 'claim_conflict' }
+            : { action: 'allow', note: 'principal:not-blocked' };
     }
     return conflict.requestedMode === 'notify'
         ? { action: 'notify', reason: 'stale_notify_hold' }
@@ -53,8 +73,9 @@ export const capabilityPreemptPolicy = (conflict) => {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: reject; honor
- *                   `onStale: 'notify'` on a stale write)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human/system
+ *                   committer is allowed (never blocked), an agent rejects on a
+ *                   `claim_held`; on a stale write, honor `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/schema/diff.d.ts

@@ -133,6 +133,20 @@ export interface MigrationSignal {
     readonly model: string;
     readonly field?: string;
     readonly detail: string;
+    /**
+     * Reader-visibility context for a removal that shadows an existing artifact:
+     * the active schema this push is being diffed against. Lets the CLI show the
+     * baseline — version + WHEN it was pushed — so "incompatible" isn't a mystery
+     * (e.g. a first sandbox push diffed against a months-old production schema).
+     */
+    readonly shadowed?: {
+        readonly environment: string;
+        readonly version: number;
+        /** ISO timestamp the shadowed artifact was activated/pushed, or null. */
+        readonly pushedAt: string | null;
+        /** Who pushed it (e.g. `apikey:…`), or null. */
+        readonly pushedBy: string | null;
+    };
 }
 export interface MigrationClassification {
     /** Execute but may lose or risk data on a non-empty table. */

package/dist/surface.d.ts

@@ -23,7 +23,7 @@ export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "g
 export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
 /** Public keys of `AbloOptions`. `schema` is required; the rest are optional
  *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -51,6 +51,8 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'databaseUrl',
     'persistence',
     'transport',
+    'debug',
+    'logLevel',
     'authToken',
     'baseURL',
     'fetch',

package/dist/sync/SyncWebSocket.js

@@ -177,7 +177,7 @@ export class SyncWebSocket extends EventEmitter {
         // which is unreliable but the only signal available; in Node it returns true
         // (assume online) so the sidecar/agent path doesn't short-circuit here.
         if (!getContext().onlineStatus.isOnline()) {
-            getContext().logger.warn('onlineStatus reports offline, but attempting connection anyway');
+            getContext().logger.debug('onlineStatus reports offline, but attempting connection anyway');
         }
         this.isConnecting = true;
         this.isManualClose = false;

package/dist/sync/awaitClaimGrant.js

@@ -13,6 +13,7 @@
  * fake; `SyncWebSocket` satisfies it structurally.
  */
 import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+import { getContext } from '../context.js';
 export function awaitClaimGrant(transport, claimId, options) {
     return new Promise((resolve, reject) => {
         const unsubs = [];
@@ -28,12 +29,18 @@ export function awaitClaimGrant(transport, claimId, options) {
         // we waited in line, and reached the head → `claim_granted`. Either frame
         // means the lease is now ours; `waited` records which path it was.
         unsubs.push(transport.subscribe('claim_acquired', (p) => {
-            if (p?.claimId === claimId)
+            if (p?.claimId === claimId) {
+                getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
                 settle(() => resolve({ waited: false }));
+            }
         }));
         unsubs.push(transport.subscribe('claim_granted', (p) => {
-            if (p?.claimId === claimId)
+            if (p?.claimId === claimId) {
+                // Promoted to the head of the line — the creator's "it's the agent's
+                // turn now" moment after waiting behind a holder.
+                getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
                 settle(() => resolve({ waited: true }));
+            }
         }));
         if (options?.maxQueueDepth !== undefined) {
             const max = options.maxQueueDepth;

package/dist/sync/createClaimStream.js

@@ -24,6 +24,11 @@
 import { asyncIteratorFrom } from '../utils/asyncIterator.js';
 import { toMs } from '../utils/duration.js';
 import { descriptionFromMeta, participantKindFromWire, } from '../coordination/schema.js';
+import { getContext } from '../context.js';
+/** Readable target for the coordination trace: `documents:abc` / `documents:abc.title`. */
+function claimLabel(type, id, field) {
+    return field ? `${type}:${id}.${field}` : `${type}:${id}`;
+}
 export function createClaimStream(config, transport = null) {
     const { participantId } = config;
     // ── State: others' open claims, keyed by claimId ───────────────
@@ -37,6 +42,9 @@ export function createClaimStream(config, transport = null) {
     const queueByEntity = new Map();
     const entityKey = (type, id) => `${type}:${id}`;
     const EMPTY_QUEUE = Object.freeze([]);
+    // Last queue position we logged per own-claim, so advancing in line is traced
+    // once per change (not re-logged on every server re-fan of the same line).
+    const lastLoggedQueuePos = new Map();
     // ── Subscribers ──────────────────────────────────────────────────
     const listeners = new Set();
     const rejectionListeners = new Set();
@@ -122,6 +130,12 @@ export function createClaimStream(config, transport = null) {
         unsubs.push(t.subscribe('claim_rejected', (rejection) => {
             if (!rejection.claimId)
                 return;
+            if (ownClaims.has(rejection.claimId)) {
+                const tgt = rejection.target
+                    ? claimLabel(rejection.target.entityType, rejection.target.entityId, rejection.target.field)
+                    : rejection.claimId;
+                getContext().logger.info(`claim: rejected ${tgt}${rejection.heldBy ? ` — held by ${rejection.heldBy}` : ''}`, { claimId: rejection.claimId, reason: rejection.reason });
+            }
             // Drop the rejected own-claim so reconnect doesn't re-announce
             // a claim the server already rejected (would just spam both
             // sides with conflicts).
@@ -141,6 +155,10 @@ export function createClaimStream(config, transport = null) {
             const lost = payload;
             if (!lost.claimId)
                 return;
+            if (ownClaims.has(lost.claimId)) {
+                const c = ownClaims.get(lost.claimId);
+                getContext().logger.info(`claim: lost ${c ? claimLabel(c.entityType, c.entityId, c.field) : lost.claimId} (preempted or expired)`, { claimId: lost.claimId });
+            }
             // Drop the lost own-claim so reconnect doesn't re-announce a lease we
             // no longer hold.
             ownClaims.delete(lost.claimId);
@@ -166,6 +184,16 @@ export function createClaimStream(config, transport = null) {
                 queueByEntity.delete(key);
             else
                 queueByEntity.set(key, Object.freeze([...line]));
+            // If WE are in this line, trace our position (the "agent queued behind a
+            // claim" moment) — once per position change, so advancing is visible.
+            const ourIndex = line.findIndex((c) => ownClaims.has(c.id));
+            if (ourIndex >= 0) {
+                const ourId = line[ourIndex].id;
+                if (lastLoggedQueuePos.get(ourId) !== ourIndex) {
+                    lastLoggedQueuePos.set(ourId, ourIndex);
+                    getContext().logger.info(`claim: queued for ${claimLabel(p.target.type, p.target.id)} — position ${ourIndex + 1} of ${line.length}, waiting`, { claimId: ourId });
+                }
+            }
             notifyListeners();
         }));
         // (3) On reconnect, re-announce every open self-claim — the
@@ -251,6 +279,9 @@ export function createClaimStream(config, transport = null) {
         };
         ownClaims.set(claimId, claim);
         sendBegin(claimId, claim);
+        // Coordination trace (info): the creator can SEE their human/agent claims.
+        getContext().logger.info(`claim: requesting ${claimLabel(claim.entityType, claim.entityId, claim.field)} for "${claim.reason}"` +
+            (claim.queue ? ' (will queue if contended)' : ''), { claimId });
         let revoked = false;
         const revoke = () => {
             if (revoked)
@@ -258,6 +289,7 @@ export function createClaimStream(config, transport = null) {
             revoked = true;
             ownClaims.delete(claimId);
             sendAbandon(claimId, claim);
+            getContext().logger.info(`claim: released ${claimLabel(claim.entityType, claim.entityId, claim.field)}`, { claimId });
         };
         return {
             object: 'claim',

package/dist/wire/errorEnvelope.d.ts

@@ -8,6 +8,19 @@ export interface ErrorEnvelope {
     readonly message: string;
     readonly doc_url?: string;
     readonly request_id?: string;
+    /** Aggregate field-level failures — so one 4xx can report EVERY invalid input
+     *  at once (schema push, batch commit, CLI-arg validation) instead of failing
+     *  on the first. `param` stays the single-field convenience case. (RFC 9457
+     *  `errors[]` / JSON:API `errors[]` / Google `BadRequest.fieldViolations[]`.) */
+    readonly errors?: ReadonlyArray<{
+        readonly code?: string;
+        readonly message: string;
+        readonly param?: string;
+    }>;
+    /** Typed-details slot: `AbloError.toJSON()` spreads its `details` (e.g.
+     *  `missingIds`, `conflicts`, `retryAfterSeconds`) as top-level members.
+     *  Consumers MUST ignore members they don't recognize (forward-compat). */
+    readonly [key: string]: unknown;
 }
 /** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
  *  match status semantics (a validation error is a 400, a permission error a