@impetik/xeer-mcp 0.2.16 → 0.2.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "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.16"
+    "@impetik/xeer": "0.2.18"
   },
   "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

@@ -12,6 +12,7 @@
  * catalogue disagree in either direction, so a new code cannot ship
  * undocumented and a retired code cannot linger here.
  */
+import { CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES, CLIENT_BUNDLE_ERROR_BUDGET_BYTES, CLIENT_IMPORT_POLICY, SERVER_IMPORT_POLICY, } from './import-policy.js';
 export const DIAGNOSTIC_FAMILIES = [
     {
         prefix: 'XE00',
@@ -142,26 +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 is not on the allowlist for that zone.', 'The client zone may import @impetik/xeer/client, /client/core, /shared, the JSX runtimes, and '
-        + 'preact; the server zone may import @impetik/xeer/server and /shared. 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', '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. 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', '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),
@@ -169,8 +205,34 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE1403', 'A file in public/ claims a platform-reserved path.', 'Move it: /_xeer/*, /__xeer/* and /_xa/* belong to the platform.', BUILT_BY_EVERY_BUILD),
     define('XE1404', 'The manifest declares a favicon the project does not ship in public/.', 'Add the file under public/, or drop app.favicon. Emitting the reference anyway would put a '
         + 'link that 404s into every document the application serves.', BUILT_BY_EVERY_BUILD),
+    define('XE1405', 'The minified client JavaScript bundle exceeds its byte budget — the platform\'s '
+        + `${Math.round(CLIENT_BUNDLE_ERROR_BUDGET_BYTES / 1024)} KiB default, or the manifest\'s `
+        + '`budgets.clientBundleBytes` when declared. The message attributes bytes to the packages that '
+        + 'contributed them.', 'Read the attribution in the message and remove or replace the heaviest dependency, or raise '
+        + '`budgets.clientBundleBytes` (bounded by the 10 MiB module ceiling) if the size is intended.', BUILT_BY_EVERY_BUILD),
+    define('XE1406', 'The minified client JavaScript bundle exceeds the fixed '
+        + `${Math.round(CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES / 1024)} KiB advisory tier. The build still `
+        + 'succeeds; this is a warning with per-package byte attribution.', 'Nothing is required. If the growth is unintended, the attribution in the message names the '
+        + '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 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 '
+        + 'it to one instance. Two renderer copies means two options singletons — hooks and components '
+        + 'silently stop sharing state.', 
+    // The analyzer admits path imports against the managed-renderer roots, so the escape is reported
+    // at the user's own import during `check`; the build's metafile verification reports the same
+    // code for the same defect one stage later, when it survives as a second bundled copy.
+    CHECKED_BY_EVERY_COMPILE),
     define('XE1602', 'A watch rebuild failed. The previously accepted generation is still serving.', 'Fix the edit named by `file`. The next quiet-window rebuild promotes automatically; no restart.', ['dev']),
     define('XE1603', 'A rebuilt candidate compiled but failed to take over — usually a manifest or schema '
         + 'change the running state cannot accept — and the last-good generation was restored.', 'Fix the manifest or schema change. To adopt an incompatible schema locally, stop dev and run '
@@ -238,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 '
@@ -315,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 '
@@ -437,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.',
     ];
@@ -477,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

@@ -0,0 +1,172 @@
+/**
+ * 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 two module graphs the compiler walks. Test files have their own surface and are not a zone. */
+export type ImportZone = 'client' | 'server';
+/**
+ * What one public entrypoint of the managed renderer package is *for*. Admission derives from this:
+ * `runtime` and `development` entrypoints may be imported by client application code; `test` and
+ * `metadata` entrypoints are deliberately rejected there (XE1202) so a test-only or package-metadata
+ * path can never become a production-client import merely because the package publishes it.
+ */
+export type RendererEntrypointClassification = 
+/** Part of the supported client runtime surface, in any build mode. */
+'runtime'
+/** Supported, but exists for development tooling; mutates the renderer's shared options. */
+ | 'development'
+/** Test-only surface. Never a production-client import. */
+ | 'test'
+/** A `package.json` subpath: metadata, not code. Pinned during bundling, rejected as an import. */
+ | 'metadata';
+/**
+ * A package family whose members must resolve to one physical package root regardless of importer —
+ * the renderer, on the client. `entrypoints` classifies every public export of the anchor package;
+ * `compatAliases` maps the React-ecosystem specifiers onto their `preact/compat` targets, which is
+ * React-library compatibility under the Preact provider, not BYO React (#214 owns a real adapter).
+ */
+export interface ManagedPackageFamily {
+    /** The one package whose installed copy anchors every member of the family. */
+    readonly anchorPackage: string;
+    /** Bare package names the family owns; any subpath of these is family territory. */
+    readonly packages: readonly string[];
+    /** Every public entrypoint of the anchor package, classified. Keys are full specifiers. */
+    readonly entrypoints: ReadonlyMap<string, RendererEntrypointClassification>;
+    /** Per-subpath React-family aliases onto anchor entrypoints. Keys are full specifiers. */
+    readonly compatAliases: ReadonlyMap<string, string>;
+    readonly jsx: {
+        readonly importSource: string;
+        readonly runtime: string;
+        readonly devRuntime: string;
+    };
+}
+export interface ZoneImportPolicy {
+    readonly zone: ImportZone;
+    /**
+     * `@impetik/xeer/*` subpaths this zone admits. What each one resolves to is the compiler's
+     * 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. */
+    readonly managedFamilies: readonly ManagedPackageFamily[];
+    /**
+     * 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` when the zone declares none. */
+        readonly bundleBudget: {
+            readonly errorBytes: number;
+            readonly advisoryBytes: number;
+        } | null;
+    };
+}
+/**
+ * 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 declare const NORMALIZED_CLIENT_RUNTIME: Readonly<{
+    readonly provider: "preact";
+    readonly source: "platform";
+}>;
+/** The normalized client runtime as compiler facts and artifact provenance spell it. */
+export declare const CLIENT_RUNTIME_ID: "preact/platform";
+/**
+ * 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 declare const CLIENT_BUNDLE_ERROR_BUDGET_BYTES: number;
+export declare const CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES: number;
+/** The client renderer family under the Preact provider. */
+export declare const PREACT_RENDERER_FAMILY: ManagedPackageFamily;
+export declare const CLIENT_IMPORT_POLICY: ZoneImportPolicy;
+/**
+ * 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;
+/** The bare package name of a specifier: the first segment, or the first two for a scope. */
+export declare function packageNameOfSpecifier(specifier: string): string;
+/** How a zone's policy answers one authored bare specifier. */
+export type BareImportAdmission = 
+/** An `@impetik/xeer/*` subpath this zone admits. */
+{
+    kind: 'platform';
+}
+/** A managed-family specifier this zone admits; `target` is the anchor entrypoint it pins to. */
+ | {
+    kind: 'managed';
+    classification: RendererEntrypointClassification;
+    target: string;
+}
+/** A managed-family specifier this zone deliberately rejects. */
+ | {
+    kind: 'managed-rejected';
+    reason: 'test-only' | 'metadata' | 'unknown-entrypoint';
+}
+/** An application dependency, admitted subject to the declaration invariant. */
+ | {
+    kind: 'open';
+}
+/**
+ * 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' | 'foreign-family' | 'closed';
+};
+/**
+ * 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;
+/**
+ * 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 declare function managedImportSpecifiers(policy: ZoneImportPolicy): ReadonlyMap<string, string>;