@githolon/dsl 0.77.0 → 0.77.1

package/dart/lib/src/webview_bridge.dart

@@ -43,6 +43,34 @@ typedef NomosEngine = NomosBridge;
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
 
+/// THE EXPECTED RUNNER-BUNDLE VERSION FLOOR — the @githolon/client release this nomos_client version
+/// ships alongside. The bundle stamps its own version into the ready frame; anything OLDER (or a
+/// pre-stamp bundle, which reports nothing) is a stale baked asset and fails loudly at boot.
+/// MUST move with the paired @githolon/client release — a release-hygiene test pairs it with the
+/// runner stamp (the pubspec-pins pattern).
+const String kExpectedRunnerBundleVersion = '0.77.1';
+
+/// A STALE BAKED RUNNER BUNDLE: the app's built assets carry an older nomos-runner.js than this
+/// nomos_client release ships — Flutter's build cache kept it across a pub upgrade. Thrown from
+/// [NomosBridge.ready] at boot (loud, immediate, named) instead of letting one-version-old runtime
+/// behavior masquerade as framework bugs.
+class StaleRunnerBundle implements Exception {
+  StaleRunnerBundle({required this.found, required this.expected});
+
+  /// The bundle's self-reported version (null = a pre-stamp bundle, definitionally stale).
+  final String? found;
+
+  /// The minimum version this nomos_client release expects ([kExpectedRunnerBundleVersion]).
+  final String expected;
+
+  @override
+  String toString() =>
+      'StaleRunnerBundle: the baked nomos-runner.js is ${found ?? "un-stamped (pre-0.77.1)"} but this '
+      'nomos_client expects >= $expected. Flutter kept an old bundle across the upgrade — run '
+      '`flutter clean` and rebuild (verify with shasum of flutter_assets/.../nomos-runner.js), or pass '
+      'NomosBridge(..., allowStaleRunnerBundle: true) for a deliberate mixed-version setup.';
+}
+
 /// The platform channel to the WebView runner: send a JSON-shaped message; receive the runner's messages.
 /// Web impl jsifies/dartifies over `dart:js_util`; mobile impl JSON-encodes over a WebView JS-channel. The
 /// bridge treats messages as plain `Map<String, Object?>` — the transport owns the channel serialization.
@@ -743,13 +771,37 @@ class NomosBridge {
   final String _traceId = _newTraceId();
   late final StreamSubscription<Map<String, Object?>> _sub;
 
-  NomosBridge(this._transport) {
+  NomosBridge(this._transport, {this.allowStaleRunnerBundle = false}) {
     _sub = _transport.messages.listen(_onMessage);
   }
 
+  /// Escape hatch for DELIBERATE mixed-version setups (framework dev, A/B probes): accept a runner
+  /// bundle older than [kExpectedRunnerBundleVersion] instead of failing [ready].
+  final bool allowStaleRunnerBundle;
+
+  /// null = acceptable; otherwise the typed boot error. "unbundled-dev" (the in-repo source lane)
+  /// always passes; a missing stamp means a pre-stamp (definitionally stale) bundle.
+  StaleRunnerBundle? _staleBundleError(Object? bundleVersion) {
+    final v = bundleVersion is String ? bundleVersion : null;
+    if (v == 'unbundled-dev') return null;
+    if (v != null && _semverAtLeast(v, kExpectedRunnerBundleVersion)) return null;
+    return StaleRunnerBundle(found: v, expected: kExpectedRunnerBundleVersion);
+  }
+
+  static bool _semverAtLeast(String v, String min) {
+    List<int> parse(String s) =>
+        s.split('-').first.split('.').map((p) => int.tryParse(p) ?? 0).toList();
+    final a = parse(v), b = parse(min);
+    for (var i = 0; i < 3; i++) {
+      final x = i < a.length ? a[i] : 0, y = i < b.length ? b[i] : 0;
+      if (x != y) return x > y;
+    }
+    return true;
+  }
+
   /// A SESSION VIEW's super-constructor: shares the parent's [_transport] but does NOT subscribe (the parent
   /// owns the one message loop + all correlation). Only [NomosSession] uses it.
-  NomosBridge._view(this._transport);
+  NomosBridge._view(this._transport) : allowStaleRunnerBundle = false;
 
   static Random _traceRandom() {
     try {
@@ -798,6 +850,18 @@ class NomosBridge {
     }
     final event = m['event'];
     if (event == 'ready') {
+      // THE STALE-BAKED-BUNDLE CHECK: Flutter's build system can silently keep an OLD runner bundle
+      // baked into an app across a correct pub upgrade — invisible version skew that cost a real
+      // tenant two archaeology hunts. The bundle stamps its release version into the ready frame;
+      // an older-than-expected (or missing — i.e. pre-stamp) bundle fails LOUDLY at boot with the
+      // remedy, instead of misbehaving subtly at runtime. "unbundled-dev" (the in-repo source lane
+      // the test harness drives) always passes; `allowStaleRunnerBundle: true` on the constructor is
+      // the deliberate-mixed-versions escape hatch.
+      final stale = _staleBundleError(m['bundleVersion']);
+      if (stale != null && !allowStaleRunnerBundle) {
+        if (!_ready.isCompleted) _ready.completeError(stale);
+        return;
+      }
       if (!_ready.isCompleted) _ready.complete();
       return;
     }

package/dart/test/acquire_session_test.dart

@@ -17,7 +17,7 @@ class FakeRunner implements BridgeTransport {
 
   FakeRunner({this.resident = const []}) {
     scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
   }
 
   int get connectCount => sent.where((m) => m['op'] == 'connect').length;

package/dart/test/bundle_version_pairing_test.dart

@@ -0,0 +1,40 @@
+// THE VERSION-PAIRING TRIPWIRE (the pubspec-pins pattern): kExpectedRunnerBundleVersion must equal
+// the @githolon/client version this repo is about to release (cloud/web-client/package.json) — a
+// client release without the Dart floor bump (or vice versa) fails the suite, so the stale-bundle
+// check can neither lag (missing real staleness) nor lead (refusing the current bundle).
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('kExpectedRunnerBundleVersion pairs with cloud/web-client/package.json', () {
+    final f = File('${Directory.current.path}/../../cloud/web-client/package.json');
+    if (!f.existsSync()) {
+      markTestSkipped('monorepo layout not present (published-package test run)');
+      return;
+    }
+    final v = (jsonDecode(f.readAsStringSync()) as Map)['version'] as String;
+    if (kExpectedRunnerBundleVersion == v) return; // released state: exact pair
+    // PENDING-RELEASE state: the floor may lead package.json by exactly the bump a queued
+    // changeset will apply (the changesets flow bumps package.json only when the version PR
+    // merges). Anything else — lagging, or leading with no changeset queued — is drift.
+    final changesets = Directory('${Directory.current.path}/../../.changeset')
+        .listSync()
+        .whereType<File>()
+        .where((c) => c.path.endsWith('.md') && !c.path.endsWith('README.md'))
+        .where((c) => c.readAsStringSync().contains('@githolon/client'));
+    expect(changesets, isNotEmpty,
+        reason: 'kExpectedRunnerBundleVersion ($kExpectedRunnerBundleVersion) != @githolon/client '
+            '($v) and NO client changeset is queued — bump the floor WITH the client release '
+            '(the stale-bundle floor must move with the bundle it ships beside)');
+    List<int> parse(String x) =>
+        x.split('.').map((p) => int.tryParse(p) ?? 0).toList();
+    final a = parse(kExpectedRunnerBundleVersion), b = parse(v);
+    final leads = a[0] > b[0] ||
+        (a[0] == b[0] && (a[1] > b[1] || (a[1] == b[1] && a[2] > b[2])));
+    expect(leads, isTrue,
+        reason: 'the floor must LEAD (never lag) package.json while a release is queued');
+  });
+}

package/dart/test/fixtures/wedge/wedge-entry.mjs

@@ -7,7 +7,7 @@ import { createInterface } from "node:readline";
 const post = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
 const wedgeOp = process.env.NOMOS_WEDGE_OP || "connect"; // default: wedge the KEYED reconnect (co2's shape)
 const wedgeOnlyKeyed = process.env.NOMOS_WEDGE_ONLY_KEYED !== "0";
-post({ v: 1, event: "ready" });
+post({ v: 1, event: "ready", bundleVersion: "unbundled-dev" });
 const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
 rl.on("line", (line) => {
   const s = line.trim();

package/dart/test/stale_bundle_test.dart

@@ -0,0 +1,65 @@
+// THE STALE-BAKED-BUNDLE CHECK (the countermeasure to the co2 incidents where Flutter's build
+// cache silently kept an old nomos-runner.js across a correct pub upgrade). ready carries the
+// bundle's self-stamped version; the bridge refuses stale/pre-stamp bundles LOUDLY at boot.
+import 'dart:async';
+
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+class _StampedRunner implements BridgeTransport {
+  _StampedRunner(this.stamp) {
+    scheduleMicrotask(() => _incoming.add({
+          'v': kWebviewBridgeVersion,
+          'event': 'ready',
+          if (stamp != null) 'bundleVersion': stamp,
+        }));
+  }
+  final String? stamp;
+  final _incoming = StreamController<Map<String, Object?>>.broadcast();
+  @override
+  Stream<Map<String, Object?>> get messages => _incoming.stream;
+  @override
+  void send(Map<String, Object?> message) {}
+}
+
+void main() {
+  test('a PRE-STAMP bundle (no bundleVersion) fails ready with StaleRunnerBundle', () async {
+    final b = NomosBridge(_StampedRunner(null));
+    await expectLater(b.ready, throwsA(isA<StaleRunnerBundle>()));
+  });
+
+  test('an OLDER stamp fails ready, and the error names found/expected + the remedy', () async {
+    final b = NomosBridge(_StampedRunner('0.53.1'));
+    Object? err;
+    try {
+      await b.ready;
+    } catch (e) {
+      err = e;
+    }
+    expect(err, isA<StaleRunnerBundle>());
+    final s = err.toString();
+    expect(s, contains('0.53.1'));
+    expect(s, contains(kExpectedRunnerBundleVersion));
+    expect(s, contains('flutter clean'));
+  });
+
+  test('the CURRENT stamp passes', () async {
+    final b = NomosBridge(_StampedRunner(kExpectedRunnerBundleVersion));
+    await b.ready; // completes
+  });
+
+  test('a NEWER stamp passes (forward-compatible)', () async {
+    final b = NomosBridge(_StampedRunner('99.0.0'));
+    await b.ready;
+  });
+
+  test('unbundled-dev (the in-repo source lane) always passes', () async {
+    final b = NomosBridge(_StampedRunner('unbundled-dev'));
+    await b.ready;
+  });
+
+  test('allowStaleRunnerBundle is the deliberate escape hatch', () async {
+    final b = NomosBridge(_StampedRunner('0.1.0'), allowStaleRunnerBundle: true);
+    await b.ready;
+  });
+}

package/dart/test/webview_bridge_test.dart

@@ -20,7 +20,7 @@ class FakeRunner implements BridgeTransport {
   FakeRunner() {
     // the runner announces readiness at construction.
     scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
   }
 
   @override
@@ -183,7 +183,7 @@ class ReplayTransport implements BridgeTransport {
   Map<String, Object?>? lastRequest;
   ReplayTransport(this.result) {
     scheduleMicrotask(
-        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready'}));
+        () => _incoming.add({'v': kWebviewBridgeVersion, 'event': 'ready', 'bundleVersion': 'unbundled-dev'}));
   }
   @override
   Stream<Map<String, Object?>> get messages => _incoming.stream;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.77.0",
+  "version": "0.77.1",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",