@cortexkit/subc-client 0.19.0 → 0.21.0

package/src/client.ts

@@ -26,6 +26,7 @@ import {
   type Frame,
 } from "./envelope.js";
 import { launchNonceOrUndefined } from "./launch-nonce.js";
+import type { Principal } from "./provider.js";
 import {
   belongsToConnection,
   createRouteHandle,
@@ -118,7 +119,19 @@ export interface ConsumerIdentity {
   launch_nonce: string;
 }
 
+/** A scope selector; scopeEpoch is required even for the scope's owner. */
+export interface RouteScope {
+  /** Owner principal, passed verbatim. The daemon decides which principal kinds may own scopes. */
+  owner: Principal;
+  /** Opaque, non-empty ref within the owner. */
+  ref: string;
+  /** Safe non-negative integer, including zero; serialized as scope_epoch. */
+  scopeEpoch: number;
+}
+
 export interface RouteOpenOptions {
+  /** Open under this scope. The caller must be its owner or a listed carrier; use a daemon advertising scopes/v1. Serialized as { owner, ref, scope_epoch }. */
+  scope?: RouteScope;
   /** Optional override for the consumer identity; by default the SUBC_MODULE_ID environment variable and the process's launch nonce (see `launchNonce`) are used when both are non-empty; a refused launch-nonce descriptor counts as no nonce. Set null to send route.open without consumer_identity. */
   consumerIdentity?: ConsumerIdentity | null;
   /**
@@ -202,6 +215,8 @@ export interface RequestOptions {
 }
 
 export interface ManagedCallOptions extends RequestOptions {
+  /** Scope for the cached route and its reconnect reopens. The caller must be the scope's owner or a listed carrier; use a daemon advertising scopes/v1. Each owner/ref/epoch has a separate cache entry. */
+  scope?: RouteScope;
   /** Overrides the per-client identity used for route.open before this call. */
   identity?: BindIdentity;
   /** Defaults to management_surface, matching the store/host management APIs. */
@@ -236,6 +251,8 @@ export interface CloseRouteOptions {
 }
 
 export interface ManagedCloseRouteOptions extends CloseRouteOptions {
+  /** Scope selector used by the cached managed route; omitted selects only an unscoped route. */
+  scope?: RouteScope;
   /** Consumer identity used by the cached managed route. */
   consumerIdentity?: ConsumerIdentity | null;
   /** The registry whose derived capability set identifies the cached route. */
@@ -297,6 +314,12 @@ export class SubcCallError extends Error {
   get detail(): unknown {
     return this.cause instanceof SubcError ? this.cause.detail : undefined;
   }
+
+  /** Why the route ended. A reason never makes an in-flight call safe to resend. */
+  get closeReason(): RouteEndReason | undefined {
+    return this.cause instanceof SubcError || this.cause instanceof SubcCallError
+      ? this.cause.closeReason : undefined;
+  }
 }
 
 /**
@@ -324,6 +347,7 @@ export class SubcError extends Error {
      * those reasons at the transport boundary.
      */
     readonly detail?: unknown,
+    readonly closeReason?: RouteEndReason,
   ) {
     super(message);
   }
@@ -404,15 +428,11 @@ export interface ConnectOptions {
    */
   timeoutArbitrationGraceMs?: number;
   /**
-   * Observer for daemon-originated channel-0 control pushes (`route.closing`,
-   * `route.closed`, and any op added later). Purely advisory: the daemon's
-   * load-bearing route-death signal remains the GOODBYE frame, and nothing in
-   * the client's own route lifecycle consumes these. The contract is the wire
-   * contract verbatim -- unrecognized ops still arrive here (callers ignore
-   * what they don't know, per the MUST-ignore clause), a push that fails to
-   * parse as JSON is dropped without surfacing, and an observer throw is
-   * swallowed like every other caller callback so it cannot fail the read loop
-   * or unrelated requests.
+   * Observer for parsed daemon control pushes, including unrecognized ops which
+   * callers should ignore. Malformed JSON is dropped and observer exceptions are
+   * swallowed so they cannot fail unrelated requests. The client records route
+   * reasons before notifying the observer, but closes routes only on the separate
+   * GOODBYE frame, never on a control push.
    */
   onControlPush?: (push: ControlPush) => void;
 }
@@ -431,11 +451,18 @@ export type KnownRouteCloseReason =
   | "restart"
   | "disable"
   | "crash"
-  | "capability_denied";
+  | "capability_denied"
+  | "scope_ended"
+  | "scope_carrier_removed"
+  | "scope_delegation_changed"
+  | "scope_parent_ended";
 
 /** A route-close reason decoded from a daemon control push. */
 export type RouteCloseReason = KnownRouteCloseReason | "unknown";
 
+/** Why a route ended. Even a planned closure can leave a call's outcome unknown. */
+export type RouteEndReason = RouteCloseReason | "closed_by_caller" | "connection_lost";
+
 /** Whether the close reason alone permits reopening a route automatically. */
 export type RouteCloseDisposition = "may_reopen" | "must_not_reopen";
 
@@ -452,6 +479,10 @@ export function parseRouteCloseReason(reason: unknown): RouteCloseReason {
     case "disable":
     case "crash":
     case "capability_denied":
+    case "scope_ended":
+    case "scope_carrier_removed":
+    case "scope_delegation_changed":
+    case "scope_parent_ended":
       return reason;
     default:
       return "unknown";
@@ -467,6 +498,10 @@ export function classifyRouteCloseReason(reason: unknown): RouteCloseDisposition
     case "disable":
     case "crash":
     case "capability_denied":
+    case "scope_ended":
+    case "scope_carrier_removed":
+    case "scope_delegation_changed":
+    case "scope_parent_ended":
     case "unknown":
       return "must_not_reopen";
   }
@@ -579,6 +614,9 @@ interface CachedRoute {
   moduleId: string;
   target: Extract<RouteTarget, { kind: ManagedRouteKind }>;
   identity: BindIdentity;
+  scope?: RouteScope;
+  /** A terminal daemon close must survive connection replacement, not become a reopen. */
+  endReason?: RouteCloseReason;
   consumerIdentity?: ConsumerIdentity;
   reverseRequests: ReverseRequestRegistry;
   handle: RouteHandle | null;
@@ -600,6 +638,9 @@ export class SubcClient {
   private readonly lateResponses = new Map<string, (frame: Frame) => void>();
   private readonly routes = new Map<string, CachedRoute>();
   private readonly liveRoutes = new Map<number, RouteHandle>();
+  private readonly routeModules = new Map<number, string>();
+  private readonly routeEndReasons = new Map<number, { reason: RouteCloseReason; final: boolean }>();
+  private readonly legacyChannelReasons = new Map<number, RouteCloseReason>();
   private connectionToken = newConnectionToken();
   private ingressEpochDropCount = 0;
   private closedErr: Error | null = null;
@@ -687,12 +728,14 @@ export class SubcClient {
    * Open a route and return its connection-bound immutable handle. At most
    * MAX_ROUTE_OPENS_IN_FLIGHT opens are outstanding at once; further calls wait
    * their turn.
+   * A scoped open requires the caller to be the scope's owner or a listed carrier.
    */
   async routeOpen(target: RouteTarget, identity: BindIdentity, opts: RouteOpenOptions = {}): Promise<RouteHandle> {
+    const scope = validatedRouteScope(opts.scope);
     // Without a timeout the gate always grants a slot eventually.
     const release = (await this.routeOpenGate.acquire())!;
     try {
-      return await this.sendRouteOpen(target, identity, opts);
+      return await this.sendRouteOpen(target, identity, { ...opts, scope });
     } finally {
       release();
     }
@@ -704,6 +747,7 @@ export class SubcClient {
     identity: BindIdentity,
     opts: RouteOpenOptions = {},
   ): Promise<RouteHandle> {
+    const scope = validatedRouteScope(opts.scope);
     const consumerIdentity = routeOpenConsumerIdentity(opts);
     const reverseRequests = opts.reverseRequests ?? new ReverseRequestRegistry();
     reverseRequests.seal();
@@ -714,6 +758,7 @@ export class SubcClient {
       identity,
       ...(consumerIdentity ? { consumer_identity: consumerIdentity } : {}),
       ...(consumerCapabilities.length > 0 ? { consumer_capabilities: consumerCapabilities } : {}),
+      ...(scope ? { scope: { owner: scope.owner, ref: scope.ref, scope_epoch: scope.scopeEpoch } } : {}),
     });
 
     let installed: RouteHandle | null = null;
@@ -724,6 +769,7 @@ export class SubcClient {
         throw new SubcError(`route.open returned no route handle: ${JSON.stringify(parsed)}`);
       }
       installed = this.installRoute(parsed.route_channel, parsed.route_epoch, reverseRequests);
+      this.routeModules.set(parsed.route_channel, target.module_id);
       return true;
     };
     const closeLateRoute = (frame: Frame): void => {
@@ -732,7 +778,7 @@ export class SubcClient {
         const parsed = this.parseJson(frame) as { route_channel?: number; route_epoch?: number };
         if (typeof parsed.route_channel !== "number" || typeof parsed.route_epoch !== "number") return;
         const lateHandle = this.installRoute(parsed.route_channel, parsed.route_epoch);
-        this.failHandle(lateHandle, new SubcError("late route.open was closed", "route_closed"));
+        this.failHandle(lateHandle, new SubcError("late route.open was closed", "route_closed", undefined, "closed_by_caller"));
         this.liveRoutes.delete(lateHandle.channel);
         this.sendRouteGoodbye(lateHandle, true);
       } catch {
@@ -770,6 +816,8 @@ export class SubcClient {
   /**
    * Managed route + request convenience. Opens and caches a route for the module,
    * reconnecting and re-opening cached routes after connection drops.
+   * Scoped routes are isolated by owner/ref/epoch and require owner or carrier authority.
+   * Terminal scope close reasons prevent automatic reopens under the same selector.
    */
   async call<Response = unknown>(
     moduleId: string,
@@ -1018,7 +1066,7 @@ export class SubcClient {
       }
     }
     if (opts.drain) await this.drainUnaryOnHandle(handle);
-    this.failHandle(handle, new SubcError("route closed by closeRoute", "route_closed"));
+    this.failHandle(handle, new SubcError("route closed by closeRoute", "route_closed", undefined, "closed_by_caller"));
     if (this.liveRoutes.get(handle.channel) === handle) this.liveRoutes.delete(handle.channel);
     this.sendRouteGoodbye(handle);
   }
@@ -1034,6 +1082,7 @@ export class SubcClient {
       identity,
       routeOpenConsumerIdentity(opts),
       (opts.reverseRequests ?? new ReverseRequestRegistry()).capabilities(),
+      validatedRouteScope(opts.scope),
     );
     const cached = this.routes.get(key);
     if (!cached) return;
@@ -1161,11 +1210,13 @@ export class SubcClient {
       };
       pending.timer = setTimeout(() => this.arbitrateTimeout(key, pending, channel, corr, ms), ms);
       this.pending.set(key, pending);
-      if (signal) this.attachCancelSignal(signal, key, handle, corr, priority);
       writeBorrowed(this.sock, encodeFrame(frame), Date.now() + ms).catch((error) => {
         const current = this.pending.get(key);
         if (current) this.rejectPending(key, current, error instanceof Error ? error : new SubcError(String(error)));
       });
+      // Queue REQUEST first: an already-aborted signal emits CANCEL immediately,
+      // and the daemon can only cancel a correlation it has already received.
+      if (signal) this.attachCancelSignal(signal, key, handle, corr, priority);
     });
   }
 
@@ -1292,17 +1343,19 @@ export class SubcClient {
       };
       pending.timer = setTimeout(() => this.arbitrateTimeout(key, pending, handle.channel, corr, ms), ms);
       this.pending.set(key, pending);
-      if (signal) this.attachCancelSignal(signal, key, handle, corr, priority);
       const write = writeTrackedBorrowed(this.sock, encodeFrame(frame), Date.now() + ms);
       handedToSocket = write.queued;
       write.completed.catch((error) => {
         const current = this.pending.get(key);
         if (current) this.rejectPending(key, current, error instanceof Error ? error : new SubcError(String(error)));
       });
+      // Preserve REQUEST/CANCEL order even when the signal was already aborted.
+      if (signal && write.queued) this.attachCancelSignal(signal, key, handle, corr, priority);
     });
   }
 
   private async cachedRouteHandle(moduleId: string, opts: ManagedCallOptions): Promise<RouteHandle> {
+    const scope = validatedRouteScope(opts.scope);
     const identity = opts.identity ?? this.opts.identity;
     if (!identity) {
       throw new SubcCallError(
@@ -1318,7 +1371,7 @@ export class SubcClient {
     const consumerIdentity = routeOpenConsumerIdentity(opts);
     const reverseRequests = opts.reverseRequests ?? new ReverseRequestRegistry();
     reverseRequests.seal();
-    const key = routeCacheKey(target, identity, consumerIdentity, reverseRequests.capabilities());
+    const key = routeCacheKey(target, identity, consumerIdentity, reverseRequests.capabilities(), scope);
     let cached = this.routes.get(key);
     if (!cached) {
       cached = {
@@ -1326,6 +1379,7 @@ export class SubcClient {
         moduleId,
         target,
         identity,
+        scope,
         consumerIdentity,
         reverseRequests,
         handle: null,
@@ -1333,6 +1387,7 @@ export class SubcClient {
       };
       this.routes.set(key, cached);
     }
+    if (cached.endReason !== undefined) throw this.endedCachedRoute(cached.endReason);
     if (cached.handle && this.isLiveHandle(cached.handle)) return cached.handle;
     // The retries end at the retry deadline or at the call's own timeoutMs,
     // whichever comes first. Without timeoutMs the call has no overall deadline
@@ -1378,6 +1433,7 @@ export class SubcClient {
     const refusals = new RouteOpenRefusals();
     for (;;) {
       if (cached.closed) throw this.routeClosedDuringOpen();
+      if (cached.endReason !== undefined) throw this.endedCachedRoute(cached.endReason);
       try {
         await this.ensureConnectedForManaged();
       } catch (error) {
@@ -1392,6 +1448,7 @@ export class SubcClient {
       try {
         outcome = {
           handle: await this.sendRouteOpen(cached.target, cached.identity, {
+            scope: cached.scope,
             consumerIdentity: cached.consumerIdentity ?? null,
             reverseRequests: cached.reverseRequests,
           }),
@@ -1650,9 +1707,10 @@ export class SubcClient {
     }
     for (const key of routeKeys) {
       const cached = this.routes.get(key);
-      if (!cached || cached.closed) continue;
+      if (!cached || cached.closed || cached.endReason !== undefined) continue;
       try {
         const handle = await this.routeOpen(cached.target, cached.identity, {
+          scope: cached.scope,
           consumerIdentity: cached.consumerIdentity ?? null,
           reverseRequests: cached.reverseRequests,
         });
@@ -1683,7 +1741,13 @@ export class SubcClient {
   }
 
   private routeClosedDuringOpen(): SubcCallError {
-    return new SubcCallError("not_sent", "route was closed before route.open completed", "route_closed");
+    const cause = new SubcError("route was closed before route.open completed", "route_closed", undefined, "closed_by_caller");
+    return new SubcCallError("not_sent", cause.message, cause.code, cause);
+  }
+
+  private endedCachedRoute(reason: RouteCloseReason): SubcCallError {
+    const cause = new SubcError(`cached route closed by subc (${reason}); must not reopen`, "route_closed", undefined, reason);
+    return this.terminalCallError(cause.message, cause);
   }
 
   private async readLoop(sock: SubcSocket, generation: number): Promise<void> {
@@ -1726,12 +1790,12 @@ export class SubcClient {
     if (frame.header.channel === 0 && frame.header.ty === FrameType.Push) {
       // Daemon-originated control push (route.closing / route.closed / future
       // ops). Never matches a pending (corr is daemon-chosen), never an error
-      // path: unparseable bodies and absent observers both drop silently per
-      // the wire contract's MUST-ignore clause, and an observer throw is
+      // path: unparseable bodies drop silently. Reasons are recorded even without
+      // an observer, and an observer throw is
       // swallowed for the same reason as onProgress below -- a caller callback
       // must not fail the read loop.
       const observer = this.opts.onControlPush;
-      if (observer) {
+      {
         let parsed: ControlPush | null = null;
         try {
           const body = this.parseJson(frame) as Record<string, unknown>;
@@ -1740,8 +1804,9 @@ export class SubcClient {
           // Unparseable control push: ignored by contract.
         }
         if (parsed) {
+          this.recordRouteEnd(parsed);
           try {
-            observer(parsed);
+            observer?.(parsed);
           } catch {
             // Observer's own throw, on its own stack; the stream must survive.
           }
@@ -1823,7 +1888,8 @@ export class SubcClient {
       // so it stays kind=outcome_unknown -- the same class as a mid-flight socket
       // drop, and never the not_sent/unknown_channel class that call() retries.
       // The code says WHICH route ended, not that it is safe to send again.
-      this.failHandle(handle, new SubcError("route closed by subc (GOODBYE)", "route_closed"));
+      this.failHandle(handle, new SubcError("route closed by subc (GOODBYE)", "route_closed", undefined, this.routeEndReason(handle.channel)));
+      this.preventRouteReopen(handle.channel, this.routeEndReason(handle.channel));
       if (this.liveRoutes.get(handle.channel) === handle) this.liveRoutes.delete(handle.channel);
       this.evictRouteHandle(handle);
       return;
@@ -1990,6 +2056,43 @@ export class SubcClient {
     }
   }
 
+  private recordRouteEnd(push: ControlPush): void {
+    const reason = routeCloseReason(push);
+    if (reason === undefined) return;
+    if ("channels" in push.body) {
+      if (Array.isArray(push.body.channels)) {
+        for (const channel of push.body.channels) {
+          if (typeof channel !== "number" || !Number.isInteger(channel) || channel < 0 || channel > 65535) continue;
+          const final = push.op === "route.closed";
+          if (final || !this.routeEndReasons.get(channel)?.final) {
+            this.routeEndReasons.set(channel, { reason, final });
+            if (final) this.preventRouteReopen(channel, reason);
+          }
+        }
+      }
+    } else if (typeof push.body.module_id === "string") {
+      for (const [channel, module] of this.routeModules) {
+        if (module === push.body.module_id) {
+          this.legacyChannelReasons.set(channel, reason);
+          if (push.op === "route.closed") this.preventRouteReopen(channel, reason);
+        }
+      }
+    }
+  }
+
+  private preventRouteReopen(channel: number, reason: RouteCloseReason): void {
+    if (classifyRouteCloseReason(reason) !== "must_not_reopen") return;
+    for (const cached of this.routes.values()) {
+      if (cached.handle?.channel === channel) cached.endReason = reason;
+    }
+  }
+
+  private routeEndReason(channel: number): RouteCloseReason {
+    const specific = this.routeEndReasons.get(channel);
+    if (specific) return specific.reason;
+    return this.legacyChannelReasons.get(channel) ?? "unknown";
+  }
+
   private failHandle(handle: RouteHandle, error: Error): void {
     for (const [key, pending] of this.pending) {
       if (pending.handle && sameRouteHandle(pending.handle, handle)) this.rejectPending(key, pending, error);
@@ -1997,9 +2100,15 @@ export class SubcClient {
   }
 
   private fail(err: Error): void {
+    const routeError = err instanceof SubcError && err.closeReason ? err
+      : new SubcError(err.message, errorCode(err), undefined,
+        this.closeStarted ? "closed_by_caller" : "connection_lost");
     if (!this.closedErr) this.closedErr = err;
+    this.routeEndReasons.clear();
+    this.legacyChannelReasons.clear();
+    this.routeModules.clear();
     for (const [key, pending] of this.pending) {
-      this.rejectPending(key, pending, err);
+      this.rejectPending(key, pending, pending.handle ? routeError : err);
     }
   }
 
@@ -2033,6 +2142,9 @@ export class SubcClient {
     reverseRequests = new ReverseRequestRegistry(),
   ): RouteHandle {
     const handle = createRouteHandle(channel, epoch, this.connectionToken, reverseRequests);
+    this.routeEndReasons.delete(channel);
+    this.legacyChannelReasons.delete(channel);
+    this.routeModules.delete(channel);
     this.liveRoutes.set(channel, handle);
     return handle;
   }
@@ -2134,6 +2246,8 @@ function isRouteOpenRefusal(err: unknown): err is SubcError & { code: string } {
 export function isRetryableRouteOpenCode(code: string | undefined): boolean {
   // A capability deny is policy, never a transient target-availability failure.
   if (code === "capability_forbidden") return false;
+  // Decoding a flow stamp alone does not promise flow behaviour.
+  if (code === "target_flow_unsupported") return false;
   return (
     code === "module_reloading" ||
     code === "module_warming" ||
@@ -2258,12 +2372,37 @@ function routeCacheKey(
   identity: BindIdentity,
   consumerIdentity: ConsumerIdentity | undefined,
   consumerCapabilities: readonly string[],
+  scope?: RouteScope,
 ): string {
   const consumerPart = consumerIdentity
     ? `${consumerIdentity.module_id}\0${consumerIdentity.launch_nonce}`
     : "";
   const capabilitiesPart = [...consumerCapabilities].sort().join("\0");
-  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}\0${capabilitiesPart}`;
+  // A JSON tuple keeps opaque refs (including embedded separators) distinct.
+  const scopePart = scope
+    ? JSON.stringify([scope.owner.kind, scope.owner.kind === "reserved" ? scope.owner.module_id : null, scope.ref, scope.scopeEpoch])
+    : "";
+  return `${target.kind}\0${target.module_id}\0${identity.project_root}\0${identity.harness}\0${identity.session}\0${consumerPart}\0${capabilitiesPart}\0${scopePart}`;
+}
+
+/** Validate before any route-open I/O, and snapshot caller-owned mutable values for reopens. */
+function validatedRouteScope(scope: RouteScope | undefined): RouteScope | undefined {
+  if (scope === undefined) return undefined;
+  if (!scope || typeof scope.owner !== "object" || !scope.owner ||
+      !["reserved", "direct", "unverified"].includes(scope.owner.kind) ||
+      (scope.owner.kind === "reserved" && (typeof scope.owner.module_id !== "string" || scope.owner.module_id.length === 0))) {
+    throw new SubcError("scope.owner must be a Principal with a non-empty reserved module_id", "invalid_scope");
+  }
+  if (typeof scope.ref !== "string" || scope.ref.length === 0) {
+    throw new SubcError("scope.ref must be a non-empty string", "invalid_scope");
+  }
+  if (scope.scopeEpoch === undefined) {
+    throw new SubcError("scope.scopeEpoch is required", "scope_epoch_required");
+  }
+  if (!Number.isSafeInteger(scope.scopeEpoch) || scope.scopeEpoch < 0) {
+    throw new SubcError("scope.scopeEpoch must be a safe non-negative integer", "invalid_scope");
+  }
+  return { owner: { ...scope.owner }, ref: scope.ref, scopeEpoch: scope.scopeEpoch };
 }
 
 function routeOpenConsumerIdentity(opts: RouteOpenOptions = {}): ConsumerIdentity | undefined {

package/src/connection-file.ts

@@ -1,8 +1,8 @@
 // Port of subc-transport's connection_file.rs reader. The connection file is
 // the daemon's published rendezvous record; its `key` is the shared transport
-// secret. We refuse to trust a key from a file other local users can read,
-// exactly as the Rust reader does, so a leaked (group/world-readable) key is a
-// loud failure rather than a silent downgrade.
+// secret. We refuse to trust a key from a file another local user owns or can
+// read, exactly as the Rust reader does, so a substituted or leaked
+// (group/world-readable) key is a loud failure rather than a silent downgrade.
 
 import { promises as fs } from "node:fs";
 
@@ -64,14 +64,22 @@ function validate(info: ConnectionInfo): void {
 }
 
 /**
- * On unix, reject any group/other permission bit: the key is published
- * owner-only (0600), so a wider mode means the secret has leaked. On Windows the
+ * On unix, refuse a file owned by anyone but `expectedUid`, then any
+ * group/other permission bit. A file another user owns is untrusted even at
+ * 0600: its owner could have written their own endpoint and key, and this
+ * client would then authenticate to them. A wider mode on our own file means the
+ * secret has leaked. `expectedUid` is undefined where the platform has no
+ * effective uid (Windows), and the owner check is skipped there. On Windows the
  * file inherits the per-user profile directory ACL at create time and there are
  * no portable mode bits to re-check, matching the Rust no-op.
  */
-async function verifyOwnerOnly(path: string): Promise<void> {
+function verifyOwnerOnly(path: string, stat: { uid: number; mode: number }, expectedUid: number | undefined): void {
   if (process.platform === "win32") return;
-  const stat = await fs.stat(path);
+  if (expectedUid !== undefined && stat.uid !== expectedUid) {
+    throw new ConnectionFileError(
+      `connection file ${path} is owned by uid ${stat.uid}, expected effective uid ${expectedUid}`,
+    );
+  }
   const mode = stat.mode & 0o777;
   if ((mode & 0o077) !== 0) {
     throw new ConnectionFileError(
@@ -80,10 +88,29 @@ async function verifyOwnerOnly(path: string): Promise<void> {
   }
 }
 
-/** Read, permission-check, and validate a connection file. */
+/** Read, ownership- and permission-check, and validate a connection file. */
 export async function readConnectionFile(path: string): Promise<ConnectionInfo> {
-  await verifyOwnerOnly(path);
-  const raw = await fs.readFile(path, "utf8");
+  return readConnectionFileForUid(path, process.geteuid?.());
+}
+
+/**
+ * @internal `readConnectionFile` with the expected owner uid supplied by the
+ * caller, so tests can present a foreign owner without changing the process uid.
+ */
+export async function readConnectionFileForUid(
+  path: string,
+  expectedUid: number | undefined,
+): Promise<ConnectionInfo> {
+  // Check the opened file, not a second lookup of the path: if the path were
+  // replaced between a stat and the read, an unchecked key would get through.
+  const handle = await fs.open(path, "r");
+  let raw: string;
+  try {
+    verifyOwnerOnly(path, await handle.stat(), expectedUid);
+    raw = await handle.readFile({ encoding: "utf8" });
+  } finally {
+    await handle.close();
+  }
   let parsed: Record<string, unknown>;
   try {
     parsed = JSON.parse(raw) as Record<string, unknown>;

package/src/envelope.ts

@@ -172,18 +172,19 @@ function validateHeaderFields(header: EnvelopeHeader): void {
       "sheddable_illegal_frame_type",
     );
   }
-  if (channel === 0 && epoch !== 0) {
-    throw new DecodeError(
-      `control channel carried nonzero epoch ${epoch}`,
-      "nonzero_epoch_on_control_channel",
-    );
-  }
+  // Match the wire decoder's precedence when a header violates both rules.
   if (isPureHeader(ty) && len !== 0) {
     throw new DecodeError(
       `pure-header frame ${FrameType[ty]} declared non-zero body length ${len}`,
       "pure_header_frame_with_body",
     );
   }
+  if (channel === 0 && epoch !== 0) {
+    throw new DecodeError(
+      `control channel carried nonzero epoch ${epoch}`,
+      "nonzero_epoch_on_control_channel",
+    );
+  }
 }
 
 /** Decode and validate a header from the front of `bytes`. */
@@ -233,18 +234,19 @@ export function decodeHeader(bytes: Uint8Array): EnvelopeHeader {
   }
   const channel = view.getUint16(7, true);
   const epoch = view.getUint32(9, true);
-  if (channel === 0 && epoch !== 0) {
-    throw new DecodeError(
-      `control channel carried nonzero epoch ${epoch}`,
-      "nonzero_epoch_on_control_channel",
-    );
-  }
+  // Body length is checked before the control epoch in Rust and Swift too.
   if (isPureHeader(ty) && len !== 0) {
     throw new DecodeError(
       `pure-header frame ${FrameType[ty]} declared non-zero body length ${len}`,
       "pure_header_frame_with_body",
     );
   }
+  if (channel === 0 && epoch !== 0) {
+    throw new DecodeError(
+      `control channel carried nonzero epoch ${epoch}`,
+      "nonzero_epoch_on_control_channel",
+    );
+  }
   return { len, ver, ty, flags, channel, epoch, corr: view.getBigUint64(13, true) };
 }
 
@@ -278,7 +280,17 @@ export function buildFrameWithVersion(
   return { header, body };
 }
 
-/** Encode a frame to wire bytes: header followed by exactly `len` body bytes. */
+/**
+ * Encode a frame to wire bytes: header followed by exactly `len` body bytes.
+ *
+ * Refuses, before producing any bytes, a frame the peer's decoder would reject:
+ * a header that fails any wire decode rule, or a body over MAX_FRAME_BODY_LEN.
+ * A `Frame` can be assembled by hand without going through `buildFrame`, and
+ * once a rejected header is on the socket the peer tears the whole connection
+ * down, so the refusal has to happen here rather than on the far side. The
+ * header check runs the encoded bytes through `decodeHeader` itself, so the
+ * writer cannot drift from the reader's rules.
+ */
 export function encodeFrame(frame: Frame): Uint8Array {
   if (frame.header.len !== frame.body.length) {
     throw new DecodeError(
@@ -286,7 +298,14 @@ export function encodeFrame(frame: Frame): Uint8Array {
       "frame_length_mismatch",
     );
   }
+  if (frame.body.length > MAX_FRAME_BODY_LEN) {
+    throw new DecodeError(
+      `frame body ${frame.body.length} exceeds max ${MAX_FRAME_BODY_LEN}`,
+      "frame_body_too_large",
+    );
+  }
   const header = encodeHeader(frame.header);
+  decodeHeader(header);
   const output = new Uint8Array(header.length + frame.body.length);
   output.set(header, 0);
   output.set(frame.body, header.length);

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   type RouteTarget,
   type ManagedRouteKind,
   type ConsumerIdentity,
+  type RouteScope,
   type RouteOpenOptions,
   type CatalogCapabilities,
   type CatalogCapabilityRequirement,
@@ -29,6 +30,7 @@ export {
   type ControlPush,
   type KnownRouteCloseReason,
   type RouteCloseReason,
+  type RouteEndReason,
   type RouteCloseDisposition,
   type ReconnectBackoff,
   type SubcCallErrorKind,