@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/state-export.d.ts

@@ -0,0 +1,143 @@
+import { type NormalizedDatabaseSchemaV0, type SchemaPlanStepV0 } from './schema-plan.js';
+import type { ApplicationSchemaIdentityV0, FieldDefinition, TableDefinition } from './types.js';
+import { type EncodedValue, type RuntimeValue } from './value.js';
+/**
+ * Portable dump of one application's stored records.
+ *
+ * The document is deliberately a logical dump rather than SQLite file bytes: a Durable Object
+ * offers no way to hand out its database file (its only first-class recovery surface is
+ * point-in-time recovery, which restores an object in place and cannot leave the platform), and a
+ * file would carry physical indexes and storage-layout details that mean nothing to a reader.
+ *
+ * Every document is self-describing: it carries the accepted application schema that produced the
+ * rows — the normalized table and field definitions plus their identity hash — so a human or an
+ * agent reading the file alone can tell what every value in `data` means, and `xeer import` can
+ * decide whether the rows still fit the schema it is importing into.
+ */
+export declare const STATE_EXPORT_PROTOCOL: "xeer.state-export.v0";
+/** Result protocol for a completed import; distinct from the document protocol on purpose. */
+export declare const STATE_IMPORT_PROTOCOL: "xeer.state-import.v0";
+/**
+ * One ceiling every hop agrees on: the runtime refuses to produce a larger export, the control
+ * plane refuses to proxy one, and `xeer import` refuses to send one. Exceeding it is a structured
+ * failure with a repair hint, never a truncated document.
+ */
+export declare const MAX_STATE_TRANSFER_BYTES: number;
+/** A single stored record: the runtime-owned identity and timestamps, plus its encoded fields. */
+export interface StateExportRecordV0 {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** The record's fields in the `xeer.value.v0` encoding, exactly as the runtime stores them. */
+    readonly data: EncodedValue;
+}
+export interface StateExportTableV0 {
+    readonly name: string;
+    readonly records: number;
+    readonly rows: readonly StateExportRecordV0[];
+}
+export interface StateExportSchemaV0 {
+    readonly applicationSchemaVersion: number;
+    readonly schemaHash: string;
+    /** The full normalized schema, so the document explains its own rows without the application. */
+    readonly database: NormalizedDatabaseSchemaV0;
+}
+export interface StateExportV0 {
+    readonly protocol: typeof STATE_EXPORT_PROTOCOL;
+    readonly exportedAt: string;
+    readonly application: string;
+    /** Present when the state was read from an app with a control-plane identity. */
+    readonly appId?: string;
+    readonly source: {
+        readonly artifactId: string;
+        readonly generation: number;
+    };
+    /** Version of the runtime's storage layout the rows were read from. */
+    readonly storage: {
+        readonly schemaVersion: number;
+    };
+    readonly schema: StateExportSchemaV0;
+    readonly tables: readonly StateExportTableV0[];
+    readonly counts: {
+        readonly tables: number;
+        readonly records: number;
+    };
+}
+export interface StateImportResultV0 {
+    readonly protocol: typeof STATE_IMPORT_PROTOCOL;
+    readonly application: string;
+    readonly schema: ApplicationSchemaIdentityV0;
+    /** `identical` when the export came from this exact schema; `compatible` when it fits forward. */
+    readonly classification: 'identical' | 'compatible';
+    readonly steps: readonly SchemaPlanStepV0[];
+    readonly importedTables: readonly {
+        readonly name: string;
+        readonly records: number;
+    }[];
+    readonly importedRecords: number;
+    readonly removedRecords: number;
+}
+export type StateTransferErrorCode = 'state_export_malformed' | 'state_export_protocol_unsupported' | 'state_export_too_large' | 'state_import_application_mismatch' | 'state_import_schema_mismatch' | 'state_import_record_invalid';
+/**
+ * Machine-readable refusal, carried verbatim from the runtime through to the CLI diagnostic. */
+export interface StateTransferDiagnostic {
+    readonly code: StateTransferErrorCode;
+    readonly message: string;
+    readonly hint?: string;
+    /** The mismatch itself, as plain JSON: expected and found identities, offending row, plan steps. */
+    readonly detail: Record<string, unknown>;
+}
+/**
+ * A refusal a caller can act on: a stable code, the mismatch itself in `detail`, and a repair hint.
+ * Import failures are reported this way rather than as a bare message so an agent can decide what
+ * to do without parsing prose.
+ */
+export declare class StateTransferError extends Error {
+    readonly code: StateTransferErrorCode;
+    readonly hint?: string | undefined;
+    readonly detail: Record<string, unknown>;
+    constructor(code: StateTransferErrorCode, message: string, hint?: string | undefined, detail?: Record<string, unknown>);
+    /** JSON shape shared by the runtime response, the control-plane envelope, and CLI diagnostics. */
+    toDiagnostic(): StateTransferDiagnostic;
+}
+/**
+ * Whether a decoded value satisfies a declared field. Shared with the runtime so an imported record
+ * is held to exactly the same rule a handler-written record is.
+ */
+export declare function fieldValueValid(field: FieldDefinition, value: RuntimeValue): boolean;
+/**
+ * Structural validation of an export document. It proves the file is a well-formed
+ * `xeer.state-export.v0` document that describes itself consistently; whether its rows fit a
+ * particular application is {@link planStateImport}'s question.
+ */
+export declare function parseStateExport(value: unknown): StateExportV0;
+export interface StateImportPlanV0 {
+    readonly classification: 'identical' | 'compatible';
+    readonly steps: readonly SchemaPlanStepV0[];
+    readonly tables: readonly {
+        readonly name: string;
+        readonly records: number;
+    }[];
+    readonly records: number;
+}
+/**
+ * Decides whether an export may be written into the schema currently in force, and validates every
+ * row against it.
+ *
+ * An export is accepted when it came from this exact schema, or from a schema the current one is a
+ * *compatible* successor of — the same classification the runtime already uses to accept a schema
+ * change without a reset, so an import can never introduce a row the running application could not
+ * have written itself. Anything else is refused with the mismatch in `detail`; there is no override,
+ * because the alternative is state the application's own type contract does not describe.
+ */
+export declare function planStateImport(input: {
+    readonly document: StateExportV0;
+    readonly application: string;
+    readonly schema: NormalizedDatabaseSchemaV0;
+    readonly identity: ApplicationSchemaIdentityV0;
+}): StateImportPlanV0;
+/** Holds one imported record to the declared field contract of the table it is being written into. */
+export declare function validateExportedRecord(tableName: string, table: TableDefinition, row: StateExportRecordV0): Record<string, RuntimeValue>;
+/** Serialized size of a document, used to hold every hop to {@link MAX_STATE_TRANSFER_BYTES}. */
+export declare function stateExportBytes(document: unknown): number;
+export declare function assertStateTransferSize(document: unknown, what: 'export' | 'import'): void;

package/vendor/spec/state-export.js

@@ -0,0 +1,341 @@
+import { planSchemaChangeWithIdentities, SchemaPlanningError, } from './schema-plan.js';
+import { normalizedDatabaseSchema } from './schema.js';
+import { decodeValue } from './value.js';
+// Deliberately no dependency on `./canonical.js` or `./schema-lifecycle.js`: this module is bundled
+// into every deployed application Worker, and those pull in `node:crypto`.
+/**
+ * Portable dump of one application's stored records.
+ *
+ * The document is deliberately a logical dump rather than SQLite file bytes: a Durable Object
+ * offers no way to hand out its database file (its only first-class recovery surface is
+ * point-in-time recovery, which restores an object in place and cannot leave the platform), and a
+ * file would carry physical indexes and storage-layout details that mean nothing to a reader.
+ *
+ * Every document is self-describing: it carries the accepted application schema that produced the
+ * rows — the normalized table and field definitions plus their identity hash — so a human or an
+ * agent reading the file alone can tell what every value in `data` means, and `xeer import` can
+ * decide whether the rows still fit the schema it is importing into.
+ */
+export const STATE_EXPORT_PROTOCOL = 'xeer.state-export.v0';
+/** Result protocol for a completed import; distinct from the document protocol on purpose. */
+export const STATE_IMPORT_PROTOCOL = 'xeer.state-import.v0';
+/**
+ * One ceiling every hop agrees on: the runtime refuses to produce a larger export, the control
+ * plane refuses to proxy one, and `xeer import` refuses to send one. Exceeding it is a structured
+ * failure with a repair hint, never a truncated document.
+ */
+export const MAX_STATE_TRANSFER_BYTES = 8 * 1024 * 1024;
+/**
+ * A refusal a caller can act on: a stable code, the mismatch itself in `detail`, and a repair hint.
+ * Import failures are reported this way rather than as a bare message so an agent can decide what
+ * to do without parsing prose.
+ */
+export class StateTransferError extends Error {
+    code;
+    hint;
+    detail;
+    constructor(code, message, hint, detail = {}) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.detail = detail;
+        this.name = 'StateTransferError';
+    }
+    /** JSON shape shared by the runtime response, the control-plane envelope, and CLI diagnostics. */
+    toDiagnostic() {
+        return { code: this.code, message: this.message, ...(this.hint ? { hint: this.hint } : {}), detail: this.detail };
+    }
+}
+function malformed(message, detail = {}) {
+    return new StateTransferError('state_export_malformed', message, 'Import the unmodified file `xeer export` produced; a hand-edited document must keep the '
+        + 'protocol, schema, tables, and counts fields consistent.', detail);
+}
+function plainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : null;
+}
+function isoTimestamp(value) {
+    return typeof value === 'string' && value.length > 0 && !Number.isNaN(Date.parse(value));
+}
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/u;
+/**
+ * Structural validation of the value encoding before anything decodes it: `decodeValue` trusts its
+ * input, so an imported document must be proven well-formed first.
+ */
+function validEncodedValue(value, path) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw malformed(`Encoded value at ${path} is not a finite number.`);
+        return;
+    }
+    const record = plainObject(value);
+    if (!record)
+        throw malformed(`Encoded value at ${path} is not a valid xeer.value.v0 node.`);
+    const keys = Object.keys(record).sort();
+    const tag = record.$xeer;
+    if (tag === 'undefined') {
+        if (keys.length !== 1)
+            throw malformed(`Encoded undefined at ${path} carries unexpected keys.`);
+        return;
+    }
+    if (keys.length !== 2 || keys[0] !== '$xeer' || keys[1] !== 'value') {
+        throw malformed(`Encoded value at ${path} must carry exactly $xeer and value.`);
+    }
+    if (tag === 'date') {
+        if (!isoTimestamp(record.value))
+            throw malformed(`Encoded date at ${path} is not an ISO timestamp.`);
+        return;
+    }
+    if (tag === 'bytes') {
+        if (typeof record.value !== 'string' || !BASE64.test(record.value)) {
+            throw malformed(`Encoded bytes at ${path} are not base64.`);
+        }
+        return;
+    }
+    if (tag === 'array') {
+        if (!Array.isArray(record.value))
+            throw malformed(`Encoded array at ${path} has no array value.`);
+        record.value.forEach((item, index) => validEncodedValue(item, `${path}[${index}]`));
+        return;
+    }
+    if (tag === 'object') {
+        const nested = plainObject(record.value);
+        if (!nested)
+            throw malformed(`Encoded object at ${path} has no object value.`);
+        for (const [key, item] of Object.entries(nested))
+            validEncodedValue(item, `${path}.${key}`);
+        return;
+    }
+    throw malformed(`Unknown encoded value tag at ${path}.`, { tag: typeof tag === 'string' ? tag : null });
+}
+/**
+ * Whether a decoded value satisfies a declared field. Shared with the runtime so an imported record
+ * is held to exactly the same rule a handler-written record is.
+ */
+export function fieldValueValid(field, value) {
+    // `null` and `undefined` are one state, because the column they land in has one. A nullable column
+    // cannot tell "omitted" from "written as null", so accepting one spelling and refusing the other
+    // would be a rule about the manifest rather than about the data. It also closes a hole: a required
+    // `json` field used to accept `null` here and then fail against its own NOT NULL, turning a
+    // repairable validation message into a raw SQLite error.
+    if (value === undefined || value === null)
+        return field.optional === true;
+    switch (field.type) {
+        case 'string': return typeof value === 'string' && (field.maxLength === undefined || value.length <= field.maxLength)
+            && (field.enum === undefined || field.enum.includes(value));
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean': return typeof value === 'boolean';
+        case 'datetime': return value instanceof Date && !Number.isNaN(value.getTime());
+        case 'bytes': return value instanceof Uint8Array && (field.maxLength === undefined || value.byteLength <= field.maxLength);
+        case 'json': return true;
+        // A ref holds the id of a row in another table. Whether that row exists is the FOREIGN KEY's
+        // job, checked by SQLite on write; all this can say is that the value has an id's shape.
+        case 'ref': return typeof value === 'string' && value.length > 0;
+    }
+}
+/**
+ * Validates the schema the document embeds. The rows are always held to the *live* schema of the
+ * application being imported into, so this check exists to keep a malformed document from reaching
+ * the schema planner as anything other than a structured refusal.
+ *
+ * It defers to the schema that validates a manifest's database block, because it is validating the
+ * same thing: a document written by one version of the vocabulary and read by another is exactly the
+ * case where a second, hand-rolled copy of the rules would quietly disagree with the first.
+ */
+function parseEmbeddedSchema(value) {
+    const parsed = normalizedDatabaseSchema.safeParse(value);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw malformed(`schema.database is not a normalized database schema: ${['database', ...issue.path].join('.')} ${issue.message}.`);
+    }
+    return parsed.data;
+}
+function parseRecord(table, index, value) {
+    const row = plainObject(value);
+    if (!row)
+        throw malformed(`Row ${index} of table ${table} is not an object.`);
+    if (typeof row.id !== 'string' || row.id.length === 0 || row.id.length > 256) {
+        throw malformed(`Row ${index} of table ${table} has no usable id.`);
+    }
+    if (!isoTimestamp(row.createdAt) || !isoTimestamp(row.updatedAt)) {
+        throw malformed(`Row ${row.id} of table ${table} has non-ISO timestamps.`);
+    }
+    if (!Object.hasOwn(row, 'data'))
+        throw malformed(`Row ${row.id} of table ${table} carries no data.`);
+    const data = plainObject(row.data);
+    if (!data || data.$xeer !== 'object') {
+        throw malformed(`Row ${row.id} of table ${table} must encode its fields as a xeer.value.v0 object.`);
+    }
+    validEncodedValue(row.data, `${table}[${index}].data`);
+    return { id: row.id, createdAt: row.createdAt, updatedAt: row.updatedAt,
+        data: row.data };
+}
+/**
+ * Structural validation of an export document. It proves the file is a well-formed
+ * `xeer.state-export.v0` document that describes itself consistently; whether its rows fit a
+ * particular application is {@link planStateImport}'s question.
+ */
+export function parseStateExport(value) {
+    const source = plainObject(value);
+    if (!source)
+        throw malformed('A state export must be a JSON object.');
+    if (source.protocol !== STATE_EXPORT_PROTOCOL) {
+        throw new StateTransferError('state_export_protocol_unsupported', `Unsupported state export protocol ${JSON.stringify(source.protocol ?? null)}; this build reads ${STATE_EXPORT_PROTOCOL}.`, 'Re-export the state with a matching `xeer` version, or upgrade the CLI to one that reads this protocol.', { expected: STATE_EXPORT_PROTOCOL, found: source.protocol ?? null });
+    }
+    if (!isoTimestamp(source.exportedAt))
+        throw malformed('exportedAt must be an ISO timestamp.');
+    if (typeof source.application !== 'string' || source.application.length === 0) {
+        throw malformed('application must be the exporting application name.');
+    }
+    if (source.appId !== undefined && (typeof source.appId !== 'string' || source.appId.length === 0)) {
+        throw malformed('appId must be a non-empty string when present.');
+    }
+    const origin = plainObject(source.source);
+    if (!origin || typeof origin.artifactId !== 'string' || !Number.isSafeInteger(origin.generation)) {
+        throw malformed('source must carry the exporting artifactId and generation.');
+    }
+    const storage = plainObject(source.storage);
+    if (!storage || !Number.isSafeInteger(storage.schemaVersion)) {
+        throw malformed('storage.schemaVersion must be an integer.');
+    }
+    const schema = plainObject(source.schema);
+    if (!schema || !Number.isSafeInteger(schema.applicationSchemaVersion)
+        || typeof schema.schemaHash !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(schema.schemaHash)) {
+        throw malformed('schema must carry applicationSchemaVersion, schemaHash, and the normalized database schema.');
+    }
+    const database = parseEmbeddedSchema(schema.database);
+    if (Number(schema.applicationSchemaVersion) !== database.version) {
+        throw malformed('schema.applicationSchemaVersion does not match the embedded database.version.', { applicationSchemaVersion: schema.applicationSchemaVersion, databaseVersion: database.version });
+    }
+    if (!Array.isArray(source.tables))
+        throw malformed('tables must be an array.');
+    const names = new Set();
+    const tables = source.tables.map((entry) => {
+        const table = plainObject(entry);
+        if (!table || typeof table.name !== 'string' || table.name.length === 0) {
+            throw malformed('Every table must carry a name.');
+        }
+        if (names.has(table.name))
+            throw malformed(`Table ${table.name} appears twice.`);
+        names.add(table.name);
+        if (!Array.isArray(table.rows))
+            throw malformed(`Table ${table.name} must carry a rows array.`);
+        if (table.records !== table.rows.length) {
+            throw malformed(`Table ${table.name} declares ${String(table.records)} records but carries ${table.rows.length}.`, { table: table.name, declared: table.records, rows: table.rows.length });
+        }
+        const rows = table.rows.map((row, index) => parseRecord(table.name, index, row));
+        const ids = new Set(rows.map((row) => row.id));
+        if (ids.size !== rows.length)
+            throw malformed(`Table ${table.name} repeats a record id.`, { table: table.name });
+        return { name: table.name, records: rows.length, rows };
+    });
+    const counts = plainObject(source.counts);
+    const records = tables.reduce((total, table) => total + table.records, 0);
+    if (!counts || counts.tables !== tables.length || counts.records !== records) {
+        throw malformed('counts must match the exported tables and rows.', { tables: tables.length, records, declared: counts ?? null });
+    }
+    return {
+        protocol: STATE_EXPORT_PROTOCOL,
+        exportedAt: source.exportedAt,
+        application: source.application,
+        ...(source.appId === undefined ? {} : { appId: source.appId }),
+        source: { artifactId: origin.artifactId, generation: Number(origin.generation) },
+        storage: { schemaVersion: Number(storage.schemaVersion) },
+        schema: {
+            applicationSchemaVersion: Number(schema.applicationSchemaVersion),
+            schemaHash: schema.schemaHash,
+            database,
+        },
+        tables,
+        counts: { tables: tables.length, records },
+    };
+}
+function schemaMismatch(message, document, identity, detail = {}) {
+    return new StateTransferError('state_import_schema_mismatch', message, `Check out the application schema this export was taken from (database.version `
+        + `${document.schema.applicationSchemaVersion}, ${document.schema.schemaHash}), import there, and let the `
+        + 'normal compatible-change path carry the data forward — or re-export from the current schema. '
+        + 'There is no forced import: writing rows a schema does not describe would corrupt the state '
+        + 'the application is allowed to assume.', { expected: identity, found: { applicationSchemaVersion: document.schema.applicationSchemaVersion,
+            schemaHash: document.schema.schemaHash }, ...detail });
+}
+/**
+ * Decides whether an export may be written into the schema currently in force, and validates every
+ * row against it.
+ *
+ * An export is accepted when it came from this exact schema, or from a schema the current one is a
+ * *compatible* successor of — the same classification the runtime already uses to accept a schema
+ * change without a reset, so an import can never introduce a row the running application could not
+ * have written itself. Anything else is refused with the mismatch in `detail`; there is no override,
+ * because the alternative is state the application's own type contract does not describe.
+ */
+export function planStateImport(input) {
+    const { document, application, schema, identity } = input;
+    if (document.application !== application) {
+        throw new StateTransferError('state_import_application_mismatch', `This export belongs to application ${JSON.stringify(document.application)}, not ${JSON.stringify(application)}.`, 'Import it into the application it was exported from. Application state is not portable between '
+            + 'applications: table and field meaning is defined per application.', { expected: application, found: document.application });
+    }
+    const identical = document.schema.schemaHash === identity.schemaHash
+        && document.schema.applicationSchemaVersion === identity.applicationSchemaVersion;
+    let steps = [];
+    if (!identical) {
+        let plan;
+        try {
+            plan = planSchemaChangeWithIdentities(application, document.schema.database, { applicationSchemaVersion: document.schema.applicationSchemaVersion,
+                schemaHash: document.schema.schemaHash }, schema, identity);
+        }
+        catch (error) {
+            throw schemaMismatch(error instanceof SchemaPlanningError
+                ? `This export cannot be replayed into the current schema: ${error.message}`
+                : 'This export cannot be replayed into the current schema.', document, identity, { planningError: error instanceof SchemaPlanningError ? error.code : 'schema_plan_failed' });
+        }
+        if (plan.classification === 'incompatible') {
+            throw schemaMismatch(`This export was taken from application schema version ${document.schema.applicationSchemaVersion}, which is `
+                + `incompatible with the current version ${identity.applicationSchemaVersion}.`, document, identity, { steps: plan.steps });
+        }
+        steps = plan.steps;
+    }
+    const tables = [];
+    for (const table of document.tables) {
+        const definition = schema.tables[table.name];
+        if (!definition) {
+            throw schemaMismatch(`The current schema has no table ${JSON.stringify(table.name)}.`, document, identity, { table: table.name, currentTables: Object.keys(schema.tables).sort() });
+        }
+        for (const row of table.rows)
+            validateExportedRecord(table.name, definition, row);
+        tables.push({ name: table.name, records: table.records });
+    }
+    return { classification: identical ? 'identical' : 'compatible', steps, tables, records: document.counts.records };
+}
+/** Holds one imported record to the declared field contract of the table it is being written into. */
+export function validateExportedRecord(tableName, table, row) {
+    const decoded = decodeValue(row.data);
+    const invalid = (message, detail = {}) => new StateTransferError('state_import_record_invalid', message, 'Re-export the state from an application whose schema matches this data, or repair the record in '
+        + 'the export file so every field matches its declared type.', { table: tableName, record: row.id, ...detail });
+    for (const key of Object.keys(decoded)) {
+        if (key === 'id' || key === 'createdAt' || key === 'updatedAt') {
+            throw invalid(`Record ${row.id} of ${tableName} stores runtime-owned field ${key} in its data.`, { field: key });
+        }
+        if (!(key in table.fields)) {
+            throw invalid(`Record ${row.id} of ${tableName} carries unknown field ${key}.`, { field: key, fields: Object.keys(table.fields).sort() });
+        }
+    }
+    for (const [name, field] of Object.entries(table.fields)) {
+        if (!fieldValueValid(field, decoded[name])) {
+            throw invalid(`Record ${row.id} of ${tableName} has an invalid value for ${name}.`, { field: name, expected: field.type, optional: field.optional === true });
+        }
+    }
+    return decoded;
+}
+/** Serialized size of a document, used to hold every hop to {@link MAX_STATE_TRANSFER_BYTES}. */
+export function stateExportBytes(document) {
+    return new TextEncoder().encode(JSON.stringify(document)).byteLength;
+}
+export function assertStateTransferSize(document, what) {
+    const bytes = stateExportBytes(document);
+    if (bytes <= MAX_STATE_TRANSFER_BYTES)
+        return;
+    throw new StateTransferError('state_export_too_large', `This state ${what} is ${bytes} bytes, above the ${MAX_STATE_TRANSFER_BYTES}-byte transfer ceiling.`, 'Xeer v0 transfers state in one document. Reduce the stored data, or read it in place with '
+        + '`xeer state` until chunked transfer lands.', { bytes, limit: MAX_STATE_TRANSFER_BYTES });
+}

package/vendor/spec/storage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The `storage` capability's shared vocabulary: the platform ceilings a manifest is capped against,
+ * the object-key contract, and the binding name a provisioned bucket is attached under.
+ *
+ * This module is deliberately dependency-free and lives in `spec` rather than in the runtime, because
+ * three separate layers have to agree on exactly the same rules and none of them may re-derive them:
+ *
+ *   the compiler   normalizes and caps the manifest's declared limits (`schema.ts`);
+ *   the runtime    validates every key and enforces every byte budget before touching R2;
+ *   the control    plane derives the bucket name and never lets it reach the artifact.
+ *
+ * A key rule that differed between the compiler and the runtime would mean an application that
+ * builds and then fails at call time, which is the one failure mode a declared contract exists to
+ * remove.
+ */
+/**
+ * The Worker binding name a provisioned per-app bucket is attached under. Platform-owned and never
+ * user-chosen, like `XEER_STATE`: the `XEER_` prefix is reserved everywhere a name can be supplied
+ * (the control plane's environment store refuses it, `packages/control/src/env.ts`), so an
+ * application value can never shadow it and `ctx.env` can never reach it — `selectAppEnv` projects
+ * only `XEER_ENV_*`, and an R2 bucket is not a string.
+ */
+export declare const STORAGE_BINDING_NAME: "XEER_STORAGE";
+/**
+ * The platform ceiling for one stored object, and the default when a manifest declares the
+ * capability without naming a limit.
+ *
+ * 25 MiB matches the artifact's own per-asset ceiling, which is the largest single payload anything
+ * else in v0 accepts, so an application cannot store an object it could never have shipped. It is
+ * well under R2's own 5 GiB single-put limit: the binding constraint is not R2 but the Worker request
+ * body a `put` is fed from.
+ */
+export declare const STORAGE_MAX_OBJECT_BYTES: number;
+/**
+ * Per-handler read and write byte budgets, in the same spirit as `queryRows` and `mutationWrites`:
+ * one handler may not stream unbounded bytes through the platform on a single request. Defaults are
+ * generous enough for a handler that moves one maximum-sized object and small enough that a runaway
+ * loop is refused rather than billed.
+ */
+export declare const STORAGE_DEFAULT_READ_BYTES: number;
+export declare const STORAGE_DEFAULT_WRITE_BYTES: number;
+/** Ceilings for the two budgets above; a manifest may lower them, never raise them past these. */
+export declare const STORAGE_MAX_READ_BYTES: number;
+export declare const STORAGE_MAX_WRITE_BYTES: number;
+/**
+ * `list` is bounded exactly the way `find` is: a default page a caller does not have to think about,
+ * and a hard ceiling it cannot ask past. Not manifest-configurable — a listing page size is a
+ * transport detail, not an application contract, and R2's own list ceiling is 1,000.
+ */
+export declare const STORAGE_LIST_DEFAULT_LIMIT = 100;
+export declare const STORAGE_LIST_MAX_LIMIT = 1000;
+/** Longest object key. R2 accepts 1,024 UTF-8 bytes; half of that is ample and leaves headroom. */
+export declare const STORAGE_MAX_KEY_BYTES = 512;
+export type StorageKeyRefusal = 'storage_key_empty' | 'storage_key_too_long' | 'storage_key_invalid';
+/** Why a key is refused, or `null` when it is acceptable. One implementation, three consumers. */
+export declare function storageKeyRefusal(key: unknown): StorageKeyRefusal | null;
+/** The same question for a list prefix, which may end in a slash or mid-segment. */
+export declare function storagePrefixRefusal(prefix: unknown): StorageKeyRefusal | null;
+export declare function storageKeyValid(key: unknown): key is string;
+/** The human wording for each refusal, shared so the runtime and the CLI say the same thing. */
+export declare function storageKeyMessage(refusal: StorageKeyRefusal, key: unknown, kind?: string): string;

package/vendor/spec/storage.js

@@ -0,0 +1,120 @@
+/**
+ * The `storage` capability's shared vocabulary: the platform ceilings a manifest is capped against,
+ * the object-key contract, and the binding name a provisioned bucket is attached under.
+ *
+ * This module is deliberately dependency-free and lives in `spec` rather than in the runtime, because
+ * three separate layers have to agree on exactly the same rules and none of them may re-derive them:
+ *
+ *   the compiler   normalizes and caps the manifest's declared limits (`schema.ts`);
+ *   the runtime    validates every key and enforces every byte budget before touching R2;
+ *   the control    plane derives the bucket name and never lets it reach the artifact.
+ *
+ * A key rule that differed between the compiler and the runtime would mean an application that
+ * builds and then fails at call time, which is the one failure mode a declared contract exists to
+ * remove.
+ */
+/**
+ * The Worker binding name a provisioned per-app bucket is attached under. Platform-owned and never
+ * user-chosen, like `XEER_STATE`: the `XEER_` prefix is reserved everywhere a name can be supplied
+ * (the control plane's environment store refuses it, `packages/control/src/env.ts`), so an
+ * application value can never shadow it and `ctx.env` can never reach it — `selectAppEnv` projects
+ * only `XEER_ENV_*`, and an R2 bucket is not a string.
+ */
+export const STORAGE_BINDING_NAME = 'XEER_STORAGE';
+/**
+ * The platform ceiling for one stored object, and the default when a manifest declares the
+ * capability without naming a limit.
+ *
+ * 25 MiB matches the artifact's own per-asset ceiling, which is the largest single payload anything
+ * else in v0 accepts, so an application cannot store an object it could never have shipped. It is
+ * well under R2's own 5 GiB single-put limit: the binding constraint is not R2 but the Worker request
+ * body a `put` is fed from.
+ */
+export const STORAGE_MAX_OBJECT_BYTES = 25 * 1024 * 1024;
+/**
+ * Per-handler read and write byte budgets, in the same spirit as `queryRows` and `mutationWrites`:
+ * one handler may not stream unbounded bytes through the platform on a single request. Defaults are
+ * generous enough for a handler that moves one maximum-sized object and small enough that a runaway
+ * loop is refused rather than billed.
+ */
+export const STORAGE_DEFAULT_READ_BYTES = 32 * 1024 * 1024;
+export const STORAGE_DEFAULT_WRITE_BYTES = 32 * 1024 * 1024;
+/** Ceilings for the two budgets above; a manifest may lower them, never raise them past these. */
+export const STORAGE_MAX_READ_BYTES = 128 * 1024 * 1024;
+export const STORAGE_MAX_WRITE_BYTES = 128 * 1024 * 1024;
+/**
+ * `list` is bounded exactly the way `find` is: a default page a caller does not have to think about,
+ * and a hard ceiling it cannot ask past. Not manifest-configurable — a listing page size is a
+ * transport detail, not an application contract, and R2's own list ceiling is 1,000.
+ */
+export const STORAGE_LIST_DEFAULT_LIMIT = 100;
+export const STORAGE_LIST_MAX_LIMIT = 1_000;
+/** Longest object key. R2 accepts 1,024 UTF-8 bytes; half of that is ample and leaves headroom. */
+export const STORAGE_MAX_KEY_BYTES = 512;
+/**
+ * Object keys are a constrained, printable, path-like vocabulary rather than "any string R2 takes".
+ *
+ * The reasons are all about keys being *quoted* somewhere later — a URL path, a log line, a signed
+ * token, an operator's shell — and none of them are hypothetical:
+ *
+ * - control characters and whitespace would corrupt any of those quotings;
+ * - `..` and a leading `/` make a key look like a traversal to whatever reads it next, and a key
+ *   that reads as a traversal invites code that treats it as one;
+ * - `//` and a trailing `/` produce two keys that look like one directory to a human and are not.
+ *
+ * The result is that a key is safe to put in a path segment, a log field, and an audit row without
+ * any escaping decision being made per call site.
+ */
+const SEGMENT = String.raw `[A-Za-z0-9!._~()'*\- ]+`;
+const STORAGE_KEY = new RegExp(`^${SEGMENT}(?:/${SEGMENT})*$`, 'u');
+/**
+ * A list prefix is **not** a key, and conflating the two would break the most ordinary listing there is.
+ *
+ * R2's keyspace is flat, so `list({ prefix: 'users/' })` is how an application asks for what a human
+ * would call a folder — and a trailing slash is exactly what a key may not have. A prefix is also allowed
+ * to end mid-segment (`'users/4'` matches `users/42`), which is what makes it a prefix rather than a
+ * path. So the rules that carry over are the ones about *safety* — the charset, no dot segments, no
+ * leading slash, no empty interior segments — and the ones about a key being a complete path do not.
+ */
+const STORAGE_PREFIX = new RegExp(`^${SEGMENT}(?:/${SEGMENT})*/?$`, 'u');
+/** Segments that make a key or prefix *read* as a traversal, whatever handles it next. */
+function hasDotSegment(value) {
+    return value.split('/').some((segment) => segment === '.' || segment === '..');
+}
+/** Why a key is refused, or `null` when it is acceptable. One implementation, three consumers. */
+export function storageKeyRefusal(key) {
+    if (typeof key !== 'string' || key.length === 0)
+        return 'storage_key_empty';
+    if (new TextEncoder().encode(key).byteLength > STORAGE_MAX_KEY_BYTES)
+        return 'storage_key_too_long';
+    // Checked before the pattern so the dot-segment refusal is reported as such rather than as a
+    // generic charset failure: `.` and `..` are legal characters, they are only illegal as segments.
+    if (hasDotSegment(key))
+        return 'storage_key_invalid';
+    return STORAGE_KEY.test(key) ? null : 'storage_key_invalid';
+}
+/** The same question for a list prefix, which may end in a slash or mid-segment. */
+export function storagePrefixRefusal(prefix) {
+    if (typeof prefix !== 'string' || prefix.length === 0)
+        return 'storage_key_empty';
+    if (new TextEncoder().encode(prefix).byteLength > STORAGE_MAX_KEY_BYTES)
+        return 'storage_key_too_long';
+    if (hasDotSegment(prefix))
+        return 'storage_key_invalid';
+    return STORAGE_PREFIX.test(prefix) ? null : 'storage_key_invalid';
+}
+export function storageKeyValid(key) {
+    return storageKeyRefusal(key) === null;
+}
+/** The human wording for each refusal, shared so the runtime and the CLI say the same thing. */
+export function storageKeyMessage(refusal, key, kind = 'key') {
+    const quoted = typeof key === 'string' ? JSON.stringify(key.slice(0, 80)) : String(key);
+    switch (refusal) {
+        case 'storage_key_empty':
+            return `A storage ${kind} must be a non-empty string.`;
+        case 'storage_key_too_long':
+            return `A storage ${kind} may not exceed ${STORAGE_MAX_KEY_BYTES} bytes.`;
+        default:
+            return `A storage ${kind} must be slash-separated printable segments without dot segments: ${quoted}`;
+    }
+}