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

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

package/src/shared/kb-layout.test.ts

@@ -1,98 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
-import { ontologyOf } from './kb-layout.js';
-
-/** `ontologyOf` under the default layout, which is what these cases are written against. */
-const ont = (path: string, kbDirName?: string) => ontologyOf(path, DEFAULT_KB_LAYOUT, kbDirName);
-
-describe('ontologyOf', () => {
-  it('classifies under the knowledge-base root the layout names, not the default one', () => {
-    const layout = { ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'docs' };
-    expect(ontologyOf('docs/Product/Knowledge/Foo.md', layout)).toBe('docs/Product');
-    expect(ontologyOf('KnowledgeBase/Product/Knowledge/Foo.md', layout)).toBeNull();
-  });
-
-  it('resolves a named ontology under Knowledge', () => {
-    expect(ont('KnowledgeBase/Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-  });
-
-  it('resolves a named ontology under NodeTypes', () => {
-    expect(ont('KnowledgeBase/Product/NodeTypes/Process.md')).toBe('KnowledgeBase/Product');
-  });
-
-  it('is space-safe in the ontology name', () => {
-    expect(ont('KnowledgeBase/IT Architecture/NodeTypes/ServiceCommitment.md')).toBe(
-      'KnowledgeBase/IT Architecture',
-    );
-  });
-
-  it('treats a nested ontology directory as the full prefix before the marker', () => {
-    expect(ont('KnowledgeBase/Plugin/Sub/Knowledge/x.md')).toBe('KnowledgeBase/Plugin/Sub');
-  });
-
-  it('returns null when the marker sits directly under KnowledgeBase/', () => {
-    expect(ont('KnowledgeBase/Knowledge/Foo.md')).toBeNull();
-    expect(ont('KnowledgeBase/NodeTypes/T.md')).toBeNull();
-  });
-
-  it('returns null for root-level Knowledge (not under KnowledgeBase/)', () => {
-    expect(ont('Knowledge/Foo.md')).toBeNull();
-  });
-
-  it('returns null for Data/ ontologies (deliberate session-ontology exemption)', () => {
-    // `Data/<X>` IS parsed into the graph (parser `ONTOLOGY_ROOTS`), but is
-    // intentionally NOT classified here so the session-ontology gate treats
-    // Data paths as neutral — pipeline agents read knowledge and write data
-    // in one session (owner decision 2026-07-27). See the `ontologyOf`
-    // docstring; this is not drift.
-    expect(ont('Data/Ops/Knowledge/x.md')).toBeNull();
-    expect(ont('Data/Ops/NodeTypes/Ticket.md')).toBeNull();
-    // KnowledgeBase paths still classify as before.
-    expect(ont('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
-  });
-
-  it('returns null for Plugins and root config (neutral)', () => {
-    expect(ont('Plugins/some-skill/SKILL.md')).toBeNull();
-    expect(ont('access.md')).toBeNull();
-    expect(ont('roles.yaml')).toBeNull();
-  });
-
-  it('returns null for an ontology path with no marker segment', () => {
-    expect(ont('KnowledgeBase/Product/Uploads/diagram.png')).toBeNull();
-  });
-
-  it('does not match substring lookalikes (segment equality)', () => {
-    expect(ont('KnowledgeBase/Product/Knowledge-notes.md')).toBeNull();
-    expect(ont('KnowledgeBase/Product/KnowledgeBase/x.md')).toBeNull();
-  });
-
-  it('strips a kbDirName prefix (normalized and un-normalized)', () => {
-    expect(ont('knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md', 'knowledge-base')).toBe(
-      'KnowledgeBase/Product',
-    );
-    expect(ont('./knowledge-base/KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base/')).toBe(
-      'KnowledgeBase/GTM',
-    );
-  });
-
-  it('normalizes backslashes and leading/trailing slashes', () => {
-    expect(ont('/KnowledgeBase/Product/Knowledge/Foo.md/')).toBe('KnowledgeBase/Product');
-    expect(ont('KnowledgeBase\\Product\\Knowledge\\Foo.md')).toBe('KnowledgeBase/Product');
-  });
-
-  it('canonicalizes inner . and .. segments to the same ontology', () => {
-    expect(ont('KnowledgeBase/Product/./Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    expect(ont('KnowledgeBase/Product/Sub/../Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    expect(ont('KnowledgeBase/Platform/../Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    // `..` also collapses inside the stripped kbDirName prefix.
-    expect(ont('knowledge-base/x/../KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base')).toBe(
-      'KnowledgeBase/GTM',
-    );
-  });
-
-  it('returns null for empty or root paths', () => {
-    expect(ont('')).toBeNull();
-    expect(ont('KnowledgeBase')).toBeNull();
-    expect(ont('KnowledgeBase/Product')).toBeNull();
-  });
-});

package/src/shared/kb-layout.ts

@@ -1,102 +0,0 @@
-import { ONTOLOGY_MARKERS, type KbLayout, type Ontology } from '@bevel-software/platform-shared';
-
-/**
- * Resolve which named ontology a KB path belongs to — the backend-side
- * implementation of the layout contract whose constants/types live in
- * `@bevel-software/platform-shared` (`kb-layout.ts`). It is backend-only and consumed by
- * more than one domain module (the `workspace` read gate and the `workflow`
- * session-ontology service), so it lives in `backend/src/shared` rather than in
- * any single module — importable by both modules without crossing a module's
- * internal boundary. Note it does NOT mirror the kb-graph parser one-to-one:
- * see the `ontologyOf` docstring for the deliberate `Data/` exemption.
- *
- * Pure string handling — no IO, no DB.
- */
-
-/**
- * Split a path into repo-root-relative POSIX segments, dropping `./`,
- * leading/trailing slashes, and an optional `kbDirName` prefix (the on-disk
- * clone folder, e.g. `knowledge-base/`). Pure string handling — no IO.
- */
-function toSegments(path: string, kbDirName?: string): string[] {
-  // Collapse to canonical segments: backslashes → `/`, drop empty and `.`
-  // segments, resolve `..` against the accumulated prefix. Canonicalizing the
-  // inner segments (not just the ends) means equivalent paths like
-  // `KnowledgeBase/Product/../Product/Knowledge/x.md` and
-  // `KnowledgeBase/Product/Knowledge/x.md` resolve to the same ontology.
-  const collapse = (s: string): string[] => {
-    const out: string[] = [];
-    for (const seg of s.replace(/\\/g, '/').split('/')) {
-      if (seg === '' || seg === '.') continue;
-      if (seg === '..') {
-        // Pop a real segment; a leading `..` (nothing to pop) is kept so it can
-        // never alias into a sibling ontology.
-        if (out.length > 0 && out[out.length - 1] !== '..') out.pop();
-        else out.push('..');
-        continue;
-      }
-      out.push(seg);
-    }
-    return out;
-  };
-
-  let segs = collapse(path);
-  const prefixSegs = kbDirName ? collapse(kbDirName) : [];
-  if (prefixSegs.length > 0 && prefixSegs.every((s, i) => segs[i] === s)) {
-    segs = segs.slice(prefixSegs.length);
-  }
-  return segs;
-}
-
-/**
- * Resolve the named ontology a KB path belongs to, or `null` (neutral) when it
- * belongs to none.
- *
- * Classification is deliberately NARROWER than the kb-graph parser: the parser
- * discovers ontologies under every `ONTOLOGY_ROOTS` entry (`KnowledgeBase/`
- * AND `Data/`), but this function classifies ONLY `KnowledgeBase/` paths.
- * `Data/` ontologies are parsed into the graph yet are intentionally NOT
- * classified here, so the session-ontology gate treats `Data/` paths as
- * neutral — pipeline agents read knowledge and write data records in one
- * session (owner decision 2026-07-27; the cross-ontology boundary mechanism
- * itself may be redesigned). This divergence is on purpose, not drift.
- *
- * Within `KnowledgeBase/`, the shape matches the parser (`parser.ts`
- * `walkForOntologies`): an ontology is the directory that holds both a
- * `Knowledge/` and a `NodeTypes/` subfolder. That directory can sit at ANY
- * depth under `KnowledgeBase/`, so the ontology id is the path PREFIX up to
- * (but excluding) the first `Knowledge/` or `NodeTypes/` marker segment — as
- * long as that prefix is inside `KnowledgeBase/` and is not `KnowledgeBase/`
- * itself.
- *
- *   KnowledgeBase/Product/Knowledge/Foo.md            → "KnowledgeBase/Product"
- *   KnowledgeBase/IT Architecture/NodeTypes/T.md      → "KnowledgeBase/IT Architecture"
- *   KnowledgeBase/Group/Sub/Knowledge/x.md            → "KnowledgeBase/Group/Sub"
- *   KnowledgeBase/Knowledge/Foo.md                    → null (marker directly under KB root)
- *   Knowledge/Foo.md, Skills/x.md, access.md          → null (not under KnowledgeBase/)
- *   Data/Ops/Knowledge/x.md                           → null (Data/ is exempt — see above)
- *   KnowledgeBase/Product/Uploads/x.png               → null (no marker segment)
- *
- * Uses exact segment equality (never substring), so `KnowledgeBase/` and
- * `Knowledge-notes.md` are never treated as markers; space-safe; pure (no IO).
- *
- * @param path       repo-root-relative POSIX path (may carry a `kbDirName` prefix)
- * @param layout     the knowledge base's layout — names its `KnowledgeBase/` root
- * @param kbDirName  optional on-disk clone folder prefix to strip first
- */
-export function ontologyOf(path: string, layout: KbLayout, kbDirName?: string): Ontology {
-  const segs = toSegments(path, kbDirName);
-  // Must live under the dedicated KnowledgeBase/ container, with at least one
-  // ontology-name segment and a marker after it (so length >= 3).
-  if (segs.length < 3 || segs[0] !== layout.knowledgeBaseDir) return null;
-  // The ontology id is the prefix before the first marker segment. Require at
-  // least one name segment between `KnowledgeBase/` and the marker, so a marker
-  // sitting directly under `KnowledgeBase/` (`KnowledgeBase/Knowledge/...`) is
-  // neutral, matching the parser (it only discovers ontologies one level down).
-  for (let i = 1; i < segs.length; i++) {
-    if (ONTOLOGY_MARKERS.has(segs[i])) {
-      return i >= 2 ? segs.slice(0, i).join('/') : null;
-    }
-  }
-  return null;
-}