@sanqianx/project-knowledge 5.0.23 → 5.0.25

package/_site/_test/helpers/parallel-knowledge-fixture.js

@@ -0,0 +1,255 @@
+'use strict';
+// Lane-owned fixture helpers for the parallel knowledge verification batch.
+// Portability contract: nothing here may hard-code a developer path.
+// The temp root is resolved as PK_TEST_TEMP_ROOT -> TEMP/TMP/TMPDIR ->
+// os.tmpdir(), and every artefact is created with mkdtemp outside the
+// repository, so the same helpers work on a developer machine and on CI.
+// Isolation contract: the helpers themselves clear the ambient module URLs
+// and the live data directories, so a test entry point never depends on the
+// caller remembering `env -u`, and never reaches the developer's real
+// 5757/5790/8787/8790 endpoints or the real HOME.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const net = require('node:net');
+const { execFileSync, spawn } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+// The developer's live surfaces. A test may never bind or talk to them.
+const FORBIDDEN_PORTS = new Set([5757, 5790, 8787, 8790]);
+
+// Ambient module addresses that would otherwise point a test at a live
+// instance. The product falls back to them when no explicit URL is given.
+const AMBIENT_MODULE_URLS = [
+  'KB_KNOWLEDGE_ENGINE_URL',
+  'KB_VECTORHUB_URL',
+  'KB_TERMINAL_URL',
+  'KB_EVENTBRIDGE_URL',
+  'KB_EVENT_BRIDGE_URL',
+];
+
+function isInside(candidate, parent) {
+  const relative = path.relative(parent, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveTempRoot() {
+  const candidates = [process.env.PK_TEST_TEMP_ROOT, process.env.TEMP, process.env.TMP, process.env.TMPDIR];
+  const chosen = candidates.find(value => value && String(value).trim());
+  const root = path.resolve(chosen ? String(chosen).trim() : os.tmpdir());
+  if (isInside(root, REPO_ROOT)) {
+    throw new Error(`refusing to use a temp root inside the repository: ${root}`);
+  }
+  return root;
+}
+
+function ensureTempRoot() {
+  const root = resolveTempRoot();
+  fs.mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function makeTempDir(prefix = 'parallel-knowledge') {
+  const root = ensureTempRoot();
+  const dir = fs.mkdtempSync(path.join(root, `${prefix}-`));
+  if (isInside(dir, REPO_ROOT)) throw new Error(`refusing to create a fixture inside the repository: ${dir}`);
+  return dir;
+}
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, windowsHide: true, encoding: 'utf8' }).trim();
+}
+
+function sha256Buffer(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function sha256File(filePath) {
+  return fs.existsSync(filePath) ? sha256Buffer(fs.readFileSync(filePath)) : null;
+}
+
+// A real Git worktree with real commits. `files` are committed in order.
+function makeRepo(root, name, commits = []) {
+  const repoPath = path.join(root, name);
+  fs.mkdirSync(repoPath, { recursive: true });
+  git(repoPath, ['init', '-q']);
+  git(repoPath, ['config', 'user.email', 'parallel-knowledge@local.invalid']);
+  git(repoPath, ['config', 'user.name', 'Parallel Knowledge Test']);
+  git(repoPath, ['config', 'commit.gpgsign', 'false']);
+  const shas = [];
+  for (const commit of commits) {
+    for (const [file, content] of Object.entries(commit.files || {})) {
+      const target = path.join(repoPath, file);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, content, 'utf8');
+    }
+    git(repoPath, ['add', '-A']);
+    git(repoPath, ['commit', '-q', '-m', commit.message || 'fixture commit']);
+    shas.push(git(repoPath, ['rev-parse', 'HEAD']));
+  }
+  return { repoPath, shas, head: shas[shas.length - 1] || null };
+}
+
+function makeKnowledgeDir(root, name) {
+  const knowledgePath = path.join(root, name);
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  return knowledgePath;
+}
+
+// Relative path -> sha256 for every file below `dir`.
+function hashTree(dir) {
+  const out = {};
+  if (!fs.existsSync(dir)) return out;
+  const walk = current => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(absolute);
+      else out[path.relative(dir, absolute).replace(/\\/g, '/')] = sha256File(absolute);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+function assertAllowedPort(port, what = 'port') {
+  if (FORBIDDEN_PORTS.has(Number(port))) {
+    throw new Error(`refusing to use the live ${what} ${port}`);
+  }
+  return Number(port);
+}
+
+function assertAllowedEndpoint(url, what = 'endpoint') {
+  const parsed = new URL(String(url));
+  const port = parsed.port ? Number(parsed.port) : (parsed.protocol === 'https:' ? 443 : 80);
+  if (FORBIDDEN_PORTS.has(port)) throw new Error(`refusing to contact the live ${what} ${url}`);
+  return url;
+}
+
+async function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => {
+        try { resolve(assertAllowedPort(port)); } catch (error) { reject(error); }
+      });
+    });
+  });
+}
+
+async function waitForHttp(url, timeoutMs = 20000) {
+  assertAllowedEndpoint(url, 'service');
+  const until = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < until) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      if (response.ok) return true;
+      lastError = new Error(`HTTP ${response.status}`);
+    } catch (error) { lastError = error; }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`Timed out waiting for ${url}: ${lastError && lastError.message}`);
+}
+
+// The environment a child may inherit: no ambient module address, no live
+// data directory, no real HOME.
+function sanitizedEnv(extra = {}) {
+  const env = { ...process.env, ...extra };
+  for (const key of AMBIENT_MODULE_URLS) delete env[key];
+  return env;
+}
+
+function spawnNode(args, env = {}) {
+  const child = spawn(process.execPath, args, {
+    env: sanitizedEnv(env),
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const output = { stdout: '', stderr: '' };
+  child.stdout.on('data', chunk => { output.stdout += chunk; });
+  child.stderr.on('data', chunk => { output.stderr += chunk; });
+  const exited = new Promise(resolve => child.once('close', code => resolve({ code, ...output })));
+  return { child, exited, output };
+}
+
+async function eventually(fn, timeoutMs = 15000, intervalMs = 25) {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) {
+    if (await fn()) return true;
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+  return false;
+}
+
+function removeTree(dir) {
+  if (!dir) return;
+  fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+}
+
+// Isolate the current process. This MUST run before any product module is
+// required, because the product reads its data directories and module
+// addresses from the environment. It returns the isolated paths so the
+// caller can clean them up.
+function isolateProcess() {
+  if (isolateProcess.done) return isolateProcess.state;
+  const root = makeTempDir('parallel-knowledge-isolate');
+  const dataHome = path.join(root, 'kb-data');
+  const knowledgeHome = path.join(root, 'kb-knowledge-data');
+  const bridgeHome = path.join(root, 'event-bridge-home');
+  const home = path.join(root, 'home');
+  for (const dir of [dataHome, knowledgeHome, bridgeHome, home]) fs.mkdirSync(dir, { recursive: true });
+
+  for (const key of AMBIENT_MODULE_URLS) delete process.env[key];
+  process.env.KB_DATA_DIR = dataHome;
+  process.env.KB_KNOWLEDGE_DATA_DIR = knowledgeHome;
+  process.env.AI_CODING_EVENT_BRIDGE_HOME = bridgeHome;
+  process.env.KB_MODULES_AUTOSTART = '0';
+
+  // The real HOME must never be read or written by a lane test.
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  const parsed = path.parse(home);
+  process.env.HOMEDRIVE = parsed.root;
+  process.env.HOMEPATH = parsed.root === path.sep ? home.slice(1) : home.slice(parsed.root.length);
+
+  isolateProcess.state = { root, dataHome, knowledgeHome, bridgeHome, home };
+  isolateProcess.done = true;
+  return isolateProcess.state;
+}
+
+function cleanupIsolatedProcess() {
+  if (!isolateProcess.done) return;
+  removeTree(isolateProcess.state.root);
+  isolateProcess.done = false;
+  isolateProcess.state = null;
+}
+
+module.exports = {
+  REPO_ROOT,
+  FORBIDDEN_PORTS,
+  AMBIENT_MODULE_URLS,
+  resolveTempRoot,
+  ensureTempRoot,
+  makeTempDir,
+  makeRepo,
+  makeKnowledgeDir,
+  hashTree,
+  sha256File,
+  sha256Buffer,
+  git,
+  freePort,
+  waitForHttp,
+  spawnNode,
+  sanitizedEnv,
+  eventually,
+  removeTree,
+  assertAllowedPort,
+  assertAllowedEndpoint,
+  isolateProcess,
+  cleanupIsolatedProcess,
+};

package/_site/_test/helpers/parallel-logging-acceptance-fixture.js

@@ -0,0 +1,111 @@
+'use strict';
+// P-LOG-ACCEPTANCE-01 lane-exclusive fixture (prefix parallel-logging-acceptance-*).
+//
+// Builds an isolated product data dir with N registered projects and
+// pre-written structured log records, mirroring helpers/logging-ui-fixture.js
+// (read-only reference) but with multi-project isolation support for
+// LOG-003/LOG-005/LOG-006. All directories live under the lane temp root the
+// driver installed into TEMP/TMP/TMPDIR (D:/SanQian.Xu/.project-knowledge-test-temp),
+// never the developer's real HOME.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { StorageLayout } = require('../../lib/storage-layout');
+const { SettingsStore } = require('../../lib/settings-store');
+const { ProjectRegistryStore } = require('../../lib/project-registry-store');
+const { ProjectStore } = require('../../lib/project-store');
+const { Logger } = require('../../lib/structured-logger');
+const { controlPath } = require('../../lib/runtime-control');
+const { makeRepo } = require('../fixtures/make-git-repos');
+
+// The product's runtime-control listens on a filesystem unix socket at
+// <dataDir>/runtime-control.sock on POSIX (runtime-control.js:14; Windows uses
+// a hashed named pipe). Linux sun_path allows 107 chars (macOS 103), so the
+// dataDir path this fixture builds under os.tmpdir() must leave room for the
+// 21-char socket name. CI 40075242420 (linux24): the old 'pk-logging-acc-'
+// prefix made the logfixr2-normal dataDir 88 chars -> a 109-char socket ->
+// net.listen refused it, the server exited 1 before the health gate with empty
+// pipes, and normalhook timed out. 'pk-la-' keeps every lane case <= 100 even
+// on the CI temp root (/home/runner/work/_temp, 23 chars).
+const POSIX_SOCKET_CHAR_LIMIT = 103; // strictest common budget (macOS); all lane cases fit
+
+function assertPosixSocketBudget(dataDir) {
+  if (process.platform === 'win32') return dataDir; // named pipe, no sun_path
+  const socketPath = controlPath(dataDir);
+  if (socketPath.length > POSIX_SOCKET_CHAR_LIMIT) {
+    throw new Error(`fixture dataDir makes the POSIX control socket ${socketPath.length} chars (limit ${POSIX_SOCKET_CHAR_LIMIT}): ${dataDir}`);
+  }
+  return dataDir;
+}
+
+async function createLoggingAcceptanceFixture(options = {}) {
+  const caseId = options.caseId || 'case';
+  const dataDir = assertPosixSocketBudget(fs.mkdtempSync(path.join(require('node:os').tmpdir(), `pk-la-${caseId}-`)));
+  if (options.freshProduct !== false) require('../../lib/product-data').initializeProductData(dataDir);
+  const knowledgeRoot = path.join(dataDir, 'knowledge-root');
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  const layout = new StorageLayout({ dataDir });
+  const settingsStore = new SettingsStore({ layout });
+  const registryStore = new ProjectRegistryStore({ layout });
+  const projectStore = new ProjectStore({ layout });
+
+  await settingsStore.initialize({
+    knowledge: { rootPath: knowledgeRoot },
+    logging: { levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'], retentionDays: 365, maxTotalSizeMB: 2048 },
+  });
+  await registryStore.initialize();
+
+  const projects = [];
+  for (const spec of options.projects || []) {
+    const repo = makeRepo({ kind: 'one-commit' });
+    const knowledgePath = path.join(knowledgeRoot, spec.projectId);
+    fs.mkdirSync(knowledgePath, { recursive: true });
+    await projectStore.create(spec.projectId, {
+      displayName: spec.displayName,
+      storageName: spec.projectId,
+      repoPath: repo.path,
+      knowledgePath,
+    }, {
+      trackingStartCommit: repo.headCommit,
+      lastAnalyzedCommit: repo.headCommit,
+      hook: { managedVersion: 2, migrationVersion: 2, lastVerifiedAt: new Date().toISOString() },
+      index: { dirty: false, generation: 1 },
+    });
+    await registryStore.add(spec.projectId, { displayName: spec.displayName });
+    projects.push({ projectId: spec.projectId, displayName: spec.displayName, repo, knowledgePath, headCommit: repo.headCommit });
+  }
+
+  const settings = settingsStore.read().logging;
+  const logger = new Logger({ layout, settingsProvider: () => settings });
+
+  return {
+    caseId,
+    dataDir,
+    layout,
+    projects,
+    logger,
+    cleanup() {
+      for (const project of projects) { try { project.repo.cleanup(); } catch {} }
+      try { fs.rmSync(dataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); } catch {}
+    },
+  };
+}
+
+// Fixture-time log writer: records carry the caller's fields verbatim so
+// write-time redaction (LOG-006) happens through the real normalizeRecord path.
+async function writeProjectLogs(logger, projectId, records) {
+  for (const record of records) {
+    await logger.log(record.level || 'info', record.event, record.message, {
+      projectId,
+      projectSlug: projectId,
+      projectDisplayName: record.projectDisplayName || projectId,
+      operationId: record.operationId || '',
+      component: record.component || 'acceptance-driver',
+      commitSha: record.commitSha || '',
+      context: record.context || {},
+      ...(record.error ? { error: record.error } : {}),
+    });
+  }
+}
+
+module.exports = { createLoggingAcceptanceFixture, writeProjectLogs, assertPosixSocketBudget, POSIX_SOCKET_CHAR_LIMIT };

package/_site/_test/helpers/parallel-logging-acceptance-proxy.js

@@ -0,0 +1,106 @@
+'use strict';
+// P-LOG-ACCEPTANCE-01 lane-exclusive observation proxy (prefix
+// parallel-logging-acceptance-*). The real product page points at this proxy;
+// the proxy forwards to the isolated server. It exists only to observe and
+// shape the network the real browser sees:
+//   * count open connections per pathname prefix (LOG-004: the diagnostics
+//     dialog's SSE stream must actually disconnect when the dialog closes);
+//   * optionally delay a pathname prefix (LOG-008: the real 3s UI read timeout
+//     fires against a slow /api/logs).
+// SSE responses are piped unbuffered both ways - the page's EventSource
+// behaves exactly as against the origin server.
+
+const http = require('node:http');
+const net = require('node:net');
+
+// One fresh connection per forwarded request: avoids keep-alive reset races
+// between the proxy and the isolated origin during bursty page loads.
+const proxyAgent = new http.Agent({ keepAlive: false });
+
+function createObservationProxy({ targetPort, targetHost = '127.0.0.1', port, host = '127.0.0.1' }) {
+  const state = {
+    activeByPrefix: new Map(),
+    requests: [],
+    upgrades: [],
+    delays: new Map(),
+    setDelay(prefix, ms) { if (ms === null) state.delays.delete(prefix); else state.delays.set(prefix, ms); },
+    snapshot() {
+      return {
+        activeByPrefix: Object.fromEntries(state.activeByPrefix),
+        requests: state.requests.slice(-200),
+        upgrades: state.upgrades.slice(-200),
+      };
+    },
+  };
+
+  const server = http.createServer((req, res) => {
+    const pathname = String(req.url || '').split('?')[0];
+    const entry = { method: req.method, pathname, url: String(req.url || ''), openedAt: new Date().toISOString(), status: null, closedAt: null };
+    state.requests.push(entry);
+    for (const [prefix] of state.activeByPrefix) {
+      if (pathname.startsWith(prefix)) state.activeByPrefix.set(prefix, state.activeByPrefix.get(prefix) + 1);
+    }
+    const trackedPrefix = [...state.activeByPrefix.keys()].find(prefix => pathname.startsWith(prefix));
+    const closeTracking = () => {
+      if (entry.closedAt) return;
+      entry.closedAt = new Date().toISOString();
+      if (trackedPrefix) state.activeByPrefix.set(trackedPrefix, Math.max(0, state.activeByPrefix.get(trackedPrefix) - 1));
+    };
+    res.on('close', closeTracking);
+
+    const forward = () => {
+      const upstream = http.request({ host: targetHost, port: targetPort, method: req.method, path: req.url, agent: proxyAgent, headers: { ...req.headers, host: `${targetHost}:${targetPort}` } }, upstreamRes => {
+        entry.status = upstreamRes.statusCode;
+        res.writeHead(upstreamRes.statusCode || 502, upstreamRes.headers);
+        upstreamRes.pipe(res);
+      });
+      upstream.on('error', error => { entry.status = 502; entry.error = String(error.message || error); if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' }); res.end(JSON.stringify({ ok: false, error: { message: 'proxy upstream failure' } })); });
+      req.pipe(upstream);
+    };
+
+    const delay = [...state.delays.entries()].find(([prefix]) => pathname.startsWith(prefix));
+    if (delay) setTimeout(forward, delay[1]);
+    else forward();
+  });
+
+  // WebSocket passthrough (the product page multiplexes /api/live over WS);
+  // host/origin are rewritten to the target so the server's same-origin
+  // security check still passes while the page stays pointed at the proxy.
+  server.on('upgrade', (req, socket, head) => {
+    const pathname = String(req.url || '').split('?')[0];
+    const entry = { method: 'UPGRADE', pathname, url: String(req.url || ''), openedAt: new Date().toISOString(), closedAt: null };
+    state.upgrades.push(entry);
+    const target = `${targetHost}:${targetPort}`;
+    const headers = [];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      const name = req.rawHeaders[i].toLowerCase();
+      const value = name === 'host' || name === 'origin' ? (name === 'host' ? target : `http://${target}`) : req.rawHeaders[i + 1];
+      headers.push(`${req.rawHeaders[i]}: ${value}`);
+    }
+    const upstream = net.connect(targetPort, targetHost, () => {
+      upstream.write(`${req.method} ${req.url} HTTP/1.1\r\n${headers.join('\r\n')}\r\n\r\n`);
+      if (head && head.length) upstream.write(head);
+      socket.pipe(upstream);
+      upstream.pipe(socket);
+    });
+    const kill = () => { entry.closedAt = entry.closedAt || new Date().toISOString(); socket.destroy(); upstream.destroy(); };
+    socket.on('error', kill);
+    upstream.on('error', kill);
+    socket.on('close', kill);
+    upstream.on('close', kill);
+  });
+
+  return new Promise(resolve => server.listen(port, host, () => resolve({
+    port: server.address().port,
+    url: `http://${host}:${server.address().port}`,
+    state,
+    trackPrefix(prefix) { state.activeByPrefix.set(prefix, 0); },
+    setDelay(prefix, ms) { state.setDelay(prefix, ms); },
+    async close() {
+      server.closeAllConnections?.();
+      await new Promise(done => server.close(done));
+    },
+  })));
+}
+
+module.exports = { createObservationProxy };

package/_site/_test/helpers/parallel-logging-fix-r2-proxy.js

@@ -0,0 +1,205 @@
+'use strict';
+// P-LOG-SAFETY-R2 lane-exclusive observation proxy (prefix
+// parallel-logging-fix-r2-*). Distinct from the R1 proxy (read-only reuse of
+// that file is not extended): this one adds a SNAPSHOT BARRIER for the
+// deterministic LOG-004 handoff proof.
+//
+// Forwarding rules (only real traffic is delayed/released, never rewritten):
+//   - HTTP: forwarded to the isolated server with host rewritten. GET
+//     /api/logs?... (the diagnostics snapshot) can be held AFTER the server
+//     produced the response: the exact original bytes are released later.
+//   - WebSocket /api/live: raw upgrade passthrough (host/origin rewritten to
+//     the target) with text-frame TAPPING in both directions so the wire
+//     timeline (subscribe frames with streamCursor, gateway event frames) is
+//     auditable evidence.
+
+const http = require('node:http');
+const crypto = require('node:crypto');
+
+function createGapProxy(options) {
+  const { targetPort, port } = options;
+  const targetHost = '127.0.0.1';
+  const events = [];
+  let seq = 0;
+  const record = (kind, detail = {}) => {
+    events.push({ seq: ++seq, at: new Date().toISOString(), kind, ...detail });
+  };
+
+  let barrierArmed = false;
+  let barrierResolve = null;
+  const barrierHeld = new Promise(resolve => { barrierResolve = resolve; });
+  let barrierInfo = null;
+  let releaseResolve = null;
+  const released = new Promise(resolve => { releaseResolve = resolve; });
+
+  const sockets = new Set();
+  const server = http.createServer((req, res) => {
+    const url = req.url || '/';
+    const isSnapshot = req.method === 'GET' && url.startsWith('/api/logs?');
+    const held = barrierArmed && isSnapshot;
+    if (held) barrierArmed = false;
+    record('request', { method: req.method, url, held });
+
+    const upstream = http.request({
+      host: targetHost,
+      port: targetPort,
+      method: req.method,
+      path: url,
+      headers: { ...req.headers, host: `${targetHost}:${targetPort}` },
+      agent: false,
+    }, upstreamRes => {
+      const chunks = [];
+      upstreamRes.on('data', chunk => chunks.push(chunk));
+      upstreamRes.on('end', () => {
+        const body = Buffer.concat(chunks);
+        const deliver = () => {
+          const headers = { ...upstreamRes.headers };
+          delete headers['transfer-encoding'];
+          delete headers['content-length'];
+          headers['content-length'] = String(body.length);
+          res.writeHead(upstreamRes.statusCode, headers);
+          res.end(body);
+          record('response', { method: req.method, url, status: upstreamRes.statusCode, byteLength: body.length, releasedFromBarrier: held });
+        };
+        if (!held) return deliver();
+        barrierInfo = {
+          url,
+          status: upstreamRes.statusCode,
+          byteLength: body.length,
+          sha256: crypto.createHash('sha256').update(body).digest('hex'),
+          heldAt: new Date().toISOString(),
+        };
+        try {
+          const parsed = JSON.parse(body.toString('utf8'));
+          barrierInfo.entries = (parsed.entries || []).length;
+          barrierInfo.newestEntryId = (parsed.entries || [])[0]?.id || null;
+          barrierInfo.streamCursor = parsed.streamCursor || '';
+          barrierInfo.health = parsed.health || null;
+        } catch (error) { barrierInfo.parseError = String(error.message); }
+        record('barrier-held', { ...barrierInfo });
+        barrierResolve(barrierInfo);
+        released.then(() => {
+          record('barrier-released', { url, at: new Date().toISOString() });
+          deliver();
+        });
+      });
+    });
+    upstream.on('error', error => {
+      record('upstream-error', { url, error: String(error.message) });
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'proxy upstream error' }));
+    });
+    req.pipe(upstream);
+  });
+
+  // Minimal RFC6455 text-frame tap (no negotiation of compression happens:
+  // the gateway's ws server runs with default options).
+  const makeFrameTap = direction => {
+    let tapBuffer = Buffer.alloc(0);
+    return chunk => {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    tapBuffer = Buffer.concat([tapBuffer, buf]);
+    for (;;) {
+      if (tapBuffer.length < 2) break;
+      const second = tapBuffer[1];
+      const opcode = tapBuffer[0] & 0x0f;
+      const masked = (second & 0x80) !== 0;
+      let len = second & 0x7f;
+      let offset = 2;
+      if (len === 126) { if (tapBuffer.length < offset + 2) break; len = tapBuffer.readUInt16BE(offset); offset += 2; }
+      else if (len === 127) { if (tapBuffer.length < offset + 8) break; len = Number(tapBuffer.readBigUInt64BE(offset)); offset += 8; }
+      let maskKey = null;
+      if (masked) { if (tapBuffer.length < offset + 4) break; maskKey = tapBuffer.subarray(offset, offset + 4); offset += 4; }
+      if (tapBuffer.length < offset + len) break;
+      let payload = tapBuffer.subarray(offset, offset + len);
+      if (masked) { const out = Buffer.alloc(len); for (let i = 0; i < len; i++) out[i] = payload[i] ^ maskKey[i % 4]; payload = out; }
+      tapBuffer = tapBuffer.subarray(offset + len);
+      if (opcode === 0x1) {
+        const text = payload.toString('utf8');
+        const detail = { direction, length: len };
+        try {
+          const message = JSON.parse(text);
+          detail.type = message.type || null;
+          if (message.type === 'subscribe' || message.type === 'unsubscribe') { detail.id = message.id; detail.route = String(message.route || '').slice(0, 400); }
+          if (message.type === 'event') { detail.eventId = message.id; detail.event = message.event; detail.cursor = message.cursor || null; detail.dataSnippet = String(message.data || '').slice(0, 1200); }
+          if (message.type === 'open' || message.type === 'error') detail.id = message.id;
+        } catch { detail.textSnippet = text.slice(0, 200); }
+        record('ws-frame', detail);
+      }
+    }
+    };
+  };
+
+  server.on('upgrade', (req, socket, head) => {
+    record('upgrade', { url: req.url || '/', origin: req.headers.origin || null });
+    const upstream = http.request({
+      host: targetHost,
+      port: targetPort,
+      method: 'GET',
+      path: req.url,
+      headers: {
+        ...req.headers,
+        host: `${targetHost}:${targetPort}`,
+        origin: `http://${targetHost}:${targetPort}`,
+      },
+      agent: false,
+    });
+    upstream.on('upgrade', (upstreamRes, upstreamSocket, upstreamHead) => {
+      socket.write(
+        `HTTP/1.1 101 Switching Protocols\r\n` +
+        `Upgrade: websocket\r\n` +
+        `Connection: Upgrade\r\n` +
+        `Sec-WebSocket-Accept: ${upstreamRes.headers['sec-websocket-accept']}\r\n` +
+        (upstreamRes.headers['sec-websocket-protocol'] ? `Sec-WebSocket-Protocol: ${upstreamRes.headers['sec-websocket-protocol']}\r\n` : '') +
+        `\r\n`
+      );
+      if (upstreamHead?.length) socket.write(upstreamHead);
+      if (head?.length) upstreamSocket.write(head);
+      const clientTap = makeFrameTap('client->server');
+      const serverTap = makeFrameTap('server->client');
+      socket.on('data', chunk => { clientTap(chunk); upstreamSocket.write(chunk); });
+      upstreamSocket.on('data', chunk => { serverTap(chunk); socket.write(chunk); });
+      const kill = () => { try { socket.destroy(); } catch {} try { upstreamSocket.destroy(); } catch {} sockets.delete(socket); sockets.delete(upstreamSocket); };
+      socket.on('error', kill); upstreamSocket.on('error', kill);
+      socket.on('close', kill); upstreamSocket.on('close', kill);
+      sockets.add(socket); sockets.add(upstreamSocket);
+    });
+    upstream.on('error', error => {
+      record('upgrade-error', { error: String(error.message) });
+      socket.destroy();
+    });
+    upstream.end();
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve({
+      url: `http://127.0.0.1:${server.address().port}`,
+      events,
+      armSnapshotBarrier() { barrierArmed = true; record('barrier-armed', {}); },
+      async waitBarrier(timeoutMs = 10000) {
+        const timer = new Promise((_, reject) => setTimeout(() => reject(new Error('barrier timeout')), timeoutMs));
+        return Promise.race([barrierHeld, timer]);
+      },
+      releaseBarrier() { record('barrier-release-command', {}); releaseResolve(); },
+      get barrierInfo() { return barrierInfo; },
+      close() {
+        return new Promise(resolve => {
+          for (const socket of sockets) { try { socket.destroy(); } catch {} }
+          server.close(() => resolve());
+          setTimeout(resolve, 2000);
+          server.closeAllConnections?.();
+        });
+      },
+    }));
+  });
+}
+
+function decodeStreamCursor(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(Buffer.from(String(value), 'base64url').toString('utf8'));
+  } catch { return null; }
+}
+
+module.exports = { createGapProxy, decodeStreamCursor };