@markii/host 0.17.0-next.2 → 0.17.0-next.4

package/dist/node.d.ts

@@ -1,5 +1,5 @@
 export type { SpawnRunOptions } from './run/run-host.js';
-export { defaultWorkerPath, spawnRunInThread, workerThreadIsolate, } from './run/node-isolate.js';
+export type { NodeHostIsolateOptions } from './run/node-isolate.js';
+export { createNodeHostIsolate, workerThreadIsolate, } from './run/node-isolate.js';
 export { createNetProvider } from './run/net-provider.js';
-export { createNodeArchiveExtractFs, createNodeDirectoryLister, createNodeFileReader, createNodePackDiscoveryIo, createNodeReader as createNodePackScriptsReader, } from './node-fs.js';
-export { createHtmlExportEngine } from './html-engine.js';
+export { createNodeDirectoryLister, createNodeFileReader, createNodePackDiscoveryIo, createNodeReader as createNodePackScriptsReader, } from './node-fs.js';

package/dist/node.js

@@ -4,10 +4,11 @@
 // The main entry (`./index.ts`) is environment-neutral. This entry adds:
 // - the worker_threads isolate and the pinned network provider (`node:*`);
 // - the Node-backed file-system seams the neutral code takes by injection;
-// - the `@markii/html`-backed static export engine;
+//
+// The `@markii/html`-backed static export engine is its own entry,
+// `@markii/host/html-engine`, so importing this one needs no optional peer.
 //
 // A Node host imports from both entries. No browser bundle imports this one.
-export { defaultWorkerPath, spawnRunInThread, workerThreadIsolate, } from './run/node-isolate.js';
+export { createNodeHostIsolate, workerThreadIsolate, } from './run/node-isolate.js';
 export { createNetProvider } from './run/net-provider.js';
-export { createNodeArchiveExtractFs, createNodeDirectoryLister, createNodeFileReader, createNodePackDiscoveryIo, createNodeReader as createNodePackScriptsReader, } from './node-fs.js';
-export { createHtmlExportEngine } from './html-engine.js';
+export { createNodeDirectoryLister, createNodeFileReader, createNodePackDiscoveryIo, createNodeReader as createNodePackScriptsReader, } from './node-fs.js';

package/dist/packs/discover.d.ts

@@ -30,6 +30,8 @@ export interface DiscoveredPack {
     /** The configured folder this pack was discovered in (absolute path, as given). */
     readonly folder: string;
     readonly manifest: PackManifest;
+    /** The exact text of the pack's `pack.json`, as read. A compiled script registers this text unchanged. Discovery always sets it; it is absent only on a pack a host assembled by hand. */
+    readonly manifestText?: string;
     /** Local component name -> absolute path to its declared source file (`manifest.components[name]`, resolved against `folder`). Informational: what a host consumes them for (bundling, `import()`, or locating the pack's prebuilt registration script) is that host's own concern. */
     readonly componentPaths: Readonly<Record<string, string>>;
     /** Engine id -> (local component name -> absolute source path), for every engine any component declares a source for. `componentPaths` is the `react` slice of this. A terminal build (`ansi`) reads its slice here. */

package/dist/packs/discover.js

@@ -102,6 +102,7 @@ async function tryLoadPackAt(folder, readFile) {
         pack: {
             folder,
             manifest: result.manifest,
+            manifestText: text,
             componentPaths,
             componentPathsByEngine,
             scriptsDir: joinPath(folder, 'scripts'),
@@ -131,7 +132,7 @@ async function tryLoadPackAt(folder, readFile) {
  */
 /**
  * When a `ManifestAttempt` succeeded (`kind: 'found'`) but the manifest's
- * `engine` does not match `supportedEngine` (batch 7 #46), downgrades it to
+ * `engine` does not match `supportedEngine`, downgrades it to
  * a `SkippedPackFolder` instead of a `DiscoveredPack` — same effect
  * `@markii/react`'s `loadPack` already has for an unsupported engine
  * (nothing registered for that namespace, unknown-component fallback for

package/dist/packs/pack-diagnostics.d.ts

@@ -34,7 +34,7 @@ export interface PackDiagnosticsContext {
     /**
      * One entry per validated, non-colliding pack whose declared engine
      * `@markii/react`'s `loadPack` cannot run (`./pack-render-registry.ts`'s
-     * `BuildRenderRegistryResult.droppedEngines`, batch 7 #46). Omitted (or
+     * `BuildRenderRegistryResult.droppedEngines`). Omitted (or
      * empty) contributes nothing — the ordinary case where every registered
      * pack's engine is supported.
      */
@@ -62,13 +62,11 @@ export declare function skippedPackCount(context: {
 }): number;
 /**
  * One informational line for a pack whose prebuilt `webview.js` shadows
- * component sources still present in the same folder — survey finding A9:
- * `apps/vscode/src/packs/pack-diagnostics.ts` and
- * `apps/obsidian/src/packs/pack-diagnostics.ts` each defined this exact
- * sentence shape, differing only in the tail clause naming how a user
- * would rebuild the prebuilt artifact from those sources (VS Code's own
- * Export Pack command versus, from Obsidian, VS Code's Export Pack command
- * by name, since Obsidian has no build command of its own).
+ * component sources still present in the same folder.
+ * The tail clause names how a user would rebuild the prebuilt artifact
+ * from those sources: VS Code's own Export Pack command, or, from
+ * Obsidian, VS Code's Export Pack command by name, since Obsidian has no
+ * build command of its own.
  *
  * Never a failure: shipping both the built artifact and its sources is a
  * supported distribution shape. `rebuildInstruction` is the one thing that

package/dist/packs/pack-diagnostics.js

@@ -53,7 +53,7 @@ function duplicateComposedNameLines(context) {
     const duplicates = context.duplicateComposedNames ?? [];
     return duplicates.map((duplicate) => `Pack "${duplicate.skippedPack}"'s component composed to the directive name "${duplicate.composedName}", already claimed by pack "${duplicate.keptPack}"; the later component was skipped.`);
 }
-/** One line per pack dropped because this renderer cannot run its declared engine (batch 7 #46) — `[]` when there was none. */
+/** One line per pack dropped because this renderer cannot run its declared engine — `[]` when there was none. */
 function droppedEngineLines(context) {
     const dropped = context.droppedEngines ?? [];
     return dropped.map((entry) => `Pack "${entry.name}" declares engine "${entry.engine}", which this renderer cannot run; it installed with zero components (every directive under its namespace falls back to the unknown-component box).`);
@@ -87,13 +87,11 @@ export function skippedPackCount(context) {
 }
 /**
  * One informational line for a pack whose prebuilt `webview.js` shadows
- * component sources still present in the same folder — survey finding A9:
- * `apps/vscode/src/packs/pack-diagnostics.ts` and
- * `apps/obsidian/src/packs/pack-diagnostics.ts` each defined this exact
- * sentence shape, differing only in the tail clause naming how a user
- * would rebuild the prebuilt artifact from those sources (VS Code's own
- * Export Pack command versus, from Obsidian, VS Code's Export Pack command
- * by name, since Obsidian has no build command of its own).
+ * component sources still present in the same folder.
+ * The tail clause names how a user would rebuild the prebuilt artifact
+ * from those sources: VS Code's own Export Pack command, or, from
+ * Obsidian, VS Code's Export Pack command by name, since Obsidian has no
+ * build command of its own.
  *
  * Never a failure: shipping both the built artifact and its sources is a
  * supported distribution shape. `rebuildInstruction` is the one thing that

package/dist/packs/pack-paths.js

@@ -12,8 +12,7 @@
  * host concern — reading the setting itself, and naming what "relative"
  * means in a diagnostic message, stays in each host's own app code.
  *
- * DECISION (per orchestrator direction, carried over from the original VS
- * Code module this was hoisted from): a relative entry is resolved against
+ * DECISION: a relative entry is resolved against
  * `baseDir` as given by the caller; an absolute entry is used as-is. This
  * matches how a user reads the setting's own description: "this pack
  * folder, relative to my project/vault".

package/dist/packs/pack-render-registry.d.ts

@@ -1,21 +1,20 @@
 import type { PackManifest } from '@markii/pack';
-import type { Registry, RegistryEntry } from '@markii/react';
 /**
  * The renderer-specific half of building a pack-aware registry: the
  * renderer's own `loadPack`, `createRegistry` and `mergeRegistries`. A
  * React host passes `@markii/react`'s `reactPackEngine`; the host layer
  * itself names no renderer.
  */
-export interface PackRegistryEngine {
-    loadPack(manifest: PackManifest, componentModules: Record<string, RegistryEntry>): {
-        registry: Registry;
+export interface PackRegistryEngine<TRegistry extends object = object, TEntry = unknown> {
+    loadPack(manifest: PackManifest, componentModules: Record<string, TEntry>): {
+        registry: TRegistry;
         dropped?: {
             name: string;
             engine: string;
         };
     };
-    createRegistry(entries?: Record<string, RegistryEntry>): Registry;
-    mergeRegistries(...registries: Registry[]): Registry;
+    createRegistry(entries?: Record<string, TEntry>): TRegistry;
+    mergeRegistries(...registries: TRegistry[]): TRegistry;
 }
 /** One registration a compiled pack script queued by calling `window.__markiiRegisterPack(manifestJson, componentModules)` (see `./pack-build.ts`'s top doc comment for the full registration convention). Structurally identical across every host that satisfies the convention. */
 export interface QueuedPackRegistration {
@@ -42,8 +41,8 @@ export interface DuplicateComposedName {
     readonly skippedPack: string;
 }
 /** What `buildRenderRegistry` reports alongside the merged registry — developer-facing diagnostics for a caller to fold into its own surface, never shown as page content. */
-export interface BuildRenderRegistryResult {
-    readonly registry: Registry;
+export interface BuildRenderRegistryResult<TRegistry extends object = object> {
+    readonly registry: TRegistry;
     /** One line per malformed registration, dropped rather than installed. */
     readonly invalidReasons: readonly string[];
     /** Non-empty only when two or more validated registrations shared a namespace — the WHOLE install was then rejected (docs/packs.md's install-time rejection rule) and `registry` falls back to `defaultRegistry` alone. */
@@ -52,7 +51,7 @@ export interface BuildRenderRegistryResult {
     readonly duplicateComposedNames: readonly DuplicateComposedName[];
     /**
      * One entry per validated, non-colliding pack whose manifest declares an
-     * engine `@markii/react`'s `loadPack` cannot run (batch 7 #46). Before
+     * engine `@markii/react`'s `loadPack` cannot run. Before
      * this field existed, such a pack installed as an empty contribution
      * with no record anywhere that it had even been attempted — every
      * directive under its namespace fell through to the ordinary
@@ -80,4 +79,4 @@ export interface BuildRenderRegistryResult {
  *   (see `DuplicateComposedName`) drops only the later claimant's
  *   component, not the whole pack.
  */
-export declare function buildRenderRegistry(queued: readonly QueuedPackRegistration[], defaultRegistry: Registry, engine: PackRegistryEngine): BuildRenderRegistryResult;
+export declare function buildRenderRegistry<TRegistry extends object, TEntry>(queued: readonly QueuedPackRegistration[], defaultRegistry: TRegistry, engine: PackRegistryEngine<TRegistry, TEntry>): BuildRenderRegistryResult<TRegistry>;

package/dist/run/browser-isolate.d.ts

@@ -13,10 +13,10 @@
  * there is no `__dirname` inside a worker to find it beside the bundle.
  *
  * Network is served by the HOST, not the worker: `serveNetRequests` wires
- * every `markii:net-request` to the caller's own `NetProvider`, which is
- * the same pinned one a worker-thread isolate runs. The isolate has no
- * network stack of its own, so the allowlist cannot be bypassed from
- * inside it.
+ * every `markii:net-request` to the caller's own `NetProvider`. Lua cannot
+ * reach JavaScript, and the worker entry removes its own network globals
+ * before the first script runs (`./worker-entry-browser.ts`), so the
+ * provider's allowlist is the only path to the network.
  *
  * What this CANNOT do, stated plainly because it is a real difference: a
  * Web Worker takes no `maxOldGenerationSizeMb`, so `options`'s heap cap is
@@ -37,7 +37,7 @@ export interface BrowserIsolateOptions {
     /** Creates the worker. Injected so a test never needs a real one, and so a host can decide how it mints the URL. */
     createWorker: (entryPath: string) => WorkerLike;
     /** The host's own pinned provider. Every `net.*` call the script makes is answered by this, in the host, never in the isolate. */
-    netProvider: (netAllowlist: string[], maxFetchBytes: number, netPolicy: unknown) => NetProvider;
+    netProvider: (netAllowlist: string[], maxFetchBytes: number, netPolicy: unknown, signal?: AbortSignal) => NetProvider;
     /** Where the worker should fetch wasmoon's `glue.wasm`; sent along with the job. */
     wasmUri?: string;
 }

package/dist/run/browser-isolate.js

@@ -19,6 +19,9 @@ export function createBrowserIsolate(options) {
         const worker = options.createWorker(spawn.entryPath);
         let provider;
         let alive = true;
+        // Aborted by `kill()`: a request still in flight when the run ends is
+        // cancelled rather than left running in the host.
+        const requests = new AbortController();
         const messageListeners = [];
         const errorListeners = [];
         worker.addEventListener('message', (event) => {
@@ -52,7 +55,7 @@ export function createBrowserIsolate(options) {
         return {
             send: (job) => {
                 const { allowlist, maxFetchBytes, policy } = netArgsFrom(job);
-                provider = options.netProvider(allowlist, maxFetchBytes, policy);
+                provider = options.netProvider(allowlist, maxFetchBytes, policy, requests.signal);
                 worker.postMessage({
                     ...job,
                     ...(options.wasmUri !== undefined
@@ -64,6 +67,7 @@ export function createBrowserIsolate(options) {
                 if (!alive)
                     return;
                 alive = false;
+                requests.abort();
                 worker.terminate();
             },
             onMessage: (listener) => {

package/dist/run/isolate.d.ts

@@ -46,10 +46,12 @@ export interface RunIsolate {
     onExit(listener: (code: number | null) => void): void;
 }
 export interface SpawnIsolateOptions {
-    /** The entry the isolate loads — resolved by the host, never guessed here (see `./run-host.ts`'s `defaultWorkerPath`). */
+    /** The entry the isolate loads — resolved by the host, never guessed here (`createNodeHostIsolate` supplies the packaged one). */
     entryPath: string;
     /** Node `execArgv` for a worker-thread isolate; meaningless to a Web Worker, which ignores it. */
     execArgv?: string[];
+    /** Environment for a worker-thread isolate; a Web Worker ignores it. */
+    env?: Record<string, string | undefined>;
     /** V8 old-space cap in MB. A worker thread honors it; a Web Worker cannot, and says so in its own doc comment. */
     maxOldGenerationSizeMb: number;
 }

package/dist/run/net-bridge.d.ts

@@ -8,11 +8,11 @@
  * host to perform it, and the host, which still has Node, runs exactly the
  * same `createNetProvider` the worker-thread isolate always used.
  *
- * This is a security improvement, not a compromise. The allowlist and the
- * pinning policy now live somewhere the sandboxed code cannot reach at
- * all: an isolate with no network stack has nothing to bypass them with.
- * What the worker can do is ask, and every ask is answered by the host's
- * own provider, against the host's own allowlist.
+ * The allowlist and the pinning policy live somewhere the sandboxed code
+ * cannot reach: Lua has no path to JavaScript, and the worker entry removes
+ * its network globals after startup (`./worker-entry-browser.ts`). What the
+ * worker can do is ask, and every ask is answered by the host's own
+ * provider, against the host's own allowlist.
  *
  * This file is the protocol and the HOST half. The worker half lives in
  * `./net-bridge-worker.ts` because it needs `@markii/lua`'s denial brand,

package/dist/run/net-bridge.js

@@ -1,3 +1,4 @@
+import { isNetRefusal } from './net-refusal.js';
 export function isNetBridgeRequest(value) {
     if (typeof value !== 'object' || value === null)
         return false;
@@ -49,11 +50,12 @@ export async function serveNetRequest(request, provider, post) {
             id: request.id,
             ok: false,
             error: error instanceof Error ? error.message : String(error),
-            // Everything the host's provider refuses IS a policy denial: the
-            // provider's own failures are allowlist, redirect, size, and pinning
-            // refusals. Marking them so keeps the worker's classification
-            // identical to the in-worker case.
-            denied: true,
+            // A policy refusal (allowlist, redirect, size, address range) is
+            // marked by the provider and crosses as a denial, so the worker
+            // classifies it exactly as it would in-worker. A transport failure
+            // (DNS, connection, timeout, abort) is unmarked and crosses as an
+            // ordinary failure with its reason. Both reach the script as errors.
+            denied: isNetRefusal(error),
         });
     }
 }

package/dist/run/net-pinning.d.ts

@@ -40,6 +40,8 @@ export type PinResult = {
 } | {
     ok: false;
     reason: string;
+    /** `unresolved`: the name did not resolve (a transport failure). `refused`: the address policy refused it. */
+    kind: 'unresolved' | 'refused';
 };
 export interface PinPolicy {
     /**

package/dist/run/net-pinning.js

@@ -79,29 +79,43 @@ export async function pinHostAddress(hostname, policy, lookup) {
     catch {
         // Deliberately not the resolver's own message: it varies by platform and
         // says nothing a note's author can act on.
-        return { ok: false, reason: `host "${hostname}" could not be resolved` };
+        return {
+            ok: false,
+            kind: 'unresolved',
+            reason: `host "${hostname}" could not be resolved`,
+        };
     }
     if (addresses.length === 0) {
-        return { ok: false, reason: `host "${hostname}" resolved to no address` };
+        return {
+            ok: false,
+            kind: 'unresolved',
+            reason: `host "${hostname}" resolved to no address`,
+        };
     }
     for (const candidate of addresses) {
         const scope = classifyIpAddress(candidate.address);
         if (scope === undefined) {
             return {
                 ok: false,
+                kind: 'refused',
                 reason: `host "${hostname}" resolved to an unusable address`,
             };
         }
         if (isRestrictedScope(scope) && !policy.allowRestrictedAddresses) {
             return {
                 ok: false,
+                kind: 'refused',
                 reason: `host "${hostname}" resolves to ${describeScope(scope)}`,
             };
         }
     }
     const chosen = addresses[0];
     if (chosen === undefined) {
-        return { ok: false, reason: `host "${hostname}" resolved to no address` };
+        return {
+            ok: false,
+            kind: 'unresolved',
+            reason: `host "${hostname}" resolved to no address`,
+        };
     }
     const scope = classifyIpAddress(chosen.address) ?? 'reserved';
     return {

package/dist/run/net-provider.d.ts

@@ -59,7 +59,9 @@ export declare function createNetProvider(allowlist: readonly string[], maxFetch
  * host marks every refusal on the wire (`./net-bridge.ts`'s `denied`
  * flag) and the worker rebuilds a properly branded error on arrival.
  */
-denial: (message: string) => Error, lookup?: HostLookup): NetProvider;
+denial: (message: string) => Error, lookup?: HostLookup, 
+/** Aborted when the run ends: an in-flight request is destroyed and no further hop is made. */
+signal?: AbortSignal): NetProvider;
 /**
  * An in-memory `CacheProvider` (`@markii/lua`) seeded from `snapshot` at
  * construction and readable back out afterward via `.snapshot()` — the

package/dist/run/net-provider.js

@@ -14,13 +14,14 @@
  * import from `@markii/lua` — the brand that marks a policy refusal — is
  * injected as `denial` instead. Types are `import type` and erase.
  *
- * The security properties are unchanged by the move, and one improves: an
- * isolate that has no network stack cannot bypass the allowlist enforced
- * here, because it has nothing to bypass it with.
+ * A Web Worker isolate asks this provider through the net bridge. The
+ * worker entry removes its own network globals after startup, so the
+ * allowlist enforced here is the only path to the network.
  */
 import * as http from 'node:http';
 import * as https from 'node:https';
 import * as dns from 'node:dns';
+import { netRefusal } from './net-refusal.js';
 import { pinHostAddress, pinnedLookup, } from './net-pinning.js';
 function describeThrown(err) {
     return err instanceof Error ? err.message : String(err);
@@ -80,7 +81,7 @@ function bareHostname(hostname) {
  */
 function issueRequest(url, method, body, pinned, maxFetchBytes, 
 /** See `createNetProvider`'s own `denial` parameter — injected for the same reason. */
-denial) {
+denial, signal) {
     return new Promise((resolve, reject) => {
         const mod = url.protocol === 'https:' ? https : http;
         const bodyBuffer = body !== undefined ? Buffer.from(body, 'utf8') : undefined;
@@ -161,8 +162,20 @@ denial) {
             res.on('error', (err) => settleReject(err));
         });
         req.on('error', (err) => {
-            settleReject(denial(`request failed: ${describeThrown(err)}`));
+            // A transport failure (connection refused, reset, timeout): an
+            // ordinary runtime failure with the reason, not a policy refusal.
+            settleReject(new Error(`request failed: ${describeThrown(err)}`));
         });
+        if (signal !== undefined) {
+            const onAbort = () => {
+                req.destroy();
+                settleReject(new Error('the run has ended'));
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
         if (bodyBuffer)
             req.write(bodyBuffer);
         req.end();
@@ -227,8 +240,14 @@ export function createNetProvider(allowlist, maxFetchBytes, policy,
  * host marks every refusal on the wire (`./net-bridge.ts`'s `denied`
  * flag) and the worker rebuilds a properly branded error on arrival.
  */
-denial, lookup = defaultHostLookup) {
+denial, lookup = defaultHostLookup, 
+/** Aborted when the run ends: an in-flight request is destroyed and no further hop is made. */
+signal) {
     const allowed = new Set(allowlist.map((host) => host.toLowerCase()));
+    // Every policy refusal is built by the injected `denial` and then marked,
+    // so the net bridge can tell it from a transport failure without importing
+    // the Lua runtime. A transport failure is a plain `Error`.
+    const refuse = (message) => netRefusal(denial(message));
     async function fetchAllowed(startUrl, method, body) {
         let currentUrl = startUrl;
         for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
@@ -237,41 +256,47 @@ denial, lookup = defaultHostLookup) {
                 parsed = new URL(currentUrl);
             }
             catch {
-                throw denial(`"${currentUrl}" is not a valid URL`);
+                throw refuse(`"${currentUrl}" is not a valid URL`);
             }
             if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-                throw denial(`scheme "${parsed.protocol}" is not allowed`);
+                throw refuse(`scheme "${parsed.protocol}" is not allowed`);
             }
             // N-4: a URL carrying credentials is refused outright, on every hop.
             if (parsed.username !== '' || parsed.password !== '') {
-                throw denial(`URL "${currentUrl}" embeds credentials, which is not allowed`);
+                throw refuse(`URL "${currentUrl}" embeds credentials, which is not allowed`);
             }
+            if (signal?.aborted)
+                throw new Error('the run has ended');
             const host = parsed.hostname.toLowerCase();
             if (!allowed.has(host)) {
-                throw denial(`host "${host}" is not on the run's allowlist`);
+                throw refuse(`host "${host}" is not on the run's allowlist`);
             }
             // Issue #10: resolve-then-pin, closing the DNS-rebinding / private-
             // range SSRF gap a hostname allowlist alone cannot see.
             const pinResult = await pinHostAddress(host, policy, lookup);
             if (!pinResult.ok) {
-                throw denial(pinResult.reason);
+                // A name that does not resolve is a transport failure; an address
+                // the policy refuses is a policy refusal.
+                throw pinResult.kind === 'unresolved'
+                    ? new Error(pinResult.reason)
+                    : refuse(pinResult.reason);
             }
-            const response = await issueRequest(parsed, method, body, pinResult.pinned, maxFetchBytes, denial);
+            const response = await issueRequest(parsed, method, body, pinResult.pinned, maxFetchBytes, refuse, signal);
             if (response.status >= 300 && response.status < 400) {
                 if (!response.location) {
-                    throw denial('redirect response carried no Location header');
+                    throw refuse('redirect response carried no Location header');
                 }
                 try {
                     currentUrl = new URL(response.location, currentUrl).toString();
                 }
                 catch {
-                    throw denial('redirect response carried an unparseable Location header');
+                    throw refuse('redirect response carried an unparseable Location header');
                 }
                 continue;
             }
             return { status: response.status, body: response.body };
         }
-        throw denial(`exceeded ${MAX_REDIRECTS} redirects`);
+        throw refuse(`exceeded ${MAX_REDIRECTS} redirects`);
     }
     return {
         get: (url) => fetchAllowed(url, 'GET', undefined),

package/dist/run/net-refusal.d.ts

@@ -0,0 +1,4 @@
+/** Returns `error` marked as a policy refusal. A network provider throws one for every request it refuses on policy grounds. */
+export declare function netRefusal(error: Error): Error;
+/** True when `error` was marked by {@link netRefusal}. */
+export declare function isNetRefusal(error: unknown): boolean;

package/dist/run/net-refusal.js

@@ -0,0 +1,24 @@
+/**
+ * Marks an `Error` as a network POLICY refusal (an unlisted host, a refused
+ * address range, an over-size body) as opposed to a transport failure (DNS,
+ * connection, timeout, abort).
+ *
+ * The brand is a global `Symbol.for` key on the error object, so it needs no
+ * runtime import and survives being created in one bundle and read in
+ * another. The net bridge reads it to decide whether a failure crosses to
+ * the worker as a capability denial or as an ordinary runtime failure. A
+ * refusal is always an error: a script can never read one as a success.
+ *
+ * It is a plain property, not a classification the Lua side trusts: the
+ * worker rebuilds its own branded denial from the `denied` flag on the wire.
+ */
+const NET_REFUSAL = Symbol.for('markii.net.refusal');
+/** Returns `error` marked as a policy refusal. A network provider throws one for every request it refuses on policy grounds. */
+export function netRefusal(error) {
+    return Object.assign(error, { [NET_REFUSAL]: true });
+}
+/** True when `error` was marked by {@link netRefusal}. */
+export function isNetRefusal(error) {
+    return (error instanceof Error &&
+        error[NET_REFUSAL] === true);
+}

package/dist/run/node-isolate.d.ts

@@ -1,30 +1,22 @@
+import type { HostIsolate } from '../host/adapter.js';
 import type { IsolateSpawner } from './isolate.js';
-import type { SpawnRunOptions } from './run-host.js';
-import type { RunResult } from './worker-entry.js';
-/**
- * The ONLY fallback this shared package supplies for an unset `workerPath`:
- * the sibling `worker-entry.ts`, run straight from source via `tsx`
- * (`TSX_DEV_EXEC_ARGV`, above). That is correct for this package's own
- * dev/Vitest runs — `__dirname` at that point is this real source
- * directory — but it says nothing about where a packaged host's bundled
- * worker lives, because this package does not know that host's `dist/`
- * layout. A packaged host (e.g. `apps/vscode`) MUST resolve its own bundled
- * worker path itself and pass it as `SpawnRunOptions.workerPath`; see
- * `apps/vscode/src/worker-path.ts` for that host's resolution and
- * `apps/vscode/esbuild.config.mjs`'s worker build for where it bundles to.
- */
-export declare function defaultWorkerPath(): string;
 /**
  * The default isolate: a `node:worker_threads` worker, which is what every
- * Node host (the VS Code extension host, this package's own tests) uses. It
- * is the only kind that accepts `resourceLimits`, so it is also the only
+ * Node host uses. It is the only kind that accepts `resourceLimits`, so it is also the only
  * kind whose V8 heap is bounded — see `./isolate.ts` for why a host might
  * still have to supply the other one.
  */
 export declare const workerThreadIsolate: IsolateSpawner;
+export interface NodeHostIsolateOptions {
+    /** The worker entry on disk. Defaults to `node-worker.js` in the package's `dist/`. */
+    workerPath?: string;
+}
 /**
- * `spawnRun` with the Node defaults filled in: the worker-thread isolate and
- * the dev/Vitest worker entry. For this package's own tests and any Node
- * caller that wants them; a packaged host passes its own `workerPath`.
+ * A `HostIsolate` of kind `node`: each run starts a `worker_threads` worker
+ * from the packaged, self-contained `node-worker.js`. A host that bundles
+ * the worker itself passes its own `workerPath`. The default is resolved
+ * when a run asks for it, so constructing the isolate never throws.
  */
-export declare function spawnRunInThread(options: Omit<SpawnRunOptions, 'spawnIsolate' | 'workerPath'> & Partial<Pick<SpawnRunOptions, 'spawnIsolate' | 'workerPath'>>): Promise<RunResult>;
+export declare function createNodeHostIsolate(options?: NodeHostIsolateOptions): Extract<HostIsolate, {
+    kind: 'node';
+}>;