@cgh567/agent 2.4.2 → 2.4.3

package/daemon/routes/project.js

@@ -107,35 +107,63 @@ function startSseKeepAlive(res) {
 
 // ── Route factory ─────────────────────────────────────────────────────────────
 
-module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateContextCache, semanticUpdater, driftDetector } = {}) {
+module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateContextCache, semanticUpdater, driftDetector, hboStore } = {}) {
 
   // ── POST /api/project ─────────────────────────────────────────────────────
   async function handleCreate(req, res, ctx) {
     const body = await readBody(req);
     if (!assertBody(body, res, req)) return;
     // D3: ctx.cid is authoritative - prevents cross-company project injection
-    const { pillarId, goalId, name } = body;
+    // P3-02: pillarId and goalId are now optional (defaults to null) so desktop
+    // users without Harada pillars can still create projects.
+    const { name } = body;
+    const pillarId  = body.pillarId  ? String(body.pillarId)  : null;
+    const goalId    = body.goalId    ? String(body.goalId)    : null;
     const companyId = ctx?.cid || body?.companyId || '';
-    if (!companyId || !pillarId || !goalId || !name) {
-      return jsonErr(res, 400, 'companyId, pillarId, goalId, name required', req);
+    if (!companyId || !name) {
+      return jsonErr(res, 400, 'companyId and name are required', req);
     }
     try {
-      const slug   = pillarId.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40);
-      const projId = `proj:${companyId}:${slug}`;
+      // projId is deterministic: use caller-supplied id (H-3: preserves desktop ID for reconciliation),
+      // then pillarId-slug, then UUID slug (P3-02: pillarId optional)
+      const slug   = pillarId
+        ? pillarId.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40)
+        : randomUUID().slice(0, 8);
+      const projId = body.id ? String(body.id) : `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 }
-      );
-      await mgQuery(
-        `MERGE (d:ProjectDocument {id: $docId})
-         ON CREATE SET d.projectId=$projId, d.purpose='', d.approach='',
-           d.successCriteria='[]', d.intentAnchor='', d.exclusions='[]',
-           d.content='', d.version=toInteger(1), d.updatedAt=datetime()`,
-        { docId, projId }
-      );
+      if (mgQuery) {
+        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 }
+        );
+        // H-1 fix: SQLite write-through happens HERE (after first Memgraph write succeeds)
+        // so it executes even if the second Memgraph write (ProjectDocument) fails
+        if (hboStore?.upsertProject) {
+          try {
+            hboStore.upsertProject({ id: projId, companyId, name, pillarId, goalId, status: 'planning', phase: 'planning', createdAt: new Date().toISOString(), updated_at: Date.now() });
+          } catch (storeErr) {
+            process.stderr.write(`[project] hboStore.upsertProject failed (non-fatal): ${storeErr.message}\n`);
+          }
+        }
+        await mgQuery(
+          `MERGE (d:ProjectDocument {id: $docId})
+           ON CREATE SET d.projectId=$projId, d.purpose='', d.approach='',
+             d.successCriteria='[]', d.intentAnchor='', d.exclusions='[]',
+             d.content='', d.version=toInteger(1), d.updatedAt=datetime()`,
+          { docId, projId }
+        );
+      } else {
+        // Memgraph unavailable — write to SQLite only (C-2 / SQL-parity invariant)
+        if (hboStore?.upsertProject) {
+          try {
+            hboStore.upsertProject({ id: projId, companyId, name, pillarId, goalId, status: 'planning', phase: 'planning', createdAt: new Date().toISOString(), updated_at: Date.now() });
+          } catch (storeErr) {
+            process.stderr.write(`[project] hboStore.upsertProject (offline) failed (non-fatal): ${storeErr.message}\n`);
+          }
+        }
+      }
       jsonOk(res, { ok: true, projectId: projId }, req, 201);
     } catch (e) {
       jsonErr(res, 500, safeMsg(e), req);
@@ -148,41 +176,84 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
     const cid    = url.searchParams.get('companyId') || ctx?.cid || '';
     const pillar = url.searchParams.get('pillarId') || '';
     const status = url.searchParams.get('status') || '';
+    // P3-SQL: try Memgraph first; fall back to SQLite when unavailable
+    if (mgQuery) {
+      try {
+        let cypher = `MATCH (p:HeliosProject)`;
+        const params = {};
+        const where = [];
+        if (cid)    { where.push('p.companyId = $cid');    params.cid = cid; }
+        if (pillar) { where.push('p.pillarId  = $pillar'); params.pillar = pillar; }
+        if (status) { where.push('p.status    = $status'); params.status = status; }
+        if (where.length) cypher += ` WHERE ${where.join(' AND ')}`;
+        cypher += ` RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt ORDER BY p.createdAt DESC LIMIT 100`;
+        const result = await mgQuery(cypher, params);
+        const keys = ['id','name','phase','status','pillarId','goalId','createdAt'];
+        const projects = parseRows(result).map(r => rowToObj(r, keys));
+        return jsonOk(res, { projects, count: projects.length }, req);
+      } catch (e) {
+        process.stderr.write(`[project] handleList Memgraph failed, falling back to SQLite: ${e.message}\n`);
+      }
+    }
+    // SQLite fallback
     try {
-      let cypher = `MATCH (p:HeliosProject)`;
-      const params = {};
-      const where = [];
-      if (cid)    { where.push('p.companyId = $cid');    params.cid = cid; }
-      if (pillar) { where.push('p.pillarId  = $pillar'); params.pillar = pillar; }
-      if (status) { where.push('p.status    = $status'); params.status = status; }
-      if (where.length) cypher += ` WHERE ${where.join(' AND ')}`;
-      cypher += ` RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt ORDER BY p.createdAt DESC LIMIT 100`;
-      const result = await mgQuery(cypher, params);
-      const keys = ['id','name','phase','status','pillarId','goalId','createdAt'];
-      const projects = parseRows(result).map(r => rowToObj(r, keys));
-      jsonOk(res, { projects, count: projects.length }, req);
-    } catch (e) {
-      jsonErr(res, 500, safeMsg(e), req);
+      const all = hboStore?.getProjectsByCompany ? hboStore.getProjectsByCompany(cid) : [];
+      let projects = all || [];
+      if (pillar) projects = projects.filter(p => p.pillarId === pillar);
+      if (status) projects = projects.filter(p => p.status === status);
+      return jsonOk(res, { projects, count: projects.length, _source: 'sqlite' }, req);
+    } catch (storeErr) {
+      return jsonErr(res, 503, `Projects unavailable: Memgraph not connected and SQLite fallback failed: ${storeErr.message}`, req);
     }
   }
 
   // ── GET /api/project/:id ──────────────────────────────────────────────────
   async function handleGet(req, res, ctx, projectId) {
+    // P3-SQL: Memgraph-first, SQLite fallback
+    if (mgQuery) {
+      try {
+        const projRes = await mgQuery(
+          `MATCH (p:HeliosProject {id: $id, companyId: $cid})
+           OPTIONAL MATCH (d:ProjectDocument {projectId: p.id})
+           RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt,
+                  d.purpose, d.approach, d.successCriteria, d.intentAnchor, d.exclusions, d.version, d.updatedAt, d.content`,
+          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+        );
+        const row = parseRows(projRes)[0];
+        if (!row) return jsonErr(res, 404, 'Project not found', req);
+        const keys = ['id','name','phase','status','pillarId','goalId','createdAt','purpose','approach','successCriteria','intentAnchor','exclusions','version','updatedAt','content'];
+        return jsonOk(res, rowToObj(row, keys), req);
+      } catch (e) {
+        process.stderr.write(`[project] handleGet Memgraph failed, falling back to SQLite: ${e.message}\n`);
+      }
+    }
+    // SQLite fallback
     try {
-      // D1: Add companyId to prevent cross-company project exfiltration
-      const projRes = await mgQuery(
-        `MATCH (p:HeliosProject {id: $id, companyId: $cid})
-         OPTIONAL MATCH (d:ProjectDocument {projectId: p.id})
-         RETURN p.id, p.name, p.phase, p.status, p.pillarId, p.goalId, p.createdAt,
-                d.purpose, d.approach, d.successCriteria, d.intentAnchor, d.exclusions, d.version, d.updatedAt, d.content`,
-        { id: projectId, cid: ctx.cid || ctx?.cid || '' }
-      );
-      const row = parseRows(projRes)[0];
-      if (!row) return jsonErr(res, 404, 'Project not found', req);
-      const keys = ['id','name','phase','status','pillarId','goalId','createdAt','purpose','approach','successCriteria','intentAnchor','exclusions','version','updatedAt','content'];
-      jsonOk(res, rowToObj(row, keys), req);
-    } catch (e) {
-      jsonErr(res, 500, safeMsg(e), req);
+      const p = hboStore?.getProject ? hboStore.getProject(projectId, ctx?.cid || '') : null;
+      if (!p) return jsonErr(res, 404, 'Project not found', req);
+      // M-2 fix: normalize response shape to match Memgraph path exactly
+      const doc = hboStore?.getProjectDocument ? hboStore.getProjectDocument(projectId) : null;
+      const createdAtMs = typeof p.created_at === 'number' ? p.created_at : (p.createdAt ? new Date(p.createdAt).getTime() : null);
+      return jsonOk(res, {
+        id: p.id,
+        name: p.name ?? null,
+        phase: p.phase ?? 'planning',
+        status: p.status ?? 'planning',
+        pillarId: p.pillarId ?? p.pillar_id ?? null,
+        goalId: p.goalId ?? p.goal_id ?? null,
+        createdAt: createdAtMs ? new Date(createdAtMs).toISOString() : null,
+        purpose: doc?.purpose ?? null,
+        approach: doc?.approach ?? null,
+        successCriteria: doc?.success_criteria ?? doc?.successCriteria ?? '[]',
+        intentAnchor: doc?.intent_anchor ?? doc?.intentAnchor ?? null,
+        exclusions: doc?.exclusions ?? '[]',
+        version: doc?.version ?? 1,
+        updatedAt: doc?.updated_at ? new Date(doc.updated_at).toISOString() : null,
+        content: doc?.content ?? null,
+        _source: 'sqlite',
+      }, req);
+    } catch (storeErr) {
+      return jsonErr(res, 503, `Project unavailable: ${storeErr.message}`, req);
     }
   }
 
@@ -202,6 +273,26 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       const docId     = `pdoc:${projectId}:main`;
       const companyId  = bodyCompanyId || ctx?.cid || projectId.split(':')[1] || 'unknown';
 
+      // C-2 fix: SQLite-only path when Memgraph unavailable
+      if (!mgQuery) {
+        if (hboStore?.upsertProjectDocument) {
+          try {
+            const existing = hboStore.getProjectDocument ? hboStore.getProjectDocument(projectId) : null;
+            const update: Record<string, any> = {
+              id: docId, project_id: projectId, company_id: companyId,
+              ...(existing ? { purpose: existing.purpose, approach: existing.approach, intent_anchor: existing.intent_anchor, success_criteria: existing.success_criteria, exclusions: existing.exclusions, content: existing.content, version: existing.version ?? 1 } : {}),
+              [section === 'intentAnchor' ? 'intent_anchor' : section === 'successCriteria' ? 'success_criteria' : section]: String(value),
+              version: ((existing?.version ?? 0) + 1),
+              updated_at: Date.now(),
+            };
+            hboStore.upsertProjectDocument(update);
+          } catch (storeErr) {
+            process.stderr.write(`[project] hboStore.upsertProjectDocument (offline) failed: ${storeErr.message}\n`);
+          }
+        }
+        return jsonOk(res, { ok: true, section, _source: 'sqlite' }, req, 200);
+      }
+
       // ── content section: persist block tree + back-extract semantic fields ──
       // When the editor saves the full BlockNote block array, we:
       //   1. Store it as d.content (JSON string) — source of truth for the editor
@@ -260,6 +351,12 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
           { docId, content: String(value), purpose, approach, intentAnchor }
         );
         if (invalidateContextCache) invalidateContextCache(projectId);
+        // C-2: SQLite write-through for content section
+        if (hboStore?.upsertProjectDocument) {
+          try {
+            hboStore.upsertProjectDocument({ id: docId, project_id: projectId, company_id: companyId, content: String(value), purpose, approach, intent_anchor: intentAnchor, updated_at: Date.now() });
+          } catch (storeErr) { process.stderr.write(`[project] content write-through failed: ${storeErr.message}\n`); }
+        }
         return jsonOk(res, { ok: true, section: 'content' }, req, 200);
       }
 
@@ -296,6 +393,21 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       // proposalId: internal LLM analysis task ID
       jsonOk(res, { ok: true, pduId, proposalId, message: 'Analyzing edit — check back shortly' }, req, 202);
 
+      // C-2: SQLite write-through for proposal/semantic edit sections
+      if (hboStore?.upsertProjectDocument) {
+        try {
+          const existing = hboStore.getProjectDocument ? hboStore.getProjectDocument(projectId) : null;
+          const colKey = section === 'intentAnchor' ? 'intent_anchor' : section === 'successCriteria' ? 'success_criteria' : section;
+          hboStore.upsertProjectDocument({
+            id: docId, project_id: projectId, company_id: companyId,
+            ...(existing ? { purpose: existing.purpose, approach: existing.approach, intent_anchor: existing.intent_anchor, success_criteria: existing.success_criteria, exclusions: existing.exclusions, content: existing.content, version: existing.version ?? 1 } : {}),
+            [colKey]: String(value),
+            version: ((existing?.version ?? 0) + 1),
+            updated_at: Date.now(),
+          });
+        } catch (storeErr) { process.stderr.write(`[project] proposal write-through failed: ${storeErr.message}\n`); }
+      }
+
       // Trigger semantic analysis asynchronously (non-blocking)
       if (semanticUpdater) {
         setImmediate(async () => {
@@ -480,21 +592,34 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
 
   // ── GET /api/project/:id/state ────────────────────────────────────────────
   async function handleGetState(req, res, ctx, projectId) {
+    // C-1 fix: guard against Memgraph unavailability — return zero-state from SQLite
+    if (!mgQuery) {
+      try {
+        const p = hboStore?.getProject ? hboStore.getProject(projectId, ctx?.cid || '') : null;
+        const currentPhase = p?.phase ?? p?.status ?? 'planning';
+        return jsonOk(res, { totalCells: 0, closedCells: 0, activeTasks: 0, openDriftSignals: 0, currentPhase, hillProgress: 0, _source: 'sqlite' }, req);
+      } catch (storeErr) {
+        return jsonOk(res, { totalCells: 0, closedCells: 0, activeTasks: 0, openDriftSignals: 0, currentPhase: 'planning', hillProgress: 0, _source: 'sqlite' }, req);
+      }
+    }
     try {
       const [cellRes, taskRes, driftRes, docRes] = await Promise.all([
         mgQuery(
+          // P3-05: OPTIONAL MATCH so projects without GoalPillars return hillProgress:0 not an error
+          // H-6 fix: WHERE gp IS NOT NULL prevents null pillarId matching unrelated ActionCells
           `MATCH (p:HeliosProject {id: $id})
-           MATCH (gp:GoalPillar {id: p.pillarId})
-           MATCH (cell:ActionCell {pillarId: gp.id}) RETURN count(cell) AS total,
+           OPTIONAL MATCH (gp:GoalPillar {id: p.pillarId})
+           OPTIONAL MATCH (cell:ActionCell) WHERE cell.pillarId = gp.id AND gp IS NOT NULL
+           RETURN count(cell) AS total,
            count(CASE WHEN cell.status='closed' THEN 1 END) AS closed`,
-          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+          { id: projectId }
         ).catch(() => null),
         mgQuery(
           `MATCH (p:HeliosProject {id: $id})
            MATCH (t:Task {companyId: p.companyId}) WHERE t.task_metadata CONTAINS p.pillarId
              AND t.status IN ['todo','in_progress']
            RETURN count(t) AS active`,
-          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+          { id: projectId }
         ).catch(() => null),
         mgQuery(
           `MATCH (sig:AnomalySignal) WHERE sig.id STARTS WITH $prefix AND sig.status='open'
@@ -503,7 +628,7 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
         ).catch(() => null),
         mgQuery(
           `MATCH (p:HeliosProject {id: $id}) RETURN p.phase`,
-          { id: projectId, cid: ctx.cid || ctx?.cid || '' }
+          { id: projectId }
         ).catch(() => null),
       ]);
 
@@ -512,16 +637,22 @@ module.exports = function createProjectRoute({ mgQuery, broadcast, invalidateCon
       const driftRow = parseRows(driftRes)[0];
       const docRow   = parseRows(docRes)[0];
 
-      const totalCells      = Number(cellRow?.[0] ?? cellRow?.['total']      ?? 0);
-      const closedCells     = Number(cellRow?.[1] ?? cellRow?.['closed']     ?? 0);
-      const activeTasks     = Number(taskRow?.[0] ?? taskRow?.['active']     ?? 0);
-      const openDriftSignals = Number(driftRow?.[0] ?? driftRow?.['open']    ?? 0);
-      const currentPhase    = docRow?.[0] ?? docRow?.['phase']               ?? 'planning';
-      const hillProgress    = totalCells > 0 ? Math.round((closedCells / totalCells) * 100) : 0;
+      const totalCells       = Number(cellRow?.[0] ?? cellRow?.['total']       ?? 0);
+      const closedCells      = Number(cellRow?.[1] ?? cellRow?.['closed']      ?? 0);
+      const activeTasks      = Number(taskRow?.[0] ?? taskRow?.['active']      ?? 0);
+      const openDriftSignals = Number(driftRow?.[0] ?? driftRow?.['open']      ?? 0);
+      const currentPhase     = docRow?.[0]  ?? docRow?.['phase']               ?? 'planning';
+      const hillProgress     = totalCells > 0 ? Math.round((closedCells / totalCells) * 100) : 0;
 
       jsonOk(res, { totalCells, closedCells, activeTasks, openDriftSignals, currentPhase, hillProgress }, req);
     } catch (e) {
-      jsonErr(res, 500, safeMsg(e), req);
+      // Memgraph query failed mid-flight — degrade to SQLite zero-state
+      try {
+        const p = hboStore?.getProject ? hboStore.getProject(projectId, ctx?.cid || '') : null;
+        jsonOk(res, { totalCells: 0, closedCells: 0, activeTasks: 0, openDriftSignals: 0, currentPhase: p?.phase ?? 'planning', hillProgress: 0, _source: 'sqlite' }, req);
+      } catch (_) {
+        jsonErr(res, 500, safeMsg(e), req);
+      }
     }
   }
 

package/daemon/routes/routines.js

@@ -14,6 +14,8 @@
 
 module.exports = function createRoutinesRouter(handlers) {
   const {
+    handleGetRoutines,
+    handleCreateRoutine,
     handleGetRoutineTriggers,
     handleCreateRoutineTrigger,
     handleFireWebhookTrigger,
@@ -30,6 +32,18 @@ module.exports = function createRoutinesRouter(handlers) {
       return true;
     }
 
+    // P5-01: GET /api/routines — list routines for a company (must be before /:id routes)
+    if (method === 'GET' && pathname === '/api/routines') {
+      await handleGetRoutines(req, res, ctx);
+      return true;
+    }
+
+    // P5-02: POST /api/routines — create a new routine
+    if (method === 'POST' && pathname === '/api/routines') {
+      await handleCreateRoutine(req, res, ctx);
+      return true;
+    }
+
     // PATCH /api/routines/:id (edit routine → creates revision)
     const patchRoutineMatch = pathname.match(/^\/api\/routines\/([^/]+)$/);
     if (method === 'PATCH' && patchRoutineMatch) {

package/daemon/routes/tasks.js

@@ -1,6 +1,7 @@
 'use strict';
 
-const VALID_TASK_STATUSES = new Set(['todo', 'in_progress', 'done', 'failed', 'cancelled']);
+// NOTE: Task status validation is handled in handleUpdateTask (helios-api.js VALID_STATUSES).
+// The canonical valid statuses include: todo, in_progress, done, failed, cancelled, blocked, escalated, in_review.
 
 /**
  * routes/tasks.js — Task-related route dispatch
@@ -26,6 +27,7 @@ module.exports = function createTasksRouter(handlers) {
     handleGetTaskComments,
     handlePostTaskComment,
     handlePatchTask,
+    handlePatchTaskPolicy,  // P4-07: PATCH /api/tasks/:id/policy
   } = handlers;
 
   return async function tasksRoute(req, res, ctx, pathname, method) {
@@ -89,6 +91,18 @@ module.exports = function createTasksRouter(handlers) {
       return true;
     }
 
+    // PATCH /api/tasks/:id/policy — P4-07: set executionPolicy on a task
+    const policyMatch = pathname.match(/^\/api\/tasks\/([^/]+)\/policy$/);
+    if (method === 'PATCH' && policyMatch) {
+      if (handlePatchTaskPolicy) {
+        await handlePatchTaskPolicy(req, res, ctx, decodeURIComponent(policyMatch[1]));
+      } else {
+        res.writeHead(501, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Policy endpoint not configured' }));
+      }
+      return true;
+    }
+
     return false;
   };
 };

package/daemon/schema-apply.js

@@ -0,0 +1,174 @@
+'use strict';
+/**
+ * schema-apply.js — Converges the Memgraph graph to the canonical schema.
+ *
+ * Uses Memgraph MAGE's schema.assert() procedure to atomically create missing
+ * indexes and uniqueness constraints, keep existing correct ones, and optionally
+ * drop anything that doesn't belong (controlled by dropExisting flag).
+ *
+ * Composite indexes (multi-property) are applied via separate Cypher statements
+ * because schema.assert() only handles single-property label indexes.
+ *
+ * Called once during daemon startup, after Memgraph connection is established
+ * and before any tick processing begins.
+ *
+ * Usage:
+ *   const { applySchema } = require('./schema-apply');
+ *   await applySchema(mgQuery);          // safe for rolling deployments
+ *   await applySchema(mgQuery, true);    // drop_existing — use on fresh installs
+ */
+
+const { INDEXES, COMPOSITE_INDEXES, UNIQUE_CONSTRAINTS } = require('./schema-definitions');
+
+/**
+ * @param {Function} mgQuery  async (cypher, params?) => { rows, keys }
+ * @param {boolean}  [dropExisting=false]
+ *   false = safe for live deployments — adds missing, keeps existing, never drops.
+ *   true  = converge exactly — drops indexes/constraints not in the definition.
+ *           Use on fresh installs or after intentional schema cleanup.
+ */
+async function applySchema(mgQuery, dropExisting = false) {
+  const log = (msg) => console.log('[schema-apply]', msg);
+  const warn = (msg) => console.warn('[schema-apply] WARN:', msg);
+
+  // ── Step 1: schema.assert() for single-property indexes + unique constraints
+  log(`Applying schema via schema.assert() (drop_existing=${dropExisting})…`);
+
+  let assertResult;
+  try {
+    assertResult = await mgQuery(
+      `CALL schema.assert($indices, $unique, {}, $drop)
+       YIELD action, label, key, unique
+       RETURN action, label, key, unique`,
+      {
+        indices: INDEXES,
+        unique:  UNIQUE_CONSTRAINTS,
+        drop:    dropExisting,
+      }
+    );
+  } catch (err) {
+    // schema.assert() is a MAGE procedure — if MAGE is not installed or the
+    // version doesn't include the schema module, fall back gracefully to the
+    // per-statement legacy approach.
+    warn(`schema.assert() unavailable: ${err.message}`);
+    warn('Falling back to per-statement legacy migration.');
+    return _legacyFallback(mgQuery);
+  }
+
+  // ── Parse and log results ────────────────────────────────────────────────
+  const rows = assertResult?.rows ?? [];
+  const counts = { Created: 0, Kept: 0, Dropped: 0 };
+
+  for (const row of rows) {
+    // Memgraph returns rows as arrays or objects depending on driver config
+    const action = Array.isArray(row) ? row[0] : row.action;
+    const label  = Array.isArray(row) ? row[1] : row.label;
+    const key    = Array.isArray(row) ? row[2] : row.key;
+    const unique = Array.isArray(row) ? row[3] : row.unique;
+
+    const kind = unique ? 'constraint' : 'index';
+    if (action === 'Created') {
+      log(`  ✓ Created ${kind}: :${label}(${key})`);
+    } else if (action === 'Dropped') {
+      log(`  ✗ Dropped ${kind}: :${label}(${key})`);
+    }
+    // Kept entries are silent — too noisy otherwise
+    if (counts[action] !== undefined) counts[action]++;
+  }
+
+  log(`schema.assert() complete — Created: ${counts.Created}, Kept: ${counts.Kept}, Dropped: ${counts.Dropped}`);
+
+  // ── Step 2: Composite indexes ─────────────────────────────────────────────
+  // schema.assert() does not support composite indexes, so we create them
+  // individually. Each uses CREATE INDEX ON :Label(propA, propB) with a
+  // try/catch to silently skip "already exists" errors.
+  let compositeCreated = 0;
+  let compositeSkipped = 0;
+
+  for (const { label, props } of COMPOSITE_INDEXES) {
+    const propList = props.join(', ');
+    const cypher = `CREATE INDEX ON :${label}(${propList})`;
+    try {
+      await mgQuery(cypher);
+      log(`  ✓ Created composite index: :${label}(${propList})`);
+      compositeCreated++;
+    } catch (err) {
+      // "already exists" is the expected no-op case
+      const msg = err.message ?? '';
+      if (/already exists/i.test(msg) || /constraint.*exists/i.test(msg) || /index.*exists/i.test(msg)) {
+        compositeSkipped++;
+      } else {
+        warn(`Composite index :${label}(${propList}) failed: ${msg}`);
+      }
+    }
+  }
+
+  if (compositeCreated > 0 || compositeSkipped > 0) {
+    log(`Composite indexes — Created: ${compositeCreated}, Already existed: ${compositeSkipped}`);
+  }
+
+  log('Schema application complete.');
+}
+
+// ── Legacy fallback ───────────────────────────────────────────────────────────
+// Used when schema.assert() is unavailable (MAGE not installed or older version).
+// Runs each constraint/index as individual CREATE statements with try/catch.
+// This is the old seven-migration-file behaviour, condensed into one function.
+
+async function _legacyFallback(mgQuery) {
+  const log  = (msg) => console.log('[schema-apply/legacy]', msg);
+  const warn = (msg) => console.warn('[schema-apply/legacy] WARN:', msg);
+
+  log('Running legacy per-statement schema migration…');
+
+  let created = 0;
+  let skipped = 0;
+  let failed  = 0;
+
+  async function exec(cypher) {
+    try {
+      await mgQuery(cypher);
+      created++;
+    } catch (err) {
+      const msg = err.message ?? '';
+      if (/already exists/i.test(msg) || /constraint.*exists/i.test(msg) || /index.*exists/i.test(msg)) {
+        skipped++;
+      } else {
+        warn(`${cypher} → ${msg}`);
+        failed++;
+      }
+    }
+  }
+
+  // Unique constraints
+  for (const [label, constraintGroups] of Object.entries(UNIQUE_CONSTRAINTS)) {
+    for (const props of constraintGroups) {
+      if (props.length === 1) {
+        await exec(`CREATE CONSTRAINT ON (n:${label}) ASSERT n.${props[0]} IS UNIQUE`);
+      } else {
+        // Composite unique — old syntax doesn't support this cleanly; use new syntax
+        await exec(`CREATE CONSTRAINT FOR (n:${label}) REQUIRE (${props.map(p => `n.${p}`).join(', ')}) IS UNIQUE`);
+      }
+    }
+  }
+
+  // Single-property indexes
+  for (const [label, props] of Object.entries(INDEXES)) {
+    for (const prop of props) {
+      if (prop === '') {
+        await exec(`CREATE INDEX ON :${label}`);
+      } else {
+        await exec(`CREATE INDEX ON :${label}(${prop})`);
+      }
+    }
+  }
+
+  // Composite indexes
+  for (const { label, props } of COMPOSITE_INDEXES) {
+    await exec(`CREATE INDEX ON :${label}(${props.join(', ')})`);
+  }
+
+  log(`Legacy migration complete — Created: ${created}, Skipped: ${skipped}, Failed: ${failed}`);
+}
+
+module.exports = { applySchema };