@bevel-software/platform-core-backend 0.21.0 → 0.23.0

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);
-  }
-}

package/src/modules/workspace/__tests__/session-ontology.gate.test.ts

@@ -1,239 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-
-import {
-  recordOntologyRead,
-  assertOntologyWriteAllowed,
-  assertShellAllowedWithinOntology,
-  MissingSessionError,
-  type SessionOntologyGate,
-} from '../session-ontology.gate.js';
-import type { ToolContext } from '../../tool-helpers/tool.contract.js';
-import type { ISessionOntologyService, OperationDecision } from '../../workflow/session-ontology.service.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { ontologyOf } from '../../../shared/kb-layout.js';
-import { testKbContext } from '../../../__tests__/kb-context.js';
-
-const KB = 'knowledge-base';
-const kbContext = testKbContext({ kbDirName: KB });
-const P_FILE = 'KnowledgeBase/Product/Knowledge/Foo.md';
-const PL_FILE = 'KnowledgeBase/Platform/Knowledge/Bar.md';
-const NEUTRAL = 'access.md';
-const RECOVERY_EMAIL = 'recovery-bot@bevel.local';
-
-/**
- * In-memory stand-in for the touched-set service — applies the real
- * reads-record / writes-block-once-multi rule against a per-session set, so the
- * gate's interaction with it is exercised end to end without a DB.
- */
-function makeFakeService(): ISessionOntologyService {
-  const touched = new Map<string, Set<string>>();
-  const setFor = (s: string) => touched.get(s) ?? new Set<string>();
-  return {
-    async checkOperation(sessionId, wsPath, isWrite): Promise<OperationDecision> {
-      const ont = ontologyOf(wsPath, kbContext.layout, KB);
-      const set = setFor(sessionId);
-      if (ont === null) return { allow: true, touched: [...set].sort() };
-      if (isWrite) {
-        const spanned = new Set(set).add(ont);
-        if (spanned.size > 1) {
-          return {
-            allow: false,
-            reason: set.size >= 2 ? 'multi-ontology' : 'different-ontology',
-            touched: [...set].sort(),
-            attempted: ont,
-          };
-        }
-      }
-      set.add(ont);
-      touched.set(sessionId, set);
-      return { allow: true, touched: [...set].sort() };
-    },
-    checkOntology: async () => ({ allow: true, touched: [] }),
-    getTouched: async (s) => [...setFor(s)].sort(),
-    delete: async (s) => { touched.delete(s); },
-    sweepOlderThan: async () => 0,
-  };
-}
-
-/**
- * Build a gate wired the way the CORE composition wires it: the fake
- * touched-set service plus an EMPTY hooks registry. Core registers no
- * `preWrite` hook, so the gate only TRACKS touches and never blocks — the
- * blocking assertions (the ontology-block hook the enterprise composition
- * root registers) live with that hook in the enterprise repo.
- */
-function makeGate(): SessionOntologyGate {
-  const service = makeFakeService();
-  const hooks = new WorkflowHooks();
-  return { service, enabled: true, kb: kbContext, recoveryBotEmail: RECOVERY_EMAIL, hooks };
-}
-
-function ctx(overrides: Partial<ToolContext> = {}): ToolContext {
-  return {
-    user: { id: 'u1', email: 'dev@bevel.local', name: 'Dev' },
-    scope: 'write',
-    source: 'internal',
-    sessionId: 's1',
-    abortSignal: new AbortController().signal,
-    workspaceService: {} as never,
-    workflowService: {} as never,
-    events: {} as never,
-    getFilesystem: async () => ({} as never),
-    ...overrides,
-  };
-}
-
-describe('recordOntologyRead', () => {
-  let gate: SessionOntologyGate;
-
-  beforeEach(() => {
-    gate = makeGate();
-  });
-
-  it('does nothing when the flag is disabled', async () => {
-    gate.enabled = false;
-    await expect(recordOntologyRead(gate, ctx(), P_FILE)).resolves.toBeUndefined();
-    expect(await gate.service.getTouched('s1')).toEqual([]);
-  });
-
-  it('skips neutral paths (no record)', async () => {
-    await expect(recordOntologyRead(gate, ctx(), NEUTRAL)).resolves.toBeUndefined();
-    expect(await gate.service.getTouched('s1')).toEqual([]);
-  });
-
-  it('skips non-agent (browser session) callers', async () => {
-    await expect(
-      recordOntologyRead(gate, ctx({ source: 'session', sessionId: undefined }), P_FILE),
-    ).resolves.toBeUndefined();
-  });
-
-  it('skips the recovery bot by identity', async () => {
-    await expect(
-      recordOntologyRead(
-        gate,
-        ctx({ user: { id: 'bot', email: 'Recovery-Bot@Bevel.Local', name: 'bot' }, sessionId: undefined }),
-        PL_FILE,
-      ),
-    ).resolves.toBeUndefined();
-  });
-
-  it('fails closed when an agent read of a named path has no session id', async () => {
-    await expect(recordOntologyRead(gate, ctx({ sessionId: undefined }), P_FILE)).rejects.toBeInstanceOf(
-      MissingSessionError,
-    );
-  });
-
-  it('allows a neutral read without a session id', async () => {
-    await expect(recordOntologyRead(gate, ctx({ sessionId: undefined }), NEUTRAL)).resolves.toBeUndefined();
-  });
-
-  it('records a read and allows it', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    expect(await gate.service.getTouched('s1')).toEqual(['KnowledgeBase/Product']);
-  });
-
-  it('allows reads across ontologies (recording both)', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await expect(recordOntologyRead(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
-    expect(await gate.service.getTouched('s1')).toEqual(['KnowledgeBase/Platform', 'KnowledgeBase/Product']);
-  });
-
-  it('never blocks — a read into a second ontology still passes (delete_file relies on this)', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    // A delete_file in a different ontology records its touch but never throws.
-    await expect(recordOntologyRead(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
-  });
-});
-
-describe('assertOntologyWriteAllowed', () => {
-  let gate: SessionOntologyGate;
-
-  beforeEach(() => {
-    gate = makeGate();
-  });
-
-  it('does nothing when the flag is disabled', async () => {
-    gate.enabled = false;
-    // Even a cross-ontology write must pass when disabled.
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await expect(assertOntologyWriteAllowed(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
-  });
-
-  it('skips neutral paths (no record, no block)', async () => {
-    await expect(assertOntologyWriteAllowed(gate, ctx(), NEUTRAL)).resolves.toBeUndefined();
-    expect(await gate.service.getTouched('s1')).toEqual([]);
-  });
-
-  it('fails closed when an agent write of a named path has no session id', async () => {
-    await expect(assertOntologyWriteAllowed(gate, ctx({ sessionId: undefined }), P_FILE)).rejects.toBeInstanceOf(
-      MissingSessionError,
-    );
-  });
-
-  it('allows a write confined to the one touched ontology', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await expect(assertOntologyWriteAllowed(gate, ctx(), P_FILE)).resolves.toBeUndefined();
-  });
-
-  // NOTE (core split): the "blocks a write to a different ontology" and
-  // "blocks ALL writes once the session has read across two ontologies" cases
-  // moved with the ontology-block hook (`registerOntologyBlockHook`) to the
-  // enterprise repo — core registers no preWrite hook, so a core-only
-  // deployment TRACKS but never blocks. The tests below pin exactly that.
-
-  it('core: allows a write to a different ontology (tracking only, no block hook)', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await expect(assertOntologyWriteAllowed(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
-  });
-
-  it('core: still allows writes after reading across two ontologies (no block hook)', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await recordOntologyRead(gate, ctx(), PL_FILE);
-    await expect(assertOntologyWriteAllowed(gate, ctx(), P_FILE)).resolves.toBeUndefined();
-  });
-});
-
-describe('assertShellAllowedWithinOntology (shell / no-path tools)', () => {
-  let gate: SessionOntologyGate;
-
-  beforeEach(() => {
-    gate = makeGate();
-  });
-
-  it('allows a fresh session (nothing touched)', async () => {
-    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
-  });
-
-  it('allows a session confined to a single ontology', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
-  });
-
-  // NOTE (core split): the "blocks once the session has crossed into two
-  // ontologies" case moved with the enterprise ontology-block hook. Core
-  // registers no preWrite hook, so shell is never refused here.
-  it('core: allows shell even after crossing into two ontologies (no block hook)', async () => {
-    await recordOntologyRead(gate, ctx(), P_FILE);
-    await recordOntologyRead(gate, ctx(), PL_FILE);
-    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
-  });
-
-  it('does nothing when the flag is disabled', async () => {
-    gate.enabled = false;
-    await gate.service.checkOperation('s1', P_FILE, false);
-    await gate.service.checkOperation('s1', PL_FILE, false);
-    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
-  });
-
-  it('exempts the recovery bot', async () => {
-    await gate.service.checkOperation('s1', P_FILE, false);
-    await gate.service.checkOperation('s1', PL_FILE, false);
-    await expect(
-      assertShellAllowedWithinOntology(gate, ctx({ user: { id: 'bot', email: RECOVERY_EMAIL, name: 'bot' } })),
-    ).resolves.toBeUndefined();
-  });
-
-  it('allows when there is no session id (nothing to evaluate)', async () => {
-    await expect(assertShellAllowedWithinOntology(gate, ctx({ sessionId: undefined }))).resolves.toBeUndefined();
-  });
-});

package/src/modules/workspace/session-ontology.gate.ts

@@ -1,191 +0,0 @@
-/**
- * Ontology-session boundary — the per-call gate used by the agent tool handlers.
- *
- * One decision fn, called by every gated file/graph handler:
- *   READS  (isWrite=false) record the touched ontology and always allow.
- *   WRITES (isWrite=true)  run the registered BLOCKING `preWrite` hooks
- *                          (`WorkflowHooks`), then record. The core registers
- *                          no hook, so core alone only TRACKS; the enterprise
- *                          overlay registers the ontology block (see
- *                          `modules/kb/ontology-block.hook.ts`), restoring
- *                          "allowed only while the session is confined to a
- *                          single ontology; once it has touched ≥2, all
- *                          writes are blocked".
- *
- * Skips entirely when: the flag is off, the path is neutral (`ontologyOf` →
- * null), the caller is not an agent, or the caller is the recovery bot. Fails
- * CLOSED for an agent named-path operation that carries no `sessionId`.
- *
- * Lives beside `assertCanRead` in the workspace tools — it does NOT touch
- * `acquireLock` (that gate is protected-branch-only; this boundary applies on
- * all branches and to reads). See `docs/rp4-ontology-boundary-plan-v2.md`.
- */
-
-import { ontologyOf } from '../../shared/kb-layout.js';
-import type { KbContext } from '../../shared/kb-context.js';
-import type { JsonSchema } from '../tool-registry/tool.contract.js';
-import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
-import type { ISessionOntologyService } from '../workflow/session-ontology.service.js';
-import type { WorkflowHooks } from '../workflow/workflow-hooks.js';
-
-/**
- * The `sessionId` input the ontology-session boundary reads: the agent run /
- * conversation id. The in-process agent supplies its thread id automatically
- * (via its per-run internal token); an external agent has no ambient run id,
- * so it must first mint one with the `start_session` tool and then pass it
- * EXPLICITLY on every gated call — the MCP proxy is a pure passthrough and
- * never injects args.
- */
-export const SESSION_ID_INPUT: JsonSchema = {
-  type: 'string',
-  description:
-    'The KnowledgeBase session id that scopes this run to one ontology. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here on EVERY gated call. The in-process agent runtime supplies this automatically (do not set it yourself).',
-};
-
-/**
- * Boundary warning appended to ontology-gated tool descriptions so the agent
- * knows the restriction before it calls one. Action-then-why phrasing per
- * docs/glossary.md.
- */
-export const ONTOLOGY_BOUNDARY_NOTE =
-  ' Stay within one KnowledgeBase ontology per conversation: once this run has read or written files in two different ontologies, every later content write (write_file/edit_file/mkdir/unzip, and both endpoints of move_file/copy_file) is blocked with a 403 and no override. Reads, delete_file and delete_folder never block — but each one records the ontology it touched and can poison a later content write, so do broad cross-ontology exploration only when you do not intend to write. Note move_file/copy_file are blocked outright when source and destination are different ontologies, since they would carry content across.';
-
-/** Thrown when a write is refused because the session has crossed ontologies. */
-export class OntologyWriteBlockedError extends ToolError {
-  constructor(touched: string[], attempted: string, reason: 'multi-ontology' | 'different-ontology') {
-    const msg =
-      reason === 'multi-ontology'
-        ? `This conversation has already read across multiple ontologies (${touched.join(', ')}), so writing is no longer allowed. Start a new conversation to write to "${attempted}".`
-        : `This conversation is working in ${touched.join(', ')}, so it can't write to a different ontology ("${attempted}"). Start a new conversation to work in "${attempted}".`;
-    super(msg, 403);
-    this.name = 'OntologyWriteBlockedError';
-  }
-}
-
-/** Thrown when an agent op on a named ontology carries no session id (fail closed). */
-export class MissingSessionError extends ToolError {
-  constructor() {
-    super(
-      'This operation needs a KnowledgeBase session id and none was provided. Call the `start_session` tool once at the start of your work to obtain a sessionId, then pass it explicitly as `sessionId` on every gated call (direct MCP calls and `call_tool_chain` alike).',
-      403,
-    );
-    this.name = 'MissingSessionError';
-  }
-}
-
-export interface SessionOntologyGate {
-  service: ISessionOntologyService;
-  enabled: boolean;
-  /** The checkout folder and the layout a path is classified under. */
-  kb: Pick<KbContext, 'kbDirName' | 'layout'>;
-  /** Lowercased email of the recovery/merge bot, which is exempt. */
-  recoveryBotEmail: string;
-  /**
-   * The workflow lifecycle-hook registry whose BLOCKING `preWrite` hooks
-   * decide whether a gated write/shell op proceeds. Core registers none (the
-   * gate then only tracks); the enterprise composition root registers the
-   * ontology block against `workflowService.hooks` — pass that same instance
-   * here.
-   */
-  hooks: WorkflowHooks;
-}
-
-/** Only internal/external agent callers are gated; `session` (browser JWT) and humans are not. */
-function isAgentSource(ctx: ToolContext): boolean {
-  return ctx.source === 'internal' || ctx.source === 'external';
-}
-
-/**
- * Shared gate preamble for the two per-path operations below. Returns `'skip'`
- * when the boundary doesn't apply to this call (flag off, neutral path,
- * non-agent caller, or recovery bot), otherwise the session id to evaluate
- * against — throwing `MissingSessionError` (fail closed) when an agent op on a
- * named ontology carries none.
- */
-function resolveGatedSession(gate: SessionOntologyGate, ctx: ToolContext, wsPath: string): string | 'skip' {
-  if (!gate.enabled) return 'skip';
-  // Neutral paths never pin/record/block — skip before any identity work.
-  if (ontologyOf(wsPath, gate.kb.layout, gate.kb.kbDirName) === null) return 'skip';
-  // Humans (UI routes) and browser-JWT callers never hit these tools; only
-  // agent tool calls are gated.
-  if (!isAgentSource(ctx)) return 'skip';
-  // The recovery/merge bot legitimately spans ontologies — exempt by identity.
-  if (ctx.user.email.toLowerCase() === gate.recoveryBotEmail) return 'skip';
-  // Fail closed: an agent operation on a named ontology must carry a session id.
-  if (!ctx.sessionId) throw new MissingSessionError();
-  return ctx.sessionId;
-}
-
-/**
- * Record a read of `wsPath`'s ontology into the session's touched set. Reads are
- * always allowed — recording is the only effect — but each one widens the
- * touched set and so can poison a later write (see {@link assertOntologyWriteAllowed}).
- * Fails closed (`MissingSessionError`) for an agent read of a named ontology
- * with no session id.
- */
-export async function recordOntologyRead(gate: SessionOntologyGate, ctx: ToolContext, wsPath: string): Promise<void> {
-  const sessionId = resolveGatedSession(gate, ctx, wsPath);
-  if (sessionId === 'skip') return;
-  // checkOperation(isWrite=false) records the touch and always allows.
-  await gate.service.checkOperation(sessionId, wsPath, false, gate.kb.kbDirName);
-}
-
-/**
- * Assert a write to `wsPath` is allowed, then record it. A write that would
- * carry information into a second ontology is the thing the boundary blocks:
- * permitted only while the session stays confined to the target ontology, and
- * refused with `OntologyWriteBlockedError` once it has touched ≥2. Note `delete`
- * is NOT a write here — removing a node propagates no cross-ontology
- * information, so it goes through {@link recordOntologyRead}.
- *
- * The BLOCKING decision itself lives behind the `preWrite` hooks: the
- * enterprise-registered ontology block evaluates-and-records atomically via
- * `checkOperation(isWrite=true)` and throws to refuse (identical behavior to
- * the previous in-gate decision). Core registers no hook, so with none the
- * write is allowed and only the touch is recorded (tracking stays core). The
- * follow-up read-record after the hooks is idempotent — a no-op when a hook
- * already recorded the allowed write.
- */
-export async function assertOntologyWriteAllowed(
-  gate: SessionOntologyGate,
-  ctx: ToolContext,
-  wsPath: string,
-): Promise<void> {
-  const sessionId = resolveGatedSession(gate, ctx, wsPath);
-  if (sessionId === 'skip') return;
-  await gate.hooks.runPreWrite({ kind: 'file-write', sessionId, wsPath });
-  // Tracking stays core: record the (now-allowed) write's ontology touch.
-  // A blocked write never reaches this line, so it records nothing — same as
-  // before the hook split.
-  await gate.service.checkOperation(sessionId, wsPath, false, gate.kb.kbDirName);
-}
-
-/**
- * Session-level write-eligibility gate for write-capable tools that have no
- * single resolvable target path to check per-call — currently `execute_command`
- * (arbitrary shell). Such a tool cannot be path-confined, so we enforce the
- * boundary at the coarser session level: once the run has crossed into ≥2
- * ontologies (the point at which EVERY path-checked write is already refused),
- * we refuse the tool outright, so shell can't become a write path around the
- * boundary. A fresh or single-ontology session is still allowed; a residual gap
- * remains (a single-ontology session could shell-write a *different* ontology),
- * accepted because arbitrary shell cannot be path-confined and blocking all
- * shell after one KB read would gut its read-style diagnostic use (git/grep/ls).
- *
- * Skips when: the flag is off, the caller is not an agent, the caller is the
- * recovery bot, or there is no session id — there is no named path here to fail
- * closed on, and with no session there is no touched set to evaluate.
- *
- * Like {@link assertOntologyWriteAllowed}, the refusal itself is the
- * enterprise-registered `preWrite` hook's (it evaluates the touched set and
- * throws); core registers none, so shell is never refused in a core-only
- * deployment.
- */
-export async function assertShellAllowedWithinOntology(gate: SessionOntologyGate, ctx: ToolContext): Promise<void> {
-  if (!gate.enabled) return;
-  if (!isAgentSource(ctx)) return;
-  if (ctx.user.email.toLowerCase() === gate.recoveryBotEmail) return;
-  if (!ctx.sessionId) return;
-
-  await gate.hooks.runPreWrite({ kind: 'shell', sessionId: ctx.sessionId });
-}