@githolon/dsl 0.113.1 → 0.113.3

package/dart/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.67.1
+
+- Git custody upkeep backing off after a failure is reported as `upkeepRetrying`, not `retrying`: the workspace is
+  ready meanwhile, so it no longer shows as a sync problem (CAP-693).
+
 ## 0.67.0
 
 - A write sent over the live link has its receipt converge on the custodian's admission: the live desk reports the

package/dart/lib/src/reception/workspace_preparation_report.dart

@@ -23,6 +23,7 @@ final class WorkspacePreparationReport {
     this.sqliteFrontier,
     this.retryAfterMillis,
     this.stopped = false,
+    this.upkeep = false,
   });
 
   final WorkspacePreparationStep step;
@@ -32,7 +33,16 @@ final class WorkspacePreparationReport {
   final String? sqliteFrontier;
   final int? retryAfterMillis;
   final bool stopped;
-  bool get retrying => retryAfterMillis != null;
+
+  /// Git custody upkeep after this peer's own writes: it never holds a read or a write.
+  final bool upkeep;
+
+  /// Preparation the workspace is waiting on is backing off after a failure. Upkeep retrying
+  /// is not: the workspace is ready meanwhile, and nothing the user can do changes it (CAP-693).
+  bool get retrying => retryAfterMillis != null && !upkeep;
+
+  /// Upkeep backing off after a failure, for diagnostics; never shown as a sync problem.
+  bool get upkeepRetrying => retryAfterMillis != null && upkeep;
 
   /// Exact equality of reported frontiers, rather than a guess from residency.
   bool? get sqliteCurrent {
@@ -81,7 +91,8 @@ final class WorkspacePreparationReport {
     final upkeep = step == WorkspacePreparationStep.preparingCustody ||
         (kernel == null &&
             progress.cause ==
-                protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_ADMITTED_OFFER);
+                protocol.ReadMaintenanceCause
+                    .READ_MAINTENANCE_CAUSE_ADMITTED_OFFER);
     return WorkspacePreparationReport(
       step: step,
       active: retry == null &&
@@ -91,6 +102,7 @@ final class WorkspacePreparationReport {
           (kernel == null || kernel.maintenancePending),
       retryAfterMillis: retry,
       stopped: progress.stopped,
+      upkeep: upkeep,
       // A new demand may target a newer frontier. Never carry old readiness
       // across its scheduled observation before the kernel reports a result.
       gitFrontier: kernel == null

package/dart/lib/src/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

package/dart/pubspec.yaml

@@ -7,7 +7,7 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.67.0
+version: 0.67.1
 
 environment:
   sdk: ^3.5.0

package/dart/test/workspace_preparation_upkeep_test.dart

@@ -7,7 +7,8 @@ void main() {
     final packing = WorkspacePreparationReport.fromMaintenance(
       protocol.ReadMaintenanceProgress(
         workspace: 'estate',
-        cause: protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_ADMITTED_OFFER,
+        cause:
+            protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_ADMITTED_OFFER,
         kernel: protocol.MaintenanceQuantumResponse(
           phase: protocol.MaintenancePhase.MAINTENANCE_PHASE_GIT_CUSTODY,
           maintenancePending: true,
@@ -20,7 +21,8 @@ void main() {
     final scheduled = WorkspacePreparationReport.fromMaintenance(
       protocol.ReadMaintenanceProgress(
         workspace: 'estate',
-        cause: protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_ADMITTED_OFFER,
+        cause:
+            protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_ADMITTED_OFFER,
       ),
     );
     expect(scheduled.active, isFalse);
@@ -35,6 +37,33 @@ void main() {
         ),
       ),
     );
-    expect(reads.active, isTrue, reason: 'a read index still being built is real preparation');
+    expect(reads.active, isTrue,
+        reason: 'a read index still being built is real preparation');
+  });
+
+  test('upkeep backing off after a failure is not a sync problem (CAP-693)',
+      () {
+    // A shallow device's Git upkeep was refused by the kernel; the status turned orange though
+    // every read and write still worked.
+    final failingUpkeep = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(
+        workspace: 'estate',
+        cause:
+            protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_ADMITTED_OFFER,
+        retryAfterMillis: 4000,
+      ),
+    );
+    expect(failingUpkeep.retrying, isFalse);
+    expect(failingUpkeep.upkeepRetrying, isTrue);
+
+    final failingReads = WorkspacePreparationReport.fromMaintenance(
+      protocol.ReadMaintenanceProgress(
+        workspace: 'estate',
+        cause: protocol.ReadMaintenanceCause.READ_MAINTENANCE_CAUSE_OPEN,
+        retryAfterMillis: 4000,
+      ),
+    );
+    expect(failingReads.retrying, isTrue,
+        reason: 'preparation a read waits on still shows');
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.113.1",
+  "version": "0.113.3",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
@@ -73,7 +73,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@githolon/runtime": "^0.113.1",
+    "@githolon/runtime": "^0.113.3",
     "@bufbuild/protobuf": "^2.13.0",
     "@bufbuild/protoc-gen-es": "^2.13.0",
     "esbuild": "0.24.2",

package/src/compile_package_main.ts

@@ -2543,8 +2543,8 @@ const NOMOS_TYPES_DEP = "^0.12.0";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.67.0";
-const NOMOS_FLUTTER_DEP = "^0.66.1";
+const NOMOS_CLIENT_DEP = "^0.67.1";
+const NOMOS_FLUTTER_DEP = "^0.66.3";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in the Dart and Flutter
 // package pubspecs — a release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).