@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/src/modules/workflow/__tests__/session-ontology.service.test.ts

@@ -1,201 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { testKbContext } from '../../../__tests__/kb-context.js';
-
-import { SessionOntologyService } from '../session-ontology.service.js';
-import type { Database } from '../../database/connection.js';
-
-const PRODUCT = 'KnowledgeBase/Product';
-const PLATFORM = 'KnowledgeBase/Platform';
-const P_READ = 'KnowledgeBase/Product/Knowledge/Foo.md';
-const PL_READ = 'KnowledgeBase/Platform/Knowledge/Bar.md';
-
-/**
- * Faithful in-memory fake of the slice of the Drizzle `Database` the service
- * uses against the `session_ontology_touches` table (one row per
- * `(session_id, ontology)`):
- *  - `insert().onConflictDoNothing()` adds a row unless the PK pair exists.
- *  - `select({ontology}).from().where(eq(session))` returns the session's rows.
- *  - `delete().where(eq(session) | lt(touchedAt, cutoff))` removes rows.
- *
- * A live-Postgres integration test (real PK conflict, real `touched_at < now()`
- * sweep) is still owed once the repo grows a Postgres test harness (tasks 3.4).
- */
-interface Row {
-  sessionId: string;
-  ontology: string;
-  touchedAt: Date;
-}
-
-function makeFakeDb() {
-  const rows: Row[] = [];
-  const db = {
-    _rows: rows,
-    insert() {
-      return {
-        values(v: { sessionId: string; ontology: string }) {
-          return {
-            onConflictDoNothing() {
-              const exists = rows.some((r) => r.sessionId === v.sessionId && r.ontology === v.ontology);
-              if (!exists) rows.push({ sessionId: v.sessionId, ontology: v.ontology, touchedAt: new Date() });
-              return Promise.resolve([]);
-            },
-          };
-        },
-      };
-    },
-    select() {
-      return {
-        from() {
-          return {
-            async where(pred: { sessionId: string }) {
-              return rows
-                .filter((r) => r.sessionId === pred.sessionId)
-                .map((r) => ({ ontology: r.ontology }));
-            },
-          };
-        },
-      };
-    },
-    delete() {
-      return {
-        where(pred: { sessionId?: string; cutoff?: Date }) {
-          if (pred.sessionId !== undefined) {
-            for (let i = rows.length - 1; i >= 0; i--) {
-              if (rows[i].sessionId === pred.sessionId) rows.splice(i, 1);
-            }
-            return { async returning() { return []; } } as never;
-          }
-          const removed: { sessionId: string }[] = [];
-          for (let i = rows.length - 1; i >= 0; i--) {
-            if (pred.cutoff && rows[i].touchedAt < pred.cutoff) {
-              removed.push({ sessionId: rows[i].sessionId });
-              rows.splice(i, 1);
-            }
-          }
-          return { async returning() { return removed; } } as never;
-        },
-      };
-    },
-  };
-  return db;
-}
-
-vi.mock('drizzle-orm', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('drizzle-orm')>();
-  return {
-    ...actual,
-    eq: (_col: unknown, val: string) => ({ sessionId: val }),
-    lt: (_col: unknown, val: Date) => ({ cutoff: val }),
-  };
-});
-
-function makeService() {
-  const db = makeFakeDb();
-  return { svc: new SessionOntologyService(db as unknown as Database, testKbContext()), db };
-}
-
-describe('SessionOntologyService (touched-set model)', () => {
-  let svc: SessionOntologyService;
-  let db: ReturnType<typeof makeFakeDb>;
-
-  beforeEach(() => {
-    ({ svc, db } = makeService());
-  });
-
-  it('records a read and allows it', async () => {
-    const d = await svc.checkOperation('s1', P_READ, false);
-    expect(d.allow).toBe(true);
-    expect(await svc.getTouched('s1')).toEqual([PRODUCT]);
-  });
-
-  it('allows reads ACROSS ontologies (reads are never blocked)', async () => {
-    expect((await svc.checkOperation('s1', P_READ, false)).allow).toBe(true);
-    expect((await svc.checkOperation('s1', PL_READ, false)).allow).toBe(true);
-    expect(await svc.getTouched('s1')).toEqual([PLATFORM, PRODUCT]);
-  });
-
-  it('allows a write while the session is confined to that one ontology', async () => {
-    await svc.checkOperation('s1', P_READ, false);
-    expect((await svc.checkOperation('s1', P_READ, true)).allow).toBe(true);
-  });
-
-  it('allows the first write with no prior reads and pins to it', async () => {
-    expect((await svc.checkOperation('s1', P_READ, true)).allow).toBe(true);
-    expect(await svc.getTouched('s1')).toEqual([PRODUCT]);
-  });
-
-  it('blocks a write to a different ontology than the one read (different-ontology)', async () => {
-    // Load-bearing for the start_session↔ask unification: the touched-set is
-    // keyed purely by sessionId, so a READ and a later WRITE that share ONE id
-    // hit the same set and cross-ontology writes are refused. This only protects
-    // the read→ask flow because both now run under the SAME id (start_session
-    // mints a real chat thread; ask accepts it). If a refactor re-splits those
-    // namespaces, the read and the ask write land in different touched-sets and
-    // this guarantee silently evaporates — see workspace.tools.ts start_session.
-    await svc.checkOperation('s1', P_READ, false);
-    const d = await svc.checkOperation('s1', PL_READ, true);
-    expect(d).toMatchObject({ allow: false, reason: 'different-ontology', attempted: PLATFORM });
-    // The blocked write does NOT record Platform.
-    expect(await svc.getTouched('s1')).toEqual([PRODUCT]);
-  });
-
-  it('blocks ALL writes once the session has read across two ontologies (multi-ontology)', async () => {
-    await svc.checkOperation('s1', P_READ, false);
-    await svc.checkOperation('s1', PL_READ, false); // reads across — poisons writes
-    // Even a write back into Product is now blocked.
-    const back = await svc.checkOperation('s1', P_READ, true);
-    expect(back).toMatchObject({ allow: false, reason: 'multi-ontology' });
-    const other = await svc.checkOperation('s1', PL_READ, true);
-    expect(other.allow).toBe(false);
-  });
-
-  it('treats a neutral path as always-allowed and never recorded', async () => {
-    const d = await svc.checkOperation('s1', 'access.md', true);
-    expect(d.allow).toBe(true);
-    expect(await svc.getTouched('s1')).toEqual([]);
-  });
-
-  it('survives a "restart": a new instance re-reads the touched set from the store', async () => {
-    await svc.checkOperation('s1', P_READ, false);
-    await svc.checkOperation('s1', PL_READ, false);
-    const afterRestart = new SessionOntologyService(db as unknown as Database, testKbContext());
-    // The poison persists across the restart: writes still blocked.
-    expect((await afterRestart.checkOperation('s1', P_READ, true)).allow).toBe(false);
-  });
-
-  it('reclaims a session on delete so it can write again', async () => {
-    await svc.checkOperation('s1', P_READ, false);
-    await svc.checkOperation('s1', PL_READ, false);
-    await svc.delete('s1');
-    expect(await svc.getTouched('s1')).toEqual([]);
-    expect((await svc.checkOperation('s1', P_READ, true)).allow).toBe(true);
-  });
-
-  it('sweeps abandoned sessions older than the cutoff', async () => {
-    await svc.checkOperation('old', P_READ, false);
-    db._rows.forEach((r) => { if (r.sessionId === 'old') r.touchedAt = new Date(Date.now() - 60_000); });
-    const removed = await svc.sweepOlderThan(new Date(Date.now() - 30_000));
-    expect(removed).toBe(1);
-    expect(await svc.getTouched('old')).toEqual([]);
-  });
-
-  it('records each ontology only once (idempotent touches)', async () => {
-    await svc.checkOperation('s1', P_READ, false);
-    await svc.checkOperation('s1', P_READ, false);
-    await svc.checkOperation('s1', P_READ, false);
-    expect(db._rows.filter((r) => r.sessionId === 's1').length).toBe(1);
-  });
-
-  it('serializes two concurrent same-session writes to different ontologies (only one wins)', async () => {
-    // Without per-session serialization both could observe an empty touched set
-    // and both pin to a different ontology before either INSERT lands.
-    const [a, b] = await Promise.all([
-      svc.checkOperation('s1', P_READ, true), // write → Product
-      svc.checkOperation('s1', PL_READ, true), // write → Platform (concurrent)
-    ]);
-    // Exactly one write is allowed; the loser is blocked as different-ontology.
-    expect([a, b].filter((d) => d.allow)).toHaveLength(1);
-    // Only the winner's ontology is recorded.
-    expect(await svc.getTouched('s1')).toHaveLength(1);
-  });
-});

package/src/modules/workflow/session-ontology.policy.ts

@@ -1,70 +0,0 @@
-/**
- * Ontology-session boundary — the PURE decision core (no IO, no DB).
- *
- * Model: each run/session accumulates the SET of named ontologies it has
- * touched (via any read or write). The rule is asymmetric:
- *
- *   READS  — always allowed. A read that touches a named ontology RECORDS it
- *            into the session's touched set (so it can poison later writes).
- *   WRITES — allowed only while the session is confined to a SINGLE named
- *            ontology and the write targets that same ontology. The moment a
- *            session has touched two or more named ontologies (typically by
- *            reading across them), EVERY subsequent write is blocked — "read
- *            across ontologies → you can't write anymore at all."
- *
- * Neutral touches (`ontologyOf` → null: root config, Skills, root-level
- * Knowledge, non-KB) never record and never block. See
- * `docs/rp4-ontology-boundary-plan-v2.md`.
- *
- * `SessionOntologyService` (Postgres-backed) persists the touched set and calls
- * these helpers; this module keeps the rule itself testable in isolation.
- */
-
-import type { Ontology } from '@bevel-software/platform-shared';
-
-/** Outcome of a write check against the session's touched-ontology set. */
-export type WriteDecision =
-  | { allow: true }
-  | { allow: false; reason: 'multi-ontology' | 'different-ontology'; touched: string[]; attempted: string };
-
-/**
- * The set of NAMED ontologies a session has touched after this operation. A
- * neutral operation (`ontology === null`) adds nothing. Pure — returns a new
- * set, never mutates the input.
- */
-export function recordTouch(touched: ReadonlySet<string>, ontology: Ontology): Set<string> {
-  const next = new Set(touched);
-  if (ontology !== null) next.add(ontology);
-  return next;
-}
-
-/**
- * Decide whether a WRITE to `attempted` is allowed given the ontologies the
- * session has already touched (NOT counting this write yet).
- *
- *   - A write to a neutral path (`attempted === null`) is always allowed.
- *   - If the session has already touched two or more named ontologies, the
- *     write is blocked (`multi-ontology`) — reading across ontologies poisoned
- *     the session's write ability.
- *   - If the session has touched exactly one named ontology and it differs from
- *     the write target, the write is blocked (`different-ontology`).
- *   - If the session is unpinned (touched none) or its single touched ontology
- *     equals the target, the write is allowed.
- */
-export function decideWrite(touched: ReadonlySet<string>, attempted: Ontology): WriteDecision {
-  if (attempted === null) return { allow: true };
-
-  // The set of named ontologies the session would span if this write lands.
-  const spanned = new Set(touched);
-  spanned.add(attempted);
-
-  if (spanned.size <= 1) return { allow: true };
-
-  // spanned.size >= 2 — the write would put the session across a boundary.
-  const touchedList = [...touched].sort();
-  if (touched.size >= 2) {
-    return { allow: false, reason: 'multi-ontology', touched: touchedList, attempted };
-  }
-  // Exactly one prior ontology, and it isn't the write target.
-  return { allow: false, reason: 'different-ontology', touched: touchedList, attempted };
-}

package/src/modules/workflow/session-ontology.service.ts

@@ -1,183 +0,0 @@
-/**
- * Ontology-session boundary — the touched-set store (Postgres + cache).
- *
- * Each session accumulates the SET of named ontologies it has touched. The gate
- * calls `checkOperation` for every gated agent tool call:
- *
- *   READ  (isWrite=false) → always allowed; RECORD the touched ontology so it
- *                           can poison later writes.
- *   WRITE (isWrite=true)  → allowed only while the session is confined to a
- *                           single named ontology equal to the target; once the
- *                           session has touched ≥2 ontologies, every write is
- *                           blocked. An allowed write also records its ontology.
- *
- * Neutral operations (`ontologyOf` → null) never record and never block.
- *
- * ┌── checkOperation(sessionId, wsPath, isWrite) ───────────────────────────┐
- * │  ont = ontologyOf(wsPath)                                                │
- * │  ont === null → { allow:true } (neutral; no record)                      │
- * │  touched = loadTouched(sessionId)  (cache, else SELECT)                  │
- * │  WRITE → decideWrite(touched, ont); if blocked, return block (no record) │
- * │  record(sessionId, ont)  (idempotent INSERT; update cache)              │
- * │  return { allow:true }                                                   │
- * └──────────────────────────────────────────────────────────────────────────┘
- *
- * Postgres is the source of truth so the boundary survives a backend restart.
- * The cache holds each session's touched set; a miss re-reads PG. See
- * `docs/rp4-ontology-boundary-plan-v2.md`.
- *
- * Eviction: `delete(sessionId)` at run end is the PRIMARY reclamation;
- * `sweepOlderThan` is the abandoned-run backstop; the MCP layer also calls
- * `delete` from its `onEvict` hook.
- */
-
-import { eq, lt } from 'drizzle-orm';
-import { ontologyOf } from '../../shared/kb-layout.js';
-import type { KbContext } from '../../shared/kb-context.js';
-
-import type { Database } from '../database/connection.js';
-import { sessionOntologyTouches } from '../database/schema.js';
-import { recordTouch, decideWrite, type WriteDecision } from './session-ontology.policy.js';
-import { WorkspaceMutex } from '../kb-fs/mutex.js';
-
-export type OperationDecision =
-  | { allow: true; touched: string[] }
-  | { allow: false; reason: 'multi-ontology' | 'different-ontology'; touched: string[]; attempted: string };
-
-export interface ISessionOntologyService {
-  /**
-   * Evaluate and record a gated agent operation. Reads always allow (and
-   * record); writes allow only while confined to a single ontology. Neutral
-   * paths always allow and record nothing.
-   */
-  checkOperation(sessionId: string, wsPath: string, isWrite: boolean, kbDirName?: string): Promise<OperationDecision>;
-  /** Evaluate/record against an already-resolved ontology (used by graph tools). */
-  checkOntology(sessionId: string, ontology: string | null, isWrite: boolean): Promise<OperationDecision>;
-  /** The set of ontologies a session has touched. */
-  getTouched(sessionId: string): Promise<string[]>;
-  /** Reclaim a session's touched set (run end / MCP onEvict). */
-  delete(sessionId: string): Promise<void>;
-  /** Backstop: drop touch rows older than `cutoff` (abandoned runs). */
-  sweepOlderThan(cutoff: Date): Promise<number>;
-}
-
-export class SessionOntologyService implements ISessionOntologyService {
-  /**
-   * Write-through cache of each session's touched-ontology set. A present entry
-   * is authoritative for the session (we only ever add to it in-process); a
-   * miss re-reads Postgres. Keyed by the agent thread / sessionId.
-   */
-  private readonly cache = new Map<string, Set<string>>();
-
-  /**
-   * Serializes each session's read→decide→record path. Without it, two
-   * concurrent same-session writes (parallel tool calls in one turn) could both
-   * observe a singleton/empty touched set and both be allowed to different
-   * ontologies before either INSERT lands — defeating the boundary. Different
-   * sessions never contend.
-   */
-  private readonly locks = new WorkspaceMutex();
-
-  constructor(
-    private readonly db: Database,
-    /** Names the knowledge-base root a path is classified under; read per call. */
-    private readonly kb: Pick<KbContext, 'layout'>,
-  ) {}
-
-  /**
-   * Resolve `wsPath` to its ontology and evaluate/record the operation. Thin
-   * wrapper over {@link checkOntology} for the common path-based call site.
-   */
-  async checkOperation(
-    sessionId: string,
-    wsPath: string,
-    isWrite: boolean,
-    kbDirName?: string,
-  ): Promise<OperationDecision> {
-    return this.checkOntology(sessionId, ontologyOf(wsPath, this.kb.layout, kbDirName), isWrite);
-  }
-
-  /**
-   * Evaluate (and, when allowed, record) an operation against an
-   * already-resolved ontology. Neutral ops always allow and record nothing;
-   * reads always allow and record; writes allow only while the session stays
-   * confined to the single target ontology (see {@link decideWrite}). A blocked
-   * write records nothing.
-   */
-  async checkOntology(sessionId: string, ontology: string | null, isWrite: boolean): Promise<OperationDecision> {
-    // Neutral operation: always allowed, records nothing. No state mutation, so
-    // it needs no per-session serialization.
-    if (ontology === null) {
-      const touched = await this.loadTouched(sessionId);
-      return { allow: true, touched: [...touched].sort() };
-    }
-
-    // Serialize the decide+record path per session so concurrent same-session
-    // operations can't both pass the boundary on a stale touched set.
-    return this.locks.run(sessionId, async () => {
-      const touched = await this.loadTouched(sessionId);
-
-      if (isWrite) {
-        const decision: WriteDecision = decideWrite(touched, ontology);
-        if (!decision.allow) {
-          return {
-            allow: false,
-            reason: decision.reason,
-            touched: decision.touched,
-            attempted: decision.attempted,
-          };
-        }
-      }
-
-      // Allowed (read, or a write confined to one ontology): record the touch.
-      await this.record(sessionId, ontology, touched);
-      return { allow: true, touched: [...recordTouch(touched, ontology)].sort() };
-    });
-  }
-
-  /** The sorted set of named ontologies this session has touched so far. */
-  async getTouched(sessionId: string): Promise<string[]> {
-    return [...(await this.loadTouched(sessionId))].sort();
-  }
-
-  /** Reclaim a session's touched set from both the cache and Postgres (run end / MCP onEvict). */
-  async delete(sessionId: string): Promise<void> {
-    this.cache.delete(sessionId);
-    await this.db.delete(sessionOntologyTouches).where(eq(sessionOntologyTouches.sessionId, sessionId));
-  }
-
-  /** Backstop sweep: drop touch rows older than `cutoff` (abandoned runs) and return how many were removed. */
-  async sweepOlderThan(cutoff: Date): Promise<number> {
-    const removed = await this.db
-      .delete(sessionOntologyTouches)
-      .where(lt(sessionOntologyTouches.touchedAt, cutoff))
-      .returning({ sessionId: sessionOntologyTouches.sessionId });
-    // A swept session may have other (newer) rows; drop its cache entry so the
-    // next op re-reads the authoritative remaining set from Postgres.
-    for (const r of removed) this.cache.delete(r.sessionId);
-    return removed.length;
-  }
-
-  /** Load a session's touched set from cache, else from Postgres (and cache it). */
-  private async loadTouched(sessionId: string): Promise<Set<string>> {
-    const cached = this.cache.get(sessionId);
-    if (cached) return cached;
-    const rows = await this.db
-      .select({ ontology: sessionOntologyTouches.ontology })
-      .from(sessionOntologyTouches)
-      .where(eq(sessionOntologyTouches.sessionId, sessionId));
-    const set = new Set(rows.map((r) => r.ontology));
-    this.cache.set(sessionId, set);
-    return set;
-  }
-
-  /** Record a touched ontology (idempotent) and update the cache. */
-  private async record(sessionId: string, ontology: string, current: Set<string>): Promise<void> {
-    if (current.has(ontology)) return; // already recorded; no DB write needed
-    await this.db
-      .insert(sessionOntologyTouches)
-      .values({ sessionId, ontology })
-      .onConflictDoNothing({ target: [sessionOntologyTouches.sessionId, sessionOntologyTouches.ontology] });
-    current.add(ontology);
-  }
-}