@impetik/xeer-mcp 0.2.16 → 0.2.18

package/vendor/spec/page-cursor.js

@@ -0,0 +1,45 @@
+/**
+ * The keyset page cursor shared by every paged read the platform serves.
+ *
+ * Every declared table is ordered by `(created_at, id)` and `id` is unique, so the pair is a total
+ * order and a cursor names an *exact position* in it rather than a count of rows to skip. That is
+ * the whole reason this is a cursor and not an `offset`: a row inserted or deleted between two
+ * pages shifts an offset and silently duplicates or skips a row, while a keyset position stays
+ * where it was pointing.
+ *
+ * Opaque by contract, and deliberately **not** signed. It encodes a position in data the caller
+ * already had to authenticate to reach and that the next page would have shown anyway, so a forged
+ * one discloses nothing — it merely starts the scan somewhere else in the caller's own rows. What
+ * it must do is *fail closed on garbage*, which is why decoding returns `null` rather than throwing
+ * or silently resetting to the first page: a caller that hands back a truncated or hand-written
+ * token gets a refusal it can act on, not page 1 wearing page 4's clothes.
+ */
+/** Mints the token that resumes a scan immediately after `(createdAt, id)`. */
+export function encodePageCursor(createdAt, id) {
+    const text = JSON.stringify([createdAt, id]);
+    return btoa(String.fromCharCode(...new TextEncoder().encode(text)))
+        .replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+/** The inverse, or `null` when the text is not a cursor this version wrote. */
+export function decodePageCursor(cursor) {
+    try {
+        const padded = cursor.replaceAll('-', '+').replaceAll('_', '/');
+        const bytes = Uint8Array.from(atob(padded + '='.repeat((4 - (padded.length % 4)) % 4)), (c) => c.charCodeAt(0));
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (!Array.isArray(parsed) || parsed.length !== 2)
+            return null;
+        const [createdAt, id] = parsed;
+        if (typeof createdAt !== 'string' || typeof id !== 'string')
+            return null;
+        // A position is only usable if its `created_at` compares the way the column does. Lexicographic
+        // order over ISO-8601 text *is* chronological order, but only for well-formed text: a token
+        // carrying `"whenever"` would otherwise seek to a position the index can never reach and return
+        // an empty page forever, which reads as "no more rows" rather than as the bad token it is.
+        if (Number.isNaN(Date.parse(createdAt)) || id.length === 0)
+            return null;
+        return { createdAt, id };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -43,11 +43,12 @@ 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
+ * Two, because two 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.
+ * one. A contract that can express a value nothing honours is worse than a narrow contract, so this
+ * bound moves only in lockstep with the retention fold in the control plane's deployment service.
  */
-export declare const MAX_RETAINED_ASSET_GENERATIONS = 1;
+export declare const MAX_RETAINED_ASSET_GENERATIONS = 2;
 /**
  * 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
@@ -95,9 +96,11 @@ export interface PublicAssetsV0 {
     /**
      * 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.
+     * The value is `0`, `1`, or `2` and nothing else — see {@link MAX_RETAINED_ASSET_GENERATIONS}.
+     * `1` means the deployment this artifact replaces keeps answering for its content-addressed paths;
+     * `2` extends that to the deployment before it, which is what an artifact carrying package-derived
+     * subresources asks for so a document cached across two deploys still resolves its assets; `0`
+     * means nothing is retained, and a client holding an 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

package/vendor/spec/public-assets.js

@@ -43,11 +43,12 @@ export 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
+ * Two, because two 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.
+ * one. A contract that can express a value nothing honours is worse than a narrow contract, so this
+ * bound moves only in lockstep with the retention fold in the control plane's deployment service.
  */
-export const MAX_RETAINED_ASSET_GENERATIONS = 1;
+export const MAX_RETAINED_ASSET_GENERATIONS = 2;
 const IMMUTABLE_PATH = /^\/_xa\/[0-9a-f]{64}\/[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/u;
 const ASSET_HASH = /^sha256:[0-9a-f]{64}$/u;
 /** The URL a blob of bytes is served at, and the only sanctioned way to mint one. */

package/vendor/spec/review.js

@@ -60,6 +60,8 @@ const schemaPlanStep = z.discriminatedUnion('kind', [
         fields: z.array(z.string().min(1)) }),
     z.strictObject({ kind: z.literal('index.change'), table: z.string().min(1), index: z.string().min(1),
         from: z.array(z.string().min(1)), to: z.array(z.string().min(1)) }),
+    z.strictObject({ kind: z.literal('table.idSource'), table: z.string().min(1),
+        from: z.enum(['runtime', 'application']), to: z.enum(['runtime', 'application']) }),
     z.strictObject({ kind: z.literal('unknown.change'), path: z.string().min(1) }),
 ]);
 const schemaPlan = z.strictObject({

package/vendor/spec/route.d.ts

@@ -10,6 +10,19 @@ export interface EndpointRoute {
 export declare function parseEndpointRoute(key: string): EndpointRoute | null;
 export declare function endpointRouteIdentity(route: Pick<EndpointRoute, 'method' | 'shape'>): string;
 export declare function endpointRouteMatches(route: Pick<EndpointRoute, 'method' | 'path'>, method: string, pathname: string): boolean;
+/**
+ * The path parameters a matched request carries, keyed by the names the route declared.
+ *
+ * This is the value half of what `Params<Key>` in the SDK describes at the type level, and it is
+ * derived from the same route the dispatcher matched with — not from a second pattern written by
+ * hand. A route with no dynamic segments yields an empty object rather than `null`, because an
+ * endpoint always has parameters; a static one simply has none.
+ *
+ * Segments are percent-decoded, and a segment that is not valid percent-encoding is handed over
+ * verbatim instead of throwing: a malformed URL is the caller's problem to answer with a status,
+ * not a reason for the runtime to turn the request into a 500.
+ */
+export declare function endpointRouteParams(route: Pick<EndpointRoute, 'path'>, pathname: string): Readonly<Record<string, string>>;
 export declare function normalizeEndpointRoutes(keys: Iterable<string>): EndpointRoute[];
 /**
  * The reserved runtime route that serves the live invalidation stream.

package/vendor/spec/route.js

@@ -30,6 +30,39 @@ export function endpointRouteMatches(route, method, pathname) {
     const actual = pathname.split('/');
     return expected.length === actual.length && expected.every((part, index) => part.startsWith(':') ? (actual[index]?.length ?? 0) > 0 : part === actual[index]);
 }
+/**
+ * The path parameters a matched request carries, keyed by the names the route declared.
+ *
+ * This is the value half of what `Params<Key>` in the SDK describes at the type level, and it is
+ * derived from the same route the dispatcher matched with — not from a second pattern written by
+ * hand. A route with no dynamic segments yields an empty object rather than `null`, because an
+ * endpoint always has parameters; a static one simply has none.
+ *
+ * Segments are percent-decoded, and a segment that is not valid percent-encoding is handed over
+ * verbatim instead of throwing: a malformed URL is the caller's problem to answer with a status,
+ * not a reason for the runtime to turn the request into a 500.
+ */
+export function endpointRouteParams(route, pathname) {
+    const expected = route.path.split('/');
+    const actual = pathname.split('/');
+    // No prototype: under the open-record fallback a caller-supplied name must never resolve to
+    // `Object.prototype.toString` where the types promise `string | undefined`.
+    const params = Object.create(null);
+    for (const [index, part] of expected.entries()) {
+        if (!part.startsWith(':'))
+            continue;
+        params[part.slice(1)] = decodeSegment(actual[index] ?? '');
+    }
+    return Object.freeze(params);
+}
+function decodeSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
 export function normalizeEndpointRoutes(keys) {
     const routes = [];
     const identities = new Map();

package/vendor/spec/schema-lifecycle.d.ts

@@ -18,10 +18,16 @@ export declare function schemaIdentityReference(): NormalizedDatabaseSchemaV0;
  * one to upgrade.
  *
  * Derived rather than declared, so it cannot be forgotten: adding, removing or renaming a key in
- * `normalizedSchemaPayload` moves this hash in the same commit that moves it, because every key is
- * emitted unconditionally and the reference declares one of each. What it cannot see is a change to how
- * a value is *derived* for a shape the reference does not declare — index normalization has its own
- * spellings, and only the ones written here are covered.
+ * `normalizedSchemaPayload` moves this hash in the same commit that moves it, because the reference
+ * declares a value for every key — and, for a key the projection omits when it is defaulted, one table
+ * holding the default beside one that does not. What it cannot see is a change to how a value is
+ * *derived* for a shape the reference does not declare — index normalization has its own spellings, and
+ * only the ones written here are covered.
+ *
+ * This value moving between releases is expected and costs nothing on its own: it is quoted in a
+ * refusal, never compared for equality. What a release must not do is move an *application's*
+ * `schemaHash` without that application changing, which is a different question and the reason
+ * `idSource` is omitted when defaulted.
  */
 export declare function schemaIdentityRevision(): `sha256:${string}`;
 export declare function planSchemaChange(application: string, fromSchema: NormalizedDatabaseSchemaV0, toSchema: NormalizedDatabaseSchemaV0): SchemaPlanV0;

package/vendor/spec/schema-lifecycle.js

@@ -44,6 +44,19 @@ function normalizedSchemaPayload(schema) {
                     unique: (table.unique ?? []).map((tuple) => [...tuple]),
                     checks: Object.fromEntries(Object.keys(table.checks ?? {}).sort()
                         .map((checkName) => [checkName, table.checks[checkName]])),
+                    // The one key here that is *omitted* when it holds its default, rather than materialized as
+                    // every key above is. Both conventions are right for what they cover, and which one applies
+                    // is decided by whether the key existed when the schemas being compared were written.
+                    //
+                    // A materialized default is what lets two spellings of the same declaration hash alike:
+                    // `optional: false` and an absent `optional` are one column, and writing `false` for both
+                    // says so. That works because every schema, of every age, has an answer for `optional`.
+                    // `idSource` does not: a schema written before decision 0006 has no opinion about it, and
+                    // materializing `"runtime"` for those would move the hash of every application that never
+                    // asked for the capability — which is the `storage?` rule in `artifact-v0.md` read from the
+                    // other side. Adding a capability must not change the identity of applications that do not
+                    // use it, so a table that does not use this one contributes exactly the bytes it did before.
+                    ...(table.idSource === undefined || table.idSource === 'runtime' ? {} : { idSource: table.idSource }),
                 }];
         })),
     };
@@ -70,6 +83,13 @@ export function applicationSchemaIdentity(schema) {
  * would each let a projection that read only the first of them hash this schema exactly as a correct
  * one does.
  *
+ * **Both values of a key the projection omits when it is defaulted.** `idSource` is the one key that is
+ * absent from the payload when it holds its default, so a single spelling of it would leave half the
+ * ways the projection can change invisible. `reference` declares `"application"`, which a build that
+ * stopped reading the key at all would drop; `beta` declares `"runtime"`, which contributes nothing
+ * today and would start contributing the moment a build stopped omitting the default. One of each is
+ * what makes both directions move this hash.
+ *
  * **Every order-preserving array declared in an order sorting would change.** Object keys are sorted by
  * canonical JSON and cannot carry order, but four arrays can and all four are semantic: an enum's
  * values, the outer and inner arrays of a composite UNIQUE, and an index's columns — `UNIQUE (a, b)`
@@ -107,12 +127,14 @@ const SCHEMA_IDENTITY_REFERENCE = {
             },
             unique: [['plain', 'number'], ['optional', 'maxLength']],
             checks: { positive: 'number > 0', bounded: 'maxLength IS NOT NULL' },
+            idSource: 'application',
         },
         beta: {
             fields: { second: { type: 'string' }, first: { type: 'number' } },
             indexes: { by_second: ['second'], by_first: ['first'] },
             unique: [['second', 'first']],
             checks: { nonzero: 'first <> 0', named: 'second <> \'\'' },
+            idSource: 'runtime',
         },
     },
 };
@@ -133,10 +155,16 @@ export function schemaIdentityReference() {
  * one to upgrade.
  *
  * Derived rather than declared, so it cannot be forgotten: adding, removing or renaming a key in
- * `normalizedSchemaPayload` moves this hash in the same commit that moves it, because every key is
- * emitted unconditionally and the reference declares one of each. What it cannot see is a change to how
- * a value is *derived* for a shape the reference does not declare — index normalization has its own
- * spellings, and only the ones written here are covered.
+ * `normalizedSchemaPayload` moves this hash in the same commit that moves it, because the reference
+ * declares a value for every key — and, for a key the projection omits when it is defaulted, one table
+ * holding the default beside one that does not. What it cannot see is a change to how a value is
+ * *derived* for a shape the reference does not declare — index normalization has its own spellings, and
+ * only the ones written here are covered.
+ *
+ * This value moving between releases is expected and costs nothing on its own: it is quoted in a
+ * refusal, never compared for equality. What a release must not do is move an *application's*
+ * `schemaHash` without that application changing, which is a different question and the reason
+ * `idSource` is omitted when defaulted.
  */
 export function schemaIdentityRevision() {
     return applicationSchemaHash(SCHEMA_IDENTITY_REFERENCE);

package/vendor/spec/schema-plan.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationSchemaIdentityV0, NormalizedApplicationManifestV0, ScalarType } from './types.js';
+import type { ApplicationSchemaIdentityV0, NormalizedApplicationManifestV0, ScalarType, TableDefinition } from './types.js';
 export declare const SCHEMA_PROTOCOL: "xeer.schema.v0";
 export type NormalizedDatabaseSchemaV0 = NormalizedApplicationManifestV0['database'];
 /**
@@ -8,6 +8,10 @@ export type NormalizedDatabaseSchemaV0 = NormalizedApplicationManifestV0['databa
  */
 export declare const FIELD_ATTRIBUTES: readonly ["collate", "default", "enum", "generated", "onDelete", "onUpdate", "table", "unique"];
 export type FieldAttribute = (typeof FIELD_ATTRIBUTES)[number];
+/** Table keys with a step of their own, beside `fields`, `indexes`, `unique` and `checks`. */
+export type IdSource = NonNullable<TableDefinition['idSource']>;
+/** The default a table that says nothing about its ids gets, in the one place the plan reads it. */
+export declare function tableIdSource(table: TableDefinition): IdSource;
 export type SchemaPlanStepV0 = {
     kind: 'table.add';
     table: string;
@@ -20,6 +24,11 @@ export type SchemaPlanStepV0 = {
     constraint: 'unique' | 'checks';
     from: unknown;
     to: unknown;
+} | {
+    kind: 'table.idSource';
+    table: string;
+    from: IdSource;
+    to: IdSource;
 } | {
     kind: 'field.add';
     table: string;

package/vendor/spec/schema-plan.js

@@ -8,6 +8,10 @@ export const SCHEMA_PROTOCOL = 'xeer.schema.v0';
 export const FIELD_ATTRIBUTES = Object.freeze([
     'collate', 'default', 'enum', 'generated', 'onDelete', 'onUpdate', 'table', 'unique',
 ]);
+/** The default a table that says nothing about its ids gets, in the one place the plan reads it. */
+export function tableIdSource(table) {
+    return table.idSource ?? 'runtime';
+}
 export class SchemaPlanningError extends Error {
     code;
     constructor(code, message) {
@@ -61,6 +65,13 @@ function tableSteps(tableName, from, to) {
         steps.push({ kind: 'table.constraint', table: tableName, constraint,
             from: from[constraint] ?? null, to: to[constraint] ?? null });
     }
+    // Read through the default, so declaring `"runtime"` on a table that had said nothing is the same
+    // table rather than a change — the same reading the hash takes when it omits the defaulted value.
+    const beforeIdSource = tableIdSource(from);
+    const afterIdSource = tableIdSource(to);
+    if (beforeIdSource !== afterIdSource) {
+        steps.push({ kind: 'table.idSource', table: tableName, from: beforeIdSource, to: afterIdSource });
+    }
     // Indexes are compared through their normalized form, so `["slug"]` and `{ columns: ["slug"] }`
     // are one index written two ways rather than a change from one to the other.
     const terms = (index) => normalizedIndex(index).columns.map(indexTermLabel);
@@ -92,12 +103,20 @@ function tableSteps(tableName, from, to) {
 }
 /**
  * Whether a step leaves the rows already stored valid. Nothing in the extended vocabulary does,
- * with one exception: a DEFAULT decides what a later insert that omits the column receives and says
- * nothing about the rows already there, so changing one cannot invalidate them.
+ * with two exceptions, and both are exceptions for the same reason: they govern what a *later* write
+ * is allowed to say and make no claim about what is already stored.
+ *
+ * A DEFAULT decides what an insert that omits the column receives, and says nothing about the rows
+ * already there. `idSource` decides who supplies the next row's id: turning it on leaves every stored
+ * uuid a valid primary key, and turning it off leaves every stored application id one too. Neither
+ * direction touches a column, an index, or a byte on disk — `id` is `TEXT PRIMARY KEY` under both —
+ * so a reset here would rewrite a table to produce the table it started with.
  */
 function isCompatible(step) {
     if (step.kind === 'table.add' || step.kind === 'index.add')
         return true;
+    if (step.kind === 'table.idSource')
+        return true;
     if (step.kind === 'field.add')
         return step.optional;
     if (step.kind === 'field.optional')
@@ -149,7 +168,7 @@ function unknownSchemaSteps(fromSchema, toSchema) {
     for (const tableName of tableNames) {
         const beforeTable = fromSchema.tables[tableName];
         const afterTable = toSchema.tables[tableName];
-        steps.push(...unknownKeySteps(`database.tables.${tableName}`, beforeTable, afterTable, ['fields', 'indexes', 'unique', 'checks']));
+        steps.push(...unknownKeySteps(`database.tables.${tableName}`, beforeTable, afterTable, ['fields', 'indexes', 'unique', 'checks', 'idSource']));
         const beforeFields = beforeTable?.fields ?? {};
         const afterFields = afterTable?.fields ?? {};
         const fieldNames = [...new Set([...Object.keys(beforeFields), ...Object.keys(afterFields)])].sort();

package/vendor/spec/schema.d.ts

@@ -62,6 +62,10 @@ export declare const normalizedDatabaseSchema: z.ZodObject<{
         }, z.core.$strict>]>>>;
         unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
         checks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        idSource: z.ZodOptional<z.ZodEnum<{
+            runtime: "runtime";
+            application: "application";
+        }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const applicationManifestSchema: z.ZodObject<{
@@ -140,6 +144,10 @@ export declare const applicationManifestSchema: z.ZodObject<{
             }, z.core.$strict>]>>>;
             unique: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
             checks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            idSource: z.ZodOptional<z.ZodEnum<{
+                runtime: "runtime";
+                application: "application";
+            }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
     storage: z.ZodOptional<z.ZodObject<{
@@ -151,12 +159,20 @@ export declare const applicationManifestSchema: z.ZodObject<{
         database: "database";
         storage: "storage";
     }>>>;
+    client: z.ZodOptional<z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodLiteral<"preact">;
+            source: z.ZodOptional<z.ZodLiteral<"platform">>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     budgets: z.ZodOptional<z.ZodObject<{
         queryRows: z.ZodOptional<z.ZodNumber>;
         mutationWrites: z.ZodOptional<z.ZodNumber>;
         requestBytes: z.ZodOptional<z.ZodNumber>;
         responseBytes: z.ZodOptional<z.ZodNumber>;
+        clientBundleBytes: z.ZodOptional<z.ZodNumber>;
         liveConnections: z.ZodOptional<z.ZodNumber>;
+        streamedBytes: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Stable editor-facing schema location emitted into every scaffolded `xeer.app.json`. */

package/vendor/spec/schema.js

@@ -138,6 +138,9 @@ const tableSchema = z.strictObject({
     indexes: z.record(identifier, indexSchema).optional(),
     unique: z.array(z.array(identifier).min(1)).optional(),
     checks: z.record(identifier, expression).optional(),
+    // Who supplies a row's id. Absent means `"runtime"`, and absent is how it stays written: the
+    // normalized schema omits the default, so declaring it explicitly is accepted but changes nothing.
+    idSource: z.enum(['runtime', 'application']).optional(),
 }).superRefine((table, ctx) => {
     for (const [indexName, definition] of Object.entries(table.indexes ?? {})) {
         const seen = new Set();
@@ -271,15 +274,34 @@ export const applicationManifestSchema = z.strictObject({
         writeBytes: z.number().int().positive().max(STORAGE_MAX_WRITE_BYTES).optional(),
     }).optional(),
     capabilities: z.array(z.enum(CAPABILITIES)).optional(),
+    /**
+     * The client runtime selection (#212). Closed: only implemented provider/source combinations are
+     * accepted, and omitting any level of it normalizes to the platform-managed Preact runtime with
+     * identical semantics and build output.
+     */
+    client: z.strictObject({
+        runtime: z.strictObject({
+            provider: z.literal('preact'),
+            source: z.literal('platform').optional(),
+        }).optional(),
+    }).optional(),
     budgets: z.strictObject({
         queryRows: z.number().int().positive().max(10_000).optional(),
         mutationWrites: z.number().int().positive().max(1_000).optional(),
         requestBytes: z.number().int().positive().max(4 * 1024 * 1024).optional(),
         responseBytes: z.number().int().positive().max(4 * 1024 * 1024).optional(),
+        // The error tier for the minified pre-gzip client bundle, defaulting to the platform's 1 MiB.
+        // Bounded by the same 10 MiB ceiling every compiled module already has, so raising it can never
+        // promise bytes the artifact format refuses.
+        clientBundleBytes: z.number().int().positive().max(10 * 1024 * 1024).optional(),
         // Zero is a declaration, not an omission: it says the application wants no server push at all,
         // and the runtime answers `live_disabled` for it rather than a retryable budget refusal. The
         // bound is `min(0)` and not `positive()` so the editor schema publishes `minimum: 0`.
         liveConnections: z.number().int().min(0).max(1_000).optional(),
+        // Deliberately above `responseBytes`' 4 MiB ceiling: a streamed body that had to fit inside the
+        // buffered one would give an author no reason to stream. It is still declared and still bounded —
+        // an unbudgeted server→client channel is not something this platform ships (decision 0007).
+        streamedBytes: z.number().int().positive().max(64 * 1024 * 1024).optional(),
     }).optional(),
 }).superRefine((manifest, ctx) => {
     // Caught here, at `xeer check` time, rather than as a failure when the schema is applied.
@@ -336,6 +358,7 @@ export const applicationManifestJsonSchema = Object.freeze({
         app: describeProperty('app', 'Browser metadata and SPA behavior.'),
         database: describeProperty('database', 'Typed application database schema. Requires the database capability.'),
         storage: describeProperty('storage', 'Private object-storage limits. Requires the storage capability.'),
+        client: describeProperty('client', 'Client runtime selection. Optional; omission means the platform-managed Preact runtime.'),
         capabilities: {
             ...describeProperty('capabilities', 'Powers granted to the application. Duplicate names are invalid.'),
             uniqueItems: true,
@@ -395,6 +418,9 @@ export function normalizeApplicationManifest(manifest) {
             }
             : null,
         capabilities: [...(manifest.capabilities ?? [])].sort(),
+        // Always normalized: omission and the explicit default are the same statement, and everything
+        // downstream (compiler facts, artifact provenance) reads one canonical value.
+        client: { runtime: { provider: 'preact', source: 'platform' } },
         budgets: {
             queryRows: manifest.budgets?.queryRows ?? 1_000,
             mutationWrites: manifest.budgets?.mutationWrites ?? 100,
@@ -404,6 +430,24 @@ export function normalizeApplicationManifest(manifest) {
             // application's Durable Object continuously, so a positive default charged every application
             // for a feature most never used. Declare a positive value to turn it on.
             liveConnections: manifest.budgets?.liveConnections ?? 0,
+            // Present only when declared, mirroring `clientBundleBytes` below. The normalized budgets go
+            // into the artifact payload verbatim, so materializing the platform default here would move
+            // the `artifactId` of every application that never asked for a streamed response — the exact
+            // identity invariant `storage` and `clientBundleBytes` exist to hold. The runtime applies
+            // {@link STREAMED_BYTES_DEFAULT} where it reads the budget instead.
+            //
+            // A positive default is safe here in a way `liveConnections` is not: this ceiling only ever
+            // applies to a stream `liveConnections` already admitted, so the default cannot open a channel
+            // on its own. It matches `responseBytes` so that turning an endpoint from buffered to streamed
+            // does not silently change how many bytes it may send.
+            ...(manifest.budgets?.streamedBytes !== undefined
+                ? { streamedBytes: manifest.budgets.streamedBytes }
+                : {}),
+            // Present only when declared, mirroring `storage`: the platform default is applied at build
+            // time, so an application that never declares the budget hashes exactly as before (#212).
+            ...(manifest.budgets?.clientBundleBytes !== undefined
+                ? { clientBundleBytes: manifest.budgets.clientBundleBytes }
+                : {}),
         },
     };
 }

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

@@ -100,6 +100,28 @@ export declare class StateTransferError extends Error {
     /** JSON shape shared by the runtime response, the control-plane envelope, and CLI diagnostics. */
     toDiagnostic(): StateTransferDiagnostic;
 }
+/** The longest a row id may be, in UTF-16 code units. */
+export declare const RECORD_ID_MAX_LENGTH = 256;
+export type RecordIdRefusal = 'record_id_empty' | 'record_id_too_long' | 'record_id_invalid';
+/**
+ * Why a row id is refused, or `null` when it is acceptable.
+ *
+ * Until `idSource: "application"` this rule had one caller and lived inside it, because the only ids
+ * an application could produce came from `crypto.randomUUID()` and the only ones a human could were
+ * the admin editor's. Both of those are now joined by ids an application chooses on `insert`, so the
+ * rule is stated once here and read by all three — the alternative being three spellings of "a row
+ * id" that agree until one of them is edited.
+ *
+ * Bounded and quotable, and no more. The bound is what stops an id becoming an unbounded key in
+ * every index and error message that carries one; control characters are refused because an id is
+ * quoted back in diagnostics, admin listings and URLs, and a newline or a NUL inside one turns a
+ * message into two. Nothing narrower would be honest: these ids come from identity providers and
+ * other outside systems, and refusing a charset that a provider legitimately issues would make the
+ * capability unusable for exactly the case it exists for.
+ */
+export declare function recordIdRefusal(id: unknown): RecordIdRefusal | null;
+/** The human wording for each refusal, shared so the runtime and the editor say the same thing. */
+export declare function recordIdMessage(refusal: RecordIdRefusal, id: unknown): string;
 /**
  * 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.

package/vendor/spec/state-export.js

@@ -110,6 +110,42 @@ function validEncodedValue(value, path) {
     }
     throw malformed(`Unknown encoded value tag at ${path}.`, { tag: typeof tag === 'string' ? tag : null });
 }
+/** The longest a row id may be, in UTF-16 code units. */
+export const RECORD_ID_MAX_LENGTH = 256;
+/**
+ * Why a row id is refused, or `null` when it is acceptable.
+ *
+ * Until `idSource: "application"` this rule had one caller and lived inside it, because the only ids
+ * an application could produce came from `crypto.randomUUID()` and the only ones a human could were
+ * the admin editor's. Both of those are now joined by ids an application chooses on `insert`, so the
+ * rule is stated once here and read by all three — the alternative being three spellings of "a row
+ * id" that agree until one of them is edited.
+ *
+ * Bounded and quotable, and no more. The bound is what stops an id becoming an unbounded key in
+ * every index and error message that carries one; control characters are refused because an id is
+ * quoted back in diagnostics, admin listings and URLs, and a newline or a NUL inside one turns a
+ * message into two. Nothing narrower would be honest: these ids come from identity providers and
+ * other outside systems, and refusing a charset that a provider legitimately issues would make the
+ * capability unusable for exactly the case it exists for.
+ */
+export function recordIdRefusal(id) {
+    if (typeof id !== 'string' || id.length === 0)
+        return 'record_id_empty';
+    if (id.length > RECORD_ID_MAX_LENGTH)
+        return 'record_id_too_long';
+    return /[\u0000-\u001f\u007f-\u009f]/u.test(id) ? 'record_id_invalid' : null;
+}
+/** The human wording for each refusal, shared so the runtime and the editor say the same thing. */
+export function recordIdMessage(refusal, id) {
+    switch (refusal) {
+        case 'record_id_empty':
+            return 'A row id must be a non-empty string.';
+        case 'record_id_too_long':
+            return `A row id may not exceed ${RECORD_ID_MAX_LENGTH} characters; received ${id.length}.`;
+        default:
+            return `A row id may not contain control characters: ${JSON.stringify(id.slice(0, 80))}`;
+    }
+}
 /**
  * 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.
@@ -156,8 +192,12 @@ 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.`);
+    // The same rule an application `insert` and the admin editor are held to. An imported row is a row
+    // like any other, and a document carrying an id no live write could have produced would restore an
+    // application into a state it had no way to reach on its own.
+    const idRefusal = recordIdRefusal(row.id);
+    if (idRefusal) {
+        throw malformed(`Row ${index} of table ${table} has no usable id. ${recordIdMessage(idRefusal, row.id)}`);
     }
     if (!isoTimestamp(row.createdAt) || !isoTimestamp(row.updatedAt)) {
         throw malformed(`Row ${row.id} of table ${table} has non-ISO timestamps.`);

package/vendor/spec/type-check-profile.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The platform TypeScript profile, in the spelling a `tsconfig.json` uses.
+ *
+ * `xeer check` type-checks an application with its own compiler options rather than the project's
+ * `tsconfig.json`, because the answer must not depend on a file the author can edit. The editor,
+ * however, reads only the `tsconfig.json` — so anything the platform enforces and the scaffold omits
+ * shows up as a green editor and a red CLI, which is what `exactOptionalPropertyTypes` did (#248).
+ *
+ * The repair is not to copy the flags into the scaffold: a copy is a thing that drifts. This module
+ * is the one declaration. The compiler converts it into `ts.CompilerOptions` for the check, and the
+ * scaffold writes it into `tsconfig.json` verbatim, so the two cannot disagree without this file
+ * changing. It lives in the spec package rather than the compiler so that writing a scaffold does
+ * not require loading TypeScript.
+ *
+ * Values are the JSON spellings TypeScript accepts in a `tsconfig.json` (`"esnext"`, `"bundler"`,
+ * `"react-jsx"`, `lib` without the `lib.`/`.d.ts` affixes), which is what
+ * `ts.convertCompilerOptionsFromJson` reads.
+ */
+export declare const PLATFORM_TYPE_CHECK_COMPILER_OPTIONS: Readonly<{
+    readonly allowJs: true;
+    readonly allowArbitraryExtensions: true;
+    readonly checkJs: true;
+    readonly exactOptionalPropertyTypes: true;
+    readonly jsx: "react-jsx";
+    readonly jsxImportSource: "@impetik/xeer";
+    readonly lib: readonly string[];
+    readonly module: "esnext";
+    readonly moduleResolution: "bundler";
+    readonly noEmit: true;
+    readonly noUncheckedIndexedAccess: true;
+    readonly skipLibCheck: true;
+    readonly strict: true;
+    readonly target: "es2022";
+    readonly types: readonly never[];
+    readonly verbatimModuleSyntax: true;
+}>;
+/**
+ * The React-family editor mappings every scaffolded and template `tsconfig.json` carries. Each
+ * target is a shim inside the installed platform package that re-exports the platform's
+ * `preact/compat` surface, so the mapping resolves under npm hoisting and pnpm strictness alike.
+ *
+ * Not part of {@link PLATFORM_TYPE_CHECK_COMPILER_OPTIONS}: the platform check answers the same
+ * question through its module-resolution host instead, so this is the editor's half of one rule
+ * rather than a second rule.
+ */
+export declare const REACT_COMPAT_TSCONFIG_PATHS: Readonly<Record<string, readonly string[]>>;
+/**
+ * The files an application's `tsconfig.json` type-checks: sources, TypeScript tests, and the
+ * generated contract.
+ *
+ * `tests/**\/*.ts` rather than `tests`, because the profile enables `checkJs` and the two sides build
+ * their file sets differently. The platform checks the entrypoint graph plus `tests/**\/*.test.ts`,
+ * so a `.js` file it reaches is a file it judges; a tsconfig's set is a directory glob, and `tests`
+ * would additionally drag in a `.mjs` harness written for Node — a file neither side is judging the
+ * same way. Restricting the glob to TypeScript keeps the two sets comparable without weakening any
+ * rule that decides how a checked file is judged.
+ */
+export declare const APPLICATION_TSCONFIG_INCLUDE: readonly string[];
+/**
+ * The `tsconfig.json` document an application carries, as a serialized file body.
+ *
+ * One function so the scaffold, the checked-in templates, and any conformance test all name the same
+ * bytes. Serialized here rather than returned as an object because "the file the editor reads" is
+ * what has to match, and two callers stringifying the same object with different options would
+ * produce two different files.
+ */
+export declare function applicationTsconfigDocument(): string;