@abloatai/transaction 0.37.0

package/dist/docs/catalog.js

@@ -0,0 +1,231 @@
+/**
+ * The catalog of documentation this package ships.
+ *
+ * One definition of *which docs exist*, read from the files themselves. Every
+ * reader — `ablo docs`, the public `/api/docs/*` routes, the MCP docs tools —
+ * resolves through here rather than keeping its own list, because a
+ * hand-maintained index of a directory is a copy that drifts the moment a page
+ * is added and nothing fails when it does. Before this module the public web
+ * allowlist had fallen 21 pages behind the corpus, including `coordination`.
+ *
+ * Title and description are DERIVED from each file's own convention: an H1,
+ * then a one-paragraph blockquote stating what the page is for. That blockquote
+ * is the description everywhere it is needed — the site frontmatter lifts the
+ * same line — so a page states its own promise exactly once, in the source that
+ * ships in the npm tarball and still reads correctly as plain markdown.
+ *
+ * The published set mirrors the tarball's `files` globs (`docs/*.md`,
+ * `docs/examples/*.md`, plus the three root files). Anything else under `docs/`
+ * — `docs/internal/**` above all — is neither shipped nor catalogued, and that
+ * exclusion is the only thing keeping internal notes off the public routes now
+ * that they read from here.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+const MARKDOWN_MIME = 'text/markdown; charset=utf-8';
+const TEXT_MIME = 'text/plain; charset=utf-8';
+/**
+ * The three files that document the package itself rather than a topic. They
+ * live at the package root, not under `docs/`, and none follows the H1 +
+ * blockquote convention — `llms.txt` opens with a prose paragraph and
+ * `README.md` with a banner — so their titles and descriptions are curated
+ * here, the one place that knows they are a different kind of artifact.
+ *
+ * Their slug is their filename, because the filename IS how these are referred
+ * to everywhere (`AGENTS.md` is an ecosystem convention, not a topic name) and
+ * because a bare word would collide: `docs/agents.md` is a published guide that
+ * the docs index cross-links as `agents`, and whichever of the two won that
+ * name would silently shadow the other. Friendlier spellings are aliases below.
+ */
+const PACKAGE_FILES = [
+    {
+        filename: 'AGENTS.md',
+        title: 'AGENTS.md',
+        description: 'The playbook a coding agent follows to install and drive Ablo without hanging on a prompt.',
+        mime: MARKDOWN_MIME,
+    },
+    {
+        filename: 'README.md',
+        title: 'README',
+        description: 'Package overview — what Ablo is and the shape of the API.',
+        mime: MARKDOWN_MIME,
+    },
+    {
+        filename: 'llms.txt',
+        title: 'llms.txt',
+        description: 'The curated single-file index of the whole API, for machine readers.',
+        mime: TEXT_MIME,
+    },
+];
+/**
+ * Curated redirects for references that are not a slug: the friendly spellings
+ * of the root files, plus the renames the public URLs carried before this
+ * module existed, kept so old links and any agent working from a cached page
+ * still resolve. Identity mappings are NOT listed — a slug resolves to itself
+ * by derivation, and restating the other 30 here would rebuild the
+ * hand-maintained list this module exists to delete.
+ */
+const SLUG_ALIASES = {
+    readme: 'README.md',
+    overview: 'README.md',
+    llms: 'llms.txt',
+    storage: 'data-sources',
+    'docs/storage.md': 'data-sources',
+};
+/**
+ * Read the catalog from a package root — the directory holding `docs/` and the
+ * three root files.
+ *
+ * The root is a parameter rather than resolved here because each reader knows
+ * it differently and they are genuinely different facts: the CLI resolves it
+ * against its own bundle inside `node_modules`, while the web app resolves it
+ * against the monorepo checkout. Nothing is cached; callers that serve many
+ * requests should memoize the returned array.
+ */
+export async function readDocsCatalog(packageRoot) {
+    const docsDir = join(packageRoot, 'docs');
+    const entries = [];
+    entries.push(...(await readDocsDirectory(docsDir, 'guide')));
+    entries.push(...(await readDocsDirectory(join(docsDir, 'examples'), 'example')));
+    for (const file of PACKAGE_FILES) {
+        const path = join(packageRoot, file.filename);
+        const body = await readFileOrNull(path);
+        if (body === null)
+            continue;
+        entries.push({
+            slug: file.filename,
+            title: file.title,
+            description: file.description,
+            kind: 'package',
+            path,
+            mime: file.mime,
+        });
+    }
+    return entries.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+/**
+ * Read one flat directory of markdown. Deliberately non-recursive: the shipped
+ * set is `docs/*.md` plus `docs/examples/*.md`, so descending would catalogue
+ * `docs/internal/**` — notes that are not in the tarball and must not reach a
+ * public route.
+ */
+async function readDocsDirectory(dir, kind) {
+    let names;
+    try {
+        const found = await readdir(dir, { withFileTypes: true });
+        names = found.filter((e) => e.isFile() && e.name.endsWith('.md')).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const path = join(dir, name);
+        const body = await readFileOrNull(path);
+        if (body === null)
+            continue;
+        const stem = basename(name, '.md');
+        const { title, description } = parseDocHeader(body);
+        entries.push({
+            slug: kind === 'example' ? `examples/${stem}` : stem,
+            title: title ?? stem,
+            description,
+            kind,
+            path,
+            mime: MARKDOWN_MIME,
+        });
+    }
+    return entries;
+}
+/** The H1 a page opens with, and the blockquote paragraph that follows it. */
+const H1_LINE = /^#[ \t]+(.+?)[ \t]*$/m;
+const PROMISE_BLOCKQUOTE = /^\s*\n((?:>.*\n)+)/;
+/**
+ * Pull a page's title and promise line out of its markdown.
+ *
+ * The convention every page follows: an H1, then a blockquote paragraph saying
+ * what the page is for. A page missing either simply reports what it has — the
+ * catalog never invents prose.
+ */
+export function parseDocHeader(body) {
+    const heading = H1_LINE.exec(body);
+    const title = heading?.[1] ?? null;
+    const afterHeading = heading === null ? body : body.slice(heading.index + heading[0].length);
+    const promise = PROMISE_BLOCKQUOTE.exec(afterHeading);
+    const description = promise?.[1]
+        ?.split('\n')
+        .filter(Boolean)
+        .map((line) => line.replace(/^>\s?/, ''))
+        .join(' ')
+        .trim() ?? '';
+    return { title, description };
+}
+/**
+ * Resolve a reference to a page. Accepts the slug (`coordination`), a curated
+ * alias (`storage`), or a repo-relative path (`docs/coordination.md`,
+ * `AGENTS.md`) — the three forms readers actually arrive with. Returns null
+ * rather than throwing so a caller can render its own not-found.
+ */
+export function findDoc(catalog, reference) {
+    const trimmed = reference.trim();
+    if (trimmed === '')
+        return null;
+    const direct = matchSlug(catalog, trimmed);
+    if (direct)
+        return direct;
+    const aliased = SLUG_ALIASES[trimmed.toLowerCase()];
+    if (aliased) {
+        const target = matchSlug(catalog, aliased);
+        if (target)
+            return target;
+    }
+    // Path form: `docs/coordination.md`, `docs/examples/nextjs.md`, `llms.txt`.
+    const asSlug = trimmed
+        .replace(/^\.?\//, '')
+        .replace(/^docs\//, '')
+        .replace(/\.(md|txt)$/i, '');
+    return matchSlug(catalog, asSlug);
+}
+function matchSlug(catalog, slug) {
+    const needle = slug.toLowerCase();
+    return catalog.find((entry) => entry.slug.toLowerCase() === needle) ?? null;
+}
+/**
+ * Slugs closest to a miss, for a "did you mean" line. Ranks by shared prefix,
+ * then substring containment — enough to catch a typo or a half-remembered
+ * name without pulling in a distance library.
+ */
+export function suggestSlugs(catalog, reference, limit = 3) {
+    const needle = reference.trim().toLowerCase();
+    if (needle === '')
+        return [];
+    return catalog
+        .map((entry) => {
+        const slug = entry.slug.toLowerCase();
+        let score = 0;
+        if (slug.includes(needle) || needle.includes(slug))
+            score += 10;
+        score += sharedPrefixLength(slug, needle);
+        return { slug: entry.slug, score };
+    })
+        .filter(({ score }) => score > 2)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(({ slug }) => slug);
+}
+function sharedPrefixLength(a, b) {
+    const max = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < max && a[i] === b[i])
+        i += 1;
+    return i;
+}
+async function readFileOrNull(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/dist/docs/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/docs/catalog.ts"],"names":[],"mappings":"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"}

package/dist/docs/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Programmatic access to the documentation this package ships.
+ *
+ * The docs travel in the npm tarball beside the code they describe, so a reader
+ * that resolves them through here is reading the pages for the version actually
+ * installed — not whatever the website is serving today. That is the whole
+ * point of the subpath: a published version is frozen, its docs are frozen with
+ * it, and the canonical `get` contract cannot drift behind a pinned dependency.
+ */
+export { readDocsCatalog, findDoc, parseDocHeader, suggestSlugs, type DocEntry, type DocKind, } from './catalog.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,OAAO,EACP,cAAc,EACd,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,OAAO,GACb,MAAM,cAAc,CAAC"}

package/dist/docs/index.js

@@ -0,0 +1,11 @@
+/**
+ * Programmatic access to the documentation this package ships.
+ *
+ * The docs travel in the npm tarball beside the code they describe, so a reader
+ * that resolves them through here is reading the pages for the version actually
+ * installed — not whatever the website is serving today. That is the whole
+ * point of the subpath: a published version is frozen, its docs are frozen with
+ * it, and the canonical `get` contract cannot drift behind a pinned dependency.
+ */
+export { readDocsCatalog, findDoc, parseDocHeader, suggestSlugs, } from './catalog.js';
+//# sourceMappingURL=index.js.map

package/dist/docs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,OAAO,EACP,cAAc,EACd,YAAY,GAGb,MAAM,cAAc,CAAC"}

package/dist/durableWrites.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 {};
+//# sourceMappingURL=durableWrites.d.ts.map

package/dist/durableWrites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durableWrites.d.ts","sourceRoot":"","sources":["../src/durableWrites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,IAAI,CACF,KAAK,EAAE,YAAY,EACnB,iBAAiB,EAAE,SAAS,MAAM,EAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,2EAA2E;IAC3E,IAAI,IAAI,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACpC,6DAA6D;IAC7D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,mDAWnC,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,yBAAyB;;;kBAIpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AASD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,uBAAuB,GAC/B,qBAAqB,CAwCvB"}

package/dist/durableWrites.js

@@ -0,0 +1,72 @@
+/**
+ * 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 {};
+}
+//# sourceMappingURL=durableWrites.js.map

package/dist/durableWrites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durableWrites.js","sourceRoot":"","sources":["../src/durableWrites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA8BlD,gFAAgF;AAChF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAC7C,CAAC,KAAK,EAAE,EAAE;IACR,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgC,CAAC;IACnD,OAAO,CACL,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU;QACpC,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU;QACpC,OAAO,SAAS,CAAC,MAAM,KAAK,UAAU,CACvC,CAAC;AACJ,CAAC,EACD,EAAE,OAAO,EAAE,mDAAmD,EAAE,CACjE,CAAC;AAEF,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,YAAY,CAAC;IACtD,KAAK,EAAE,uBAAuB;IAC9B,iFAAiF;IACjF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC/C,CAAC,CAAC;AAiBH,SAAS,oBAAoB,CAAC,OAAe;IAC3C,OAAO,IAAI,mBAAmB,CAAC,4CAA4C,OAAO,GAAG,EAAE;QACrF,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,eAAe;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAgC;IAEhC,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC9E,MAAM,oBAAoB,CACxB,iEAAiE,CAClE,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,yBAAyB,CAAC,SAAS,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC1E,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,oBAAoB,CACxB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC7D,CAAC;QACJ,CAAC;QACD,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK;YACxB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS;gBACrC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE;gBACtC,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,SAAS,KAAK,SAAS;oBAClD,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,SAAS,EAAE;oBACpD,CAAC,CAAC,EAAE,CAAC;SACV,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,oBAAoB,CACxB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC7D,CAAC;QACJ,CAAC;QACD,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,IAAI;YAClB,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,SAAS,KAAK,SAAS;gBACpD,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,iBAAiB,CAAC,SAAS,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/environment.d.ts

@@ -0,0 +1,106 @@
+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;
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,oCAAqC,CAAC;AAE/D,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,oCAAqC,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2BAA4B,CAAC;AACjE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,aAEgD,CAAC;AAE/E,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,gEAAgE;AAChE,eAAO,MAAM,oBAAoB;;;EAA2B,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,WAA8B,GAAG,WAAW,CAG1G;AAED,mDAAmD;AACnD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,CAEzE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,cAAc,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,oBAAoB,CAElF;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAEhE"}

package/dist/environment.js

@@ -0,0 +1,109 @@
+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';
+}
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,YAAY,EAAE,SAAS,CAAU,CAAC;AAE/D,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,YAAY,EAAE,SAAS,CAAU,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC;AAGjE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,KAAK,CAAC,wCAAwC,EAAE,0BAA0B,CAAC,CAAC;AAK/E,gEAAgE;AAChE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AAS7D;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc,EAAE,WAAwB,gBAAgB;IAC3F,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AACjD,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,iBAAiB,CAAC,KAAkB;IAClD,OAAO,KAAK,KAAK,gBAAgB,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAkB;IACvD,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAA2B;IAClE,OAAO,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAqB;IAC1D,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB,CAAC,KAAkB;IACrD,OAAO,KAAK,KAAK,SAAS,CAAC;AAC7B,CAAC"}