@nylorun/runtime 0.19.1-beta → 0.20.0-beta

package/dist/store/postgres/connect.d.ts

@@ -41,3 +41,13 @@ export declare function createPostgresClient(url: string, options?: PostgresClie
 export declare function assertLogicalReplication(sql: Sql): Promise<void>;
 /** Separate, bounded pool for read projections; inherits the Tenant connection credentials. */
 export declare function createPostgresReadClient(source: PostgresClient): PostgresClient;
+/**
+ * One connection of its own for `LISTEN` (the control bus, `control.ts`), with `source`'s
+ * database and credentials. It never idles out. `onClose` runs when the connection ends for
+ * any reason; the caller listens again, which connects again. A `LISTEN` needs a session of
+ * its own: behind a pooler in transaction mode it would not hear a thing.
+ */
+export declare function createPostgresListenClient(source: PostgresClient, handlers: {
+    onNotify: (channel: string, payload: string) => void;
+    onClose: () => void;
+}): PostgresClient;

package/dist/store/postgres/connect.js

@@ -40,9 +40,9 @@ export async function assertLogicalReplication(sql) {
     if (!row.replicates)
         throw new Error("The Runtime's Postgres role cannot replicate: grant it REPLICATION (ALTER ROLE … REPLICATION). See DEPLOYMENT.md.");
 }
-/** Separate, bounded pool for read projections; inherits the Tenant connection credentials. */
-export function createPostgresReadClient(source) {
-    const options = {
+/** Where `source` connects, as whom: for clients that share its database and credentials. */
+function connectionOf(source) {
+    return {
         host: source.options.host.length === 1
             ? source.options.host[0]
             : source.options.host
@@ -54,6 +54,12 @@ export function createPostgresReadClient(source) {
         pass: source.options.pass ?? "",
         ssl: source.options.ssl,
         path: source.options.path,
+    };
+}
+/** Separate, bounded pool for read projections; inherits the Tenant connection credentials. */
+export function createPostgresReadClient(source) {
+    const options = {
+        ...connectionOf(source),
         max: 4,
         idle_timeout: 30,
         connect_timeout: 2,
@@ -69,3 +75,24 @@ export function createPostgresReadClient(source) {
     const pool = postgres(options);
     return pool;
 }
+/**
+ * One connection of its own for `LISTEN` (the control bus, `control.ts`), with `source`'s
+ * database and credentials. It never idles out. `onClose` runs when the connection ends for
+ * any reason; the caller listens again, which connects again. A `LISTEN` needs a session of
+ * its own: behind a pooler in transaction mode it would not hear a thing.
+ */
+export function createPostgresListenClient(source, handlers) {
+    const options = {
+        ...connectionOf(source),
+        max: 1,
+        idle_timeout: 0,
+        max_lifetime: null,
+        connect_timeout: 10,
+        fetch_types: false,
+        onnotice() { },
+        onnotify: handlers.onNotify,
+        onclose: () => handlers.onClose(),
+        connection: { application_name: "nylorun-control" },
+    };
+    return postgres(options);
+}

package/dist/store/postgres/control.d.ts

@@ -0,0 +1,14 @@
+import type { Sql } from "postgres";
+import type { ControlSignal, FollowSignalsOptions, SignalFollower } from "../types.js";
+import type { Database, Queryable } from "./db.js";
+/** The channel every signal is notified on. */
+export declare const CONTROL_CHANNEL = "nylorun_control";
+/** Puts `signal` on the bus in the transaction `db` runs: a row, notified at commit. */
+export declare function writeSignal(db: Queryable, signal: ControlSignal): Promise<void>;
+/** Deletes the signals written before `before`; returns how many. */
+export declare function pruneSignals(db: Queryable, before: Date): Promise<number>;
+/**
+ * Follows the bus on `source`'s database (`SessionStore.followSignals`). Resolves once the
+ * start is fixed; the first LISTEN may still be retrying, and the poll covers it meanwhile.
+ */
+export declare function followControlSignals(source: Sql, db: Database, onSignal: (signal: ControlSignal) => void, options?: FollowSignalsOptions): Promise<SignalFollower>;

package/dist/store/postgres/control.js

@@ -0,0 +1,187 @@
+/**
+ * The control bus on Postgres (blueprint D21, D48): how one process tells the others with the
+ * Tenant open to act now. `session.cancel` aborts the advance of a cancelled turn;
+ * `sessions.reset` moves the session streams to the Tenant's new basin generation. Nothing
+ * internal goes through S2, which only serves API listeners.
+ *
+ * - **Write.** `writeSignal` inserts a `control_signals` row and calls `pg_notify` on
+ *   `nylorun_control`, in the caller's transaction. Postgres sends the notification to every
+ *   listening session when the transaction commits and drops it on rollback, so a signal
+ *   exists exactly when what it announces committed.
+ * - **Follow.** `followControlSignals` holds one connection of its own that LISTENs (a pooled
+ *   connection cannot). Each notification reads back the signals of the last
+ *   `WINDOW_SECONDS` and delivers those this follower has not delivered yet. So does a poll
+ *   every `pollMs`, and every LISTEN after a reconnect: Postgres does not queue notifications
+ *   for a session that is not connected, and the rows are what catches up. Ids are never read
+ *   as a cursor: they are allocated at insert and commit out of order, so a later id can be
+ *   visible first.
+ * - **Start.** A follower delivers the signals written from its start on (the database's
+ *   clock), never older ones.
+ * - **Prune.** A row outlives its notification only for the read-back; the Tenant sweep
+ *   deletes old ones (`pruneSignals`).
+ */
+import { gte, lt, sql } from "drizzle-orm";
+import { createPostgresListenClient } from "./connect.js";
+import { controlSignals } from "./schema.js";
+/** The channel every signal is notified on. */
+export const CONTROL_CHANNEL = "nylorun_control";
+/** How far back a read-back looks. Longer than the poll, so a missed notification is caught. */
+const WINDOW_SECONDS = 120;
+const POLL_MS = 5000;
+const RETRY_MIN_MS = 100;
+const RETRY_MAX_MS = 5000;
+const SIGNAL = {
+    id: controlSignals.id,
+    kind: controlSignals.kind,
+    sessionId: controlSignals.sessionId,
+    turnId: controlSignals.turnId,
+    generation: controlSignals.generation,
+};
+/** Puts `signal` on the bus in the transaction `db` runs: a row, notified at commit. */
+export async function writeSignal(db, signal) {
+    const [row] = await db
+        .insert(controlSignals)
+        .values({
+        kind: signal.type,
+        sessionId: signal.type === "session.cancel" ? signal.sessionId : null,
+        turnId: signal.type === "session.cancel" ? (signal.turnId ?? null) : null,
+        generation: signal.type === "sessions.reset" ? signal.generation : null,
+    })
+        .returning({ id: controlSignals.id });
+    // The payload is only the id: a follower reads the rows back either way.
+    await db.execute(sql `SELECT pg_notify(${CONTROL_CHANNEL}, ${String(row.id)})`);
+}
+/** Deletes the signals written before `before`; returns how many. */
+export async function pruneSignals(db, before) {
+    const deleted = await db
+        .delete(controlSignals)
+        .where(lt(controlSignals.createdAt, before.toISOString()))
+        .returning({ id: controlSignals.id });
+    return deleted.length;
+}
+/**
+ * Follows the bus on `source`'s database (`SessionStore.followSignals`). Resolves once the
+ * start is fixed; the first LISTEN may still be retrying, and the poll covers it meanwhile.
+ */
+export async function followControlSignals(source, db, onSignal, options = {}) {
+    const pollMs = options.pollMs ?? POLL_MS;
+    const onError = options.onError ?? (() => { });
+    // Drizzle leaves timestamps to its column types, so a raw read of one is text.
+    const [start] = await db.execute(sql `SELECT clock_timestamp()::text AS now`);
+    const since = start.now;
+    /** Ids delivered, with when (this process's clock), until no read-back can return them. */
+    const delivered = new Map();
+    let stopped = false;
+    let retry;
+    let delay = RETRY_MIN_MS;
+    let draining;
+    let again = false;
+    const client = createPostgresListenClient(source, {
+        onNotify: (channel) => {
+            if (channel === CONTROL_CHANNEL)
+                drain();
+        },
+        // The connection ended (Postgres restarted, the network dropped): listen again, which
+        // connects again, and read back what was missed meanwhile.
+        onClose: () => relisten(),
+    });
+    function relisten() {
+        if (stopped || retry)
+            return;
+        retry = setTimeout(() => {
+            retry = undefined;
+            void listen();
+        }, delay);
+        retry.unref();
+        delay = Math.min(delay * 2, RETRY_MAX_MS);
+    }
+    async function listen() {
+        if (stopped)
+            return;
+        try {
+            await client.unsafe(`LISTEN ${CONTROL_CHANNEL}`);
+            delay = RETRY_MIN_MS;
+            drain();
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            onError(error);
+            relisten();
+        }
+    }
+    function drain() {
+        if (stopped)
+            return;
+        if (draining) {
+            again = true;
+            return;
+        }
+        draining = (async () => {
+            do {
+                again = false;
+                try {
+                    const rows = await db
+                        .select(SIGNAL)
+                        .from(controlSignals)
+                        .where(gte(controlSignals.createdAt, sql `greatest(${since}::timestamptz, clock_timestamp() - make_interval(secs => ${WINDOW_SECONDS}))`))
+                        .orderBy(controlSignals.id);
+                    for (const row of rows)
+                        deliver(row);
+                }
+                catch (error) {
+                    if (!stopped)
+                        onError(error);
+                }
+                forgetOld();
+            } while (again && !stopped);
+        })().finally(() => {
+            draining = undefined;
+        });
+    }
+    function deliver(row) {
+        if (stopped || delivered.has(row.id))
+            return;
+        delivered.set(row.id, Date.now());
+        const signal = signalOf(row);
+        if (!signal)
+            return;
+        try {
+            onSignal(signal);
+        }
+        catch (error) {
+            onError(error);
+        }
+    }
+    /** A row a read-back can still return is younger than the window: keep twice that. */
+    function forgetOld() {
+        const before = Date.now() - 2 * WINDOW_SECONDS * 1000;
+        for (const [id, at] of delivered)
+            if (at < before)
+                delivered.delete(id);
+    }
+    const poll = setInterval(drain, pollMs);
+    poll.unref();
+    await listen();
+    return {
+        async close() {
+            stopped = true;
+            clearInterval(poll);
+            if (retry)
+                clearTimeout(retry);
+            await draining;
+            await client.end({ timeout: 0 });
+        },
+    };
+}
+function signalOf(row) {
+    if (row.kind === "session.cancel" && row.sessionId !== null)
+        return {
+            type: "session.cancel",
+            sessionId: row.sessionId,
+            ...(row.turnId !== null ? { turnId: row.turnId } : {}),
+        };
+    if (row.kind === "sessions.reset" && row.generation !== null)
+        return { type: "sessions.reset", generation: row.generation };
+    return undefined;
+}

package/dist/store/postgres/drizzle/0015_control_signals.sql

@@ -0,0 +1,11 @@
+CREATE TABLE "nylorun"."control_signals" (
+	"id" bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY (sequence name "nylorun"."control_signals_id_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START WITH 1 CACHE 1),
+	"kind" text NOT NULL,
+	"session_id" text COLLATE "C",
+	"turn_id" text COLLATE "C",
+	"generation" integer,
+	"created_at" timestamp with time zone DEFAULT clock_timestamp() NOT NULL,
+	CONSTRAINT "control_signals_kind_check" CHECK ("nylorun"."control_signals"."kind" IN ('session.cancel', 'sessions.reset'))
+);
+--> statement-breakpoint
+CREATE INDEX "control_signals_created_at" ON "nylorun"."control_signals" USING btree ("created_at");

package/dist/store/postgres/drizzle/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1791218903443,
       "tag": "0014_action_endpoints_removed",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1791296131735,
+      "tag": "0015_control_signals",
+      "breakpoints": true
     }
   ]
 }

package/dist/store/postgres/schema.d.ts

@@ -3478,6 +3478,126 @@ export declare const definitionFileUses: import("drizzle-orm/pg-core").PgTableWi
     };
     dialect: 'pg';
 }>;
+/**
+ * The control bus (D21, D48): signals between the processes that have the Tenant open,
+ * written in the transaction that commits what they announce and notified on
+ * `nylorun_control` at commit (`control.ts`). A row outlives its notification so a process
+ * whose listener was down catches up; the Tenant sweep deletes old ones. `created_at` is the
+ * insert's own clock (`clock_timestamp()`), not its transaction's start.
+ */
+export declare const controlSignals: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "control_signals";
+    schema: "nylorun";
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "control_signals";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: "always";
+            generated: undefined;
+        }, {}, {}>;
+        kind: import("drizzle-orm/pg-core").PgColumn<{
+            name: "kind";
+            tableName: "control_signals";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sessionId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "sessionId";
+            tableName: "control_signals";
+            dataType: "custom";
+            columnType: "PgCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            pgColumnBuilderBrand: 'PgCustomColumnBuilderBrand';
+        }>;
+        turnId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "turnId";
+            tableName: "control_signals";
+            dataType: "custom";
+            columnType: "PgCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            pgColumnBuilderBrand: 'PgCustomColumnBuilderBrand';
+        }>;
+        generation: import("drizzle-orm/pg-core").PgColumn<{
+            name: "generation";
+            tableName: "control_signals";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "createdAt";
+            tableName: "control_signals";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>;
 /**
  * Each sandbox's lifecycle stream (`nylorun.sandbox-event/1`), numbered from 0 per sandbox id.
  * Written only by the record module; not published to the stream relay.

package/dist/store/postgres/schema.js

@@ -435,6 +435,26 @@ export const definitionFileUses = nylorun.table("definition_file_uses", {
     primaryKey({ name: "definition_file_uses_pkey", columns: [t.agentId, t.manifestHash, t.sha256] }),
     index("definition_file_uses_sha256").on(t.sha256),
 ]);
+/**
+ * The control bus (D21, D48): signals between the processes that have the Tenant open,
+ * written in the transaction that commits what they announce and notified on
+ * `nylorun_control` at commit (`control.ts`). A row outlives its notification so a process
+ * whose listener was down catches up; the Tenant sweep deletes old ones. `created_at` is the
+ * insert's own clock (`clock_timestamp()`), not its transaction's start.
+ */
+export const controlSignals = nylorun.table("control_signals", {
+    id: bigint({ mode: "number" }).primaryKey().generatedAlwaysAsIdentity(),
+    kind: text().notNull(),
+    sessionId: textC(),
+    turnId: textC(),
+    generation: integer(),
+    createdAt: timestamp({ withTimezone: true, mode: "string" })
+        .notNull()
+        .default(sql `clock_timestamp()`),
+}, (t) => [
+    index("control_signals_created_at").on(t.createdAt),
+    check("control_signals_kind_check", sql `${t.kind} IN ('session.cancel', 'sessions.reset')`),
+]);
 // ---------------------------------------------------------------------------
 // nylorun_streams: the record
 /**

package/dist/store/postgres/store.js

@@ -52,6 +52,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { and, count, eq, getTableColumns, gte, inArray, isNotNull, isNull, lt, lte, ne, or, sql, } from "drizzle-orm";
 import { appendEvent, appendSandboxEvent } from "../../record/index.js";
 import { OwnershipLostError, PrincipalRoleConflict } from "../ownership.js";
+import { followControlSignals, pruneSignals, writeSignal } from "./control.js";
 import { database, driverError } from "./db.js";
 import { expectedSchemaVersion, readSchemaVersion } from "./migrate.js";
 import { createPostgresRecordReader } from "./record.js";
@@ -175,6 +176,11 @@ class PostgresSessionStore {
             return { ok: false, schemaVersion: 0, expectedSchemaVersion };
         }
     }
+    followSignals(onSignal, options) {
+        if (this.closed)
+            throw new Error("SessionStore is closed");
+        return followControlSignals(this.sql, this.db, onSignal, options);
+    }
     /** Rejects new transactions and waits for running ones. Does not end the pool. */
     async close() {
         this.closed = true;
@@ -583,6 +589,15 @@ class PostgresTx {
             definitions: row.definitions,
         };
     }
+    // --- control bus (D21) ---------------------------------------------------
+    async signal(signal) {
+        this.check();
+        await writeSignal(this.db, signal);
+    }
+    async pruneSignals(before) {
+        this.check();
+        return pruneSignals(this.db, before);
+    }
     // --- basin generations --------------------------------------------------
     async basinGenerations() {
         this.check();

package/dist/store/types.d.ts

@@ -261,6 +261,39 @@ export interface SessionStore {
     record(): RecordReader;
     /** Reachability and schema check for Tenant status and `/ready`. Never throws. */
     health(): Promise<StoreHealth>;
+    /**
+     * Follows the control bus (D21): calls `onSignal` once for each signal committed after the
+     * returned promise resolves, on every process that follows. Delivery is by notification,
+     * backed by a poll of recent signals (every `pollMs`, and each time the listener connects
+     * again) that catches the notifications a dropped connection missed. `onSignal` must not
+     * throw; what it throws goes to `onError`, as do listener failures.
+     */
+    followSignals(onSignal: (signal: ControlSignal) => void, options?: FollowSignalsOptions): Promise<SignalFollower>;
+    close(): Promise<void>;
+}
+/**
+ * A signal on the control bus (D21, D48): one process tells the others with the Tenant open.
+ * Signals are not events: they are never recorded in a session's log or streamed, and a
+ * lost one costs latency, never correctness. They never go through S2.
+ */
+export type ControlSignal = {
+    /** The process running the session's advance aborts it. */
+    type: "session.cancel";
+    sessionId: string;
+    /** The cancelled turn: an advance of another turn keeps running. Absent: any advance. */
+    turnId?: string;
+} | {
+    /** The Tenant's sessions were reset and it moved to basin generation `generation`. */
+    type: "sessions.reset";
+    generation: number;
+};
+export interface FollowSignalsOptions {
+    /** How often recent signals are read back. Default 5 s. */
+    pollMs?: number;
+    onError?: (error: unknown) => void;
+}
+export interface SignalFollower {
+    /** Stops following and ends the listener's connection. */
     close(): Promise<void>;
 }
 export interface StoreHealth {
@@ -393,6 +426,13 @@ export interface Tx {
     /** Links of one workflow session joined to their existing agent sessions, ordered by agent session id. */
     linkedSessions<S extends SessionDoc = SessionDoc>(workflowSessionId: string): Promise<LinkedSession<S>[]>;
     counts(): Promise<StoreCounts>;
+    /**
+     * Puts `signal` on the control bus: a row, and a notification Postgres sends every
+     * following process when this transaction commits (and never on rollback).
+     */
+    signal(signal: ControlSignal): Promise<void>;
+    /** Deletes signals written before `before`. Returns how many. */
+    pruneSignals(before: Date): Promise<number>;
     basinGenerations(): Promise<BasinGenerations>;
     /** Forgets a retired generation once its basin is deleted. */
     forgetRetiredGeneration(generation: number): Promise<void>;

package/dist/streams/types.d.ts

@@ -7,7 +7,10 @@
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
  * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
- * | `tenant/control` | `session.cancel`, `sessions.reset` and `action.resolved` signals | API nodes | every process with the Tenant open |
+ *
+ * S2 serves API listeners only (history, SSE, AG-UI, A2A): nothing inside the Runtime signals
+ * through it or waits on it (D48). Signals between processes go over the control bus on
+ * Postgres (`store/postgres/control.ts`).
  *
  * **Basin generations.** A session id is unique within its Tenant's basin generation. A
  * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
@@ -104,38 +107,12 @@ export interface DurableStreams {
     listStreams(tenantId: string, prefix: string): Promise<string[]>;
     close(): Promise<void>;
     /**
-     * Resolves when the backing service answers, rejects otherwise (readiness,
-     * `infra/streams.ts`). Absent for in-process implementations, which are
+     * Resolves when the backing service answers, rejects otherwise (the Tenant's status,
+     * `streamsStatus` in `tenant/streams.ts`; never readiness, D48). Absent for in-process implementations, which are
      * always reachable.
      */
     probe?(signal: AbortSignal): Promise<void>;
 }
 export declare const SESSION_STREAM_PREFIX = "sessions/";
-/** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
-export declare const CONTROL_STREAM = "tenant/control";
 /** The stream of a session: `sessions/<sessionId>`. */
 export declare function sessionStream(sessionId: string): string;
-/**
- * Signals are not events: they are appended directly, never recorded, and a
- * lost signal costs latency, not correctness.
- */
-/** Ends the advance of `sessionId` on the process running it. */
-export interface SessionCancelSignal {
-    type: "session.cancel";
-    sessionId: string;
-    /**
-     * The cancelled turn. Only an advance of this turn stops, so a signal delivered late (an
-     * append retried after S2 returns) never stops a later turn. Absent: any advance stops.
-     */
-    turnId?: string;
-}
-/**
- * The Tenant was reset and moved to basin generation `generation`. Appended to the old
- * generation's `tenant/control`: each process switches its readers to the new basin and
- * ends the streams of sessions the reset deleted.
- */
-export interface SessionsResetSignal {
-    type: "sessions.reset";
-    generation?: number;
-}
-export type ControlSignal = SessionCancelSignal | SessionsResetSignal;

package/dist/streams/types.js

@@ -7,7 +7,10 @@
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
  * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
- * | `tenant/control` | `session.cancel`, `sessions.reset` and `action.resolved` signals | API nodes | every process with the Tenant open |
+ *
+ * S2 serves API listeners only (history, SSE, AG-UI, A2A): nothing inside the Runtime signals
+ * through it or waits on it (D48). Signals between processes go over the control bus on
+ * Postgres (`store/postgres/control.ts`).
  *
  * **Basin generations.** A session id is unique within its Tenant's basin generation. A
  * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
@@ -39,10 +42,8 @@
  *   encode them as they need.
  */
 // ---------------------------------------------------------------------------
-// Stream names and signal records
+// Stream names
 export const SESSION_STREAM_PREFIX = "sessions/";
-/** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
-export const CONTROL_STREAM = "tenant/control";
 /** The stream of a session: `sessions/<sessionId>`. */
 export function sessionStream(sessionId) {
     if (!sessionId)

package/dist/tenant/auth.d.ts

@@ -1,9 +1,10 @@
 /**
  * Tenant request authentication and authorization: a bearer token resolves to an application
- * principal or a trusted issuer's token; anything else is the opaque 404
- * (D5). An application principal may act for a subject (`Nylorun-Subject`, `Nylorun-Scopes`);
- * an issuer token names its subject itself. `requireScopes` limits them to the routes their
- * scopes allow, decided from the route alone.
+ * principal or a trusted issuer's token. Anything else is `401` with a `Bearer` challenge
+ * (protocol 9, `resource-server.ts`): `credential_required` without one, `credential_invalid`
+ * for one the Tenant refuses, its reason only logged. An application principal may act for a
+ * subject (`Nylorun-Subject`, `Nylorun-Scopes`); an issuer token names its subject itself.
+ * `requireScopes` limits them to the routes their scopes allow, decided from the route alone.
  *
  * Browsers: a request with `Origin` may carry an issuer token (CORS is the operator's proxy's),
  * never an application key, which is a server secret.
@@ -21,6 +22,11 @@ export interface KeyAccess {
 }
 /** Every route that does not say otherwise is a Runtime API route. */
 export declare const RUNTIME_KEYS: KeyAccess;
+/**
+ * The `resource_metadata` a route's challenges point at: a Runtime API route's, when the Runtime
+ * trusts issuers. The Management API is no OAuth resource.
+ */
+export declare function challengeMetadata(ctx: TenantContext, request: IncomingMessage, keys: KeyAccess): string | undefined;
 export declare function authenticate(ctx: TenantContext, request: IncomingMessage, keys?: KeyAccess): Promise<AuthScope>;
 /**
  * What a subject needs for a route: any one of the scopes, nothing grants it (`never`), or
@@ -30,9 +36,13 @@ export declare function authenticate(ctx: TenantContext, request: IncomingMessag
 export type SubjectAccess = readonly SubjectScope[] | "never" | "any";
 /**
  * A subject or a token caller reaches a route only with one of the scopes it declares:
- * `403 scope_required`, decided from the route alone before anything is read.
+ * `403 scope_required`, decided from the route alone before anything is read. A token caller
+ * also gets the OAuth challenge (`error="insufficient_scope"` and the scopes that would do), so
+ * its client can ask its identity provider for them; a route no scope reaches has none.
  */
-export declare function requireScopes(scope: AuthScope, access: SubjectAccess): void;
+export declare function requireScopes(scope: AuthScope, access: SubjectAccess, 
+/** The route's `resource_metadata` (`challengeMetadata`), for a token caller's challenge. */
+resourceMetadata?: string): void;
 export declare function accessOf(scope: AuthScope): SessionAccess | undefined;
 /** The subject whose sessions the request is limited to, if it acts for one. */
 export declare function ownerOf(scope: AuthScope): string | undefined;