@nimbus-sh/core 0.1.0

package/dist/_shared/crypto.d.ts

@@ -0,0 +1,17 @@
+export interface SealedJsonOptions {
+    purpose?: string;
+    minSecretLength?: number;
+}
+export declare function randomBase64Url(byteLength: number): string;
+export declare function sha256Base64Url(input: string): Promise<string>;
+export declare function pkceChallenge(verifier: string): Promise<string>;
+/** Lowercase hex SHA-256 — the digest form the staged-artifact integrity checks pin. */
+export declare function sha256Hex(input: BufferSource | string): Promise<string>;
+export declare function sealJson(value: unknown, secret: string, options?: SealedJsonOptions): Promise<string>;
+export declare function unsealJson<T>(value: string, secret: string, options?: SealedJsonOptions): Promise<T | null>;
+export declare function encodeJsonBase64Url(value: unknown): string;
+export declare function decodeJsonBase64Url<T>(value: string): T;
+export declare function base64Url(bytes: Uint8Array): string;
+export declare function base64UrlDecode(value: string): Uint8Array;
+export declare function base64Utf8(value: string): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/_shared/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/_shared/crypto.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAErE;AAED,wFAAwF;AACxF,wBAAsB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS7E;AAED,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,wBAAsB,UAAU,CAAC,CAAC,EAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CA6BnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAEvD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAUnD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CASzD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD"}

package/dist/_shared/crypto.js

@@ -0,0 +1,131 @@
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const SEALED_JSON_V2 = 'v2.';
+const SEALED_JSON_V1 = 'v1.';
+const HKDF_SALT = textEncoder.encode('nimbus-sh sealed-json v2');
+const BASE64URL_RE = /^[A-Za-z0-9_-]*$/;
+export function randomBase64Url(byteLength) {
+    const bytes = new Uint8Array(byteLength);
+    crypto.getRandomValues(bytes);
+    return base64Url(bytes);
+}
+export async function sha256Base64Url(input) {
+    const digest = await crypto.subtle.digest('SHA-256', textEncoder.encode(input));
+    return base64Url(new Uint8Array(digest));
+}
+export async function pkceChallenge(verifier) {
+    return sha256Base64Url(verifier);
+}
+/** Lowercase hex SHA-256 — the digest form the staged-artifact integrity checks pin. */
+export async function sha256Hex(input) {
+    const digest = await crypto.subtle.digest('SHA-256', typeof input === 'string' ? textEncoder.encode(input) : input);
+    const view = new Uint8Array(digest);
+    let hex = '';
+    for (let i = 0; i < view.length; i++)
+        hex += view[i].toString(16).padStart(2, '0');
+    return hex;
+}
+export async function sealJson(value, secret, options = {}) {
+    const purpose = normalizePurpose(options.purpose);
+    const key = await hkdfAesGcmKey(secret, purpose, options.minSecretLength);
+    const iv = new Uint8Array(12);
+    crypto.getRandomValues(iv);
+    const plaintext = textEncoder.encode(JSON.stringify(value));
+    const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad(purpose) }, key, plaintext));
+    const packed = new Uint8Array(iv.length + ciphertext.length);
+    packed.set(iv, 0);
+    packed.set(ciphertext, iv.length);
+    return SEALED_JSON_V2 + base64Url(packed);
+}
+export async function unsealJson(value, secret, options = {}) {
+    if (value.startsWith(SEALED_JSON_V2)) {
+        const purpose = normalizePurpose(options.purpose);
+        const packed = base64UrlDecode(value.slice(SEALED_JSON_V2.length));
+        if (packed.length <= 12)
+            return null;
+        const iv = packed.slice(0, 12);
+        const ciphertext = packed.slice(12);
+        const key = await hkdfAesGcmKey(secret, purpose, options.minSecretLength);
+        const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv, additionalData: aad(purpose) }, key, ciphertext);
+        return JSON.parse(textDecoder.decode(plaintext));
+    }
+    // Backward compatibility for the original agent OAuth cookie format.
+    // New cookies are always v2 and purpose-bound through AES-GCM AAD.
+    if (value.startsWith(SEALED_JSON_V1)) {
+        const packed = base64UrlDecode(value.slice(SEALED_JSON_V1.length));
+        if (packed.length <= 12)
+            return null;
+        const iv = packed.slice(0, 12);
+        const ciphertext = packed.slice(12);
+        const key = await legacyShaAesGcmKey(secret, options.minSecretLength);
+        const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+        return JSON.parse(textDecoder.decode(plaintext));
+    }
+    return null;
+}
+export function encodeJsonBase64Url(value) {
+    return base64Url(textEncoder.encode(JSON.stringify(value)));
+}
+export function decodeJsonBase64Url(value) {
+    return JSON.parse(textDecoder.decode(base64UrlDecode(value)));
+}
+export function base64Url(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/g, '');
+}
+export function base64UrlDecode(value) {
+    if (!BASE64URL_RE.test(value) || value.length % 4 === 1) {
+        throw new Error('Invalid base64url input');
+    }
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(value.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+export function base64Utf8(value) {
+    const bytes = textEncoder.encode(value);
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+async function hkdfAesGcmKey(secret, purpose, minSecretLength = 32) {
+    assertSecret(secret, minSecretLength);
+    const material = await crypto.subtle.importKey('raw', textEncoder.encode(secret), 'HKDF', false, ['deriveKey']);
+    return crypto.subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: HKDF_SALT,
+        info: textEncoder.encode(purpose),
+    }, material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+async function legacyShaAesGcmKey(secret, minSecretLength = 32) {
+    assertSecret(secret, minSecretLength);
+    const digest = await crypto.subtle.digest('SHA-256', textEncoder.encode(secret));
+    return crypto.subtle.importKey('raw', digest, 'AES-GCM', false, ['decrypt']);
+}
+function assertSecret(secret, minSecretLength) {
+    if (!secret || secret.length < minSecretLength) {
+        throw new Error(`Sealed JSON secret must be ${minSecretLength}+ characters`);
+    }
+}
+function normalizePurpose(purpose) {
+    const value = (purpose || 'default').trim();
+    if (!value)
+        return 'default';
+    return value.slice(0, 128);
+}
+function aad(purpose) {
+    return textEncoder.encode(`nimbus-sh:${purpose}:sealed-json:v2`);
+}

package/dist/_shared/esbuild-facet-shim.d.ts

@@ -0,0 +1,21 @@
+/**
+ * esbuild's `__name` helper, for source injected into a facet isolate.
+ *
+ * wrangler bundles the supervisor with esbuild `keepNames`, which wraps every
+ * named function and named arrow as `__name(fn, "fn")`. Code we ship into a
+ * facet by `.toString()` therefore carries bare `__name` references, and the
+ * supervisor's module-local binding does NOT cross the isolate boundary — the
+ * facet must provide one or the embed dies with "__name is not defined".
+ *
+ * Assigned on `globalThis` rather than declared with `const` because these
+ * injection sites do not own their scope: the pyodide asm.js inlined next to
+ * it already declares `__name`/`__defProp` (a `const` would be "already
+ * declared"), and the W7 facet frame evaluates the embed elsewhere. A bare
+ * `__name` with no lexical binding resolves to the global either way, and the
+ * `typeof` guard keeps it idempotent when several embeds share one isolate.
+ *
+ * Unit tests import the un-bundled TS source, so only the deployed,
+ * esbuild-bundled worker ever needs this.
+ */
+export declare const ESBUILD_NAME_GLOBAL_SHIM = "if (typeof globalThis.__name !== \"function\") {\n  globalThis.__name = (target, value) => Object.defineProperty(target, \"name\", { value, configurable: true });\n}";
+//# sourceMappingURL=esbuild-facet-shim.d.ts.map

package/dist/_shared/esbuild-facet-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild-facet-shim.d.ts","sourceRoot":"","sources":["../../src/_shared/esbuild-facet-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,0KAEnC,CAAC"}

package/dist/_shared/esbuild-facet-shim.js

@@ -0,0 +1,22 @@
+/**
+ * esbuild's `__name` helper, for source injected into a facet isolate.
+ *
+ * wrangler bundles the supervisor with esbuild `keepNames`, which wraps every
+ * named function and named arrow as `__name(fn, "fn")`. Code we ship into a
+ * facet by `.toString()` therefore carries bare `__name` references, and the
+ * supervisor's module-local binding does NOT cross the isolate boundary — the
+ * facet must provide one or the embed dies with "__name is not defined".
+ *
+ * Assigned on `globalThis` rather than declared with `const` because these
+ * injection sites do not own their scope: the pyodide asm.js inlined next to
+ * it already declares `__name`/`__defProp` (a `const` would be "already
+ * declared"), and the W7 facet frame evaluates the embed elsewhere. A bare
+ * `__name` with no lexical binding resolves to the global either way, and the
+ * `typeof` guard keeps it idempotent when several embeds share one isolate.
+ *
+ * Unit tests import the un-bundled TS source, so only the deployed,
+ * esbuild-bundled worker ever needs this.
+ */
+export const ESBUILD_NAME_GLOBAL_SHIM = `if (typeof globalThis.__name !== "function") {
+  globalThis.__name = (target, value) => Object.defineProperty(target, "name", { value, configurable: true });
+}`;

package/dist/_shared/exports-resolver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * exports-resolver.ts — Single source of truth for `package.json#exports` /
+ * `package.json#imports` resolution per the Node.js spec.
+ *
+ * Used in three contexts:
+ *
+ *   1. Install-time supervisor (TS) — `src/npm-resolver.ts` re-exports the
+ *      typed functions for tree resolution.
+ *
+ *   2. NimbusLoaderPool isolates (JS string) — `src/loaders/pre-bundle-preamble.ts`
+ *      embeds `getExportsResolverJS()` as part of the pool preamble so the
+ *      pre-bundle facet uses identical resolution semantics to the supervisor.
+ *
+ *   3. User-shell `node` runtime (JS string) — `src/node-shims.ts` embeds
+ *      the same JS source so `require()` from inside a user's `node` script
+ *      sees the same exports map as the install pipeline.
+ *
+ *
+ * Spec features supported:
+ *   - String shorthand:                "exports": "./dist/index.mjs"
+ *   - Subpath maps:                    { ".": "...", "./client": "..." }
+ *   - Conditional maps (top-level):    { "import": "...", "require": "..." }
+ *   - Nested conditions:               { ".": { "node": { "default": "..." } } }
+ *   - Subpath wildcards:               { "./*": "./dist/*.js" }
+ *   - Array fallbacks:                 [ "./esm.js", "./cjs.js" ]
+ *   - `imports` field (`#name`):       same shape, same impl (re-uses resolveExports)
+ *   - Null-target enforcement:         { "./private/*": null } — returns null, blocks fallback
+ *
+ * Caller-controlled `conditions` lets the same impl serve:
+ *   - install/ESM/browser  →  ['import', 'module', 'browser', 'default']
+ *   - runtime CJS          →  ['require', 'node', 'default']
+ */
+/** Default conditions for ESM/install/browser resolution. */
+export declare const DEFAULT_ESM_CONDITIONS: string[];
+/** Default conditions for CJS runtime resolution (user-shell node). */
+export declare const DEFAULT_CJS_CONDITIONS: string[];
+/**
+ * Resolve `package.json#exports` (or `#imports`) per Node spec.
+ *
+ * @param exportsField  Raw value from package.json#exports or #imports
+ * @param subpath       '.' for root, './foo' for subpath, '#name' for imports
+ * @param conditions    Active conditions, in priority order
+ * @returns             Relative path target string, or null if not found / forbidden
+ */
+export declare function resolveExports(exportsField: any, subpath?: string, conditions?: string[]): string | null;
+/**
+ * Resolve a package's entry-point file relative to its directory.
+ * Priority: exports → module → main → null.
+ * For non-root subpaths without an `exports` field, returns the subpath
+ * itself (caller probes filesystem with extension-list).
+ */
+export declare function resolvePackageEntry(pkg: {
+    exports?: any;
+    module?: string;
+    main?: string;
+}, subpath?: string, conditions?: string[]): string | null;
+/**
+ * Returns the resolver source as plain JavaScript (no TypeScript syntax),
+ * suitable for embedding into a generated worker preamble or shim string.
+ *
+ * The emitted source declares three top-level functions in scope:
+ *   - resolveExports(exports, subpath, conditions)
+ *   - resolveConditionValue(target, conditions)        (helper)
+ *   - resolvePackageEntry(pkg, subpath, conditions)
+ *
+ * It also declares two arrays:
+ *   - DEFAULT_ESM_CONDITIONS
+ *   - DEFAULT_CJS_CONDITIONS
+ *
+ * This source must be byte-equivalent to the TS impl above (modulo type
+ * annotations and `export` keywords). Keep them in sync — there is one
+ */
+export declare function getExportsResolverJS(): string;
+//# sourceMappingURL=exports-resolver.d.ts.map

package/dist/_shared/exports-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports-resolver.d.ts","sourceRoot":"","sources":["../../src/_shared/exports-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,UAA6C,CAAC;AAEjF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,UAAiC,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,GAAG,EACjB,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAkEf;AAwCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAsBf;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAkG7C"}

package/dist/_shared/exports-resolver.js

@@ -0,0 +1,284 @@
+/**
+ * exports-resolver.ts — Single source of truth for `package.json#exports` /
+ * `package.json#imports` resolution per the Node.js spec.
+ *
+ * Used in three contexts:
+ *
+ *   1. Install-time supervisor (TS) — `src/npm-resolver.ts` re-exports the
+ *      typed functions for tree resolution.
+ *
+ *   2. NimbusLoaderPool isolates (JS string) — `src/loaders/pre-bundle-preamble.ts`
+ *      embeds `getExportsResolverJS()` as part of the pool preamble so the
+ *      pre-bundle facet uses identical resolution semantics to the supervisor.
+ *
+ *   3. User-shell `node` runtime (JS string) — `src/node-shims.ts` embeds
+ *      the same JS source so `require()` from inside a user's `node` script
+ *      sees the same exports map as the install pipeline.
+ *
+ *
+ * Spec features supported:
+ *   - String shorthand:                "exports": "./dist/index.mjs"
+ *   - Subpath maps:                    { ".": "...", "./client": "..." }
+ *   - Conditional maps (top-level):    { "import": "...", "require": "..." }
+ *   - Nested conditions:               { ".": { "node": { "default": "..." } } }
+ *   - Subpath wildcards:               { "./*": "./dist/*.js" }
+ *   - Array fallbacks:                 [ "./esm.js", "./cjs.js" ]
+ *   - `imports` field (`#name`):       same shape, same impl (re-uses resolveExports)
+ *   - Null-target enforcement:         { "./private/*": null } — returns null, blocks fallback
+ *
+ * Caller-controlled `conditions` lets the same impl serve:
+ *   - install/ESM/browser  →  ['import', 'module', 'browser', 'default']
+ *   - runtime CJS          →  ['require', 'node', 'default']
+ */
+/** Default conditions for ESM/install/browser resolution. */
+export const DEFAULT_ESM_CONDITIONS = ['import', 'module', 'browser', 'default'];
+/** Default conditions for CJS runtime resolution (user-shell node). */
+export const DEFAULT_CJS_CONDITIONS = ['require', 'node', 'default'];
+/**
+ * Resolve `package.json#exports` (or `#imports`) per Node spec.
+ *
+ * @param exportsField  Raw value from package.json#exports or #imports
+ * @param subpath       '.' for root, './foo' for subpath, '#name' for imports
+ * @param conditions    Active conditions, in priority order
+ * @returns             Relative path target string, or null if not found / forbidden
+ */
+export function resolveExports(exportsField, subpath = '.', conditions = DEFAULT_ESM_CONDITIONS) {
+    if (exportsField === undefined || exportsField === null)
+        return null;
+    // String shorthand — only valid for root entry
+    if (typeof exportsField === 'string') {
+        return subpath === '.' ? exportsField : null;
+    }
+    // Array fallback — try each in order
+    if (Array.isArray(exportsField)) {
+        for (const item of exportsField) {
+            const r = resolveExports(item, subpath, conditions);
+            if (r)
+                return r;
+        }
+        return null;
+    }
+    if (typeof exportsField !== 'object')
+        return null;
+    const keys = Object.keys(exportsField);
+    if (keys.length === 0)
+        return null;
+    // Subpath-map detection: keys begin with "." (exports) or "#" (imports)
+    const isSubpathMap = keys[0].startsWith('.') || keys[0].startsWith('#');
+    if (isSubpathMap) {
+        // Exact match first
+        if (subpath in exportsField) {
+            const target = exportsField[subpath];
+            // Null target — forbidden subpath, returns null and BLOCKS fallback
+            if (target === null)
+                return null;
+            return resolveConditionValue(target, conditions);
+        }
+        // Wildcard pattern match — try most-specific (longest prefix) first
+        const wildcardKeys = keys
+            .filter(k => k.includes('*'))
+            .sort((a, b) => b.length - a.length); // longest pattern wins
+        for (const pattern of wildcardKeys) {
+            const target = exportsField[pattern];
+            const starIdx = pattern.indexOf('*');
+            const prefix = pattern.slice(0, starIdx);
+            const suffix = pattern.slice(starIdx + 1);
+            if (subpath.startsWith(prefix) &&
+                (suffix ? subpath.endsWith(suffix) : true) &&
+                subpath.length >= prefix.length + suffix.length) {
+                // Null target on wildcard — forbidden, BLOCK fallback
+                if (target === null)
+                    return null;
+                const matched = subpath.slice(prefix.length, suffix ? subpath.length - suffix.length : undefined);
+                const resolved = resolveConditionValue(target, conditions);
+                if (resolved)
+                    return resolved.split('*').join(matched);
+            }
+        }
+        return null;
+    }
+    // Condition map (no subpath map keys) — only valid for root entry
+    if (subpath !== '.')
+        return null;
+    return resolveConditionValue(exportsField, conditions);
+}
+/**
+ * Resolve a condition target. Recurses through nested condition objects
+ * and array fallbacks. Honours `default` even if not in the conditions
+ * array (Node spec).
+ */
+function resolveConditionValue(target, conditions) {
+    if (target === null || target === undefined)
+        return null;
+    if (typeof target === 'string')
+        return target;
+    if (Array.isArray(target)) {
+        for (const item of target) {
+            const r = resolveConditionValue(item, conditions);
+            if (r)
+                return r;
+        }
+        return null;
+    }
+    if (typeof target !== 'object')
+        return null;
+    // Try each requested condition in priority order
+    for (const cond of conditions) {
+        if (cond in target) {
+            const r = resolveConditionValue(target[cond], conditions);
+            if (r)
+                return r;
+        }
+    }
+    // Spec: `default` is always a valid fallback
+    if (!conditions.includes('default') && 'default' in target) {
+        return resolveConditionValue(target.default, conditions);
+    }
+    return null;
+}
+/**
+ * Resolve a package's entry-point file relative to its directory.
+ * Priority: exports → module → main → null.
+ * For non-root subpaths without an `exports` field, returns the subpath
+ * itself (caller probes filesystem with extension-list).
+ */
+export function resolvePackageEntry(pkg, subpath = '.', conditions = DEFAULT_ESM_CONDITIONS) {
+    // 1. exports field
+    if (pkg.exports !== undefined && pkg.exports !== null) {
+        const entry = resolveExports(pkg.exports, subpath, conditions);
+        if (entry)
+            return entry;
+        // If exports is defined but yields nothing for this subpath,
+        // Node spec is: this is an error (subpath isn't exposed).
+        // We return null to let caller decide (some callers fall back to
+        // direct filesystem probing for compatibility with packages that
+        // mis-declare exports).
+        return null;
+    }
+    // 2. Root entry: module → main
+    if (subpath === '.') {
+        if (pkg.module)
+            return pkg.module;
+        if (pkg.main)
+            return pkg.main;
+        return null;
+    }
+    // 3. Non-root subpath without exports — caller probes raw subpath
+    return subpath;
+}
+// ─── JS-source emission for embedding into facet preambles ───────────────
+/**
+ * Returns the resolver source as plain JavaScript (no TypeScript syntax),
+ * suitable for embedding into a generated worker preamble or shim string.
+ *
+ * The emitted source declares three top-level functions in scope:
+ *   - resolveExports(exports, subpath, conditions)
+ *   - resolveConditionValue(target, conditions)        (helper)
+ *   - resolvePackageEntry(pkg, subpath, conditions)
+ *
+ * It also declares two arrays:
+ *   - DEFAULT_ESM_CONDITIONS
+ *   - DEFAULT_CJS_CONDITIONS
+ *
+ * This source must be byte-equivalent to the TS impl above (modulo type
+ * annotations and `export` keywords). Keep them in sync — there is one
+ */
+export function getExportsResolverJS() {
+    return `
+// ── exports-resolver.js (auto-generated; keep in sync with src/_shared/exports-resolver.ts) ──
+const DEFAULT_ESM_CONDITIONS = ['import', 'module', 'browser', 'default'];
+const DEFAULT_CJS_CONDITIONS = ['require', 'node', 'default'];
+
+function resolveExports(exportsField, subpath, conditions) {
+  if (subpath === undefined) subpath = '.';
+  if (!conditions) conditions = DEFAULT_ESM_CONDITIONS;
+  if (exportsField === undefined || exportsField === null) return null;
+  if (typeof exportsField === 'string') {
+    return subpath === '.' ? exportsField : null;
+  }
+  if (Array.isArray(exportsField)) {
+    for (const item of exportsField) {
+      const r = resolveExports(item, subpath, conditions);
+      if (r) return r;
+    }
+    return null;
+  }
+  if (typeof exportsField !== 'object') return null;
+  const keys = Object.keys(exportsField);
+  if (keys.length === 0) return null;
+  const isSubpathMap = keys[0].startsWith('.') || keys[0].startsWith('#');
+  if (isSubpathMap) {
+    if (subpath in exportsField) {
+      const target = exportsField[subpath];
+      if (target === null) return null;
+      return resolveConditionValue(target, conditions);
+    }
+    const wildcardKeys = keys
+      .filter(k => k.includes('*'))
+      .sort((a, b) => b.length - a.length);
+    for (const pattern of wildcardKeys) {
+      const target = exportsField[pattern];
+      const starIdx = pattern.indexOf('*');
+      const prefix = pattern.slice(0, starIdx);
+      const suffix = pattern.slice(starIdx + 1);
+      if (
+        subpath.startsWith(prefix) &&
+        (suffix ? subpath.endsWith(suffix) : true) &&
+        subpath.length >= prefix.length + suffix.length
+      ) {
+        if (target === null) return null;
+        const matched = subpath.slice(
+          prefix.length,
+          suffix ? subpath.length - suffix.length : undefined,
+        );
+        const resolved = resolveConditionValue(target, conditions);
+        if (resolved) return resolved.split('*').join(matched);
+      }
+    }
+    return null;
+  }
+  if (subpath !== '.') return null;
+  return resolveConditionValue(exportsField, conditions);
+}
+
+function resolveConditionValue(target, conditions) {
+  if (target === null || target === undefined) return null;
+  if (typeof target === 'string') return target;
+  if (Array.isArray(target)) {
+    for (const item of target) {
+      const r = resolveConditionValue(item, conditions);
+      if (r) return r;
+    }
+    return null;
+  }
+  if (typeof target !== 'object') return null;
+  for (const cond of conditions) {
+    if (cond in target) {
+      const r = resolveConditionValue(target[cond], conditions);
+      if (r) return r;
+    }
+  }
+  if (!conditions.includes('default') && 'default' in target) {
+    return resolveConditionValue(target.default, conditions);
+  }
+  return null;
+}
+
+function resolvePackageEntry(pkg, subpath, conditions) {
+  if (subpath === undefined) subpath = '.';
+  if (!conditions) conditions = DEFAULT_ESM_CONDITIONS;
+  if (pkg.exports !== undefined && pkg.exports !== null) {
+    const entry = resolveExports(pkg.exports, subpath, conditions);
+    if (entry) return entry;
+    return null;
+  }
+  if (subpath === '.') {
+    if (pkg.module) return pkg.module;
+    if (pkg.main) return pkg.main;
+    return null;
+  }
+  return subpath;
+}
+// ── end exports-resolver.js ────────────────────────────────────────────
+`;
+}

package/dist/_shared/facet-vfs-cursor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Seed the coherence cursor the facet's staged VFS snapshot was read at.
+ *
+ * A facet's resident set is a cache of the supervisor's VFS, and the cursor is
+ * the only thing that says WHICH state it caches. Without one the first ACQUIRE
+ * carries a null epoch, and a null epoch is not a stale cursor the authority can
+ * compute a delta from — it can only answer poison, "drop everything". So the
+ * first async fs call in the process throws away every staged cell, and the next
+ * synchronous read of any of them raises EAGAIN for content that was staged
+ * correctly and never changed. Measured: pi, launched as a bin, lost all 3210
+ * cells of its bundle to one `fs.promises` call and then failed reading its own
+ * `dist/modes/interactive/theme/dark.json`.
+ *
+ * Shared source rather than a line per body: the long-running node body and the
+ * staged-artifact body each hold a hand-written copy of the snapshot preamble,
+ * and neither gained this seed when the one-shot body did. That drift is the
+ * defect, and one definition every generator splices is what makes it
+ * unrepeatable.
+ *
+ * Splice it AFTER `__MODULE_VFS_CURSOR` is defined and BEFORE the shims: the
+ * shims read the cursor into a closure const as they evaluate, so an assignment
+ * that lands later replaces an object nothing still points at.
+ *
+ * Where `__MODULE_VFS_CURSOR` comes from is the generator's business, and for
+ * the two node bodies there is only one right answer: the invocation. Their
+ * generated text is content-addressed — the one-shot body is cached on
+ * hash(code + bundle + manifest), the resident body is stored as a facet image
+ * named by its own digest — and a cursor carries a revision that advances on
+ * every spawn and an epoch that belongs to one supervisor incarnation. Baked
+ * in, it gives the same program a new image each time and hands a shared body
+ * another session's epoch. So it rides the request body and the start payload
+ * respectively, the same channel argv and env want. The staged-artifact body
+ * is generated from a per-invocation spec that is not addressed by its bytes,
+ * so there it is simply one more field of that spec.
+ */
+export declare const VFS_CURSOR_SEED_SOURCE = "\nif (__MODULE_VFS_CURSOR) {\n  globalThis.__nimbusVfsCursor = {\n    epoch: __MODULE_VFS_CURSOR.epoch,\n    rev: __MODULE_VFS_CURSOR.rev,\n  };\n}\n";
+/** The cursor a facet snapshot travels with, or `null` when it has none. */
+export interface FacetVfsCursor {
+    epoch: string;
+    rev: number;
+}
+/**
+ * The `__MODULE_VFS_CURSOR` literal for a generated facet body. `null` is a
+ * real answer — a facet built without a VFS has no state to be coherent with —
+ * and the seed above is a no-op for it.
+ */
+export declare function serializeFacetVfsCursor(cursor: FacetVfsCursor | undefined): string;
+//# sourceMappingURL=facet-vfs-cursor.d.ts.map

package/dist/_shared/facet-vfs-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet-vfs-cursor.d.ts","sourceRoot":"","sources":["../../src/_shared/facet-vfs-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,sBAAsB,0JAOlC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAElF"}

package/dist/_shared/facet-vfs-cursor.js

@@ -0,0 +1,51 @@
+/**
+ * Seed the coherence cursor the facet's staged VFS snapshot was read at.
+ *
+ * A facet's resident set is a cache of the supervisor's VFS, and the cursor is
+ * the only thing that says WHICH state it caches. Without one the first ACQUIRE
+ * carries a null epoch, and a null epoch is not a stale cursor the authority can
+ * compute a delta from — it can only answer poison, "drop everything". So the
+ * first async fs call in the process throws away every staged cell, and the next
+ * synchronous read of any of them raises EAGAIN for content that was staged
+ * correctly and never changed. Measured: pi, launched as a bin, lost all 3210
+ * cells of its bundle to one `fs.promises` call and then failed reading its own
+ * `dist/modes/interactive/theme/dark.json`.
+ *
+ * Shared source rather than a line per body: the long-running node body and the
+ * staged-artifact body each hold a hand-written copy of the snapshot preamble,
+ * and neither gained this seed when the one-shot body did. That drift is the
+ * defect, and one definition every generator splices is what makes it
+ * unrepeatable.
+ *
+ * Splice it AFTER `__MODULE_VFS_CURSOR` is defined and BEFORE the shims: the
+ * shims read the cursor into a closure const as they evaluate, so an assignment
+ * that lands later replaces an object nothing still points at.
+ *
+ * Where `__MODULE_VFS_CURSOR` comes from is the generator's business, and for
+ * the two node bodies there is only one right answer: the invocation. Their
+ * generated text is content-addressed — the one-shot body is cached on
+ * hash(code + bundle + manifest), the resident body is stored as a facet image
+ * named by its own digest — and a cursor carries a revision that advances on
+ * every spawn and an epoch that belongs to one supervisor incarnation. Baked
+ * in, it gives the same program a new image each time and hands a shared body
+ * another session's epoch. So it rides the request body and the start payload
+ * respectively, the same channel argv and env want. The staged-artifact body
+ * is generated from a per-invocation spec that is not addressed by its bytes,
+ * so there it is simply one more field of that spec.
+ */
+export const VFS_CURSOR_SEED_SOURCE = `
+if (__MODULE_VFS_CURSOR) {
+  globalThis.__nimbusVfsCursor = {
+    epoch: __MODULE_VFS_CURSOR.epoch,
+    rev: __MODULE_VFS_CURSOR.rev,
+  };
+}
+`;
+/**
+ * The `__MODULE_VFS_CURSOR` literal for a generated facet body. `null` is a
+ * real answer — a facet built without a VFS has no state to be coherent with —
+ * and the seed above is a no-op for it.
+ */
+export function serializeFacetVfsCursor(cursor) {
+    return JSON.stringify(cursor ?? null);
+}