@impetik/xeer-mcp 0.2.17 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.17"
+    "@impetik/xeer": "0.2.19"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/actions.d.ts

@@ -481,7 +481,7 @@ declare const actions: readonly [{
     readonly command: readonly ["inspect"];
     readonly summary: "Read a running application manifest.";
     readonly description: string;
-    readonly usage: readonly ["inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]"];
+    readonly usage: readonly ["inspect <local-url|app|directory> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 230;
     readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly ["network-read", "read-state"];
@@ -874,7 +874,7 @@ declare const actions: readonly [{
     readonly id: "preview";
     readonly command: readonly ["preview"];
     readonly summary: "Run a verified artifact in a local preview server.";
-    readonly usage: readonly ["preview [directory] [--host <host>] [--port <port>] [--json]"];
+    readonly usage: readonly ["preview [directory] [--host <host>] [--port <port>] [--force] [--json]"];
     readonly helpOrder: 240;
     readonly outputProtocol: "xeer.dev.v0";
     readonly effects: readonly ["read-source", "write-generated", "run-local", "write-state"];
@@ -892,7 +892,7 @@ declare const actions: readonly [{
     readonly command: readonly ["state"];
     readonly summary: "Read record counts from a running application.";
     readonly description: string;
-    readonly usage: readonly ["state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]"];
+    readonly usage: readonly ["state <local-url|app|directory> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 260;
     readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly ["network-read", "read-state"];
@@ -927,7 +927,7 @@ declare const actions: readonly [{
     readonly command: readonly ["logs"];
     readonly summary: "Read the bounded log ring of a running application.";
     readonly description: string;
-    readonly usage: readonly ["logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]"];
+    readonly usage: readonly ["logs <local-url|app|directory> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]"];
     readonly helpOrder: 280;
     readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly ["network-read", "read-state"];
@@ -1014,7 +1014,7 @@ declare const actions: readonly [{
     readonly id: "auth.as";
     readonly command: readonly ["auth", "as"];
     readonly summary: "Select a deterministic local development persona.";
-    readonly usage: readonly ["auth as <alice|bob> [directory] [--workspace <id>]... [--json]"];
+    readonly usage: readonly ["auth as <alice|bob|carol> [directory] [--workspace <id>]... [--role <name>]... [--permission <name>]... [--json]"];
     readonly helpOrder: 200;
     readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly ["write-state"];

package/vendor/spec/actions.js

@@ -75,7 +75,9 @@ const MCP_PRESENTATION = {
             'Each failed case carries a Diagnostic-shaped failure with matcher, expected, actual, and the',
             'project-relative test location: XE1904 assertion, XE1905 threw or unexpectedly refused call,',
             'XE1906 timeout. Compiler diagnostics abort the run before any test boots.',
-            'Tests call as(\'alice\'|\'bob\'|\'guest\'), so ownership and authorization are directly testable.',
+            'Tests call as(\'alice\'|\'bob\'|\'carol\'|\'guest\'), optionally with { workspaceIds, roles, permissions },',
+            'so ownership and authorization are directly testable. A persona holding none of the three is',
+            'kind: "guest" and authenticated() refuses it.',
         ].join(' '),
     },
     new: {
@@ -340,7 +342,8 @@ const actions = [
         description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
             + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
             + '--environment preview to select preview.',
-        usage: ['inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 230,
+        usage: ['inspect <local-url|app|directory> [--environment prod|preview] [--control-url <url>] [--json]'],
+        helpOrder: 230,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
         surfaces: {
@@ -531,7 +534,7 @@ const actions = [
     },
     {
         id: 'preview', command: ['preview'], summary: 'Run a verified artifact in a local preview server.',
-        usage: ['preview [directory] [--host <host>] [--port <port>] [--json]'], helpOrder: 240,
+        usage: ['preview [directory] [--host <host>] [--port <port>] [--force] [--json]'], helpOrder: 240,
         outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
         idempotent: false, reversible: true, destructive: false, humanPrerequisites: [],
         pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
@@ -541,7 +544,8 @@ const actions = [
         description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
             + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
             + '--environment preview to select preview.',
-        usage: ['state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 260,
+        usage: ['state <local-url|app|directory> [--environment prod|preview] [--control-url <url>] [--json]'],
+        helpOrder: 260,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
         surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
@@ -559,7 +563,7 @@ const actions = [
         description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
             + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
             + '--environment preview to select preview.',
-        usage: ['logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]'],
+        usage: ['logs <local-url|app|directory> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]'],
         helpOrder: 280, outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'],
         idempotent: true, reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
         surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
@@ -607,7 +611,8 @@ const actions = [
     },
     {
         id: 'auth.as', command: ['auth', 'as'], summary: 'Select a deterministic local development persona.',
-        usage: ['auth as <alice|bob> [directory] [--workspace <id>]... [--json]'], helpOrder: 200,
+        usage: ['auth as <alice|bob|carol> [directory] [--workspace <id>]... [--role <name>]... [--permission <name>]... [--json]'],
+        helpOrder: 200,
         outputProtocol: 'xeer.command.v0', effects: ['write-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
         surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },

package/vendor/spec/admin.d.ts

@@ -19,6 +19,7 @@
  * `INSERT OR IGNORE`, so a retried request writes the same id and changes nothing, and the response
  * says whether this call was the one that created it. No request ledger, no dedupe window.
  */
+import { decodePageCursor, encodePageCursor } from './page-cursor.js';
 import type { EncodedValue } from './value.js';
 export declare const ADMIN_PROTOCOL: "xeer.admin.v0";
 /** Columns the runtime owns on every table. Present in every row, never writable by a client. */
@@ -101,10 +102,11 @@ export interface AdminWriteResponseV0 {
  * A page cursor. Opaque to clients by contract, and deliberately not signed: it names a position in
  * the caller's own data on a surface they already had to authenticate to reach, so there is nothing
  * for a forged one to disclose that the next page would not have shown anyway.
+ *
+ * The console and `ctx.db.table(…).page(…)` seek the same `(created_at, id)` keyset over the same
+ * tables, so they share one codec rather than keeping two that could drift into disagreeing about
+ * what a token means. The names stay because the admin protocol names them.
  */
-export declare function encodeAdminCursor(createdAt: string, id: string): string;
+export declare const encodeAdminCursor: typeof encodePageCursor;
 /** The inverse, or `null` when the text is not a cursor this version wrote. */
-export declare function decodeAdminCursor(cursor: string): {
-    createdAt: string;
-    id: string;
-} | null;
+export declare const decodeAdminCursor: typeof decodePageCursor;

package/vendor/spec/admin.js

@@ -19,6 +19,7 @@
  * `INSERT OR IGNORE`, so a retried request writes the same id and changes nothing, and the response
  * says whether this call was the one that created it. No request ledger, no dedupe window.
  */
+import { decodePageCursor, encodePageCursor } from './page-cursor.js';
 export const ADMIN_PROTOCOL = 'xeer.admin.v0';
 /** Columns the runtime owns on every table. Present in every row, never writable by a client. */
 export const ADMIN_RUNTIME_FIELDS = Object.freeze([
@@ -33,26 +34,11 @@ export const ADMIN_PAGE_MAX = 200;
  * A page cursor. Opaque to clients by contract, and deliberately not signed: it names a position in
  * the caller's own data on a surface they already had to authenticate to reach, so there is nothing
  * for a forged one to disclose that the next page would not have shown anyway.
+ *
+ * The console and `ctx.db.table(…).page(…)` seek the same `(created_at, id)` keyset over the same
+ * tables, so they share one codec rather than keeping two that could drift into disagreeing about
+ * what a token means. The names stay because the admin protocol names them.
  */
-export function encodeAdminCursor(createdAt, id) {
-    const text = JSON.stringify([createdAt, id]);
-    return btoa(String.fromCharCode(...new TextEncoder().encode(text)))
-        .replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
-}
+export const encodeAdminCursor = encodePageCursor;
 /** The inverse, or `null` when the text is not a cursor this version wrote. */
-export function decodeAdminCursor(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;
-        return { createdAt, id };
-    }
-    catch {
-        return null;
-    }
-}
+export const decodeAdminCursor = decodePageCursor;

package/vendor/spec/diagnostics.js

@@ -143,39 +143,61 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE1003', 'The manifest carries a property the application-source schema does not define.', 'Remove the property, or fix its spelling. The manifest is closed: unknown keys are never ignored.', CHECKED_BY_EVERY_COMPILE),
     define('XE1101', 'An entrypoint path is absolute or escapes the project root.', 'Use a forward-slash path relative to xeer.app.json that stays inside the project.', CHECKED_BY_EVERY_COMPILE),
     define('XE1201', 'A source import breaks the zone boundary: it is absolute, leaves the project root, '
-        + 'reaches the opposite entrypoint, or the module is reachable from both graphs while living outside '
-        + 'src/shared/.', 'Keep imports relative and inside the project. Move genuinely shared code to src/shared/ and update '
-        + 'both importers; never import one entrypoint from the other.', CHECKED_BY_EVERY_COMPILE),
-    define('XE1202', 'A package import violates the zone\'s import policy structurally: a Node builtin, '
-        + 'a platform subpath the zone does not admit, a renderer-family entrypoint that is test-only, '
-        + 'metadata, or unknown to the selected runtime source, or (server zone) any npm package — the '
-        + 'server zone is closed.', `The client zone admits ${CLIENT_IMPORT_POLICY.platformModules.join(', ')}, the platform-managed `
-        + 'renderer surface (preact and its supported entrypoints, plus React-ecosystem imports aliased '
-        + 'onto preact/compat), and any npm package declared in package.json dependencies and installed. '
-        + `The server zone admits only ${SERVER_IMPORT_POLICY.platformModules.join(', ')}. Node builtins `
-        + 'are never importable. Move the code to the zone that owns it instead of widening the import.', CHECKED_BY_EVERY_COMPILE),
+        + 'reaches the opposite entrypoint, or pulls a module out of the other zone\'s graph. A cross-zone '
+        + 'import is reported at the import that admitted the module, not at the modules it dragged in — '
+        + 'those are correct where they live. A module both graphs reach with no zone-exclusive import '
+        + 'anywhere beneath it names no offending side, and is reported on the module itself.', 'Keep imports relative and inside the project; never import one entrypoint from the other. For a '
+        + 'cross-zone import, delete the import the message points at: move code both zones need to '
+        + 'src/shared/ and import it from there, or expose the data through a query, mutation, or endpoint '
+        + 'and call it from the client. Do not remove the zone imports from the modules it reached.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1202', 'A package import violates the zone\'s import policy structurally: a Node builtin '
+        + 'or a native addon (.node) in any zone, a platform subpath the zone does not admit, a '
+        + 'renderer-family entrypoint that is test-only, metadata, or unknown to the selected runtime '
+        + 'source, or a package family the other zone owns — the renderer (preact, react, react-dom, '
+        + 'scheduler) in the server zone. It is not reported for an ordinary npm package in either zone: '
+        + 'both admit any declared and installed dependency.', `The client zone admits ${CLIENT_IMPORT_POLICY.platformModules.join(', ')} and the `
+        + 'platform-managed renderer surface (preact and its supported entrypoints, plus '
+        + 'React-ecosystem imports aliased onto preact/compat); the server zone admits '
+        + `${SERVER_IMPORT_POLICY.platformModules.join(', ')}. Both zones additionally admit any npm `
+        + 'package declared in package.json dependencies and installed. Node builtins and native addons '
+        + 'are never importable anywhere: the client runs in a browser and the server runs in workerd, '
+        + 'neither of which has them — that is a runtime fact, not an allowlist. Move the code to the '
+        + 'zone that owns the import, or use a dependency that targets browsers and workers.', CHECKED_BY_EVERY_COMPILE),
     define('XE1203', 'A dynamic import() specifier is not a string literal.', 'Use a literal specifier so the module graph stays statically knowable, or a static import.', CHECKED_BY_EVERY_COMPILE),
     define('XE1204', 'A relative source import does not resolve to a file.', 'Write the specifier without an extension, or with the file\'s real one: the resolver appends '
         + 'candidate extensions rather than rewriting them, so ./shared/title.js does not find '
         + 'shared/title.ts. Directory imports resolve to index.*.', CHECKED_BY_EVERY_COMPILE),
     define('XE1205', 'TypeScript reported an error in a file reachable from an entrypoint. The message '
         + 'starts with the TS#### code and span points at the exact position.', 'Fix the type error. Operation input and result types come from the generated contract, so a mismatch '
-        + 'between a client call and its server handler surfaces here.', CHECKED_BY_EVERY_COMPILE),
+        + 'between a client call and its server handler surfaces here. A handler whose result the platform '
+        + 'cannot encode is reported on the handler: declare result shapes with a `type` alias rather than an '
+        + '`interface`, which TypeScript never gives an implicit index signature.', CHECKED_BY_EVERY_COMPILE),
     define('XE1206', 'A stylesheet is imported outside the client graph.', 'Import .css only from client modules; the server bundle has no styling stage.', CHECKED_BY_EVERY_COMPILE),
-    define('XE1207', 'A client-zone import names an npm package that package.json does not declare in '
+    define('XE1207', 'An import names an npm package that package.json does not declare in '
         + '"dependencies". It may still resolve through hoisting, which is exactly the accident the rule '
-        + 'exists to prevent.', 'Add the package to the application\'s package.json "dependencies" and install it. The client '
-        + 'zone may import any declared and installed npm package; type-only imports may come from '
+        + 'exists to prevent. Reported in both zones: the message names the zone the import was written '
+        + 'in, but the rule is the same one.', 'Add the package to the application\'s package.json "dependencies" and install it. Either zone '
+        + 'may import any declared and installed npm package; type-only imports may come from '
         + 'devDependencies instead.', CHECKED_BY_EVERY_COMPILE),
-    define('XE1208', 'A client-zone import names a declared dependency that is not installed: nothing '
-        + 'in a reachable node_modules provides it.', 'Run your package manager\'s install (npm install / pnpm install) so the declared dependency is '
+    define('XE1208', 'An import names a declared dependency that is not installed: nothing '
+        + 'in a reachable node_modules provides it. Reported in both zones.', 'Run your package manager\'s install (npm install / pnpm install) so the declared dependency is '
         + 'present on disk, then check again.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1209', 'A subresource — an image, a font, or a wasm module — is imported outside the '
+        + 'client graph. The declarations that give such an import a type are program-global, so it '
+        + 'type-checks in every zone, but only the client bundler has a loader that turns one into a URL.', 'Import images, fonts, and wasm only from client modules; the server bundle has no asset stage. '
+        + 'A server handler that needs the bytes should read them from public/ or receive the URL from '
+        + 'the client.', CHECKED_BY_EVERY_COMPILE),
     define('XE1300', 'The default server export is not a statically inspectable defineServer({...}) call, '
         + 'or an operation group is not a literal object.', 'Export `default defineServer({ queries: {...}, mutations: {...}, endpoints: {...} })` with literal '
         + 'object members: no spreads, shorthand, computed keys, or wrappers.', CHECKED_BY_EVERY_COMPILE),
     define('XE1301', 'Two operations in the same group share a name.', 'Rename one of them, or delete the duplicate registration if it was a copy-paste.', CHECKED_BY_EVERY_COMPILE),
     define('XE1302', 'An endpoint key is not `METHOD /api/path`.', 'Use an uppercase HTTP method, one space, and a literal /api path; dynamic segments are :name.', CHECKED_BY_EVERY_COMPILE),
-    define('XE1303', 'A query or mutation name is not namespaced.', 'Use a dotted lowercase name such as notes.list.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1303', 'A query or mutation name does not match the operation-name grammar: two or more '
+        + 'dot-separated segments, each starting with a lowercase letter and continuing with lowercase '
+        + 'letters, digits, `_`, or `-`.', 'Write the name as `namespace.name` with no uppercase letter anywhere — uppercase is the '
+        + 'restriction authors do not expect, so `posts.bySlug` is refused even though it is namespaced. '
+        + 'Separate words with `_` or `-` instead: notes.list, notes.list_pinned, notes.by-slug, and '
+        + 'notes.pinned.v2 are all accepted. Formally `^[a-z][a-z0-9_-]*\\.[a-z][a-z0-9_.-]*$`.', CHECKED_BY_EVERY_COMPILE),
     define('XE1304', 'Two endpoints reduce to the same route shape, so dispatch would be ambiguous.', 'Change the method or a static path segment. Parameter names do not distinguish routes: '
         + 'GET /api/notes/:id and GET /api/notes/:slug are the same route.', CHECKED_BY_EVERY_COMPILE),
     define('XE1401', 'A compiled module (10 MiB) or an asset (25 MiB) exceeds the v0 limit.', 'Shrink the module or asset. There is no flag that raises a v0 limit.', BUILT_BY_EVERY_BUILD),
@@ -194,12 +216,14 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'packages to reconsider before the error tier is reached.', BUILT_BY_EVERY_BUILD),
     define('XE1501', 'Bundling failed after the module graph and types were accepted.', 'Read the bundler message in `message`. It usually names a syntax construct the target does not '
         + 'support, rather than a Xeer rule.', BUILT_BY_EVERY_BUILD),
-    define('XE1502', 'A bundled client dependency imports a Node builtin, so the bundle cannot run in a '
-        + 'browser. The message names the dependency and the builtin; the offending import sits inside '
-        + 'the package, not in application code. The diagnostic is located at the application import '
-        + 'that admitted the package into the client graph.', 'Use a browser-targeted package (or the package\'s browser entrypoint) instead. The client zone '
-        + 'has no Node builtins to offer, so the platform refuses the bundle rather than shipping one '
-        + 'that throws at load time.', BUILT_BY_EVERY_BUILD),
+    define('XE1502', 'A bundled dependency imports a Node builtin, so the bundle cannot run where its '
+        + 'zone runs — a browser for the client zone, workerd for the server zone. The message names the '
+        + 'zone, the dependency and the builtin; the offending import sits inside the package, not in '
+        + 'application code. The diagnostic is located at the application import that admitted the '
+        + 'package into that zone\'s graph.', 'Use a package targeting browsers and workers, or the package\'s browser/worker entrypoint. '
+        + 'Neither zone has Node builtins to offer, so the platform refuses the bundle rather than '
+        + 'shipping one that throws at load time. This is a property of the dependency chain and so is '
+        + 'found at build, not at check.', BUILT_BY_EVERY_BUILD),
     define('XE1503', 'The client bundle would contain a second physical copy of the managed renderer. '
         + 'Bare renderer imports are pinned to the platform anchor, so a second copy means a path-based '
         + 'escape: a relative or absolute import reaching into some node_modules copy of the renderer.', 'Import the renderer by its bare specifier (preact, preact/hooks, react, …) so the platform pins '
@@ -276,8 +300,10 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + "names: pass it with as({ name, workspaceIds }).", ['test']),
     define('XE1906', 'A test exceeded its 20 second budget. The remaining tests still run.', 'Remove the wait: tests run against a local runtime, so a timeout means an unresolved promise or an '
         + 'operation that never returns, not a slow machine.', ['test']),
-    define('XE2001', 'An inspector command was invoked without a target.', 'Pass the preview URL from the dev/preview `preview.ready` event, or a deployed application name, '
-        + 'appId, or URL.', ['inspect', 'state']),
+    define('XE2001', 'An inspector command was invoked without a target, or with a project directory in '
+        + 'which no `xeer dev` or `xeer preview` server is running — or in which both are, so the '
+        + 'directory does not name one of them.', 'Pass a project directory (`.`) to read the local server running for it, the URL from the '
+        + 'dev/preview `preview.ready` event, or a deployed application name, appId, or URL.', ['inspect', 'state']),
     define('XE2002', 'The inspector request itself failed: a local dev/preview inspector that answered '
         + 'a non-2xx status or no JSON, or a control plane that refused the proxied read, in which case '
         + 'the read never reached the application. An application that refused the read is XE2004.', 'Confirm the preview is still running and the URL matches the current `preview.ready` event. For a '
@@ -353,6 +379,11 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE5133', 'A closed-beta quota refused the environment-variable request: `xeer env set` claims '
         + 'the project on first use, so it is capped by the same apps-per-builder quota as `xeer deploy`.', 'Set the value on an app you already own — `xeer link` lists them — or ask the Xeer team to raise the '
         + 'quota. `message` states the quota, your usage, and any reset.', ['env']),
+    define('XE5134', 'A file exists at `.xeer/env.<environment>.local.json` but could not be used '
+        + 'in full: it is not a `xeer.env-local.v0` document, it could not be read, or some of its '
+        + 'entries have names or values a local run cannot load — so `ctx.env` is missing them.', 'Read `message`: it names the file and the exact problem — the shape to write is '
+        + '{"format": "xeer.env-local.v0", "values": {"NAME": "value"}} with UPPER_SNAKE_CASE names '
+        + 'and string values. `xeer env pull` writes the file correctly.', ['dev', 'preview', 'test']),
     define('XE5139', 'xeer env failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['env']),
     define('XE5140', 'An `xeer deployments` invocation is wrong: an unusable --limit, or a directory that '
         + 'declares no app identity.', 'Read `message`. --limit takes a positive integer up to 200. In a directory with no appId, run '
@@ -475,9 +506,18 @@ export function renderDiagnosticsReference() {
         '  file?: string;                // project-relative POSIX path, never absolute',
         '  span?: { line: number; column: number; length?: number };  // 1-based',
         '  hint?: string;                // suggested edit',
+        '  primary?: true;               // this broke the generated contract — repair it first',
+        '  causedBy?: string;            // a consequence of that code, not an independent error',
         '}',
         '```',
         '',
+        '`primary` and `causedBy` are optional and may be absent from an entire envelope; absence means nothing',
+        'was attributed, not that a diagnostic is independent. When they are present, repair every `primary: true`',
+        'diagnostic first and leave every `causedBy` one alone until the primaries are clean: a `causedBy`',
+        'diagnostic sits in a file the broken contract poisoned, and editing that file makes the application',
+        'worse. Re-run afterwards — whatever still reports is real and carries its own location. A run that',
+        'found a contract failure emits its primaries first; sort on the field rather than relying on that.',
+        '',
         'The "Seen in" column lists the commands whose JSON can carry the code. `check` diagnostics also appear',
         'in `build` and `dev`, because both run the same manifest and analysis stages first.',
     ];
@@ -515,9 +555,20 @@ export function renderDiagnosticsDocsPage() {
         '  file?: string;                // project-relative POSIX path, never absolute',
         '  span?: { line: number; column: number; length?: number };  // 1-based',
         '  hint?: string;                // suggested edit',
+        '  primary?: true;               // this broke the generated contract — repair it first',
+        '  causedBy?: string;            // a consequence of that code, not an independent error',
         '}',
         '```',
         '',
+        'The last two fields are optional and may be absent from an entire envelope; absence means nothing was',
+        'attributed, not that a diagnostic is independent. A failure that invalidates the generated contract —',
+        'a `defineServer` the compiler cannot read statically, a duplicate operation name, an operation result',
+        'the platform cannot encode — makes every type derived from those operations wrong, so the files that',
+        'consume the contract fill with `XE1205` type errors their authors never caused. Repair the',
+        '`primary: true` diagnostics first, ignore the `causedBy` ones until the primaries are clean, then',
+        're-run: whatever still reports is real. Such a run emits its primaries ahead of the rest, so the',
+        'diagnostic worth reading is also the first one printed.',
+        '',
         'Every command prints these as JSON with `--json`; see [Building with AI agents](/guides/agents).',
         'The "Seen in" column lists the commands whose output can carry the code. `check` diagnostics also',
         'appear in `build` and `dev`, because both run the same manifest and analysis stages first.',

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

@@ -59,16 +59,24 @@ export interface ZoneImportPolicy {
      * knowledge — the SDK module targets live beside its resolver, not in this declarative layer.
      */
     readonly platformModules: readonly string[];
-    /** Singleton-sensitive families. The renderer on the client; empty on the server today. */
+    /** Singleton-sensitive families. The renderer on the client; empty on the server. */
     readonly managedFamilies: readonly ManagedPackageFamily[];
-    /** The open set. `closed` reproduces the pre-#212 behavior exactly. */
+    /**
+     * Package families another zone owns, refused here whatever the open set says. The renderer on the
+     * server: `preact` is declared and installed in any application with a client, so once the server
+     * zone admits declared dependencies (#244) nothing else would stop a server module importing it,
+     * and the server has no DOM to render into. Zone-exclusive rather than structurally impossible —
+     * which is what makes it *evidence* for cross-zone attribution, where a Node builtin is not.
+     */
+    readonly foreignFamilies: readonly ManagedPackageFamily[];
+    /** The open set. `closed` admits nothing beyond the two lists above. */
     readonly applicationDependencies: {
         readonly mode: 'closed' | 'open';
         /** Bundler resolution conditions for this zone's application dependencies. */
         readonly conditions: readonly string[];
         /** Compile-time defines applied when bundling this zone. */
         readonly defines: Readonly<Record<string, string>>;
-        /** Byte budgets over the zone's single-chunk bundle; `null` while the zone is closed. */
+        /** Byte budgets over the zone's single-chunk bundle; `null` when the zone declares none. */
         readonly bundleBudget: {
             readonly errorBytes: number;
             readonly advisoryBytes: number;
@@ -98,9 +106,22 @@ export declare const CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES: number;
 export declare const PREACT_RENDERER_FAMILY: ManagedPackageFamily;
 export declare const CLIENT_IMPORT_POLICY: ZoneImportPolicy;
 /**
- * The server zone: today's behavior, expressed as a policy value rather than a separate code path.
- * `mode: 'closed'` is byte-identical to the pre-#212 server allowlist; opening it later is a policy
- * decision plus a trust-model decision (#27), not new machinery.
+ * 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 declare const SERVER_IMPORT_POLICY: ZoneImportPolicy;
 export declare function zoneImportPolicy(zone: ImportZone): ZoneImportPolicy;
@@ -127,15 +148,21 @@ export type BareImportAdmission =
  | {
     kind: 'open';
 }
-/** Structurally rejected: a Node builtin, a foreign platform subpath, or a closed zone. */
+/**
+ * Rejected on a zone rule rather than on the declaration invariant: a subpath of the platform
+ * package this zone does not admit, a package family another zone owns, or a zone that admits no
+ * application dependencies at all. Every one of these is *zone-exclusive* — the same specifier is
+ * legal somewhere — which is why they are attribution evidence and Node builtins are not.
+ */
  | {
     kind: 'rejected';
-    reason: 'platform-subpath' | 'closed';
+    reason: 'platform-subpath' | 'foreign-family' | 'closed';
 };
 /**
- * Classifies one bare specifier under a zone's policy. Node builtins are the caller's concern (the
- * analyzer already owns that list); everything else — platform subpaths, managed families, and the
- * open set — is answered here so no consumer keeps a private copy of the rules.
+ * 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 declare function admitBareImport(policy: ZoneImportPolicy, specifier: string): BareImportAdmission;
 /**

package/vendor/spec/import-policy.js

@@ -110,6 +110,7 @@ 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']),
@@ -121,17 +122,31 @@ export const CLIENT_IMPORT_POLICY = Object.freeze({
     }),
 });
 /**
- * The server zone: today's behavior, expressed as a policy value rather than a separate code path.
- * `mode: 'closed'` is byte-identical to the pre-#212 server allowlist; opening it later is a policy
- * decision plus a trust-model decision (#27), not new machinery.
+ * 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: 'closed',
-        conditions: Object.freeze([]),
+        mode: 'open',
+        conditions: Object.freeze(['worker', 'import']),
         defines: Object.freeze({}),
         bundleBudget: null,
     }),
@@ -145,9 +160,10 @@ export function packageNameOfSpecifier(specifier) {
     return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
 }
 /**
- * Classifies one bare specifier under a zone's policy. Node builtins are the caller's concern (the
- * analyzer already owns that list); everything else — platform subpaths, managed families, and the
- * open set — is answered here so no consumer keeps a private copy of the rules.
+ * 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))
@@ -169,6 +185,12 @@ export function admitBareImport(policy, specifier) {
             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' };

package/vendor/spec/index.d.ts

@@ -21,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

@@ -21,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';