@impetik/xeer-mcp 0.2.16 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "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.17"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

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',
@@ -145,9 +146,14 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + '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),
+    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),
     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 '
@@ -156,6 +162,14 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + '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),
     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 '
+        + '"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 '
+        + '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 '
+        + 'present on disk, then check again.', 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),
@@ -169,8 +183,32 @@ 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 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('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 '

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

@@ -0,0 +1,145 @@
+/**
+ * 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 today. */
+    readonly managedFamilies: readonly ManagedPackageFamily[];
+    /** The open set. `closed` reproduces the pre-#212 behavior exactly. */
+    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. */
+        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: 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.
+ */
+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';
+}
+/** Structurally rejected: a Node builtin, a foreign platform subpath, or a closed zone. */
+ | {
+    kind: 'rejected';
+    reason: 'platform-subpath' | '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.
+ */
+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>;

package/vendor/spec/import-policy.js

@@ -0,0 +1,194 @@
+/**
+ * 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]),
+    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: 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.
+ */
+export const SERVER_IMPORT_POLICY = Object.freeze({
+    zone: 'server',
+    platformModules: SERVER_PLATFORM_MODULES,
+    managedFamilies: Object.freeze([]),
+    applicationDependencies: Object.freeze({
+        mode: 'closed',
+        conditions: Object.freeze([]),
+        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 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.
+ */
+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 };
+    }
+    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';

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

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

@@ -43,11 +43,12 @@ export declare const IMMUTABLE_ASSET_HASH_LENGTH = 64;
 /**
  * Upper bound on {@link PublicAssetsV0.retainedGenerations}.
  *
- * One, because one is what the control plane implements. A wider range was declared first and that
+ * Two, because two is what the control plane implements. A wider range was declared first and that
  * was a promise the code did not keep: an artifact could ask for four generations and silently get
- * one. A contract that can express a value nothing honours is worse than a narrow contract.
+ * one. A contract that can express a value nothing honours is worse than a narrow contract, so this
+ * bound moves only in lockstep with the retention fold in the control plane's deployment service.
  */
-export declare const MAX_RETAINED_ASSET_GENERATIONS = 1;
+export declare const MAX_RETAINED_ASSET_GENERATIONS = 2;
 /**
  * What a declared entry is an alias *of*. Kept as a string rather than a structured pair because its
  * only consumers are humans reading an artifact and a diagnostic naming the file that produced a
@@ -95,9 +96,11 @@ export interface PublicAssetsV0 {
     /**
      * How many *previous* deployments' immutable assets keep serving alongside this one.
      *
-     * The value is `0` or `1` and nothing else — see {@link MAX_RETAINED_ASSET_GENERATIONS}. `1` means
-     * the deployment this artifact replaces keeps answering for its content-addressed paths; `0` means
-     * it does not, and a client holding the older document gets a 404.
+     * The value is `0`, `1`, or `2` and nothing else — see {@link MAX_RETAINED_ASSET_GENERATIONS}.
+     * `1` means the deployment this artifact replaces keeps answering for its content-addressed paths;
+     * `2` extends that to the deployment before it, which is what an artifact carrying package-derived
+     * subresources asks for so a document cached across two deploys still resolves its assets; `0`
+     * means nothing is retained, and a client holding an older document gets a 404.
      *
      * Worth recording honestly: this is the *incoming* artifact selecting an obligation that is owed to
      * documents emitted by the *outgoing* one, and deployment cadence is a control-plane concern rather

package/vendor/spec/public-assets.js

@@ -43,11 +43,12 @@ export const IMMUTABLE_ASSET_HASH_LENGTH = 64;
 /**
  * Upper bound on {@link PublicAssetsV0.retainedGenerations}.
  *
- * One, because one is what the control plane implements. A wider range was declared first and that
+ * Two, because two is what the control plane implements. A wider range was declared first and that
  * was a promise the code did not keep: an artifact could ask for four generations and silently get
- * one. A contract that can express a value nothing honours is worse than a narrow contract.
+ * one. A contract that can express a value nothing honours is worse than a narrow contract, so this
+ * bound moves only in lockstep with the retention fold in the control plane's deployment service.
  */
-export const MAX_RETAINED_ASSET_GENERATIONS = 1;
+export const MAX_RETAINED_ASSET_GENERATIONS = 2;
 const IMMUTABLE_PATH = /^\/_xa\/[0-9a-f]{64}\/[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/u;
 const ASSET_HASH = /^sha256:[0-9a-f]{64}$/u;
 /** The URL a blob of bytes is served at, and the only sanctioned way to mint one. */

package/vendor/spec/schema.d.ts

@@ -151,11 +151,18 @@ export declare const applicationManifestSchema: z.ZodObject<{
         database: "database";
         storage: "storage";
     }>>>;
+    client: z.ZodOptional<z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodLiteral<"preact">;
+            source: z.ZodOptional<z.ZodLiteral<"platform">>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     budgets: z.ZodOptional<z.ZodObject<{
         queryRows: z.ZodOptional<z.ZodNumber>;
         mutationWrites: z.ZodOptional<z.ZodNumber>;
         requestBytes: z.ZodOptional<z.ZodNumber>;
         responseBytes: z.ZodOptional<z.ZodNumber>;
+        clientBundleBytes: z.ZodOptional<z.ZodNumber>;
         liveConnections: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/vendor/spec/schema.js

@@ -271,11 +271,26 @@ export const applicationManifestSchema = z.strictObject({
         writeBytes: z.number().int().positive().max(STORAGE_MAX_WRITE_BYTES).optional(),
     }).optional(),
     capabilities: z.array(z.enum(CAPABILITIES)).optional(),
+    /**
+     * The client runtime selection (#212). Closed: only implemented provider/source combinations are
+     * accepted, and omitting any level of it normalizes to the platform-managed Preact runtime with
+     * identical semantics and build output.
+     */
+    client: z.strictObject({
+        runtime: z.strictObject({
+            provider: z.literal('preact'),
+            source: z.literal('platform').optional(),
+        }).optional(),
+    }).optional(),
     budgets: z.strictObject({
         queryRows: z.number().int().positive().max(10_000).optional(),
         mutationWrites: z.number().int().positive().max(1_000).optional(),
         requestBytes: z.number().int().positive().max(4 * 1024 * 1024).optional(),
         responseBytes: z.number().int().positive().max(4 * 1024 * 1024).optional(),
+        // The error tier for the minified pre-gzip client bundle, defaulting to the platform's 1 MiB.
+        // Bounded by the same 10 MiB ceiling every compiled module already has, so raising it can never
+        // promise bytes the artifact format refuses.
+        clientBundleBytes: z.number().int().positive().max(10 * 1024 * 1024).optional(),
         // Zero is a declaration, not an omission: it says the application wants no server push at all,
         // and the runtime answers `live_disabled` for it rather than a retryable budget refusal. The
         // bound is `min(0)` and not `positive()` so the editor schema publishes `minimum: 0`.
@@ -336,6 +351,7 @@ export const applicationManifestJsonSchema = Object.freeze({
         app: describeProperty('app', 'Browser metadata and SPA behavior.'),
         database: describeProperty('database', 'Typed application database schema. Requires the database capability.'),
         storage: describeProperty('storage', 'Private object-storage limits. Requires the storage capability.'),
+        client: describeProperty('client', 'Client runtime selection. Optional; omission means the platform-managed Preact runtime.'),
         capabilities: {
             ...describeProperty('capabilities', 'Powers granted to the application. Duplicate names are invalid.'),
             uniqueItems: true,
@@ -395,6 +411,9 @@ export function normalizeApplicationManifest(manifest) {
             }
             : null,
         capabilities: [...(manifest.capabilities ?? [])].sort(),
+        // Always normalized: omission and the explicit default are the same statement, and everything
+        // downstream (compiler facts, artifact provenance) reads one canonical value.
+        client: { runtime: { provider: 'preact', source: 'platform' } },
         budgets: {
             queryRows: manifest.budgets?.queryRows ?? 1_000,
             mutationWrites: manifest.budgets?.mutationWrites ?? 100,
@@ -404,6 +423,11 @@ export function normalizeApplicationManifest(manifest) {
             // application's Durable Object continuously, so a positive default charged every application
             // for a feature most never used. Declare a positive value to turn it on.
             liveConnections: manifest.budgets?.liveConnections ?? 0,
+            // Present only when declared, mirroring `storage`: the platform default is applied at build
+            // time, so an application that never declares the budget hashes exactly as before (#212).
+            ...(manifest.budgets?.clientBundleBytes !== undefined
+                ? { clientBundleBytes: manifest.budgets.clientBundleBytes }
+                : {}),
         },
     };
 }

package/vendor/spec/types.d.ts

@@ -141,6 +141,18 @@ export interface ApplicationManifestV0 {
     };
     storage?: StorageConfigV0;
     capabilities?: Capability[];
+    /**
+     * The client runtime selection (#212). Optional, and closed: only implemented provider/source
+     * combinations are accepted, and omission normalizes to `{ provider: "preact", source:
+     * "platform" }` with identical semantics and build output. Declaring it is a statement of the
+     * default, not a choice — a future app-owned source would be `"application"`, not `"user"`.
+     */
+    client?: {
+        runtime?: {
+            provider: 'preact';
+            source?: 'platform';
+        };
+    };
     budgets?: {
         queryRows?: number;
         mutationWrites?: number;
@@ -152,6 +164,12 @@ export interface ApplicationManifestV0 {
          * runtime answers a terminal `live_disabled` without waking the state object.
          */
         liveConnections?: number;
+        /**
+         * Error-tier byte budget for the minified pre-gzip client JavaScript bundle. Defaults to the
+         * platform's 1 MiB when omitted; bounded above by the 10 MiB module ceiling. The advisory tier
+         * is fixed and not declarable.
+         */
+        clientBundleBytes?: number;
     };
 }
 export interface NormalizedApplicationManifestV0 {
@@ -176,6 +194,13 @@ export interface NormalizedApplicationManifestV0 {
      */
     storage: NormalizedStorageConfigV0 | null;
     capabilities: Capability[];
+    /** Always present once normalized: omission and the explicit default are the same statement. */
+    client: {
+        runtime: {
+            provider: 'preact';
+            source: 'platform';
+        };
+    };
     budgets: {
         queryRows: number;
         mutationWrites: number;
@@ -183,6 +208,11 @@ export interface NormalizedApplicationManifestV0 {
         responseBytes: number;
         /** `0` means server push is off for this application; see {@link ApplicationManifestV0}. */
         liveConnections: number;
+        /**
+         * Present only when the manifest declares it, mirroring `storage`: an application on the
+         * platform default hashes exactly as it did before the budget was declarable.
+         */
+        clientBundleBytes?: number;
     };
 }
 export interface SourceReceipt {
@@ -190,6 +220,31 @@ export interface SourceReceipt {
     size: number;
     hash: `sha256:${string}`;
 }
+/**
+ * Provenance for one npm package the client bundle consumed (#212). `files` receipts the exact
+ * bytes the bundler read — strictly stronger than lockfile integrity, which pins tarballs rather
+ * than the post-install state a patch or postinstall script left on disk.
+ */
+export interface BundledDependencyReceiptV0 {
+    name: string;
+    version: string;
+    /** The metafile inputs consumed from this package, package-root-relative, content-hashed. */
+    files: SourceReceipt[];
+}
+/**
+ * The application-dependency provenance block, present in an artifact only when the bundle
+ * consumed open dependencies. The lockfile identity is opportunistic — recorded when a parseable
+ * npm or pnpm lockfile is found — and never an admission gate: workspace applications have no
+ * per-app lockfile at all.
+ */
+export interface BundledDependenciesV0 {
+    packages: BundledDependencyReceiptV0[];
+    lockfile?: {
+        manager: 'npm' | 'pnpm';
+        path: string;
+        hash: `sha256:${string}`;
+    };
+}
 export interface ApplicationSchemaIdentityV0 {
     applicationSchemaVersion: number;
     schemaHash: `sha256:${string}`;
@@ -222,6 +277,12 @@ export interface ApplicationArtifactV0 {
      * artifact binds different buckets in preview and production, which is correct (#51 §7).
      */
     storage?: NormalizedStorageConfigV0;
+    /**
+     * The normalized client runtime, recorded when the application declares `client` or the bundle
+     * consumed open dependencies. Present-only-then for the same reason as `storage`: an untouched
+     * application keeps its `artifactId` (#212).
+     */
+    clientRuntime?: NormalizedApplicationManifestV0['client']['runtime'];
     budgets: NormalizedApplicationManifestV0['budgets'];
     schema: NormalizedApplicationManifestV0['database'];
     schemaIdentity: ApplicationSchemaIdentityV0;
@@ -264,6 +325,8 @@ export interface ApplicationArtifactV0 {
     publicAssets: PublicAssetsV0;
     source: {
         files: SourceReceipt[];
+        /** Present only when the client bundle consumed open application dependencies (#212). */
+        dependencies?: BundledDependenciesV0;
     };
 }
 export interface DevEvent<T = unknown> {