move response topic default off $SYS + reactive peer-mode design doc

ARCHITECTURE.md

@@ -411,7 +411,7 @@ Both instances share the same WASM module (one load per page). `memory-store.ts`
 Dynamically imported inside `SyncEngine.connect(serverUrl, wasmModule, getTicket?)`. The engine handles:
 
 - MQTT5 CONNECT with enhanced authentication (`AUTH` / `RE-AUTH` flow) when `getTicket` is provided — the ticket is the JWT, sent as auth data.
-- Request-response correlation via `$SYS/responses/{clientId}/{requestId}` subscription.
+- Request-response correlation via `$DB/clients/{clientId}/{requestId}` subscription (configurable via `responseTopicPrefix`).
 - Topic matching against the `$DB/{entity}/…` topic tree.
 - `x-origin-client-id` user property on every published message so clients can filter their own echoes.
 

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Changed (breaking)
+
+- **`responseTopicPrefix` default moved off `$SYS`.** Default changed from `$SYS/responses` to `$DB/clients`. The previous default published responses under `$SYS`, which the MQTT 5 spec reserves for broker-internal use (§4.7.2) — production brokers (EMQX, HiveMQ, AWS IoT Core) reject client publishes under `$SYS` by default ACL, so the old default only worked against permissive or custom-configured brokers. Per-request response topic shape is unchanged: `{prefix}/{clientId}/{requestId}`. Deployments overriding `responseTopicPrefix` explicitly are unaffected. Deployments relying on the old default must either set `responseTopicPrefix: '$SYS/responses'` to preserve current behavior or update broker ACLs to accept the new `$DB/clients/...` topic.
+
+### Fixed
+
+- **Brittle response-topic regex.** `handleResponseMessage` in `src/sync-engine.ts` built its match regex by prepending `\\$` to `responseTopicPrefix`, which only worked because the default started with `$`. Any prefix not beginning with `$` (e.g. a custom override like `responses`) produced an invalid regex (`\r` was interpreted as carriage return). Replaced with a `String.prototype.startsWith`-based check that works for any prefix value. As a side effect, the handler now binds to the live `clientId` rather than the previous `[^/]+` wildcard segment — defense in depth, since the response subscription is already scoped per client.
+
 ## 0.4.3
 
 ### Added

docs/configuration.md

@@ -11,7 +11,7 @@
 | `topLevelEntities` | `Array<{ entity, subscriptionPattern }>` | Entities synced globally, not scoped |
 | `localOnlyEntities` | `Record<string, EntityDefinition>` | Entities that never touch MQTT |
 | `syncTopicPrefix` | `string` | MQTT topic prefix (default: `$DB`) |
-| `responseTopicPrefix` | `string` | MQTT response prefix (default: `$SYS/responses`) |
+| `responseTopicPrefix` | `string` | MQTT response inbox prefix (default: `$DB/clients`). Per-request response topic is `{prefix}/{clientId}/{requestId}` |
 | `versionField` | `string` | Field name for optimistic version tracking |
 | `updatedAtField` | `string` | Field name for last-updated timestamp |
 | `userScopeField` | `string` | Field name for user-level scoping |

src/internal-utils.ts

@@ -19,3 +19,15 @@ export function isPermanentMutationError(err: unknown): boolean {
     err.message
   );
 }
+
+export function parseResponseRequestId(
+  responsePrefix: string,
+  clientId: string,
+  topic: string
+): string | null {
+  const expected = `${responsePrefix}/${clientId}/`;
+  if (!topic.startsWith(expected)) return null;
+  const requestId = topic.slice(expected.length);
+  if (!requestId || requestId.includes('/')) return null;
+  return requestId;
+}

src/sync-engine.ts

@@ -13,6 +13,7 @@ import type {
   SyncEngine,
 } from './types.ts';
 import { OwnershipError } from './types.ts';
+import { parseResponseRequestId } from './internal-utils.ts';
 
 interface ChangeEvent {
   operation: 'Create' | 'Update' | 'Delete';
@@ -79,7 +80,7 @@ class SyncEngineImpl implements SyncEngine {
     this.clientId = clientId;
     this.config = config;
     this.prefix = config.syncTopicPrefix ?? '$DB';
-    this.responsePrefix = config.responseTopicPrefix ?? '$SYS/responses';
+    this.responsePrefix = config.responseTopicPrefix ?? '$DB/clients';
   }
 
   async connect(
@@ -420,10 +421,9 @@ class SyncEngineImpl implements SyncEngine {
   }
 
   private handleResponseMessage(topic: string, payload: Uint8Array): void {
-    const match = topic.match(new RegExp(`^\\${this.responsePrefix}/[^/]+/(.+)$`));
-    if (!match) return;
+    const requestId = parseResponseRequestId(this.responsePrefix, this.clientId, topic);
+    if (!requestId) return;
 
-    const requestId = match[1];
     const pending = this.pendingRequests.get(requestId);
     if (pending) {
       this.pendingRequests.delete(requestId);

tests/unit/response-topic-parse.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { parseResponseRequestId } from '../../src/internal-utils.ts';
+
+describe('parseResponseRequestId', () => {
+  it('extracts requestId from current default prefix', () => {
+    const requestId = parseResponseRequestId(
+      '$DB/clients',
+      'client-abc',
+      '$DB/clients/client-abc/req-123'
+    );
+    expect(requestId).toBe('req-123');
+  });
+
+  it('extracts requestId from legacy $SYS/responses prefix', () => {
+    const requestId = parseResponseRequestId(
+      '$SYS/responses',
+      'client-abc',
+      '$SYS/responses/client-abc/req-456'
+    );
+    expect(requestId).toBe('req-456');
+  });
+
+  it('extracts requestId from a non-$ custom prefix (regression: old regex broke here)', () => {
+    const requestId = parseResponseRequestId(
+      'responses',
+      'client-abc',
+      'responses/client-abc/req-789'
+    );
+    expect(requestId).toBe('req-789');
+  });
+
+  it('handles a multi-segment custom prefix', () => {
+    const requestId = parseResponseRequestId(
+      'app/v2/responses',
+      'node-1',
+      'app/v2/responses/node-1/uuid-abc'
+    );
+    expect(requestId).toBe('uuid-abc');
+  });
+
+  it('returns null when topic targets a different clientId', () => {
+    expect(
+      parseResponseRequestId('$DB/clients', 'client-abc', '$DB/clients/other-client/req-1')
+    ).toBeNull();
+  });
+
+  it('returns null when topic prefix does not match', () => {
+    expect(
+      parseResponseRequestId('$DB/clients', 'client-abc', '$DB/other/client-abc/req-1')
+    ).toBeNull();
+  });
+
+  it('returns null when requestId segment is empty', () => {
+    expect(
+      parseResponseRequestId('$DB/clients', 'client-abc', '$DB/clients/client-abc/')
+    ).toBeNull();
+  });
+
+  it('returns null when requestId would contain a slash (deeper subtopic)', () => {
+    expect(
+      parseResponseRequestId('$DB/clients', 'client-abc', '$DB/clients/client-abc/req/extra')
+    ).toBeNull();
+  });
+
+  it('returns null for an unrelated topic on the same broker', () => {
+    expect(
+      parseResponseRequestId('$DB/clients', 'client-abc', '$DB/task/scope-1/events/created')
+    ).toBeNull();
+  });
+});