@cogenta/plugins 0.1.0

package/dist/guest/sandbox-entry.mjs

@@ -0,0 +1,155 @@
+// Hand-written plain JS, not compiled from TypeScript — this file is loaded
+// directly by `node:worker_threads`' `Worker` constructor, which reads it as
+// real Node-executable JS with no build step involved (the same reasoning
+// `create-cogenta`'s scaffolded `cogenta.config.mjs` is hand-written rather
+// than routed through a TS-to-JS build: this file must run as-is, before any
+// bundler or `tsc` output exists during `vitest` runs against `src/`).
+//
+// This is the ENTIRE trusted surface a plugin's code runs against. It does
+// three things, and nothing else:
+//   1. Creates a fresh `vm` context whose global object has no `process`, no
+//      `require`, no `fs`/`net`, and no dynamic `import()` — a plugin cannot
+//      reach any of these because they were never put there, not because
+//      they were removed after being present.
+//   2. Runs the plugin's code as a classic (non-module) `vm.Script` inside
+//      that context, with `codeGeneration: { strings: false }` — this is a
+//      real, documented V8/Node guarantee that blocks `eval()`/`new
+//      Function(...)`, closing the most common "climb the prototype chain to
+//      reach the real Function constructor" vm-escape technique.
+//   3. Reports the outcome back over `parentPort`, JSON-round-tripped so no
+//      live object (a function, a class instance, a Proxy) can leak out.
+//
+// Honest limitation, stated plainly rather than oversold: Node's own docs
+// are explicit that `vm` is not a hardened security boundary against a
+// sufficiently determined co-located attacker on its own — it is one layer.
+// The real isolation here is the COMBINATION of this vm sandbox (blocks the
+// Node API surface) running inside a separate `worker_threads` thread
+// spawned with `env: {}` (blocks secrets/environment access structurally,
+// not by convention) and bounded `resourceLimits` + a host-side timeout
+// (blocks resource exhaustion). No single layer is claimed to be sufficient
+// alone.
+
+import vm from 'node:vm'
+import { parentPort } from 'node:worker_threads'
+
+if (!parentPort) {
+  throw new Error('sandbox-entry.mjs must run inside a worker_threads Worker')
+}
+
+/** JSON round-trip strips functions/symbols/live references — nothing but plain data survives. */
+function toSerializable(value) {
+  if (value === undefined) return null
+  try {
+    return JSON.parse(JSON.stringify(value))
+  } catch {
+    return null
+  }
+}
+
+let nextCallId = 1
+/** Pending SDK calls this sandbox is waiting on a host reply for, keyed by `callId`. */
+const pendingSdkCalls = new Map()
+
+/**
+ * One real RPC method, bound to a specific capability name. Calling it posts
+ * a `sdk-call` message to the host and returns a Promise that resolves or
+ * rejects when the matching `sdk-result`/`sdk-error` arrives — the host
+ * re-verifies the request against what was actually granted before ever
+ * executing it (`./host/capabilities.js`).
+ */
+function makeSdkMethod(method) {
+  return (args) =>
+    new Promise((resolve, reject) => {
+      const callId = nextCallId
+      nextCallId += 1
+      pendingSdkCalls.set(callId, { resolve, reject })
+      parentPort.postMessage({ type: 'sdk-call', callId, method, args })
+    })
+}
+
+/**
+ * Builds the plugin-visible `sdk` object from exactly the capability strings
+ * the host says were granted — task 4/5's central, testable property:
+ * "toute méthode non accordée est absente de l'objet, pas présente et
+ * refusée : absente." A namespace or method whose capability was never
+ * granted is never assigned onto `sdk` at all, so `'read' in sdk.content`
+ * is `false`, not a present method that throws when called.
+ */
+function buildSdk(grantedCapabilities) {
+  const sdk = {}
+  for (const capability of grantedCapabilities) {
+    const separatorIndex = capability.indexOf(':')
+    const name = separatorIndex === -1 ? capability : capability.slice(0, separatorIndex)
+    const dotIndex = name.indexOf('.')
+    if (dotIndex === -1) continue
+    const namespace = name.slice(0, dotIndex)
+    const method = name.slice(dotIndex + 1)
+    if (sdk[namespace] === undefined) sdk[namespace] = {}
+    if (sdk[namespace][method] === undefined) sdk[namespace][method] = makeSdkMethod(name)
+  }
+  return sdk
+}
+
+function buildSandbox(grantedCapabilities) {
+  // Deliberately minimal. No `process`, no `require`, no `fetch`, no
+  // `Buffer`, no `fs`/`net` — only `sdk`, and only the namespaces/methods
+  // `grantedCapabilities` actually names.
+  return {
+    console,
+    Math,
+    JSON,
+    Promise,
+    setTimeout,
+    clearTimeout,
+    sdk: buildSdk(grantedCapabilities),
+  }
+}
+
+parentPort.on('message', (message) => {
+  if (message == null) return
+
+  // A reply to a pending SDK call — resolve/reject its Promise and let the
+  // sandbox's own `await` resume; this is not a new `run` request.
+  if (message.type === 'sdk-result' || message.type === 'sdk-error') {
+    const pending = pendingSdkCalls.get(message.callId)
+    if (pending === undefined) return
+    pendingSdkCalls.delete(message.callId)
+    if (message.type === 'sdk-result') pending.resolve(message.value)
+    else pending.reject(new Error(message.message))
+    return
+  }
+
+  if (message.type !== 'run') return
+  const { id, code, grantedCapabilities } = message
+
+  // Fire-and-report, not awaited by the message handler itself: plugin code
+  // may be a top-level `async () => {...}()` (e.g. to `await import(...)`
+  // and observe the rejection a blocked dynamic import produces) — its
+  // returned Promise is awaited here before the result is serialized.
+  void (async () => {
+    let result
+    try {
+      const context = vm.createContext(buildSandbox(grantedCapabilities ?? []), {
+        codeGeneration: { strings: false, wasm: false },
+      })
+      const script = new vm.Script(code, { filename: 'plugin.js' })
+      // A second, independent time bound on top of the host's own
+      // worker.terminate() timeout — this one stops a synchronous infinite
+      // loop from inside the same thread, which a host-side terminate() can
+      // be slow to land on under heavy CPU contention.
+      const rawValue = script.runInContext(context, { timeout: 5000 })
+      const value =
+        rawValue !== null && typeof rawValue === 'object' && typeof rawValue.then === 'function'
+          ? await rawValue
+          : rawValue
+      result = { id, type: 'result', value: toSerializable(value) }
+    } catch (error) {
+      result = {
+        id,
+        type: 'error',
+        message: error instanceof Error ? error.message : String(error),
+      }
+    }
+    parentPort.postMessage(result)
+  })()
+})

package/dist/host/capabilities.d.ts

@@ -0,0 +1,46 @@
+import type { StorageDriver } from '@cogenta/core';
+/**
+ * Host-side implementations of the SDK methods a sandboxed plugin can call.
+ * "Commencer minimal" (docs/lots/L7-extensibilite.md § Pièges connus) — this
+ * is a deliberately small starter set: `content.read`, `http.fetch`,
+ * `storage.read`/`storage.write`. Task 5 owns turning a real permission grant
+ * into the `grantedCapabilities` list these handlers re-verify against; this
+ * file owns what each capability actually DOES once granted.
+ *
+ * Every handler re-checks the SPECIFIC request against the SPECIFIC granted
+ * capability parameter (the exact domain, the exact storage prefix) — never
+ * just "was this capability name granted at all." The manifest schema
+ * (task 1) already validates that a declared capability's parameter is
+ * well-formed (a real hostname, a prefix confined to the plugin's own
+ * namespace), but a well-formed *declaration* says nothing about what the
+ * *specific call a plugin makes at runtime* asks for — a plugin granted
+ * `http.fetch:api.example.com` could still ask its own SDK method to fetch
+ * `evil.example.com`, and only a host-side re-check of the actual request
+ * against the actual granted parameter closes that gap.
+ */
+export interface CapabilityCallContext {
+    /** The full manifest-shaped capability strings actually granted, e.g. `["http.fetch:api.example.com"]`. */
+    readonly grantedCapabilities: readonly string[];
+}
+export type CapabilityHandler = (args: unknown, context: CapabilityCallContext) => Promise<unknown>;
+/**
+ * `content.read` — read-only, via whatever real content-read function the
+ * host provides (typically `ContentStore.read`, `@cogenta/schema`) for a
+ * single, specific collection this plugin instance is scoped to. No
+ * per-call re-verification beyond capability presence: `content.read` is
+ * bare (task 1 never parameterizes it per-collection), so the host, not
+ * this handler, is what decides which collection's store gets wired in.
+ */
+export declare function createContentReadHandler(readEntry: (id: string) => Promise<unknown>): CapabilityHandler;
+/**
+ * `http.fetch:<domain>` — the requested URL's hostname must exactly match
+ * one of the domains actually granted, re-checked here against the real
+ * request, not merely against the fact that *some* `http.fetch` capability
+ * exists.
+ */
+export declare function createHttpFetchHandler(fetchImpl?: typeof fetch): CapabilityHandler;
+/** `storage.read:<prefix>` — the requested key must fall within a granted prefix, re-verified per call. */
+export declare function createStorageReadHandler(driver: StorageDriver): CapabilityHandler;
+/** `storage.write:<prefix>` — same per-call prefix re-verification as `storage.read`. */
+export declare function createStorageWriteHandler(driver: StorageDriver): CapabilityHandler;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/host/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/host/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAGlD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,2GAA2G;IAC3G,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAA;CAChD;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AA6BnG;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC1C,iBAAiB,CAQnB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,GAAE,OAAO,KAAa,GAAG,iBAAiB,CAYzF;AAgBD,2GAA2G;AAC3G,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAejF;AAED,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAYlF"}

package/dist/host/capabilities.js

@@ -0,0 +1,105 @@
+import { CogentaError } from '@cogenta/core';
+/** Parameters (the part after `:`) granted for a given bare capability name. */
+function grantedParameters(name, context) {
+    const prefix = `${name}:`;
+    return context.grantedCapabilities
+        .filter((capability) => capability.startsWith(prefix))
+        .map((capability) => capability.slice(prefix.length));
+}
+function refused(message) {
+    throw new CogentaError({
+        code: 'PLUGIN_CAPABILITY_REFUSED',
+        message,
+        hint: 'The plugin requested something its granted capabilities do not cover.',
+    });
+}
+function asRecord(value) {
+    if (value === null || typeof value !== 'object')
+        refused('expected an object argument');
+    return value;
+}
+function asString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '')
+        refused(`"${field}" must be a non-empty string`);
+    return value;
+}
+/**
+ * `content.read` — read-only, via whatever real content-read function the
+ * host provides (typically `ContentStore.read`, `@cogenta/schema`) for a
+ * single, specific collection this plugin instance is scoped to. No
+ * per-call re-verification beyond capability presence: `content.read` is
+ * bare (task 1 never parameterizes it per-collection), so the host, not
+ * this handler, is what decides which collection's store gets wired in.
+ */
+export function createContentReadHandler(readEntry) {
+    return async (args, context) => {
+        if (!context.grantedCapabilities.includes('content.read')) {
+            refused('"content.read" was not granted');
+        }
+        const id = asString(asRecord(args).id, 'id');
+        return await readEntry(id);
+    };
+}
+/**
+ * `http.fetch:<domain>` — the requested URL's hostname must exactly match
+ * one of the domains actually granted, re-checked here against the real
+ * request, not merely against the fact that *some* `http.fetch` capability
+ * exists.
+ */
+export function createHttpFetchHandler(fetchImpl = fetch) {
+    return async (args, context) => {
+        const url = asString(asRecord(args).url, 'url');
+        const allowedDomains = grantedParameters('http.fetch', context);
+        const hostname = new URL(url).hostname;
+        if (!allowedDomains.includes(hostname)) {
+            refused(`"http.fetch" was not granted for domain "${hostname}"`);
+        }
+        const response = await fetchImpl(url);
+        const body = await response.text();
+        return { status: response.status, body };
+    };
+}
+function isWithinGrantedPrefix(path, prefixes) {
+    return prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+/** Refuses any request whose normalised path escapes what the granted prefix set allows — closes `../` traversal. */
+function normalisedStorageKey(rawKey) {
+    const key = asString(rawKey, 'key');
+    const segments = key.split('/');
+    if (segments.some((segment) => segment === '..' || segment === '.')) {
+        refused(`storage key "${key}" must not contain "." or ".." segments`);
+    }
+    return key;
+}
+/** `storage.read:<prefix>` — the requested key must fall within a granted prefix, re-verified per call. */
+export function createStorageReadHandler(driver) {
+    return async (args, context) => {
+        const record = asRecord(args);
+        const key = normalisedStorageKey(asString(record.key, 'key'));
+        const allowedPrefixes = grantedParameters('storage.read', context);
+        if (!isWithinGrantedPrefix(key, allowedPrefixes)) {
+            refused(`"storage.read" was not granted for key "${key}"`);
+        }
+        const readable = await driver.get(key);
+        const chunks = [];
+        for await (const chunk of readable) {
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    };
+}
+/** `storage.write:<prefix>` — same per-call prefix re-verification as `storage.read`. */
+export function createStorageWriteHandler(driver) {
+    return async (args, context) => {
+        const record = asRecord(args);
+        const key = normalisedStorageKey(asString(record.key, 'key'));
+        const content = asString(record.content, 'content');
+        const allowedPrefixes = grantedParameters('storage.write', context);
+        if (!isWithinGrantedPrefix(key, allowedPrefixes)) {
+            refused(`"storage.write" was not granted for key "${key}"`);
+        }
+        await driver.put(key, Buffer.from(content, 'utf8'));
+        return { ok: true };
+    };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/host/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/host/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/host/protocol.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The real, serialized message protocol between the host and an isolated
+ * plugin worker. Every field here must survive `worker_threads`' structured
+ * clone — no live objects, no functions, no class instances ever cross this
+ * boundary ("communication par messages sérialisés. Aucun objet vivant du
+ * noyau ne traverse la frontière" — docs/lots/L7-extensibilite.md §
+ * Isolation).
+ */
+/**
+ * Host → worker: evaluate `code` inside the sandbox and report the result.
+ * `grantedCapabilities` (task 1's manifest capability strings, e.g.
+ * `"http.fetch:api.example.com"`) is what the guest-side sandbox uses to
+ * decide which SDK methods to construct — task 4's "absent, not refused"
+ * property is enforced entirely by which keys this list causes to exist on
+ * the sandbox's `sdk` object, never by a present-but-guarded method.
+ */
+export interface WorkerRunMessage {
+    readonly id: number;
+    readonly type: 'run';
+    readonly code: string;
+    readonly grantedCapabilities: readonly string[];
+}
+/** Worker → host: the plugin's sandboxed code is calling an SDK method — a real capability request, not yet executed. */
+export interface WorkerSdkCallMessage {
+    readonly type: 'sdk-call';
+    readonly callId: number;
+    /** The capability name the requested method belongs to, e.g. `"content.read"`, `"http.fetch"`. */
+    readonly method: string;
+    readonly args: unknown;
+}
+export type WorkerHostMessage = WorkerRunMessage;
+/** Host → worker: the SDK call succeeded — a JSON-safe value only, same "no live object crosses the boundary" rule as every other message here. */
+export interface WorkerSdkResultMessage {
+    readonly type: 'sdk-result';
+    readonly callId: number;
+    readonly value: unknown;
+}
+/** Host → worker: the SDK call was refused or failed — re-verified host-side, never trusted from the manifest alone. */
+export interface WorkerSdkErrorMessage {
+    readonly type: 'sdk-error';
+    readonly callId: number;
+    readonly message: string;
+}
+export type WorkerHostReplyMessage = WorkerSdkResultMessage | WorkerSdkErrorMessage;
+/** Worker → host: `code` completed and returned a JSON-safe value. */
+export interface WorkerResultMessage {
+    readonly id: number;
+    readonly type: 'result';
+    readonly value: unknown;
+}
+/** Worker → host: `code` threw, or the sandbox itself refused to run it. */
+export interface WorkerErrorMessage {
+    readonly id: number;
+    readonly type: 'error';
+    readonly message: string;
+}
+export type WorkerGuestMessage = WorkerResultMessage | WorkerErrorMessage | WorkerSdkCallMessage;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/host/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/host/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAA;CAChD;AAED,yHAAyH;AACzH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,CAAA;AAEhD,mJAAmJ;AACnJ,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,wHAAwH;AACxH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,MAAM,sBAAsB,GAAG,sBAAsB,GAAG,qBAAqB,CAAA;AAEnF,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,oBAAoB,CAAA"}

package/dist/host/protocol.js

@@ -0,0 +1,10 @@
+/**
+ * The real, serialized message protocol between the host and an isolated
+ * plugin worker. Every field here must survive `worker_threads`' structured
+ * clone — no live objects, no functions, no class instances ever cross this
+ * boundary ("communication par messages sérialisés. Aucun objet vivant du
+ * noyau ne traverse la frontière" — docs/lots/L7-extensibilite.md §
+ * Isolation).
+ */
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/host/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/host/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/host/worker-runner.d.ts

@@ -0,0 +1,92 @@
+import type { PluginManifest } from '../manifest.js';
+import type { PluginDisableStore, PluginViolationReason } from '../permissions/disabled.js';
+import type { PluginGrant } from '../permissions/grants.js';
+import type { CapabilityHandler } from './capabilities.js';
+export interface RunIsolatedOptions {
+    /** Killed and reported as a timeout past this — the basic kill switch this task's tests need. */
+    readonly timeoutMs?: number;
+    /** Real V8 heap ceiling for the worker's old-generation heap. */
+    readonly maxOldGenerationSizeMb?: number;
+    /**
+     * Task 1's manifest capability strings actually granted to this run, e.g.
+     * `["content.read", "http.fetch:api.example.com"]`. The guest-side sandbox
+     * uses this to decide which SDK methods to construct at all — an absent
+     * capability means an absent key on `sdk`, never a present-but-refusing
+     * method (docs/lots/L7-extensibilite.md § Isolation, and the explicit
+     * acceptance criterion "une méthode non accordée est absente de l'objet
+     * SDK, pas seulement refusée").
+     */
+    readonly grantedCapabilities?: readonly string[];
+    /**
+     * Real host-side implementations for each granted capability's SDK
+     * method, keyed by capability name (`"content.read"`, `"http.fetch"`,
+     * `"storage.read"`, `"storage.write"`, ...). Task 4's real deliverable —
+     * see `./capabilities.js`. A capability granted but with no matching
+     * handler here is a host misconfiguration, not a security gap: the guest
+     * sandbox still won't expose a method for it unless BOTH `grantedCapabilities`
+     * names it AND a handler exists.
+     */
+    readonly handlers?: Readonly<Record<string, CapabilityHandler>>;
+}
+export interface IsolatedRunResult {
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly error?: string;
+    /**
+     * Set only when `ok` is `false` — classifies WHY the worker failed, so a
+     * caller (task 6's disable policy) can tell "the plugin's own code threw a
+     * normal error" apart from "it exceeded its time or memory budget", which
+     * is the distinction "tué et désactivé" hinges on. `'crash'` covers any
+     * other non-zero exit that isn't recognizably a timeout or a heap-limit
+     * violation (e.g. a native worker fault) — still real grounds to disable,
+     * just not one of the two named-and-required policies.
+     */
+    readonly reason?: PluginViolationReason;
+}
+/**
+ * Runs `code` inside a fresh, isolated worker and reports the outcome.
+ * `code` is a classic (non-module) script body — the sandbox's real,
+ * documented restriction, not an accident: `vm.Script` without an
+ * `importModuleDynamically` callback refuses `import()`, and no `require`
+ * is ever injected into the sandbox, which is exactly what stops a plugin
+ * from reaching `node:fs`/`node:net` no matter which syntax it tries.
+ *
+ * A fresh `Worker` per call, not a pool — task 6 decides whether a
+ * long-lived, reusable worker (with the resource/time policy it owns) is
+ * worth the complexity; this task only needs a real, working isolation
+ * primitive to build on.
+ */
+export declare function runIsolated(code: string, options?: RunIsolatedOptions): Promise<IsolatedRunResult>;
+/** Emitted once, synchronously, the moment a plugin is disabled — never a hard dependency on any specific notification transport (channels, email, ...); wiring this to a real alert is an integration decision for whatever assembles a site, not this package's job. */
+export interface PluginDisabledEvent {
+    readonly pluginName: string;
+    readonly reason: PluginViolationReason;
+    readonly at: string;
+    readonly details?: string;
+}
+export interface RunPluginOptions extends Omit<RunIsolatedOptions, 'grantedCapabilities'> {
+    /** Task 6's real, persisted "is this plugin currently disabled" gate — required, not optional, since a caller with no store to check against cannot honestly claim to enforce "tué et désactivé". */
+    readonly disableStore: PluginDisableStore;
+    /** Fired synchronously right after a violation is recorded — the real "avec alerte" half of "tué et désactivé, avec alerte". */
+    readonly onPluginDisabled?: (event: PluginDisabledEvent) => void;
+}
+/**
+ * The real entry point for actually running a resolved plugin — unlike
+ * `runIsolated`, which task 4 left accepting an externally-decided
+ * `grantedCapabilities` list as a placeholder, this computes that list
+ * itself via `resolveGrantedCapabilities` (task 5) from the plugin's real
+ * manifest and its real, persisted grants. A caller cannot bypass grant
+ * resolution by simply passing whatever capability list it wants — the only
+ * way a capability reaches the sandbox is a real row in the grant store.
+ *
+ * Task 6 adds the other two real gates the lot demands: a disabled plugin is
+ * refused BEFORE a worker is ever spawned (`PLUGIN_DISABLED`, not a silent
+ * no-op), and a timeout or memory-limit violation disables the plugin for
+ * every future run, not just the one that failed — "il ne peut pas faire
+ * tomber le CMS" is the isolation boundary's job (task 3); making sure it
+ * cannot even try again unsupervised is this task's.
+ */
+export declare function runPlugin(manifest: PluginManifest, code: string, grants: readonly PluginGrant[], options: RunPluginOptions): Promise<IsolatedRunResult>;
+/** Throws instead of returning a discriminated failure — for call sites that want a plain success value or a real error. */
+export declare function runIsolatedOrThrow(code: string, options?: RunIsolatedOptions): Promise<unknown>;
+//# sourceMappingURL=worker-runner.d.ts.map

package/dist/host/worker-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-runner.d.ts","sourceRoot":"","sources":["../../src/host/worker-runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAyB1D,MAAM,WAAW,kBAAkB;IACjC,iGAAiG;IACjG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAA;CAChE;AAKD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAA;CACxC;AAsDD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAsE5B;AAED,0QAA0Q;AAC1Q,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,qBAAqB,CAAC;IACvF,qMAAqM;IACrM,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;IACzC,gIAAgI;IAChI,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAA;CACjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAyB5B;AAED,4HAA4H;AAC5H,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAWlB"}