logisheets-runtime 1.1.1 → 1.3.0

package/dist/craft.d.ts

@@ -0,0 +1,92 @@
+import type { CraftManifest, CraftRuntime, CraftState, Violation, JsonRpcRequest, JsonRpcResponse } from 'logisheets-core';
+import type { Workbook } from './index.js';
+/**
+ * A {@link CraftRuntime} bound to this runtime's {@link Workbook} — the shape a
+ * Node craft implements. logisheets-core keeps the workbook type generic; here
+ * we pin it to the concrete runtime workbook.
+ */
+export type NodeCraftRuntime<S extends CraftState = CraftState> = CraftRuntime<S, Workbook>;
+/**
+ * Resolves craft ids to their code. This is the only part that talks to the
+ * outside world (an HTTP registry, a filesystem, a test double), so the loader
+ * stays environment-agnostic.
+ */
+export interface CraftRegistry {
+    /**
+     * Look up a craft's manifest by its stable id. Returns `undefined` when the
+     * registry has no such craft (the loader then skips it).
+     */
+    getManifest(craftId: string): Promise<CraftManifest | undefined>;
+    /**
+     * Download and import a craft's runtime module. `manifest.rtJs` is the path
+     * of the runtime JS file; implementations fetch it and `import()` the
+     * result. Returns the imported module namespace (the loader extracts the
+     * {@link CraftRuntime} from it), or `undefined` when the craft ships no
+     * runtime (`rtJs` empty) or the import yields nothing.
+     */
+    importRuntime(craftId: string, manifest: CraftManifest): Promise<unknown | undefined>;
+}
+/** One craft the loader brought up, with its manifest, live runtime, and the
+ * parsed state it was loaded with (kept so the request/validate/response hooks
+ * can be re-invoked with the same state per RPC exchange). */
+export interface LoadedCraft<S extends CraftState = CraftState> {
+    readonly craftId: string;
+    readonly manifest: CraftManifest;
+    readonly runtime: NodeCraftRuntime<S>;
+    readonly state: S;
+}
+/**
+ * Read a workbook's AppData and return the `craftStates` map it carries
+ * (craftId -> opaque serialized state), or an empty object when there is none.
+ *
+ * The state string is left opaque exactly as the craft wrote it — parsing is
+ * the craft's business (see {@link loadCrafts}, which hands it to `onLoad`).
+ */
+export declare function readCraftStates(wb: Workbook): Promise<Record<string, string>>;
+/**
+ * Bring up every craft a workbook depends on and hand each its saved state.
+ *
+ * For each craft id found in the workbook's AppData: resolve its manifest,
+ * download + import its runtime, then call `runtime.onLoad(state, wb)`. A craft
+ * that has no manifest, ships no runtime, or throws while loading is skipped —
+ * one broken craft never blocks the rest. Returns the crafts that loaded.
+ */
+export declare function loadCrafts(wb: Workbook, registry: CraftRegistry): Promise<LoadedCraft[]>;
+/**
+ * Notify every loaded craft that an RPC request's inputs are about to be
+ * applied, and collect any objections. A craft signals "reject this request"
+ * by returning an ErrorMessage (or throwing) from `onRequest` — e.g. the
+ * data-gateway craft rejects a request that names a block it isn't allowed to
+ * write. Returns the objection messages (empty when every craft is fine); a
+ * host that gets a non-empty result should reject the request before applying
+ * it.
+ */
+export declare function applyCraftRequest(loaded: readonly LoadedCraft[], req: JsonRpcRequest, wb: Workbook): Promise<string[]>;
+/**
+ * The validation checkpoint: run every loaded craft's `onValidate` now that
+ * the request's inputs are in place, and return the union of the cells that
+ * fail their rules. An empty result means every craft is satisfied and the
+ * host may proceed to read the response; a non-empty result means the host
+ * should reject the request and roll the inputs back. Crafts with no
+ * `onValidate` contribute nothing; a craft that errors is treated as
+ * contributing no violations (its objection, if any, surfaced in onRequest).
+ */
+export declare function validateLoadedCrafts(loaded: readonly LoadedCraft[], wb: Workbook): Promise<Violation[]>;
+/**
+ * Hand every loaded craft the RPC response about to be returned (e.g. so a
+ * craft can read its output blocks back). Returns any objection messages, same
+ * contract as {@link applyCraftRequest}.
+ */
+export declare function applyCraftResponse(loaded: readonly LoadedCraft[], resp: JsonRpcResponse, wb: Workbook): Promise<string[]>;
+/**
+ * A default {@link CraftRegistry} for local dev and tests. Crafts are
+ * registered in-process against a fake base url; `importRuntime` just returns
+ * the pre-registered module so no network or bundler is involved.
+ */
+export declare class MockCraftRegistry implements CraftRegistry {
+    private readonly entries;
+    /** Register a craft's manifest and its already-imported runtime module. */
+    add(craftId: string, manifest: CraftManifest, module: unknown): this;
+    getManifest(craftId: string): Promise<CraftManifest | undefined>;
+    importRuntime(craftId: string): Promise<unknown | undefined>;
+}

package/dist/craft.js

@@ -0,0 +1,219 @@
+// Craft loading for the headless runtime.
+//
+// A workbook can carry per-craft state in its AppData side channel (see
+// logisheets-core's craft/state.ts). When such state is present it signals that
+// the workbook depends on one or more crafts. This module reconstructs those
+// crafts on the runtime side so their logic runs headlessly:
+//
+//   1. read the workbook's AppData and pull out the `craftStates` map
+//      (craftId -> opaque serialized state) folded in by the host on save,
+//   2. for every craft id found, ask the {@link CraftRegistry} for its
+//      {@link CraftManifest},
+//   3. if the manifest names a runtime JS file, download + import it — the
+//      imported module *is* the craft's {@link CraftRuntime},
+//   4. call the runtime's `onLoad(state, workbook)` so it can rehydrate.
+//
+// The registry is a seam: production wires it to a real HTTP registry, tests
+// (and local dev) use {@link MockCraftRegistry}.
+/**
+ * The name of the AppData entry the host folds craft/block/interaction state
+ * into. Mirrors the envelope written by the browser host on save.
+ */
+const APP_DATA_ENVELOPE_NAME = 'logisheets';
+/**
+ * Read a workbook's AppData and return the `craftStates` map it carries
+ * (craftId -> opaque serialized state), or an empty object when there is none.
+ *
+ * The state string is left opaque exactly as the craft wrote it — parsing is
+ * the craft's business (see {@link loadCrafts}, which hands it to `onLoad`).
+ */
+export async function readCraftStates(wb) {
+    const appData = await wb.client.getAppData();
+    if (!Array.isArray(appData))
+        return {};
+    const entry = appData.find((d) => !!d &&
+        typeof d.name === 'string' &&
+        d.name === APP_DATA_ENVELOPE_NAME);
+    if (!entry)
+        return {};
+    let envelope;
+    try {
+        envelope = JSON.parse(entry.data);
+    }
+    catch {
+        // Legacy (raw BlockManager) payload — no craft states.
+        return {};
+    }
+    const raw = envelope?.craftStates;
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const out = {};
+    for (const [craftId, state] of Object.entries(raw)) {
+        if (typeof state === 'string')
+            out[craftId] = state;
+    }
+    return out;
+}
+/**
+ * Bring up every craft a workbook depends on and hand each its saved state.
+ *
+ * For each craft id found in the workbook's AppData: resolve its manifest,
+ * download + import its runtime, then call `runtime.onLoad(state, wb)`. A craft
+ * that has no manifest, ships no runtime, or throws while loading is skipped —
+ * one broken craft never blocks the rest. Returns the crafts that loaded.
+ */
+export async function loadCrafts(wb, registry) {
+    const states = await readCraftStates(wb);
+    const craftIds = Object.keys(states);
+    if (craftIds.length === 0)
+        return [];
+    const loaded = [];
+    for (const craftId of craftIds) {
+        // Deliberately sequential: crafts may touch shared workbook state in
+        // onLoad, so we don't race them. Revisit if that proves too slow.
+        // eslint-disable-next-line no-await-in-loop
+        const craft = await loadOneCraft(wb, registry, craftId, states[craftId]);
+        if (craft)
+            loaded.push(craft);
+    }
+    return loaded;
+}
+async function loadOneCraft(wb, registry, craftId, stateJson) {
+    const manifest = await registry.getManifest(craftId);
+    if (!manifest)
+        return undefined;
+    // No runtime file -> nothing to run for this craft (it may be UI-only).
+    if (!manifest.rtJs)
+        return undefined;
+    const mod = await registry.importRuntime(craftId, manifest);
+    const runtime = asCraftRuntime(mod);
+    if (!runtime)
+        return undefined;
+    const state = parseState(stateJson);
+    if (!state)
+        return undefined;
+    // onLoad may run engine operations (async on every host), so await it.
+    const result = await runtime.onLoad(state, wb);
+    if (isErrorMessage(result))
+        return undefined;
+    return { craftId, manifest, runtime, state };
+}
+/**
+ * Notify every loaded craft that an RPC request's inputs are about to be
+ * applied, and collect any objections. A craft signals "reject this request"
+ * by returning an ErrorMessage (or throwing) from `onRequest` — e.g. the
+ * data-gateway craft rejects a request that names a block it isn't allowed to
+ * write. Returns the objection messages (empty when every craft is fine); a
+ * host that gets a non-empty result should reject the request before applying
+ * it.
+ */
+export async function applyCraftRequest(loaded, req, wb) {
+    const errors = [];
+    for (const craft of loaded) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await craft.runtime.onRequest(req, craft.state, wb);
+            if (isErrorMessage(res))
+                errors.push(res.msg);
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e.message : String(e));
+        }
+    }
+    return errors;
+}
+/**
+ * The validation checkpoint: run every loaded craft's `onValidate` now that
+ * the request's inputs are in place, and return the union of the cells that
+ * fail their rules. An empty result means every craft is satisfied and the
+ * host may proceed to read the response; a non-empty result means the host
+ * should reject the request and roll the inputs back. Crafts with no
+ * `onValidate` contribute nothing; a craft that errors is treated as
+ * contributing no violations (its objection, if any, surfaced in onRequest).
+ */
+export async function validateLoadedCrafts(loaded, wb) {
+    const violations = [];
+    for (const craft of loaded) {
+        if (!craft.runtime.onValidate)
+            continue;
+        // eslint-disable-next-line no-await-in-loop
+        const res = await craft.runtime.onValidate(craft.state, wb);
+        if (isErrorMessage(res))
+            continue;
+        violations.push(...res);
+    }
+    return violations;
+}
+/**
+ * Hand every loaded craft the RPC response about to be returned (e.g. so a
+ * craft can read its output blocks back). Returns any objection messages, same
+ * contract as {@link applyCraftRequest}.
+ */
+export async function applyCraftResponse(loaded, resp, wb) {
+    const errors = [];
+    for (const craft of loaded) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await craft.runtime.onResponse(resp, craft.state, wb);
+            if (isErrorMessage(res))
+                errors.push(res.msg);
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e.message : String(e));
+        }
+    }
+    return errors;
+}
+/**
+ * A default {@link CraftRegistry} for local dev and tests. Crafts are
+ * registered in-process against a fake base url; `importRuntime` just returns
+ * the pre-registered module so no network or bundler is involved.
+ */
+export class MockCraftRegistry {
+    constructor() {
+        this.entries = new Map();
+    }
+    /** Register a craft's manifest and its already-imported runtime module. */
+    add(craftId, manifest, module) {
+        this.entries.set(craftId, { manifest, module });
+        return this;
+    }
+    getManifest(craftId) {
+        return Promise.resolve(this.entries.get(craftId)?.manifest);
+    }
+    importRuntime(craftId) {
+        return Promise.resolve(this.entries.get(craftId)?.module);
+    }
+}
+// The runtime may be the module's default export or the module itself.
+function asCraftRuntime(mod) {
+    const candidate = mod && typeof mod === 'object' && 'default' in mod
+        ? mod.default
+        : mod;
+    if (candidate &&
+        typeof candidate.onLoad === 'function') {
+        return candidate;
+    }
+    return undefined;
+}
+// Craft state is stored as an opaque string but is always a serialized JSON
+// object. Parse it back; return undefined if it isn't a JSON object (a
+// malformed entry we skip rather than hand a craft a bad shape).
+function parseState(stateJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stateJson);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return undefined;
+    }
+    return parsed;
+}
+function isErrorMessage(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'msg' in v);
+}

package/dist/enterprise.d.ts

@@ -0,0 +1,116 @@
+import type { AddressInfo } from 'node:net';
+import { SpreadsheetRuntime, type Workbook } from './index.js';
+import { type CraftRegistry, type LoadedCraft } from './craft.js';
+import { WorkbookWatcher } from './watcher.js';
+import type { CraftManifest } from 'logisheets-core';
+export interface ControlPlaneOptions {
+    /** Base URL of the enterprise control panel, e.g. http://cp.internal:3000 */
+    controlPlaneUrl: string;
+    /** Shared secret presented as Bearer to CP-facing endpoints. Optional (dev). */
+    secret?: string;
+}
+export interface RegisterResult {
+    runtimeId: string;
+    registryUrl: string | null;
+    registryToken: string | null;
+}
+export interface AccessEvent {
+    wbStringId?: string;
+    version?: string;
+    caller?: string;
+    method?: string;
+}
+export declare class ControlPlaneClient {
+    private readonly opts;
+    constructor(opts: ControlPlaneOptions);
+    private headers;
+    private url;
+    register(input: {
+        address: string;
+        name?: string;
+        mode?: 'serving' | 'ephemeral' | 'both';
+        capacity?: number;
+        id?: string;
+    }): Promise<RegisterResult>;
+    heartbeat(runtimeId: string): Promise<void>;
+    ingest(runtimeId: string, accessEvents: AccessEvent[]): Promise<void>;
+}
+export declare class HttpCraftRegistry implements CraftRegistry {
+    private readonly registryUrl;
+    private readonly token;
+    constructor(registryUrl: string, token: string | null);
+    private headers;
+    getManifest(craftId: string): Promise<CraftManifest | undefined>;
+    importRuntime(_craftId: string, manifest: CraftManifest): Promise<unknown | undefined>;
+}
+/** Context handed to a task handler: the loaded workbook + its crafts. */
+export interface TaskContext {
+    readonly workbook: Workbook;
+    readonly crafts: readonly LoadedCraft[];
+    readonly params: unknown;
+}
+/** A task handler runs one `rpcCall` against an ephemerally-loaded workbook. */
+export type TaskHandler = (ctx: TaskContext) => unknown | Promise<unknown>;
+export interface EnterpriseServerOptions {
+    runtime: SpreadsheetRuntime;
+    /** Registry to load crafts from. Set after registration via {@link setRegistry}. */
+    registry?: CraftRegistry;
+    /** Shared secret the control panel presents (Bearer). Open when unset. */
+    secret?: string;
+    /** rpcCall → handler (e.g. extractIndicators, compute). */
+    taskHandlers?: Record<string, TaskHandler>;
+}
+export declare class EnterpriseRuntimeServer {
+    private readonly runtime;
+    private registry?;
+    private readonly secret?;
+    private readonly handlers;
+    private readonly pins;
+    private server?;
+    constructor(opts: EnterpriseServerOptions);
+    setRegistry(registry: CraftRegistry): void;
+    registerTask(name: string, handler: TaskHandler): this;
+    listen(port: number, host?: string): Promise<AddressInfo>;
+    close(): Promise<void>;
+    private authOk;
+    private loadFromUrl;
+    private onRequest;
+    private pin;
+    private unpin;
+    private task;
+}
+export interface EnterpriseRuntimeOptions extends ControlPlaneOptions {
+    /** Externally-reachable base URL of THIS runtime (control panel dials it). */
+    address: string;
+    /** Port to listen on. Default 0 (OS-assigned; then set `address` accordingly). */
+    port?: number;
+    host?: string;
+    name?: string;
+    mode?: 'serving' | 'ephemeral' | 'both';
+    heartbeatMs?: number;
+    taskHandlers?: Record<string, TaskHandler>;
+    /**
+     * Optional local-directory watcher (pull-based `wb_*.json` loading). **Off by
+     * default** — the enterprise model is control-plane-driven (the panel pushes
+     * via `/pin`), so this is only for standalone / hybrid setups that also want
+     * the file-drop convention. Enable by giving it a directory to watch.
+     */
+    watch?: {
+        dir: string;
+        intervalMs?: number;
+    };
+}
+export interface EnterpriseRuntimeHandle {
+    runtimeId: string;
+    address: AddressInfo;
+    server: EnterpriseRuntimeServer;
+    /** The local-dir watcher, if `watch` was enabled (§ opts.watch). */
+    watcher?: WorkbookWatcher;
+    stop: () => Promise<void>;
+}
+/**
+ * Bring up an enterprise runtime: start the RPC server, register with the
+ * control panel (getting registry creds), wire the craft registry, and begin
+ * heartbeating. The control panel then dials this runtime for pin/task.
+ */
+export declare function startEnterpriseRuntime(opts: EnterpriseRuntimeOptions): Promise<EnterpriseRuntimeHandle>;

package/dist/enterprise.js

@@ -0,0 +1,292 @@
+// Enterprise integration for the headless runtime (logisheets-enterprise
+// RUNTIME_CHANGES.md). One runtime process that:
+//
+//   1. registers with the control panel on startup and gets back registry
+//      creds + its runtimeId (§2.2),
+//   2. exposes its own RPC the control panel dials (§2.3):
+//        POST /pin   {wbUrl}                    → load + keep resident (serving)
+//        POST /unpin {wbId}                     → release
+//        POST /task  {workbookUrl, rpcCall, params} → one-shot (extract/what-if)
+//        GET  /status                            → pins + load
+//   3. pulls crafts from the enterprise registry using those creds (§2.5).
+//
+// Transport + lifecycle live here; the actual business RPCs (extractIndicators,
+// what-if compute) are registered as task handlers by the consumer, since they
+// depend on the merged data-gateway craft + engine cell ops (DATA_GATEWAY_CHANGES).
+import { createServer, } from 'node:http';
+import { SpreadsheetRuntime } from './index.js';
+import { loadCrafts, } from './craft.js';
+import { WorkbookWatcher } from './watcher.js';
+export class ControlPlaneClient {
+    constructor(opts) {
+        this.opts = opts;
+    }
+    headers() {
+        return {
+            'content-type': 'application/json',
+            ...(this.opts.secret
+                ? { authorization: `Bearer ${this.opts.secret}` }
+                : {}),
+        };
+    }
+    url(path) {
+        return `${this.opts.controlPlaneUrl.replace(/\/$/, '')}${path}`;
+    }
+    async register(input) {
+        const res = await fetch(this.url('/api/runtimes/register'), {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        if (!res.ok)
+            throw new Error(`register failed: ${res.status}`);
+        return (await res.json());
+    }
+    async heartbeat(runtimeId) {
+        await fetch(this.url(`/api/runtimes/${runtimeId}/heartbeat`), {
+            method: 'POST',
+            headers: this.headers(),
+        }).catch(() => { });
+    }
+    async ingest(runtimeId, accessEvents) {
+        if (accessEvents.length === 0)
+            return;
+        await fetch(this.url('/api/ingest'), {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ runtimeId, accessEvents }),
+        }).catch(() => { });
+    }
+}
+// ── Enterprise craft registry (§2.5) ─────────────────────────────────────────
+// Pulls craft manifests + runtime modules from the enterprise registry using
+// the creds handed back at registration. Best-effort import via a data: URL
+// (works for self-contained ESM bundles; host-SDK externals must be provided by
+// the runtime's own module resolution). TODO: tarball unpack + external mapping
+// to match craft-registry's bundle format.
+export class HttpCraftRegistry {
+    constructor(registryUrl, token) {
+        this.registryUrl = registryUrl;
+        this.token = token;
+    }
+    headers() {
+        return this.token ? { 'x-api-key': this.token } : {};
+    }
+    async getManifest(craftId) {
+        const res = await fetch(`${this.registryUrl.replace(/\/$/, '')}/api/craft/${encodeURIComponent(craftId)}`, { headers: this.headers() }).catch(() => undefined);
+        if (!res || !res.ok)
+            return undefined;
+        const body = (await res.json());
+        if (body.manifest)
+            return body.manifest;
+        // Map the registry's `logisheets` metadata to the manifest shape.
+        const rtJs = body.logisheets?.runtime;
+        if (!rtJs)
+            return undefined;
+        return { rtJs, html: body.logisheets?.html ?? '' };
+    }
+    async importRuntime(_craftId, manifest) {
+        if (!manifest.rtJs)
+            return undefined;
+        // manifest.rtJs is expected to be a fetchable URL to the runtime bundle.
+        const res = await fetch(manifest.rtJs, { headers: this.headers() }).catch(() => undefined);
+        if (!res || !res.ok)
+            return undefined;
+        const code = await res.text();
+        const dataUrl = `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`;
+        try {
+            return await import(dataUrl);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+export class EnterpriseRuntimeServer {
+    constructor(opts) {
+        this.handlers = new Map();
+        // Resident (pinned) workbooks, keyed by the engine's numeric id as a string.
+        this.pins = new Map();
+        this.runtime = opts.runtime;
+        this.registry = opts.registry;
+        this.secret = opts.secret;
+        for (const [name, h] of Object.entries(opts.taskHandlers ?? {}))
+            this.handlers.set(name, h);
+    }
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    registerTask(name, handler) {
+        this.handlers.set(name, handler);
+        return this;
+    }
+    listen(port, host = '0.0.0.0') {
+        if (this.server)
+            throw new Error('server already listening');
+        const server = createServer((req, res) => void this.onRequest(req, res));
+        this.server = server;
+        return new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(port, host, () => {
+                server.removeListener('error', reject);
+                resolve(server.address());
+            });
+        });
+    }
+    close() {
+        const server = this.server;
+        if (!server)
+            return Promise.resolve();
+        this.server = undefined;
+        return new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+    }
+    authOk(req) {
+        if (!this.secret)
+            return true;
+        return req.headers.authorization === `Bearer ${this.secret}`;
+    }
+    async loadFromUrl(url) {
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`fetch workbook failed: ${res.status}`);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        const wb = this.runtime.loadWorkbookFromBytes(bytes, nameFromUrl(url));
+        if (this.registry)
+            await loadCrafts(wb, this.registry);
+        return wb;
+    }
+    async onRequest(req, res) {
+        try {
+            const url = req.url ?? '/';
+            if (req.method === 'GET' && url === '/status') {
+                if (!this.authOk(req))
+                    return json(res, 403, { error: 'forbidden' });
+                return json(res, 200, {
+                    pins: [...this.pins.keys()],
+                    open: this.runtime.workbooks.length,
+                });
+            }
+            if (req.method !== 'POST')
+                return void res.writeHead(405).end();
+            if (!this.authOk(req))
+                return json(res, 403, { error: 'forbidden' });
+            const body = JSON.parse((await readBody(req)) || '{}');
+            if (url === '/pin')
+                return json(res, 200, await this.pin(body));
+            if (url === '/unpin')
+                return json(res, 200, this.unpin(body));
+            if (url === '/task')
+                return json(res, 200, await this.task(body));
+            return json(res, 404, { error: 'not found' });
+        }
+        catch (e) {
+            json(res, 500, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    // Load a workbook and keep it resident (= serving it).
+    async pin(body) {
+        if (!body.wbUrl)
+            throw new Error('wbUrl required');
+        const wb = await this.loadFromUrl(body.wbUrl);
+        const wbId = String(wb.id);
+        this.pins.set(wbId, wb);
+        return { wbId };
+    }
+    unpin(body) {
+        if (!body.wbId)
+            throw new Error('wbId required');
+        const wb = this.pins.get(body.wbId);
+        if (wb) {
+            this.runtime.close(wb);
+            this.pins.delete(body.wbId);
+        }
+        return { ok: true };
+    }
+    // One-shot: load → run handler → release (ephemeral, workbookless).
+    async task(body) {
+        if (!body.workbookUrl || !body.rpcCall)
+            throw new Error('workbookUrl and rpcCall required');
+        const handler = this.handlers.get(body.rpcCall);
+        if (!handler)
+            throw new Error(`unknown rpcCall: ${body.rpcCall}`);
+        const wb = await this.loadFromUrl(body.workbookUrl);
+        try {
+            const crafts = this.registry ? await loadCrafts(wb, this.registry) : [];
+            return await handler({ workbook: wb, crafts, params: body.params });
+        }
+        finally {
+            this.runtime.close(wb);
+        }
+    }
+}
+/**
+ * Bring up an enterprise runtime: start the RPC server, register with the
+ * control panel (getting registry creds), wire the craft registry, and begin
+ * heartbeating. The control panel then dials this runtime for pin/task.
+ */
+export async function startEnterpriseRuntime(opts) {
+    const runtime = new SpreadsheetRuntime();
+    const server = new EnterpriseRuntimeServer({
+        runtime,
+        secret: opts.secret,
+        taskHandlers: opts.taskHandlers,
+    });
+    const address = await server.listen(opts.port ?? 0, opts.host);
+    const client = new ControlPlaneClient(opts);
+    const reg = await client.register({
+        address: opts.address,
+        name: opts.name,
+        mode: opts.mode ?? 'both',
+    });
+    if (reg.registryUrl) {
+        server.setRegistry(new HttpCraftRegistry(reg.registryUrl, reg.registryToken));
+    }
+    const interval = setInterval(() => void client.heartbeat(reg.runtimeId), opts.heartbeatMs ?? 30000);
+    interval.unref?.();
+    // Opt-in local-dir watcher (off by default; enterprise is pin-driven).
+    let watcher;
+    if (opts.watch) {
+        watcher = new WorkbookWatcher(runtime, opts.watch.dir, {
+            intervalMs: opts.watch.intervalMs,
+        });
+        watcher.start();
+    }
+    return {
+        runtimeId: reg.runtimeId,
+        address,
+        server,
+        watcher,
+        stop: async () => {
+            clearInterval(interval);
+            watcher?.stop();
+            await server.close();
+            runtime.closeAll();
+        },
+    };
+}
+function nameFromUrl(url) {
+    try {
+        const last = new URL(url).pathname.split('/').filter(Boolean).pop();
+        if (last)
+            return decodeURIComponent(last);
+    }
+    catch {
+        /* not a URL — fall through */
+    }
+    return 'workbook.xlsx';
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function json(res, status, payload) {
+    const body = JSON.stringify(payload);
+    res.writeHead(status, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body),
+    }).end(body);
+}

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import type { Value, Client } from 'logisheets-web';
 import { WorkbookOps } from 'logisheets-core';
 export * from 'logisheets-core';
 export * from './rpc.js';
+export * from './craft.js';
+export * from './watcher.js';
+export * from './enterprise.js';
 /**
  * A single live workbook in the Node WASM engine, with logisheets-core's logic
  * available as methods. You don't construct one directly — obtain it from

package/dist/index.js

@@ -18,6 +18,13 @@ import { WorkbookOps } from 'logisheets-core';
 export * from 'logisheets-core';
 // The developer-defined JSON-RPC server (operations run against this runtime).
 export * from './rpc.js';
+// Craft loading: reconstruct the crafts a workbook depends on, headlessly.
+export * from './craft.js';
+// Directory watcher: hot-(re)load workbooks from `wb_*.json` descriptors.
+export * from './watcher.js';
+// Enterprise integration: register with the control panel, expose pin/unpin/task
+// RPC, pull crafts from the enterprise registry (logisheets-enterprise).
+export * from './enterprise.js';
 /**
  * Adapt the synchronous Node `handle()` entry point into the async {@link
  * Client} that logisheets-core's operation layer expects.

package/dist/rpc.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import type { SpreadsheetRuntime, Workbook } from './index.js';
+export type { JsonRpcRequest, JsonRpcError, JsonRpcResponse } from 'logisheets-core';
 export declare const RPC_PARSE_ERROR = -32700;
 export declare const RPC_INVALID_REQUEST = -32600;
 export declare const RPC_METHOD_NOT_FOUND = -32601;

package/dist/watcher.d.ts

@@ -0,0 +1,94 @@
+import type { SpreadsheetRuntime, Workbook } from './index.js';
+/** The descriptor persisted in each `wb_*.json` file. */
+export interface WorkbookDescriptor {
+    /** Stable external string id for this workbook (the watcher's key). */
+    id: string;
+    /**
+     * Revision marker. Any change from the last-loaded value triggers a reload;
+     * accepted as a number or string and compared as its string form.
+     */
+    version: number | string;
+    /**
+     * Path to the .xlsx file. Absolute, or resolved relative to the watched
+     * directory. Optional when {@link url} is given; if both are present,
+     * `path` wins (local reads are cheaper).
+     */
+    path?: string;
+    /**
+     * URL to fetch the .xlsx from (via `fetch`). Used when {@link path} is
+     * absent. At least one of `path`/`url` must be present.
+     */
+    url?: string;
+}
+/** Options for {@link WorkbookWatcher}. */
+export interface WorkbookWatcherOptions {
+    /** Poll interval in milliseconds. Default `10_000` (10s). */
+    intervalMs?: number;
+    /**
+     * Called after a workbook is (re)loaded and swapped in, with the string id,
+     * the new live handle, and the descriptor that triggered the load.
+     */
+    onLoad?: (id: string, wb: Workbook, descriptor: WorkbookDescriptor) => void;
+    /**
+     * Called when a descriptor file can't be read, parsed, or loaded. The
+     * previously-loaded workbook (if any) is left in place. `file` is the
+     * descriptor's absolute path.
+     */
+    onError?: (file: string, err: unknown) => void;
+}
+/**
+ * Polls a directory for `wb_*.json` descriptors and keeps the runtime's
+ * workbooks in sync with them — loading new ones and replacing changed ones.
+ *
+ * ```ts
+ * const rt = new SpreadsheetRuntime()
+ * const watcher = new WorkbookWatcher(rt, './watch', {
+ *     intervalMs: 10_000,
+ *     onLoad: (id) => console.log('loaded', id),
+ * })
+ * watcher.start()
+ * // ... later ...
+ * const wb = watcher.get('sales-2026')
+ * watcher.stop()
+ * ```
+ */
+export declare class WorkbookWatcher {
+    private readonly runtime;
+    private readonly options;
+    private readonly dir;
+    private readonly intervalMs;
+    private readonly loaded;
+    private timer?;
+    /** Guards against a slow scan overlapping the next interval tick. */
+    private scanning;
+    constructor(runtime: SpreadsheetRuntime, dir: string, options?: WorkbookWatcherOptions);
+    /**
+     * Begin polling. Runs one scan immediately, then every `intervalMs`. The
+     * interval is `unref`'d so it never keeps the process alive on its own.
+     * Calling {@link start} while already running is a no-op.
+     */
+    start(): void;
+    /** Stop polling. Loaded workbooks stay open — {@link close} them if needed. */
+    stop(): void;
+    /** The live workbook currently loaded under `id`, if any. */
+    get(id: string): Workbook | undefined;
+    /** The string ids of every workbook currently loaded by the watcher. */
+    get ids(): readonly string[];
+    /**
+     * Run a single scan pass now: read every `wb_*.json` descriptor and reload
+     * any whose version changed. Exposed for tests and manual triggering; the
+     * interval calls it for you. Overlapping calls are skipped (a scan already
+     * in flight wins), so this never runs two passes concurrently.
+     */
+    scanOnce(): Promise<void>;
+    private scan;
+    /** Load-or-replace the workbook described by a single descriptor file. */
+    private reconcile;
+    /**
+     * Fetch a descriptor's .xlsx bytes — from its local {@link
+     * WorkbookDescriptor.path} if present, otherwise its {@link
+     * WorkbookDescriptor.url} — and load a fresh workbook. Only the local-path
+     * source records a `path` on the handle (a URL isn't a filesystem path).
+     */
+    private load;
+}

package/dist/watcher.js

@@ -0,0 +1,198 @@
+// Directory watcher: hot-(re)load workbooks from descriptor files.
+//
+// A host process drops small JSON descriptor files named `wb_*.json` into a
+// watched directory, each naming a workbook by a stable *string* id, a version,
+// and where to fetch its .xlsx — a local `path`, a `url`, or both:
+//
+//   { "id": "sales-2026", "version": 7, "path": "books/sales.xlsx" }
+//   { "id": "sales-2026", "version": 7, "url": "https://host/books/sales.xlsx" }
+//
+// On a fixed interval (10s by default, configurable) the {@link WorkbookWatcher}
+// scans the directory, and for every descriptor whose version differs from what
+// it last loaded it (re)loads the workbook and swaps it in under that string id.
+// This lets an external system publish new workbook revisions — bumping the
+// version each time — and have the running runtime pick them up automatically.
+//
+// The string id namespace is the watcher's own, distinct from the engine's
+// numeric {@link Workbook.id}; use {@link WorkbookWatcher.get} to resolve a
+// string id to its currently-loaded live {@link Workbook}.
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, isAbsolute, resolve } from 'node:path';
+/**
+ * Polls a directory for `wb_*.json` descriptors and keeps the runtime's
+ * workbooks in sync with them — loading new ones and replacing changed ones.
+ *
+ * ```ts
+ * const rt = new SpreadsheetRuntime()
+ * const watcher = new WorkbookWatcher(rt, './watch', {
+ *     intervalMs: 10_000,
+ *     onLoad: (id) => console.log('loaded', id),
+ * })
+ * watcher.start()
+ * // ... later ...
+ * const wb = watcher.get('sales-2026')
+ * watcher.stop()
+ * ```
+ */
+export class WorkbookWatcher {
+    constructor(runtime, dir, options = {}) {
+        this.runtime = runtime;
+        this.options = options;
+        this.loaded = new Map();
+        /** Guards against a slow scan overlapping the next interval tick. */
+        this.scanning = false;
+        this.dir = resolve(dir);
+        this.intervalMs = options.intervalMs ?? 10000;
+    }
+    /**
+     * Begin polling. Runs one scan immediately, then every `intervalMs`. The
+     * interval is `unref`'d so it never keeps the process alive on its own.
+     * Calling {@link start} while already running is a no-op.
+     */
+    start() {
+        if (this.timer !== undefined)
+            return;
+        this.timer = setInterval(() => void this.scanOnce(), this.intervalMs);
+        this.timer.unref?.();
+        void this.scanOnce();
+    }
+    /** Stop polling. Loaded workbooks stay open — {@link close} them if needed. */
+    stop() {
+        if (this.timer === undefined)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /** The live workbook currently loaded under `id`, if any. */
+    get(id) {
+        return this.loaded.get(id)?.wb;
+    }
+    /** The string ids of every workbook currently loaded by the watcher. */
+    get ids() {
+        return [...this.loaded.keys()];
+    }
+    /**
+     * Run a single scan pass now: read every `wb_*.json` descriptor and reload
+     * any whose version changed. Exposed for tests and manual triggering; the
+     * interval calls it for you. Overlapping calls are skipped (a scan already
+     * in flight wins), so this never runs two passes concurrently.
+     */
+    async scanOnce() {
+        if (this.scanning)
+            return;
+        this.scanning = true;
+        try {
+            await this.scan();
+        }
+        finally {
+            this.scanning = false;
+        }
+    }
+    async scan() {
+        let files;
+        try {
+            files = await readdir(this.dir);
+        }
+        catch (err) {
+            this.options.onError?.(this.dir, err);
+            return;
+        }
+        for (const name of files) {
+            if (!isDescriptorFile(name))
+                continue;
+            const file = resolve(this.dir, name);
+            // eslint-disable-next-line no-await-in-loop
+            await this.reconcile(file);
+        }
+    }
+    /** Load-or-replace the workbook described by a single descriptor file. */
+    async reconcile(file) {
+        let descriptor;
+        try {
+            descriptor = parseDescriptor(await readFile(file, 'utf8'));
+        }
+        catch (err) {
+            this.options.onError?.(file, err);
+            return;
+        }
+        const version = String(descriptor.version);
+        const prev = this.loaded.get(descriptor.id);
+        if (prev && prev.version === version)
+            return; // unchanged — nothing to do
+        // Fetch the bytes and load a fresh handle directly, bypassing
+        // SpreadsheetRuntime.loadWorkbook's path-dedup: a new version usually
+        // reuses the same source with changed content, so the dedup cache would
+        // hand back the stale handle. Load the new one first, then swap and
+        // release the old — on failure the old workbook is left untouched.
+        let loaded;
+        try {
+            loaded = await this.load(descriptor);
+        }
+        catch (err) {
+            this.options.onError?.(file, err);
+            return;
+        }
+        this.loaded.set(descriptor.id, { version, ...loaded });
+        if (prev)
+            this.runtime.close(prev.wb);
+        this.options.onLoad?.(descriptor.id, loaded.wb, descriptor);
+    }
+    /**
+     * Fetch a descriptor's .xlsx bytes — from its local {@link
+     * WorkbookDescriptor.path} if present, otherwise its {@link
+     * WorkbookDescriptor.url} — and load a fresh workbook. Only the local-path
+     * source records a `path` on the handle (a URL isn't a filesystem path).
+     */
+    async load(d) {
+        if (d.path !== undefined) {
+            const source = isAbsolute(d.path)
+                ? d.path
+                : resolve(this.dir, d.path);
+            const content = await readFile(source);
+            const wb = this.runtime.loadWorkbookFromBytes(content, basename(source), source);
+            return { wb, source };
+        }
+        // d.url is guaranteed present by parseDescriptor when path is absent.
+        const url = d.url;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`fetch ${url} failed: ${res.status} ${res.statusText}`);
+        const content = new Uint8Array(await res.arrayBuffer());
+        const wb = this.runtime.loadWorkbookFromBytes(content, nameFromUrl(url));
+        return { wb, source: url };
+    }
+}
+/** True for descriptor file names — `wb_*.json`. */
+function isDescriptorFile(name) {
+    return /^wb_.*\.json$/i.test(name);
+}
+/** Parse and validate a descriptor's JSON text, throwing on a bad shape. */
+function parseDescriptor(text) {
+    const raw = JSON.parse(text);
+    if (typeof raw !== 'object' || raw === null)
+        throw new Error('descriptor must be a JSON object');
+    const { id, version, path, url } = raw;
+    if (typeof id !== 'string' || id.length === 0)
+        throw new Error('descriptor.id must be a non-empty string');
+    if (typeof version !== 'string' && typeof version !== 'number')
+        throw new Error('descriptor.version must be a string or number');
+    if (path !== undefined && (typeof path !== 'string' || path.length === 0))
+        throw new Error('descriptor.path, if present, must be a non-empty string');
+    if (url !== undefined && (typeof url !== 'string' || url.length === 0))
+        throw new Error('descriptor.url, if present, must be a non-empty string');
+    if (path === undefined && url === undefined)
+        throw new Error('descriptor must have a `path` or a `url`');
+    return { id, version, path, url };
+}
+/** Derive a workbook file name from a URL, falling back to a generic name. */
+function nameFromUrl(url) {
+    try {
+        const last = new URL(url).pathname.split('/').filter(Boolean).pop();
+        if (last)
+            return decodeURIComponent(last);
+    }
+    catch {
+        /* not a parseable URL — fall through */
+    }
+    return 'workbook.xlsx';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-runtime",
-    "version": "1.1.1",
+    "version": "1.3.0",
     "description": "Headless LogiSheets spreadsheet runtime for Node — logisheets-core wired to the Node WASM engine. The Node counterpart of the browser app.",
     "type": "module",
     "main": "./dist/index.js",
@@ -18,8 +18,8 @@
     "author": "Jeremy He",
     "license": "MIT",
     "dependencies": {
-        "logisheets": "^1.1.0",
-        "logisheets-core": "^1.1.0"
+        "logisheets": "^1.3.0",
+        "logisheets-core": "^1.3.0"
     },
     "devDependencies": {
         "typescript": "^5.5.0",