@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/coordination/targetConflict.d.ts

@@ -0,0 +1,2 @@
+import type { ClaimTargetDetails } from './locator.js';
+export declare function targetsConflict(held: ClaimTargetDetails, incoming: ClaimTargetDetails | undefined): boolean;

package/dist/transaction/coordination/targetConflict.js

@@ -0,0 +1,107 @@
+/**
+ * Whether two claims on the same entity collide — the single most consequential
+ * predicate in the claim protocol, and the one rule that decides whether a
+ * second writer is granted a lease or made to wait.
+ *
+ * It lived in two files for as long as there were two claim authorities: the
+ * Redis lease store, which is authoritative wherever Redis is wired, and the
+ * in-process presence store, which answers when it is not. Both spelled the
+ * rule out in full, byte for byte, so a change to the granularity semantics had
+ * two places to land and no way to notice when it landed in one. It is one
+ * definition here, and both authorities import it.
+ *
+ * It lives in the settlement core rather than the server because it is the rule
+ * itself, not a deployment of it: a claim authority running against a
+ * developer's own database has to answer this question exactly the same way,
+ * and a client that wants to predict a refusal before paying for the round trip
+ * reads the same predicate. Nothing about it needs a socket, a store, or a
+ * screen.
+ *
+ * Entity identity is NOT part of this comparison. Callers reach this predicate
+ * having already narrowed to a single `(organization, environment, entityType,
+ * entityId)` bucket — the lease store through its key, the presence store
+ * through its per-entity scan — so what remains to decide is only whether the
+ * two sub-targets within that entity overlap.
+ *
+ * **The bias is deliberate: when in doubt, conflict.** A false conflict costs a
+ * writer a wait. A missed conflict hands two writers the same target and loses
+ * one of their updates with no error anywhere, which is the failure this
+ * predicate exists to prevent.
+ */
+/**
+ * The named parts a claim covers, as one set.
+ *
+ * `field` and `fields` are the same idea at two cardinalities, so the rule
+ * reads both through here and never has to ask which one a caller used. Names
+ * are lowercased for the same reason the single-field comparison always
+ * lowercased them.
+ */
+function fieldSet(target) {
+    const named = [
+        ...(target?.field !== undefined ? [target.field] : []),
+        ...(target?.fields ?? []),
+    ];
+    // A path names a part too: `/content/3` addresses a position inside the
+    // `content` field, so a claim on it covers that field and nothing else.
+    //
+    // Deriving it here is what stops a path from reading as EVERY field. A
+    // target that named no field left this set empty, and an empty set means
+    // "all of them" — so a claim on one paragraph blocked a write to `status`
+    // on the same row. It also makes the exclusion honest in the other
+    // direction: a write of the whole `content` field does conflict with a
+    // claim on part of it, because nothing can write only that part.
+    //
+    // Only when no field was named outright — an explicit `field`/`fields`
+    // beside a path is the caller being specific, and is not second-guessed.
+    // A bare `range` derives nothing: it names a span without saying of what,
+    // so it stays the conservative whole-row answer.
+    const rootOfPath = named.length === 0 && target?.path !== undefined
+        ? target.path.split('/').filter(Boolean)[0]
+        : undefined;
+    const names = rootOfPath !== undefined ? [...named, rootOfPath] : named;
+    return new Set(names.map((n) => n.toLowerCase()));
+}
+/** Whether a claim narrows below the whole entity at all. */
+function hasSubtarget(target) {
+    return Boolean(target?.path ||
+        target?.field ||
+        (target?.fields && target.fields.length > 0) ||
+        target?.range);
+}
+function rangesOverlap(a, b) {
+    // Line-level overlap is the stable default. Columns can be layered
+    // in by policy later, but line ranges are what code/editor agents
+    // can reliably produce across tools.
+    return a.startLine <= b.endLine && b.startLine <= a.endLine;
+}
+export function targetsConflict(held, incoming) {
+    // Whole-entity claims are conservative: they conflict with any
+    // narrower path/field/range claim under the same entity.
+    if (!hasSubtarget(held) || !hasSubtarget(incoming))
+        return true;
+    // A claim is only as fine as the smallest thing the write path can address,
+    // and today that is a field: nothing writes part of a value. So two paths
+    // into the SAME field contend, and this rule used to grant them both — by
+    // comparing paths for containment and answering "disjoint" for `/content/3`
+    // against `/content/7`. Both holders were then blocked at their first write,
+    // each by the other, which is a wait dressed as concurrency and resolves
+    // only when someone releases.
+    //
+    // Both are answered below instead, through the field a path names: same
+    // field, conflict; different fields, disjoint. Path containment returns when
+    // a field can declare a smaller write unit than its whole value — an
+    // operation rather than a value — because that is what makes two positions
+    // inside one field separately writable and the disjointness real.
+    // A claim that names no field covers every field, so it conflicts with any
+    // claim under the same path. Two that both name fields conflict only where
+    // their sets intersect.
+    const heldFields = fieldSet(held);
+    const incomingFields = fieldSet(incoming);
+    const fieldConflicts = heldFields.size === 0 ||
+        incomingFields.size === 0 ||
+        [...heldFields].some((name) => incomingFields.has(name));
+    const rangeConflicts = !held.range ||
+        !incoming?.range ||
+        rangesOverlap(held.range, incoming.range);
+    return fieldConflicts && rangeConflicts;
+}

package/dist/{coordination → transaction/coordination}/trace.d.ts

@@ -9,7 +9,7 @@
  * as `Ablo({ observability })`, run your scenario, then read back an ordered
  * list — print it to eyeball what happened, or call `collisions()` to assert on it.
  */
-import type { SyncObservabilityProvider, ClaimEvent, ConflictEvent } from '../interfaces/index.js';
+import type { ClaimEvent, ConflictEvent, CoordinationObserver } from './events.js';
 /** A claim state change as one quiet, greppable line. */
 export declare function formatClaim(e: ClaimEvent): string;
 /** A notify-instead-of-abort stale write as one readable line. */
@@ -37,11 +37,13 @@ export interface ClaimLogEntry {
  * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
  * ```
  *
- * Implements the full {@link SyncObservabilityProvider} (every method it does not
- * care about is an inert no-op), so it drops straight into the `observability`
- * slot with no adapter.
+ * Implements the transaction layer's narrow {@link CoordinationObserver}.
+ * The sync engine re-serves a compatibility subclass that fills its broader
+ * lifecycle-observability contract, so the public `Ablo({ observability })`
+ * usage remains unchanged without teaching this core class about bootstrap,
+ * IndexedDB, or WebSockets.
  */
-export declare class ClaimLog implements SyncObservabilityProvider {
+export declare class ClaimLog implements CoordinationObserver {
     private readonly max;
     private rows;
     private seq;
@@ -73,17 +75,4 @@ export declare class ClaimLog implements SyncObservabilityProvider {
     toString(): string;
     private add;
     private notify;
-    setContext(): void;
-    setConnectionState(): void;
-    breadcrumb(): void;
-    captureRollback(): void;
-    captureTransactionFailure(): void;
-    captureBootstrapFailure(): void;
-    captureReconciliation(): void;
-    captureDeltaRetryExhausted(): void;
-    captureWebSocketError(): void;
-    captureSelfHealing(): void;
-    captureCommitZeroSyncId(): void;
-    startSpan<T>(_name: string, _op: string, fn: () => T): T;
-    startSpanAsync<T>(_name: string, _op: string, fn: () => Promise<T>): Promise<T>;
 }

package/dist/{coordination → transaction/coordination}/trace.js

@@ -18,16 +18,25 @@ export function formatClaim(e) {
     const target = e.model && e.id ? `${e.model}/${e.id}` : e.claimId ?? 'unknown target';
     const scope = e.field ? `#${e.field}` : '';
     const pos = e.position !== undefined ? ` [pos ${e.position}]` : '';
-    const actor = e.actor
-        ? `${e.actor}${e.participantKind ? ` (${e.participantKind})` : ''}`
-        : '';
+    // The kind belongs to the counterparty, which is the only participant an
+    // event names: on an acquisition the participant is us.
+    const kind = e.heldBy?.participantKind;
+    const actor = e.actor ? `${e.actor}${kind ? ` (${kind})` : ''}` : '';
     // `rejected`/`lost` name the blocking holder; the rest name us (or no one).
     const by = actor
         ? e.phase === 'rejected' || e.phase === 'lost'
             ? ` — held by ${actor}`
             : ` — by ${actor}`
         : '';
-    const why = e.reason ? `: ${e.reason}` : '';
+    // The cause when there is one, in the policy's own words when a policy
+    // decided; otherwise what the holder said they were doing. A line never
+    // shows both, because a claim that ended has a cause and a claim that is
+    // simply alive has only its description.
+    const why = e.reason
+        ? `: ${e.policyReason ?? e.reason}`
+        : e.description
+            ? `: ${e.description}`
+            : '';
     return `claim ${e.phase}: ${target}${scope}${pos}${by}${why}`;
 }
 /** A notify-instead-of-abort stale write as one readable line. */
@@ -47,9 +56,11 @@ export function formatConflict(e) {
  * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
  * ```
  *
- * Implements the full {@link SyncObservabilityProvider} (every method it does not
- * care about is an inert no-op), so it drops straight into the `observability`
- * slot with no adapter.
+ * Implements the transaction layer's narrow {@link CoordinationObserver}.
+ * The sync engine re-serves a compatibility subclass that fills its broader
+ * lifecycle-observability contract, so the public `Ablo({ observability })`
+ * usage remains unchanged without teaching this core class about bootstrap,
+ * IndexedDB, or WebSockets.
  */
 export class ClaimLog {
     max;
@@ -124,22 +135,4 @@ export class ClaimLog {
         for (const listener of this.listeners)
             listener();
     }
-    // —— inert provider surface (this log only cares about claims) ——
-    setContext() { }
-    setConnectionState() { }
-    breadcrumb() { }
-    captureRollback() { }
-    captureTransactionFailure() { }
-    captureBootstrapFailure() { }
-    captureReconciliation() { }
-    captureDeltaRetryExhausted() { }
-    captureWebSocketError() { }
-    captureSelfHealing() { }
-    captureCommitZeroSyncId() { }
-    startSpan(_name, _op, fn) {
-        return fn();
-    }
-    startSpanAsync(_name, _op, fn) {
-        return fn();
-    }
 }

package/dist/transaction/durableWrites.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The durable-write port and the option that installs it.
+ *
+ * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
+ * contract of methods, not a serialized shape, which is why it lives here
+ * rather than in `transactions/settlement/`. The records that cross this port
+ * are owned by `pendingWriteSchema` there; this module never redescribes them.
+ *
+ * The engine consumes the port through `commitOutboxStore`, and the HTTP client
+ * accepts the same option through `transport/httpOptions`.
+ */
+import { z } from 'zod';
+import type { CommitOutboxScope } from './transactions/settlement/commitEnvelope.js';
+import type { PendingWrite } from './transactions/settlement/pendingWrite.js';
+/**
+ * Persistence port used by `Ablo({ durableWrites })`.
+ *
+ * `seal` is the durability boundary: it must atomically persist the exact write
+ * and consume the staged records that write supersedes. Resolving this promise
+ * authorizes Ablo to dispatch the request, so adapters must never report success
+ * before the data is durable.
+ */
+export interface DurableWriteStore {
+    /**
+     * Atomically reserve a pending write and consume the staged records it owns.
+     * The same id + same request is idempotent; the same id + a different request
+     * must be rejected. For a source-accepted envelope, a re-seal may add the
+     * monotonic `acceptedAt`/`correlationId` evidence and the store must preserve
+     * that upgrade atomically rather than ignoring it.
+     */
+    seal(write: PendingWrite, consumedRecordIds: readonly string[]): Promise<void>;
+    /** Load all unacknowledged writes. Stored data is treated as untrusted. */
+    list(): Promise<readonly unknown[]>;
+    /** Remove one write only after its outcome is definitive. */
+    remove(writeId: string): Promise<void>;
+}
+/** Runtime validation for injected adapters, including JavaScript consumers. */
+export declare const durableWriteStoreSchema: z.ZodCustom<DurableWriteStore, DurableWriteStore>;
+/** Options for crash-durable `create`, `update`, and `delete` calls. */
+export declare const durableWritesConfigSchema: z.ZodObject<{
+    store: z.ZodCustom<DurableWriteStore, DurableWriteStore>;
+    namespace: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type DurableWritesConfig = z.infer<typeof durableWritesConfigSchema>;
+interface DurableWriteOptionInput {
+    readonly durableWrites?: DurableWritesConfig;
+    /** Compatibility input for pre-`durableWrites` clients. */
+    readonly commitOutbox?: DurableWriteStore;
+    /** Compatibility input and internal child-client identity seam. */
+    readonly commitOutboxScope?: CommitOutboxScope;
+}
+export interface ResolvedDurableWrites {
+    readonly store?: DurableWriteStore;
+    readonly namespace?: string;
+}
+/**
+ * Resolves one canonical store configuration for both HTTP and WebSocket
+ * clients. Mixed old/new configuration fails loudly so Ablo never persists to
+ * one adapter while the caller believes another adapter is authoritative.
+ */
+export declare function resolveDurableWrites(options: DurableWriteOptionInput): ResolvedDurableWrites;
+export {};

package/dist/{client → transaction}/durableWrites.js

@@ -1,6 +1,31 @@
-/** Normalize the product-facing durable-write option and its legacy aliases. */
-import { AbloValidationError } from '../errors.js';
-import { durableWritesConfigSchema, durableWriteStoreSchema, } from '../transactions/durableWriteStore.js';
+/**
+ * The durable-write port and the option that installs it.
+ *
+ * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
+ * contract of methods, not a serialized shape, which is why it lives here
+ * rather than in `transactions/settlement/`. The records that cross this port
+ * are owned by `pendingWriteSchema` there; this module never redescribes them.
+ *
+ * The engine consumes the port through `commitOutboxStore`, and the HTTP client
+ * accepts the same option through `transport/httpOptions`.
+ */
+import { z } from 'zod';
+import { AbloValidationError } from './errors.js';
+/** Runtime validation for injected adapters, including JavaScript consumers. */
+export const durableWriteStoreSchema = z.custom((value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.seal === 'function' &&
+        typeof candidate.list === 'function' &&
+        typeof candidate.remove === 'function');
+}, { message: 'store must implement seal(), list(), and remove()' });
+/** Options for crash-durable `create`, `update`, and `delete` calls. */
+export const durableWritesConfigSchema = z.strictObject({
+    store: durableWriteStoreSchema,
+    /** Separates deployments or workflow lanes that share an authenticated actor. */
+    namespace: z.string().trim().min(1).optional(),
+});
 function invalidDurableWrites(message) {
     return new AbloValidationError(`Ablo: invalid \`durableWrites\` option — ${message}.`, {
         code: 'invalid_options',

package/dist/transaction/environment.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+/**
+ * Two axes live in this module, and they are NOT the same axis. They stay
+ * together because they convert into each other; they stay distinct because
+ * conflating them is how credentials acquire a mode nobody chose.
+ *
+ *  - The PLANE axis ({@link Environment}) — which isolated plane a row, schema
+ *    artifact, or data source belongs to. Open-ended: `production` is the root
+ *    plane and any number of others may exist beside it.
+ *  - The CREDENTIAL axis ({@link KeyEnvironment}) — the mode a key was minted
+ *    in. Binary, and fixed by the key format: a prefix spells exactly one of
+ *    `live` or `test`, so a third value is not representable in a key at all.
+ *
+ * These were one type until this split, which is the shape behind two
+ * incidents: an `sk_test_` exchange that minted an `ek_live_` and landed
+ * sandbox commits in another tenant's tables, and a rotation that handed back
+ * an `rk_live_` in place of an `rk_test_`. Widening the plane axis while the
+ * credential axis aliased it would reopen that door one plane name wider, so
+ * the split comes first and the conversions below are deliberately narrow.
+ */
+/**
+ * The plane names every deployment has: the root, plus the plane every project
+ * starts with beside it. This is the well-known set, not the permitted set —
+ * {@link environmentSchema} decides what is valid.
+ */
+export declare const ENVIRONMENTS: readonly ["production", "sandbox"];
+/** The root plane — the one every other plane is defined relative to. */
+export declare const ROOT_ENVIRONMENT = "production";
+/**
+ * The modes a credential can be minted in. Deliberately its own list rather
+ * than a view of {@link ENVIRONMENTS}: this one is fixed by the key format,
+ * which has exactly two prefix spellings, and must not grow when planes do.
+ */
+export declare const KEY_ENVIRONMENTS: readonly ["production", "sandbox"];
+/**
+ * How a credential's mode is spelled inside an API-key prefix: a `live` key
+ * acts on production and a `test` key acts on the sandbox. Convert between this
+ * spelling and {@link KeyEnvironment} with {@link environmentFromKeyPrefix} and
+ * {@link environmentToKeyPrefix}.
+ */
+export declare const KEY_PREFIX_ENVIRONMENTS: readonly ["live", "test"];
+export type KeyPrefixEnvironment = (typeof KEY_PREFIX_ENVIRONMENTS)[number];
+/**
+ * Validates a value as a plane name — a lowercase slug that may not lead or
+ * trail with a hyphen.
+ *
+ * The character set is load-bearing rather than cosmetic. A plane name is
+ * interpolated into two delimited identifiers: the sync-group prefix
+ * (`sandbox:<org>:<slug>`, colon separated) and the tenant secret scope
+ * (`<org>/<env>/<project>/<sandbox>`, slash separated). Admitting `:` or `/`
+ * would let one plane's name parse as two segments and so collide with a
+ * different plane's identity, which is why the pattern excludes every delimiter
+ * either format relies on.
+ */
+export declare const environmentSchema: z.ZodString;
+/** A plane name. `production` is the root; any other slug is a plane beside it. */
+export type Environment = z.infer<typeof environmentSchema>;
+/** Validates a value as one of the {@link KEY_ENVIRONMENTS}. */
+export declare const keyEnvironmentSchema: z.ZodEnum<{
+    production: "production";
+    sandbox: "sandbox";
+}>;
+/**
+ * The mode a credential was minted in — `'production'` or `'sandbox'`, never
+ * anything else. Not an alias of {@link Environment}: a key's mode is a trust
+ * boundary, and a plane name must never be able to answer it.
+ */
+export type KeyEnvironment = z.infer<typeof keyEnvironmentSchema>;
+/**
+ * Coerces an untrusted value into a valid {@link Environment}, returning
+ * `fallback` (which defaults to the root plane) when the value is not a
+ * well-formed plane name. Use it when reading a plane from configuration or off
+ * the wire.
+ */
+export declare function normalizeEnvironment(value: unknown, fallback?: Environment): Environment;
+/** True when the given plane is the root plane. */
+export declare function isRootEnvironment(value: Environment): boolean;
+/**
+ * The mode a credential acting on the given plane must be minted in.
+ *
+ * This is the ONE narrowing from the open plane axis to the binary credential
+ * axis, and it is deliberately asymmetric: only the root plane yields a
+ * production-mode key, and every other plane — named, numbered, or newly forked
+ * — yields a sandbox-mode one. A plane cannot acquire live authority by being
+ * spelled a particular way, which is the property that keeps adding planes from
+ * widening what any credential is allowed to touch.
+ */
+export declare function keyEnvironmentForPlane(value: Environment): KeyEnvironment;
+/**
+ * Maps an API-key prefix spelling to the mode it denotes: a `'test'` key was
+ * minted in the sandbox, and anything else in production.
+ */
+export declare function environmentFromKeyPrefix(value: KeyPrefixEnvironment): KeyEnvironment;
+/**
+ * Maps a credential's mode to the spelling used in its key prefix.
+ *
+ * Takes a {@link KeyEnvironment} rather than an {@link Environment} on purpose.
+ * Planes outside the well-known two have no prefix spelling, and a signature
+ * that accepted one would silently answer `'live'` for them — minting a
+ * production-mode credential for a plane that is not production. That is the
+ * 2026-06-10 incident with a new cause, so the type refuses the input instead.
+ */
+export declare function environmentToKeyPrefix(value: KeyEnvironment): KeyPrefixEnvironment;
+/** Returns true when the given environment is the sandbox. */
+export declare function isSandboxEnvironment(value: Environment): boolean;

package/dist/transaction/environment.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+/**
+ * Two axes live in this module, and they are NOT the same axis. They stay
+ * together because they convert into each other; they stay distinct because
+ * conflating them is how credentials acquire a mode nobody chose.
+ *
+ *  - The PLANE axis ({@link Environment}) — which isolated plane a row, schema
+ *    artifact, or data source belongs to. Open-ended: `production` is the root
+ *    plane and any number of others may exist beside it.
+ *  - The CREDENTIAL axis ({@link KeyEnvironment}) — the mode a key was minted
+ *    in. Binary, and fixed by the key format: a prefix spells exactly one of
+ *    `live` or `test`, so a third value is not representable in a key at all.
+ *
+ * These were one type until this split, which is the shape behind two
+ * incidents: an `sk_test_` exchange that minted an `ek_live_` and landed
+ * sandbox commits in another tenant's tables, and a rotation that handed back
+ * an `rk_live_` in place of an `rk_test_`. Widening the plane axis while the
+ * credential axis aliased it would reopen that door one plane name wider, so
+ * the split comes first and the conversions below are deliberately narrow.
+ */
+/**
+ * The plane names every deployment has: the root, plus the plane every project
+ * starts with beside it. This is the well-known set, not the permitted set —
+ * {@link environmentSchema} decides what is valid.
+ */
+export const ENVIRONMENTS = ['production', 'sandbox'];
+/** The root plane — the one every other plane is defined relative to. */
+export const ROOT_ENVIRONMENT = 'production';
+/**
+ * The modes a credential can be minted in. Deliberately its own list rather
+ * than a view of {@link ENVIRONMENTS}: this one is fixed by the key format,
+ * which has exactly two prefix spellings, and must not grow when planes do.
+ */
+export const KEY_ENVIRONMENTS = ['production', 'sandbox'];
+/**
+ * How a credential's mode is spelled inside an API-key prefix: a `live` key
+ * acts on production and a `test` key acts on the sandbox. Convert between this
+ * spelling and {@link KeyEnvironment} with {@link environmentFromKeyPrefix} and
+ * {@link environmentToKeyPrefix}.
+ */
+export const KEY_PREFIX_ENVIRONMENTS = ['live', 'test'];
+/**
+ * Validates a value as a plane name — a lowercase slug that may not lead or
+ * trail with a hyphen.
+ *
+ * The character set is load-bearing rather than cosmetic. A plane name is
+ * interpolated into two delimited identifiers: the sync-group prefix
+ * (`sandbox:<org>:<slug>`, colon separated) and the tenant secret scope
+ * (`<org>/<env>/<project>/<sandbox>`, slash separated). Admitting `:` or `/`
+ * would let one plane's name parse as two segments and so collide with a
+ * different plane's identity, which is why the pattern excludes every delimiter
+ * either format relies on.
+ */
+export const environmentSchema = z
+    .string()
+    .regex(/^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/, 'must be a lowercase slug');
+/** Validates a value as one of the {@link KEY_ENVIRONMENTS}. */
+export const keyEnvironmentSchema = z.enum(KEY_ENVIRONMENTS);
+/**
+ * Coerces an untrusted value into a valid {@link Environment}, returning
+ * `fallback` (which defaults to the root plane) when the value is not a
+ * well-formed plane name. Use it when reading a plane from configuration or off
+ * the wire.
+ */
+export function normalizeEnvironment(value, fallback = ROOT_ENVIRONMENT) {
+    const parsed = environmentSchema.safeParse(value);
+    return parsed.success ? parsed.data : fallback;
+}
+/** True when the given plane is the root plane. */
+export function isRootEnvironment(value) {
+    return value === ROOT_ENVIRONMENT;
+}
+/**
+ * The mode a credential acting on the given plane must be minted in.
+ *
+ * This is the ONE narrowing from the open plane axis to the binary credential
+ * axis, and it is deliberately asymmetric: only the root plane yields a
+ * production-mode key, and every other plane — named, numbered, or newly forked
+ * — yields a sandbox-mode one. A plane cannot acquire live authority by being
+ * spelled a particular way, which is the property that keeps adding planes from
+ * widening what any credential is allowed to touch.
+ */
+export function keyEnvironmentForPlane(value) {
+    return isRootEnvironment(value) ? 'production' : 'sandbox';
+}
+/**
+ * Maps an API-key prefix spelling to the mode it denotes: a `'test'` key was
+ * minted in the sandbox, and anything else in production.
+ */
+export function environmentFromKeyPrefix(value) {
+    return value === 'test' ? 'sandbox' : 'production';
+}
+/**
+ * Maps a credential's mode to the spelling used in its key prefix.
+ *
+ * Takes a {@link KeyEnvironment} rather than an {@link Environment} on purpose.
+ * Planes outside the well-known two have no prefix spelling, and a signature
+ * that accepted one would silently answer `'live'` for them — minting a
+ * production-mode credential for a plane that is not production. That is the
+ * 2026-06-10 incident with a new cause, so the type refuses the input instead.
+ */
+export function environmentToKeyPrefix(value) {
+    return value === 'sandbox' ? 'test' : 'live';
+}
+/** Returns true when the given environment is the sandbox. */
+export function isSandboxEnvironment(value) {
+    return value === 'sandbox';
+}

package/dist/{errorCodes.d.ts → transaction/errorCodes.d.ts}

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * error documentation and returned on the `Ablo-Version` response header, so a
  * consumer can detect when its expected contract has drifted from the server's.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-07-15";
+export declare const ERROR_CONTRACT_VERSION = "2026-07-23";
 /** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
@@ -148,6 +148,7 @@ export declare const ERROR_CODES: {
     readonly database_role_unreadable: ErrorCodeSpec;
     readonly database_tables_unforced_rls: ErrorCodeSpec;
     readonly database_host_not_allowed: ErrorCodeSpec;
+    readonly connected_database_unreachable: ErrorCodeSpec;
     readonly byo_role_cannot_enforce_rls: ErrorCodeSpec;
     readonly byo_role_unreadable: ErrorCodeSpec;
     readonly byo_tenant_tables_unforced_rls: ErrorCodeSpec;
@@ -158,6 +159,7 @@ export declare const ERROR_CODES: {
     readonly entity_claimed: ErrorCodeSpec;
     readonly malformed_claim: ErrorCodeSpec;
     readonly malformed_subscription: ErrorCodeSpec;
+    readonly malformed_response: ErrorCodeSpec;
     readonly model_claimed: ErrorCodeSpec;
     readonly model_claimed_timeout: ErrorCodeSpec;
     readonly model_claim_not_configured: ErrorCodeSpec;
@@ -170,13 +172,13 @@ export declare const ERROR_CODES: {
     readonly source_transport_pinned: ErrorCodeSpec;
     readonly idempotency_key_too_long: ErrorCodeSpec;
     readonly write_options_invalid: ErrorCodeSpec;
+    readonly write_payload_invalid: ErrorCodeSpec;
     readonly source_operation_id_required: ErrorCodeSpec;
     readonly source_adapter_misconfigured: ErrorCodeSpec;
     readonly source_event_invalid: ErrorCodeSpec;
     readonly duration_invalid: ErrorCodeSpec;
     readonly schema_definition_invalid: ErrorCodeSpec;
     readonly cli_invalid_arguments: ErrorCodeSpec;
-    readonly turn_validation_failed: ErrorCodeSpec;
     readonly commit_operation_required: ErrorCodeSpec;
     readonly commit_operation_invalid: ErrorCodeSpec;
     readonly commit_operation_model_required: ErrorCodeSpec;
@@ -225,11 +227,9 @@ export declare const ERROR_CODES: {
     readonly claim_not_wired: ErrorCodeSpec;
     readonly claim_queued: ErrorCodeSpec;
     readonly claim_wait_aborted: ErrorCodeSpec;
-    readonly claim_wait_poll_interval_required: ErrorCodeSpec;
     readonly grant_timeout: ErrorCodeSpec;
-    readonly slide_intent_missing_deck_id: ErrorCodeSpec;
-    readonly slide_intent_unknown_sibling: ErrorCodeSpec;
     readonly bootstrap_fetch_timeout: ErrorCodeSpec;
+    readonly bootstrap_cancelled: ErrorCodeSpec;
     readonly bootstrap_offline: ErrorCodeSpec;
     readonly bootstrap_offline_no_cache: ErrorCodeSpec;
     readonly bootstrap_response_invalid: ErrorCodeSpec;
@@ -258,8 +258,6 @@ export declare const ERROR_CODES: {
     readonly internal_error: ErrorCodeSpec;
     readonly quota_lookup_failed: ErrorCodeSpec;
     readonly rate_limiter_unavailable: ErrorCodeSpec;
-    readonly turn_open_failed: ErrorCodeSpec;
-    readonly turn_close_failed: ErrorCodeSpec;
     readonly invalid_options: ErrorCodeSpec;
     readonly no_ablo_provider: ErrorCodeSpec;
     readonly no_sync_group_provider: ErrorCodeSpec;
@@ -307,12 +305,14 @@ export declare const ERROR_CODES: {
     readonly forbidden: ErrorCodeSpec;
     readonly source_api_key_unresolved: ErrorCodeSpec;
     readonly capability_auth_disabled: ErrorCodeSpec;
+    readonly capability_rotation_unavailable: ErrorCodeSpec;
     readonly provisioner_unavailable: ErrorCodeSpec;
     readonly invalid_model: ErrorCodeSpec;
     readonly invalid_id: ErrorCodeSpec;
     readonly unknown_model: ErrorCodeSpec;
     readonly model_not_tenant_scoped: ErrorCodeSpec;
     readonly source_tenancy_not_enforced: ErrorCodeSpec;
+    readonly user_scope_not_enforced: ErrorCodeSpec;
     readonly model_not_provisioned: ErrorCodeSpec;
     readonly schema_table_invalid: ErrorCodeSpec;
     readonly schema_scope_invalid: ErrorCodeSpec;
@@ -329,6 +329,7 @@ export declare const ERROR_CODES: {
     readonly protocol_version_unsupported: ErrorCodeSpec;
     readonly database_unreachable: ErrorCodeSpec;
     readonly database_not_replication_ready: ErrorCodeSpec;
+    readonly database_already_connected: ErrorCodeSpec;
     readonly replication_publication_drift: ErrorCodeSpec;
     readonly query_unknown_relation: ErrorCodeSpec;
     readonly query_relation_target_unknown: ErrorCodeSpec;
@@ -346,20 +347,19 @@ export declare const ERROR_CODES: {
     readonly usage_invalid: ErrorCodeSpec;
     readonly invalid_request: ErrorCodeSpec;
     readonly capability_not_found: ErrorCodeSpec;
+    readonly claim_not_found: ErrorCodeSpec;
     readonly invalid_participant_kind: ErrorCodeSpec;
     readonly invalid_sync_group: ErrorCodeSpec;
     readonly narrow_scope_required: ErrorCodeSpec;
     readonly wide_scope_forbidden: ErrorCodeSpec;
     readonly capability_required: ErrorCodeSpec;
-    readonly parent_turn_not_found: ErrorCodeSpec;
-    readonly parent_turn_foreign_agent: ErrorCodeSpec;
-    readonly turn_not_found: ErrorCodeSpec;
-    readonly turn_foreign_agent: ErrorCodeSpec;
-    readonly invalid_intent: ErrorCodeSpec;
+    readonly position_missing_parent: ErrorCodeSpec;
+    readonly position_unknown_sibling: ErrorCodeSpec;
     readonly schema_too_large: ErrorCodeSpec;
     readonly request_too_large: ErrorCodeSpec;
     readonly invalid_schema: ErrorCodeSpec;
     readonly incompatible_change: ErrorCodeSpec;
+    readonly replication_reset_required: ErrorCodeSpec;
 };
 /**
  * The type of a valid error code: any key registered in {@link ERROR_CODES},