@irisrun/host 0.1.0

package/dist/adapter.d.ts

@@ -0,0 +1,33 @@
+import type { StateStore, Scheduler, LogicalClock, Program, PerformerRegistry, TurnOutcome, JournalRecord, Json } from "@irisrun/core";
+import type { CapabilityProfile } from "@irisrun/agent";
+export interface HostAdapter {
+    name: string;
+    capabilities: CapabilityProfile;
+    store: StateStore;
+    scheduler: Scheduler;
+}
+export interface RunTurnOnOptions<S extends Json> {
+    sessionId: string;
+    defDigest: string;
+    program: Program<S>;
+    performers: PerformerRegistry;
+    clock: LogicalClock;
+    holderId?: string;
+    assertReplay?: boolean;
+    snapshotThreshold?: number;
+    keepHistory?: boolean;
+    maxStepsPerTurn?: number;
+    onWarn?: (message: string) => void;
+    onRecord?: (record: JournalRecord) => void;
+}
+/** Run one turn on `adapter`'s store + scheduler. Same image (defDigest) + program
+ *  on any host → the engine's deterministic replay does the rest. */
+export declare function runTurnOn<S extends Json>(adapter: HostAdapter, opts: RunTurnOnOptions<S>): Promise<TurnOutcome<S>>;
+/**
+ * Tool/host-level capability check (ADR-0008): for every capability the image
+ * REQUIRES (`requires[k] === true`), the host must PROVIDE it (`capabilities[k]
+ * === true`). `undefined`/`false` on the host means NOT satisfied — never silently
+ * widened (cf. the secure-floor posture). Refuses LOUDLY, naming the gaps; the
+ * full host capability-diff gate is deferred to M6.
+ */
+export declare function checkHostCapabilities(requires: CapabilityProfile, capabilities: CapabilityProfile, hostName?: string): void;

package/dist/adapter.js

@@ -0,0 +1,53 @@
+// HostAdapter (Spec 04 §3): a host is just {name, capabilities, store, scheduler}.
+// `runTurnOn` runs a turn ON a host's store+scheduler — the host convenience that
+// makes "the SAME image, a DIFFERENT host" explicit. It REPLACES the framework's
+// enterTurn(sessionId,event) member (there is nothing to replace — no core type);
+// it is a thin call into the engine's runTurn with the adapter's ports injected.
+// `checkHostCapabilities` is the tool/host-level ADR-0008 refusal (the FULL host
+// capability-diff gate stays deferred to M6). Host-side; core stays pure.
+import { runTurn } from "@irisrun/core";
+/** Run one turn on `adapter`'s store + scheduler. Same image (defDigest) + program
+ *  on any host → the engine's deterministic replay does the rest. */
+export async function runTurnOn(adapter, opts) {
+    return runTurn({
+        store: adapter.store,
+        scheduler: adapter.scheduler,
+        clock: opts.clock,
+        program: opts.program,
+        performers: opts.performers,
+        defDigest: opts.defDigest,
+        holderId: opts.holderId ?? adapter.name,
+        assertReplay: opts.assertReplay,
+        snapshotThreshold: opts.snapshotThreshold,
+        keepHistory: opts.keepHistory,
+        maxStepsPerTurn: opts.maxStepsPerTurn,
+        onWarn: opts.onWarn,
+        onRecord: opts.onRecord,
+    }, opts.sessionId);
+}
+// The boolean capability keys (tool_locality is a profile STRING, not a gateable
+// boolean, so it is not part of this refusal — the full degrade/refuse matrix is M6).
+const BOOLEAN_CAPS = [
+    "long_running",
+    "local_subprocess",
+    "filesystem",
+    "websockets",
+];
+/**
+ * Tool/host-level capability check (ADR-0008): for every capability the image
+ * REQUIRES (`requires[k] === true`), the host must PROVIDE it (`capabilities[k]
+ * === true`). `undefined`/`false` on the host means NOT satisfied — never silently
+ * widened (cf. the secure-floor posture). Refuses LOUDLY, naming the gaps; the
+ * full host capability-diff gate is deferred to M6.
+ */
+export function checkHostCapabilities(requires, capabilities, hostName = "host") {
+    const unmet = [];
+    for (const k of BOOLEAN_CAPS) {
+        if (requires[k] === true && capabilities[k] !== true) {
+            unmet.push(`${k} (required true, host has ${JSON.stringify(capabilities[k])})`);
+        }
+    }
+    if (unmet.length > 0) {
+        throw new Error(`checkHostCapabilities: '${hostName}' cannot satisfy required capabilities (ADR-0008): ${unmet.join("; ")}`);
+    }
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,24 @@
+import type { CapabilityProfile } from "@irisrun/agent";
+import type { HostAdapter } from "./adapter.js";
+export interface CapabilityGap {
+    capability: keyof CapabilityProfile;
+    required: unknown;
+    hostProvides: unknown;
+    message: string;
+}
+/**
+ * Diff an image's required CapabilityProfile against a host's capabilities,
+ * returning the structured gaps (empty ⇒ deployable). Booleans reuse the
+ * checkHostCapabilities rule; tool_locality compares the image's DEMAND to the
+ * host's CEILING by the fixed rank remote<local<in-process. The local-tools-on-edge
+ * gap (local_subprocess required, OR tool_locality over ceiling) carries the
+ * literal ADR-0008 message; every other boolean gap carries the precise per-cap
+ * message. Never silently widens: undefined/false on the host = NOT satisfied.
+ */
+export declare function diffCapabilities(requires: CapabilityProfile, host: HostAdapter): CapabilityGap[];
+/**
+ * The deploy gate: throw an Error joining every gap's precise message if the
+ * image cannot run on the host; return silently if it can. Refuse LOUDLY — never
+ * degrade or silently widen the host's policy.
+ */
+export declare function assertDeployable(requires: CapabilityProfile, host: HostAdapter): void;

package/dist/capabilities.js

@@ -0,0 +1,93 @@
+// The boolean capability keys (tool_locality is the STRING dimension, handled
+// separately by rank). Mirrors adapter.ts's BOOLEAN_CAPS, kept local so the two
+// gates stay independent.
+const BOOLEAN_CAPS = [
+    "long_running",
+    "local_subprocess",
+    "filesystem",
+    "websockets",
+];
+// tool_locality demand rank: remote is the LEAST host-demanding (any host can
+// reach a network endpoint; the only option on edge), in-process the MOST (the
+// tool runs inside the core process — only a trusted same-language host). The
+// host side reads its tool_locality as the CEILING; an image demanding a
+// higher-ranked locality than the ceiling cannot be satisfied.
+const LOCALITY_RANK = {
+    remote: 0,
+    local: 1,
+    "in-process": 2,
+};
+function localityRank(v) {
+    // An absent demand defaults to `remote` (the least-demanding, edge-safe floor).
+    return LOCALITY_RANK[v ?? "remote"];
+}
+/** The literal ADR-0008 refusal (agent-framework.md:682), interpolating the host
+ *  label. With `name === "Cloudflare"` the result is byte-identical to the example. */
+function adr0008Refusal(hostName) {
+    return `this agent requires local_subprocess tools; the ${hostName} target supports remote MCP tools only. Set tool_locality: remote or choose a VPS/serverless target.`;
+}
+/**
+ * Diff an image's required CapabilityProfile against a host's capabilities,
+ * returning the structured gaps (empty ⇒ deployable). Booleans reuse the
+ * checkHostCapabilities rule; tool_locality compares the image's DEMAND to the
+ * host's CEILING by the fixed rank remote<local<in-process. The local-tools-on-edge
+ * gap (local_subprocess required, OR tool_locality over ceiling) carries the
+ * literal ADR-0008 message; every other boolean gap carries the precise per-cap
+ * message. Never silently widens: undefined/false on the host = NOT satisfied.
+ */
+export function diffCapabilities(requires, host) {
+    const caps = host.capabilities;
+    const gaps = [];
+    for (const k of BOOLEAN_CAPS) {
+        if (k === "local_subprocess")
+            continue; // handled with the locality dimension below
+        if (requires[k] === true && caps[k] !== true) {
+            gaps.push({
+                capability: k,
+                required: true,
+                hostProvides: caps[k],
+                message: `${k} (required true, host has ${JSON.stringify(caps[k])})`,
+            });
+        }
+    }
+    // The local-tools-on-edge dimension: local_subprocess demanded, OR the
+    // requested tool_locality is more host-demanding than the host's ceiling. Both
+    // surface as the literal ADR-0008 refusal.
+    const ceiling = caps.tool_locality;
+    const wantsLocalSubprocess = requires.local_subprocess === true && caps.local_subprocess !== true;
+    const localityOverCeiling = localityRank(requires.tool_locality) > localityRank(ceiling);
+    if (wantsLocalSubprocess) {
+        gaps.push({
+            capability: "local_subprocess",
+            required: true,
+            hostProvides: caps.local_subprocess,
+            message: adr0008Refusal(host.name),
+        });
+    }
+    if (localityOverCeiling) {
+        gaps.push({
+            capability: "tool_locality",
+            required: requires.tool_locality,
+            hostProvides: ceiling,
+            message: adr0008Refusal(host.name),
+        });
+    }
+    return gaps;
+}
+/**
+ * The deploy gate: throw an Error joining every gap's precise message if the
+ * image cannot run on the host; return silently if it can. Refuse LOUDLY — never
+ * degrade or silently widen the host's policy.
+ */
+export function assertDeployable(requires, host) {
+    const gaps = diffCapabilities(requires, host);
+    if (gaps.length > 0) {
+        // De-duplicate identical messages before joining: an image demanding BOTH
+        // local_subprocess AND an over-ceiling tool_locality is ONE root cause (local
+        // tools on a remote-only host) and both gaps carry the same literal ADR-0008
+        // refusal — the user-facing message must render that sentence ONCE, not twice.
+        // (diffCapabilities still returns both structured gaps for programmatic inspection.)
+        const messages = [...new Set(gaps.map((g) => g.message))];
+        throw new Error(messages.join("; "));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export declare const PACKAGE = "@irisrun/host";
+export { runTurnOn, checkHostCapabilities } from "./adapter.js";
+export type { HostAdapter, RunTurnOnOptions } from "./adapter.js";
+export { diffCapabilities, assertDeployable } from "./capabilities.js";
+export type { CapabilityGap } from "./capabilities.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// @irisrun/host — public surface (host-side; makes "same image, different host" explicit).
+export const PACKAGE = "@irisrun/host";
+export { runTurnOn, checkHostCapabilities } from "./adapter.js";
+export { diffCapabilities, assertDeployable } from "./capabilities.js";

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@irisrun/host",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Iris host adapter surface — HostAdapter {name, capabilities, store, scheduler}, runTurnOn (run a turn ON a host's store+scheduler), and checkHostCapabilities (the tool/host-level ADR-0008 refusal). Makes 'same image, different host' explicit for the portability proof. Host-side; zero external deps.",
+  "exports": {
+    ".": {
+      "iris-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@irisrun/core": "^0.1.0",
+    "@irisrun/agent": "^0.1.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoai/iris.git",
+    "directory": "packages/host"
+  },
+  "homepage": "https://github.com/xoai/iris#readme",
+  "files": [
+    "dist"
+  ]
+}