@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/events.js

@@ -0,0 +1,21 @@
+import { DEV_PROTOCOL } from './types.js';
+export class DevEventWriter {
+    writeLine;
+    now;
+    #sequence = 0;
+    constructor(writeLine, now = () => new Date()) {
+        this.writeLine = writeLine;
+        this.now = now;
+    }
+    emit(type, data) {
+        const event = {
+            protocol: DEV_PROTOCOL,
+            seq: ++this.#sequence,
+            time: this.now().toISOString(),
+            type,
+            data,
+        };
+        this.writeLine(JSON.stringify(event));
+        return event;
+    }
+}

package/vendor/spec/identity-keys.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Identity-assertion verification key set: the wire format of the `XEER_IDENTITY_PUBLIC_KEY`
+ * binding shared by the control plane (which attaches it to every user Worker) and the runtime
+ * verifier (which enforces it as a `kid` allowlist).
+ *
+ * Two shapes are accepted:
+ *
+ *   `<publicKeyRaw>`                     single unversioned key; accepts any signing key id
+ *   `<keyId>:<publicKeyRaw>[,<keyId>:<publicKeyRaw>]…`  versioned key set; strict allowlist
+ *
+ * Rotation keeps the outgoing and incoming key ids in the set for an overlap window no shorter
+ * than the maximum assertion lifetime plus clock skew (docs/AUTH_THREAT_MODEL.md, signing-key
+ * compromise row), then removes the outgoing key id.
+ */
+export declare const IDENTITY_KEY_SET_FORMAT: "xeer.identity-key-set.v0";
+export interface IdentityVerificationKey {
+    /** `null` only for the legacy single-key configuration, which accepts any signing key id. */
+    readonly keyId: string | null;
+    /** base64url-encoded raw 32-byte Ed25519 public key. Verification-only material. */
+    readonly publicKeyRaw: string;
+}
+export declare class IdentityKeySetError extends Error {
+    readonly code = "invalid_identity_key_set";
+    constructor(message: string);
+}
+/** Parses the binding value, failing closed on an absent, malformed, or ambiguous key set. */
+export declare function parseIdentityKeySet(configured: string | null | undefined): readonly IdentityVerificationKey[];
+/**
+ * Resolves the key a signing key id is allowed to use. A versioned set is a strict allowlist:
+ * an unknown key id resolves to `null` so the caller fails closed.
+ */
+export declare function selectIdentityVerificationKey(keys: readonly IdentityVerificationKey[], keyId: string | null | undefined): IdentityVerificationKey | null;
+/** Non-secret key ids, safe for readiness diagnostics; `*` marks the unversioned legacy key. */
+export declare function identityKeySetIds(keys: readonly IdentityVerificationKey[]): readonly string[];
+/** Canonical binding text: comma-separated, key id qualified whenever the input was. */
+export declare function formatIdentityKeySet(keys: readonly IdentityVerificationKey[]): string;

package/vendor/spec/identity-keys.js

@@ -0,0 +1,72 @@
+/**
+ * Identity-assertion verification key set: the wire format of the `XEER_IDENTITY_PUBLIC_KEY`
+ * binding shared by the control plane (which attaches it to every user Worker) and the runtime
+ * verifier (which enforces it as a `kid` allowlist).
+ *
+ * Two shapes are accepted:
+ *
+ *   `<publicKeyRaw>`                     single unversioned key; accepts any signing key id
+ *   `<keyId>:<publicKeyRaw>[,<keyId>:<publicKeyRaw>]…`  versioned key set; strict allowlist
+ *
+ * Rotation keeps the outgoing and incoming key ids in the set for an overlap window no shorter
+ * than the maximum assertion lifetime plus clock skew (docs/AUTH_THREAT_MODEL.md, signing-key
+ * compromise row), then removes the outgoing key id.
+ */
+export const IDENTITY_KEY_SET_FORMAT = 'xeer.identity-key-set.v0';
+/** Ed25519 raw public keys are 32 bytes, i.e. exactly 43 unpadded base64url characters. */
+const RAW_PUBLIC_KEY = /^[A-Za-z0-9_-]{43}$/u;
+const KEY_ID = /^[A-Za-z0-9_-]{1,64}$/u;
+const UNVERSIONED_KEY_LABEL = '*';
+export class IdentityKeySetError extends Error {
+    code = 'invalid_identity_key_set';
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityKeySetError';
+    }
+}
+/** Parses the binding value, failing closed on an absent, malformed, or ambiguous key set. */
+export function parseIdentityKeySet(configured) {
+    const entries = String(configured ?? '').trim().split(/[\s,;]+/u).filter((entry) => entry.length > 0);
+    if (entries.length === 0) {
+        throw new IdentityKeySetError('No identity-assertion verification key is configured.');
+    }
+    const keys = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        const separator = entry.indexOf(':');
+        const keyId = separator < 0 ? null : entry.slice(0, separator);
+        const publicKeyRaw = separator < 0 ? entry : entry.slice(separator + 1);
+        if (keyId === null && entries.length > 1) {
+            throw new IdentityKeySetError('Every key in a multi-key identity key set must carry its key id.');
+        }
+        if (keyId !== null && !KEY_ID.test(keyId)) {
+            throw new IdentityKeySetError(`Identity key id is invalid: ${JSON.stringify(keyId)}`);
+        }
+        if (!RAW_PUBLIC_KEY.test(publicKeyRaw)) {
+            throw new IdentityKeySetError(`Identity verification key ${keyId ?? UNVERSIONED_KEY_LABEL} must be a base64url raw 32-byte Ed25519 public key.`);
+        }
+        if (seen.has(keyId ?? UNVERSIONED_KEY_LABEL)) {
+            throw new IdentityKeySetError(`Identity key id is duplicated: ${keyId ?? UNVERSIONED_KEY_LABEL}`);
+        }
+        seen.add(keyId ?? UNVERSIONED_KEY_LABEL);
+        keys.push(Object.freeze({ keyId, publicKeyRaw }));
+    }
+    return Object.freeze(keys);
+}
+/**
+ * Resolves the key a signing key id is allowed to use. A versioned set is a strict allowlist:
+ * an unknown key id resolves to `null` so the caller fails closed.
+ */
+export function selectIdentityVerificationKey(keys, keyId) {
+    return keys.find((key) => key.keyId !== null && key.keyId === keyId)
+        ?? keys.find((key) => key.keyId === null)
+        ?? null;
+}
+/** Non-secret key ids, safe for readiness diagnostics; `*` marks the unversioned legacy key. */
+export function identityKeySetIds(keys) {
+    return Object.freeze(keys.map((key) => key.keyId ?? UNVERSIONED_KEY_LABEL));
+}
+/** Canonical binding text: comma-separated, key id qualified whenever the input was. */
+export function formatIdentityKeySet(keys) {
+    return keys.map((key) => (key.keyId === null ? key.publicKeyRaw : `${key.keyId}:${key.publicKeyRaw}`)).join(',');
+}

package/vendor/spec/index.d.ts

@@ -0,0 +1,20 @@
+export * from './types.js';
+export * from './diagnostics.js';
+export * from './schema.js';
+export * from './storage.js';
+export * from './canonical.js';
+export * from './public-assets.js';
+export * from './events.js';
+export * from './value.js';
+export * from './route.js';
+export * from './identity-keys.js';
+export * from './local-identity.js';
+export * from './schema-lifecycle.js';
+export * from './sql-expression.js';
+export * from './table-ddl.js';
+export * from './state-export.js';
+export * from './actions.js';
+export * from './admin.js';
+export * from './admin-sql.js';
+export * from './network-policy.js';
+export * from './review.js';

package/vendor/spec/index.js

@@ -0,0 +1,20 @@
+export * from './types.js';
+export * from './diagnostics.js';
+export * from './schema.js';
+export * from './storage.js';
+export * from './canonical.js';
+export * from './public-assets.js';
+export * from './events.js';
+export * from './value.js';
+export * from './route.js';
+export * from './identity-keys.js';
+export * from './local-identity.js';
+export * from './schema-lifecycle.js';
+export * from './sql-expression.js';
+export * from './table-ddl.js';
+export * from './state-export.js';
+export * from './actions.js';
+export * from './admin.js';
+export * from './admin-sql.js';
+export * from './network-policy.js';
+export * from './review.js';

package/vendor/spec/local-identity.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The local persona model shared by `xeer dev`, `xeer preview`, and `xeer test`.
+ *
+ * A local persona is a deterministic stand-in for an identity the platform would otherwise mint in
+ * a signed assertion. It carries the same two facts production membership carries — who the caller
+ * is, and which workspaces they belong to — so `workspaceTable()` policies and `memberOf()` guards
+ * are exercisable before anything is deployed.
+ *
+ * Everything here is a pure value contract, deliberately free of platform and Node dependencies:
+ * the runtime parses these cookies, the CLI writes them, and the test host serializes them, so the
+ * three must agree on one definition or local identity silently diverges between them.
+ *
+ * Workspace ids are the labels the builder declares. There is no hidden derivation: the same label
+ * is the same workspace on every machine, in `xeer dev` and in `xeer test`, which is what makes a
+ * membership assertion reproducible. The accepted shape is the *production* assertion charset (see
+ * `workspaceIds` in the identity assertion payload), so an id that works locally is an id the
+ * hosted auth service could also issue.
+ */
+export declare const LOCAL_PERSONA_COOKIE = "xeer_local_persona";
+export declare const LOCAL_WORKSPACE_COOKIE = "xeer_local_workspaces";
+/** Deterministic local identities. Each persona is a distinct application user. */
+export type LocalPersonaName = 'alice' | 'bob' | 'guest';
+export declare const LOCAL_PERSONA_NAMES: readonly LocalPersonaName[];
+/**
+ * Personas the local sign-in route may select. `guest` is deliberately absent: it is the unclaimed
+ * visitor a test uses to prove that neither alice's nor bob's rows leak, not a session to log into.
+ */
+export declare const LOCAL_SIGN_IN_PERSONA_NAMES: readonly LocalPersonaName[];
+/** The identity-assertion charset for a workspace id, so local ids stay production-shaped. */
+export declare const LOCAL_WORKSPACE_ID_PATTERN: RegExp;
+/**
+ * Local membership is a development fixture, not a directory. The cap keeps the cookie well inside
+ * every browser's per-cookie budget while staying far above what a local isolation test needs.
+ */
+export declare const MAXIMUM_LOCAL_WORKSPACES = 16;
+/** An unusable local membership specification. Always a builder input error, never a denial. */
+export declare class LocalWorkspaceMembershipError extends Error {
+    readonly code: "invalid_local_workspace";
+    constructor(message: string);
+}
+export declare function isLocalPersonaName(value: unknown): value is LocalPersonaName;
+/**
+ * Validates and de-duplicates a declared membership set, preserving declaration order so the
+ * single-workspace insert default (`preparePolicyInsert`) is predictable.
+ */
+export declare function normalizeLocalWorkspaceIds(values: readonly unknown[]): readonly string[];
+/**
+ * The one place the persona/membership pairing rule lives: only a provisioned identity can hold
+ * membership, and `guest` is by definition unprovisioned. A local persona that holds membership is
+ * therefore minted as `kind: "user"` — see `localPersonaAssertion` in the runtime.
+ */
+export declare function normalizeLocalMembership(persona: LocalPersonaName, workspaceIds: readonly unknown[]): readonly string[];
+/** True when a persona holding this membership is a provisioned user rather than a guest. */
+export declare function localPersonaKind(workspaceIds: readonly string[]): 'guest' | 'user';
+/** Parses one comma-separated membership list, as written in a cookie or a query parameter. */
+export declare function parseLocalWorkspaceList(value: string | null | undefined): readonly string[];
+/** The persona a session chose, or null when it made no choice and the baked default applies. */
+export declare function readLocalPersonaCookie(cookie: string | null | undefined): LocalPersonaName | null;
+/**
+ * The membership a session chose. An absent, empty, or malformed cookie is no membership: local
+ * identity fails closed, exactly as an assertion with an empty `workspaceIds` does.
+ */
+export declare function readLocalWorkspaceCookie(cookie: string | null | undefined): readonly string[];
+export declare function localWorkspaceCookieValue(workspaceIds: readonly string[]): string;
+/**
+ * The complete local identity selection as a single `cookie` request header. `xeer test` sends this
+ * for every call, so a test persona reaches the runtime through the same seam a browser uses.
+ */
+export declare function localIdentityCookieHeader(persona: LocalPersonaName, workspaceIds?: readonly string[]): string;

package/vendor/spec/local-identity.js

@@ -0,0 +1,132 @@
+/**
+ * The local persona model shared by `xeer dev`, `xeer preview`, and `xeer test`.
+ *
+ * A local persona is a deterministic stand-in for an identity the platform would otherwise mint in
+ * a signed assertion. It carries the same two facts production membership carries — who the caller
+ * is, and which workspaces they belong to — so `workspaceTable()` policies and `memberOf()` guards
+ * are exercisable before anything is deployed.
+ *
+ * Everything here is a pure value contract, deliberately free of platform and Node dependencies:
+ * the runtime parses these cookies, the CLI writes them, and the test host serializes them, so the
+ * three must agree on one definition or local identity silently diverges between them.
+ *
+ * Workspace ids are the labels the builder declares. There is no hidden derivation: the same label
+ * is the same workspace on every machine, in `xeer dev` and in `xeer test`, which is what makes a
+ * membership assertion reproducible. The accepted shape is the *production* assertion charset (see
+ * `workspaceIds` in the identity assertion payload), so an id that works locally is an id the
+ * hosted auth service could also issue.
+ */
+export const LOCAL_PERSONA_COOKIE = 'xeer_local_persona';
+export const LOCAL_WORKSPACE_COOKIE = 'xeer_local_workspaces';
+export const LOCAL_PERSONA_NAMES = Object.freeze(['alice', 'bob', 'guest']);
+/**
+ * Personas the local sign-in route may select. `guest` is deliberately absent: it is the unclaimed
+ * visitor a test uses to prove that neither alice's nor bob's rows leak, not a session to log into.
+ */
+export const LOCAL_SIGN_IN_PERSONA_NAMES = Object.freeze(['alice', 'bob']);
+/** The identity-assertion charset for a workspace id, so local ids stay production-shaped. */
+export const LOCAL_WORKSPACE_ID_PATTERN = /^[A-Za-z0-9:_-]{1,96}$/u;
+/**
+ * Local membership is a development fixture, not a directory. The cap keeps the cookie well inside
+ * every browser's per-cookie budget while staying far above what a local isolation test needs.
+ */
+export const MAXIMUM_LOCAL_WORKSPACES = 16;
+/** An unusable local membership specification. Always a builder input error, never a denial. */
+export class LocalWorkspaceMembershipError extends Error {
+    code = 'invalid_local_workspace';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalWorkspaceMembershipError';
+    }
+}
+export function isLocalPersonaName(value) {
+    return typeof value === 'string' && LOCAL_PERSONA_NAMES.includes(value);
+}
+/**
+ * Validates and de-duplicates a declared membership set, preserving declaration order so the
+ * single-workspace insert default (`preparePolicyInsert`) is predictable.
+ */
+export function normalizeLocalWorkspaceIds(values) {
+    const normalized = [];
+    for (const value of values) {
+        if (typeof value !== 'string' || !LOCAL_WORKSPACE_ID_PATTERN.test(value)) {
+            throw new LocalWorkspaceMembershipError(`Invalid workspace id ${JSON.stringify(String(value))}: use 1-96 characters from A-Z, a-z, 0-9, ':', '_', and '-'.`);
+        }
+        if (!normalized.includes(value))
+            normalized.push(value);
+    }
+    if (normalized.length > MAXIMUM_LOCAL_WORKSPACES) {
+        throw new LocalWorkspaceMembershipError(`A local persona may hold at most ${MAXIMUM_LOCAL_WORKSPACES} workspaces; ${normalized.length} were declared.`);
+    }
+    return Object.freeze(normalized);
+}
+/**
+ * The one place the persona/membership pairing rule lives: only a provisioned identity can hold
+ * membership, and `guest` is by definition unprovisioned. A local persona that holds membership is
+ * therefore minted as `kind: "user"` — see `localPersonaAssertion` in the runtime.
+ */
+export function normalizeLocalMembership(persona, workspaceIds) {
+    const normalized = normalizeLocalWorkspaceIds(workspaceIds);
+    if (persona === 'guest' && normalized.length > 0) {
+        throw new LocalWorkspaceMembershipError('The guest persona cannot carry workspace membership: it is the unclaimed visitor, and '
+            + 'membership is only ever held by a provisioned identity. Use alice or bob.');
+    }
+    return normalized;
+}
+/** True when a persona holding this membership is a provisioned user rather than a guest. */
+export function localPersonaKind(workspaceIds) {
+    return workspaceIds.length > 0 ? 'user' : 'guest';
+}
+/** Parses one comma-separated membership list, as written in a cookie or a query parameter. */
+export function parseLocalWorkspaceList(value) {
+    if (value === null || value === undefined)
+        return Object.freeze([]);
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return Object.freeze([]);
+    return normalizeLocalWorkspaceIds(trimmed.split(',').map((entry) => entry.trim()));
+}
+function cookieValue(cookie, name) {
+    if (!cookie)
+        return null;
+    for (const part of cookie.split(';')) {
+        const separator = part.indexOf('=');
+        if (separator < 0)
+            continue;
+        if (part.slice(0, separator).trim() !== name)
+            continue;
+        return part.slice(separator + 1).trim();
+    }
+    return null;
+}
+/** The persona a session chose, or null when it made no choice and the baked default applies. */
+export function readLocalPersonaCookie(cookie) {
+    const value = cookieValue(cookie, LOCAL_PERSONA_COOKIE);
+    return isLocalPersonaName(value) ? value : null;
+}
+/**
+ * The membership a session chose. An absent, empty, or malformed cookie is no membership: local
+ * identity fails closed, exactly as an assertion with an empty `workspaceIds` does.
+ */
+export function readLocalWorkspaceCookie(cookie) {
+    try {
+        return parseLocalWorkspaceList(cookieValue(cookie, LOCAL_WORKSPACE_COOKIE));
+    }
+    catch {
+        return Object.freeze([]);
+    }
+}
+export function localWorkspaceCookieValue(workspaceIds) {
+    return normalizeLocalWorkspaceIds(workspaceIds).join(',');
+}
+/**
+ * The complete local identity selection as a single `cookie` request header. `xeer test` sends this
+ * for every call, so a test persona reaches the runtime through the same seam a browser uses.
+ */
+export function localIdentityCookieHeader(persona, workspaceIds = []) {
+    const membership = normalizeLocalMembership(persona, workspaceIds);
+    const pairs = [`${LOCAL_PERSONA_COOKIE}=${persona}`];
+    if (membership.length > 0)
+        pairs.push(`${LOCAL_WORKSPACE_COOKIE}=${membership.join(',')}`);
+    return pairs.join('; ');
+}

package/vendor/spec/network-policy.d.ts

@@ -0,0 +1,16 @@
+/** The hosted control plane that ordinary CLI and MCP calls use. */
+export declare const DEFAULT_XEER_CONTROL_ORIGIN: "https://control.xeer.run";
+/** True only for a literal loopback hostname after URL canonicalization. */
+export declare function isLoopbackHostname(value: string): boolean;
+/**
+ * Canonical HTTP(S) origin, or undefined when the value carries a path, credentials, query, fragment,
+ * or another scheme. This is the boundary used before a bearer credential may be sent anywhere.
+ */
+export declare function exactHttpOrigin(value: string): string | undefined;
+/** A direct local inspector target. HTTPS and non-loopback hosts are never treated as local. */
+export declare function isLocalInspectorTarget(value: string): boolean;
+/**
+ * An exact hosted Xeer application origin. It is safe as an application reference: the CLI sends it
+ * to the control plane for owner resolution and never fetches the application URL directly.
+ */
+export declare function isHostedXeerApplicationTarget(value: string): boolean;

package/vendor/spec/network-policy.js

@@ -0,0 +1,50 @@
+/** The hosted control plane that ordinary CLI and MCP calls use. */
+export const DEFAULT_XEER_CONTROL_ORIGIN = 'https://control.xeer.run';
+function parsedUrl(value) {
+    if (/[\u0000-\u001f\u007f]/u.test(value))
+        return undefined;
+    try {
+        return new URL(value.trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True only for a literal loopback hostname after URL canonicalization. */
+export function isLoopbackHostname(value) {
+    const hostname = value.replace(/^\[(.*)\]$/u, '$1').toLowerCase();
+    if (hostname === 'localhost' || hostname === '::1')
+        return true;
+    const octets = hostname.split('.');
+    return octets.length === 4 && octets[0] === '127'
+        && octets.every((octet) => /^\d{1,3}$/u.test(octet) && Number(octet) <= 255);
+}
+/**
+ * Canonical HTTP(S) origin, or undefined when the value carries a path, credentials, query, fragment,
+ * or another scheme. This is the boundary used before a bearer credential may be sent anywhere.
+ */
+export function exactHttpOrigin(value) {
+    const url = parsedUrl(value);
+    if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:')
+        || url.pathname !== '/' || url.search || url.hash || url.username || url.password)
+        return undefined;
+    return url.origin;
+}
+/** A direct local inspector target. HTTPS and non-loopback hosts are never treated as local. */
+export function isLocalInspectorTarget(value) {
+    const url = parsedUrl(value);
+    return url !== undefined && url.protocol === 'http:' && !url.username && !url.password
+        && isLoopbackHostname(url.hostname);
+}
+/**
+ * An exact hosted Xeer application origin. It is safe as an application reference: the CLI sends it
+ * to the control plane for owner resolution and never fetches the application URL directly.
+ */
+export function isHostedXeerApplicationTarget(value) {
+    const url = parsedUrl(value);
+    if (!url || url.protocol !== 'https:' || url.port || url.pathname !== '/'
+        || url.search || url.hash || url.username || url.password)
+        return false;
+    const hostname = url.hostname.toLowerCase();
+    return hostname.length > '.xeer.run'.length && hostname.endsWith('.xeer.run');
+}

package/vendor/spec/public-assets.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Deliberately free of imports. The control plane and the dispatcher are Workers, and this module is
+ * the one piece of the contract they both need; pulling in `canonical.ts` would drag `node:crypto`
+ * across that boundary for the sake of a helper neither of them calls.
+ */
+export declare const PUBLIC_ASSETS_FORMAT: "xeer.assets.v0";
+/**
+ * The one prefix under which a URL *is* a content address, and which no application may occupy.
+ *
+ * It does **not** bypass the dispatcher — every request to a deployed application is routed through
+ * it, so a cold asset request still pays origin resolution and authorization. What a dedicated
+ * prefix buys is narrower and worth stating exactly: it stays clear of `/_xeer/*` (dispatcher) and
+ * `/__xeer/*` (runtime), both of which are claimed before the assets are consulted; it gives the
+ * `_headers` rule an exclusive namespace, so the immutable directive can never reach a mutable path;
+ * and it gives the deployment somewhere to route a *miss*, which is what turns a stale reference into
+ * a 404 instead of the single-page-application fallback.
+ */
+export declare const IMMUTABLE_ASSET_PREFIX: "/_xa/";
+/**
+ * What a hashed path is served with, and the reason the naming scheme exists at all.
+ *
+ * `immutable` (RFC 8246) tells a browser not to revalidate on an ordinary reload; a force reload
+ * still revalidates, so this does not cost anyone a debugging tool. It is only ever safe because the
+ * URL is a digest of the bytes — the same URL can never legitimately answer with anything else — and
+ * that is why {@link immutableAssetPath} is the only sanctioned way to mint one.
+ */
+export declare const IMMUTABLE_ASSET_CACHE_CONTROL: "public, max-age=31536000, immutable";
+/**
+ * How much of the digest goes into the URL: all of it.
+ *
+ * A truncated digest was the first design and it was wrong. The argument for it — that collisions are
+ * inconceivable across one application's three generated files — answers the wrong question. The
+ * threat model includes attacker-influenced bytes, and against a *constructed* pair the bound is the
+ * birthday bound over the retained prefix, not the second-preimage bound over the whole digest. At
+ * 128 bits that is 2^64 work to mint two files sharing a URL, one of which then inherits a one-year
+ * `immutable` cache entry that no later deployment can withdraw. Thirty-two more characters of URL is
+ * not a price worth arguing about against that.
+ *
+ * It also makes a property the rest of the system leans on actually true: equal paths imply equal
+ * bytes.
+ */
+export declare const IMMUTABLE_ASSET_HASH_LENGTH = 64;
+/**
+ * Upper bound on {@link PublicAssetsV0.retainedGenerations}.
+ *
+ * One, because one is what the control plane implements. A wider range was declared first and that
+ * was a promise the code did not keep: an artifact could ask for four generations and silently get
+ * one. A contract that can express a value nothing honours is worse than a narrow contract.
+ */
+export declare const MAX_RETAINED_ASSET_GENERATIONS = 1;
+/**
+ * What a declared entry is an alias *of*. Kept as a string rather than a structured pair because its
+ * only consumers are humans reading an artifact and a diagnostic naming the file that produced a
+ * collision — nothing branches on it.
+ */
+export type PublicAssetOrigin = `module:${string}` | `asset:${string}` | 'document';
+export interface ImmutableAssetV0 {
+    /**
+     * `${immutablePrefix}${hash.slice(7)}/${basename}`, and {@link parsePublicAssets} recomputes it
+     * rather than trusting it.
+     *
+     * That check alone is not sufficient and must never be mistaken for sufficient: it proves the path
+     * agrees with the *declared* digest, not that the declared digest describes the bytes being served.
+     * Only a party holding the bytes can prove the second half, and it has to be proved before an
+     * immutable directive is attached — see `verifyDeclaredAssetBytes` in the control plane.
+     */
+    path: string;
+    hash: `sha256:${string}`;
+    contentType: string;
+    size: number;
+    origin: PublicAssetOrigin;
+}
+export interface RevalidatedAssetV0 {
+    path: string;
+    contentType: string;
+    origin: PublicAssetOrigin;
+}
+/**
+ * The compiler's statement about which of an application's public URLs are content addresses and
+ * which are stable contracts. It is part of the artifact, so it is covered by `artifactId`, and it is
+ * the *only* thing downstream is allowed to classify an asset by: never the extension, never the
+ * content type, never the status code. An application endpoint may legitimately serve personalised
+ * bytes from a path that ends in `.js`, so inference from the shape of a URL is not a classification
+ * — it is a guess that is wrong the first time it matters.
+ */
+export interface PublicAssetsV0 {
+    format: typeof PUBLIC_ASSETS_FORMAT;
+    /**
+     * Published so every reader names the prefix from the artifact rather than from a literal of its
+     * own. Moving it is still a coordinated change — {@link parsePublicAssets} pins it to the compiled
+     * constant, deliberately, so a bundle cannot nominate its own reserved namespace — but there is
+     * exactly one place that knows the string.
+     */
+    immutablePrefix: typeof IMMUTABLE_ASSET_PREFIX;
+    /**
+     * How many *previous* deployments' immutable assets keep serving alongside this one.
+     *
+     * The value is `0` or `1` and nothing else — see {@link MAX_RETAINED_ASSET_GENERATIONS}. `1` means
+     * the deployment this artifact replaces keeps answering for its content-addressed paths; `0` means
+     * it does not, and a client holding the older document gets a 404.
+     *
+     * Worth recording honestly: this is the *incoming* artifact selecting an obligation that is owed to
+     * documents emitted by the *outgoing* one, and deployment cadence is a control-plane concern rather
+     * than a compiler fact. It lives here because it is covered by `artifactId` and therefore visible in
+     * a retained bundle, which is what a rollback replays. If retention ever needs an age component —
+     * Rails Sprockets keeps the last two versions *or* anything younger than an hour — that policy
+     * belongs to the control plane and this field should become a floor rather than the whole rule.
+     */
+    retainedGenerations: number;
+    /** Sorted by path. Cacheable forever, because the path is the digest. */
+    immutable: ImmutableAssetV0[];
+    /**
+     * Sorted by path. Declared public and deliberately *not* cacheable: the URL is a contract, the
+     * bytes are not.
+     *
+     * The compiler emits this exhaustively — the document plus every `public/**` file — and the control
+     * plane enforces that exhaustiveness where it matters, by requiring the uploaded asset set to be
+     * exactly `immutable ∪ revalidate`. Nothing here can therefore be a public URL the declaration
+     * failed to mention.
+     */
+    revalidate: RevalidatedAssetV0[];
+}
+/** The URL a blob of bytes is served at, and the only sanctioned way to mint one. */
+export declare function immutableAssetPath(hash: `sha256:${string}`, basename: string): string;
+/**
+ * A cheap structural pre-filter, and never the authority. Membership of
+ * {@link PublicAssetsV0.immutable} is what makes a path immutable; this only rejects the
+ * overwhelming majority of traffic before anything more expensive is consulted.
+ */
+export declare function isImmutableAssetPath(path: string): boolean;
+/**
+ * The `_headers` document Cloudflare's static asset layer applies to a deployment.
+ *
+ * One rule, scoped to the prefix. Nothing else may appear here: an `immutable` directive that leaked
+ * onto the HTML document would pin stale markup in every browser that saw it for a year, and no
+ * server-side action reaches a browser that has already stored one.
+ */
+export declare function immutableAssetHeaders(prefix?: string): string;
+/**
+ * Validates a declaration rather than trusting one. Every rule below has a failure it exists to
+ * prevent, and the two that matter most are the last two:
+ *
+ * - **path–hash binding.** If a hashed path could ever name bytes other than its own digest, the
+ *   immutable cache directive becomes unsafe and there is no way to withdraw it.
+ * - **prefix exclusivity.** If anything mutable could answer under the prefix, the single `_headers`
+ *   rule would make it permanently cacheable too.
+ */
+export declare function parsePublicAssets(value: unknown): PublicAssetsV0;
+/**
+ * Every path that must answer for this deployment, immutable first. The union a control plane uploads
+ * is this set for the current artifact plus the immutable half of the retained generations.
+ */
+export declare function declaredAssetPaths(declaration: PublicAssetsV0): readonly string[];