@impetik/xeer-mcp 0.2.17 → 0.2.19

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

@@ -2,9 +2,10 @@
  * 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.
+ * a signed assertion. It carries the same facts a production assertion carries — who the caller is,
+ * which workspaces they belong to, and which roles and permissions they hold — so `workspaceTable()`
+ * policies and `memberOf()`, `hasRole()`, and `hasPermission()` guards are all 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
@@ -18,14 +19,30 @@
  */
 export declare const LOCAL_PERSONA_COOKIE = "xeer_local_persona";
 export declare const LOCAL_WORKSPACE_COOKIE = "xeer_local_workspaces";
+/**
+ * The two claim cookies are siblings of {@link LOCAL_WORKSPACE_COOKIE}, carrying the other two facts
+ * a production assertion carries. Three cookies rather than one encoded blob, for the reason the
+ * membership cookie is already one: each is a comma-separated list a human can read in devtools and
+ * set by hand, and each fails closed on its own without taking the others down with it.
+ */
+export declare const LOCAL_ROLE_COOKIE = "xeer_local_roles";
+export declare const LOCAL_PERMISSION_COOKIE = "xeer_local_permissions";
 /** Deterministic local identities. Each persona is a distinct application user. */
-export type LocalPersonaName = 'alice' | 'bob' | 'guest';
+export type LocalPersonaName = 'alice' | 'bob' | 'carol' | '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.
+ * visitor a test uses to prove that none of alice's, bob's, or carol's rows leak, not a session to
+ * log into.
  */
 export declare const LOCAL_SIGN_IN_PERSONA_NAMES: readonly LocalPersonaName[];
+/** The provisioned personas: every local identity except the unclaimed visitor. */
+export declare const LOCAL_MEMBER_PERSONA_NAMES: readonly LocalPersonaName[];
+/**
+ * `alice, bob, carol, or guest` — the one place the persona list is spelled for a human, so adding
+ * a persona cannot leave a diagnostic naming a set that no longer exists.
+ */
+export declare function localPersonaNameList(names?: readonly LocalPersonaName[]): string;
 /** The identity-assertion charset for a workspace id, so local ids stay production-shaped. */
 export declare const LOCAL_WORKSPACE_ID_PATTERN: RegExp;
 /**
@@ -33,27 +50,74 @@ export declare const LOCAL_WORKSPACE_ID_PATTERN: RegExp;
  * every browser's per-cookie budget while staying far above what a local isolation test needs.
  */
 export declare const MAXIMUM_LOCAL_WORKSPACES = 16;
+/**
+ * The identity-assertion charset for a role or a permission. Deliberately wider than a workspace id
+ * and identical to what `validateTrustedIdentityAssertion` accepts, because applications already
+ * spell permissions `notes:write` and roles `org/admin`. `,` is excluded by the charset, which is
+ * what keeps a comma-separated cookie unambiguous.
+ */
+export declare const LOCAL_CLAIM_PATTERN: RegExp;
+/** Claims are a development fixture too, and the same cap keeps each cookie small. */
+export declare const MAXIMUM_LOCAL_CLAIMS = 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);
 }
+/** An unusable local role or permission. Always a builder input error, never a denial. */
+export declare class LocalPersonaClaimError extends Error {
+    readonly code: "invalid_local_claim";
+    constructor(message: string);
+}
+/** Which claim list is being spoken about, so one implementation can name itself in errors. */
+export type LocalClaimKind = 'role' | 'permission';
 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[];
+/**
+ * Validates and de-duplicates a declared role or permission set, preserving declaration order for
+ * the same reason membership does: what a builder wrote is what a diagnostic reads back.
+ */
+export declare function normalizeLocalClaims(kind: LocalClaimKind, values: readonly unknown[]): readonly string[];
+/** Everything a local persona can be granted beyond its name. */
+export interface LocalPersonaClaims {
+    readonly roles?: readonly unknown[];
+    readonly permissions?: readonly unknown[];
+}
+/** The resolved grant: three lists, each already validated and in declaration order. */
+export interface ResolvedLocalPersonaClaims {
+    readonly roles: readonly string[];
+    readonly permissions: 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';
+/**
+ * The same pairing rule, applied to roles and permissions. Production issues a role to a
+ * provisioned identity and to nothing else, so a `guest` holding one would be a local-only fiction
+ * that no deployment could reproduce — and the guard it made pass would still refuse in production.
+ */
+export declare function normalizeLocalPersonaClaims(persona: LocalPersonaName, claims?: LocalPersonaClaims): ResolvedLocalPersonaClaims;
+/**
+ * True when a persona holding this grant is a provisioned user rather than a guest.
+ *
+ * Any claim promotes, not membership alone: production assigns a workspace, a role, and a
+ * permission by the same act of provisioning an identity, so a persona that holds a role but no
+ * workspace is still someone the platform knows. Without that, `[authenticated(), hasRole('admin')]`
+ * would be untestable locally without inventing a workspace the application never declared.
+ * A persona granted nothing is unchanged: `as('alice')` is still a guest.
+ */
+export declare function localPersonaKind(workspaceIds: readonly string[], roles?: readonly string[], permissions?: 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[];
+/** Parses one comma-separated claim list, as written in a cookie or a query parameter. */
+export declare function parseLocalClaimList(kind: LocalClaimKind, 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;
 /**
@@ -61,9 +125,20 @@ export declare function readLocalPersonaCookie(cookie: string | null | undefined
  * identity fails closed, exactly as an assertion with an empty `workspaceIds` does.
  */
 export declare function readLocalWorkspaceCookie(cookie: string | null | undefined): readonly string[];
+/**
+ * The roles a session was granted. An absent, empty, or malformed cookie is no roles: a claim
+ * cookie fails closed exactly as the membership cookie does, so tampering can only ever narrow.
+ */
+export declare function readLocalRoleCookie(cookie: string | null | undefined): readonly string[];
+/** The permissions a session was granted, read with the same fail-closed rule as roles. */
+export declare function readLocalPermissionCookie(cookie: string | null | undefined): readonly string[];
 export declare function localWorkspaceCookieValue(workspaceIds: readonly string[]): string;
+export declare function localClaimCookieValue(kind: LocalClaimKind, values: 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.
+ *
+ * `claims` is a third argument rather than three positional lists so that adding a fourth fact to
+ * the local identity later does not move an existing caller's arguments.
  */
-export declare function localIdentityCookieHeader(persona: LocalPersonaName, workspaceIds?: readonly string[]): string;
+export declare function localIdentityCookieHeader(persona: LocalPersonaName, workspaceIds?: readonly string[], claims?: LocalPersonaClaims): string;

package/vendor/spec/local-identity.js

@@ -2,9 +2,10 @@
  * 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.
+ * a signed assertion. It carries the same facts a production assertion carries — who the caller is,
+ * which workspaces they belong to, and which roles and permissions they hold — so `workspaceTable()`
+ * policies and `memberOf()`, `hasRole()`, and `hasPermission()` guards are all 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
@@ -18,12 +19,34 @@
  */
 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']);
+/**
+ * The two claim cookies are siblings of {@link LOCAL_WORKSPACE_COOKIE}, carrying the other two facts
+ * a production assertion carries. Three cookies rather than one encoded blob, for the reason the
+ * membership cookie is already one: each is a comma-separated list a human can read in devtools and
+ * set by hand, and each fails closed on its own without taking the others down with it.
+ */
+export const LOCAL_ROLE_COOKIE = 'xeer_local_roles';
+export const LOCAL_PERMISSION_COOKIE = 'xeer_local_permissions';
+export const LOCAL_PERSONA_NAMES = Object.freeze(['alice', 'bob', 'carol', '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.
+ * visitor a test uses to prove that none of alice's, bob's, or carol's rows leak, not a session to
+ * log into.
+ */
+export const LOCAL_SIGN_IN_PERSONA_NAMES = Object.freeze(['alice', 'bob', 'carol']);
+/** The provisioned personas: every local identity except the unclaimed visitor. */
+export const LOCAL_MEMBER_PERSONA_NAMES = Object.freeze(['alice', 'bob', 'carol']);
+/**
+ * `alice, bob, carol, or guest` — the one place the persona list is spelled for a human, so adding
+ * a persona cannot leave a diagnostic naming a set that no longer exists.
  */
-export const LOCAL_SIGN_IN_PERSONA_NAMES = Object.freeze(['alice', 'bob']);
+export function localPersonaNameList(names = LOCAL_PERSONA_NAMES) {
+    if (names.length < 2)
+        return names.join('');
+    const last = names[names.length - 1];
+    const rest = names.slice(0, -1);
+    return names.length === 2 ? `${rest[0]} or ${last}` : `${rest.join(', ')}, or ${last}`;
+}
 /** 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;
 /**
@@ -31,6 +54,15 @@ export const LOCAL_WORKSPACE_ID_PATTERN = /^[A-Za-z0-9:_-]{1,96}$/u;
  * every browser's per-cookie budget while staying far above what a local isolation test needs.
  */
 export const MAXIMUM_LOCAL_WORKSPACES = 16;
+/**
+ * The identity-assertion charset for a role or a permission. Deliberately wider than a workspace id
+ * and identical to what `validateTrustedIdentityAssertion` accepts, because applications already
+ * spell permissions `notes:write` and roles `org/admin`. `,` is excluded by the charset, which is
+ * what keeps a comma-separated cookie unambiguous.
+ */
+export const LOCAL_CLAIM_PATTERN = /^[A-Za-z0-9._:@/-]{1,128}$/u;
+/** Claims are a development fixture too, and the same cap keeps each cookie small. */
+export const MAXIMUM_LOCAL_CLAIMS = 16;
 /** An unusable local membership specification. Always a builder input error, never a denial. */
 export class LocalWorkspaceMembershipError extends Error {
     code = 'invalid_local_workspace';
@@ -39,6 +71,17 @@ export class LocalWorkspaceMembershipError extends Error {
         this.name = 'LocalWorkspaceMembershipError';
     }
 }
+/** An unusable local role or permission. Always a builder input error, never a denial. */
+export class LocalPersonaClaimError extends Error {
+    code = 'invalid_local_claim';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalPersonaClaimError';
+    }
+}
+function claimPlural(kind) {
+    return kind === 'role' ? 'roles' : 'permissions';
+}
 export function isLocalPersonaName(value) {
     return typeof value === 'string' && LOCAL_PERSONA_NAMES.includes(value);
 }
@@ -60,6 +103,24 @@ export function normalizeLocalWorkspaceIds(values) {
     }
     return Object.freeze(normalized);
 }
+/**
+ * Validates and de-duplicates a declared role or permission set, preserving declaration order for
+ * the same reason membership does: what a builder wrote is what a diagnostic reads back.
+ */
+export function normalizeLocalClaims(kind, values) {
+    const normalized = [];
+    for (const value of values) {
+        if (typeof value !== 'string' || !LOCAL_CLAIM_PATTERN.test(value)) {
+            throw new LocalPersonaClaimError(`Invalid ${kind} ${JSON.stringify(String(value))}: use 1-128 characters from A-Z, a-z, 0-9, '.', '_', ':', '@', '/', and '-'.`);
+        }
+        if (!normalized.includes(value))
+            normalized.push(value);
+    }
+    if (normalized.length > MAXIMUM_LOCAL_CLAIMS) {
+        throw new LocalPersonaClaimError(`A local persona may hold at most ${MAXIMUM_LOCAL_CLAIMS} ${claimPlural(kind)}; ${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
@@ -69,13 +130,35 @@ 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.');
+            + `membership is only ever held by a provisioned identity. Use ${localPersonaNameList(LOCAL_MEMBER_PERSONA_NAMES)}.`);
     }
     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';
+/**
+ * The same pairing rule, applied to roles and permissions. Production issues a role to a
+ * provisioned identity and to nothing else, so a `guest` holding one would be a local-only fiction
+ * that no deployment could reproduce — and the guard it made pass would still refuse in production.
+ */
+export function normalizeLocalPersonaClaims(persona, claims = {}) {
+    const roles = normalizeLocalClaims('role', claims.roles ?? []);
+    const permissions = normalizeLocalClaims('permission', claims.permissions ?? []);
+    if (persona === 'guest' && (roles.length > 0 || permissions.length > 0)) {
+        throw new LocalPersonaClaimError('The guest persona cannot carry roles or permissions: it is the unclaimed visitor, and a '
+            + `claim is only ever held by a provisioned identity. Use ${localPersonaNameList(LOCAL_MEMBER_PERSONA_NAMES)}.`);
+    }
+    return Object.freeze({ roles, permissions });
+}
+/**
+ * True when a persona holding this grant is a provisioned user rather than a guest.
+ *
+ * Any claim promotes, not membership alone: production assigns a workspace, a role, and a
+ * permission by the same act of provisioning an identity, so a persona that holds a role but no
+ * workspace is still someone the platform knows. Without that, `[authenticated(), hasRole('admin')]`
+ * would be untestable locally without inventing a workspace the application never declared.
+ * A persona granted nothing is unchanged: `as('alice')` is still a guest.
+ */
+export function localPersonaKind(workspaceIds, roles = [], permissions = []) {
+    return workspaceIds.length > 0 || roles.length > 0 || permissions.length > 0 ? 'user' : 'guest';
 }
 /** Parses one comma-separated membership list, as written in a cookie or a query parameter. */
 export function parseLocalWorkspaceList(value) {
@@ -86,6 +169,15 @@ export function parseLocalWorkspaceList(value) {
         return Object.freeze([]);
     return normalizeLocalWorkspaceIds(trimmed.split(',').map((entry) => entry.trim()));
 }
+/** Parses one comma-separated claim list, as written in a cookie or a query parameter. */
+export function parseLocalClaimList(kind, value) {
+    if (value === null || value === undefined)
+        return Object.freeze([]);
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return Object.freeze([]);
+    return normalizeLocalClaims(kind, trimmed.split(',').map((entry) => entry.trim()));
+}
 function cookieValue(cookie, name) {
     if (!cookie)
         return null;
@@ -116,17 +208,49 @@ export function readLocalWorkspaceCookie(cookie) {
         return Object.freeze([]);
     }
 }
+/**
+ * The roles a session was granted. An absent, empty, or malformed cookie is no roles: a claim
+ * cookie fails closed exactly as the membership cookie does, so tampering can only ever narrow.
+ */
+export function readLocalRoleCookie(cookie) {
+    try {
+        return parseLocalClaimList('role', cookieValue(cookie, LOCAL_ROLE_COOKIE));
+    }
+    catch {
+        return Object.freeze([]);
+    }
+}
+/** The permissions a session was granted, read with the same fail-closed rule as roles. */
+export function readLocalPermissionCookie(cookie) {
+    try {
+        return parseLocalClaimList('permission', cookieValue(cookie, LOCAL_PERMISSION_COOKIE));
+    }
+    catch {
+        return Object.freeze([]);
+    }
+}
 export function localWorkspaceCookieValue(workspaceIds) {
     return normalizeLocalWorkspaceIds(workspaceIds).join(',');
 }
+export function localClaimCookieValue(kind, values) {
+    return normalizeLocalClaims(kind, values).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.
+ *
+ * `claims` is a third argument rather than three positional lists so that adding a fourth fact to
+ * the local identity later does not move an existing caller's arguments.
  */
-export function localIdentityCookieHeader(persona, workspaceIds = []) {
+export function localIdentityCookieHeader(persona, workspaceIds = [], claims = {}) {
     const membership = normalizeLocalMembership(persona, workspaceIds);
+    const { roles, permissions } = normalizeLocalPersonaClaims(persona, claims);
     const pairs = [`${LOCAL_PERSONA_COOKIE}=${persona}`];
     if (membership.length > 0)
         pairs.push(`${LOCAL_WORKSPACE_COOKIE}=${membership.join(',')}`);
+    if (roles.length > 0)
+        pairs.push(`${LOCAL_ROLE_COOKIE}=${roles.join(',')}`);
+    if (permissions.length > 0)
+        pairs.push(`${LOCAL_PERMISSION_COOKIE}=${permissions.join(',')}`);
     return pairs.join('; ');
 }

package/vendor/spec/page-cursor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export interface PageCursorPosition {
+    /** The last returned row's `created_at`, as the ISO-8601 text the column stores. */
+    readonly createdAt: string;
+    /** That row's id, which breaks ties within a single `created_at`. */
+    readonly id: string;
+}
+/** Mints the token that resumes a scan immediately after `(createdAt, id)`. */
+export declare function encodePageCursor(createdAt: string, id: string): string;
+/** The inverse, or `null` when the text is not a cursor this version wrote. */
+export declare function decodePageCursor(cursor: string): PageCursorPosition | null;

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/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;