@irisrun/channel-core 0.2.0

package/README.md

@@ -0,0 +1,38 @@
+# @irisrun/channel-core
+
+**Own, portable, verifiable state — in front of a human, over any channel.**
+The narrow channel **port**: the contract every Iris channel implements so durable,
+resumable, approval-gated sessions are pluggable and **replay-safe by construction**.
+
+## What it is
+
+`channel-rest`, `channel-mcp`, and `channel-slack` all speak the same two-identifier
+protocol. This package is that protocol, factored into one driver:
+
+- `makeChannelSession({ runTurn })` — mints the `sessionId`, owns and **rotates a
+  single-use continuation token**, and enforces the rotation rule in one place:
+  rotate **only on a committed turn** (`finished`/`parked`); a non-committed turn
+  (`contended`/`aborted`) journaled nothing, so it **keeps the prior token**. The
+  in-flight claim is atomic (taken in the same callback as the token check), so a
+  concurrent replay of a token is refused, not double-applied.
+- `start` / `continueTurn` — the high-level API; `validateContinue` / `inFlight` /
+  `advance` — primitives a streaming transport uses to refuse loudly *before* opening
+  a stream. Refusals are a typed taxonomy: `unknown-session` · `missing-token` ·
+  `stale-token` · `in-flight`.
+- `ChannelPort<Platform, Reply>` — the `normalizeInbound` / `emitOutbound` contract a
+  platform adapter implements. A transport reduces to: normalize → drive the session
+  → emit.
+- `ChannelEvent` / `toOutcomeEvent` — the one streaming-event vocabulary (`record` ·
+  `delta` · `outcome` · `error`), shared so SSE, WebSocket, and any future transport
+  agree field-for-field.
+
+The proof that channels are interchangeable is a single shared **conformance suite**
+(`tests/lib/channel-port-conformance.ts`) that `channel-rest`, `channel-mcp`, and
+`channel-slack` all pass — "channels behind one port" is a literal, executed guarantee.
+
+The continuation token is an instance-local ordering credential; the **durable**
+session lives in the StateStore journal. See `docs/reference/channel-port-spec.md`.
+
+---
+
+Part of [Iris](../../README.md) — own, portable, verifiable state.

package/dist/events.d.ts

@@ -0,0 +1,20 @@
+import type { Json, TurnOutcome } from "@irisrun/core";
+export type ChannelEvent = {
+    type: "record";
+    record: Json;
+} | {
+    type: "delta";
+    text: string;
+} | {
+    type: "outcome";
+    sessionId: string;
+    status: TurnOutcome<Json>["status"];
+    output?: Json;
+    wait?: Json;
+    current?: number;
+    continuationToken?: string;
+} | {
+    type: "error";
+    message: string;
+};
+export declare function toOutcomeEvent<S extends Json>(sessionId: string, outcome: TurnOutcome<S>, token?: string): ChannelEvent;

package/dist/events.js

@@ -0,0 +1,19 @@
+// Map a finished turn to the terminal `outcome` event, plus the rotated token.
+// `token` is omitted only when the channel did not (re)issue one. Mirrors the
+// buffered turn-response mapping so streaming and buffered agree field-for-field.
+export function toOutcomeEvent(sessionId, outcome, token) {
+    const ev = {
+        type: "outcome",
+        sessionId,
+        status: outcome.status,
+    };
+    if (outcome.status === "finished" && outcome.output !== undefined)
+        ev.output = outcome.output;
+    if (outcome.status === "parked")
+        ev.wait = outcome.wait;
+    if (outcome.status === "contended")
+        ev.current = outcome.current;
+    if (token !== undefined)
+        ev.continuationToken = token;
+    return ev;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export declare const PACKAGE = "@irisrun/channel-core";
+export { makeChannelSession } from "./session.js";
+export type { ChannelSession, ChannelSessionOptions, ChannelRefusal, StartResult, ContinueResult, AdvanceResult, } from "./session.js";
+export type { ChannelEvent } from "./events.js";
+export { toOutcomeEvent } from "./events.js";
+export type { Inbound, ChannelPort } from "./port.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// @irisrun/channel-core — the narrow, replay-safe channel PORT.
+// The two-identifier protocol (mint sessionId, own/rotate a single-use continuation
+// token, atomic single-use, loud refusals) in one place, behind which channel-rest,
+// channel-mcp, and channel-slack are interchangeable — proven by a shared conformance
+// suite any channel must pass. Depends only on @irisrun/core types.
+export const PACKAGE = "@irisrun/channel-core";
+export { makeChannelSession } from "./session.js";
+export { toOutcomeEvent } from "./events.js";

package/dist/port.d.ts

@@ -0,0 +1,26 @@
+import type { Json } from "@irisrun/core";
+import type { StartResult, ContinueResult } from "./session.js";
+/** A platform event normalized to a channel intent. `ignore` = a platform event the
+ *  channel does not act on (a bot's own echo, a health ping, a handshake handled
+ *  out of band). `continue` carries the token the platform round-tripped (null when
+ *  the transport authorizes by connection rather than token, e.g. a held socket). */
+export type Inbound = {
+    kind: "start";
+    body: Json;
+} | {
+    kind: "continue";
+    sessionId: string;
+    token: string | null;
+    body: Json;
+} | {
+    kind: "ignore";
+};
+/**
+ * A channel adapter for a platform. `Platform` is the inbound event type (an HTTP
+ * request, a JSON-RPC call, a Slack payload); `Reply` is the platform's outbound
+ * shape. The driver in between is the shared ChannelSession.
+ */
+export interface ChannelPort<Platform, Reply> {
+    normalizeInbound(ev: Platform): Inbound;
+    emitOutbound(result: StartResult<Json> | ContinueResult<Json>): Reply;
+}

package/dist/port.js

@@ -0,0 +1 @@
+export {};

package/dist/session.d.ts

@@ -0,0 +1,57 @@
+import type { Json, TurnOutcome } from "@irisrun/core";
+import type { ChannelEvent } from "./events.js";
+/** Why a continue was refused — each maps to a transport's loud error. */
+export type ChannelRefusal = "unknown-session" | "missing-token" | "stale-token" | "in-flight";
+export interface StartResult<S extends Json> {
+    sessionId: string;
+    token: string;
+    outcome: TurnOutcome<S>;
+}
+export type ContinueResult<S extends Json> = {
+    ok: true;
+    sessionId: string;
+    token: string;
+    outcome: TurnOutcome<S>;
+} | {
+    ok: false;
+    reason: ChannelRefusal;
+};
+/** advance() result: in-flight is the only refusal it can produce (validation is separate). */
+export type AdvanceResult<S extends Json> = {
+    ok: true;
+    sessionId: string;
+    token: string;
+    outcome: TurnOutcome<S>;
+} | {
+    ok: false;
+    reason: "in-flight";
+};
+export interface ChannelSessionOptions<S extends Json> {
+    runTurn: (sessionId: string, body: Json, emit?: (ev: ChannelEvent) => void) => Promise<TurnOutcome<S>>;
+    mintSessionId?: () => string;
+    mintToken?: () => string;
+}
+export interface ChannelSession<S extends Json> {
+    /** START: mint a session, run the first turn, issue a fresh token. */
+    start(body: Json, emit?: (ev: ChannelEvent) => void): Promise<StartResult<S>>;
+    /** CONTINUE (strict): validate the token, claim in-flight, run, rotate. */
+    continueTurn(sessionId: string, presentedToken: string | null, body: Json, emit?: (ev: ChannelEvent) => void): Promise<ContinueResult<S>>;
+    /** Pure token validation (no run) — for streaming transports that must refuse
+     *  loudly BEFORE opening the stream. Returns null when the token is acceptable.
+     *  Does NOT consider in-flight (use inFlight()); call inFlight() then advance() with
+     *  no `await` in between to keep the check→claim atomic. */
+    validateContinue(sessionId: string, presentedToken: string | null): ChannelRefusal | null;
+    /** True if a turn is already in flight for this session (peek; for streaming). */
+    inFlight(sessionId: string): boolean;
+    /** Claim in-flight, run the turn, rotate per the committed-only rule, release.
+     *  Used by START, by continueTurn, and directly by the WS path (which authorizes via
+     *  the held connection rather than a presented token). A fresh session id (not yet
+     *  registered) runs as a START (prior token null → always mints). */
+    advance(sessionId: string, body: Json, emit?: (ev: ChannelEvent) => void): Promise<AdvanceResult<S>>;
+    /** A fresh session id (for the WS path, which binds the session to the connection
+     *  synchronously before the first turn runs). */
+    newSessionId(): string;
+    currentToken(sessionId: string): string | undefined;
+    hasSession(sessionId: string): boolean;
+}
+export declare function makeChannelSession<S extends Json>(opts: ChannelSessionOptions<S>): ChannelSession<S>;

package/dist/session.js

@@ -0,0 +1,76 @@
+function randomId() {
+    // node:crypto is host-side; avoid importing it here so channel-core stays
+    // dependency-light. A transport may inject mintSessionId/mintToken (they do, with
+    // randomUUID) — this fallback is only for tests/usages that don't.
+    return `${Date.now().toString(36)}-${Math.round(Math.random() * 1e9).toString(36)}`;
+}
+const COMMITTED = new Set(["finished", "parked"]);
+export function makeChannelSession(opts) {
+    const mintSessionId = opts.mintSessionId ?? randomId;
+    const mintToken = opts.mintToken ?? randomId;
+    // The channel OWNS the current continuationToken per session (in-process; a durable
+    // deploy persists the durable JOURNAL in the store — the token is an instance-local
+    // ordering credential, not durable state).
+    const tokens = new Map();
+    // Single-use guard under concurrency: the in-flight claim is taken in the SAME
+    // event-loop callback as the token check, with no `await` between, so a second
+    // concurrent request presenting the same valid token is refused before rotation.
+    const inFlightSet = new Set();
+    // Issue the next token: rotate (mint) ONLY on a committed outcome; a non-committed
+    // outcome with a prior token keeps it. A START (priorToken null) always mints.
+    const issueToken = (sessionId, outcome, priorToken) => {
+        if (priorToken !== null && !COMMITTED.has(outcome.status))
+            return priorToken;
+        const token = mintToken();
+        tokens.set(sessionId, token);
+        return token;
+    };
+    const advance = async (sessionId, body, emit) => {
+        if (inFlightSet.has(sessionId))
+            return { ok: false, reason: "in-flight" };
+        const prior = tokens.get(sessionId) ?? null; // null for a fresh session → START
+        inFlightSet.add(sessionId);
+        try {
+            const outcome = await opts.runTurn(sessionId, body, emit);
+            const token = issueToken(sessionId, outcome, prior);
+            return { ok: true, sessionId, token, outcome };
+        }
+        finally {
+            inFlightSet.delete(sessionId);
+        }
+    };
+    const validateContinue = (sessionId, presentedToken) => {
+        if (!tokens.has(sessionId))
+            return "unknown-session";
+        if (presentedToken === null || presentedToken === "")
+            return "missing-token";
+        if (presentedToken !== tokens.get(sessionId))
+            return "stale-token";
+        return null;
+    };
+    return {
+        async start(body, emit) {
+            const sessionId = mintSessionId();
+            // A brand-new id cannot be in flight, so advance always succeeds here.
+            const r = await advance(sessionId, body, emit);
+            // r.ok is always true (fresh id). Narrow for the type system.
+            if (!r.ok)
+                throw new Error("channel-core: unreachable in-flight on a fresh session");
+            return { sessionId, token: r.token, outcome: r.outcome };
+        },
+        async continueTurn(sessionId, presentedToken, body, emit) {
+            // Token check (sync) → advance (claims in-flight synchronously before its first
+            // await) — one callback, no await between → the single-use claim is atomic.
+            const refusal = validateContinue(sessionId, presentedToken);
+            if (refusal)
+                return { ok: false, reason: refusal };
+            return advance(sessionId, body, emit);
+        },
+        validateContinue,
+        inFlight: (sessionId) => inFlightSet.has(sessionId),
+        advance,
+        newSessionId: () => mintSessionId(),
+        currentToken: (sessionId) => tokens.get(sessionId),
+        hasSession: (sessionId) => tokens.has(sessionId),
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@irisrun/channel-core",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Iris channel port — the narrow, replay-safe contract every channel implements: mint the sessionId, own and rotate a single-use continuation token (rotate only on a committed turn; keep it on a non-committed one), an atomic single-use in-flight claim, normalize-inbound / emit-outbound, and a loud refusal taxonomy. The shared driver behind channel-rest, channel-mcp, and channel-slack, with one conformance suite any channel must pass — so durable, resumable sessions are pluggable and replay-safe by construction. Depends only on @irisrun/core types.",
+  "exports": {
+    ".": {
+      "iris-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@irisrun/core": "^0.2.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoai/iris.git",
+    "directory": "packages/channel-core"
+  },
+  "homepage": "https://github.com/xoai/iris#readme",
+  "files": [
+    "dist"
+  ]
+}