@abloatai/ablo 0.35.0 → 0.37.0

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

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

package/dist/transaction/coordination/targetConflict.js

@@ -1,103 +0,0 @@
-/**
- * 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 names = [
-        ...(target?.field !== undefined ? [target.field] : []),
-        ...(target?.fields ?? []),
-    ];
-    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 lower(value) {
-    return value?.toLowerCase();
-}
-/**
- * Whether two paths address overlapping parts of a document.
- *
- * Paths are hierarchical, so equality is the wrong test: `/content` contains
- * `/content/3`, and a writer holding the parent is holding the child too.
- * Comparing them as opaque strings reported no conflict and granted both
- * leases — the parent's writer and the child's writer would then both write,
- * and one update would vanish with nothing raised anywhere.
- *
- * Containment is checked on a separator boundary so `/content` contains
- * `/content/3` but not `/contentious`, which is the same trap as any
- * prefix match over structured names.
- */
-function pathsOverlap(a, b) {
-    const x = lower(a) ?? '';
-    const y = lower(b) ?? '';
-    if (x === y)
-        return true;
-    const contains = (parent, child) => child.startsWith(parent.endsWith('/') ? parent : `${parent}/`);
-    return contains(x, y) || contains(y, x);
-}
-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;
-    if (held.path && incoming?.path && !pathsOverlap(held.path, incoming.path)) {
-        return false;
-    }
-    // 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/transaction/coordination/trace.d.ts

@@ -1,78 +0,0 @@
-/**
- * A claim log — the simplest way to watch agents collide. The engine reports
- * the claim lifecycle (`acquired → queued → granted → lost / rejected /
- * expired`) and the notify-instead-of-abort stale write through two channels:
- * human-readable `logger` lines (shown with `new Ablo({ debug: true })`) and
- * structured `observability.captureClaim` / `captureConflict` calls.
- *
- * This is a third channel, shaped for tests and evals. Pass a {@link ClaimLog}
- * 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 { 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. */
-export declare function formatConflict(e: ConflictEvent): string;
-/** One ordered entry in a {@link ClaimLog}. */
-export interface ClaimLogEntry {
-    /** Monotonic order index — deterministic, clock-free, eval-friendly. */
-    readonly seq: number;
-    /** The same one-line text the console and breadcrumb channels emit. */
-    readonly line: string;
-    /** A collision worth flagging: a rejected/lost claim or a stale write. */
-    readonly collision: boolean;
-    readonly claim?: ClaimEvent;
-    readonly conflict?: ConflictEvent;
-}
-/**
- * Collects the claim lifecycle + stale-write collisions into an ordered list.
- *
- * @example
- * ```ts
- * const log = new ClaimLog();
- * const ablo = new Ablo({ schema, apiKey, observability: log });
- * // …run the agents…
- * console.log(`${log}`);                 // pretty timeline for eyeballing
- * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
- * ```
- *
- * 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 CoordinationObserver {
-    private readonly max;
-    private rows;
-    private seq;
-    private readonly listeners;
-    /** Cap the buffer so a long-running session can't grow unbounded. */
-    constructor(max?: number);
-    captureClaim(claim: ClaimEvent): void;
-    captureConflict(conflict: ConflictEvent): void;
-    /**
-     * Fire `listener` every time an event lands. Returns an unsubscribe fn. Same
-     * contract as `ablo.claims.onChange` — drop it into `useSyncExternalStore` in
-     * React or `autorun` in MobX to render a live activity feed.
-     *
-     * @example
-     * ```tsx
-     * const log = useMemo(() => new ClaimLog(), []);
-     * const entries = useSyncExternalStore(log.onChange, () => log.entries);
-     * return <ul>{entries.map((e) => <li key={e.seq}>{e.line}</li>)}</ul>;
-     * ```
-     */
-    readonly onChange: (listener: () => void) => (() => void);
-    /** The full ordered list. Stable reference until the next event lands. */
-    get entries(): readonly ClaimLogEntry[];
-    /** Only the collisions: rejected/lost claims + stale writes. */
-    collisions(): readonly ClaimLogEntry[];
-    /** Drop everything — useful between scenarios in one process. */
-    clear(): void;
-    /** Printable: one event per line, collisions marked. */
-    toString(): string;
-    private add;
-    private notify;
-}

package/dist/transaction/coordination/trace.js

@@ -1,138 +0,0 @@
-/**
- * A claim log — the simplest way to watch agents collide. The engine reports
- * the claim lifecycle (`acquired → queued → granted → lost / rejected /
- * expired`) and the notify-instead-of-abort stale write through two channels:
- * human-readable `logger` lines (shown with `new Ablo({ debug: true })`) and
- * structured `observability.captureClaim` / `captureConflict` calls.
- *
- * This is a third channel, shaped for tests and evals. Pass a {@link ClaimLog}
- * 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.
- */
-// ─────────────────────────────────────────────
-// Formatters — one readable line per event. Shared by the debug logger and
-// this log so console output and log output never drift.
-// ─────────────────────────────────────────────
-/** A claim state change as one quiet, greppable line. */
-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}]` : '';
-    // 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}`
-        : '';
-    // 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. */
-export function formatConflict(e) {
-    const rows = e.rows.map((r) => `${r.model}/${r.id}(${r.fields.join(',')})`).join(', ');
-    return `conflict: tx ${e.clientTxId} — ${e.rows.length} row(s) changed underneath${rows ? `: ${rows}` : ''}`;
-}
-/**
- * Collects the claim lifecycle + stale-write collisions into an ordered list.
- *
- * @example
- * ```ts
- * const log = new ClaimLog();
- * const ablo = new Ablo({ schema, apiKey, observability: log });
- * // …run the agents…
- * console.log(`${log}`);                 // pretty timeline for eyeballing
- * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
- * ```
- *
- * 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;
-    // Immutable list: a new array reference on every change. This is what lets
-    // `useSyncExternalStore(log.onChange, () => log.entries)` detect updates —
-    // it compares snapshots by reference, so an in-place push would never render.
-    rows = [];
-    seq = 0;
-    listeners = new Set();
-    /** Cap the buffer so a long-running session can't grow unbounded. */
-    constructor(max = 1_000) {
-        this.max = max;
-    }
-    // —— the two channels we record ——
-    captureClaim(claim) {
-        this.add({
-            line: formatClaim(claim),
-            collision: claim.phase === 'rejected' || claim.phase === 'lost',
-            claim,
-        });
-    }
-    captureConflict(conflict) {
-        this.add({ line: formatConflict(conflict), collision: true, conflict });
-    }
-    // —— reactivity ——
-    /**
-     * Fire `listener` every time an event lands. Returns an unsubscribe fn. Same
-     * contract as `ablo.claims.onChange` — drop it into `useSyncExternalStore` in
-     * React or `autorun` in MobX to render a live activity feed.
-     *
-     * @example
-     * ```tsx
-     * const log = useMemo(() => new ClaimLog(), []);
-     * const entries = useSyncExternalStore(log.onChange, () => log.entries);
-     * return <ul>{entries.map((e) => <li key={e.seq}>{e.line}</li>)}</ul>;
-     * ```
-     */
-    onChange = (listener) => {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
-    };
-    // —— inspection ——
-    /** The full ordered list. Stable reference until the next event lands. */
-    get entries() {
-        return this.rows;
-    }
-    /** Only the collisions: rejected/lost claims + stale writes. */
-    collisions() {
-        return this.rows.filter((e) => e.collision);
-    }
-    /** Drop everything — useful between scenarios in one process. */
-    clear() {
-        this.rows = [];
-        this.seq = 0;
-        this.notify();
-    }
-    /** Printable: one event per line, collisions marked. */
-    toString() {
-        if (this.rows.length === 0)
-            return 'claim log: (empty)';
-        const w = String(this.rows.length).length;
-        return this.rows
-            .map((e) => `${String(e.seq).padStart(w)}  ${e.collision ? '⚠ ' : '  '}${e.line}`)
-            .join('\n');
-    }
-    add(entry) {
-        const next = [...this.rows, { seq: this.seq++, ...entry }];
-        this.rows = next.length > this.max ? next.slice(next.length - this.max) : next;
-        this.notify();
-    }
-    notify() {
-        for (const listener of this.listeners)
-            listener();
-    }
-}

package/dist/transaction/durableWrites.d.ts

@@ -1,62 +0,0 @@
-/**
- * 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/transaction/durableWrites.js

@@ -1,71 +0,0 @@
-/**
- * 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',
-        param: 'durableWrites',
-    });
-}
-/**
- * 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 function resolveDurableWrites(options) {
-    if (options.durableWrites !== undefined && options.commitOutbox !== undefined) {
-        throw invalidDurableWrites('pass `durableWrites` or the deprecated `commitOutbox`, not both');
-    }
-    if (options.durableWrites !== undefined) {
-        const parsed = durableWritesConfigSchema.safeParse(options.durableWrites);
-        if (!parsed.success) {
-            throw invalidDurableWrites(parsed.error.issues.map((issue) => issue.message).join('; '));
-        }
-        return {
-            store: parsed.data.store,
-            ...(parsed.data.namespace !== undefined
-                ? { namespace: parsed.data.namespace }
-                : options.commitOutboxScope?.namespace !== undefined
-                    ? { namespace: options.commitOutboxScope.namespace }
-                    : {}),
-        };
-    }
-    if (options.commitOutbox !== undefined) {
-        const parsed = durableWriteStoreSchema.safeParse(options.commitOutbox);
-        if (!parsed.success) {
-            throw invalidDurableWrites(parsed.error.issues.map((issue) => issue.message).join('; '));
-        }
-        return {
-            store: parsed.data,
-            ...(options.commitOutboxScope?.namespace !== undefined
-                ? { namespace: options.commitOutboxScope.namespace }
-                : {}),
-        };
-    }
-    return {};
-}

package/dist/transaction/environment.d.ts

@@ -1,105 +0,0 @@
-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

@@ -1,108 +0,0 @@
-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';
-}