@impetik/xeer-mcp 0.2.16 → 0.2.18

package/vendor/spec/import-policy.js

@@ -0,0 +1,216 @@
+/**
+ * The per-zone import policy: the one hand-maintained statement of what a bare specifier may mean
+ * in each zone (#212).
+ *
+ * Before this module existed the same facts lived in five independently maintained forms — the
+ * analyzer's client-package allowlist, the platform type-module resolver, the build-time runtime
+ * aliases and their entrypoint-matching regex, the dev server's alias/dedupe/optimizeDeps block,
+ * and the diagnostics prose — and issue #210 was the drift that duplication invites: validation
+ * accepted an import that bundling then resolved to a second Preact instance. Every one of those
+ * consumers now derives from the two policy instances declared here.
+ *
+ * Deliberately free of I/O and of `require.resolve`: this module states *policy*, and the compiler
+ * turns it into resolved file paths against the platform's own installed renderer (its "anchor").
+ * Keeping it in the spec package lets the diagnostics catalogue render its guidance from the same
+ * source, and vendoring folds it into the published tarball with everything else.
+ */
+/**
+ * The normalized client runtime: the only implemented provider/source combination. `client.runtime`
+ * in the manifest is optional and omission normalizes to exactly this value, so declaring it is a
+ * statement of the default rather than a choice.
+ */
+export const NORMALIZED_CLIENT_RUNTIME = Object.freeze({
+    provider: 'preact',
+    source: 'platform',
+});
+/** The normalized client runtime as compiler facts and artifact provenance spell it. */
+export const CLIENT_RUNTIME_ID = `${NORMALIZED_CLIENT_RUNTIME.provider}/${NORMALIZED_CLIENT_RUNTIME.source}`;
+/**
+ * Default and advisory budgets for the open client bundle, minified pre-gzip bytes of the single
+ * JavaScript chunk. The error tier is overridable through manifest `budgets.clientBundleBytes`
+ * under the existing normalization pattern, bounded by the 10 MiB module ceiling; the advisory tier
+ * is fixed. Values are a product decision recorded in #212.
+ */
+export const CLIENT_BUNDLE_ERROR_BUDGET_BYTES = 1024 * 1024;
+export const CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES = 400 * 1024;
+/**
+ * Every public entrypoint of the platform Preact package, classified. The compiler's conformance
+ * test compares this map against the installed package's `exports` map in both directions, so a
+ * Preact upgrade that adds, removes, or renames an entrypoint fails until it is deliberately
+ * classified here.
+ */
+const PREACT_ENTRYPOINTS = new Map([
+    ['preact', 'runtime'],
+    ['preact/hooks', 'runtime'],
+    ['preact/jsx-runtime', 'runtime'],
+    ['preact/jsx-dev-runtime', 'runtime'],
+    ['preact/compat', 'runtime'],
+    ['preact/compat/client', 'runtime'],
+    // Browser-safe server rendering: both resolve to the browser build under the client conditions.
+    ['preact/compat/server', 'runtime'],
+    ['preact/compat/server.browser', 'runtime'],
+    ['preact/compat/jsx-runtime', 'runtime'],
+    ['preact/compat/jsx-dev-runtime', 'runtime'],
+    ['preact/compat/scheduler', 'runtime'],
+    // Side-effectful development surfaces: they mutate the shared renderer options, which is exactly
+    // why they must be pinned to the same singleton as everything else.
+    ['preact/debug', 'development'],
+    ['preact/devtools', 'development'],
+    ['preact/test-utils', 'test'],
+    ['preact/compat/test-utils', 'test'],
+    ['preact/package.json', 'metadata'],
+    ['preact/compat/package.json', 'metadata'],
+    ['preact/debug/package.json', 'metadata'],
+    ['preact/devtools/package.json', 'metadata'],
+    ['preact/hooks/package.json', 'metadata'],
+    ['preact/test-utils/package.json', 'metadata'],
+    ['preact/jsx-runtime/package.json', 'metadata'],
+]);
+/**
+ * The complete per-subpath React-family alias table. Every key is pinned to its target for every
+ * importer — application code, SDK, JSX runtime, generated bootstrap, and bundled dependencies'
+ * own imports alike — so a React-ecosystem library and the platform renderer can never diverge
+ * into two instances. The installed Preact publishes a matching export for every target.
+ */
+const REACT_COMPAT_ALIASES = new Map([
+    ['react', 'preact/compat'],
+    ['react/jsx-runtime', 'preact/compat/jsx-runtime'],
+    ['react/jsx-dev-runtime', 'preact/compat/jsx-dev-runtime'],
+    ['react-dom', 'preact/compat'],
+    ['react-dom/client', 'preact/compat/client'],
+    ['react-dom/server', 'preact/compat/server'],
+    ['react-dom/server.browser', 'preact/compat/server.browser'],
+    ['react-dom/test-utils', 'preact/compat/test-utils'],
+    ['scheduler', 'preact/compat/scheduler'],
+]);
+/** The client renderer family under the Preact provider. */
+export const PREACT_RENDERER_FAMILY = Object.freeze({
+    anchorPackage: 'preact',
+    packages: Object.freeze(['preact', 'react', 'react-dom', 'scheduler']),
+    entrypoints: PREACT_ENTRYPOINTS,
+    compatAliases: REACT_COMPAT_ALIASES,
+    jsx: Object.freeze({
+        importSource: '@impetik/xeer',
+        runtime: 'preact/jsx-runtime',
+        devRuntime: 'preact/jsx-dev-runtime',
+    }),
+});
+const CLIENT_PLATFORM_MODULES = Object.freeze([
+    '@impetik/xeer/client',
+    '@impetik/xeer/client/core',
+    '@impetik/xeer/shared',
+    '@impetik/xeer/jsx-runtime',
+    '@impetik/xeer/jsx-dev-runtime',
+]);
+const SERVER_PLATFORM_MODULES = Object.freeze([
+    '@impetik/xeer/server',
+    '@impetik/xeer/shared',
+]);
+export const CLIENT_IMPORT_POLICY = Object.freeze({
+    zone: 'client',
+    platformModules: CLIENT_PLATFORM_MODULES,
+    managedFamilies: Object.freeze([PREACT_RENDERER_FAMILY]),
+    foreignFamilies: Object.freeze([]),
+    applicationDependencies: Object.freeze({
+        mode: 'open',
+        conditions: Object.freeze(['browser', 'import']),
+        defines: Object.freeze({ 'process.env.NODE_ENV': '"production"' }),
+        bundleBudget: Object.freeze({
+            errorBytes: CLIENT_BUNDLE_ERROR_BUDGET_BYTES,
+            advisoryBytes: CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES,
+        }),
+    }),
+});
+/**
+ * The server zone, open to application dependencies since ADR 0005 was accepted (#244).
+ *
+ * The two zones now state the same rule — declare it, install it, type it, use it — and differ only
+ * where the *runtime* differs. `workerd` conditions are declared because that is what the server
+ * executes in, so a package that publishes a worker build gets it. What stays refused on the server
+ * is refused for one of two reasons, and the distinction is load-bearing for both the diagnostic's
+ * wording and cross-zone attribution:
+ *
+ * - **Impossible**: Node builtins and native addons. workerd provides neither, and no policy change
+ *   can conjure them. Refused in *every* zone, so it says nothing about which zone a module is in.
+ * - **Zone-exclusive**: the renderer family, and `@impetik/xeer/client*`. Perfectly loadable here;
+ *   simply the other zone's surface. This is what attribution reads as evidence.
+ *
+ * No byte budget: unlike the client bundle, the server module is not shipped to a browser on every
+ * cold navigation, so the 10 MiB v0 module ceiling (XE1401) is the only bound the platform has a
+ * defensible number for. A per-zone budget is a product decision, not a gap this change may fill.
+ */
+export const SERVER_IMPORT_POLICY = Object.freeze({
+    zone: 'server',
+    platformModules: SERVER_PLATFORM_MODULES,
+    managedFamilies: Object.freeze([]),
+    foreignFamilies: Object.freeze([PREACT_RENDERER_FAMILY]),
+    applicationDependencies: Object.freeze({
+        mode: 'open',
+        conditions: Object.freeze(['worker', 'import']),
+        defines: Object.freeze({}),
+        bundleBudget: null,
+    }),
+});
+export function zoneImportPolicy(zone) {
+    return zone === 'client' ? CLIENT_IMPORT_POLICY : SERVER_IMPORT_POLICY;
+}
+/** The bare package name of a specifier: the first segment, or the first two for a scope. */
+export function packageNameOfSpecifier(specifier) {
+    const segments = specifier.split('/');
+    return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+}
+/**
+ * Classifies one bare specifier under a zone's policy. Node builtins and native addons are the
+ * caller's concern (the analyzer already owns those, and they are refused in every zone); everything
+ * else — platform subpaths, managed and foreign families, and the open set — is answered here so no
+ * consumer keeps a private copy of the rules.
+ */
+export function admitBareImport(policy, specifier) {
+    if (policy.platformModules.includes(specifier))
+        return { kind: 'platform' };
+    if (specifier === '@impetik/xeer' || specifier.startsWith('@impetik/xeer/')) {
+        return { kind: 'rejected', reason: 'platform-subpath' };
+    }
+    const packageName = packageNameOfSpecifier(specifier);
+    for (const family of policy.managedFamilies) {
+        if (!family.packages.includes(packageName))
+            continue;
+        const target = family.compatAliases.get(specifier) ?? specifier;
+        const classification = family.entrypoints.get(target);
+        if (!classification)
+            return { kind: 'managed-rejected', reason: 'unknown-entrypoint' };
+        if (classification === 'test')
+            return { kind: 'managed-rejected', reason: 'test-only' };
+        if (classification === 'metadata')
+            return { kind: 'managed-rejected', reason: 'metadata' };
+        return { kind: 'managed', classification, target };
+    }
+    // Before the open set, or an installed renderer would be admitted by the declaration invariant it
+    // satisfies in every application that has a client.
+    for (const family of policy.foreignFamilies) {
+        if (family.packages.includes(packageName))
+            return { kind: 'rejected', reason: 'foreign-family' };
+    }
+    if (policy.applicationDependencies.mode === 'open')
+        return { kind: 'open' };
+    return { kind: 'rejected', reason: 'closed' };
+}
+/**
+ * The admitted managed-family surface of a zone, alias keys included — what bundling and the dev
+ * server must pin to the anchor, and what documentation lists as the renderer surface.
+ */
+export function managedImportSpecifiers(policy) {
+    const result = new Map();
+    for (const family of policy.managedFamilies) {
+        for (const [specifier, classification] of family.entrypoints) {
+            if (classification === 'runtime' || classification === 'development')
+                result.set(specifier, specifier);
+        }
+        for (const [alias, target] of family.compatAliases) {
+            const classification = family.entrypoints.get(target);
+            if (classification === 'runtime' || classification === 'development')
+                result.set(alias, target);
+        }
+    }
+    return result;
+}

package/vendor/spec/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './diagnostics.js';
+export * from './import-policy.js';
 export * from './schema.js';
 export * from './storage.js';
 export * from './canonical.js';
@@ -20,3 +21,4 @@ export * from './network-policy.js';
 export * from './review.js';
 export * from './template.js';
 export * from './tunnel.js';
+export * from './type-check-profile.js';

package/vendor/spec/index.js

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './diagnostics.js';
+export * from './import-policy.js';
 export * from './schema.js';
 export * from './storage.js';
 export * from './canonical.js';
@@ -20,3 +21,4 @@ export * from './network-policy.js';
 export * from './review.js';
 export * from './template.js';
 export * from './tunnel.js';
+export * from './type-check-profile.js';

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;