agent-relay-server 0.57.2 → 0.59.0

package/src/db/project-entries.ts

@@ -0,0 +1,270 @@
+import { randomUUID } from "node:crypto";
+import { getDb, ValidationError } from "./connection.ts";
+import { getEntry as getBlackboardEntry, listEntries as listBlackboardEntries } from "./blackboard.ts";
+import { parseJson } from "../utils";
+import { PROJECT_ENTRY_KINDS, PROJECT_ENTRY_SOURCES, type BlackboardEntryKind, type ProjectEntry, type ProjectEntryKind, type ProjectEntrySource, type ProjectEntryStatus } from "../types";
+
+// Project-entry CRUD (#405) — a near-exact copy of src/db/blackboard.ts re-scoped
+// from team_id → project_id, plus the source/origin_ref provenance columns. Kept as
+// a parallel copy (not folded with blackboard) because the two scopes have different
+// lifetimes and column sets; the duplication is intentional and ratchet-noted.
+
+const PROJECT_ENTRY_STATUSES = ["active", "superseded", "retracted"] as const;
+
+interface ProjectEntryRow {
+  id: string;
+  project_id: string;
+  kind: ProjectEntryKind;
+  title: string;
+  body: string | null;
+  status: ProjectEntryStatus;
+  supersedes: string | null;
+  tags: string | null;
+  author_id: string;
+  source: ProjectEntrySource;
+  origin_ref: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+interface WriteProjectEntryInput {
+  projectId: string;
+  kind: ProjectEntryKind;
+  title: string;
+  body?: string;
+  tags?: string[];
+  authorId: string;
+  supersedes?: string;
+  source?: ProjectEntrySource;
+  originRef?: string;
+}
+
+function projectEntryId(): string {
+  return `pe_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+function rowToEntry(row: ProjectEntryRow): ProjectEntry {
+  const tags = parseJson<string[]>(row.tags, []).filter((tag) => typeof tag === "string");
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    kind: row.kind,
+    title: row.title,
+    ...(row.body ? { body: row.body } : {}),
+    status: row.status,
+    ...(row.supersedes ? { supersedes: row.supersedes } : {}),
+    tags,
+    authorId: row.author_id,
+    source: row.source,
+    ...(row.origin_ref ? { originRef: row.origin_ref } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function assertKind(kind: ProjectEntryKind): void {
+  if (!PROJECT_ENTRY_KINDS.includes(kind)) {
+    throw new ValidationError(`kind must be one of: ${PROJECT_ENTRY_KINDS.join(", ")}`);
+  }
+}
+
+function assertSource(source: ProjectEntrySource): void {
+  if (!PROJECT_ENTRY_SOURCES.includes(source)) {
+    throw new ValidationError(`source must be one of: ${PROJECT_ENTRY_SOURCES.join(", ")}`);
+  }
+}
+
+function assertStatus(status: ProjectEntryStatus): void {
+  if (!PROJECT_ENTRY_STATUSES.includes(status)) {
+    throw new ValidationError(`status must be one of: ${PROJECT_ENTRY_STATUSES.join(", ")}`);
+  }
+}
+
+function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+
+export function writeProjectEntry(input: WriteProjectEntryInput): ProjectEntry {
+  assertKind(input.kind);
+  const source = input.source ?? "manual";
+  assertSource(source);
+  const id = projectEntryId();
+  const now = Date.now();
+  getDb().transaction(() => {
+    if (input.supersedes) {
+      const previous = getProjectEntry(input.supersedes);
+      if (!previous) throw new ValidationError(`project entry ${input.supersedes} not found`);
+      if (previous.projectId !== input.projectId) throw new ValidationError("superseded entry belongs to another project");
+      if (previous.status === "retracted") throw new ValidationError("cannot supersede a retracted entry");
+      getDb().query("UPDATE project_entries SET status = 'superseded', updated_at = ? WHERE id = ?")
+        .run(now, input.supersedes);
+    }
+    getDb().query(`
+      INSERT INTO project_entries (id, project_id, kind, title, body, status, supersedes, tags, author_id, source, origin_ref, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id,
+      input.projectId,
+      input.kind,
+      input.title,
+      input.body ?? null,
+      input.supersedes ?? null,
+      input.tags?.length ? JSON.stringify([...new Set(input.tags)]) : null,
+      input.authorId,
+      source,
+      input.originRef ?? null,
+      now,
+      now,
+    );
+  })();
+  return getProjectEntry(id)!;
+}
+
+export function getProjectEntry(id: string): ProjectEntry | null {
+  const row = getDb().query("SELECT * FROM project_entries WHERE id = ?").get(id) as ProjectEntryRow | undefined;
+  return row ? rowToEntry(row) : null;
+}
+
+export function getProjectEntryChain(id: string): ProjectEntry[] {
+  const chain: ProjectEntry[] = [];
+  const seen = new Set<string>();
+  let current = getProjectEntry(id);
+  while (current && !seen.has(current.id)) {
+    chain.push(current);
+    seen.add(current.id);
+    current = current.supersedes ? getProjectEntry(current.supersedes) : null;
+  }
+  return chain;
+}
+
+export function listProjectEntries(
+  projectId: string,
+  opts: { kind?: ProjectEntryKind; includeInactive?: boolean } = {},
+): ProjectEntry[] {
+  if (opts.kind) assertKind(opts.kind);
+  const conditions = ["project_id = ?"];
+  const params: string[] = [projectId];
+  if (opts.kind) {
+    conditions.push("kind = ?");
+    params.push(opts.kind);
+  }
+  if (!opts.includeInactive) conditions.push("status = 'active'");
+  const rows = getDb().query(`
+    SELECT * FROM project_entries
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY updated_at DESC, created_at DESC, id DESC
+  `).all(...params) as ProjectEntryRow[];
+  return rows.map(rowToEntry);
+}
+
+export function searchProjectEntries(
+  projectId: string,
+  query: string,
+  opts: { kind?: ProjectEntryKind } = {},
+): ProjectEntry[] {
+  if (opts.kind) assertKind(opts.kind);
+  const like = `%${escapeLike(query)}%`;
+  const conditions = [
+    "project_id = ?",
+    "status = 'active'",
+    "(title LIKE ? ESCAPE '\\' OR body LIKE ? ESCAPE '\\' OR tags LIKE ? ESCAPE '\\')",
+  ];
+  const params: string[] = [projectId, like, like, like];
+  if (opts.kind) {
+    conditions.push("kind = ?");
+    params.push(opts.kind);
+  }
+  const rows = getDb().query(`
+    SELECT * FROM project_entries
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY updated_at DESC, created_at DESC, id DESC
+  `).all(...params) as ProjectEntryRow[];
+  return rows.map(rowToEntry);
+}
+
+export function retractProjectEntry(id: string): ProjectEntry | null {
+  const existing = getProjectEntry(id);
+  if (!existing) return null;
+  assertStatus("retracted");
+  getDb().query("UPDATE project_entries SET status = 'retracted', updated_at = ? WHERE id = ?")
+    .run(Date.now(), id);
+  return getProjectEntry(id);
+}
+
+// --- blackboard → project promotion (#404): the lossy→durable lift ---------------
+// The ONLY bridge between the ephemeral team blackboard and the durable project ledger.
+// Promotion is ALWAYS explicit — nothing here is wired into blackboard writes or team
+// dissolve; an agent/operator decides what graduates. Blackboard kinds map to project
+// kinds 1:1 except `ruled_out`, which becomes a durable `rule` (a "don't do X" lands as
+// a standing rule). `memory` has no blackboard source — it is project-native only.
+const BLACKBOARD_TO_PROJECT_KIND: Record<BlackboardEntryKind, ProjectEntryKind> = {
+  decision: "decision",
+  fact: "fact",
+  ruled_out: "rule",
+};
+
+export interface PromoteBlackboardEntryInput {
+  blackboardEntryId: string;
+  projectId: string;
+}
+
+/** Find the active project entry already promoted from `originRef` into `projectId`,
+ * if any — the anchor for idempotent re-promotion. */
+function activePromotedEntry(projectId: string, originRef: string): ProjectEntry | null {
+  const row = getDb().query(`
+    SELECT * FROM project_entries
+    WHERE project_id = ? AND origin_ref = ? AND source = 'promoted' AND status = 'active'
+    ORDER BY created_at DESC, id DESC
+    LIMIT 1
+  `).get(projectId, originRef) as ProjectEntryRow | undefined;
+  return row ? rowToEntry(row) : null;
+}
+
+/** Copy an active blackboard finding into the durable project ledger as a `promoted`
+ * entry whose `origin_ref` back-references the `bb_…` id. Preserves title/body/tags/author.
+ * Validates the source is `active` (superseded/retracted findings cannot be promoted).
+ *
+ * Double-promote is IDEMPOTENT-BY-SUPERSEDE: re-promoting the same `bb_…` into the same
+ * project supersedes the prior promoted copy rather than duplicating it, so the durable
+ * ledger holds at most one active entry per promoted finding while keeping the full
+ * supersede chain for audit. */
+export function promoteBlackboardEntry(input: PromoteBlackboardEntryInput): ProjectEntry {
+  const source = getBlackboardEntry(input.blackboardEntryId);
+  if (!source) throw new ValidationError(`blackboard entry ${input.blackboardEntryId} not found`);
+  if (source.status !== "active") {
+    throw new ValidationError(`blackboard entry ${source.id} is ${source.status}; only active entries can be promoted`);
+  }
+  const existing = activePromotedEntry(input.projectId, source.id);
+  return writeProjectEntry({
+    projectId: input.projectId,
+    kind: BLACKBOARD_TO_PROJECT_KIND[source.kind],
+    title: source.title,
+    ...(source.body ? { body: source.body } : {}),
+    ...(source.tags.length ? { tags: source.tags } : {}),
+    authorId: source.authorId,
+    source: "promoted",
+    originRef: source.id,
+    ...(existing ? { supersedes: existing.id } : {}),
+  });
+}
+
+export interface UnpromotedBlackboardSummary {
+  count: number;
+  entries: Array<{ id: string; kind: BlackboardEntryKind; title: string }>;
+}
+
+/** Active blackboard findings for a team that have NOT been promoted into any project
+ * (no active `promoted` project entry back-references them). Surfaced at team dissolve so
+ * the operator/agent can choose to lift them rather than silently losing them. */
+export function unpromotedBlackboardEntries(teamId: string): UnpromotedBlackboardSummary {
+  const active = listBlackboardEntries(teamId);
+  const promotedRefs = new Set(
+    (getDb().query(
+      "SELECT DISTINCT origin_ref FROM project_entries WHERE source = 'promoted' AND status = 'active' AND origin_ref IS NOT NULL",
+    ).all() as Array<{ origin_ref: string }>).map((row) => row.origin_ref),
+  );
+  const entries = active
+    .filter((entry) => !promotedRefs.has(entry.id))
+    .map((entry) => ({ id: entry.id, kind: entry.kind, title: entry.title }));
+  return { count: entries.length, entries };
+}

package/src/db/projects.ts

@@ -0,0 +1,304 @@
+import { randomUUID } from "node:crypto";
+import { getDb, ValidationError } from "./connection.ts";
+import { listProjectEntries } from "./project-entries.ts";
+import { isPathWithinBase } from "../utils";
+import { PROJECT_EDGE_KINDS, type Project, type ProjectEdge, type ProjectEdgeKind, type ProjectEntryKind, type ProjectRoot, type ResolvedProjectEntry } from "../types";
+
+// Projects entity CRUD + roots + cwd→project resolution (#405). Templated on
+// src/db/teams.ts; the durable analog of a team. project_entries CRUD lives in
+// the sibling src/db/project-entries.ts (templated on blackboard.ts).
+
+interface ProjectRow {
+  id: string;
+  slug: string;
+  title: string | null;
+  description: string | null;
+  tenant_id: string | null;
+  status: Project["status"];
+  created_at: number;
+  updated_at: number;
+}
+
+interface ProjectRootRow {
+  project_id: string;
+  root_path: string;
+  created_at: number;
+}
+
+export function projectId(): string {
+  return `project_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+function rowToProject(row: ProjectRow): Project {
+  return {
+    id: row.id,
+    slug: row.slug,
+    ...(row.title ? { title: row.title } : {}),
+    ...(row.description ? { description: row.description } : {}),
+    ...(row.tenant_id ? { tenantId: row.tenant_id } : {}),
+    status: row.status,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function rowToRoot(row: ProjectRootRow): ProjectRoot {
+  return { projectId: row.project_id, rootPath: row.root_path, createdAt: row.created_at };
+}
+
+export function getProject(id: string): Project | null {
+  const row = getDb().query("SELECT * FROM projects WHERE id = ?").get(id) as ProjectRow | undefined;
+  return row ? rowToProject(row) : null;
+}
+
+export function getProjectBySlug(slug: string): Project | null {
+  const row = getDb().query("SELECT * FROM projects WHERE slug = ?").get(slug) as ProjectRow | undefined;
+  return row ? rowToProject(row) : null;
+}
+
+/** Resolve a project by id first, then by slug — the form MCP/route callers pass. */
+export function resolveProject(ref: string): Project | null {
+  return getProject(ref) ?? getProjectBySlug(ref);
+}
+
+export function listProjects(opts: { includeArchived?: boolean } = {}): Project[] {
+  const where = opts.includeArchived ? "" : "WHERE status = 'active' ";
+  const rows = getDb()
+    .query(`SELECT * FROM projects ${where}ORDER BY created_at ASC, id ASC`)
+    .all() as ProjectRow[];
+  return rows.map(rowToProject);
+}
+
+export function rootsForProject(id: string): ProjectRoot[] {
+  const rows = getDb()
+    .query("SELECT * FROM project_roots WHERE project_id = ? ORDER BY root_path ASC")
+    .all(id) as ProjectRootRow[];
+  return rows.map(rowToRoot);
+}
+
+export interface EnsureProjectInput {
+  slug: string;
+  title?: string;
+  description?: string;
+  tenantId?: string;
+}
+
+/** Get-or-create a project by slug. The create-on-first-use analog of ensureTeam;
+ * updates title/description/tenant on an existing project only when provided. */
+export function ensureProject(input: EnsureProjectInput): Project {
+  const slug = input.slug.trim();
+  if (!slug) throw new ValidationError("slug required");
+  const existing = getProjectBySlug(slug);
+  const now = Date.now();
+  if (existing) {
+    if (input.title !== undefined || input.description !== undefined || input.tenantId !== undefined) {
+      getDb().query(`
+        UPDATE projects
+        SET title = ?, description = ?, tenant_id = ?, updated_at = ?
+        WHERE id = ?
+      `).run(
+        input.title ?? existing.title ?? null,
+        input.description ?? existing.description ?? null,
+        input.tenantId ?? existing.tenantId ?? null,
+        now,
+        existing.id,
+      );
+      return getProject(existing.id)!;
+    }
+    return existing;
+  }
+  const id = projectId();
+  getDb().query(`
+    INSERT INTO projects (id, slug, title, description, tenant_id, status, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, 'active', ?, ?)
+  `).run(id, slug, input.title ?? null, input.description ?? null, input.tenantId ?? null, now, now);
+  return getProject(id)!;
+}
+
+/** Register a root path for a project (idempotent — UNIQUE(project_id, root_path)). */
+export function addProjectRoot(id: string, rootPath: string): ProjectRoot[] {
+  const project = getProject(id);
+  if (!project) throw new ValidationError(`project ${id} not found`);
+  const path = rootPath.trim();
+  if (!path) throw new ValidationError("rootPath required");
+  getDb().query(`
+    INSERT INTO project_roots (project_id, root_path, created_at)
+    VALUES (?, ?, ?)
+    ON CONFLICT(project_id, root_path) DO NOTHING
+  `).run(id, path, Date.now());
+  return rootsForProject(id);
+}
+
+/** cwd→project binding: the project whose any root_path contains `cwd`. Uses the
+ * shared containment helper (resolve+relative, never startsWith). When more than one
+ * root matches, the most specific (longest root_path) wins. Returns null gracefully
+ * when no root contains the cwd. */
+export function resolveProjectForCwd(cwd: string): Project | null {
+  if (!cwd) return null;
+  const rows = getDb()
+    .query("SELECT project_id, root_path, created_at FROM project_roots")
+    .all() as ProjectRootRow[];
+  let best: { projectId: string; len: number } | null = null;
+  for (const row of rows) {
+    if (isPathWithinBase(cwd, row.root_path) && (!best || row.root_path.length > best.len)) {
+      best = { projectId: row.project_id, len: row.root_path.length };
+    }
+  }
+  return best ? getProject(best.projectId) : null;
+}
+
+// ── Composition graph (#406) ────────────────────────────────────────────────
+// project_edges models two relations, asymmetric by design:
+//   • contains    — umbrella → sub-project hierarchy. INHERITS: resolving a
+//                   project's entries pulls in its transitive contains-ANCESTORS.
+//   • depends_on  — reference-only. A project's deps are exposed for explicit
+//                   lookup but NEVER auto-inherited (a dependency's internal
+//                   rules must not flood every consuming agent).
+// Cycles are rejected per-kind on insert (addEdge); the traversal helpers also
+// carry a visited-set so a manually-corrupted graph can't loop them.
+
+interface ProjectEdgeRow {
+  from_project: string;
+  to_project: string;
+  kind: ProjectEdgeKind;
+  created_at: number;
+}
+
+function rowToEdge(row: ProjectEdgeRow): ProjectEdge {
+  return { fromProject: row.from_project, toProject: row.to_project, kind: row.kind, createdAt: row.created_at };
+}
+
+function assertEdgeKind(kind: ProjectEdgeKind): void {
+  if (!PROJECT_EDGE_KINDS.includes(kind)) {
+    throw new ValidationError(`kind must be one of: ${PROJECT_EDGE_KINDS.join(", ")}`);
+  }
+}
+
+/** Can `start` reach `target` following same-kind edges in the from→to direction?
+ * Used by addEdge to reject an edge that would close a cycle. Visited-set bounded. */
+function reachableSameKind(start: string, target: string, kind: ProjectEdgeKind): boolean {
+  const stack = [start];
+  const seen = new Set<string>();
+  while (stack.length) {
+    const node = stack.pop()!;
+    if (node === target) return true;
+    if (seen.has(node)) continue;
+    seen.add(node);
+    const rows = getDb()
+      .query("SELECT to_project FROM project_edges WHERE from_project = ? AND kind = ?")
+      .all(node, kind) as Array<{ to_project: string }>;
+    for (const row of rows) stack.push(row.to_project);
+  }
+  return false;
+}
+
+/** Add a graph edge `from`→`to` of `kind`. Both projects must exist. Rejects a
+ * self-loop and any edge that would create a cycle within the same kind (so the
+ * contains hierarchy stays a DAG). Idempotent — UNIQUE(from, to, kind). */
+export function addEdge(fromProject: string, toProject: string, kind: ProjectEdgeKind): ProjectEdge {
+  assertEdgeKind(kind);
+  if (fromProject === toProject) throw new ValidationError("an edge cannot point a project at itself");
+  if (!getProject(fromProject)) throw new ValidationError(`project ${fromProject} not found`);
+  if (!getProject(toProject)) throw new ValidationError(`project ${toProject} not found`);
+  // A cycle forms iff `to` can already reach `from` along same-kind edges; adding
+  // from→to would then close the loop.
+  if (reachableSameKind(toProject, fromProject, kind)) {
+    throw new ValidationError(`edge ${fromProject} -> ${toProject} (${kind}) would create a cycle`);
+  }
+  getDb().query(`
+    INSERT INTO project_edges (from_project, to_project, kind, created_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(from_project, to_project, kind) DO NOTHING
+  `).run(fromProject, toProject, kind, Date.now());
+  return { fromProject, toProject, kind, createdAt: Date.now() };
+}
+
+/** Remove a graph edge. Returns true when a row was deleted, false when absent. */
+export function removeEdge(fromProject: string, toProject: string, kind: ProjectEdgeKind): boolean {
+  assertEdgeKind(kind);
+  const result = getDb()
+    .query("DELETE FROM project_edges WHERE from_project = ? AND to_project = ? AND kind = ?")
+    .run(fromProject, toProject, kind);
+  return result.changes > 0;
+}
+
+/** All edges incident to a project — both outgoing (project is `from`) and
+ * incoming (project is `to`), across both kinds. The visibility surface that lets
+ * a caller see its umbrella(s) and its dependencies. */
+export function edgesFor(projectId: string): ProjectEdge[] {
+  const rows = getDb()
+    .query("SELECT * FROM project_edges WHERE from_project = ? OR to_project = ? ORDER BY kind ASC, created_at ASC")
+    .all(projectId, projectId) as ProjectEdgeRow[];
+  return rows.map(rowToEdge);
+}
+
+/** Transitive `contains` ancestors of a project (the umbrellas that contain it,
+ * directly or via intermediate umbrellas), nearest-first (BFS). Self is excluded. */
+export function ancestors(projectId: string): string[] {
+  const order: string[] = [];
+  const seen = new Set<string>([projectId]);
+  let frontier = [projectId];
+  while (frontier.length) {
+    const next: string[] = [];
+    for (const node of frontier) {
+      const rows = getDb()
+        .query("SELECT from_project FROM project_edges WHERE to_project = ? AND kind = 'contains'")
+        .all(node) as Array<{ from_project: string }>;
+      for (const row of rows) {
+        if (seen.has(row.from_project)) continue;
+        seen.add(row.from_project);
+        order.push(row.from_project);
+        next.push(row.from_project);
+      }
+    }
+    frontier = next;
+  }
+  return order;
+}
+
+/** Direct `depends_on` targets of a project. NOT transitive — dependencies are a
+ * reference edge, surfaced for explicit opt-in lookup, never an inheritance chain. */
+export function dependencies(projectId: string): string[] {
+  const rows = getDb()
+    .query("SELECT to_project FROM project_edges WHERE from_project = ? AND kind = 'depends_on' ORDER BY created_at ASC")
+    .all(projectId) as Array<{ to_project: string }>;
+  return rows.map((row) => row.to_project);
+}
+
+export interface ResolveProjectEntriesOptions {
+  kind?: ProjectEntryKind;
+  includeInactive?: boolean;
+  /** When true (default), merge in entries from transitive `contains` ancestors,
+   * each tagged `inherited: true`. When false, only the project's own entries. */
+  includeInherited?: boolean;
+}
+
+/** Cascade resolution — THE behavioral core of the composition graph.
+ *
+ * Returns a project's own entries PLUS, when `includeInherited` (the default), the
+ * entries of its transitive `contains` ancestors, each tagged with `inherited`.
+ *
+ * MERGE SEMANTICS: own ⊕ ancestors is a UNION, not an override — a project and its
+ * umbrella can both hold a `rule` and both are returned (same-kind = merge). Order
+ * is most-specific-first: the project's own entries lead, then ancestors
+ * nearest-first; if a consumer ever needs precedence, more-specific/nearer (and,
+ * within a project, more-recent) wins by appearing first.
+ *
+ * ASYMMETRY: only `contains` ancestors inherit. `depends_on` targets are NEVER
+ * folded in here — pull a dependency's entries explicitly via its own project ref. */
+export function resolveProjectEntries(
+  projectId: string,
+  opts: ResolveProjectEntriesOptions = {},
+): ResolvedProjectEntry[] {
+  const listOpts = { kind: opts.kind, includeInactive: opts.includeInactive };
+  const resolved: ResolvedProjectEntry[] = listProjectEntries(projectId, listOpts).map(
+    (entry) => ({ ...entry, inherited: false }),
+  );
+  if (opts.includeInherited === false) return resolved;
+  for (const ancestorId of ancestors(projectId)) {
+    for (const entry of listProjectEntries(ancestorId, listOpts)) {
+      resolved.push({ ...entry, inherited: true });
+    }
+  }
+  return resolved;
+}

package/src/db/schema.ts

@@ -187,6 +187,56 @@ export function initDb(path: string = "agent-relay.db"): Database {
     );
     CREATE INDEX IF NOT EXISTS idx_blackboard_team ON blackboard_entries(team_id);
     CREATE INDEX IF NOT EXISTS idx_blackboard_team_kind ON blackboard_entries(team_id, kind);
+    -- Projects (#403/#405) — the durable knowledge scope. projects/project_roots/project_entries
+    -- re-scope the teams/blackboard_entries pair above (team_id → project_id); project_entries
+    -- adds source/origin_ref so a promoted or ingested entry tracks where it came from.
+    CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      slug TEXT NOT NULL UNIQUE,
+      title TEXT,
+      description TEXT,
+      tenant_id TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS project_roots (
+      project_id TEXT NOT NULL,
+      root_path TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      UNIQUE(project_id, root_path)
+    );
+    CREATE INDEX IF NOT EXISTS idx_project_roots_project ON project_roots(project_id);
+    CREATE TABLE IF NOT EXISTS project_entries (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      supersedes TEXT,
+      tags TEXT,
+      author_id TEXT NOT NULL,
+      source TEXT NOT NULL DEFAULT 'manual',
+      origin_ref TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_project_entries_project ON project_entries(project_id);
+    CREATE INDEX IF NOT EXISTS idx_project_entries_project_kind ON project_entries(project_id, kind);
+    -- Project composition graph (#406). kind is 'contains' (umbrella→sub-project, INHERITS)
+    -- or 'depends_on' (reference-only, never inherits). Cycles are rejected on insert in
+    -- src/db/projects.ts (addEdge). Both-direction indexes: from_project for descend/deps,
+    -- to_project for the ancestors() walk.
+    CREATE TABLE IF NOT EXISTS project_edges (
+      from_project TEXT NOT NULL,
+      to_project TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      UNIQUE(from_project, to_project, kind)
+    );
+    CREATE INDEX IF NOT EXISTS idx_project_edges_from ON project_edges(from_project, kind);
+    CREATE INDEX IF NOT EXISTS idx_project_edges_to ON project_edges(to_project, kind);
     CREATE TABLE IF NOT EXISTS plans (
       id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, team_id TEXT, channel TEXT, version INTEGER NOT NULL DEFAULT 1,
       title TEXT, objective TEXT, nodes TEXT NOT NULL DEFAULT '[]', edges TEXT NOT NULL DEFAULT '[]',