@promptowl/contextnest-community 1.8.0 → 1.9.0

package/CONFIGURATION.md

@@ -66,7 +66,16 @@ The server prints a loud warning at startup when `AUTH_MODE=open` is active.
 | `CORS_ORIGINS` | `*` in open mode; `http://localhost:5173,http://localhost:3838` in key mode | Comma-separated allowlist. Set to `*` to allow any origin (**only** safe in open mode — in key mode with Bearer tokens this enables CSRF). |
 | `MAX_BODY_BYTES` | `10485760` (10 MB) | Reject requests whose `Content-Length` exceeds this. Prevents giant-payload DoS. |
 | `LOGO_URL` | _(unset)_ | Custom logo shown in the UI header + login screen. Must start with `https://`, `http://`, or `data:image/` — other schemes (`file://`, relative, `javascript:`) are rejected with a warning and the bundled icon is used. |
+| `FEATURE_WORKFLOW_PLANE` | _(unset — off)_ | Enables the workflow plane: typed edges, edge-type registry, governed runs. Optional feature; also toggleable from Settings. |
+| `FEATURE_SUBAGENT_RUNS` | _(unset — off)_ | Lets runs spawn nested sub-agent runs (recursion). Gated separately from the plane; requires `FEATURE_WORKFLOW_PLANE`. Also toggleable from Settings → Advanced (turning the plane off forces this off too). Opens a recursion surface — enable only after reviewing the depth/fan-out caps. |
+| `SUBAGENT_MAX_DEPTH` | `8` | Max sub-agent nesting depth (clamped 1..32) — bounds the call tree's HEIGHT so it stays finite/haltable. |
+| `SUBAGENT_MAX_CHILDREN` | `16` | Max direct children a single run may spawn (clamped 1..128) — bounds the call tree's WIDTH. Together with `SUBAGENT_MAX_DEPTH` this caps total tree size so a runner can't fork-bomb the DB. |
+| `RUN_MAX_STEPS` | `10000` | Max steps a single run may accumulate (clamped 10..100000) — bounds a runaway/hostile runner's step log. |
 | `SLACK_WEBHOOK_URL` | _(unset — connector off)_ | Slack incoming-webhook URL for governance-event notifications (review submitted/approved/rejected, collaborator added). `https://` only — the URL embeds a secret. Also editable from Settings in the UI. |
+| `SMTP_URL` | _(unset — connector off)_ | SMTP connection URL for email notifications (`smtp://` or `smtps://`, credentials inline). Requires `NOTIFY_EMAIL_FROM` and `NOTIFY_EMAIL_TO`. Also editable from Settings. |
+| `NOTIFY_EMAIL_FROM` | _(unset)_ | From address for notification emails. |
+| `NOTIFY_EMAIL_TO` | _(unset)_ | Comma-separated recipients for notification emails. |
+| `NOTIFY_DEBOUNCE_MS` | `15000` | Per-nest buffer window before notifications flush; bursts collapse into one digest message. |
 
 ---
 

package/dist/chunk-3JTODC3Y.js

@@ -0,0 +1,48 @@
+// src/shared/errors.ts
+var AppError = class extends Error {
+  constructor(statusCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "AppError";
+  }
+  statusCode;
+};
+var NotFoundError = class extends AppError {
+  constructor(message = "Not found") {
+    super(404, message);
+    this.name = "NotFoundError";
+  }
+};
+var ForbiddenError = class extends AppError {
+  constructor(message = "Forbidden") {
+    super(403, message);
+    this.name = "ForbiddenError";
+  }
+};
+var ValidationError = class extends AppError {
+  constructor(message) {
+    super(400, message);
+    this.name = "ValidationError";
+  }
+};
+var ConflictError = class extends AppError {
+  constructor(message) {
+    super(409, message);
+    this.name = "ConflictError";
+  }
+};
+var LockedError = class extends AppError {
+  constructor(message = "Locked") {
+    super(423, message);
+    this.name = "LockedError";
+  }
+};
+
+export {
+  AppError,
+  NotFoundError,
+  ForbiddenError,
+  ValidationError,
+  ConflictError,
+  LockedError
+};

package/dist/{chunk-PJTAUVD7.js → chunk-BYS4HDME.js}

@@ -1,9 +1,15 @@
 import {
-  config,
-  getDb,
+  ConflictError,
+  ValidationError
+} from "./chunk-3JTODC3Y.js";
+import {
   insertOrReplace,
   nowExpr
-} from "./chunk-PLAHCDQG.js";
+} from "./chunk-XQ46F76G.js";
+import {
+  config,
+  getDb
+} from "./chunk-DPHV6Q26.js";
 import {
   ANON_USER_ID
 } from "./chunk-SLTQACJW.js";
@@ -104,46 +110,6 @@ function parseAccessYaml(content) {
   return result;
 }
 
-// src/shared/errors.ts
-var AppError = class extends Error {
-  constructor(statusCode, message) {
-    super(message);
-    this.statusCode = statusCode;
-    this.name = "AppError";
-  }
-  statusCode;
-};
-var NotFoundError = class extends AppError {
-  constructor(message = "Not found") {
-    super(404, message);
-    this.name = "NotFoundError";
-  }
-};
-var ForbiddenError = class extends AppError {
-  constructor(message = "Forbidden") {
-    super(403, message);
-    this.name = "ForbiddenError";
-  }
-};
-var ValidationError = class extends AppError {
-  constructor(message) {
-    super(400, message);
-    this.name = "ValidationError";
-  }
-};
-var ConflictError = class extends AppError {
-  constructor(message) {
-    super(409, message);
-    this.name = "ConflictError";
-  }
-};
-var LockedError = class extends AppError {
-  constructor(message = "Locked") {
-    super(423, message);
-    this.name = "LockedError";
-  }
-};
-
 // src/nodes/engine.ts
 import {
   NestStorage as NestStorage3,
@@ -924,11 +890,35 @@ async function buildTitleMap(nestId) {
 function folderForNode(nodeId) {
   return nodeId.replace(/^nodes\//, "").split("/").slice(0, -1).join("/");
 }
-async function describeNode(nestId, nodeId) {
+async function nestName(nestId) {
+  try {
+    const row = await getDb().get("SELECT name FROM nests WHERE id = ?", [
+      nestId
+    ]);
+    return row?.name || nestId;
+  } catch {
+    return nestId;
+  }
+}
+function docLink(nestId, nodeId, baseUrl) {
+  const base = baseUrl || config.PUBLIC_BASE_URL;
+  if (!base) return "";
+  const q = new URLSearchParams({ nest: nestId });
+  if (nodeId) q.set("doc", nodeId);
+  return `${base.replace(/\/$/, "")}/?${q.toString()}`;
+}
+async function buildDocContext(nestId, nodeId, baseUrl) {
   const titles = await buildTitleMap(nestId);
-  const title = titles.get(nodeId) || nodeId;
+  const docTitle = titles.get(nodeId) || nodeId;
   const folder = folderForNode(nodeId);
-  return folder ? `${title} (in ${folder})` : title;
+  const name = await nestName(nestId);
+  return {
+    docTitle,
+    // Slack one-liner label ("Title (in Folder)"), same as describeNode().
+    label: folder ? `${docTitle} (in ${folder})` : docTitle,
+    path: folder ? `${name} / ${folder}` : name,
+    link: docLink(nestId, nodeId, baseUrl)
+  };
 }
 
 // src/shared/access.ts
@@ -1549,12 +1539,6 @@ function rowToSteward(row) {
 }
 
 export {
-  AppError,
-  NotFoundError,
-  ForbiddenError,
-  ValidationError,
-  ConflictError,
-  LockedError,
   trackEvent,
   startTelemetryLoop,
   getCurrentLicense,
@@ -1589,7 +1573,9 @@ export {
   deleteNest,
   engineCache,
   buildTitleMap,
-  describeNode,
+  nestName,
+  docLink,
+  buildDocContext,
   collabPermToRole,
   assignSteward,
   removeSteward,

package/dist/{chunk-PLAHCDQG.js → chunk-DPHV6Q26.js}

@@ -2,6 +2,11 @@ import {
   ANON_USER_ID
 } from "./chunk-SLTQACJW.js";
 
+// src/db/client.ts
+import Database from "better-sqlite3";
+import { mkdirSync, readFileSync } from "fs";
+import { dirname as dirname2 } from "path";
+
 // src/config.ts
 import { join, dirname } from "path";
 import { existsSync } from "fs";
@@ -21,6 +26,14 @@ if (envFileLoaded && !isTestRun) {
 var canonicalEnvFile = process.env.ENV_FILE_PATH || join(dataRoot(), ".env");
 var canonicalEnvLoaded = null;
 var slackUrlWarned = false;
+var emailFromWarned = false;
+var emailToWarned = false;
+function isEmailish(v) {
+  return /^[^\s@]+@[^\s@]+$/.test(v) && !/[\r\n]/.test(v);
+}
+function isEmailListish(v) {
+  return v.split(",").every((e) => isEmailish(e.trim()));
+}
 if (!isTestRun && canonicalEnvFile !== envFileLoaded && existsSync(canonicalEnvFile)) {
   dotenv.config({ path: canonicalEnvFile, override: true });
   canonicalEnvLoaded = canonicalEnvFile;
@@ -187,9 +200,101 @@ var config = {
     }
     return raw;
   },
+  /**
+   * Workflow plane ("turing" track): typed edges, edge-type registry, runs.
+   * OFF by default — an optional feature an admin turns on (env or Settings).
+   * This flag is also the future license-tier hook: gating a paid tier here
+   * is a one-line change because every plane route checks it per request.
+   */
+  get FEATURE_WORKFLOW_PLANE() {
+    return process.env.FEATURE_WORKFLOW_PLANE === "true";
+  },
+  /**
+   * Sub-agent runs: lets a run spawn nested runs (an external runner calling
+   * back into POST /run for a child agent). Gated SEPARATELY from the base
+   * plane because recursion is the risky surface — unbounded fan-out,
+   * re-entrancy, resource exhaustion. Off by default; must clear a security
+   * review before an operator turns it on. Requires FEATURE_WORKFLOW_PLANE too.
+   */
+  get FEATURE_SUBAGENT_RUNS() {
+    return process.env.FEATURE_SUBAGENT_RUNS === "true";
+  },
+  /** Hard ceiling on sub-agent nesting depth — keeps the call tree finite
+   *  (haltable / statically bounded). Clamped to [1, 32]. */
+  get SUBAGENT_MAX_DEPTH() {
+    const n = parseInt(process.env.SUBAGENT_MAX_DEPTH || "8", 10);
+    return Number.isFinite(n) ? Math.min(32, Math.max(1, n)) : 8;
+  },
+  /** Max direct children a single run may spawn. Depth bounds the tree's
+   *  height; this bounds its width — together they cap total size so a
+   *  runner can't fork-bomb the DB. Clamped to [1, 128]. */
+  get SUBAGENT_MAX_CHILDREN() {
+    const n = parseInt(process.env.SUBAGENT_MAX_CHILDREN || "16", 10);
+    return Number.isFinite(n) ? Math.min(128, Math.max(1, n)) : 16;
+  },
+  /** Max steps a single run may accumulate — bounds a runaway/hostile
+   *  runner's step log. Clamped to [10, 100000]. */
+  get RUN_MAX_STEPS() {
+    const n = parseInt(process.env.RUN_MAX_STEPS || "10000", 10);
+    return Number.isFinite(n) ? Math.min(1e5, Math.max(10, n)) : 1e4;
+  },
   get AUTH_MODE() {
     return process.env.AUTH_MODE || "key";
   },
+  /**
+   * Optional SMTP connection URL for email notifications, e.g.
+   * smtps://user:pass@smtp.example.com:465. smtp:// or smtps:// only.
+   * Empty/unset = email connector off. Requires NOTIFY_EMAIL_FROM/_TO.
+   */
+  get SMTP_URL() {
+    const raw = process.env.SMTP_URL?.trim();
+    if (!raw) return null;
+    if (!/^smtps?:\/\//i.test(raw)) {
+      console.warn(
+        "[config] SMTP_URL rejected: must be an smtp:// or smtps:// URL. Email notifications disabled."
+      );
+      return null;
+    }
+    return raw;
+  },
+  /**
+   * From address for notification emails. Shape-validated here (not only in
+   * the /admin/settings PATCH) so a value set directly via env/Docker can't
+   * reach nodemailer's envelope unchecked. Invalid = connector off.
+   */
+  get NOTIFY_EMAIL_FROM() {
+    const raw = process.env.NOTIFY_EMAIL_FROM?.trim();
+    if (!raw) return null;
+    if (!isEmailish(raw)) {
+      if (!emailFromWarned) {
+        emailFromWarned = true;
+        console.warn(
+          "[config] NOTIFY_EMAIL_FROM rejected: must be a plain email address. Email notifications disabled."
+        );
+      }
+      return null;
+    }
+    return raw;
+  },
+  /**
+   * Comma-separated recipient list for notification emails. Shape-validated
+   * here for the same env-bypass reason as NOTIFY_EMAIL_FROM. Invalid (any
+   * entry malformed) = connector off.
+   */
+  get NOTIFY_EMAIL_TO() {
+    const raw = process.env.NOTIFY_EMAIL_TO?.trim();
+    if (!raw) return null;
+    if (!isEmailListish(raw)) {
+      if (!emailToWarned) {
+        emailToWarned = true;
+        console.warn(
+          "[config] NOTIFY_EMAIL_TO rejected: must be a comma-separated list of email addresses. Email notifications disabled."
+        );
+      }
+      return null;
+    }
+    return raw;
+  },
   /**
    * Optional Slack incoming-webhook URL for team notifications (review
    * submitted/approved/rejected, nest shared). Empty/unset = connector off.
@@ -210,6 +315,18 @@ var config = {
     }
     return raw;
   },
+  /**
+   * Per-nest notification digest window in milliseconds. A burst of governance
+   * events on one nest inside this window collapses into a single digest
+   * message instead of one post per event. Empty / non-numeric / negative /
+   * unset → 15000 (15s).
+   */
+  get NOTIFY_DEBOUNCE_MS() {
+    const raw = process.env.NOTIFY_DEBOUNCE_MS?.trim();
+    if (!raw) return 15e3;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : 15e3;
+  },
   /**
    * CORS origin allowlist. Comma-separated list of origins or "*".
    * Defaults to "*" in open mode (read-heavy, no credentials to steal)
@@ -231,11 +348,6 @@ var config = {
   }
 };
 
-// src/db/client.ts
-import Database from "better-sqlite3";
-import { mkdirSync, readFileSync } from "fs";
-import { dirname as dirname2 } from "path";
-
 // src/db/migrations.ts
 function runMigrations(db) {
   db.exec(`
@@ -802,6 +914,27 @@ function runMigrations(db) {
     })();
     recordMigration("012_merge_case_colliding_users");
   }
+  if (!hasMigration("019_grants")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS grants (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          target_type TEXT NOT NULL CHECK(target_type IN ('document', 'folder')),
+          target TEXT NOT NULL,        -- node id (document) or path prefix (folder)
+          user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+          role TEXT NOT NULL CHECK(role IN ('read', 'write')),
+          granted_by TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_grants_unique
+          ON grants(nest_id, target_type, target, user_id);
+        CREATE INDEX IF NOT EXISTS idx_grants_user ON grants(nest_id, user_id);
+      `);
+    })();
+    recordMigration("019_grants");
+  }
   if (!hasMigration("013_node_deletion_tombstones")) {
     db.transaction(() => {
       db.exec(`
@@ -839,6 +972,112 @@ function runMigrations(db) {
     })();
     recordMigration("014_api_events");
   }
+  if (!hasMigration("015_definitions")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS definitions (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          term TEXT NOT NULL,
+          definition TEXT NOT NULL,
+          linked_tag TEXT,               -- optional #tag this term maps to
+          defined_by TEXT NOT NULL,      -- email
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_definitions_term
+          ON definitions(nest_id, term COLLATE NOCASE);
+      `);
+    })();
+    recordMigration("015_definitions");
+  }
+  if (!hasMigration("016_workflow_edges")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS edge_types (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          name TEXT NOT NULL,
+          description TEXT NOT NULL,
+          direction TEXT NOT NULL DEFAULT 'directed'
+            CHECK(direction IN ('directed', 'undirected')),
+          is_flow INTEGER NOT NULL DEFAULT 0,   -- flow types form the DAG
+          condition_schema TEXT,                -- JSON template | NULL
+          color TEXT,
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_edge_types_name
+          ON edge_types(nest_id, LOWER(name));
+
+        CREATE TABLE IF NOT EXISTS edges (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          from_node TEXT NOT NULL,
+          to_node TEXT NOT NULL,
+          -- RESTRICT (not CASCADE): the app refuses to delete an edge type
+          -- while edges reference it; the DB backs that invariant instead of
+          -- silently cascade-deleting live edges if the app check is bypassed.
+          type_id TEXT NOT NULL REFERENCES edge_types(id) ON DELETE RESTRICT,
+          condition_mode TEXT
+            CHECK(condition_mode IN ('structured', 'nl', 'open')),
+          condition TEXT,
+          metadata TEXT,
+          created_by TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(nest_id, from_node);
+        CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(nest_id, to_node);
+        CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(nest_id, type_id);
+      `);
+    })();
+    recordMigration("016_workflow_edges");
+  }
+  if (!hasMigration("017_workflow_runs")) {
+    db.transaction(() => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS runs (
+          id TEXT PRIMARY KEY,
+          nest_id TEXT NOT NULL REFERENCES nests(id) ON DELETE CASCADE,
+          agent_node TEXT NOT NULL,
+          triggered_by TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'running'
+            CHECK(status IN ('running', 'succeeded', 'failed', 'cancelled')),
+          inputs TEXT,
+          trace TEXT,
+          started_at TEXT NOT NULL,
+          finished_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_runs_nest ON runs(nest_id, started_at);
+        CREATE INDEX IF NOT EXISTS idx_runs_agent ON runs(nest_id, agent_node);
+
+        CREATE TABLE IF NOT EXISTS run_steps (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+          seq INTEGER NOT NULL,
+          node_id TEXT,
+          edge_id TEXT,
+          action TEXT NOT NULL,
+          detail TEXT,
+          at TEXT NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_run_steps ON run_steps(run_id, seq);
+      `);
+    })();
+    recordMigration("017_workflow_runs");
+  }
+  if (!hasMigration("018_subagent_runs")) {
+    db.transaction(() => {
+      db.exec(`
+        ALTER TABLE runs ADD COLUMN parent_run_id TEXT;
+        ALTER TABLE runs ADD COLUMN depth INTEGER NOT NULL DEFAULT 0;
+        CREATE INDEX IF NOT EXISTS idx_runs_parent ON runs(parent_run_id);
+      `);
+    })();
+    recordMigration("018_subagent_runs");
+  }
 }
 function mergeCaseCollidingUsers(db) {
   const groups = db.prepare(
@@ -1056,7 +1295,7 @@ async function initDb() {
   if (config.DB_DRIVER === "postgres") {
     const { Pool } = await import("pg");
     const { PostgresAdapter } = await import("./adapter.postgres-YOODX2BI.js");
-    const { runPostgresMigrations } = await import("./migrations.postgres-VCG45LMK.js");
+    const { runPostgresMigrations } = await import("./migrations.postgres-ORSV7UFJ.js");
     const pool = new Pool(buildPgConfig());
     adapter = new PostgresAdapter(pool);
     await runPostgresMigrations(adapter);
@@ -1076,23 +1315,18 @@ function getDb() {
   }
   return adapter;
 }
-
-// src/db/sql.ts
-function nowExpr(db) {
-  return db.dialect === "sqlite" ? "datetime('now')" : "to_char((now() AT TIME ZONE 'utc'), 'YYYY-MM-DD HH24:MI:SS')";
-}
-function insertOrIgnore(db, insertSql) {
-  return db.dialect === "sqlite" ? insertSql.replace(/^\s*INSERT\s+INTO/i, "INSERT OR IGNORE INTO") : `${insertSql} ON CONFLICT DO NOTHING`;
-}
-function insertOrReplace(db, insertSql, conflictCols, set) {
-  return db.dialect === "sqlite" ? insertSql.replace(/^\s*INSERT\s+INTO/i, "INSERT OR REPLACE INTO") : `${insertSql} ON CONFLICT (${conflictCols.join(", ")}) DO UPDATE SET ${set}`;
+async function resetDb() {
+  if (adapter) {
+    await adapter.close();
+    adapter = null;
+  }
 }
 
 export {
+  isEmailish,
+  isEmailListish,
   config,
   initDb,
   getDb,
-  nowExpr,
-  insertOrIgnore,
-  insertOrReplace
+  resetDb
 };

package/dist/chunk-FRQJWGN3.js

@@ -0,0 +1,8 @@
+// src/shared/email.ts
+function normalizeEmail(email) {
+  return email.trim().toLowerCase();
+}
+
+export {
+  normalizeEmail
+};

package/dist/{chunk-XNGOO6RI.js → chunk-HRQWNRVI.js}

@@ -1,8 +1,10 @@
 import {
-  getDb,
   insertOrReplace,
   nowExpr
-} from "./chunk-PLAHCDQG.js";
+} from "./chunk-XQ46F76G.js";
+import {
+  getDb
+} from "./chunk-DPHV6Q26.js";
 
 // src/governance/version-service.ts
 import { createHash } from "crypto";

package/dist/chunk-TIO5XOFD.js

@@ -0,0 +1,103 @@
+import {
+  ValidationError
+} from "./chunk-3JTODC3Y.js";
+import {
+  getDb
+} from "./chunk-DPHV6Q26.js";
+
+// src/governance/grants-service.ts
+import { v4 as uuid } from "uuid";
+var rank = (r) => r === "write" ? 2 : 1;
+async function resolveNodeGrant(nestId, userId, nodeId) {
+  if (!userId || !nodeId) return null;
+  const rows = await getDb().all(
+    "SELECT target, role FROM grants WHERE nest_id = ? AND user_id = ?",
+    [nestId, userId]
+  );
+  let best = null;
+  for (const r of rows) {
+    if (nodeId === r.target || nodeId.startsWith(r.target + "/")) {
+      if (!best || rank(r.role) > rank(best)) best = r.role;
+    }
+  }
+  return best;
+}
+async function hasAnyGrant(nestId, userId) {
+  if (!userId) return false;
+  const row = await getDb().get(
+    "SELECT 1 AS x FROM grants WHERE nest_id = ? AND user_id = ? LIMIT 1",
+    [nestId, userId]
+  );
+  return !!row;
+}
+async function listUserGrants(nestId, userId) {
+  if (!userId) return [];
+  return await getDb().all(
+    "SELECT target, role FROM grants WHERE nest_id = ? AND user_id = ?",
+    [nestId, userId]
+  );
+}
+function grantCoversNode(grants, nodeId) {
+  return grants.some(
+    (g) => nodeId === g.target || nodeId.startsWith(g.target + "/")
+  );
+}
+async function createGrant(params) {
+  const { nestId, targetType, target, userId, role, grantedBy } = params;
+  if (!["document", "folder"].includes(targetType)) {
+    throw new ValidationError("target_type must be document | folder");
+  }
+  if (!["read", "write"].includes(role)) {
+    throw new ValidationError("role must be read | write");
+  }
+  if (!target.trim()) throw new ValidationError("target is required");
+  if (targetType === "folder") {
+    const t = target.trim().replace(/\/+$/, "");
+    if (t === "nodes" || t === "") {
+      throw new ValidationError("folder target must name a subfolder, not the nest root");
+    }
+  }
+  const db = getDb();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const existing = await db.get(
+    "SELECT id FROM grants WHERE nest_id = ? AND target_type = ? AND target = ? AND user_id = ?",
+    [nestId, targetType, target, userId]
+  );
+  if (existing) {
+    await db.run(
+      "UPDATE grants SET role = ?, granted_by = ?, updated_at = ? WHERE id = ?",
+      [role, grantedBy, now, existing.id]
+    );
+    return await db.get("SELECT * FROM grants WHERE id = ?", [existing.id]);
+  }
+  const id = uuid();
+  await db.run(
+    `INSERT INTO grants (id, nest_id, target_type, target, user_id, role, granted_by, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [id, nestId, targetType, target, userId, role, grantedBy, now, now]
+  );
+  return await db.get("SELECT * FROM grants WHERE id = ?", [id]);
+}
+async function listGrants(nestId) {
+  return await getDb().all(
+    "SELECT * FROM grants WHERE nest_id = ? ORDER BY target_type, target",
+    [nestId]
+  );
+}
+async function deleteGrant(nestId, id) {
+  const db = getDb();
+  const row = await db.get("SELECT id FROM grants WHERE id = ? AND nest_id = ?", [id, nestId]);
+  if (!row) return false;
+  await db.run("DELETE FROM grants WHERE id = ?", [id]);
+  return true;
+}
+
+export {
+  resolveNodeGrant,
+  hasAnyGrant,
+  listUserGrants,
+  grantCoversNode,
+  createGrant,
+  listGrants,
+  deleteGrant
+};