githolon 0.113.2 → 0.113.3

package/dist/compile_mountability_entry.js

@@ -7050,6 +7050,37 @@ var init_kernel_port = __esm({
   }
 });
 
+// ../peer-office/src/runtime/http_origin.ts
+function httpOrigin(url) {
+  const match = AUTHORITY.exec(url.trim());
+  if (!match) return void 0;
+  const scheme = match[1].toLowerCase();
+  if (scheme !== "http" && scheme !== "https") return void 0;
+  const authority = match[2];
+  const hostAndPort = authority.slice(authority.lastIndexOf("@") + 1);
+  const ipv6 = /^(\[[0-9a-f:.]+\])(?::(\d*))?$/i.exec(hostAndPort);
+  const named = /^([^:[\]\s]+)(?::(\d*))?$/.exec(hostAndPort);
+  const parts = ipv6 ?? named;
+  if (!parts) return void 0;
+  const host = parts[1].toLowerCase();
+  if (host.length === 0 || /[\s<>^`{|}%\\]/.test(host)) return void 0;
+  let port = parts[2] ?? "";
+  if (port !== "") {
+    const value = Number(port);
+    if (!Number.isInteger(value) || value > 65535) return void 0;
+    port = String(value);
+  }
+  return port === "" || port === DEFAULT_PORTS[scheme] ? `${scheme}://${host}` : `${scheme}://${host}:${port}`;
+}
+var AUTHORITY, DEFAULT_PORTS;
+var init_http_origin = __esm({
+  "../peer-office/src/runtime/http_origin.ts"() {
+    "use strict";
+    AUTHORITY = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+    DEFAULT_PORTS = { http: "80", https: "443" };
+  }
+});
+
 // ../peer-office/src/git_read_lease.ts
 import { fromBinary as fromBinary5 } from "@bufbuild/protobuf";
 function decodeGitReadLease(bytes, workspace, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1e3))) {
@@ -7401,6 +7432,7 @@ var stableIdentifier, normalizeProfile, originOf2, ReplicaPlacementDirectiveKind
 var init_placement_desk = __esm({
   "../peer-office/src/runtime/placement_desk.ts"() {
     "use strict";
+    init_http_origin();
     init_provider_origins();
     init_kernel_pb();
     init_placement_desk_pb();
@@ -7425,14 +7457,7 @@ var init_placement_desk = __esm({
         ...servedOrigin === void 0 ? {} : { servedOrigin }
       });
     };
-    originOf2 = (url) => {
-      try {
-        const parsed = new URL(url);
-        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : void 0;
-      } catch {
-        return void 0;
-      }
-    };
+    originOf2 = httpOrigin;
     ReplicaPlacementDirectiveKind = Object.freeze({
       None: "none",
       Cache: "cache",
@@ -13599,7 +13624,10 @@ var init_read_maintenance_desk = __esm({
           ...background ? { background } : {},
           ...awaited || existing?.awaited ? { awaited: true } : {},
           failures: existing?.failures ?? 0,
-          retryNotBeforeNanoseconds: 0n
+          // A foreground read may retry at once. Upkeep owed by a write or a sync keeps any back-off
+          // it is already serving: otherwise every write retried a failing upkeep immediately, and a
+          // workspace whose upkeep could not succeed retried on every write (CAP-693).
+          retryNotBeforeNanoseconds: isReadDemand ? 0n : existing?.retryNotBeforeNanoseconds ?? 0n
         });
         if (isReadDemand && (!existing?.read || existing.read.owedByAdvance)) {
           const entries = [...this.#pending.entries()];
@@ -14248,18 +14276,17 @@ var init_subscription_manager = __esm({
       #requestReadMaintenance;
       #clock;
       #subscriptions = /* @__PURE__ */ new Map();
-      /** Watches owed a re-read, drained one query group per turn when a turn scheduler is given. */
+      /** Watches owed a re-read, drained one query group per office turn (see [drainOwedTurn]). */
       #owed = /* @__PURE__ */ new Set();
-      #nextTurn;
-      #draining = false;
+      #deferRefreshes;
       #sequence = 0n;
-      constructor(queries, sessions, events, requestReadMaintenance, clock, nextTurn) {
+      constructor(queries, sessions, events, requestReadMaintenance, clock, deferRefreshes = false) {
         this.#queries = queries;
         this.#sessions = sessions;
         this.#events = events;
         this.#requestReadMaintenance = requestReadMaintenance;
         this.#clock = clock;
-        this.#nextTurn = nextTurn;
+        this.#deferRefreshes = deferRefreshes;
       }
       start(request, command) {
         if (!command.subscriptionId) throw new Error("watch requires a subscription identity");
@@ -14365,34 +14392,33 @@ var init_subscription_manager = __esm({
        * or replace current authorization. Each watch still owns its delivery state.
        */
       #refreshMatching(matches, cause) {
-        if (this.#nextTurn && !cause) {
+        if (this.#deferRefreshes && !cause) {
           for (const [id, subscription] of this.#subscriptions) {
             if (subscription.request.query && matches(subscription)) this.#owed.add(id);
           }
-          this.#drain();
           return;
         }
         this.#refreshGroups(this.#groups(matches), cause);
       }
-      #drain() {
-        if (this.#draining || this.#owed.size === 0) return;
-        this.#draining = true;
-        this.#nextTurn(() => {
-          this.#draining = false;
-          if (this.#owed.size === 0) return;
-          const first = this.#owed.values().next().value;
-          const lead = this.#subscriptions.get(first);
-          if (!lead?.request.query) {
-            this.#owed.delete(first);
-          } else {
-            const declaration = toBinary15(QueryRequestSchema, lead.request.query);
-            const session = lead.request.session;
-            const group = this.#groups((subscription) => subscription.request.session === session && this.#owed.has(subscription.request.subscriptionId) && sameBytes(toBinary15(QueryRequestSchema, subscription.request.query), declaration));
-            for (const each of group) for (const watch of each.watches) this.#owed.delete(watch.request.subscriptionId);
-            this.#refreshGroups(group);
-          }
-          this.#drain();
-        });
+      /** Whether any watch is owed a re-read: the office's next drive() is due at once. */
+      get owesRefresh() {
+        return this.#owed.size > 0;
+      }
+      /** One office turn of owed re-reads: the first owed watch's query group. False when none was owed. */
+      drainOwedTurn() {
+        if (this.#owed.size === 0) return false;
+        const first = this.#owed.values().next().value;
+        const lead = this.#subscriptions.get(first);
+        if (!lead?.request.query) {
+          this.#owed.delete(first);
+          return true;
+        }
+        const declaration = toBinary15(QueryRequestSchema, lead.request.query);
+        const session = lead.request.session;
+        const group = this.#groups((subscription) => subscription.request.session === session && this.#owed.has(subscription.request.subscriptionId) && sameBytes(toBinary15(QueryRequestSchema, subscription.request.query), declaration));
+        for (const each of group) for (const watch of each.watches) this.#owed.delete(watch.request.subscriptionId);
+        this.#refreshGroups(group);
+        return true;
       }
       #groups(matches) {
         const groups = [];
@@ -14512,6 +14538,44 @@ var init_subscription_manager = __esm({
   }
 });
 
+// ../peer-office/src/runtime/shell_contract.ts
+function declaredShellContract(scope = globalThis) {
+  const declared = scope.__nomosShellContract;
+  return declared === void 0 ? 1 : Number(declared);
+}
+function assertShellContract(scope = globalThis) {
+  const declared = declaredShellContract(scope);
+  if (!Number.isInteger(declared) || declared < SHELL_CONTRACT_MINIMUM) {
+    throw new Error(`nomos.runtime.shell_contract_unsupported: this runtime needs shell contract ${SHELL_CONTRACT_MINIMUM} or later; the shell declares ${String(declared)}`);
+  }
+}
+var SHELL_CONTRACT_V1, SHELL_CONTRACT_V2, SHELL_CONTRACT_MINIMUM;
+var init_shell_contract = __esm({
+  "../peer-office/src/runtime/shell_contract.ts"() {
+    "use strict";
+    SHELL_CONTRACT_V1 = Object.freeze({
+      version: 1,
+      /** Host globals beyond ECMAScript 2022, which every shell supplies. */
+      host: Object.freeze(["TextEncoder", "TextDecoder", "queueMicrotask", "console"]),
+      /** Nomos bridges a native bootstrap installs for the ports it hands to peerOffice.open. */
+      bridges: Object.freeze([
+        "__nomosKernel",
+        "__nomosCredentialVault",
+        "__nomosProfile",
+        "__nomosObservations",
+        "__nomosCustodyStorage",
+        "__nomosPeerDeskStore",
+        "__nomosSyncDiagnostic",
+        "__nomosShellContract"
+      ]),
+      /** Globals the runtime may only probe: used behind their own `typeof` test, never bare. */
+      probed: Object.freeze(["process", "Deno", "Bun", "define"])
+    });
+    SHELL_CONTRACT_V2 = Object.freeze({ ...SHELL_CONTRACT_V1, version: 2 });
+    SHELL_CONTRACT_MINIMUM = 1;
+  }
+});
+
 // ../peer-office/src/runtime/replica_follow_state.ts
 function reduceReplicaFollow(state, event, policy) {
   switch (event.case) {
@@ -22741,6 +22805,7 @@ var init_peer_office = __esm({
     init_residency_pins();
     init_maintenance_desk_pb();
     init_subscription_manager();
+    init_shell_contract();
     init_replica_follow_controller();
     init_replica_follow_desk();
     init_local_copy_drop();
@@ -22937,10 +23002,9 @@ var init_peer_office = __esm({
           this.#trace,
           (session) => this.#readMaintenance.schedule(session, ReadMaintenanceCause.READ_DEBT),
           observations,
-          // An interactive peer keeps its thread responsive while watches catch up.
-          this.#interactivePeer ? (run2) => {
-            setTimeout(run2, 0);
-          } : void 0
+          // An interactive peer keeps its thread responsive while watches catch up: owed re-reads
+          // wait for its drive() turns.
+          this.#interactivePeer
         );
         this.#application = new ApplicationDesk({
           onAdmitted: (session) => {
@@ -23347,7 +23411,9 @@ var init_peer_office = __esm({
        * mirrors queue/backoff state.
        */
       drive() {
-        return this.#maintenance.drive();
+        if (this.#subscriptions.drainOwedTurn()) return 0n;
+        const wake = this.#maintenance.drive();
+        return this.#subscriptions.owesRefresh ? 0n : wake;
       }
       /**
        * Carry one exact maintenance demand through a durable host continuation.
@@ -24308,6 +24374,7 @@ var init_peer_office = __esm({
     };
     peerOffice = {
       open(kernel, credentials, profile, observations, custodyStorage, peerDeskStore) {
+        assertShellContract();
         return new PeerOffice(kernel, credentials, profile, observations, custodyStorage, peerDeskStore);
       },
       Peer: PeerOffice

package/dist/dev-server.mjs

@@ -4954,6 +4954,31 @@ var KernelPort = class {
 // ../peer-office/src/runtime/placement_desk.ts
 import { create as create14 } from "@bufbuild/protobuf";
 
+// ../peer-office/src/runtime/http_origin.ts
+var AUTHORITY = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+var DEFAULT_PORTS = { http: "80", https: "443" };
+function httpOrigin(url) {
+  const match = AUTHORITY.exec(url.trim());
+  if (!match) return void 0;
+  const scheme = match[1].toLowerCase();
+  if (scheme !== "http" && scheme !== "https") return void 0;
+  const authority = match[2];
+  const hostAndPort = authority.slice(authority.lastIndexOf("@") + 1);
+  const ipv6 = /^(\[[0-9a-f:.]+\])(?::(\d*))?$/i.exec(hostAndPort);
+  const named = /^([^:[\]\s]+)(?::(\d*))?$/.exec(hostAndPort);
+  const parts = ipv6 ?? named;
+  if (!parts) return void 0;
+  const host = parts[1].toLowerCase();
+  if (host.length === 0 || /[\s<>^`{|}%\\]/.test(host)) return void 0;
+  let port = parts[2] ?? "";
+  if (port !== "") {
+    const value = Number(port);
+    if (!Number.isInteger(value) || value > 65535) return void 0;
+    port = String(value);
+  }
+  return port === "" || port === DEFAULT_PORTS[scheme] ? `${scheme}://${host}` : `${scheme}://${host}:${port}`;
+}
+
 // ../peer-office/src/runtime/provider_origins.ts
 import { create as create13 } from "@bufbuild/protobuf";
 import { fromBinary as fromBinary10 } from "@bufbuild/protobuf";
@@ -5292,14 +5317,7 @@ var normalizeProfile = (profile) => {
     ...servedOrigin === void 0 ? {} : { servedOrigin }
   });
 };
-var originOf2 = (url) => {
-  try {
-    const parsed = new URL(url);
-    return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : void 0;
-  } catch {
-    return void 0;
-  }
-};
+var originOf2 = httpOrigin;
 var ReplicaPlacementDirectiveKind = Object.freeze({
   None: "none",
   Cache: "cache",
@@ -11138,7 +11156,10 @@ var ReadMaintenanceDesk = class {
       ...background ? { background } : {},
       ...awaited || existing?.awaited ? { awaited: true } : {},
       failures: existing?.failures ?? 0,
-      retryNotBeforeNanoseconds: 0n
+      // A foreground read may retry at once. Upkeep owed by a write or a sync keeps any back-off
+      // it is already serving: otherwise every write retried a failing upkeep immediately, and a
+      // workspace whose upkeep could not succeed retried on every write (CAP-693).
+      retryNotBeforeNanoseconds: isReadDemand ? 0n : existing?.retryNotBeforeNanoseconds ?? 0n
     });
     if (isReadDemand && (!existing?.read || existing.read.owedByAdvance)) {
       const entries = [...this.#pending.entries()];
@@ -11746,18 +11767,17 @@ var SubscriptionManager = class {
   #requestReadMaintenance;
   #clock;
   #subscriptions = /* @__PURE__ */ new Map();
-  /** Watches owed a re-read, drained one query group per turn when a turn scheduler is given. */
+  /** Watches owed a re-read, drained one query group per office turn (see [drainOwedTurn]). */
   #owed = /* @__PURE__ */ new Set();
-  #nextTurn;
-  #draining = false;
+  #deferRefreshes;
   #sequence = 0n;
-  constructor(queries, sessions, events, requestReadMaintenance, clock, nextTurn) {
+  constructor(queries, sessions, events, requestReadMaintenance, clock, deferRefreshes = false) {
     this.#queries = queries;
     this.#sessions = sessions;
     this.#events = events;
     this.#requestReadMaintenance = requestReadMaintenance;
     this.#clock = clock;
-    this.#nextTurn = nextTurn;
+    this.#deferRefreshes = deferRefreshes;
   }
   start(request, command) {
     if (!command.subscriptionId) throw new Error("watch requires a subscription identity");
@@ -11863,34 +11883,33 @@ var SubscriptionManager = class {
    * or replace current authorization. Each watch still owns its delivery state.
    */
   #refreshMatching(matches, cause) {
-    if (this.#nextTurn && !cause) {
+    if (this.#deferRefreshes && !cause) {
       for (const [id, subscription] of this.#subscriptions) {
         if (subscription.request.query && matches(subscription)) this.#owed.add(id);
       }
-      this.#drain();
       return;
     }
     this.#refreshGroups(this.#groups(matches), cause);
   }
-  #drain() {
-    if (this.#draining || this.#owed.size === 0) return;
-    this.#draining = true;
-    this.#nextTurn(() => {
-      this.#draining = false;
-      if (this.#owed.size === 0) return;
-      const first = this.#owed.values().next().value;
-      const lead = this.#subscriptions.get(first);
-      if (!lead?.request.query) {
-        this.#owed.delete(first);
-      } else {
-        const declaration = toBinary20(QueryRequestSchema, lead.request.query);
-        const session = lead.request.session;
-        const group = this.#groups((subscription) => subscription.request.session === session && this.#owed.has(subscription.request.subscriptionId) && sameBytes(toBinary20(QueryRequestSchema, subscription.request.query), declaration));
-        for (const each of group) for (const watch of each.watches) this.#owed.delete(watch.request.subscriptionId);
-        this.#refreshGroups(group);
-      }
-      this.#drain();
-    });
+  /** Whether any watch is owed a re-read: the office's next drive() is due at once. */
+  get owesRefresh() {
+    return this.#owed.size > 0;
+  }
+  /** One office turn of owed re-reads: the first owed watch's query group. False when none was owed. */
+  drainOwedTurn() {
+    if (this.#owed.size === 0) return false;
+    const first = this.#owed.values().next().value;
+    const lead = this.#subscriptions.get(first);
+    if (!lead?.request.query) {
+      this.#owed.delete(first);
+      return true;
+    }
+    const declaration = toBinary20(QueryRequestSchema, lead.request.query);
+    const session = lead.request.session;
+    const group = this.#groups((subscription) => subscription.request.session === session && this.#owed.has(subscription.request.subscriptionId) && sameBytes(toBinary20(QueryRequestSchema, subscription.request.query), declaration));
+    for (const each of group) for (const watch of each.watches) this.#owed.delete(watch.request.subscriptionId);
+    this.#refreshGroups(group);
+    return true;
   }
   #groups(matches) {
     const groups = [];
@@ -12014,6 +12033,38 @@ function createSyntheticRequest(requestId) {
   });
 }
 
+// ../peer-office/src/runtime/shell_contract.ts
+var SHELL_CONTRACT_V1 = Object.freeze({
+  version: 1,
+  /** Host globals beyond ECMAScript 2022, which every shell supplies. */
+  host: Object.freeze(["TextEncoder", "TextDecoder", "queueMicrotask", "console"]),
+  /** Nomos bridges a native bootstrap installs for the ports it hands to peerOffice.open. */
+  bridges: Object.freeze([
+    "__nomosKernel",
+    "__nomosCredentialVault",
+    "__nomosProfile",
+    "__nomosObservations",
+    "__nomosCustodyStorage",
+    "__nomosPeerDeskStore",
+    "__nomosSyncDiagnostic",
+    "__nomosShellContract"
+  ]),
+  /** Globals the runtime may only probe: used behind their own `typeof` test, never bare. */
+  probed: Object.freeze(["process", "Deno", "Bun", "define"])
+});
+var SHELL_CONTRACT_V2 = Object.freeze({ ...SHELL_CONTRACT_V1, version: 2 });
+var SHELL_CONTRACT_MINIMUM = 1;
+function declaredShellContract(scope = globalThis) {
+  const declared = scope.__nomosShellContract;
+  return declared === void 0 ? 1 : Number(declared);
+}
+function assertShellContract(scope = globalThis) {
+  const declared = declaredShellContract(scope);
+  if (!Number.isInteger(declared) || declared < SHELL_CONTRACT_MINIMUM) {
+    throw new Error(`nomos.runtime.shell_contract_unsupported: this runtime needs shell contract ${SHELL_CONTRACT_MINIMUM} or later; the shell declares ${String(declared)}`);
+  }
+}
+
 // ../peer-office/src/runtime/replica_follow_state.ts
 var ReplicaFollowPhase = Object.freeze({
   Desired: "desired",
@@ -19990,10 +20041,9 @@ var PeerOffice = class {
       this.#trace,
       (session) => this.#readMaintenance.schedule(session, ReadMaintenanceCause.READ_DEBT),
       observations,
-      // An interactive peer keeps its thread responsive while watches catch up.
-      this.#interactivePeer ? (run2) => {
-        setTimeout(run2, 0);
-      } : void 0
+      // An interactive peer keeps its thread responsive while watches catch up: owed re-reads
+      // wait for its drive() turns.
+      this.#interactivePeer
     );
     this.#application = new ApplicationDesk({
       onAdmitted: (session) => {
@@ -20400,7 +20450,9 @@ var PeerOffice = class {
    * mirrors queue/backoff state.
    */
   drive() {
-    return this.#maintenance.drive();
+    if (this.#subscriptions.drainOwedTurn()) return 0n;
+    const wake = this.#maintenance.drive();
+    return this.#subscriptions.owesRefresh ? 0n : wake;
   }
   /**
    * Carry one exact maintenance demand through a durable host continuation.
@@ -21361,6 +21413,7 @@ var PeerOffice = class {
 };
 var peerOffice = {
   open(kernel, credentials, profile, observations, custodyStorage, peerDeskStore) {
+    assertShellContract();
     return new PeerOffice(kernel, credentials, profile, observations, custodyStorage, peerDeskStore);
   },
   Peer: PeerOffice

package/dist/full-cli.mjs

@@ -12985,6 +12985,37 @@ var init_kernel_port = __esm({
   }
 });
 
+// ../peer-office/src/runtime/http_origin.ts
+function httpOrigin(url) {
+  const match = AUTHORITY.exec(url.trim());
+  if (!match) return void 0;
+  const scheme = match[1].toLowerCase();
+  if (scheme !== "http" && scheme !== "https") return void 0;
+  const authority = match[2];
+  const hostAndPort = authority.slice(authority.lastIndexOf("@") + 1);
+  const ipv6 = /^(\[[0-9a-f:.]+\])(?::(\d*))?$/i.exec(hostAndPort);
+  const named = /^([^:[\]\s]+)(?::(\d*))?$/.exec(hostAndPort);
+  const parts = ipv6 ?? named;
+  if (!parts) return void 0;
+  const host2 = parts[1].toLowerCase();
+  if (host2.length === 0 || /[\s<>^`{|}%\\]/.test(host2)) return void 0;
+  let port = parts[2] ?? "";
+  if (port !== "") {
+    const value = Number(port);
+    if (!Number.isInteger(value) || value > 65535) return void 0;
+    port = String(value);
+  }
+  return port === "" || port === DEFAULT_PORTS[scheme] ? `${scheme}://${host2}` : `${scheme}://${host2}:${port}`;
+}
+var AUTHORITY, DEFAULT_PORTS;
+var init_http_origin = __esm({
+  "../peer-office/src/runtime/http_origin.ts"() {
+    "use strict";
+    AUTHORITY = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+    DEFAULT_PORTS = { http: "80", https: "443" };
+  }
+});
+
 // ../peer-office/src/git_read_lease.ts
 import { fromBinary as fromBinary5 } from "@bufbuild/protobuf";
 function decodeGitReadLease(bytes, workspace, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1e3))) {
@@ -13336,6 +13367,7 @@ var stableIdentifier, normalizeProfile, originOf2, ReplicaPlacementDirectiveKind
 var init_placement_desk = __esm({
   "../peer-office/src/runtime/placement_desk.ts"() {
     "use strict";
+    init_http_origin();
     init_provider_origins();
     init_kernel_pb();
     init_placement_desk_pb();
@@ -13360,14 +13392,7 @@ var init_placement_desk = __esm({
         ...servedOrigin === void 0 ? {} : { servedOrigin }
       });
     };
-    originOf2 = (url) => {
-      try {
-        const parsed = new URL(url);
-        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : void 0;
-      } catch {
-        return void 0;
-      }
-    };
+    originOf2 = httpOrigin;
     ReplicaPlacementDirectiveKind = Object.freeze({
       None: "none",
       Cache: "cache",
@@ -19534,7 +19559,10 @@ var init_read_maintenance_desk = __esm({
           ...background ? { background } : {},
           ...awaited || existing?.awaited ? { awaited: true } : {},
           failures: existing?.failures ?? 0,
-          retryNotBeforeNanoseconds: 0n
+          // A foreground read may retry at once. Upkeep owed by a write or a sync keeps any back-off
+          // it is already serving: otherwise every write retried a failing upkeep immediately, and a
+          // workspace whose upkeep could not succeed retried on every write (CAP-693).
+          retryNotBeforeNanoseconds: isReadDemand ? 0n : existing?.retryNotBeforeNanoseconds ?? 0n
         });
         if (isReadDemand && (!existing?.read || existing.read.owedByAdvance)) {
           const entries = [...this.#pending.entries()];
@@ -20183,18 +20211,17 @@ var init_subscription_manager = __esm({
       #requestReadMaintenance;
       #clock;
       #subscriptions = /* @__PURE__ */ new Map();
-      /** Watches owed a re-read, drained one query group per turn when a turn scheduler is given. */
+      /** Watches owed a re-read, drained one query group per office turn (see [drainOwedTurn]). */
       #owed = /* @__PURE__ */ new Set();
-      #nextTurn;
-      #draining = false;
+      #deferRefreshes;
       #sequence = 0n;
-      constructor(queries, sessions, events, requestReadMaintenance, clock, nextTurn) {
+      constructor(queries, sessions, events, requestReadMaintenance, clock, deferRefreshes = false) {
         this.#queries = queries;
         this.#sessions = sessions;
         this.#events = events;
         this.#requestReadMaintenance = requestReadMaintenance;
         this.#clock = clock;
-        this.#nextTurn = nextTurn;
+        this.#deferRefreshes = deferRefreshes;
       }
       start(request, command) {
         if (!command.subscriptionId) throw new Error("watch requires a subscription identity");
@@ -20300,34 +20327,33 @@ var init_subscription_manager = __esm({
        * or replace current authorization. Each watch still owns its delivery state.
        */
       #refreshMatching(matches, cause) {
-        if (this.#nextTurn && !cause) {
+        if (this.#deferRefreshes && !cause) {
           for (const [id, subscription] of this.#subscriptions) {
             if (subscription.request.query && matches(subscription)) this.#owed.add(id);
           }
-          this.#drain();
           return;
         }
         this.#refreshGroups(this.#groups(matches), cause);
       }
-      #drain() {
-        if (this.#draining || this.#owed.size === 0) return;
-        this.#draining = true;
-        this.#nextTurn(() => {
-          this.#draining = false;
-          if (this.#owed.size === 0) return;
-          const first = this.#owed.values().next().value;
-          const lead = this.#subscriptions.get(first);
-          if (!lead?.request.query) {
-            this.#owed.delete(first);
-          } else {
-            const declaration = toBinary15(QueryRequestSchema, lead.request.query);
-            const session = lead.request.session;
-            const group = this.#groups((subscription) => subscription.request.session === session && this.#owed.has(subscription.request.subscriptionId) && sameBytes(toBinary15(QueryRequestSchema, subscription.request.query), declaration));
-            for (const each of group) for (const watch of each.watches) this.#owed.delete(watch.request.subscriptionId);
-            this.#refreshGroups(group);
-          }
-          this.#drain();
-        });
+      /** Whether any watch is owed a re-read: the office's next drive() is due at once. */
+      get owesRefresh() {
+        return this.#owed.size > 0;
+      }
+      /** One office turn of owed re-reads: the first owed watch's query group. False when none was owed. */
+      drainOwedTurn() {
+        if (this.#owed.size === 0) return false;
+        const first = this.#owed.values().next().value;
+        const lead = this.#subscriptions.get(first);
+        if (!lead?.request.query) {
+          this.#owed.delete(first);
+          return true;
+        }
+        const declaration = toBinary15(QueryRequestSchema, lead.request.query);
+        const session = lead.request.session;
+        const group = this.#groups((subscription) => subscription.request.session === session && this.#owed.has(subscription.request.subscriptionId) && sameBytes(toBinary15(QueryRequestSchema, subscription.request.query), declaration));
+        for (const each of group) for (const watch of each.watches) this.#owed.delete(watch.request.subscriptionId);
+        this.#refreshGroups(group);
+        return true;
       }
       #groups(matches) {
         const groups = [];
@@ -20447,6 +20473,44 @@ var init_subscription_manager = __esm({
   }
 });
 
+// ../peer-office/src/runtime/shell_contract.ts
+function declaredShellContract(scope = globalThis) {
+  const declared = scope.__nomosShellContract;
+  return declared === void 0 ? 1 : Number(declared);
+}
+function assertShellContract(scope = globalThis) {
+  const declared = declaredShellContract(scope);
+  if (!Number.isInteger(declared) || declared < SHELL_CONTRACT_MINIMUM) {
+    throw new Error(`nomos.runtime.shell_contract_unsupported: this runtime needs shell contract ${SHELL_CONTRACT_MINIMUM} or later; the shell declares ${String(declared)}`);
+  }
+}
+var SHELL_CONTRACT_V1, SHELL_CONTRACT_V2, SHELL_CONTRACT_MINIMUM;
+var init_shell_contract = __esm({
+  "../peer-office/src/runtime/shell_contract.ts"() {
+    "use strict";
+    SHELL_CONTRACT_V1 = Object.freeze({
+      version: 1,
+      /** Host globals beyond ECMAScript 2022, which every shell supplies. */
+      host: Object.freeze(["TextEncoder", "TextDecoder", "queueMicrotask", "console"]),
+      /** Nomos bridges a native bootstrap installs for the ports it hands to peerOffice.open. */
+      bridges: Object.freeze([
+        "__nomosKernel",
+        "__nomosCredentialVault",
+        "__nomosProfile",
+        "__nomosObservations",
+        "__nomosCustodyStorage",
+        "__nomosPeerDeskStore",
+        "__nomosSyncDiagnostic",
+        "__nomosShellContract"
+      ]),
+      /** Globals the runtime may only probe: used behind their own `typeof` test, never bare. */
+      probed: Object.freeze(["process", "Deno", "Bun", "define"])
+    });
+    SHELL_CONTRACT_V2 = Object.freeze({ ...SHELL_CONTRACT_V1, version: 2 });
+    SHELL_CONTRACT_MINIMUM = 1;
+  }
+});
+
 // ../peer-office/src/runtime/replica_follow_state.ts
 function reduceReplicaFollow(state, event, policy) {
   switch (event.case) {
@@ -28676,6 +28740,7 @@ var init_peer_office = __esm({
     init_residency_pins();
     init_maintenance_desk_pb();
     init_subscription_manager();
+    init_shell_contract();
     init_replica_follow_controller();
     init_replica_follow_desk();
     init_local_copy_drop();
@@ -28872,10 +28937,9 @@ var init_peer_office = __esm({
           this.#trace,
           (session) => this.#readMaintenance.schedule(session, ReadMaintenanceCause.READ_DEBT),
           observations,
-          // An interactive peer keeps its thread responsive while watches catch up.
-          this.#interactivePeer ? (run2) => {
-            setTimeout(run2, 0);
-          } : void 0
+          // An interactive peer keeps its thread responsive while watches catch up: owed re-reads
+          // wait for its drive() turns.
+          this.#interactivePeer
         );
         this.#application = new ApplicationDesk({
           onAdmitted: (session) => {
@@ -29282,7 +29346,9 @@ var init_peer_office = __esm({
        * mirrors queue/backoff state.
        */
       drive() {
-        return this.#maintenance.drive();
+        if (this.#subscriptions.drainOwedTurn()) return 0n;
+        const wake = this.#maintenance.drive();
+        return this.#subscriptions.owesRefresh ? 0n : wake;
       }
       /**
        * Carry one exact maintenance demand through a durable host continuation.
@@ -30243,6 +30309,7 @@ var init_peer_office = __esm({
     };
     peerOffice = {
       open(kernel, credentials, profile, observations, custodyStorage, peerDeskStore) {
+        assertShellContract();
         return new PeerOffice(kernel, credentials, profile, observations, custodyStorage, peerDeskStore);
       },
       Peer: PeerOffice

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "githolon",
-  "version": "0.113.2",
+  "version": "0.113.3",
   "type": "module",
   "description": "githolon — the Nomos developer CLI: Rails-style generators for @githolon/dsl domains + the package compiler. Kernel-independent.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -30,7 +30,7 @@
   "dependencies": {
     "@bjorn3/browser_wasi_shim": "0.4.2",
     "@bufbuild/protobuf": "^2.13.0",
-    "@githolon/dsl": "^0.113.2",
+    "@githolon/dsl": "^0.113.3",
     "fast-xml-parser": "5.10.1",
     "isomorphic-git": "^1.38.4",
     "tsx": "^4.19.2",