@irisrun/host 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,37 @@
+# @irisrun/host
+
+**Same image, a different host — made explicit.** A host is just
+`{name, capabilities, store, scheduler}`. Once the engine is pure and durability
+lives in the journal, "run anywhere" stops being a slogan: any host that supplies
+a store + scheduler can resume the same image, and a capability diff decides — at
+deploy time, loudly — whether it's allowed to. Host-side; the core stays pure.
+
+## What it is
+
+`HostAdapter` is the four-field surface (`name`, `capabilities`, `store`,
+`scheduler`). `runTurnOn(adapter, opts)` runs ONE turn on that host's store +
+scheduler — a thin call into the engine's `runTurn` with the adapter's ports
+injected, defaulting the writer `holderId` to the host name.
+
+The deploy gate is two functions over an image's `CapabilityProfile`:
+`diffCapabilities` returns the structured `CapabilityGap[]` (booleans like
+`filesystem`/`websockets`, plus `tool_locality` ranked `remote < local <
+in-process` against the host's ceiling); `assertDeployable` throws — joining every
+gap's message — if the image can't run. `checkHostCapabilities` is the narrower
+tool-level boolean refusal. Refuse LOUDLY, never silently degrade. Zero external
+deps; depends on `@irisrun/core` + `@irisrun/agent` only.
+
+## Use it
+
+```ts
+import { runTurnOn, assertDeployable, type HostAdapter } from "@irisrun/host";
+
+assertDeployable(image.requires, host);        // throws naming every gap, or returns
+const outcome = await runTurnOn(host, { sessionId, defDigest, program, performers, clock });
+```
+
+See **[docs/Architecture](../../docs/architecture.md)** and
+**[docs/Deploy](../../docs/deploy.md)**.
+
+---
+Part of [Iris](../../README.md) — own, portable, verifiable state.

package/dist/adapter.d.ts

@@ -24,10 +24,10 @@ export interface RunTurnOnOptions<S extends Json> {
  *  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
+ * Tool/host-level capability check: 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.
+ * full host capability-diff gate is deferred.
  */
 export declare function checkHostCapabilities(requires: CapabilityProfile, capabilities: CapabilityProfile, hostName?: string): void;

package/dist/adapter.js

@@ -1,10 +1,10 @@
-// HostAdapter (Spec 04 §3): a host is just {name, capabilities, store, scheduler}.
+// HostAdapter: 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.
+// `checkHostCapabilities` is the tool/host-level capability refusal (the FULL host
+// capability-diff gate stays deferred). 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. */
@@ -26,7 +26,7 @@ export async function runTurnOn(adapter, opts) {
     }, 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).
+// boolean, so it is not part of this refusal — the full degrade/refuse matrix is deferred).
 const BOOLEAN_CAPS = [
     "long_running",
     "local_subprocess",
@@ -34,11 +34,11 @@ const BOOLEAN_CAPS = [
     "websockets",
 ];
 /**
- * Tool/host-level capability check (ADR-0008): for every capability the image
+ * Tool/host-level capability check: 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.
+ * full host capability-diff gate is deferred.
  */
 export function checkHostCapabilities(requires, capabilities, hostName = "host") {
     const unmet = [];
@@ -48,6 +48,6 @@ export function checkHostCapabilities(requires, capabilities, hostName = "host")
         }
     }
     if (unmet.length > 0) {
-        throw new Error(`checkHostCapabilities: '${hostName}' cannot satisfy required capabilities (ADR-0008): ${unmet.join("; ")}`);
+        throw new Error(`checkHostCapabilities: '${hostName}' cannot satisfy required capabilities: ${unmet.join("; ")}`);
     }
 }

package/dist/capabilities.d.ts

@@ -12,7 +12,7 @@ export interface CapabilityGap {
  * 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
+ * literal refusal 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[];

package/dist/capabilities.js

@@ -21,9 +21,9 @@ 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
+/** The literal host-capability refusal, interpolating the host
  *  label. With `name === "Cloudflare"` the result is byte-identical to the example. */
-function adr0008Refusal(hostName) {
+function localToolsRefusal(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.`;
 }
 /**
@@ -32,7 +32,7 @@ function adr0008Refusal(hostName) {
  * 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
+ * literal refusal 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) {
@@ -52,7 +52,7 @@ export function diffCapabilities(requires, host) {
     }
     // 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.
+    // surface as the literal refusal.
     const ceiling = caps.tool_locality;
     const wantsLocalSubprocess = requires.local_subprocess === true && caps.local_subprocess !== true;
     const localityOverCeiling = localityRank(requires.tool_locality) > localityRank(ceiling);
@@ -61,7 +61,7 @@ export function diffCapabilities(requires, host) {
             capability: "local_subprocess",
             required: true,
             hostProvides: caps.local_subprocess,
-            message: adr0008Refusal(host.name),
+            message: localToolsRefusal(host.name),
         });
     }
     if (localityOverCeiling) {
@@ -69,7 +69,7 @@ export function diffCapabilities(requires, host) {
             capability: "tool_locality",
             required: requires.tool_locality,
             hostProvides: ceiling,
-            message: adr0008Refusal(host.name),
+            message: localToolsRefusal(host.name),
         });
     }
     return gaps;
@@ -84,7 +84,7 @@ export function assertDeployable(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
+        // tools on a remote-only host) and both gaps carry the same literal
         // 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))];

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@irisrun/host",
-  "version": "0.1.0",
+  "version": "0.2.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.",
+  "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 refusal). Makes 'same image, different host' explicit for the portability proof. Host-side; zero external deps.",
   "exports": {
     ".": {
       "iris-src": "./src/index.ts",
@@ -11,8 +11,8 @@
     }
   },
   "dependencies": {
-    "@irisrun/core": "^0.1.0",
-    "@irisrun/agent": "^0.1.0"
+    "@irisrun/core": "^0.2.0",
+    "@irisrun/agent": "^0.2.0"
   },
   "license": "MIT",
   "engines": {