@abloatai/ablo 0.34.1 → 0.35.0

package/dist/testing/mocks/MockMutationExecutor.js

@@ -5,7 +5,7 @@
  * live backend. Each successful commit hands back an incrementing `lastSyncId`,
  * so tests can drive the delta-confirmation flow that depends on those ids.
  */
-import { AbloError } from '../../errors.js';
+import { AbloError } from '../../transaction/errors.js';
 export class MockMutationExecutor {
     /** Every captured call, in the order it was made. Assertions read from this list. */
     calls = [];
@@ -25,7 +25,7 @@ export class MockMutationExecutor {
         this._syncId = options.initialSyncId ?? 1;
         this._shouldSucceed = options.shouldSucceed ?? true;
         this._latencyMs = options.latencyMs ?? 0;
-        this._status = options.status;
+        this._status = options.status ?? 'confirmed';
         this._correlationId = options.correlationId;
         this._notifications = options.notifications;
         this._missingIds = options.missingIds;
@@ -91,7 +91,7 @@ export class MockMutationExecutor {
         this._syncId = options?.initialSyncId ?? 1;
         this._shouldSucceed = options?.shouldSucceed ?? true;
         this._latencyMs = options?.latencyMs ?? 0;
-        this._status = options?.status;
+        this._status = options?.status ?? 'confirmed';
         this._correlationId = options?.correlationId;
         this._notifications = options?.notifications;
         this._missingIds = options?.missingIds;
@@ -118,19 +118,13 @@ export class MockMutationExecutor {
                 ...(this._missingIds ? { missingIds: this._missingIds } : {}),
             };
         }
-        const evidence = {
+        return {
+            lastSyncId: syncId,
+            status: 'confirmed',
+            ...(this._correlationId ? { correlationId: this._correlationId } : {}),
             ...(this._notifications ? { notifications: this._notifications } : {}),
             ...(this._missingIds ? { missingIds: this._missingIds } : {}),
         };
-        if (this._status === 'confirmed') {
-            return {
-                lastSyncId: syncId,
-                status: 'confirmed',
-                ...(this._correlationId ? { correlationId: this._correlationId } : {}),
-                ...evidence,
-            };
-        }
-        return { lastSyncId: syncId, ...evidence };
     }
     async executeCreate(modelName, id, input, clientMutationId) {
         this._capture('executeCreate', { modelName, modelId: id, input, clientMutationId });
@@ -141,7 +135,7 @@ export class MockMutationExecutor {
         this._capture('executeUpdate', { modelName, modelId, input: data, clientMutationId });
         await this._maybeDelay();
         this._maybeThrow('executeUpdate');
-        return { lastSyncId: this._syncId++ };
+        return { lastSyncId: this._syncId++, status: 'confirmed' };
     }
     async executeDelete(modelName, modelId, clientMutationId) {
         this._capture('executeDelete', { modelName, modelId, clientMutationId });

package/dist/testing/mocks/MockSyncContext.d.ts

@@ -1,32 +1,32 @@
 /**
- * Assembles a ready-to-use {@link SyncEngineContext} for tests. The context
+ * Assembles a ready-to-use {@link RuntimeContext} for tests. The context
  * bundles every dependency the engine needs — logger, network monitor,
  * mutation executor, and configuration — so a test can start the engine
  * without a real backend. {@link createTestContext} is the entry point: it
- * wires the mocks, installs the context globally through {@link initSyncEngine},
+ * wires the mocks, installs the context globally through {@link initRuntime},
  * and returns handles to each mock for assertions.
  */
-import type { SyncEngineContext } from '../../SyncEngineContext.js';
-import type { SyncLogger, SyncObservabilityProvider, SessionErrorDetector, SyncEngineConfig } from '../../interfaces/index.js';
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { Logger, ObservabilityProvider, SessionErrorDetector, RuntimeConfig } from '../../interfaces/index.js';
 import { MockMutationExecutor } from './MockMutationExecutor.js';
 import { MockNetworkMonitor } from './MockNetworkMonitor.js';
 export interface TestContextOptions {
     /** Replaces the default no-op logger. */
-    logger?: SyncLogger;
+    logger?: Logger;
     /** Replaces the default no-op observability provider. */
-    observability?: SyncObservabilityProvider;
+    observability?: ObservabilityProvider;
     /** Replaces the detector that decides whether an error means the session has expired. */
     sessionErrorDetector?: SessionErrorDetector;
     /** Options forwarded to the {@link MockMutationExecutor} that the context creates. */
     mutationExecutorOptions?: ConstructorParameters<typeof MockMutationExecutor>[0];
-    /** A partial {@link SyncEngineConfig} merged over the defaults. */
-    config?: Partial<SyncEngineConfig>;
+    /** A partial {@link RuntimeConfig} merged over the defaults. */
+    config?: Partial<RuntimeConfig>;
     /** Starts the network monitor offline. Defaults to online. */
     startOffline?: boolean;
 }
 export interface TestContextResult {
     /** The assembled context that {@link createTestContext} installed globally. */
-    context: SyncEngineContext;
+    context: RuntimeContext;
     /** Handles to the underlying mocks, so tests can drive them and assert on them. */
     mocks: {
         mutationExecutor: MockMutationExecutor;
@@ -36,8 +36,8 @@ export interface TestContextResult {
     cleanup: () => void;
 }
 /**
- * Builds a {@link SyncEngineContext} with every mock pre-wired and installs it
- * globally through {@link initSyncEngine}, so code under test reaches the engine
+ * Builds a {@link RuntimeContext} with every mock pre-wired and installs it
+ * globally through {@link initRuntime}, so code under test reaches the engine
  * the same way it would in production. Returns the context, the mock handles,
  * and a cleanup function to call when the test finishes.
  *

package/dist/testing/mocks/MockSyncContext.js

@@ -1,20 +1,20 @@
 /**
- * Assembles a ready-to-use {@link SyncEngineContext} for tests. The context
+ * Assembles a ready-to-use {@link RuntimeContext} for tests. The context
  * bundles every dependency the engine needs — logger, network monitor,
  * mutation executor, and configuration — so a test can start the engine
  * without a real backend. {@link createTestContext} is the entry point: it
- * wires the mocks, installs the context globally through {@link initSyncEngine},
+ * wires the mocks, installs the context globally through {@link initRuntime},
  * and returns handles to each mock for assertions.
  */
-import { noopLogger, noopObservability, noopAnalytics, defaultSessionErrorDetector, emptyConfig, } from '../../SyncEngineContext.js';
-import { initSyncEngine, resetSyncEngine } from '../../context.js';
-import { ModelRegistry, setActiveRegistry, hasActiveRegistry, clearActiveRegistry, } from '../../ModelRegistry.js';
+import { noopLogger, noopObservability, noopAnalytics, defaultSessionErrorDetector, emptyConfig, } from '../../RuntimeContext.js';
+import { initRuntime, resetRuntime } from '../../context.js';
+import { ModelRegistry, getActiveRegistry, setActiveRegistry, hasActiveRegistry, clearActiveRegistry, } from '../../ModelRegistry.js';
 import { registerTestModels } from '../fixtures/models.js';
 import { MockMutationExecutor } from './MockMutationExecutor.js';
 import { MockNetworkMonitor } from './MockNetworkMonitor.js';
 /**
- * Builds a {@link SyncEngineContext} with every mock pre-wired and installs it
- * globally through {@link initSyncEngine}, so code under test reaches the engine
+ * Builds a {@link RuntimeContext} with every mock pre-wired and installs it
+ * globally through {@link initRuntime}, so code under test reaches the engine
  * the same way it would in production. Returns the context, the mock handles,
  * and a cleanup function to call when the test finishes.
  *
@@ -35,6 +35,7 @@ export function createTestContext(options = {}) {
         modelCreatePriority: options.config?.modelCreatePriority ?? emptyConfig.modelCreatePriority,
     };
     const context = {
+        getModelMetadata: (name) => (hasActiveRegistry() ? getActiveRegistry().getMetadata(name) : undefined),
         logger: options.logger ?? noopLogger,
         observability: options.observability ?? noopObservability,
         analytics: noopAnalytics,
@@ -43,7 +44,7 @@ export function createTestContext(options = {}) {
         mutationExecutor,
         config,
     };
-    initSyncEngine(context);
+    initRuntime(context);
     // Bootstrap a default ModelRegistry with test models if none is active.
     // Tests that manage their own registry call setActiveRegistry before this.
     const bootstrappedRegistry = !hasActiveRegistry();
@@ -59,7 +60,7 @@ export function createTestContext(options = {}) {
             networkMonitor,
         },
         cleanup: () => {
-            resetSyncEngine();
+            resetRuntime();
             // Leave the active ModelRegistry in place on purpose. Async callbacks
             // from in-flight transactions can call Model.toJSON() after a test's
             // teardown has run; keeping the default registry available keeps those

package/dist/testing/mocks/MockSyncStore.js

@@ -4,7 +4,7 @@
  * test made — all without a real sync backend.
  */
 import { ViewRegistry } from '../../core/ViewRegistry.js';
-import { AbloValidationError } from '../../errors.js';
+import { AbloValidationError } from '../../transaction/errors.js';
 /**
  * An in-memory implementation of {@link SyncStoreContract}. Seed rows with
  * {@link MockSyncStore.setModels}, then read and write through the contract

package/dist/testing/mocks/MockWebSocket.d.ts

@@ -3,8 +3,8 @@
  * event interface of the real connection without opening a socket, so tests
  * can drive connection changes, deltas, and bootstrap hints by hand.
  */
-import type { SyncActionType } from '../../types/index.js';
-import type { BootstrapReason } from '../../wire/bootstrapReason.js';
+import type { SyncActionType } from '../../stores/syncAction.js';
+import type { BootstrapReason } from '../../transaction/wire/bootstrapReason.js';
 /** The shape of a single delta — one change the server pushes to the client. */
 export interface MockDelta {
     id: number;

package/dist/transaction/ablo.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `Ablo` — the entry point to the coordination layer.
+ *
+ * The factory constructs the stateless client: typed model resources, commits,
+ * claims, and session minting over request/response HTTP. It holds no socket,
+ * no store, and no local copy of anything — the bearer credential is the
+ * identity and the server resolves it on every request. This is the client a
+ * server-side actor installs: an agent, a worker, a cron job, a route handler.
+ *
+ * ```ts
+ * import { Ablo } from '@abloatai/ablo';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * await ablo.tasks.update({ id: taskId, data: { status: 'done' } });
+ * ```
+ *
+ * The reactive materialiser — local store, live queries, presence rendering —
+ * is the consumer package's entry point (`@abloatai/ablo`), which layers
+ * above this one and shares the same `ablo.<model>` surface (ADR 0016).
+ */
+import { type AbloHttpClient, type AbloHttpClientOptions } from './transport/httpClient.js';
+import type { SchemaRecord } from './schema/schema.js';
+import type * as _Streams from './types/streams.js';
+import type * as _SchemaTypes from './schema/schema.js';
+import type * as _Global from './types/global.js';
+import type * as _Policy from './policy/types.js';
+import type * as _Http from './resources/httpResources.js';
+/**
+ * Create a coordination-layer client in one call.
+ *
+ * The core carries one transport today — request/response HTTP — so
+ * `transport: 'http'` is accepted for symmetry with the reactive package's
+ * factory and may be omitted. The duplex transport joins this slot when the
+ * socket carve lands (ADR 0016, follow-up 3a).
+ */
+export declare function Ablo<const S extends SchemaRecord>(options: AbloHttpClientOptions<S> & {
+    transport?: 'http';
+}): AbloHttpClient<S>;
+export declare namespace Ablo {
+    type ClaimTarget = _Streams.ClaimTarget;
+    type PresenceTarget = _Streams.PresenceTarget;
+    type Duration = _Streams.Duration;
+    type Peer = _Streams.Peer;
+    type Activity = _Streams.Activity;
+    type Claim = _Streams.Claim;
+    type ClaimHeartbeat = _Streams.ClaimHeartbeat;
+    type ClaimHeartbeatOptions = _Streams.ClaimHeartbeatOptions;
+    namespace Claim {
+        type Held<T = Record<string, unknown>, M = _Global.ResolveClaimMeta> = _Streams.HeldClaim<T, M>;
+        type WaitOptions = _Streams.ClaimWaitOptions;
+        type LeaseOptions = _Streams.ClaimLeaseOptions;
+    }
+    type Schema<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord> = _SchemaTypes.Schema<S>;
+    /**
+     * The schema this program has registered via `interface Register { Schema }`
+     * (falls back to a loose shape when unregistered). Use it where shared code
+     * needs "this app's schema" without importing a specific one.
+     */
+    type ResolveSchema = _Global.ResolveSchema;
+    /**
+     * The claim metadata shape this program has registered via
+     * `interface Register { ClaimMeta }` (falls back to a loose record when
+     * unregistered). Every claim surface reads `target.meta` as this.
+     */
+    type ResolveClaimMeta = _Global.ResolveClaimMeta;
+    namespace Schema {
+        type Model<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.Model<S, K>;
+        type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
+        type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
+    }
+    type Conflict = _Policy.Conflict;
+    namespace Conflict {
+        type Kind = _Policy.ConflictKind;
+        type Operation = _Policy.ConflictOperation;
+        type Decision = _Policy.ConflictDecision;
+        type Policy = _Policy.ConflictPolicy;
+        type Axis = _Policy.ConflictAxis;
+    }
+    namespace Commit {
+        type Wait = _Http.CommitWait;
+        type OperationAction = _Http.ModelOperationAction;
+        type OperationInput = _Http.CommitOperationInput;
+        type CreateOptions = _Http.CommitCreateOptions;
+        type Receipt = _Http.CommitReceipt;
+        type Client = _Http.CommitResource;
+    }
+}

package/dist/transaction/ablo.js

@@ -0,0 +1,33 @@
+/**
+ * `Ablo` — the entry point to the coordination layer.
+ *
+ * The factory constructs the stateless client: typed model resources, commits,
+ * claims, and session minting over request/response HTTP. It holds no socket,
+ * no store, and no local copy of anything — the bearer credential is the
+ * identity and the server resolves it on every request. This is the client a
+ * server-side actor installs: an agent, a worker, a cron job, a route handler.
+ *
+ * ```ts
+ * import { Ablo } from '@abloatai/ablo';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * await ablo.tasks.update({ id: taskId, data: { status: 'done' } });
+ * ```
+ *
+ * The reactive materialiser — local store, live queries, presence rendering —
+ * is the consumer package's entry point (`@abloatai/ablo`), which layers
+ * above this one and shares the same `ablo.<model>` surface (ADR 0016).
+ */
+import { createAbloHttpClient, } from './transport/httpClient.js';
+/**
+ * Create a coordination-layer client in one call.
+ *
+ * The core carries one transport today — request/response HTTP — so
+ * `transport: 'http'` is accepted for symmetry with the reactive package's
+ * factory and may be omitted. The duplex transport joins this slot when the
+ * socket carve lands (ADR 0016, follow-up 3a).
+ */
+export function Ablo(options) {
+    return createAbloHttpClient(options);
+}

package/dist/{client/auth.d.ts → transaction/auth/apiKey.d.ts}

@@ -11,6 +11,7 @@
  * override is an explicit option, so an app never picks up hidden behavior from
  * a stray environment variable.
  */
+import type { KeyEnvironment } from '../environment.js';
 /**
  * The credential-resolver callable type. It is defined alongside
  * {@link createEndpointCredentialResolver} in `./credentialEndpoint` and
@@ -19,19 +20,31 @@
  */
 import type { ApiKeySetter } from './credentialEndpoint.js';
 export type { ApiKeySetter };
+/**
+ * The client options that decide a credential.
+ *
+ * This is the ONE declaration of that set. The resolvers below read it, and the
+ * transport configs that accept these options derive from it rather than listing
+ * the fields again — a second list is how `authEndpoint` came to be supported at
+ * runtime, named in an error message, and absent from the type a caller writes
+ * against.
+ */
+export interface AuthClientOptions {
+    readonly apiKey?: string | ApiKeySetter | null;
+    /** A route that mints the token, instead of a key the process holds. */
+    readonly authEndpoint?: string | ApiKeySetter | null;
+    /** A token the caller already has, used as-is. */
+    readonly authToken?: string | null;
+    readonly baseURL?: string | null;
+    readonly dangerouslyAllowBrowser?: boolean;
+}
 export interface AuthResolveInput {
     /**
      * The full set of options the caller passed to the client constructor. Each
      * resolver reads only the fields it needs; passing the whole object avoids
      * threading many separate parameters through every helper.
      */
-    readonly options: {
-        readonly apiKey?: string | ApiKeySetter | null;
-        readonly authEndpoint?: string | ApiKeySetter | null;
-        readonly authToken?: string | null;
-        readonly baseURL?: string | null;
-        readonly dangerouslyAllowBrowser?: boolean;
-    };
+    readonly options: AuthClientOptions;
     readonly env: Record<string, string | undefined>;
 }
 /**
@@ -41,8 +54,30 @@ export interface AuthResolveInput {
  */
 export declare function readProcessEnv(): Record<string, string | undefined>;
 export declare function resolveApiKey(input: AuthResolveInput): string | ApiKeySetter | null;
+/**
+ * Narrow a resolved `apiKey` to the single resolver the credential lifecycle
+ * needs: an async `() => token | null`, or `null` when auth is static — a plain
+ * long-lived key string with no refresh, which is the common case.
+ *
+ * The short-lived per-user browser path passes a function `apiKey` (an
+ * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
+ * from it: mint-before-connect, the proactive refresh timer with its
+ * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
+ * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
+ * resolve `null` when the login is gone (terminal — surfaces `session_expired`
+ * and signs the user out), or throw on a transient failure (backs off, without
+ * signing out).
+ */
+export declare function resolveCredentialResolver(apiKey: string | ApiKeySetter | null): (() => Promise<string | null>) | null;
 export declare function resolveAuthToken(input: AuthResolveInput): string | null;
-type CliMode = 'sandbox' | 'production';
+/**
+ * The credential axis, not a second copy of it. `environment.ts` documents two
+ * incidents caused by conflating the plane a request runs on with the mode a
+ * credential was minted in, and states the credential axis must not grow when
+ * planes do — so the CLI mismatch path reads the canonical vocabulary rather
+ * than restating its members here.
+ */
+type CliMode = KeyEnvironment;
 type StaticApiKeySource = 'option' | 'env';
 interface StaticApiKey {
     readonly key: string;

package/dist/{client/auth.js → transaction/auth/apiKey.js}

@@ -56,6 +56,25 @@ export function resolveApiKey(input) {
     }
     return configured ?? input.env.ABLO_API_KEY ?? null;
 }
+/**
+ * Narrow a resolved `apiKey` to the single resolver the credential lifecycle
+ * needs: an async `() => token | null`, or `null` when auth is static — a plain
+ * long-lived key string with no refresh, which is the common case.
+ *
+ * The short-lived per-user browser path passes a function `apiKey` (an
+ * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
+ * from it: mint-before-connect, the proactive refresh timer with its
+ * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
+ * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
+ * resolve `null` when the login is gone (terminal — surfaces `session_expired`
+ * and signs the user out), or throw on a transient failure (backs off, without
+ * signing out).
+ */
+export function resolveCredentialResolver(apiKey) {
+    if (typeof apiKey === 'function')
+        return apiKey;
+    return null;
+}
 export function resolveAuthToken(input) {
     return input.options.authToken ?? null;
 }

package/dist/transaction/auth/bootstrapScope.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The hand-off the identity flow performs once a credential resolves: it names
+ * the account scope and the sync groups everything downstream should read under.
+ *
+ * The core defines the port; the consumer supplies the implementation. That
+ * keeps identity resolution — which is settlement's business — from depending on
+ * whatever happens to materialise rows on the other side of it (ADR 0016). The
+ * reactive engine's `BootstrapFetcher` satisfies this structurally.
+ */
+export interface BootstrapScope {
+    /** Bind subsequent reads to one account's cache partition. */
+    setCacheScope(cacheScope: string): void;
+    /** Narrow subsequent reads to the sync groups the credential authorises. */
+    setSyncGroups(syncGroups: readonly string[] | undefined): void;
+}

package/dist/transaction/auth/bootstrapScope.js

@@ -0,0 +1 @@
+export {};

package/dist/transaction/auth/capability.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Capability — the one definition of what a credential may do.
+ *
+ * A grant is declared once, in the vocabulary a developer writes:
+ *
+ *     can: { documents: ['read', 'update'] }
+ *
+ * Everything downstream derives from that declaration: the wire spelling
+ * (`documents.update`) stored on the key row, the typed `can` a schema narrows
+ * to its own models, the request body the mint route parses, the pattern the
+ * published contract advertises, and the scope block echoed back on the minted
+ * session.
+ *
+ * Before this module the same grant was spelled five times — a literal union in
+ * the resource types, a `z.array(z.string())` on the wire, a hand-rolled
+ * field-by-field parser in the mint route, an object literal in the response
+ * type, and a hand-written `model.verb` array at each caller that mints without
+ * the SDK. Nothing failed when they drifted; the drift surfaced as
+ * `capability_scope_denied` on a grant the caller believed it held.
+ *
+ * Two axes decide blast radius. VERBS come from `can`; ROWS come from
+ * `syncGroups`. They belong to one grant, which is why they are declared
+ * together here rather than meeting for the first time on the wire.
+ */
+import { z } from 'zod';
+/**
+ * The verbs a grant can name — the whole vocabulary, in one place. Every other
+ * spelling of an operation in the system derives from this enum: the SDK's
+ * `can` values, the wire's `model.verb` pattern, and the JSON Schema the
+ * published contract advertises.
+ */
+export declare const capabilityOperationSchema: z.ZodEnum<{
+    update: "update";
+    create: "create";
+    delete: "delete";
+    read: "read";
+}>;
+export type CapabilityOperation = z.infer<typeof capabilityOperationSchema>;
+/**
+ * One granted operation in its wire spelling: `<model>.<verb>`, lowercased.
+ *
+ * The template literal derives both halves — the verb set from
+ * {@link capabilityOperationSchema}, the pattern in the published contract from
+ * the template — so tightening the verb vocabulary can never leave a stale
+ * regex or a stale doc behind. The model half is the name the server matches
+ * against a model's registered aliases (type name, schema key, or table name),
+ * so it stays permissive here and is resolved at the gate.
+ */
+export declare const grantedOperationSchema: z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>;
+export type GrantedOperation = z.infer<typeof grantedOperationSchema>;
+/**
+ * The declared grant, per model — the runtime shape of `can`. Model keys are
+ * free-form at runtime because the server resolves them against the schema it
+ * has; {@link CapabilityCan} narrows them to a known schema's models at the
+ * type level.
+ */
+export declare const capabilityCanSchema: z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+    update: "update";
+    create: "create";
+    delete: "delete";
+    read: "read";
+}>>>>;
+/**
+ * `can`, narrowed to one schema's model names. A projection of
+ * {@link capabilityCanSchema} — the value type is the operation enum, the key
+ * domain is the schema's models, so `can: { tasks: ['update'] }` fails to
+ * compile against a schema with no `tasks` model.
+ */
+export type CapabilityCan<S> = Partial<Record<keyof S & string, readonly CapabilityOperation[]>>;
+/**
+ * Read-your-writes expansion: append `<model>.read` for every model the grant
+ * can write.
+ *
+ * A scoped agent that may update a row must be able to read it, or the read
+ * gate (query / bootstrap / entity self-heal / delta fan-out) starves the very
+ * writes the grant allows. The write verbs stay the source of truth; reads are
+ * derived and deduped, and models the grant cannot write stay unreadable —
+ * that is the read-side blast-radius reduction.
+ *
+ * It lives beside the declaration, so it applies wherever a grant is built,
+ * rather than only at whichever mint the callers happen to share. The server
+ * applies it again at the mint chokepoint for callers that post raw JSON; the
+ * function is idempotent, so the second application is a no-op.
+ */
+export declare function expandReadYourWrites(operations: readonly GrantedOperation[]): GrantedOperation[];
+/**
+ * The parts of a model definition a grant can name. Structural, so both the
+ * SDK (which holds a `Schema`) and the mint route (which holds the tenant's
+ * pushed artifact) derive names from the same rule.
+ */
+export interface CapabilityModelShape {
+    readonly typename?: string;
+    readonly tableName?: string;
+}
+/**
+ * Schema key → the wire name a grant must be minted with.
+ *
+ * THE derivation. A model whose type name is overridden — schema key
+ * `documents`, type name `Document` — has to mint `document.update`, not
+ * `documents.update`, and a caller who works that out by hand gets it wrong
+ * once and learns at `capability_scope_denied`. Callers pass their schema's
+ * models, never a map they assembled themselves.
+ */
+export declare function modelWireNames(models: Readonly<Record<string, CapabilityModelShape>>): Record<string, string>;
+/**
+ * Every name the enforcement gates accept for a model, lowercased. Three
+ * vocabularies name one logical model — the wire type name (`lineitem`), the
+ * schema key (`lineItems`), and the table name (`line_items`) — so a grant
+ * minted in any of them is honored, and the mint can tell a real model from a
+ * typo without guessing which vocabulary the caller used.
+ */
+export declare function capabilityModelAliases(models: Readonly<Record<string, CapabilityModelShape>>): Set<string>;
+/**
+ * The granted operations whose model half names nothing in the schema.
+ *
+ * A grant is checked against the schema at MINT, the way a write to an unpushed
+ * model already fails with `server_execute_unknown_model` — so a typo in
+ * `lineitem.update` is a rejected mint rather than a credential that looks
+ * healthy and is denied on its first write. Without this the `model` half is a
+ * hole: an opaque string nothing validates until enforcement time.
+ */
+export declare function unresolvableOperations(operations: readonly GrantedOperation[], aliases: ReadonlySet<string>): GrantedOperation[];
+/**
+ * Serializes a declared `can` into the wire allowlist — the ONE translation
+ * from what a developer writes to what the server stores and enforces.
+ *
+ * `wireNames` comes from {@link modelWireNames} over the client's own schema.
+ * It is required rather than optional: an omitted map silently mints the schema
+ * key verbatim, which is right for most models and wrong for every model with
+ * a type-name override — the kind of default that is correct until it isn't.
+ */
+export declare function grantedOperations(can: Readonly<Record<string, readonly CapabilityOperation[] | undefined>>, wireNames: Readonly<Record<string, string>>): GrantedOperation[];
+/**
+ * The grant at rest: what the credential ended up with, on both axes, plus the
+ * participant it acts as. The mint echoes this block, the key row stores it,
+ * and the gates read it — so a session's reported scope and its enforced scope
+ * are the same shape by construction.
+ */
+export declare const capabilityScopeSchema: z.ZodObject<{
+    organizationId: z.ZodString;
+    syncGroups: z.ZodArray<z.ZodString>;
+    operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
+    participantKind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+export type CapabilityScope = z.infer<typeof capabilityScopeSchema>;
+/**
+ * `POST /v1/capabilities` — mint a capability for a participant.
+ *
+ * Where an ephemeral key is a session for a person, a capability is a scoped,
+ * revocable grant for an agent or a system. Narrow by default: an agent or
+ * system capability must name its `operations` unless the caller explicitly
+ * asks for `wideScope`, which is itself privileged.
+ *
+ * This is the parsed body — the mint route validates against it rather than
+ * reading fields one at a time, so the shape and the validation rules cannot
+ * drift from each other or from the published contract.
+ */
+export declare const capabilityRequestSchema: z.ZodObject<{
+    participantKind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    participantId: z.ZodOptional<z.ZodString>;
+    syncGroups: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>>>>;
+    operations: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>>>;
+    ttlSeconds: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+    wideScope: z.ZodOptional<z.ZodBoolean>;
+    userMeta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CapabilityRequest = z.infer<typeof capabilityRequestSchema>;