@githolon/runtime 0.113.2 → 0.113.3

package/dist/RUNTIME-SOURCES.sha256

@@ -4,12 +4,12 @@
 03248bc7c77ccc8d57679b45d21b0d614c17c4bd3868acb1c91bb83dd2bcf58f  adapter/kernel_execution_desk.ts
 0428fb43c2875c495874c4fb26a79a7eee04aed744466ce0313cd28118b1671c  platform-shells/node/node_custody_filesystem.ts
 052eb91130bab10cdbb01335957751fa5f187b94687a5242bd262e62a6dfba31  peer-office/src/runtime/replica_follow_state.ts
+056f5dd72c5f930463326cc8817e53474607a45d52debcb2a515b6f142438576  peer-office/package/package.json
 05cc75d3ab961d813beede39a2afa7b3ce899968c4ca88eff298b6636ef55d5a  adapter/proto/nomos/runtime/v2/application_desk_pb.js
 0611319c199a2ce589514261275562f691b9c3b4778b4903389bae618952350f  peer-office/src/runtime/kernel_queries.ts
 062ccf10c0501529b87e93598d27769304e2077de7cc9cc7c7b93efdabab9762  peer-office/src/runtime/read_authentication.ts
 063a8e43056578ecec6ba95eb1a9f28d8b704daea2260ef2943840def1cf9526  node_modules/@bufbuild/protobuf/dist/esm/wkt/gen/google/protobuf/source_context_pb.js
 06525d62b18918913a7fe7981204fba9e1f70369cc2aa785851caae39f546de3  node_modules/@bufbuild/protobuf/dist/esm/wire/base64-encoding.js
-073fdbe5a86f289aa546aaa7e4b3658d8aa69f74baba8780a8af69e3a7c69750  peer-office/src/peer_office.ts
 082f4f24399a3f7dc46465903f825c0287a81f4cf8a17ccd96c4bf556ad3d7cb  platform-shells/browser/runtime_fetch.ts
 09a24ed660112991f8105d8c0c2c250617b6ad99f6a12afe2d39b8a9305289ec  peer-office/src/runtime/session_directory.ts
 0a687d73d1754114045dd64ab0125af437945ed11b1302753b1c3c46793a014b  peer-office/src/runtime/replica_follow_lane.ts
@@ -35,7 +35,6 @@
 16d6522ee4ecf4a91c4d29357ebc874844c266f2ae89ef2a92ec2d391f3762e9  node_modules/is-unsafe/src/contexts/sql-strict.js
 17b0d228dd20748bd5fa03164478198c813214e4fa5d8f1650705128a954f0bd  adapter/wasi_custody_filesystem.ts
 1963a804a9cfe7d44a76b2c476817639b939d7e93828da865cab40fe9ba536fa  adapter/custody-transport.ts
-198d9850ef7cf6f9d54cbec0ad6c168e6cc29a5a5f19a6366bfc537c0b021edc  peer-office/src/runtime/read_maintenance_desk.ts
 19a320ee1d4c811af432f1b9d511d5cd840c0fc8bbca74a455a81836fe6c4d1f  peer-office/src/runtime/workspace_sync_dependencies.ts
 1a5d9fd32360e2cec4adbee9e56221fb26def66bb9d122e0b5745cebc963d92e  node_modules/xml-naming/src/index.js
 1a873dadab0fdef771d16b70d3ad318018dbf5c185337519f230064da4e7ea8a  adapter/proto/nomos/kernel/v1/kernel_pb.js
@@ -54,7 +53,6 @@
 208a47278c60cd0f3470c58e981fdd2995d7ce1024cef9caebe208f6a9b291ae  adapter/proto/nomos/runtime/v2/law_desk_pb.js
 20d82153da53012f461d67c21673fdf84dc2d9c62cb7339f95288d375e4ba23b  peer-office/src/runtime/background_paper_slots.ts
 22a2b398e7c3fcbfc171080a6288c710522bf1baf5f56e63f5bdcfbaaf7757b7  node_modules/@bufbuild/protobuf/dist/esm/wkt/wrappers.js
-24bc816455f9aef9c1d3d91724a59936014dabb732083d7833c197f8371251f2  peer-office/src/runtime/subscription_manager.ts
 24f5eb575e633b68771328cc12fa6fde751ecc5f2700a6f52ea325938dc94342  node_modules/is-unsafe/src/index.js
 25c033d29ed62a510d8c43054ec238776bcba0949808cb6054df5cbea951ddf7  adapter/proto/nomos/runtime/v2/interaction_desk_pb.js
 25d57b7e880708c04738087de674a8c98092e5bfd39d5193cdb63a2f1e33871e  node_modules/@bufbuild/protobuf/dist/esm/wkt/gen/google/protobuf/compiler/plugin_pb.js
@@ -77,6 +75,7 @@
 33917d22c20458fce8ef7e3a4fca8f51af8ace4508e6a435870b3ad61ea2eab4  peer-office/src/git_read_lease.ts
 33e7d6bdd22396057d3f8db92384079f7ec2fda4b3582709de2d43fccacc4a9c  node_modules/@bufbuild/protobuf/dist/esm/codegenv2/extension.js
 34f8712de2bd30a2cb8366d8cfdcde466d979f1a28ac0d78f7547341b01f6c57  adapter/proto/nomos/kernel/v1/progress_pb.js
+3586d9b52efc73c3cf40a427a09b4e091a52655942979a2b24b13cd6e8baea83  peer-office/src/peer_office.ts
 3a90933569db7e42ec2ed3b77509c29d1ab75f6eb078f53fe5d1ac6d239d231e  peer-office/src/runtime/peer_background_scheduler.ts
 3c092b8d4185badd23ecf4552434d05aa541b0cd0d534781d687db55260d5da8  adapter/proto/nomos/runtime/v2/sealing_desk_pb.js
 3c98fa838c05abcfd8dfda1128f2d1fca9b196a371fe9751abbd8f4c3b9d04ec  node_modules/@bufbuild/protobuf/dist/esm/wkt/timestamp.js
@@ -130,6 +129,7 @@
 63a928e5632cca54994a7fdde23c44db762fdc3df6afba4677fe4fdc3101b98f  adapter/proto/nomos/runtime/v2/observability_desk_pb.js
 64256c9570f2d73851f8b7e1a47ccee787120ca13b862b317d46c1bdb128f06c  adapter/custody_paths.ts
 666242642051bff6e5bff6d2697b774fe518b78461bde4e0bdb497592cd56d95  peer-office/package/src/nominal_value.ts
+68fbb966cea063ed495d2b11117742a6829f4328ebd20fda06cb0a10358ad38c  peer-office/src/runtime/subscription_manager.ts
 692c6542af574ad4ec2882ae9591db3be7635e7721b43af13158a5397f537ebb  adapter/git_placement_custody.ts
 6b3d69203397fa63fa4d5d38a216de18193e128ee4843630531ef1e6232b3448  adapter/memory_custody_filesystem.ts
 6cfa5fe6f17219f03e2650dec635934cff6601dbee72f188bbd2874a9d1d4523  platform-shells/shared/credential_effects.ts
@@ -155,6 +155,7 @@
 7ec79572a67e1764cd0e93fe2c49d696cd179836293f62e5f50c54e01d6af242  peer-office/src/runtime/provider_origins.ts
 812a2077e073564d6470b8fda8ac0d20ecaaf75ddb1594d55d28acc2da8a1a71  node_modules/@nodable/entities/src/EntityEncoder.js
 81539d21eb82b21f6bab3b84d0b7296cb240532e0314c303d06799a1f5fe4e81  adapter/proto/nomos/runtime/v2/residency_desk_pb.js
+815a6dca44ffad90e4394a2e745c65a86e2abace4ac51aece9c8bf29144bc383  peer-office/src/runtime/placement_desk.ts
 8265b7063f35842f61f48c693eb9c740f07949284fb589380b6795dd88dd5ff1  peer-office/src/runtime/replica_follow_controller.ts
 829eadd8a1a441d25be0cb93b00e16a0d0c20fd294db95d8f2ed87e6954b7182  node_modules/base64-js/index.js
 836d6535b507906f82129a7cae5b1cbd42efaef969f18b13675b39ba7cb5ebcb  peer-office/src/runtime/birth_custody_desk.ts
@@ -182,7 +183,6 @@
 94a3cef0f355a9a177661748d24faae32206a5cc382c8601a34dcf005340107b  node_modules/fast-xml-parser/src/xmlparser/OrderedObjParser.js
 95ad7c933403a0c8f7fd3e2df6c4df3008c29911d3d5db063a90460a14144da2  peer-office/src/runtime/records_desk.ts
 95dbcb2580ed30cb11222c773163c6a906a7e363c5ec4263bd39c1f3a7a16cc2  node_modules/@bufbuild/protobuf/dist/esm/from-json.js
-9634891339d48126199a20c3ee535eb20b0635b862f632725fdc6d645542eff2  peer-office/package/package.json
 96cb2eb563ccb18dc23fd9f8fb0f65193a1b90f39758a561eed747368ead00b3  node_modules/@bufbuild/protobuf/dist/esm/wkt/index.js
 96ec5d127a4e8cd77bdc678422f0d57c8ff9e37bcec999983da71a7b72ce9a0e  node_modules/@nodable/entities/src/entities.js
 98f5abf9a7fb522aab513ef3831dd9c5837cebcb38a960cb546ffd084926d746  node_modules/@bufbuild/protobuf/dist/esm/wkt/gen/google/protobuf/empty_pb.js
@@ -210,6 +210,7 @@ a91848ee180529e2a60c05dfb9584cad19cd4e1c6f391fdb76a938bcae4c0328  node_modules/@
 a9a2aefe743f0243ae1adb3acdd3db6cdb671b744b5f83235cc4e0be905f1a5b  peer-office/package/src/typescript_application_desk.public.d.ts
 aa39c85046ef2b8cd9f7d825eefb502e382e9107b39c9110297f8b84f63f6011  peer-office/src/runtime/replica_inventory_desk.ts
 aa6349944f16d71986273ecfc8e552bfece3d61d5641e526c0ceabf3f154fdaf  peer-office/src/runtime/application_desk.ts
+aabbcb3d691d6ea517811feae5049f094a3a8ffeb14d8332137c8d7a033093e1  peer-office/package/runner/build.ts
 ab43714f566a6ccd988cc3a30810d857552dbd14d0f060934907fb4bba1000f0  peer-office/package/src/admission_decision.ts
 ab80eeeafd4d89a5daaf5d2e00fb471cc6b53fa90776750ca3ad82df482d7c3f  peer-office/src/runtime/peer_lifecycle.ts
 ad3de46df125304b2a61c2fa5537b0e519635997d99686a76119b38cf260963f  adapter/proto/nomos/runtime/v2/identity_desk_pb.js
@@ -225,7 +226,6 @@ b68312b9501ba96f45496f3f30db62c158a127bbb00d7e8ff081b2d741218497  adapter/git_cu
 b683cb36f7b9eacef4270428f7875d3211d84dd851eb226f6a3030a166ca9fa9  peer-office/src/reception/tally_read.ts
 b6d7539356e92bfa257edd790e8d5d697167205b7154106e8758455cc3483e82  runtime/osgi_repository.ts
 b82bb05bb957bb59990dda51bb60ed8b9f656cc090312295ea0958e4cd52bdb7  peer-office/src/runtime/device_recovery_journal.ts
-b95daa723d0b62946657a5dbaef9a2b14150a1cbd504102b95650b53cbf48c36  peer-office/package/runner/build.ts
 ba7223ebf0eea2f078ba83f0128830f7cd07224c57d7e61251541c1c17e83009  peer-office/src/runtime/workspace_effect_delivery.ts
 bb8e81020a9cbf3f8562c196fa5609ef5dec911e0981920c7d05de67769c79d4  peer-office/src/runtime/credential_failure.ts
 bcc5325758b3b940384c7bf2a7132874421989c2561a59dc49c4ef0b88c352dc  node_modules/fast-xml-parser/src/xmlbuilder/json2xml.js
@@ -267,6 +267,7 @@ d4b90e97ac754d086a6ec26756bb2d5cff563396434f16aee3ae34d913d756b9  node_modules/@
 d4ecef7a571afb93de1f62b0e6877237febace34d5487687a8b7c92bc3234a19  peer-office/src/runtime/identity_recovery_desk.ts
 d730efb4ee5b52c492c1d04859568461a4efbfa7474048afa5f8f776a3b6d55b  node_modules/@bufbuild/protobuf/dist/esm/wkt/duration.js
 d851f0d85aa051c8f7880855f4af21b56507afdaebfc99623693eda933df7726  peer-office/src/runtime/residency_pins.ts
+d8f3407bb4a3d5ecd382eea801bab684c8b9345a2aa6e41f9033fad11c4a1750  peer-office/src/runtime/shell_contract.ts
 da6362509cb895cc68dc6c050f3a59ed47d2ee009108e2093e2905e0171efe9c  peer-office/src/runtime/custody_retention_plan.ts
 db05a3f19bc575c1ed771fc6882af337a49cde7bd469181f3acc772d1a76df3e  node_modules/@bufbuild/protobuf/dist/esm/to-json.js
 db61a17ab4dbb3514b676cd93cc702fe62a6582d5ec292725f1ada20dfbc1f72  peer-office/src/runtime/custody_replacement.ts
@@ -275,9 +276,11 @@ deaa25227d669aa3fbe99174275588dcc175de648ae6623fddf11d6ae69d7f67  platform-shell
 dff6af323ca5f9c73dd06120879fcd5f561d22a8a7fd36d3317e564ae4e10e3b  platform-shells/shared/kernel_work_accounting.ts
 e20a132033f105a29db1cfdb3d85bbadbb7206b9a7e3336bcb030a63d66b4ab2  node_modules/is-unsafe/src/contexts/nosql.js
 e2133d7e0f0ce5491a3e9bd560e9e47db2243a6a9f762be89c82e027d99d278e  peer-office/src/runtime/credential_sessions.ts
+e2f82db2565bd1e8766c9220c7cde9cdb39023a861f6a8f24e14a6a0fb0bd62d  peer-office/src/runtime/read_maintenance_desk.ts
 e394b7a580a2853949ec937d742b54fd8169029a5d10a3e4e521b984c60adb6d  peer-office/src/runtime/identity_desk.ts
 e411cf95c1c0c7063b863a08ad568d61044069f9338028eace56e362029ad3a7  peer-office/src/runtime/residency_desk.ts
 e45a879696cd2e7b692aa282677abf216297c1d129135e914b8a76fd0cbe15bd  peer-office/src/reception/generated_offer_counter.ts
+e4a9e97abd58f2989428d7ed6fd771315a72c696ce0b65bdc938e477772f1edd  peer-office/src/runtime/http_origin.ts
 eb9e106e81226ab9547882079e7fd6a9d885d2c71ba78784f7edaa7db61bb941  node_modules/is-unsafe/src/contexts/svg.js
 ebbf22c6979f6b2b05c580922e7dd197f4f4a246d504d4c0cc8e64778f12d4ed  node_modules/path-expression-matcher/src/index.js
 ece435d3784d928d02bff4d015b7cb686f8c06de8536ff9f8ebc38a8f403a3be  node_modules/@bjorn3/browser_wasi_shim/dist/strace.js
@@ -285,7 +288,6 @@ eda289d9ef0e979fe77a578ffbbf8012cadcfec4629b66cd98c27d6229a9f020  node_modules/@
 efce20f9f127263ca66d855115e01b37af0afb8b8baafeba7dcc2e0834e99e4f  node_modules/@bufbuild/protobuf/dist/esm/wkt/gen/google/protobuf/struct_pb.js
 f23513db2fea432df6121956d9bab4761dabf8034b6eba8988452104dba1783e  adapter/proto/nomos/runtime/v2/records_desk_pb.js
 f3b9324922e08cffcc4c7ae3c6e08454f62e187a37404df31a00160cddf34d77  node_modules/@bufbuild/protobuf/dist/esm/reflect/guard.js
-f4eb625c1c0ebee8e5863b6958706af4635ca58d1d2544ae2b465e75060ba12c  peer-office/src/runtime/placement_desk.ts
 f50218256bfd061c59b454fbaf8ca304f1799b1d0d09b0f7851ba2420e1129ca  adapter/kernel_failure.ts
 f585f26c6fa18af890c32d00fbb00fbfd05b9c7217419b6fe8675bdcee264140  node_modules/fast-xml-builder/src/util.js
 f5f56922916f3b22e72a37521c5ca915506b8b205fe28e89a1986dbce15d4b47  node_modules/@bufbuild/protobuf/dist/esm/wkt/gen/google/protobuf/wrappers_pb.js

package/dist/nomos-native-runtime.js

@@ -7018,6 +7018,31 @@ var NomosRuntimeComponent = (() => {
     }
   };
 
+  // ../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}`;
+  }
+
   // ../src/git_read_lease.ts
   var GIT_READ_LEASE_MEDIA_TYPE = "application/vnd.nomos.git-read-lease+protobuf";
   function decodeGitReadLease(bytes, workspace, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1e3))) {
@@ -7351,14 +7376,7 @@ var NomosRuntimeComponent = (() => {
       ...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",
@@ -13103,7 +13121,10 @@ var NomosRuntimeComponent = (() => {
         ...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()];
@@ -13722,18 +13743,17 @@ var NomosRuntimeComponent = (() => {
     #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");
@@ -13839,34 +13859,33 @@ var NomosRuntimeComponent = (() => {
      * 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 = toBinary(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(toBinary(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 = toBinary(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(toBinary(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 = [];
@@ -13990,6 +14009,38 @@ var NomosRuntimeComponent = (() => {
     });
   }
 
+  // ../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)}`);
+    }
+  }
+
   // ../src/runtime/replica_follow_state.ts
   var ReplicaFollowPhase = Object.freeze({
     Desired: "desired",
@@ -21930,10 +21981,9 @@ var NomosRuntimeComponent = (() => {
         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) => {
@@ -22340,7 +22390,9 @@ var NomosRuntimeComponent = (() => {
      * 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.
@@ -23301,6 +23353,7 @@ var NomosRuntimeComponent = (() => {
   };
   var peerOffice = {
     open(kernel, credentials, profile, observations, custodyStorage, peerDeskStore) {
+      assertShellContract();
       return new PeerOffice(kernel, credentials, profile, observations, custodyStorage, peerDeskStore);
     },
     Peer: PeerOffice

package/dist/nomos-runner-web.js

@@ -1,7 +1,7 @@
 "use strict";
 (() => {
   // ../../platform-shells/browser/worker_page_entry.ts
-  var workerDigest = true ? "051bd37c4dec771340abac5fab088d66a63328bce47c928d3fe547fd950eaef5" : "";
+  var workerDigest = true ? "3f3e4381edf95e9461d7e433b5f55c357eb56cb7d4e280b15077bfadb8eca8cb" : "";
   var SLOW_OPERATION_MICROS = 1e6;
   var slowOperationsReported = 0;
   var bootStages = [];

package/dist/nomos-runner-worker.js

@@ -13463,6 +13463,33 @@
   init_define_NOMOS_KERNEL_RELEASE();
   init_shims();
 
+  // ../src/runtime/http_origin.ts
+  init_define_NOMOS_KERNEL_RELEASE();
+  init_shims();
+  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}`;
+  }
+
   // ../src/runtime/provider_origins.ts
   init_define_NOMOS_KERNEL_RELEASE();
   init_shims();
@@ -13816,14 +13843,7 @@
       ...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",
@@ -19934,7 +19954,10 @@
       ...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 = [...__privateGet(this, _pending).entries()];
@@ -20388,9 +20411,9 @@
     }
     return true;
   };
-  var _queries4, _sessions6, _events2, _requestReadMaintenance, _clock9, _subscriptions2, _owed, _nextTurn, _draining, _sequence11, _SubscriptionManager_instances, now_fn4, refreshMatching_fn, drain_fn, groups_fn, refreshGroups_fn, read_fn, refresh_fn, failed_fn;
+  var _queries4, _sessions6, _events2, _requestReadMaintenance, _clock9, _subscriptions2, _owed, _deferRefreshes, _sequence11, _SubscriptionManager_instances, now_fn4, refreshMatching_fn, groups_fn, refreshGroups_fn, read_fn, refresh_fn, failed_fn;
   var SubscriptionManager = class {
-    constructor(queries, sessions, events, requestReadMaintenance, clock, nextTurn) {
+    constructor(queries, sessions, events, requestReadMaintenance, clock, deferRefreshes = false) {
       __privateAdd(this, _SubscriptionManager_instances);
       __privateAdd(this, _queries4);
       __privateAdd(this, _sessions6);
@@ -20398,17 +20421,16 @@
       __privateAdd(this, _requestReadMaintenance);
       __privateAdd(this, _clock9);
       __privateAdd(this, _subscriptions2, /* @__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]). */
       __privateAdd(this, _owed, /* @__PURE__ */ new Set());
-      __privateAdd(this, _nextTurn);
-      __privateAdd(this, _draining, false);
+      __privateAdd(this, _deferRefreshes);
       __privateAdd(this, _sequence11, 0n);
       __privateSet(this, _queries4, queries);
       __privateSet(this, _sessions6, sessions);
       __privateSet(this, _events2, events);
       __privateSet(this, _requestReadMaintenance, requestReadMaintenance);
       __privateSet(this, _clock9, clock);
-      __privateSet(this, _nextTurn, nextTurn);
+      __privateSet(this, _deferRefreshes, deferRefreshes);
     }
     start(request, command) {
       if (!command.subscriptionId) throw new Error("watch requires a subscription identity");
@@ -20506,6 +20528,26 @@
     readIndexAdvanced(workspace) {
       this.refreshWorkspace(workspace);
     }
+    /** Whether any watch is owed a re-read: the office's next drive() is due at once. */
+    get owesRefresh() {
+      return __privateGet(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 (__privateGet(this, _owed).size === 0) return false;
+      const first = __privateGet(this, _owed).values().next().value;
+      const lead = __privateGet(this, _subscriptions2).get(first);
+      if (!lead?.request.query) {
+        __privateGet(this, _owed).delete(first);
+        return true;
+      }
+      const declaration = toBinary(QueryRequestSchema, lead.request.query);
+      const session = lead.request.session;
+      const group = __privateMethod(this, _SubscriptionManager_instances, groups_fn).call(this, (subscription) => subscription.request.session === session && __privateGet(this, _owed).has(subscription.request.subscriptionId) && sameBytes(toBinary(QueryRequestSchema, subscription.request.query), declaration));
+      for (const each of group) for (const watch of each.watches) __privateGet(this, _owed).delete(watch.request.subscriptionId);
+      __privateMethod(this, _SubscriptionManager_instances, refreshGroups_fn).call(this, group);
+      return true;
+    }
   };
   _queries4 = new WeakMap();
   _sessions6 = new WeakMap();
@@ -20514,8 +20556,7 @@
   _clock9 = new WeakMap();
   _subscriptions2 = new WeakMap();
   _owed = new WeakMap();
-  _nextTurn = new WeakMap();
-  _draining = new WeakMap();
+  _deferRefreshes = new WeakMap();
   _sequence11 = new WeakMap();
   _SubscriptionManager_instances = new WeakSet();
   now_fn4 = function() {
@@ -20526,35 +20567,14 @@
    * or replace current authorization. Each watch still owns its delivery state.
    */
   refreshMatching_fn = function(matches, cause) {
-    if (__privateGet(this, _nextTurn) && !cause) {
+    if (__privateGet(this, _deferRefreshes) && !cause) {
       for (const [id, subscription] of __privateGet(this, _subscriptions2)) {
         if (subscription.request.query && matches(subscription)) __privateGet(this, _owed).add(id);
       }
-      __privateMethod(this, _SubscriptionManager_instances, drain_fn).call(this);
       return;
     }
     __privateMethod(this, _SubscriptionManager_instances, refreshGroups_fn).call(this, __privateMethod(this, _SubscriptionManager_instances, groups_fn).call(this, matches), cause);
   };
-  drain_fn = function() {
-    if (__privateGet(this, _draining) || __privateGet(this, _owed).size === 0) return;
-    __privateSet(this, _draining, true);
-    __privateGet(this, _nextTurn).call(this, () => {
-      __privateSet(this, _draining, false);
-      if (__privateGet(this, _owed).size === 0) return;
-      const first = __privateGet(this, _owed).values().next().value;
-      const lead = __privateGet(this, _subscriptions2).get(first);
-      if (!lead?.request.query) {
-        __privateGet(this, _owed).delete(first);
-      } else {
-        const declaration = toBinary(QueryRequestSchema, lead.request.query);
-        const session = lead.request.session;
-        const group = __privateMethod(this, _SubscriptionManager_instances, groups_fn).call(this, (subscription) => subscription.request.session === session && __privateGet(this, _owed).has(subscription.request.subscriptionId) && sameBytes(toBinary(QueryRequestSchema, subscription.request.query), declaration));
-        for (const each of group) for (const watch of each.watches) __privateGet(this, _owed).delete(watch.request.subscriptionId);
-        __privateMethod(this, _SubscriptionManager_instances, refreshGroups_fn).call(this, group);
-      }
-      __privateMethod(this, _SubscriptionManager_instances, drain_fn).call(this);
-    });
-  };
   groups_fn = function(matches) {
     const groups = [];
     for (const subscription of __privateGet(this, _subscriptions2).values()) {
@@ -20676,6 +20696,40 @@
     });
   }
 
+  // ../src/runtime/shell_contract.ts
+  init_define_NOMOS_KERNEL_RELEASE();
+  init_shims();
+  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(scope2 = globalThis) {
+    const declared = scope2.__nomosShellContract;
+    return declared === void 0 ? 1 : Number(declared);
+  }
+  function assertShellContract(scope2 = globalThis) {
+    const declared = declaredShellContract(scope2);
+    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)}`);
+    }
+  }
+
   // ../src/runtime/replica_follow_controller.ts
   init_define_NOMOS_KERNEL_RELEASE();
   init_shims();
@@ -29046,10 +29100,9 @@
         __privateGet(this, _trace13),
         (session) => __privateGet(this, _readMaintenance).schedule(session, ReadMaintenanceCause.READ_DEBT),
         observations,
-        // An interactive peer keeps its thread responsive while watches catch up.
-        __privateGet(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.
+        __privateGet(this, _interactivePeer)
       ));
       __privateSet(this, _application3, new ApplicationDesk({
         onAdmitted: (session) => {
@@ -29456,7 +29509,9 @@
      * mirrors queue/backoff state.
      */
     drive() {
-      return __privateGet(this, _maintenance2).drive();
+      if (__privateGet(this, _subscriptions5).drainOwedTurn()) return 0n;
+      const wake = __privateGet(this, _maintenance2).drive();
+      return __privateGet(this, _subscriptions5).owesRefresh ? 0n : wake;
     }
     /**
      * Carry one exact maintenance demand through a durable host continuation.
@@ -30431,6 +30486,7 @@
   };
   var peerOffice = {
     open(kernel, credentials, profile, observations, custodyStorage, peerDeskStore) {
+      assertShellContract();
       return new PeerOffice(kernel, credentials, profile, observations, custodyStorage, peerDeskStore);
     },
     Peer: PeerOffice

package/dist/nomos-runner.js

@@ -13463,6 +13463,33 @@
   init_define_NOMOS_KERNEL_RELEASE();
   init_shims();
 
+  // ../src/runtime/http_origin.ts
+  init_define_NOMOS_KERNEL_RELEASE();
+  init_shims();
+  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}`;
+  }
+
   // ../src/runtime/provider_origins.ts
   init_define_NOMOS_KERNEL_RELEASE();
   init_shims();
@@ -13816,14 +13843,7 @@
       ...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",
@@ -19931,7 +19951,10 @@
       ...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 = [...__privateGet(this, _pending).entries()];
@@ -20385,9 +20408,9 @@
     }
     return true;
   };
-  var _queries4, _sessions6, _events2, _requestReadMaintenance, _clock9, _subscriptions2, _owed, _nextTurn, _draining, _sequence11, _SubscriptionManager_instances, now_fn4, refreshMatching_fn, drain_fn, groups_fn, refreshGroups_fn, read_fn, refresh_fn, failed_fn;
+  var _queries4, _sessions6, _events2, _requestReadMaintenance, _clock9, _subscriptions2, _owed, _deferRefreshes, _sequence11, _SubscriptionManager_instances, now_fn4, refreshMatching_fn, groups_fn, refreshGroups_fn, read_fn, refresh_fn, failed_fn;
   var SubscriptionManager = class {
-    constructor(queries, sessions, events, requestReadMaintenance, clock, nextTurn) {
+    constructor(queries, sessions, events, requestReadMaintenance, clock, deferRefreshes = false) {
       __privateAdd(this, _SubscriptionManager_instances);
       __privateAdd(this, _queries4);
       __privateAdd(this, _sessions6);
@@ -20395,17 +20418,16 @@
       __privateAdd(this, _requestReadMaintenance);
       __privateAdd(this, _clock9);
       __privateAdd(this, _subscriptions2, /* @__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]). */
       __privateAdd(this, _owed, /* @__PURE__ */ new Set());
-      __privateAdd(this, _nextTurn);
-      __privateAdd(this, _draining, false);
+      __privateAdd(this, _deferRefreshes);
       __privateAdd(this, _sequence11, 0n);
       __privateSet(this, _queries4, queries);
       __privateSet(this, _sessions6, sessions);
       __privateSet(this, _events2, events);
       __privateSet(this, _requestReadMaintenance, requestReadMaintenance);
       __privateSet(this, _clock9, clock);
-      __privateSet(this, _nextTurn, nextTurn);
+      __privateSet(this, _deferRefreshes, deferRefreshes);
     }
     start(request, command) {
       if (!command.subscriptionId) throw new Error("watch requires a subscription identity");
@@ -20503,6 +20525,26 @@
     readIndexAdvanced(workspace) {
       this.refreshWorkspace(workspace);
     }
+    /** Whether any watch is owed a re-read: the office's next drive() is due at once. */
+    get owesRefresh() {
+      return __privateGet(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 (__privateGet(this, _owed).size === 0) return false;
+      const first = __privateGet(this, _owed).values().next().value;
+      const lead = __privateGet(this, _subscriptions2).get(first);
+      if (!lead?.request.query) {
+        __privateGet(this, _owed).delete(first);
+        return true;
+      }
+      const declaration = toBinary(QueryRequestSchema, lead.request.query);
+      const session = lead.request.session;
+      const group = __privateMethod(this, _SubscriptionManager_instances, groups_fn).call(this, (subscription) => subscription.request.session === session && __privateGet(this, _owed).has(subscription.request.subscriptionId) && sameBytes(toBinary(QueryRequestSchema, subscription.request.query), declaration));
+      for (const each of group) for (const watch of each.watches) __privateGet(this, _owed).delete(watch.request.subscriptionId);
+      __privateMethod(this, _SubscriptionManager_instances, refreshGroups_fn).call(this, group);
+      return true;
+    }
   };
   _queries4 = new WeakMap();
   _sessions6 = new WeakMap();
@@ -20511,8 +20553,7 @@
   _clock9 = new WeakMap();
   _subscriptions2 = new WeakMap();
   _owed = new WeakMap();
-  _nextTurn = new WeakMap();
-  _draining = new WeakMap();
+  _deferRefreshes = new WeakMap();
   _sequence11 = new WeakMap();
   _SubscriptionManager_instances = new WeakSet();
   now_fn4 = function() {
@@ -20523,35 +20564,14 @@
    * or replace current authorization. Each watch still owns its delivery state.
    */
   refreshMatching_fn = function(matches, cause) {
-    if (__privateGet(this, _nextTurn) && !cause) {
+    if (__privateGet(this, _deferRefreshes) && !cause) {
       for (const [id, subscription] of __privateGet(this, _subscriptions2)) {
         if (subscription.request.query && matches(subscription)) __privateGet(this, _owed).add(id);
       }
-      __privateMethod(this, _SubscriptionManager_instances, drain_fn).call(this);
       return;
     }
     __privateMethod(this, _SubscriptionManager_instances, refreshGroups_fn).call(this, __privateMethod(this, _SubscriptionManager_instances, groups_fn).call(this, matches), cause);
   };
-  drain_fn = function() {
-    if (__privateGet(this, _draining) || __privateGet(this, _owed).size === 0) return;
-    __privateSet(this, _draining, true);
-    __privateGet(this, _nextTurn).call(this, () => {
-      __privateSet(this, _draining, false);
-      if (__privateGet(this, _owed).size === 0) return;
-      const first = __privateGet(this, _owed).values().next().value;
-      const lead = __privateGet(this, _subscriptions2).get(first);
-      if (!lead?.request.query) {
-        __privateGet(this, _owed).delete(first);
-      } else {
-        const declaration = toBinary(QueryRequestSchema, lead.request.query);
-        const session = lead.request.session;
-        const group = __privateMethod(this, _SubscriptionManager_instances, groups_fn).call(this, (subscription) => subscription.request.session === session && __privateGet(this, _owed).has(subscription.request.subscriptionId) && sameBytes(toBinary(QueryRequestSchema, subscription.request.query), declaration));
-        for (const each of group) for (const watch of each.watches) __privateGet(this, _owed).delete(watch.request.subscriptionId);
-        __privateMethod(this, _SubscriptionManager_instances, refreshGroups_fn).call(this, group);
-      }
-      __privateMethod(this, _SubscriptionManager_instances, drain_fn).call(this);
-    });
-  };
   groups_fn = function(matches) {
     const groups = [];
     for (const subscription of __privateGet(this, _subscriptions2).values()) {
@@ -20673,6 +20693,40 @@
     });
   }
 
+  // ../src/runtime/shell_contract.ts
+  init_define_NOMOS_KERNEL_RELEASE();
+  init_shims();
+  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)}`);
+    }
+  }
+
   // ../src/runtime/replica_follow_controller.ts
   init_define_NOMOS_KERNEL_RELEASE();
   init_shims();
@@ -29040,10 +29094,9 @@
         __privateGet(this, _trace13),
         (session) => __privateGet(this, _readMaintenance).schedule(session, ReadMaintenanceCause.READ_DEBT),
         observations,
-        // An interactive peer keeps its thread responsive while watches catch up.
-        __privateGet(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.
+        __privateGet(this, _interactivePeer)
       ));
       __privateSet(this, _application3, new ApplicationDesk({
         onAdmitted: (session) => {
@@ -29450,7 +29503,9 @@
      * mirrors queue/backoff state.
      */
     drive() {
-      return __privateGet(this, _maintenance2).drive();
+      if (__privateGet(this, _subscriptions5).drainOwedTurn()) return 0n;
+      const wake = __privateGet(this, _maintenance2).drive();
+      return __privateGet(this, _subscriptions5).owesRefresh ? 0n : wake;
     }
     /**
      * Carry one exact maintenance demand through a durable host continuation.
@@ -30425,6 +30480,7 @@
   };
   var 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/runtime",
-  "version": "0.113.2",
+  "version": "0.113.3",
   "type": "module",
   "description": "The portable Nomos application runtime, reception contracts, and Node/browser runners.",
   "license": "SEE LICENSE IN LICENSE.md",

package/runner/build.ts

@@ -198,6 +198,17 @@ if (existsSync(FLUTTER_ASSETS)) {
     "// GENERATED by peer-office/package/runner/build.ts. Do not edit.\n"
     + "// The sha256 of the packaged nomos-runner-web.js this package ships.\n"
     + `const String kNomosRunnerWebSha256 =\n    '${pageSha256}';\n`);
+  // The native Peer Office ships as Dart code, not a Flutter asset: a code-push update (Shorebird
+  // patch) replaces Dart but never assets, and this runtime is the code we most often need to fix.
+  const nativeRuntime = readFileSync(here("../dist/nomos-native-runtime.js"), "utf8");
+  if (nativeRuntime.includes("'''")) throw new Error("native runtime bundle cannot be a Dart raw string: it contains '''");
+  const nativeRuntimeSha256 = createHash("sha256").update(nativeRuntime).digest("hex");
+  writeFileSync(join(FLUTTER_ASSETS, "../lib/src/platform_shell/native_runtime_bundle.g.dart"),
+    "// GENERATED by peer-office/package/runner/build.ts from dist/nomos-native-runtime.js. Do not edit.\n"
+    + "// ignore_for_file: lines_longer_than_80_chars\n"
+    + "// The shared Peer Office the native hosts execute, as Dart code so a code patch can carry it.\n"
+    + `const String kNomosNativeRuntimeSha256 =\n    '${nativeRuntimeSha256}';\n`
+    + `const String kNomosNativeRuntimeJavascript = r'''${nativeRuntime}''';\n`);
   console.error("✓ synced browser shell and shared Peer Office assets → nomos_flutter/assets");
 }
 

package/runner/node-entry.mjs

@@ -14587,6 +14587,32 @@ var KernelPort = class {
 // ../src/runtime/placement_desk.ts
 init_define_NOMOS_KERNEL_RELEASE();
 
+// ../src/runtime/http_origin.ts
+init_define_NOMOS_KERNEL_RELEASE();
+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}`;
+}
+
 // ../src/runtime/provider_origins.ts
 init_define_NOMOS_KERNEL_RELEASE();
 
@@ -14926,14 +14952,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",
@@ -20783,7 +20802,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()];
@@ -21392,18 +21414,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");
@@ -21509,34 +21530,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 = toBinary(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(toBinary(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 = toBinary(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(toBinary(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 = [];
@@ -21660,6 +21680,39 @@ function createSyntheticRequest(requestId) {
   });
 }
 
+// ../src/runtime/shell_contract.ts
+init_define_NOMOS_KERNEL_RELEASE();
+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)}`);
+  }
+}
+
 // ../src/runtime/replica_follow_controller.ts
 init_define_NOMOS_KERNEL_RELEASE();
 
@@ -29657,10 +29710,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) => {
@@ -30067,7 +30119,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.
@@ -31028,6 +31082,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