stackables · aarne · Mar 6, 2026 · Mar 6, 2026
diff --git a/.changeset/aot-timeout-error-class.md b/.changeset/aot-timeout-error-class.md
diff --git a/.changeset/fifty-cases-rhyme.md b/.changeset/fifty-cases-rhyme.md
diff --git a/.changeset/many-beds-like.md b/.changeset/many-beds-like.md
diff --git a/.changeset/runtime-parity-fixes.md b/.changeset/runtime-parity-fixes.md
diff --git a/.changeset/stdlib-type-guard-fixes.md b/.changeset/stdlib-type-guard-fixes.md
diff --git a/.changeset/sync-tool-optimisation.md b/.changeset/sync-tool-optimisation.md
diff --git a/.changeset/tool-metadata.md b/.changeset/tool-metadata.md
diff --git a/packages/bridge-compiler/CHANGELOG.md b/packages/bridge-compiler/CHANGELOG.md
@@ -1,5 +1,49 @@
 # @stackables/bridge-compiler
 
+## 2.4.0
+
+### Minor Changes
+
+- [#104](https://github.com/stackables/bridge/pull/104) [`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Multi-Level Control Flow (break N, continue N)
+
+  When working with deeply nested arrays (e.g., mapping categories that contain lists of products), you may want an error deep inside the inner array to skip the outer array element.
+
+  You can append a number to break or continue to specify how many loop levels the signal should pierce.
+
+- [#102](https://github.com/stackables/bridge/pull/102) [`2243c7e`](https://github.com/stackables/bridge/commit/2243c7e7fd23a37c30118e713ae348b833c523fe) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Sync tool optimisation — honour the `sync` flag in ToolMetadata
+
+  When a tool declares `{ sync: true }` in its `.bridge` metadata the engine
+  now enforces and optimises it:
+
+  1. **Enforcement** — if a sync-declared tool returns a Promise, both the
+     runtime and compiled engines throw immediately.
+  2. **Core optimisation** — `callTool()` skips timeout racing, the OTel span
+     wrapper, and all promise handling for sync tools.
+  3. **Compiler optimisation** — generated code uses a dedicated `__callSync()`
+     helper at every call-site, avoiding `await` overhead entirely.
+  4. **Array-map fast path** — when all per-element tools in an array map are
+     sync, the compiled engine generates a dual-path: a synchronous `.map()`
+     branch (no microtask ticks) with a runtime fallback to `for…of + await`
+     for async tools.
+
+  Benchmarks show up to ~50 % latency reduction for compiled array maps
+  with sync tools (100 elements).
+
+### Patch Changes
+
+- [#103](https://github.com/stackables/bridge/pull/103) [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60) Thanks [@aarne](https://github.com/aarne)! - Fix AOT compiler to throw `BridgeTimeoutError` on tool timeout
+
+  AOT-compiled bridges now throw `BridgeTimeoutError` (with the same name and
+  message format as the runtime) when a tool exceeds `toolTimeoutMs`. Previously
+  the generated code constructed a generic `Error`, causing a class mismatch when
+  callers caught and inspected the error type.
+
+- [#103](https://github.com/stackables/bridge/pull/103) [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60) Thanks [@aarne](https://github.com/aarne)! - Fix AOT/runtime parity for null element traversal, catch-null recovery, and non-array source handling
+
+- Updated dependencies [[`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`2243c7e`](https://github.com/stackables/bridge/commit/2243c7e7fd23a37c30118e713ae348b833c523fe), [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac)]:
+  - @stackables/bridge-core@1.5.0
+  - @stackables/bridge-stdlib@1.5.2
+
 ## 2.3.0
 
 ### Minor Changes

diff --git a/packages/bridge-compiler/package.json b/packages/bridge-compiler/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-compiler",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Compiles a BridgeDocument into highly optimized JavaScript code",
   "main": "./build/index.js",
   "type": "module",

diff --git a/packages/bridge-core/CHANGELOG.md b/packages/bridge-core/CHANGELOG.md
@@ -1,5 +1,59 @@
 # @stackables/bridge-core
 
+## 1.5.0
+
+### Minor Changes
+
+- [#104](https://github.com/stackables/bridge/pull/104) [`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Multi-Level Control Flow (break N, continue N)
+
+  When working with deeply nested arrays (e.g., mapping categories that contain lists of products), you may want an error deep inside the inner array to skip the outer array element.
+
+  You can append a number to break or continue to specify how many loop levels the signal should pierce.
+
+- [#102](https://github.com/stackables/bridge/pull/102) [`2243c7e`](https://github.com/stackables/bridge/commit/2243c7e7fd23a37c30118e713ae348b833c523fe) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Sync tool optimisation — honour the `sync` flag in ToolMetadata
+
+  When a tool declares `{ sync: true }` in its `.bridge` metadata the engine
+  now enforces and optimises it:
+
+  1. **Enforcement** — if a sync-declared tool returns a Promise, both the
+     runtime and compiled engines throw immediately.
+  2. **Core optimisation** — `callTool()` skips timeout racing, the OTel span
+     wrapper, and all promise handling for sync tools.
+  3. **Compiler optimisation** — generated code uses a dedicated `__callSync()`
+     helper at every call-site, avoiding `await` overhead entirely.
+  4. **Array-map fast path** — when all per-element tools in an array map are
+     sync, the compiled engine generates a dual-path: a synchronous `.map()`
+     branch (no microtask ticks) with a runtime fallback to `for…of + await`
+     for async tools.
+
+  Benchmarks show up to ~50 % latency reduction for compiled array maps
+  with sync tools (100 elements).
+
+- [#100](https://github.com/stackables/bridge/pull/100) [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac) Thanks [@aarne](https://github.com/aarne)! - Add `ToolMetadata` — per-tool observability controls
+
+  Tools can now attach a `.bridge` property to declare how the engine should
+  instrument them, imported as `ToolMetadata` from `@stackables/bridge`.
+
+  ```ts
+  import type { ToolMetadata } from "@stackables/bridge";
+
+  myTool.bridge = {
+    trace: false, // skip OTel span for this tool
+    log: {
+      execution: "info", // log successful calls at info level
+      errors: "error", // log failures at error level (default)
+    },
+  } satisfies ToolMetadata;
+  ```
+
+### Patch Changes
+
+- [#103](https://github.com/stackables/bridge/pull/103) [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60) Thanks [@aarne](https://github.com/aarne)! - Fix AOT/runtime parity for null element traversal, catch-null recovery, and non-array source handling
+
+- Updated dependencies [[`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac)]:
+  - @stackables/bridge-stdlib@1.5.2
+  - @stackables/bridge-types@1.1.0
+
 ## 1.4.0
 
 ### Minor Changes

diff --git a/packages/bridge-core/package.json b/packages/bridge-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-core",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Bridge runtime engine — execute pre-compiled bridge instructions",
   "main": "./build/index.js",
   "type": "module",

diff --git a/packages/bridge-graphql/CHANGELOG.md b/packages/bridge-graphql/CHANGELOG.md
@@ -1,5 +1,17 @@
 # @stackables/bridge-graphql
 
+## 1.2.0
+
+### Minor Changes
+
+- [#104](https://github.com/stackables/bridge/pull/104) [`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Support optional lookahead resolver with compiler
+
+### Patch Changes
+
+- Updated dependencies [[`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`2243c7e`](https://github.com/stackables/bridge/commit/2243c7e7fd23a37c30118e713ae348b833c523fe), [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac)]:
+  - @stackables/bridge-core@1.5.0
+  - @stackables/bridge-stdlib@1.5.2
+
 ## 1.1.4
 
 ### Patch Changes

diff --git a/packages/bridge-graphql/package.json b/packages/bridge-graphql/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-graphql",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Bridge GraphQL adapter — wire bridges into a GraphQL schema",
   "main": "./build/index.js",
   "type": "module",

diff --git a/packages/bridge-parser/CHANGELOG.md b/packages/bridge-parser/CHANGELOG.md
@@ -1,5 +1,21 @@
 # @stackables/bridge-parser
 
+## 1.4.0
+
+### Minor Changes
+
+- [#104](https://github.com/stackables/bridge/pull/104) [`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Multi-Level Control Flow (break N, continue N)
+
+  When working with deeply nested arrays (e.g., mapping categories that contain lists of products), you may want an error deep inside the inner array to skip the outer array element.
+
+  You can append a number to break or continue to specify how many loop levels the signal should pierce.
+
+### Patch Changes
+
+- Updated dependencies [[`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`2243c7e`](https://github.com/stackables/bridge/commit/2243c7e7fd23a37c30118e713ae348b833c523fe), [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac)]:
+  - @stackables/bridge-core@1.5.0
+  - @stackables/bridge-stdlib@1.5.2
+
 ## 1.3.0
 
 ### Minor Changes

diff --git a/packages/bridge-parser/package.json b/packages/bridge-parser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-parser",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Bridge DSL parser — turns .bridge text into a BridgeDocument (AST)",
   "main": "./build/index.js",
   "type": "module",

diff --git a/packages/bridge-stdlib/CHANGELOG.md b/packages/bridge-stdlib/CHANGELOG.md
@@ -1,5 +1,31 @@
 # @stackables/bridge-stdlib
 
+## 1.5.2
+
+### Patch Changes
+
+- [#103](https://github.com/stackables/bridge/pull/103) [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60) Thanks [@aarne](https://github.com/aarne)! - Fix `filter`, `find`, `toLowerCase`, `toUpperCase`, `trim`, and `length` crashing on unexpected input types
+
+- [#100](https://github.com/stackables/bridge/pull/100) [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac) Thanks [@aarne](https://github.com/aarne)! - Add `ToolMetadata` — per-tool observability controls
+
+  Tools can now attach a `.bridge` property to declare how the engine should
+  instrument them, imported as `ToolMetadata` from `@stackables/bridge`.
+
+  ```ts
+  import type { ToolMetadata } from "@stackables/bridge";
+
+  myTool.bridge = {
+    trace: false, // skip OTel span for this tool
+    log: {
+      execution: "info", // log successful calls at info level
+      errors: "error", // log failures at error level (default)
+    },
+  } satisfies ToolMetadata;
+  ```
+
+- Updated dependencies [[`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac)]:
+  - @stackables/bridge-types@1.1.0
+
 ## 1.5.1
 
 ### Patch Changes

diff --git a/packages/bridge-stdlib/package.json b/packages/bridge-stdlib/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-stdlib",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Bridge standard library — httpCall, string, array, and audit tools",
   "main": "./build/index.js",
   "type": "module",

diff --git a/packages/bridge-types/CHANGELOG.md b/packages/bridge-types/CHANGELOG.md
@@ -1,5 +1,26 @@
 # @stackables/bridge-types
 
+## 1.1.0
+
+### Minor Changes
+
+- [#100](https://github.com/stackables/bridge/pull/100) [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac) Thanks [@aarne](https://github.com/aarne)! - Add `ToolMetadata` — per-tool observability controls
+
+  Tools can now attach a `.bridge` property to declare how the engine should
+  instrument them, imported as `ToolMetadata` from `@stackables/bridge`.
+
+  ```ts
+  import type { ToolMetadata } from "@stackables/bridge";
+
+  myTool.bridge = {
+    trace: false, // skip OTel span for this tool
+    log: {
+      execution: "info", // log successful calls at info level
+      errors: "error", // log failures at error level (default)
+    },
+  } satisfies ToolMetadata;
+  ```
+
 ## 1.0.1
 
 ### Patch Changes

diff --git a/packages/bridge-types/package.json b/packages/bridge-types/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-types",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Shared type definitions for the Bridge ecosystem",
   "main": "./build/index.js",
   "type": "module",

diff --git a/packages/bridge/CHANGELOG.md b/packages/bridge/CHANGELOG.md
@@ -1,5 +1,15 @@
 # @stackables/bridge
 
+## 2.2.1
+
+### Patch Changes
+
+- Updated dependencies [[`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c), [`b213e9f`](https://github.com/stackables/bridge/commit/b213e9f49ed5da80e7d9a1b9e161586e59b3719c), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`fc6c619`](https://github.com/stackables/bridge/commit/fc6c6195dec524c880ac20f3057e776f76583f60), [`2243c7e`](https://github.com/stackables/bridge/commit/2243c7e7fd23a37c30118e713ae348b833c523fe), [`8e5b2e2`](https://github.com/stackables/bridge/commit/8e5b2e21796cfd7e9a9345225d94ceb8bfc39bac)]:
+  - @stackables/bridge-parser@1.4.0
+  - @stackables/bridge-core@1.5.0
+  - @stackables/bridge-graphql@1.2.0
+  - @stackables/bridge-stdlib@1.5.2
+
 ## 2.2.0
 
 ### Minor Changes

diff --git a/packages/bridge/package.json b/packages/bridge/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Declarative dataflow for GraphQL",
   "main": "./build/index.js",
   "type": "module",