@abloatai/ablo 0.18.0 → 0.20.0

package/dist/client/auth.d.ts

@@ -49,6 +49,29 @@ export interface AuthResolveInput {
 export declare function readProcessEnv(): Record<string, string | undefined>;
 export declare function resolveApiKey(input: AuthResolveInput): string | ApiKeySetter | null;
 export declare function resolveAuthToken(input: AuthResolveInput): string | null;
+type CliMode = 'sandbox' | 'production';
+type StaticApiKeySource = 'option' | 'env';
+interface StaticApiKey {
+    readonly key: string;
+    readonly source: StaticApiKeySource;
+}
+interface CliCredentialSnapshot {
+    readonly mode: CliMode;
+    readonly activeProfile: string;
+    readonly storedKey?: string;
+}
+export interface CliKeyMismatch {
+    readonly source: StaticApiKeySource;
+    readonly configuredKeyPrefix: string;
+    readonly configuredMode?: CliMode;
+    readonly cliMode: CliMode;
+    readonly storedKeyPrefix?: string;
+    readonly kind: 'mode_mismatch' | 'key_override';
+    readonly message: string;
+}
+/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+export declare function modeFromApiKey(key: string): CliMode | undefined;
+export declare function describeCliKeyMismatch(configured: StaticApiKey, cli: CliCredentialSnapshot): CliKeyMismatch | null;
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
@@ -63,6 +86,8 @@ export declare function resolveAuthToken(input: AuthResolveInput): string | null
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
 export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
+export declare function warnIfDatabaseUrlDeprecated(input: AuthResolveInput, warn?: (message: string) => void): void;
+export declare function warnIfCliKeyMismatch(input: AuthResolveInput, warn?: (message: string) => void): Promise<void>;
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
 export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
 export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";
@@ -108,3 +133,4 @@ export declare function resolveBootstrapBaseUrl(input: {
     readonly url: string;
     readonly bootstrapBaseUrl?: string;
 }): string;
+export {};

package/dist/client/auth.js

@@ -28,6 +28,160 @@ export function resolveApiKey(input) {
 export function resolveAuthToken(input) {
     return input.options.authToken ?? null;
 }
+function keyPrefix(key) {
+    return `${key.slice(0, 12)}…`;
+}
+/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+export function modeFromApiKey(key) {
+    if (/^(sk|rk)_test_/.test(key))
+        return 'sandbox';
+    if (/^(sk|rk)_live_/.test(key))
+        return 'production';
+    return undefined;
+}
+function resolveStaticApiKey(input) {
+    if (typeof input.options.apiKey === 'string') {
+        return { key: input.options.apiKey, source: 'option' };
+    }
+    if (input.options.apiKey !== undefined && input.options.apiKey !== null) {
+        return null;
+    }
+    const envKey = input.env.ABLO_API_KEY;
+    if (typeof envKey === 'string' && envKey.length > 0) {
+        return { key: envKey, source: 'env' };
+    }
+    return null;
+}
+function readProfileKeys(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const profiles = {};
+    for (const [name, raw] of Object.entries(value)) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const row = raw;
+        const sandbox = row.sandbox;
+        const production = row.production;
+        profiles[name] = {
+            sandbox: sandbox && typeof sandbox === 'object' ? sandbox : undefined,
+            production: production && typeof production === 'object' ? production : undefined,
+        };
+    }
+    return profiles;
+}
+function legacyProfileKeys(value) {
+    if (!value)
+        return { sandbox: undefined, production: undefined };
+    const sandbox = value.sandbox;
+    const production = value.production;
+    if ((sandbox && typeof sandbox === 'object') ||
+        (production && typeof production === 'object')) {
+        return {
+            sandbox: sandbox && typeof sandbox === 'object' ? sandbox : undefined,
+            production: production && typeof production === 'object' ? production : undefined,
+        };
+    }
+    if (typeof value.apiKey === 'string') {
+        return { sandbox: { apiKey: value.apiKey }, production: undefined };
+    }
+    return { sandbox: undefined, production: undefined };
+}
+function normalizeCliMode(value) {
+    return value === 'sandbox' || value === 'production' ? value : undefined;
+}
+function activeProjectSlug(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const slug = value.slug;
+    return typeof slug === 'string' && slug.length > 0 ? slug : undefined;
+}
+function importNodeBuiltin(specifier) {
+    return import(specifier);
+}
+async function readJsonIfPresent(path) {
+    try {
+        const { readFile } = await importNodeBuiltin('node:fs/promises');
+        const text = await readFile(path, 'utf8');
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readCliCredentialSnapshot(env) {
+    const processLike = globalThis.process;
+    if (!processLike?.versions?.node)
+        return null;
+    if (typeof window !== 'undefined')
+        return null;
+    const [{ homedir }, { join }] = await Promise.all([
+        importNodeBuiltin('node:os'),
+        importNodeBuiltin('node:path'),
+    ]);
+    const dir = env.ABLO_CONFIG_DIR
+        ?? (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, 'ablo') : join(homedir(), '.config', 'ablo'));
+    const [cfg, creds] = await Promise.all([
+        readJsonIfPresent(join(dir, 'config.json')),
+        readJsonIfPresent(join(dir, 'credentials.json')),
+    ]);
+    const mode = normalizeCliMode(cfg?.mode) ?? normalizeCliMode(creds?.mode);
+    const activeProfile = activeProjectSlug(cfg?.activeProject) ?? 'default';
+    const profiles = {
+        ...readProfileKeys(creds?.profiles),
+        ...readProfileKeys(cfg?.profiles),
+    };
+    if (!profiles[activeProfile]) {
+        const legacy = { ...legacyProfileKeys(cfg), ...legacyProfileKeys(creds) };
+        if (legacy.sandbox?.apiKey || legacy.production?.apiKey) {
+            profiles[activeProfile] = legacy;
+        }
+    }
+    const effectiveMode = mode ?? (Object.keys(profiles).length > 0 ? 'sandbox' : undefined);
+    if (!effectiveMode)
+        return null;
+    return {
+        mode: effectiveMode,
+        activeProfile,
+        ...(profiles[activeProfile]?.[effectiveMode]?.apiKey
+            ? { storedKey: profiles[activeProfile][effectiveMode].apiKey }
+            : {}),
+    };
+}
+export function describeCliKeyMismatch(configured, cli) {
+    const configuredMode = modeFromApiKey(configured.key);
+    const configuredKeyPrefix = keyPrefix(configured.key);
+    const storedKeyPrefix = cli.storedKey ? keyPrefix(cli.storedKey) : undefined;
+    const sourceLabel = configured.source === 'env' ? 'ABLO_API_KEY' : 'configured apiKey';
+    if (configuredMode && configuredMode !== cli.mode) {
+        return {
+            source: configured.source,
+            configuredKeyPrefix,
+            configuredMode,
+            cliMode: cli.mode,
+            ...(storedKeyPrefix ? { storedKeyPrefix } : {}),
+            kind: 'mode_mismatch',
+            message: `${sourceLabel} is a ${configuredMode} key (${configuredKeyPrefix}) but the Ablo CLI is in ` +
+                `${cli.mode} mode${storedKeyPrefix ? ` (active stored key ${storedKeyPrefix})` : ''}. ` +
+                `Requests will use ${configuredMode}. Use the ${cli.mode} key, unset ABLO_API_KEY, ` +
+                `or run \`ablo mode ${configuredMode}\` intentionally.`,
+        };
+    }
+    if (configured.source === 'env' && cli.storedKey && configured.key !== cli.storedKey) {
+        return {
+            source: configured.source,
+            configuredKeyPrefix,
+            ...(configuredMode ? { configuredMode } : {}),
+            cliMode: cli.mode,
+            storedKeyPrefix,
+            kind: 'key_override',
+            message: `ABLO_API_KEY (${configuredKeyPrefix}) overrides the CLI's stored active ${cli.mode} key ` +
+                `(${storedKeyPrefix}). Requests will use the environment key. Unset ABLO_API_KEY to use ` +
+                '`ablo status` / `ablo mode` credentials.',
+        };
+    }
+    return null;
+}
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
@@ -85,6 +239,60 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
     else if (typeof console !== 'undefined')
         console.warn('[Ablo]', message);
 }
+/**
+ * One-time deprecation nudge for the `databaseUrl` direct connector.
+ *
+ * `databaseUrl` registers the `dedicated` storage mode — Ablo opens a pool INTO
+ * the caller's Postgres and writes into it directly. That is the operate-their-
+ * database posture we are moving off. Ablo is Stripe-shaped: it hosts only the
+ * transaction log (the ordered sync_deltas) + coordination, never your data — your
+ * rows always live in your own database. The supported path is the signed Data
+ * Source endpoint (`dataSource(...)`), where your app owns the write and your
+ * credentials never leave it. See docs/plans/stripe-shaped-storage-posture.md.
+ *
+ * Still honored at runtime so existing integrations keep working; this only warns
+ * once per process (so it never spams) and falls back to `console.warn` when no
+ * logger is supplied (the `transport: 'http'`/`'api'` client has none).
+ */
+let warnedDatabaseUrlDeprecated = false;
+export function warnIfDatabaseUrlDeprecated(input, warn) {
+    if (warnedDatabaseUrlDeprecated)
+        return;
+    if (input.options.databaseUrl == null)
+        return;
+    warnedDatabaseUrlDeprecated = true;
+    const message = '`databaseUrl` (the direct connector) is deprecated and will be removed from ' +
+        'the supported path. It lets Ablo dial into your database; we are moving off ' +
+        'that. Ablo hosts only the transaction log — your data stays in your DB. Expose ' +
+        'a signed Data Source endpoint (`dataSource(...)`) so your app owns the write, ' +
+        'or self-host the engine to keep the log in your infra too. ' +
+        'See docs/plans/stripe-shaped-storage-posture.md.';
+    if (warn)
+        warn(message);
+    else if (typeof console !== 'undefined')
+        console.warn('[Ablo]', message);
+}
+let warnedCliKeyMismatch = false;
+export async function warnIfCliKeyMismatch(input, warn) {
+    if (warnedCliKeyMismatch)
+        return;
+    if (input.env.NODE_ENV === 'production')
+        return;
+    const configured = resolveStaticApiKey(input);
+    if (!configured)
+        return;
+    const cli = await readCliCredentialSnapshot(input.env);
+    if (!cli)
+        return;
+    const mismatch = describeCliKeyMismatch(configured, cli);
+    if (!mismatch)
+        return;
+    warnedCliKeyMismatch = true;
+    if (warn)
+        warn(mismatch.message);
+    else if (typeof console !== 'undefined')
+        console.warn('[Ablo]', mismatch.message);
+}
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
 export const ABLO_DEFAULT_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;

package/dist/client/createModelProxy.d.ts

@@ -22,7 +22,7 @@ import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import type { JoinedParticipant } from '../sync/participants.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Claim, ClaimHandle, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
+import type { Duration, Claim, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
@@ -90,7 +90,7 @@ export interface ModelCollaboration<T> {
             range?: TargetRange;
             meta?: Record<string, unknown>;
         };
-        /** Human-readable phase (`'editing'`); wire field is `action`. */
+        /** Human-readable phase (`'editing'`). */
         reason: string;
         ttl?: Duration;
         /**
@@ -101,7 +101,7 @@ export interface ModelCollaboration<T> {
         queue?: boolean;
         /** Reject (don't wait) if the queue is already this deep when we join. */
         maxQueueDepth?: number;
-    }): Promise<ClaimHandle>;
+    }): Promise<Claim>;
     createSnapshot(modelKey: string, id: string): Snapshot;
     /**
      * Current coordination state on a target — who (if anyone) holds it.
@@ -185,7 +185,7 @@ export interface ModelCollaboration<T> {
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Human-readable phase shown to observers while held. Defaults to
-     *  `'editing'`. The same word on every claim surface; wire field is `action`. */
+     *  `'editing'`. The same word on every claim surface. */
     reason?: string;
     /** Peer-visible explanation of the work being performed. */
     description?: string;
@@ -258,7 +258,7 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
  * lease id and snapshot watermark for attribution + stale protection.
  */
-export type { ClaimHandle };
+export type { Claim };
 export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 /**
  * The coordination surface for a model, exposed as a callable namespace.
@@ -312,7 +312,7 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
      */
     reorder(params: ClaimReorderParams<T>): void;
     /** Release a manual claim handle early. Single-write claims auto-release. */
-    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
+    release(params: ClaimLookupParams<T> | Claim<T>): Promise<void>;
 }
 /**
  * The awaited form of a claim method: a synchronous return becomes a `Promise`,
@@ -321,8 +321,13 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
  */
 export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
 export interface ClaimApi<T> extends ClaimReadApi<T> {
-    /** Take a claim and get an explicit held-work handle back. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+    /**
+     * Take a claim and get an explicit held-work handle back. Returns a
+     * {@link Claim} — `data` (and `readAt`) are guaranteed present
+     * because this door always re-reads the row under the lease, so callers use
+     * `handle.data` directly without a guard.
+     */
+    (params: ClaimParams<T>): Promise<Claim<T>>;
 }
 export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
@@ -330,16 +335,16 @@ export interface ModelRetrieveParams extends ServerRetrieveOptions {
 export interface ModelCreateParams<T, CreateInput> extends MutationOptions {
     readonly data: CreateInput;
     readonly id?: string | null;
-    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
 export interface ModelUpdateParams<T> extends MutationOptions {
     readonly id: string;
     readonly data: Partial<T>;
-    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
 export interface ModelDeleteParams<T> extends MutationOptions {
     readonly id: string;
-    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
 /** Options for the WebSocket-only `ablo.<model>.watch(ids, options?)`. */
 export interface WatchOptions {

package/dist/client/createModelProxy.js

@@ -39,7 +39,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // with the commit op's model name; a lease recorded under the schema key
     // never collides with it — which silently disarmed the guard for every
     // model whose schema key differs from its typename (i.e. nearly all of
-    // them, plural key vs singular typename). Public surfaces (ClaimHandle.
+    // them, plural key vs singular typename). Public surfaces (Claim.
     // target.model) keep the schema key; only the wire/coordination targets
     // use this.
     const wireModel = registeredModelName.toLowerCase();
@@ -90,7 +90,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
-        typeof value.claimId === 'string' &&
+        typeof value.id === 'string' &&
         typeof value.release === 'function';
     const claimMeta = (options) => {
         if (!options?.description)
@@ -131,7 +131,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         if (!held)
             return;
         activeClaims.delete(id);
-        await held.lease.release();
+        await held.lease.release?.();
     };
     const takeClaim = async (params) => {
         if (!collaboration) {
@@ -214,7 +214,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         const reason = options?.reason ?? 'editing';
-        // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
+        // The self-claim's `ClaimTarget` mirrors what a peer's `claim.state` would
         // report (`state` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
         const selfTarget = {
@@ -235,7 +235,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             expiresAt,
         });
         const target = {
-            model: schemaKey,
+            type: schemaKey,
             id,
             ...(options?.field ? { field: options.field } : {}),
             ...(options?.path ? { path: options.path } : {}),
@@ -245,7 +245,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const release = () => releaseClaim(id);
         return {
             object: 'claim',
-            claimId: lease.claimId,
+            id: lease.id,
             readAt: snapshot.stamp,
             target,
             reason,
@@ -278,7 +278,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             if (own) {
                 return {
                     object: 'claim',
-                    id: own.lease.claimId,
+                    id: own.lease.id,
                     status: 'active',
                     target: own.target,
                     reason: own.reason,
@@ -403,7 +403,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             const effective = {
                 ...opts,
                 ...(autoLease ? { claim: autoLease } : {}),
-                ...(isClaimHandle(claim) ? { claim: { id: claim.claimId } } : {}),
+                ...(isClaimHandle(claim) ? { claim: { id: claim.id } } : {}),
             };
             try {
                 syncClient.add(model, effective);
@@ -411,7 +411,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 return modelAsRow(model);
             }
             finally {
-                await autoLease?.release().catch(() => { });
+                await autoLease?.release?.().catch(() => { });
             }
         }),
         update: guard(async (params) => {
@@ -422,7 +422,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     return await operations.update({ ...params, claim: handle });
                 }
                 finally {
-                    await handle.release();
+                    await handle.release?.();
                 }
             }
             const { id } = params;
@@ -439,7 +439,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
-                    claimRef: { id: claimed.lease.claimId },
+                    claimRef: { id: claimed.lease.id },
                     ...opts,
                 }
                 : {
@@ -454,7 +454,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         }
                         : {}),
                     ...opts,
-                    ...(handle ? { claim: { id: handle.claimId } } : {}),
+                    ...(handle ? { claim: { id: handle.id } } : {}),
                 };
             // Local user update: `applyChanges` keeps change tracking ON so
             // the edited fields land in `modifiedProperties` and actually get
@@ -473,7 +473,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     await operations.delete({ ...params, claim: handle });
                 }
                 finally {
-                    await handle.release();
+                    await handle.release?.();
                 }
                 return;
             }
@@ -489,7 +489,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
-                    claimRef: { id: claimed.lease.claimId },
+                    claimRef: { id: claimed.lease.id },
                     ...opts,
                 }
                 : {
@@ -501,7 +501,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         }
                         : {}),
                     ...opts,
-                    ...(handle ? { claim: { id: handle.claimId } } : {}),
+                    ...(handle ? { claim: { id: handle.id } } : {}),
                 };
             syncClient.delete(model, effective);
             await waitForMutation(model, effective);

package/dist/client/sessionMint.d.ts

@@ -6,6 +6,16 @@ export interface MintSessionContext {
     readonly apiKey: string;
     readonly baseUrl: string;
     readonly fetch?: typeof fetch;
+    /**
+     * Schema-key → wire typename map, supplied ONLY by the schema client
+     * (`Ablo`). A capability is scoped by the lowercased TYPENAME the Hub
+     * checks, but `can` is keyed by schema key — so `can: { documents: ['update'] }`
+     * on a model whose `typename` is overridden to `Document` must mint
+     * `document.update`, not `documents.update` (else the Hub denies it with
+     * `capability_scope_denied`). The schemaless `ApiClient` omits this map:
+     * there the `can` key already IS the wire token, so no translation applies.
+     */
+    readonly modelTypenames?: Readonly<Record<string, string>>;
 }
 /**
  * Mint a session token from an already-resolved `sk_` credential + base URL.

package/dist/client/sessionMint.js

@@ -63,7 +63,14 @@ export async function mintSession(params, ctx) {
             userMeta: params.userMeta ?? { id: res.participantId },
         };
     }
-    const operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
+    const operations = Object.entries(params.can).flatMap(([model, ops]) => {
+        // Translate the schema key the developer used in `can` to the wire
+        // typename the Hub gates on — see `modelTypenames` above. Falls back to
+        // the key when no map is supplied (schemaless client) or the key isn't
+        // in it, preserving the prior behaviour exactly for those callers.
+        const ns = ctx.modelTypenames?.[model] ?? model;
+        return (ops ?? []).map((op) => `${ns.toLowerCase()}.${op}`);
+    });
     const res = await exchangeApiKey({
         apiKey,
         baseUrl,

package/dist/coordination/schema.d.ts

@@ -209,7 +209,7 @@ export declare const wireClaimSummarySchema: z.ZodObject<{
     entityId: z.ZodString;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    action: z.ZodString;
+    reason: z.ZodString;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -227,7 +227,7 @@ export declare const claimErrorSchema: z.ZodObject<{
         entityId: z.ZodString;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        action: z.ZodString;
+        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
     }, z.core.$strip>>;
@@ -237,7 +237,7 @@ export type ClaimError = z.infer<typeof claimErrorSchema>;
 /**
  * A declared pending-mutation claim — the unit broadcast in presence
  * `activeClaims`. Clients supply the descriptive `targetRef` fields, an
- * `action`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
+ * explanatory `reason`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
  * `expiresAt` and may set `status` / `error`.
  *
  * `status` and `error` are OPTIONAL: this single shape serves both the
@@ -259,7 +259,7 @@ export declare const wireClaimSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    action: z.ZodString;
+    reason: z.ZodString;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
     status: z.ZodOptional<z.ZodEnum<{
@@ -280,7 +280,7 @@ export declare const wireClaimSchema: z.ZodObject<{
             entityId: z.ZodString;
             meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             claimId: z.ZodString;
-            action: z.ZodString;
+            reason: z.ZodString;
             declaredAt: z.ZodNumber;
             expiresAt: z.ZodNumber;
         }, z.core.$strip>>;
@@ -313,7 +313,7 @@ export declare const claimRejectionSchema: z.ZodObject<{
         entityId: z.ZodString;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        action: z.ZodString;
+        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
     }, z.core.$strip>>;
@@ -385,7 +385,7 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
 }, z.core.$strip>>;
 export type ModelClaim = z.infer<typeof modelClaimSchema>;
 /**
- * `claim_begin` payload (client → server). The descriptive target + action,
+ * `claim_begin` payload (client → server). The descriptive target + reason,
  * plus an optional duration hint and the opt-in fair-queue flag. The server
  * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
  * shape — this is exactly what the WS ingest validates.
@@ -403,7 +403,7 @@ export declare const claimBeginPayloadSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    action: z.ZodString;
+    reason: z.ZodString;
     estimatedMs: z.ZodOptional<z.ZodNumber>;
     queue: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
@@ -585,7 +585,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
         field: z.ZodOptional<z.ZodString>;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        action: z.ZodString;
+        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
         status: z.ZodOptional<z.ZodEnum<{
@@ -606,7 +606,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
                 entityId: z.ZodString;
                 meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 claimId: z.ZodString;
-                action: z.ZodString;
+                reason: z.ZodString;
                 declaredAt: z.ZodNumber;
                 expiresAt: z.ZodNumber;
             }, z.core.$strip>>;

package/dist/coordination/schema.js

@@ -209,8 +209,8 @@ export const claimStatusSchema = z.enum([
 ]);
 const wireClaimBaseSchema = targetRefSchema.extend({
     claimId: z.string(),
-    /** Verb the agent expects: 'update' | 'create' | 'editing' | 'reviewing' … */
-    action: z.string(),
+    /** Human-readable phase: 'editing' | 'reviewing' | 'forecasting' … */
+    reason: z.string(),
     /** Server-stamped declaration time (epoch ms). */
     declaredAt: z.number(),
     /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
@@ -219,7 +219,7 @@ const wireClaimBaseSchema = targetRefSchema.extend({
 });
 export const wireClaimSummarySchema = wireClaimBaseSchema.pick({
     claimId: true,
-    action: true,
+    reason: true,
     declaredAt: true,
     expiresAt: true,
     entityType: true,
@@ -243,7 +243,7 @@ export const claimErrorSchema = z.object({
 /**
  * A declared pending-mutation claim — the unit broadcast in presence
  * `activeClaims`. Clients supply the descriptive `targetRef` fields, an
- * `action`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
+ * explanatory `reason`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
  * `expiresAt` and may set `status` / `error`.
  *
  * `status` and `error` are OPTIONAL: this single shape serves both the
@@ -298,8 +298,7 @@ export const modelClaimSchema = z
     id: z.string(),
     actor: z.string(),
     participantKind: wireParticipantKindSchema,
-    /** Human-readable phase (`'editing'`). The public SDK field; the WS/HTTP
-     *  wire carries the same value as `action` (healed on read). */
+    /** Human-readable phase (`'editing'`). */
     reason: z.string(),
     description: z.string().optional(),
     field: z.string().optional(),
@@ -310,14 +309,14 @@ export const modelClaimSchema = z
 })
     .readonly();
 /**
- * `claim_begin` payload (client → server). The descriptive target + action,
+ * `claim_begin` payload (client → server). The descriptive target + reason,
  * plus an optional duration hint and the opt-in fair-queue flag. The server
  * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
  * shape — this is exactly what the WS ingest validates.
  */
 export const claimBeginPayloadSchema = targetRefSchema.extend({
     claimId: z.string(),
-    action: z.string(),
+    reason: z.string(),
     /** Hint for `expiresAt`; the server caps it. */
     estimatedMs: z.number().optional(),
     /**