@cgh567/agent 2.4.3 → 2.4.5

package/daemon/lib/headroom-proxy-manager.js

@@ -0,0 +1,319 @@
+'use strict';
+/**
+ * daemon/lib/headroom-proxy-manager.js
+ *
+ * Singleton process manager for the Helios Compression Server
+ * (lib/compression/dist/server.js).
+ *
+ * Responsibilities:
+ *   - Find a free TCP port in range 8787–8796
+ *   - Spawn server.js as a child process (no shell — cross-platform)
+ *   - Wait for the {"event":"ready",...} JSON line on child stdout
+ *   - Expose getBaseUrl() so all call sites can reach the server
+ *   - Auto-restart on crash with exponential backoff (1s → 2s → ... → 30s)
+ *   - Log lifecycle events to daemon/headroom-proxy.log (append)
+ *
+ * Interface (matches all call sites in helios-api.js, helios-company-daemon.js,
+ * helios-rpc-adapter.js, planning.ts):
+ *   HeadroomProxyManager.getInstance(): HeadroomProxyManager
+ *   instance.start(): Promise<{baseUrl: string}>
+ *   instance.getBaseUrl(): string | null
+ *   instance.stop(): Promise<void>
+ *
+ * Cross-platform: uses process.execPath (Node binary), path.join, net.createServer.
+ * No hardcoded company IDs. Port is dynamic — injected via HEADROOM_PROXY_URL env.
+ */
+
+const path        = require('path');
+const net         = require('net');
+const fs          = require('fs');
+const { spawn }   = require('child_process');
+
+// Path to the compiled compression server entry point.
+// Relative from this file: daemon/lib/ → ../../lib/compression/dist/server.js
+const SERVER_SCRIPT = path.join(__dirname, '..', '..', 'lib', 'compression', 'dist', 'server.js');
+
+// Log file: daemon/headroom-proxy.log (same dir as daemon/, sibling of lib/)
+const LOG_FILE = path.join(__dirname, '..', 'headroom-proxy.log');
+
+// Port scan range — 50 ports gives headroom when multiple test suites run concurrently
+// (vitest maxWorkers=4, each test file may start its own server instance).
+//
+// PRECONDITION (O2): HEADROOM_PORT_START must be set in process.env BEFORE the first
+// require() of this module. PORT_START is a module-level constant evaluated once at
+// load time. Setting the env var after require() has no effect on the running instance.
+// Tests that need a custom range must: (1) set process.env.HEADROOM_PORT_START,
+// (2) delete require.cache[managerPath], (3) require() again. See test files for pattern.
+//
+// Can be overridden via env for specific deployment constraints:
+//   HEADROOM_PORT_START=9000 to use a different range entirely.
+const PORT_START = parseInt(process.env.HEADROOM_PORT_START || '8787', 10);
+const PORT_END   = PORT_START + 49; // 50 ports
+
+// Backoff config (ms)
+const BACKOFF_INITIAL = 1000;
+const BACKOFF_MAX     = 30000;
+const READY_TIMEOUT   = 15000; // 15s max wait for ready signal
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Append a JSON line to the proxy log. Fail-open — never throws.
+ */
+function appendLog(obj) {
+  try {
+    fs.appendFileSync(LOG_FILE, JSON.stringify({ ...obj, ts: Date.now() }) + '\n');
+  } catch (_) { /* non-critical */ }
+}
+
+/**
+ * Find the first free TCP port in [start, end].
+ * Returns a Promise<number> or rejects if none are free.
+ */
+function findFreePort(start, end) {
+  return new Promise((resolve, reject) => {
+    let current = start;
+
+    function tryPort() {
+      if (current > end) {
+        reject(new Error(`No free port found in range ${start}–${end}`));
+        return;
+      }
+      const server = net.createServer();
+      server.unref();
+      server.listen(current, '127.0.0.1', () => {
+        const port = server.address().port;
+        server.close(() => resolve(port));
+      });
+      server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          current++;
+          tryPort();
+        } else {
+          reject(err);
+        }
+      });
+    }
+
+    tryPort();
+  });
+}
+
+// ── Singleton ─────────────────────────────────────────────────────────────────
+
+let _instance = null;
+
+class HeadroomProxyManager {
+  constructor() {
+    this._child      = null;
+    this._baseUrl    = null;
+    this._port       = null;
+    this._stopped    = false;
+    this._backoffMs  = BACKOFF_INITIAL;
+    this._starting   = false;
+    this._startPromise = null;
+  }
+
+  /**
+   * Returns the module-level singleton. Safe to call from multiple require()s.
+   */
+  static getInstance() {
+    if (!_instance) _instance = new HeadroomProxyManager();
+    return _instance;
+  }
+
+  /**
+   * Start the compression server. Idempotent — multiple calls return the same promise.
+   * Resolves with {baseUrl} once the server emits its ready signal.
+   * Rejects if server fails to start within READY_TIMEOUT ms.
+   */
+  start() {
+    // Already started
+    if (this._baseUrl) return Promise.resolve({ baseUrl: this._baseUrl });
+    // In-flight start — reuse same promise
+    if (this._startPromise) return this._startPromise;
+
+    this._startPromise = this._doStart().then((result) => {
+      this._startPromise = null;
+      return result;
+    }).catch((err) => {
+      this._startPromise = null;
+      throw err;
+    });
+
+    return this._startPromise;
+  }
+
+  /**
+   * Internal: find a port, spawn the server, wait for ready.
+   */
+  async _doStart() {
+    this._stopped = false;
+
+    // Verify server script exists
+    if (!fs.existsSync(SERVER_SCRIPT)) {
+      throw new Error(`Compression server not found at ${SERVER_SCRIPT}`);
+    }
+
+    const port = await findFreePort(PORT_START, PORT_END);
+    this._port = port;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Compression server did not emit ready within ${READY_TIMEOUT}ms on port ${port}`));
+        if (this._child) {
+          try { this._child.kill(); } catch (_) {}
+          this._child = null;
+        }
+      }, READY_TIMEOUT);
+
+      const child = spawn(
+        process.execPath,
+        [SERVER_SCRIPT],
+        {
+          stdio : ['ignore', 'pipe', 'pipe'],
+          env   : { ...process.env, HEADROOM_PORT: String(port) },
+          shell : false,
+        }
+      );
+
+      this._child = child;
+
+      let stdoutBuf = '';
+      child.stdout.on('data', (chunk) => {
+        stdoutBuf += chunk.toString('utf-8');
+        const lines = stdoutBuf.split('\n');
+        stdoutBuf = lines.pop(); // keep partial line
+
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const parsed = JSON.parse(line);
+            if (parsed.event === 'ready') {
+              clearTimeout(timer);
+              this._baseUrl = `http://127.0.0.1:${parsed.port || port}`;
+              this._backoffMs = BACKOFF_INITIAL; // reset backoff on successful start
+              appendLog({ event: 'ready', port: parsed.port || port, pid: child.pid });
+              resolve({ baseUrl: this._baseUrl });
+            }
+          } catch (_) { /* non-JSON stdout line — skip */ }
+        }
+      });
+
+      child.stderr.on('data', (chunk) => {
+        // Forward compression server stderr to our stderr for visibility
+        process.stderr.write(`[compression-server] ${chunk.toString('utf-8')}`);
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        appendLog({ event: 'spawn_error', error: err.message });
+        reject(err);
+      });
+
+      child.on('exit', (code, signal) => {
+        // On Windows, Node.js reports abnormal OS termination as exit code 4294967295
+        // (0xFFFFFFFF — the unsigned 32-bit representation of -1).
+        // This indicates an OS-level process termination (e.g. OOM, crash).
+        if (code === 4294967295) {
+          process.stderr.write(
+            `[headroom-proxy-manager] WARN: compression server on port ${port} exited with abnormal code 0xFFFFFFFF (-1) — ` +
+            `likely an OOM kill or unhandled exception in the server process. ` +
+            `Scheduling restart with backoff.\n`
+          );
+        }
+        appendLog({ event: 'exit', code, signal, port });
+        this._child   = null;
+        this._baseUrl = null;
+
+        // Schedule restart unless intentionally stopped
+        if (!this._stopped) {
+          const delay = this._backoffMs;
+          this._backoffMs = Math.min(this._backoffMs * 2, BACKOFF_MAX);
+          appendLog({ event: 'restart_scheduled', delayMs: delay });
+          setTimeout(() => {
+            if (!this._stopped) {
+              this._doStart().catch((restartErr) => {
+                process.stderr.write(
+                  `[headroom-proxy-manager] Restart failed: ${restartErr.message}\n`
+                );
+              });
+            }
+          }, delay);
+        }
+      });
+    });
+  }
+
+  /**
+   * Returns the base URL of the running compression server, or null if not running.
+   * Never throws.
+   */
+  getBaseUrl() {
+    return this._baseUrl;
+  }
+
+  /**
+   * Stop the compression server and disable auto-restart.
+   *
+   * Awaits the child process exit event (with a 3s safety-net timeout) before
+   * resolving. This eliminates the H2 race where the old child still holds the
+   * TCP port while a subsequent start() call runs findFreePort.
+   *
+   * Safe to call multiple times — idempotent after the first call.
+   */
+  async stop() {
+    this._stopped = true;
+    this._baseUrl = null;
+    const child = this._child;
+    this._child = null;
+
+    if (child) {
+      await new Promise((resolve) => {
+        // Safety net: if exit never fires (e.g. zombie process), resolve after 3s
+        // so callers are never blocked indefinitely.
+        const timeout = setTimeout(resolve, 3000);
+        timeout.unref?.(); // don't hold the event loop open
+
+        child.once('exit', () => {
+          clearTimeout(timeout);
+          resolve();
+        });
+
+        // Send the kill signal.  kill() may throw on Windows if the process
+        // has already exited — catch and resolve immediately in that case.
+        try {
+          child.kill();
+        } catch (_) {
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+    }
+
+    appendLog({ event: 'stopped' });
+  }
+}
+
+/**
+ * buildCompressionEnv() — returns the env fragment to inject into Pi subprocess spawns.
+ *
+ * Called from helios-rpc-adapter.js when building the subprocess env object.
+ * Exported here so it can be tested directly — the test starts a real proxy manager,
+ * calls this function, and asserts HEADROOM_PROXY_URL is set to the real baseUrl.
+ *
+ * Returns { HEADROOM_PROXY_URL: string } when the proxy is running,
+ * or {} when the proxy is not started / getBaseUrl() is null.
+ * Never throws.
+ */
+function buildCompressionEnv() {
+  try {
+    const baseUrl = HeadroomProxyManager.getInstance().getBaseUrl();
+    if (baseUrl) {
+      return { HEADROOM_PROXY_URL: baseUrl };
+    }
+  } catch (_) {}
+  return {};
+}
+
+module.exports = { HeadroomProxyManager, buildCompressionEnv };

package/daemon/lib/intelligence/department-page-generator.js

@@ -327,9 +327,54 @@ function makeDepartmentPageGenerator({ mgQuery, broadcast }) {
 
       rawData = await deptModule.fetchData(companyId);
 
+      // ── Step 1b: Harada cascade enrichment ───────────────────────────────────────
+      // Inject GoalPillar cascade progress for this department so the LLM has
+      // real strategic context even when department-specific signals are sparse.
+      // This is the primary data source for "Work in Progress" and "Decisions & Asks".
+      const cascadeRows = await mgQuery(
+        `MATCH (gp:GoalPillar {companyId: $cid})
+         WHERE gp.department = $dept
+            OR toLower(gp.name) CONTAINS toLower($dept)
+         OPTIONAL MATCH (gp)-[:HAS_CELL]->(ac:ActionCell)
+         OPTIONAL MATCH (t:Task {companyId: $cid})
+           WHERE t.pillarId = gp.id
+         RETURN gp.id AS pillarId, gp.name AS pillarName,
+                gp.l2Strategy AS l2Strategy, gp.l2Content AS l2Content,
+                gp.l2ReviewStatus AS l2ReviewStatus,
+                count(DISTINCT ac) AS totalCells,
+                count(DISTINCT CASE WHEN ac.status = 'closed' THEN ac END) AS closedCells,
+                collect(DISTINCT {id: t.id, title: t.title, status: t.status, originKind: t.originKind})[..5] AS recentTasks
+         ORDER BY gp.createdAt DESC LIMIT 3`,
+        { cid: companyId, dept: department }
+      ).catch(() => null);
+
+      const cascadeArr = cascadeRows && cascadeRows.rows
+        ? cascadeRows.rows
+        : (Array.isArray(cascadeRows) ? cascadeRows : []);
+
+      if (cascadeArr.length > 0) {
+        const pillarSummary = cascadeArr.map((r, i) => {
+          const row = Array.isArray(r) ? {
+            pillarName: r[1], l2Strategy: r[2], l2Content: r[3], l2ReviewStatus: r[4],
+            totalCells: r[5], closedCells: r[6], recentTasks: r[7],
+          } : r;
+          const progress = row.totalCells > 0
+            ? `${row.closedCells}/${row.totalCells} cells closed`
+            : 'no action cells yet';
+          const status = row.l2ReviewStatus ? `review: ${row.l2ReviewStatus}` : 'pending review';
+          return `${row.pillarName}: ${status}, ${progress}. Strategy: ${row.l2Strategy || row.l2Content || '(not yet defined)'}`;
+        }).join('\n');
+        rawData._haradaCascadeSummary = pillarSummary;
+      }
+
       // ── Step 2: Build base prompt ────────────────────────────────────────────────
       const basePrompt = deptModule.buildPrompt(rawData, today);
 
+      // ── Step 2a: Harada cascade context block ────────────────────────────────────
+      const cascadeBlock = rawData._haradaCascadeSummary
+        ? `\nStrategic cascade progress (Hoshin Kanri):\n${rawData._haradaCascadeSummary}\n`
+        : '';
+
       // ── Step 2b: Prior learnings priming block ────────────────────────────
       const priorLearningsRaw = await mgQuery(
         `MATCH (l:DeptLearning {companyId: $cid, department: $dept})
@@ -356,7 +401,7 @@ Additionally, include these fields in your JSON output:
 "learningsStructured": [{"text": "string", "type": "observation|principle|required_change"}]
 `;
 
-      const prompt = basePrompt + primingBlock + additionalOutputSchema;
+      const prompt = basePrompt + cascadeBlock + primingBlock + additionalOutputSchema;
 
       // ── Step 3: Call LLM ───────────────────────────────────────────────────
       const llmText = await callLLM(prompt, MAX_TOKENS);

package/daemon/lib/interpretation-engine.js

@@ -0,0 +1,92 @@
+'use strict';
+/**
+ * interpretation-engine.js — P_EXPLAIN interpretation loop
+ * Creates HITLInteraction nodes for new tasks and queues agent explanation.
+ *
+ * API contract: rawWriteFn is the safe-memgraph rawWrite function
+ * (exported as `{ rawWrite }` from lib/safe-memgraph.js), not an object.
+ * It is called as: rawWriteFn(cypher, params)
+ *
+ * Retry policy (inline CJS — no p-retry dependency):
+ *   3 attempts, exponential backoff 500ms→8000ms, randomised ±25%.
+ *   Every failed attempt logs [hitl_write_retry] at warn level.
+ *   Permanent failure (all attempts exhausted) logs [hitl_write_failed_permanently] at error level.
+ */
+
+const _logger = (() => { try { return require('../lib/logger.js'); } catch { return null; } })();
+const log = (lvl, msg, meta) => {
+  const fn = _logger?.[lvl === 'error' ? 'error' : 'warn'];
+  const text = `[${msg}]${meta ? ' ' + JSON.stringify(meta) : ''}`;
+  if (fn) fn(text);
+  else console[lvl === 'error' ? 'error' : 'warn'](`[${lvl}] ${msg}`, meta ?? '');
+};
+
+/**
+ * Inline exponential-backoff retry — CJS, no external deps.
+ * @param {() => Promise<void>} fn      — async function to retry
+ * @param {string}              label   — structured log event name prefix
+ * @param {{ retries?: number, minTimeout?: number, maxTimeout?: number }} [opts]
+ */
+async function withRetry(fn, label, opts = {}) {
+  const retries    = opts.retries    ?? 3;
+  const minTimeout = opts.minTimeout ?? 500;
+  const maxTimeout = opts.maxTimeout ?? 8000;
+
+  let lastErr;
+  for (let attempt = 1; attempt <= retries + 1; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      const retriesLeft = retries + 1 - attempt;
+      if (retriesLeft === 0) break;
+
+      // Exponential backoff with ±25% jitter
+      const base  = Math.min(minTimeout * Math.pow(2, attempt - 1), maxTimeout);
+      const jitter = base * 0.25 * (Math.random() * 2 - 1);
+      const delay  = Math.max(minTimeout, Math.round(base + jitter));
+
+      log('warn', 'hitl_write_retry', {
+        event: `${label}_retry`,
+        attempt,
+        retriesLeft,
+        delayMs: delay,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+
+  log('error', 'hitl_write_failed_permanently', {
+    event: `${label}_failed_permanently`,
+    err: lastErr instanceof Error ? lastErr.message : String(lastErr),
+  });
+  throw lastErr;
+}
+
+async function createInterpretationExplanation(taskId, companyId, rawWriteFn) {
+  if (!rawWriteFn || typeof rawWriteFn !== 'function' || !taskId || !companyId) return;
+  const hiId = `hitl:interp:${taskId}:${Date.now()}`;
+  await withRetry(
+    () => rawWriteFn(
+      "MERGE (h:HITLInteraction {id: $hiId}) SET h.taskId = $taskId, h.companyId = $companyId, h.kind = 'interpretation', h.status = 'pending', h.createdAt = datetime()",
+      { hiId, taskId, companyId }
+    ),
+    'hitl_interp_create'
+  );
+}
+
+async function resolveInterpretation(hiId, taskId, action, body, rawWriteFn) {
+  if (!rawWriteFn || typeof rawWriteFn !== 'function' || !hiId) return;
+  await rawWriteFn(
+    "MATCH (h:HITLInteraction {id: $hiId}) SET h.status = 'resolved', h.action = $action, h.resolvedAt = datetime()",
+    { hiId, action }
+  );
+  const commentId = `sys:interp:${hiId}`;
+  await rawWriteFn(
+    "MERGE (c:Comment {id: $commentId}) SET c.taskId = $taskId, c.body = $body, c.author = 'system', c.createdAt = datetime()",
+    { commentId, taskId, body: body || `Interpretation ${action}` }
+  );
+}
+
+module.exports = { createInterpretationExplanation, resolveInterpretation };

package/daemon/lib/mental-model-cache.js

@@ -0,0 +1,96 @@
+'use strict';
+/**
+ * mental-model-cache.js — CachedPersonModel node CRUD
+ * Pre-assembled mental models for fast agent brief injection.
+ * Cache is invalidated by enrichmentNeeded flag on Person node.
+ */
+
+const SCHEMA_VERSION = 1;
+
+/**
+ * writeCachedModel — upsert a CachedPersonModel node for a person in a company.
+ *
+ * @param {Function} mgQuery       — Memgraph query function (async)
+ * @param {string}   personId      — Person node id
+ * @param {string}   companyId     — Company node id
+ * @param {object}   assembledModel — Output from assembleMentalModel()
+ */
+async function writeCachedModel(mgQuery, personId, companyId, assembledModel) {
+  const modelId = `model:${companyId}:${personId}`;
+  const contextBrief = assembledModel.contextBrief || '';
+  const faveeJson = JSON.stringify(assembledModel.favee || {});
+  const topicsJson = JSON.stringify((assembledModel.activeTopics || []).slice(0, 10));
+  const questionsJson = JSON.stringify((assembledModel.openQuestions || []).slice(0, 5));
+  const completeness = contextBrief ? 'full' : (faveeJson !== '{}' ? 'partial' : 'none');
+
+  await mgQuery(
+    `MERGE (m:CachedPersonModel {id: $id})
+     ON CREATE SET
+       m.personId = $personId, m.companyId = $companyId,
+       m.contextBrief = $brief, m.faveeJson = $favee,
+       m.topicsJson = $topics, m.questionsJson = $questions,
+       m.assembledAt = localdatetime(), m.completeness = $completeness,
+       m.schemaVersion = $sv
+     ON MATCH SET
+       m.contextBrief = $brief, m.faveeJson = $favee,
+       m.topicsJson = $topics, m.questionsJson = $questions,
+       m.assembledAt = localdatetime(), m.completeness = $completeness,
+       m.dirtyAt = null
+     WITH m
+     MATCH (p:Person {id: $personId})
+     MERGE (p)-[:HAS_CACHED_MODEL]->(m)`,
+    { id: modelId, personId, companyId, brief: contextBrief,
+      favee: faveeJson, topics: topicsJson, questions: questionsJson,
+      completeness, sv: SCHEMA_VERSION }
+  );
+}
+
+/**
+ * invalidateCache — mark a CachedPersonModel dirty so next read triggers a refresh.
+ * Non-fatal: silently ignores errors if the model node doesn't exist yet.
+ *
+ * @param {Function} mgQuery
+ * @param {string}   personId
+ * @param {string}   companyId
+ */
+async function invalidateCache(mgQuery, personId, companyId) {
+  const modelId = `model:${companyId}:${personId}`;
+  await mgQuery(
+    `MATCH (m:CachedPersonModel {id: $id}) SET m.dirtyAt = localdatetime()`,
+    { id: modelId }
+  ).catch(() => {});
+}
+
+/**
+ * getCachedModel — return a cached model if it exists, is not dirty, and is within maxAge.
+ * Returns null if the cache is cold, dirty, or expired.
+ *
+ * @param {Function} mgQuery
+ * @param {string}   personId
+ * @param {string}   companyId
+ * @param {number}   maxAgeMinutes — default 60 minutes
+ * @returns {object|null}
+ */
+async function getCachedModel(mgQuery, personId, companyId, maxAgeMinutes = 60) {
+  const modelId = `model:${companyId}:${personId}`;
+  const rows = await mgQuery(
+    `MATCH (m:CachedPersonModel {id: $id})
+     WHERE m.dirtyAt IS NULL
+       AND m.assembledAt > localdatetime() - duration({minutes: $maxAge})
+     RETURN m.contextBrief, m.faveeJson, m.topicsJson, m.questionsJson,
+            m.assembledAt, m.completeness`,
+    { id: modelId, maxAge: maxAgeMinutes }
+  );
+  if (!rows?.rows?.length) return null;
+  const r = rows.rows[0];
+  return {
+    contextBrief:  r[0],
+    faveeJson:     r[1],
+    topicsJson:    r[2],
+    questionsJson: r[3],
+    assembledAt:   r[4],
+    completeness:  r[5],
+  };
+}
+
+module.exports = { writeCachedModel, invalidateCache, getCachedModel, SCHEMA_VERSION };

package/daemon/lib/project-factory.js

@@ -0,0 +1,47 @@
+'use strict';
+/**
+ * project-factory.js — Creates HeliosProject + ProjectDocument nodes when
+ * a GoalPillar is initialized via tickGoalDecompose().
+ *
+ * Called from daemon/lib/hbo-bridge.js tickGoalDecompose() after
+ * mandala.initializeMandala() succeeds for each GoalPillar.
+ *
+ * ID conventions:
+ *   HeliosProject:    proj:<companyId>:<pillarSlug>
+ *   ProjectDocument:  pdoc:<projectId>:main
+ */
+
+async function ensureProject(mgQuery, companyId, goalId, pillarId, pillarTitle) {
+  const slug   = pillarId.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40);
+  const projId = `proj:${companyId}:${slug}`;
+  const docId  = `pdoc:${projId}:main`;
+
+  await mgQuery(
+    `MERGE (p:HeliosProject {id: $projId})
+     ON CREATE SET
+       p.companyId = $cid,
+       p.goalId    = $goalId,
+       p.pillarId  = $pillarId,
+       p.name      = $name,
+       p.status    = 'planning',
+       p.phase     = 'planning',
+       p.createdAt = datetime()`,
+    { projId, cid: companyId, goalId, pillarId, name: pillarTitle }
+  ).catch(() => {});
+
+  await mgQuery(
+    `MERGE (d:ProjectDocument {id: $docId})
+     ON CREATE SET
+       d.projectId       = $projId,
+       d.purpose         = '',
+       d.approach        = '',
+       d.successCriteria = '[]',
+       d.intentAnchor    = '',
+       d.exclusions      = '[]',
+       d.version         = toInteger(1),
+       d.updatedAt       = datetime()`,
+    { docId, projId }
+  ).catch(() => {});
+}
+
+module.exports = { ensureProject };