AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
fix(knowledge): isolate integration attachments from company documents
Rufus6f3d12af6ffc
diff --git a/packages/core/openexecutive/api/main.py b/packages/core/openexecutive/api/main.pyindex c9838501..4095c339 100644--- a/packages/core/openexecutive/api/main.py+++ b/packages/core/openexecutive/api/main.py@@ -152,6 +152,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:from openexecutive.audit import AuditLogger, set_audit_loggerfrom openexecutive.config import get_settingsfrom openexecutive.knowledge.loader import (+ migrate_attachments_out_of_company_docs,reconcile_company_docs,seed_builtin_knowledge,seed_failures,@@ -179,10 +180,19 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:await seed_builtin_skills(store=store)await seed_failures(store=store)- # Repair company_docs rows left by the old upload path, which indexed- # documents under their random staging filename: those chunks match no- # DELETE and are displaced by no re-upload, so nothing else can reach- # them. Converges on a stable store, so it is safe to run every boot.+ # Two boot-time repairs of company_docs, in one task, in order.+ #+ # First, move out any attachment chunks: they were written into+ # company_docs under a domain outside the specialist set, which did NOT+ # keep them out of retrieval (an unfiltered query builds no `where`+ # clause and matches every domain). They belong in the isolated+ # collection nothing queries. It runs first so that a row it is about to+ # move cannot also be re-indexed by the reconcile in the same pass.+ #+ # Then repair rows left by the old upload path, which indexed documents+ # under their random staging filename: those chunks match no DELETE and+ # are displaced by no re-upload, so nothing else can reach them. Both+ # converge on a stable store, so it is safe to run every boot.## Deliberately NOT awaited here. `ingest_file` does synchronous embedding# work, and the boot that matters most — the first one after this deploy —@@ -195,6 +205,23 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:# Strong ref, same reason as `_thread_rename_tasks` in discord_bot: a bare# create_task is only weakly held and can be GC'd mid-flight.async def _reconcile_company_docs() -> None:+ try:+ # On a thread, not merely off the lifespan: every step of the+ # migration blocks (metadata scan, text fetch, embedding pass), so+ # scheduling it on this loop would defer the stall rather than+ # avoid it, and `/health` would go unanswered for the whole repair.+ moved = await asyncio.to_thread(+ migrate_attachments_out_of_company_docs, store+ )+ if moved:+ logging.getLogger("openexecutive").info(+ "company_docs reconcile: moved %d attachment chunk(s) out of the "+ "company collection",+ moved,+ )+ except Exception:+ logging.getLogger("openexecutive").exception("attachment migration failed")+try:swept, indexed = await reconcile_company_docs(store, settings.company_profile_path.parent / "docs"diff --git a/packages/core/openexecutive/api/routes/chat.py b/packages/core/openexecutive/api/routes/chat.pyindex 280a327d..8866c934 100644--- a/packages/core/openexecutive/api/routes/chat.py+++ b/packages/core/openexecutive/api/routes/chat.py@@ -585,9 +585,10 @@ async def chat_upload("""Streaming chat turn with file/photo attachments.Documents (PDF/DOCX/TXT/MD/CSV) have their text extracted, inlined into- the user message, and indexed into the ChromaDB ``company_docs``+ the user message, and indexed into the ChromaDB ``inbound_attachments``collection as a background task — exactly the behavior the Discord and- Telegram bots already use. Images are converted into Anthropic vision+ Telegram bots already use. That collection is never retrieved from, so an+ attachment informs the turn that carried it and no later one. Images are converted into Anthropic visionblocks and passed through ``attachment_blocks``."""if not files:diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex 029d400d..a7ccb4ff 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -691,13 +691,11 @@ knowledge:path, an uploaded plan.md and a fixture-loaded plan.md are the samedocument rather than two.- Chat/email attachments (integrations.attachments) share this- collection but are namespaced `attachment:<bare filename>`. The- sender chooses that filename and the filename is the id namespace, so- an unprefixed one would upsert straight over the curated company- document it collides with — same "unvetted text must not blend into- curated uploads" reasoning that isolates NOTION_WIKI and- RECENT_RESEARCH, applied within a collection.+ Chat/integration attachments are NOT in this collection — see+ ATTACHMENTS below. They used to be, isolated only by a domain outside+ the specialist set, which isolated nothing. Rows left by that path are+ migrated out on boot by+ loader.migrate_attachments_out_of_company_docs, not purged.RECONCILE ON BOOT. The lifespan callsloader.reconcile_company_docs(store, docs_dir), which drops rows whose@@ -743,6 +741,37 @@ knowledge:retriever queries it with a small n and appends it under a clearly-labelled "Recent research (unverified, web-sourced …)" section rankedBELOW the curated company-documents section.+ - name: ATTACHMENTS+ what: |+ Files attached in an integration channel (ChromaDB collection+ `inbound_attachments`), written only by+ integrations.attachments._schedule_ingest. Rows carry+ `type=attachment`, domain `attachment`, filename+ `attachment:<bare name>`.++ The one collection retriever.retrieve NEVER queries. An attachment's+ content is chosen by whoever sent the message, passes through no+ upload endpoint, gets no review, and leaves no copy in docs/. It is+ already inlined into the turn that carried it, which is where it is+ useful; what it must not become is company knowledge resurfacing in+ later, unrelated turns. NOTION_WIKI and RECENT_RESEARCH are+ queried-but-labelled; this one is not queried at all.++ Wiped per company by store.delete_attachment_docs() on client-slot+ restore and fixture reset — drop-and-recreate, not a where-delete,+ because a surviving row there is one company's attachment visible to+ the next.++ Caveat for anyone auditing an existing install: before this+ collection existed, the ingest built its store with the bare+ ChromaDBStore() default rather than settings.vector_store_path, so+ wherever that differs from VECTOR_STORE_PATH the rows went to a+ different database than the API reads. In a container that directory+ is outside the data volume and goes with the container; on a+ non-container install with a stable CWD it persists as a stray+ <cwd>/chroma_db holding the plaintext of every attachment ever sent,+ which no wipe path reaches and an operator should delete by hand. The+ boot migration cannot see it either way and correctly reports zero.domain_aliases_source: openexecutive.knowledge.retriever.DOMAIN_ALIASESdedupe_note: Multi-domain chunks can fan out to multiple rows; the retriever dedupes by text before returning.upload_domains: |@@ -764,7 +793,19 @@ knowledge:external OER sources, and external_sources falls back to ["general"] for asource that declares no domains; widening BUILTIN too would fan unvettedthird-party material into every specialist's context. NOTION_WIKI and- RECENT_RESEARCH keep their existing filters.+ RECENT_RESEARCH keep their existing filters, and ATTACHMENTS is not+ queried at all.++ The property that makes all of this easy to get wrong: _with_general+ returns a falsy filter UNCHANGED, and ChromaDBStore.query builds a `where`+ clause only when the filter is truthy. So a retrieve with no domain filter+ and no specialist — every Executive-level turn, as opposed to the+ specialist fan-out — queries COMPANY with no `where` at all and matches+ EVERY domain, including values chosen precisely because no specialist maps+ to them. An unrecognised domain excludes nothing. That is what put inbound+ attachments in front of the Executive under "From your company documents",+ and it is why isolation belongs in the collection, never in a domain+ value.memory:episodic_db: ./episodic_memory.db@@ -2882,34 +2923,53 @@ integrations:extracted to Anthropic vision content blocks and forwarded to theExecutive in the same turn as the text. Inbound documents(PDF/DOCX/TXT/MD/CSV) have their text extracted and inlined into the- user message AND are indexed into the ChromaDB ``company_docs``- collection in a fire-and-forget background task, so attachments- surface in future RAG retrieval. Per-file cap 20 MB; extracted text+ user message AND are indexed into the ChromaDB+ ``inbound_attachments`` collection in a fire-and-forget background+ task. Per-file cap 20 MB; extracted texttruncated to 40 000 chars. Web chat exposes this through``POST /chat/upload`` (multipart) — capped at 5 files per turn.- Indexed under ``source_name="attachment:<bare filename>"`` and domain- ``general``. Both matter. The name is the chunk-id namespace and the- retrieval citation, and an attachment's filename is chosen by whoever- sent the message — unprefixed, an emailed ``strategy-2026.md`` would- upsert straight over the curated company document of that name, so- inbound content stays in its own namespace and its provenance is- visible in the ``[filename]`` citation. (``Path(...).name`` strips- directory components first.)-- The domain stays ``company_docs``, which is deliberately NOT one of the- specialist domains: these chunks match no domain filter and so do not- reach the Executive. Leaving them inert is a decision, not an oversight —- anyone who can attach a file in an integration channel would otherwise be- writing into every specialist's RAG context, and these rows have no- removal path (never written to docs/, so GET /documents does not list them- and DELETE /documents/{filename} 404s before reaching the store). Making- them retrievable needs its own change, with a delete path alongside it.+ Indexed under ``source_name="attachment:<bare filename>"``, domain+ ``attachment``, metadata ``type=attachment``. The name is the chunk-id+ namespace and the retrieval citation, and an attachment's filename is+ chosen by whoever sent the message — unprefixed, an inbound+ ``strategy-2026.md`` would upsert over the curated company document of+ that name, so inbound content stays in its own namespace and its+ provenance is visible. (``Path(...).name`` strips directory components+ first.) The prefix does NOT separate senders from each other: ids are+ md5 of the prefixed name alone, so two senders' ``notes.md`` collide.+ Inert while nothing reads the collection, and the first thing to fix if+ that changes.++ Isolation is the COLLECTION. ``inbound_attachments`` is the one+ collection ``retriever.retrieve`` never queries at all, so an attachment+ cannot resurface as company knowledge in a later, unrelated turn. It is+ still inlined into the turn that carried it, which is where it is useful.+ The domain value is belt-and-braces behind that: ``attachment`` is in+ neither UPLOAD_DOMAINS nor DOMAIN_ALIASES, and deliberately not+ ``general``, which ``_with_general`` would fan out to every specialist.++ What this replaced, because the reasoning was wrong and should not come+ back: the rows lived in ``company_docs`` under domain ``company_docs``,+ on the premise that a domain outside the specialist set matched no+ filter. It matched every one — the mechanism is written up once under+ knowledge.general_catch_all. They came back under "From your company+ documents", top-ranked and indistinguishable from a curated upload.+ ``loader.migrate_attachments_out_of_company_docs`` moves the+ legacy rows across on boot (write-then-delete: the store holds the only+ copy). Wiped per company by ``store.delete_attachment_docs()`` on+ client-slot restore and fixture reset.++ Attachment processing is roster-gated on Discord (``_is_rostered`` in+ ``on_message``): it used to run before ``_handle_message``'s gate, so an+ unrostered sender's file was downloaded and indexed before their message+ was dropped. There is still no operator surface listing these rows —+ ``GET /documents`` is a filesystem listing and attachments are never+ written to docs/.Passing the staging tempfile path as the identity was the #113 bug on thispath too: duplicate chunks on every re-send, and no filename any API call- could delete. The boot reconcile drops their orphans rather than- recovering them, there being no file on disk to recover from.+ could delete.broadcast_tools: |openexecutive.orchestrator.broadcast_tools — two new tools exposedto the Executive alongside the existing per-Person DM tools:diff --git a/packages/core/openexecutive/architecture/prebuilt/clients.json b/packages/core/openexecutive/architecture/prebuilt/clients.jsonindex b7a3a4fb..c360733b 100644--- a/packages/core/openexecutive/architecture/prebuilt/clients.json+++ b/packages/core/openexecutive/architecture/prebuilt/clients.json@@ -1,7 +1,7 @@{"section_id": "clients","title": "Client Companies (Slots)",- "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* \u2014 save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored \u2014 client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB \u2014 chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults \u2014 departments, onboarding templates, principal briefs, cadences \u2014 so the new client's Today page works without a restart. That wipe covers the **derived caches** \u2014 `briefing_narrative` and `person_insights` \u2014 as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active \u2014 recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase \u2014 aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one \u2014 a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` \u2014 a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup \u2014 a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe \u2014 on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments \u2014 so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent \u2014 the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent \u2014 unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** \u2014 your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact \u2014 editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** \u2014 no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** \u2014 a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones \u2014 single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** \u2014 then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am \u2014 rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings \u2192 advanced tools.",+ "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. The isolated per-company collections are wiped in the same pass — `recent_research`, `notion_wiki`, and `inbound_attachments` (attachments are dropped and recreated rather than re-indexed: they have no source directory to rebuild from, and a row surviving a slot switch would be one client's attachment visible to the next). Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, onboarding templates, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.","mermaid": "flowchart TD\n UI[\"/clients page (Settings)\"] -->|\"activate slug\"| Lock[\"destructive-op lock (shared with fixtures)\"]\n Lock --> SaveBack[\"save-back: VACUUM INTO state.db + copy profile / docs / skills / mcp\"]\n SaveBack --> SlotA[(\"slot A dir\")]\n SlotB[(\"slot B dir\")] --> Restore[\"restore: sqlite backup API + artifact replacement\"]\n Lock --> Restore\n Restore --> Live[(\"live company context\")]\n Restore --> Chroma[\"reindex company_docs + skills\"]\n Restore -.stable workspace.-> Honcho[\"Honcho peer memory\"]\n Live --> Scheduler[\"scheduler: only the ACTIVE client's actions fire\"]",- "generated_at": "2026-09-07T00:00:00Z"-}\ No newline at end of file+ "generated_at": "2026-09-16T12:33:27.680504+00:00"+}diff --git a/packages/core/openexecutive/architecture/prebuilt/integrations.json b/packages/core/openexecutive/architecture/prebuilt/integrations.jsonindex 0d24f7f6..a48ca524 100644--- a/packages/core/openexecutive/architecture/prebuilt/integrations.json+++ b/packages/core/openexecutive/architecture/prebuilt/integrations.json@@ -1,7 +1,7 @@{"section_id": "integrations","title": "Integrations",- "markdown": "External channels connect callers to the Executive. Each inbound adapter resolves the sender to a Person via `find_person_by_{slack,discord,telegram,email}_id` and threads `person_id` into `Executive.chat()`.\n\n### Inbound channels\n\n- **Slack** (`integrations.slack_bot`) — Bolt socket-mode; responds to `@mention`s, DMs, and thread continuations.\n- **Discord** (`integrations.discord_bot`) — discord.py gateway embedded in the lifespan; per-thread auto-titling, session-scoped memory, author attribution, configurable `@mention` thread promotion.\n- **Telegram** — webhook gating + per-chat history.\n- **Google Chat** — webhook + service-account auth.\n- **Email** (`integrations.email_poller`) — IMAP poll loop; strips Reply-To, filters auto-replies.\n\nSlack, Discord, and Telegram are roster-gated on inbound: an unrostered sender's message is silently dropped (`details.outcome=\"rejected_unknown_sender\"`). Email is not inbound-gated — non-roster mail flows through with a `[POLICY]` notice so triage can classify it. Slack/Discord thread continuations pass the shared `integrations.response_gate` (utility-fast model, biased toward replying).\n\n### Attachments\n\n`integrations.attachments` handles web chat, Discord, and Telegram. Images become Anthropic vision blocks; documents (PDF/DOCX/TXT/MD/CSV) are inlined and indexed into the ChromaDB `company_docs` collection for future RAG. 20 MB/file cap; web chat uses `POST /chat/upload`.\n\nIndexed chunks are keyed on `attachment:<bare filename>`. An attachment's name is chosen by whoever sent the message, and the name is the chunk-id namespace — unprefixed, an emailed `strategy-2026.md` would upsert straight over the curated company document of that name. The prefix keeps inbound content in its own namespace and makes its provenance visible in the `[filename]` retrieval citation.\n\nThey carry the domain `company_docs`, which is deliberately **not** one of the specialist domains: the chunks match no domain filter, so they do not currently reach the Executive. Anyone who can attach a file in an integration channel would otherwise be writing into every specialist's context, and these rows have no removal path — they are never written to `company/docs/`, so `GET /documents` does not list them and `DELETE /documents/{filename}` 404s before reaching the store. Making them retrievable is a trust-boundary change that needs a delete path alongside it.\n\n### MCP gateway & outbound\n\nMCP runs in **both directions**. As a *client*, `orchestrator.mcp_gateway.MCPGateway` proxies MCP servers (Gmail, Calendar, Drive — whatever `mcp_servers.json` configures) as Executive tools, with egress gating on Gmail recipients, Calendar attendees, and Drive share grantees against the roster (and a refusal of public / whole-domain Drive sharing). The Google Workspace server (`workspace-mcp`) behind those Gmail/Calendar/Drive tools runs **co-located inside the API** as a stdio child of the gateway — fitting the single-tenant model (one install = one company = one exec Google account), so there's no separate service to operate. It's baked into the API image and launched by `docker/workspace-mcp-launch.sh`, which selects single-user OAuth (token persisted at `/data/google_credentials`) or service-account domain-wide delegation from `GWORKSPACE_AUTH_MODE`. The gateway forwards the Google secrets to the child via `_FORWARDED_ENV_VARS`. As a *server*, `openexecutive.mcp_server` exposes OE's own company context and specialist council to external MCP clients at `/mcp` — the inverse direction; see the dedicated **MCP Server** section. The gateway launches extensible-mcp as a `uvx` subprocess whose fastembed tool-search index uses an embedding model baked into the API image and loaded offline, so it no longer re-downloads that model from the Hugging Face Hub on every cold start. Because the MCP stdio client does not inherit the parent environment, `MCPGateway.start()` explicitly forwards the embedding-cache/offline env vars (`FASTEMBED_CACHE_PATH`, `HF_HUB_OFFLINE`, …) into the child. Outbound tools: per-Person DMs (`send_slack_dm`, `send_discord_dm`, `send_telegram_message`) plus room-targeted `send_department_message` and `send_company_broadcast`. The per-Person DMs are additionally rate-limited and de-duplicated by the outbound anti-spam guard (below).\n\n### Outbound anti-spam guard\n\nEvery per-Person DM passes a deterministic guard (`orchestrator.outbound_guard.check_outbound_allowed`) after the roster gate and recipient-id recovery but before the network send — the single chokepoint **all** proactive DM paths reach (ad-hoc chat sends, the scheduler's followup/nudge dispatch, principal-brief delivery, the reflection turn, and research-finding routing). On a violation it returns a human-readable reason and the handler **suppresses** the send (`{\"status\":\"suppressed\",\"reason\":…}`), writes a `tool_invocation` audit row with `suppressed=true`, and writes **no** `done` activity row — so a blocked attempt never counts toward its own rate cap, and the Executive can read the reason and hold or `schedule_followup` for the recipient's next window. Three controls: **content dedup** (a near-identical message — whitespace/case-normalized, first 160 chars — already sent to the same recipient within `OUTBOUND_DEDUP_WINDOW_MINUTES`, default 360); a **per-recipient rate cap** (`OUTBOUND_MAX_PER_RECIPIENT_PER_WINDOW`, default 5, over `OUTBOUND_RATE_WINDOW_MINUTES`, default 60); and **quiet hours / availability** (`OUTBOUND_RESPECT_QUIET_HOURS`, default on — refuse while the recipient is on leave or outside their `people.channel` availability windows, surfacing the next open window). Delivery history is read from the existing `status='done'` `scheduled_actions` rows (`episodic.recent_sends_for_channel_ref`), so there is no new table. The guard is **fail-open**: any internal lookup error returns \"allow\", so it can never turn a working send into a crash or a silently-dropped message. Principal briefs and the internal heartbeat kinds use the `__internal__` channel and never reach these handlers, so they are unaffected.\n\n### Calendar & Google Meet\n\nThe Executive books meetings through two typed tools over the Calendar MCP. `create_calendar_event` schedules a **future** meeting (propose→approve by default, or auto-execute once that decision class is promoted) and may be used proactively when a stalled goal warrants a sync. `create_instant_meeting` spins up an **impromptu call starting now**, auto-executing without the approval step and skipping the business-hours/horizon caps, so the Executive can hand back a join link immediately. Both attach a **Google Meet** link by default (`add_google_meet`; opt out for in-person), parsed from the created event's `conferenceData` and surfaced to the caller plus persisted on the decision ledger. Either way the caps that matter still hold — roster membership, principal-protection, max attendees, and a daily booking ceiling.\n\n**Around-the-meeting participation.** The Executive doesn't join the call as a live voice; instead, on every successful booking it schedules a best-effort post-meeting follow-up (~5 min after the end) that DMs a human attendee asking for a quick recap — key decisions and action items. The reply flows back through the same cross-session DM context linkage described below, so the Executive can act on it (summarize, follow up) in a later turn. No meeting-transcript or Drive integration is required.\n\n### Cross-session DM context\n\nWhen the principal says \"DM Alex about X\" in one session, OE sends the DM and — if a live conversation is active — records an `outbound_context` linkage row (recipient, full outbound text, originating session id). Email is covered too but recorded one layer deeper — there is no `send_email` tool, so the linkage is written in `orchestrator.mcp_gateway` after a successful `google_workspace__send_gmail_message`, one row per `to`/`cc` recipient keyed by the bare lowercased address (OE's own address skipped). When Alex later replies on the 1:1 DM path — or by email — the shared helper `integrations.inbound_hydration.hydrate_user_message` (called by the Discord, Telegram, and Slack handlers, and by the email poller keyed on the sender address) looks up the most-recent `open` linkage for that sender within 72h and prepends an `<outbound_reply_context>` block — the outbound text plus a backstory excerpt from the originating session — to the message handed to `Executive.chat()`. So OE knows what the reply is about instead of starting from an empty per-person session. The block lands in the user turn (caching rule) and is injected into a copy only — the pristine reply is persisted to history. The linkage is one-shot (consumed on first matched reply, race-safe) so an unrelated later DM isn't re-hydrated. This is deterministic and independent of the per-person `peer_memory` (Honcho) layer.",- "mermaid": "flowchart TD\n Channels[\"Slack / Discord<br/>Telegram / GChat / Email\"]\n Resolve[\"find_person_by_*_id\"]\n Gate[\"roster gate\"]\n Drop[\"drop unrostered\"]\n Exec[\"Executive.chat()\"]\n Attach[\"attachments<br/>(vision / company_docs)\"]\n MCP[\"MCP gateway\"]\n Guard[\"outbound anti-spam guard<br/>(dedup / rate cap / quiet hours)\"]\n Out[\"DM / department<br/>/ broadcast tools\"]\n Channels --> Resolve\n Resolve --> Gate\n Gate -- \"unknown sender\" --> Drop\n Gate -- \"Person\" --> Exec\n Channels --> Attach\n Attach --> Exec\n Exec --> MCP\n Exec --> Guard\n Guard -- \"suppress\" --> Drop\n Guard -- \"allow\" --> Out\n Out --> Channels\n class Channels entry\n class Resolve compute\n class Gate compute\n class Drop external\n class Exec hot\n class Attach compute\n class MCP external\n class Guard compute\n class Out compute",- "generated_at": "2026-09-16T10:27:41.699684+00:00"+ "markdown": "External channels connect callers to the Executive. Each inbound adapter resolves the sender to a Person via `find_person_by_{slack,discord,telegram,email}_id` and threads `person_id` into `Executive.chat()`.\n\n### Inbound channels\n\n- **Slack** (`integrations.slack_bot`) — Bolt socket-mode; responds to `@mention`s, DMs, and thread continuations.\n- **Discord** (`integrations.discord_bot`) — discord.py gateway embedded in the lifespan; per-thread auto-titling, session-scoped memory, author attribution, configurable `@mention` thread promotion.\n- **Telegram** — webhook gating + per-chat history.\n- **Google Chat** — webhook + service-account auth.\n- **Email** (`integrations.email_poller`) — IMAP poll loop; strips Reply-To, filters auto-replies.\n\nSlack, Discord, and Telegram are roster-gated on inbound: an unrostered sender's message is silently dropped (`details.outcome=\"rejected_unknown_sender\"`). Email is not inbound-gated — non-roster mail flows through with a `[POLICY]` notice so triage can classify it. Slack/Discord thread continuations pass the shared `integrations.response_gate` (utility-fast model, biased toward replying).\n\n### Attachments\n\n`integrations.attachments` handles web chat, Discord, and Telegram. Images become Anthropic vision blocks; documents (PDF/DOCX/TXT/MD/CSV) are inlined into the turn that carried them and indexed into the ChromaDB `inbound_attachments` collection. 20 MB/file cap; web chat uses `POST /chat/upload`.\n\nIndexed chunks are keyed on `attachment:<bare filename>` and tagged `type=attachment`. An attachment's name is chosen by whoever sent the message and the name is the chunk-id namespace, so without the prefix an inbound `strategy-2026.md` would upsert over the curated company document of that name. The prefix separates inbound content from curated uploads and keeps provenance visible; it does not separate senders from one another.\n\nIsolation is the **collection**: `retriever.retrieve` never queries `inbound_attachments` at all, so an attachment cannot resurface as company knowledge in a later, unrelated turn. Attachment processing is roster-gated on Discord too — it previously ran before the gate, so an unrostered sender's file was downloaded and indexed before their message was dropped. These rows still have no operator surface: they are never written to `company/docs/`, so `GET /documents` does not list them.\n\nThis replaced a domain-based scheme that did not work. The chunks lived in `company_docs` under a domain outside the specialist set, on the premise that an unrecognised domain matched no filter. It matched every one — `ChromaDBStore.query` attaches a `where` clause only when a domain filter is present, and an Executive-level retrieval passes none — so attachments came back under “From your company documents”, top-ranked and indistinguishable from a curated upload. Legacy rows are migrated across on boot.\n\n### MCP gateway & outbound\n\nMCP runs in **both directions**. As a *client*, `orchestrator.mcp_gateway.MCPGateway` proxies MCP servers (Gmail, Calendar, Drive — whatever `mcp_servers.json` configures) as Executive tools, with egress gating on Gmail recipients, Calendar attendees, and Drive share grantees against the roster (and a refusal of public / whole-domain Drive sharing). The Google Workspace server (`workspace-mcp`) behind those Gmail/Calendar/Drive tools runs **co-located inside the API** as a stdio child of the gateway — fitting the single-tenant model (one install = one company = one exec Google account), so there's no separate service to operate. It's baked into the API image and launched by `docker/workspace-mcp-launch.sh`, which selects single-user OAuth (token persisted at `/data/google_credentials`) or service-account domain-wide delegation from `GWORKSPACE_AUTH_MODE`. The gateway forwards the Google secrets to the child via `_FORWARDED_ENV_VARS`. As a *server*, `openexecutive.mcp_server` exposes OE's own company context and specialist council to external MCP clients at `/mcp` — the inverse direction; see the dedicated **MCP Server** section. The gateway launches extensible-mcp as a `uvx` subprocess whose fastembed tool-search index uses an embedding model baked into the API image and loaded offline, so it no longer re-downloads that model from the Hugging Face Hub on every cold start. Because the MCP stdio client does not inherit the parent environment, `MCPGateway.start()` explicitly forwards the embedding-cache/offline env vars (`FASTEMBED_CACHE_PATH`, `HF_HUB_OFFLINE`, …) into the child. Outbound tools: per-Person DMs (`send_slack_dm`, `send_discord_dm`, `send_telegram_message`) plus room-targeted `send_department_message` and `send_company_broadcast`. The per-Person DMs are additionally rate-limited and de-duplicated by the outbound anti-spam guard (below).\n\n### Outbound anti-spam guard\n\nEvery per-Person DM passes a deterministic guard (`orchestrator.outbound_guard.check_outbound_allowed`) after the roster gate and recipient-id recovery but before the network send — the single chokepoint **all** proactive DM paths reach (ad-hoc chat sends, the scheduler's followup/nudge dispatch, principal-brief delivery, the reflection turn, and research-finding routing). On a violation it returns a human-readable reason and the handler **suppresses** the send (`{\"status\":\"suppressed\",\"reason\":…}`), writes a `tool_invocation` audit row with `suppressed=true`, and writes **no** `done` activity row — so a blocked attempt never counts toward its own rate cap, and the Executive can read the reason and hold or `schedule_followup` for the recipient's next window. Three controls: **content dedup** (a near-identical message — whitespace/case-normalized, first 160 chars — already sent to the same recipient within `OUTBOUND_DEDUP_WINDOW_MINUTES`, default 360); a **per-recipient rate cap** (`OUTBOUND_MAX_PER_RECIPIENT_PER_WINDOW`, default 5, over `OUTBOUND_RATE_WINDOW_MINUTES`, default 60); and **quiet hours / availability** (`OUTBOUND_RESPECT_QUIET_HOURS`, default on — refuse while the recipient is on leave or outside their `people.channel` availability windows, surfacing the next open window). Delivery history is read from the existing `status='done'` `scheduled_actions` rows (`episodic.recent_sends_for_channel_ref`), so there is no new table. The guard is **fail-open**: any internal lookup error returns \"allow\", so it can never turn a working send into a crash or a silently-dropped message. Principal briefs and the internal heartbeat kinds use the `__internal__` channel and never reach these handlers, so they are unaffected.\n\n### Calendar & Google Meet\n\nThe Executive books meetings through two typed tools over the Calendar MCP. `create_calendar_event` schedules a **future** meeting (propose→approve by default, or auto-execute once that decision class is promoted) and may be used proactively when a stalled goal warrants a sync. `create_instant_meeting` spins up an **impromptu call starting now**, auto-executing without the approval step and skipping the business-hours/horizon caps, so the Executive can hand back a join link immediately. Both attach a **Google Meet** link by default (`add_google_meet`; opt out for in-person), parsed from the created event's `conferenceData` and surfaced to the caller plus persisted on the decision ledger. Either way the caps that matter still hold — roster membership, principal-protection, max attendees, and a daily booking ceiling.\n\n**Around-the-meeting participation.** The Executive doesn't join the call as a live voice; instead, on every successful booking it schedules a best-effort post-meeting follow-up (~5 min after the end) that DMs a human attendee asking for a quick recap — key decisions and action items. The reply flows back through the same cross-session DM context linkage described below, so the Executive can act on it (summarize, follow up) in a later turn. No meeting-transcript or Drive integration is required.\n\n### Cross-session DM context\n\nWhen the principal says \"DM Alex about X\" in one session, OE sends the DM and — if a live conversation is active — records an `outbound_context` linkage row (recipient, full outbound text, originating session id). Email is covered too but recorded one layer deeper — there is no `send_email` tool, so the linkage is written in `orchestrator.mcp_gateway` after a successful `google_workspace__send_gmail_message`, one row per `to`/`cc` recipient keyed by the bare lowercased address (OE's own address skipped). When Alex later replies on the 1:1 DM path — or by email — the shared helper `integrations.inbound_hydration.hydrate_user_message` (called by the Discord, Telegram, and Slack handlers, and by the email poller keyed on the sender address) looks up the most-recent `open` linkage for that sender within 72h and prepends an `<outbound_reply_context>` block — the outbound text plus a backstory excerpt from the originating session — to the message handed to `Executive.chat()`. So OE knows what the reply is about instead of starting from an empty per-person session. The block lands in the user turn (caching rule) and is injected into a copy only — the pristine reply is persisted to history. The linkage is one-shot (consumed on first matched reply, race-safe) so an unrelated later DM isn't re-hydrated. This is deterministic and independent of the per-person `peer_memory` (Honcho) layer.",+ "mermaid": "flowchart TD\n Channels[\"Slack / Discord<br/>Telegram / GChat / Email\"]\n Resolve[\"find_person_by_*_id\"]\n Gate[\"roster gate\"]\n Drop[\"drop unrostered\"]\n Exec[\"Executive.chat()\"]\n Attach[\"attachments<br/>(vision / inbound_attachments)\"]\n MCP[\"MCP gateway\"]\n Guard[\"outbound anti-spam guard<br/>(dedup / rate cap / quiet hours)\"]\n Out[\"DM / department<br/>/ broadcast tools\"]\n Channels --> Resolve\n Resolve --> Gate\n Gate -- \"unknown sender\" --> Drop\n Gate -- \"Person\" --> Exec\n Gate --> Attach\n Attach --> Exec\n Exec --> MCP\n Exec --> Guard\n Guard -- \"suppress\" --> Drop\n Guard -- \"allow\" --> Out\n Out --> Channels\n class Channels entry\n class Resolve compute\n class Gate compute\n class Drop external\n class Exec hot\n class Attach compute\n class MCP external\n class Guard compute\n class Out compute",+ "generated_at": "2026-09-16T12:39:20.262413+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/rag.json b/packages/core/openexecutive/architecture/prebuilt/rag.jsonindex b23e9b3b..d29e3fe0 100644--- a/packages/core/openexecutive/architecture/prebuilt/rag.json+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json@@ -1,7 +1,7 @@{"section_id": "rag","title": "Knowledge & RAG",- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Five collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Chat/email attachments share the collection but are namespaced `attachment:<name>`, since the sender picks that name and an unprefixed one would overwrite the curated document it collides with; they also carry a non-specialist domain, so they are not retrieved (see Integrations).\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",- "mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class Failures storage\n class Research storage\n class Inject hot",- "generated_at": "2026-09-16T10:00:04.693907+00:00"+ "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Six collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",+ "mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Attach[\"integrations.attachments\"] --> Attachments[(ATTACHMENTS<br/>never queried)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class Failures storage\n class Research storage\n class Attachments storage\n class Attach compute\n class Inject hot",+ "generated_at": "2026-09-16T12:26:36.985695+00:00"}diff --git a/packages/core/openexecutive/cli/fixture_loader.py b/packages/core/openexecutive/cli/fixture_loader.pyindex 82885d5c..7c4b1053 100644--- a/packages/core/openexecutive/cli/fixture_loader.py+++ b/packages/core/openexecutive/cli/fixture_loader.py@@ -460,6 +460,7 @@ async def _apply_state_from_source(source_dir: Path, settings: Any) -> dict[str,where={"type": "recent_research"},)store.delete_notion_docs()+ store.delete_attachment_docs()from openexecutive.knowledge.notion_sync import reset_local_statereset_local_state(profile_path=settings.company_profile_path)@@ -664,6 +665,7 @@ async def reset_all_state(where={"type": "recent_research"},)store.delete_notion_docs()+ store.delete_attachment_docs()from openexecutive.knowledge.notion_sync import reset_local_statereset_local_state(profile_path=settings.company_profile_path)diff --git a/packages/core/openexecutive/clients/slots.py b/packages/core/openexecutive/clients/slots.pyindex b8a92418..0db5913d 100644--- a/packages/core/openexecutive/clients/slots.py+++ b/packages/core/openexecutive/clients/slots.py@@ -652,6 +652,9 @@ async def _rebuild_vector_state(settings: Any, app_state: Any | None) -> int:where={"type": "recent_research"},)store.delete_notion_docs()+ # Inbound attachments are per-company too, and no longer swept by+ # delete_company_docs above now that they live in their own collection.+ store.delete_attachment_docs()from openexecutive.knowledge.notion_sync import reset_local_statereset_local_state(profile_path=settings.company_profile_path)diff --git a/packages/core/openexecutive/integrations/attachments.py b/packages/core/openexecutive/integrations/attachments.pyindex 8be9a443..b482fbc6 100644--- a/packages/core/openexecutive/integrations/attachments.py+++ b/packages/core/openexecutive/integrations/attachments.py@@ -150,7 +150,7 @@ def _extract_text(data: bytes, filename: str) -> str:def _schedule_ingest(data: bytes, filename: str) -> None:- """Fire-and-forget ChromaDB ingest of *data* as a new company document.+ """Fire-and-forget ChromaDB ingest of *data* into the attachment collection.Uses the same strong-ref pattern as ``_thread_rename_tasks`` indiscord_bot to prevent GC cancellation mid-flight.@@ -158,10 +158,21 @@ def _schedule_ingest(data: bytes, filename: str) -> None:async def _run() -> None:suffix = _suffix_from_filename(filename)try:- from openexecutive.knowledge.loader import ingest_file+ from openexecutive.config import get_settings+ from openexecutive.knowledge.loader import (+ ATTACHMENT_DOMAIN,+ ATTACHMENT_SOURCE_PREFIX,+ ingest_file,+ )from openexecutive.knowledge.store import ChromaDBStore- store = ChromaDBStore()+ # The configured store, not the bare default. `ChromaDBStore()`+ # falls back to a RELATIVE "./chroma_db", resolved against the+ # process CWD — so with VECTOR_STORE_PATH set (every container+ # deployment) this wrote to a second database nothing reads,+ # off the data volume and gone with the container. It happened+ # to work in local dev only because CWD is the repo root there.+ store = ChromaDBStore(persist_directory=get_settings().vector_store_path)with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:tmp.write(data)tmp_path = Path(tmp.name)@@ -172,31 +183,34 @@ def _schedule_ingest(data: bytes, filename: str) -> None:# on every re-send and leaves chunks no API call can delete.## It is PREFIXED, and stripped to a bare name, because an- # attachment name is chosen by whoever sent the message. The- # name is the chunk-id namespace, so an unprefixed- # "strategy-2026.md" arriving by email would upsert straight- # over the curated company document of that name. The prefix- # keeps inbound content in its own namespace and makes the- # provenance visible in the `[filename]` retrieval citation —- # the same reason Notion and research artifacts are isolated.+ # attachment name is chosen by whoever sent the message and+ # the name is the chunk-id namespace: unprefixed, an inbound+ # "strategy-2026.md" would upsert over the curated company+ # document of that name. The prefix separates inbound content+ # from curated uploads, and makes provenance visible in the+ # `[filename]` citation. It does NOT separate senders from+ # each other — ids are md5 of the prefixed name alone, so two+ # senders' "notes.md" still collide. Harmless while nothing+ # reads this collection; it is the first thing to fix if+ # anything ever does.+ #+ # Isolation is the COLLECTION. These rows go to+ # ATTACHMENT_COLLECTION, which `retriever.retrieve` never+ # queries, so an attachment cannot resurface as company+ # knowledge in a later, unrelated turn.#- # `domain` stays "company_docs", which is NOT one of the- # specialist domains — so these chunks match no specialist's- # domain filter and never reach the Executive's context. That- # is a known gap, left deliberately: anyone who can attach a- # file in an integration channel would otherwise be writing- # into every specialist's RAG context, and these rows have no- # removal path at all (they are never written to- # `company/docs/`, so `GET /documents` does not list them and- # `DELETE /documents/{filename}` 404s before reaching the- # store). Making them retrievable is a trust-boundary decision- # that needs its own change, with a delete path alongside it —- # not a side effect of fixing the chunk-id bug below.+ # What this replaced, so nobody reinstates it: the rows used+ # to land in COMPANY_COLLECTION under a non-specialist domain,+ # which excluded them from nothing — an unfiltered retrieval+ # has no `where` clause at all. See knowledge.general_catch_all+ # in architecture-facts.yaml.count = await ingest_file(tmp_path,store,- domain="company_docs",- source_name=f"attachment:{Path(filename).name}",+ domain=ATTACHMENT_DOMAIN,+ collection=ChromaDBStore.ATTACHMENT_COLLECTION,+ source_name=f"{ATTACHMENT_SOURCE_PREFIX}{Path(filename).name}",+ extra_metadata={"type": "attachment"},)logger.info("attachments: indexed %d chunks from %s into ChromaDB",diff --git a/packages/core/openexecutive/integrations/discord_bot.py b/packages/core/openexecutive/integrations/discord_bot.pyindex 07e80e8c..2786a19d 100644--- a/packages/core/openexecutive/integrations/discord_bot.py+++ b/packages/core/openexecutive/integrations/discord_bot.py@@ -524,6 +524,27 @@ def _schedule_thread_rename(task.add_done_callback(_thread_rename_tasks.discard)+def _is_rostered(discord_user_id: str) -> bool:+ """Whether this Discord user maps to a Person on the roster.++ The same lookup ``_handle_message``'s roster gate makes, exposed so+ ``on_message`` can skip work it would otherwise do *before* that gate+ runs. Kept as a boolean rather than returning the Person: the caller+ only needs the decision, and the gate below still does its own lookup+ so its audit rows keep their existing shape.+ """+ if not discord_user_id:+ return False+ from openexecutive.people.store import find_person_by_discord_id++ try:+ return find_person_by_discord_id(discord_user_id) is not None+ except Exception:+ # A roster lookup that errors must not be read as "rostered".+ logger.exception("Discord: roster lookup failed for user=%s", discord_user_id)+ return False++async def _handle_message(text: str,discord_user_id: str,@@ -539,6 +560,7 @@ async def _handle_message(gate_eligible: bool = False,bot_display_name: str | None = None,attachment_blocks: list[dict] | None = None,+ attachment_count: int = 0,co_present_discord_user_ids: list[str] | None = None,response_router: Callable[[str], Awaitable[MentionRouteResult]] | None = None,) -> None:@@ -553,6 +575,11 @@ async def _handle_message(by process_attachments(). Text-extracted document content is expected toalready be prepended to `text` by the caller.+ `attachment_count` is how many files the message carried, recorded in the+ audit row. It is passed separately from `attachment_blocks` because the+ caller skips attachment processing for an unrostered sender — that is+ exactly the case where /audit should still show a file was sent.+`response_router`, if provided, is awaited with the full reply textAFTER ``executive.chat`` returns and BEFORE the chunked send loop.The returned :class:`MentionRouteResult` selects the actual ``send_fn``@@ -576,6 +603,7 @@ async def _handle_message("message_id": message_id,"thread_id": thread_id,"text_len": len(text),+ "attachments": attachment_count,},)@@ -1237,8 +1265,20 @@ def create_discord_bot():# Process file attachments — download, extract text / build image blocks.# Must run BEFORE the send_fn closure is called so we can prepend# extracted text to `cleaned` and pass image_blocks through.+ #+ # Roster-gated separately here, because that "before" put it before+ # _handle_message's gate too: an unrostered sender's message was+ # dropped, but not until after we had downloaded their file and+ # indexed its text.+ #+ # The message still goes to _handle_message, so a rejected attempt+ # still produces both the integration_inbound row and the+ # rejected_unknown_sender row. What changes is that row's preview:+ # extracted attachment text used to be prepended to `cleaned` and so+ # appeared in it. Not extracting an unrostered sender's file is the+ # point, and `attachments` below records that one was sent.att_image_blocks: list[dict] = []- if message.attachments:+ if message.attachments and _is_rostered(discord_user_id):try:from openexecutive.integrations.attachments import (AttachmentItem,@@ -1310,6 +1350,7 @@ def create_discord_bot():# replies that arrive in the same DM or thread channel.await _handle_message(text=cleaned,+ attachment_count=len(message.attachments or []),discord_user_id=discord_user_id,discord_channel=discord_channel,message_id=message_id,diff --git a/packages/core/openexecutive/knowledge/loader.py b/packages/core/openexecutive/knowledge/loader.pyindex 426c4728..807fd862 100644--- a/packages/core/openexecutive/knowledge/loader.py+++ b/packages/core/openexecutive/knowledge/loader.py@@ -34,6 +34,28 @@ GENERAL_DOMAIN = "general"# silently index the document where no specialist can ever retrieve it.UPLOAD_DOMAINS: frozenset[str] = frozenset(DOMAIN_MAP) | {GENERAL_DOMAIN}+# Chunk-id namespace for a file attached in an integration channel. The+# sender picks the filename and the filename is the id namespace, so an+# unprefixed ``strategy-2026.md`` would upsert over whatever else carries+# that name. Shared between the write path+# (``integrations.attachments``) and the migration below, which has to+# recognise exactly what the write path produced.+ATTACHMENT_SOURCE_PREFIX = "attachment:"++# Domain tag on attachment chunks. Isolation is the collection+# (``ChromaDBStore.ATTACHMENT_COLLECTION``), never this value — but if+# anything ever does query that collection, this keeps the default+# "not retrieved": it is in neither UPLOAD_DOMAINS nor DOMAIN_ALIASES, and+# deliberately NOT ``general``, which ``retriever._with_general`` would fan+# out to every specialist.+ATTACHMENT_DOMAIN = "attachment"++# What the pre-isolation attachment path wrote into ``domain``. Only the+# boot migration reads it, to tell its own legacy rows from a curated+# upload that merely happens to be named with the prefix. UPLOAD_DOMAINS+# never accepts this value, so nothing uploaded through the API carries it.+_LEGACY_ATTACHMENT_DOMAIN = "company_docs"+def chunk_text(text: str, chunk_size: int = 512, overlap: int = 50) -> list[str]:words = text.split()@@ -143,6 +165,7 @@ async def ingest_file(collection: str = ChromaDBStore.COMPANY_COLLECTION,*,source_name: str | None = None,+ extra_metadata: dict[str, Any] | None = None,) -> int:"""Index a file on disk into a knowledge collection.@@ -159,6 +182,11 @@ async def ingest_file(fixture-loaded ``plan.md`` on the same ids instead of duplicating eachother, and matches how ``DELETE`` and ``list_company_docs`` already treatfilename as the document's identity.++ ``extra_metadata`` is merged into every chunk, mirroring+ ``ingest_text_sync``. It is how a collection gets a ``type`` tag it can+ later be deleted by: Chroma's ``where`` matches exact values only, so a+ tag is the difference between a one-call delete and a full metadata scan."""text = extract_text_from_file(path)if not text.strip():@@ -175,6 +203,7 @@ async def ingest_file("filename": name,"source": name,"chunk_index": i,+ **(extra_metadata or {}),}for i in range(len(chunks))]@@ -401,6 +430,143 @@ async def reconcile_company_docs(return deleted, indexed+def _is_attachment_row(metadata: dict[str, Any]) -> bool:+ """True when a COMPANY row was written by the attachment path.++ The prefix alone is not enough. A colon is legal in a filename and+ ``POST /documents`` passes one through, so a curated upload can be called+ ``attachment:q4-plan.md`` — matching on the name alone would migrate a+ real company document out of the collection it belongs in, and (because+ the file is still on disk) the boot reconcile would re-index it as+ ``general`` on the way back, widening it to every specialist. So the name+ has to be corroborated by ``domain="company_docs"``, the value the old+ attachment path always wrote and the one value ``UPLOAD_DOMAINS`` will+ never accept from an upload.++ ``type="attachment"`` is checked first as defence in depth: this change+ introduces the tag, so no shipped build ever wrote one into COMPANY, but+ a row carrying it is unambiguously ours.++ ``startswith``, not ``in`` — ``attachments-policy.md`` is a document about+ attachments, not an attachment.+ """+ if metadata.get("type") == "attachment":+ return True+ if metadata.get("domain") != _LEGACY_ATTACHMENT_DOMAIN:+ return False+ return any(+ str(metadata.get(key) or "").startswith(ATTACHMENT_SOURCE_PREFIX)+ for key in ("filename", "source")+ )+++def migrate_attachments_out_of_company_docs(store: ChromaDBStore) -> int:+ """Move attachment chunks from COMPANY into the isolated collection.++ Attachment rows used to be written into ``company_docs`` and kept out of+ retrieval by a domain outside the specialist set, which never excluded+ them (see knowledge.general_catch_all in architecture-facts.yaml).+ Isolation is now the collection, and the rows already in COMPANY have to+ follow.++ Returns the number of chunks actually removed from COMPANY — not the+ number attempted. A row that was copied but not deleted is still+ retrievable, so reporting it as moved would announce the leak as closed+ while it is open.++ Idempotent: ids are reused verbatim, an id already present in the+ destination is left alone, and once a run completes the scan that+ precedes it finds nothing.++ Synchronous on purpose. Every step here blocks — the metadata scan, the+ text fetch, the embedding pass inside ``add_documents`` — so the caller+ has to put it on a thread rather than merely scheduling it on the event+ loop, which would defer the stall without avoiding it.++ A note for anyone reading a zero on an install that certainly received+ attachments: before this change the ingest path built its store with the+ bare ``ChromaDBStore()`` default rather than ``settings.vector_store_path``,+ so wherever those differ the rows went to a different database than the+ one the API reads. In a container that directory is outside the data+ volume and goes with the container; elsewhere it persists as a stray+ ``<cwd>/chroma_db`` that no wipe path reaches and an operator should+ remove by hand. Either way it is unreachable from here, and zero is the+ honest answer rather than a failure.+ """+ candidates = [+ chunk_id+ for chunk_id, metadata in store.iter_chunk_metadata(+ ChromaDBStore.COMPANY_COLLECTION+ )+ if _is_attachment_row(metadata)+ ]+ if not candidates:+ return 0++ rows = store.get_documents_by_ids(ChromaDBStore.COMPANY_COLLECTION, candidates)+ if not rows:+ # The scan found rows and the fetch returned none. Those two cannot+ # both be right, and `get_documents_by_ids` reports a read failure the+ # same way it reports an empty result — so say so rather than letting+ # a broken read look like a clean store.+ logger.error(+ "attachment migration: %d row(s) matched but none could be read "+ "from %s; leaving them in place",+ len(candidates),+ ChromaDBStore.COMPANY_COLLECTION,+ )+ return 0++ # Ids collide by design: they are md5 of the same source name on both+ # sides. A row already in the destination is a NEWER copy written by the+ # post-fix path, so upserting the COMPANY copy over it would restore+ # superseded text. Skip those and just drop the stale original.+ already_there = {+ chunk_id+ for chunk_id, _, _ in store.get_documents_by_ids(+ ChromaDBStore.ATTACHMENT_COLLECTION, [cid for cid, _, _ in rows]+ )+ }+ fresh = [row for row in rows if row[0] not in already_there]++ if fresh:+ ids = [chunk_id for chunk_id, _, _ in fresh]+ texts = [text for _, text, _ in fresh]+ metadatas: list[dict[str, Any]] = []+ for _, _, metadata in fresh:+ # Normalise onto one shape. Nothing reads these values today —+ # the collection is never queried — which is why it is cheap now+ # and expensive once something does.+ moved = dict(metadata)+ moved["type"] = "attachment"+ moved["domain"] = ATTACHMENT_DOMAIN+ metadatas.append(moved)++ # Write first, delete second, and never the other way round. Chroma+ # spans no transaction across two collections: a crash between them+ # leaves a duplicate the next run collapses on unchanged ids, while+ # deleting first would destroy the only copy — an attachment is never+ # written to ``company/docs/``, so nothing can re-ingest it.+ store.add_documents(+ texts=texts,+ metadatas=metadatas,+ ids=ids,+ collection=ChromaDBStore.ATTACHMENT_COLLECTION,+ )++ stale_ids = [chunk_id for chunk_id, _, _ in rows]+ deleted = store.delete_by_ids(ChromaDBStore.COMPANY_COLLECTION, stale_ids)+ if deleted != len(stale_ids):+ logger.error(+ "attachment migration: copied %d row(s) but removed %d from %s — "+ "the remainder are still retrievable",+ len(stale_ids),+ deleted,+ ChromaDBStore.COMPANY_COLLECTION,+ )+ return deleted++async def seed_builtin_knowledge(store: ChromaDBStore | None = None,force: bool = False,diff --git a/packages/core/openexecutive/knowledge/store.py b/packages/core/openexecutive/knowledge/store.pyindex fdf16c45..3bf7cd51 100644--- a/packages/core/openexecutive/knowledge/store.py+++ b/packages/core/openexecutive/knowledge/store.py@@ -49,6 +49,22 @@ class ChromaDBStore(KnowledgeStore):# who can edit a shared page can inject text the agents will read.# Retrieved under its own clearly-labelled, lower-ranked section.NOTION_COLLECTION = "notion_wiki"+ # Files attached in an integration channel. Same isolation reasoning as+ # the two above, taken one step further: this collection is NEVER+ # queried — not by ``retriever.retrieve``, not by anything else.+ #+ # An attachment's content is chosen by whoever sent the message. It+ # passes through no upload endpoint, gets no review, and leaves no copy+ # in ``company/docs/``. It is already inlined into the turn that carried+ # it, which is where it is useful; what it must not become is company+ # knowledge that resurfaces in later, unrelated turns.+ #+ # These rows used to live in COMPANY_COLLECTION, isolated only by a+ # domain outside the specialist set. That isolated nothing — see+ # ``query`` below, and knowledge.general_catch_all in+ # architecture-facts.yaml. The collection is the boundary; a domain+ # value never was.+ ATTACHMENT_COLLECTION = "inbound_attachments"def __init__(self, persist_directory: str | Path = "./chroma_db") -> None:import chromadb@@ -185,6 +201,54 @@ class ChromaDBStore(KnowledgeStore):)return 0+ def get_documents_by_ids(+ self, collection: str, ids: list[str]+ ) -> list[tuple[str, str, dict[str, Any]]]:+ """Return ``(chunk_id, text, metadata)`` for each id that exists.++ The counterpart to :meth:`iter_chunk_metadata`, which deliberately+ fetches metadata only: that scan runs on every boot, and pulling the+ text of every chunk along with it would cost the full collection in+ memory each time to find nothing in the steady state. Callers that+ need the text find candidate ids with the cheap scan first, then ask+ for those ids here.++ Empty list in, empty list out — guarded before the call, because+ ``col.get(ids=[])`` degrades to "fetch everything", the same footgun+ :meth:`delete_by_ids` guards against.++ Batched for the same reason ``add_documents`` batches: a channel that+ has been collecting attachments for months holds more rows than one+ request should materialise at once.+ """+ if not ids:+ return []+ out: list[tuple[str, str, dict[str, Any]]] = []+ batch_size = 100+ try:+ col = self._get_or_create_collection(collection)+ for i in range(0, len(ids), batch_size):+ rows = col.get(+ ids=ids[i : i + batch_size], include=["documents", "metadatas"]+ )+ got_ids = rows.get("ids") or []+ docs = rows.get("documents") or []+ metas = rows.get("metadatas") or []+ for cid, doc, md in zip(got_ids, docs, metas, strict=False):+ out.append(+ (+ str(cid),+ str(doc) if doc is not None else "",+ dict(md) if isinstance(md, dict) else {},+ )+ )+ except Exception:+ logging.getLogger(__name__).exception(+ "get_documents_by_ids failed for %d id(s) in %s", len(ids), collection+ )+ return []+ return out+def delete_company_docs(self) -> None:"""Delete and recreate the company_docs collection, clearing all indexed documents."""import contextlib@@ -199,3 +263,27 @@ class ChromaDBStore(KnowledgeStore):leftover COMPANY rows tagged ``type=notion`` (pre-isolation ingest)."""self.delete_documents(collection=self.NOTION_COLLECTION, where={"type": "notion"})self.delete_documents(collection=self.COMPANY_COLLECTION, where={"type": "notion"})++ def delete_attachment_docs(self) -> None:+ """Drop every inbound attachment chunk, plus any pre-isolation+ leftovers still tagged ``type=attachment`` in COMPANY.++ Drop-and-recreate rather than a ``where`` delete, unlike+ :meth:`delete_notion_docs`: the callers are client-slot restore and+ fixture reset, where one surviving row is one company's attachment+ visible to the next. "Deleted every row carrying the tag" is not the+ same guarantee as "the collection is empty", and here only the+ second one is good enough.++ The COMPANY sweep is belt-and-braces — every caller drops that+ collection wholesale a line or two earlier — but it keeps this+ method correct when called on its own.+ """+ import contextlib++ with contextlib.suppress(Exception):+ self._client.delete_collection(self.ATTACHMENT_COLLECTION)+ self._get_or_create_collection(self.ATTACHMENT_COLLECTION)+ self.delete_documents(+ collection=self.COMPANY_COLLECTION, where={"type": "attachment"}+ )diff --git a/packages/core/tests/unit/test_attachment_isolation.py b/packages/core/tests/unit/test_attachment_isolation.pynew file mode 100644index 00000000..35550acf--- /dev/null+++ b/packages/core/tests/unit/test_attachment_isolation.py@@ -0,0 +1,412 @@+"""Integration attachments are isolated from company knowledge.++Two guarantees, both regressions of a real bug:++1. ``retriever.retrieve`` never queries the attachment collection, so an+ attachment cannot resurface as company knowledge in a later turn.+2. Rows written by the old path — which put them in ``company_docs`` and+ relied on a non-specialist domain to keep them out — are migrated across+ on boot rather than left behind.++The bug that motivated both: an unrecognised domain does NOT exclude a row.+``ChromaDBStore.query`` builds a ``where`` clause only when ``domain_filter``+is truthy, and an Executive-level ``retrieve`` passes none, so those chunks+matched and were rendered under "From your company documents" — top-ranked+and indistinguishable from a curated upload.+"""+from __future__ import annotations++from typing import Any++from openexecutive.knowledge.loader import (+ ATTACHMENT_DOMAIN,+ ATTACHMENT_SOURCE_PREFIX,+ migrate_attachments_out_of_company_docs,+)+from openexecutive.knowledge.store import ChromaDBStore+++class FakeStore:+ """Collection-aware in-memory store.++ Local rather than the shared ``tests.unit._fake_store``, which is flat and+ drops the ``collection`` argument — it cannot express "this row went to a+ different collection", which is the whole subject here. Same shape as the+ fakes in ``test_recent_research_knowledge`` and ``test_notion_sync``.+ """++ def __init__(self) -> None:+ # collection -> chunk_id -> {"text": str, "metadata": dict}+ self.collections: dict[str, dict[str, dict[str, Any]]] = {}+ self.add_failures: set[str] = set()++ def _col(self, collection: str) -> dict[str, dict[str, Any]]:+ return self.collections.setdefault(collection, {})++ def add_documents(+ self,+ texts: list[str],+ metadatas: list[dict[str, Any]],+ ids: list[str],+ collection: str,+ ) -> None:+ if collection in self.add_failures:+ raise RuntimeError(f"simulated write failure into {collection}")+ col = self._col(collection)+ for chunk_id, text, meta in zip(ids, texts, metadatas, strict=True):+ col[chunk_id] = {"text": text, "metadata": dict(meta)}++ def iter_chunk_metadata(self, collection: str) -> list[tuple[str, dict[str, Any]]]:+ return [(cid, dict(r["metadata"])) for cid, r in self._col(collection).items()]++ def get_documents_by_ids(+ self, collection: str, ids: list[str]+ ) -> list[tuple[str, str, dict[str, Any]]]:+ if not ids:+ return []+ col = self._col(collection)+ return [+ (cid, col[cid]["text"], dict(col[cid]["metadata"]))+ for cid in ids+ if cid in col+ ]++ def delete_by_ids(self, collection: str, ids: list[str]) -> int:+ if not ids:+ return 0+ col = self._col(collection)+ return sum(col.pop(cid, None) is not None for cid in ids)++ def query(+ self,+ query_text: str,+ collection: str,+ domain_filter: list[str] | None = None,+ n_results: int = 5,+ ) -> list[dict[str, Any]]:+ """Models the one behaviour this whole change turns on: a falsy+ domain filter is NO filter, so it matches every row — the same+ `if domain_filter:` gate `ChromaDBStore.query` uses."""+ rows = []+ for r in self._col(collection).values():+ if domain_filter and r["metadata"].get("domain") not in domain_filter:+ continue+ rows.append({"text": r["text"], "metadata": r["metadata"], "distance": 0.1})+ return rows[:n_results]++ # -- helpers ----------------------------------------------------------+ def seed(+ self,+ collection: str,+ chunk_id: str,+ text: str,+ **metadata: Any,+ ) -> None:+ self._col(collection)[chunk_id] = {"text": text, "metadata": metadata}++ def names(self, collection: str) -> set[str]:+ return {r["metadata"].get("filename") for r in self._col(collection).values()}+++def _seed_legacy_attachment(store: FakeStore, name: str, text: str) -> str:+ """A row exactly as the pre-fix path wrote it: in COMPANY, no type tag."""+ chunk_id = f"id-{name}"+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ chunk_id,+ text,+ domain="company_docs",+ filename=f"{ATTACHMENT_SOURCE_PREFIX}{name}",+ source=f"{ATTACHMENT_SOURCE_PREFIX}{name}",+ chunk_index=0,+ )+ return chunk_id+++def _migrate(store: FakeStore) -> int:+ return migrate_attachments_out_of_company_docs(store) # type: ignore[arg-type]+++# ── migration ─────────────────────────────────────────────────────────────+++def test_legacy_rows_move_to_the_isolated_collection_with_their_text():+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "ACME gross margin is 91 percent.")+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-plan",+ "Curated plan.",+ domain="strategy",+ filename="plan.md",+ source="plan.md",+ chunk_index=0,+ )++ assert _migrate(store) == 1++ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {"plan.md"}+ attachments = store.collections[ChromaDBStore.ATTACHMENT_COLLECTION]+ assert len(attachments) == 1+ moved = next(iter(attachments.values()))+ # The text has to survive: attachments are never written to company/docs/,+ # so the store holds the only copy and a lossy move destroys it.+ assert moved["text"] == "ACME gross margin is 91 percent."+++def test_migration_preserves_chunk_ids():+ """Ids are what make a re-ingest of the same attachment upsert rather than+ duplicate, and what make this migration idempotent."""+ store = FakeStore()+ chunk_id = _seed_legacy_attachment(store, "leak.md", "text")++ _migrate(store)++ assert chunk_id in store.collections[ChromaDBStore.ATTACHMENT_COLLECTION]+++def test_migration_normalizes_domain_and_type():+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "text")++ _migrate(store)++ moved = next(iter(store.collections[ChromaDBStore.ATTACHMENT_COLLECTION].values()))+ assert moved["metadata"]["type"] == "attachment"+ assert moved["metadata"]["domain"] == ATTACHMENT_DOMAIN+++def test_migration_is_idempotent():+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "text")++ assert _migrate(store) == 1+ before = dict(store.collections[ChromaDBStore.ATTACHMENT_COLLECTION])++ assert _migrate(store) == 0+ assert store.collections[ChromaDBStore.ATTACHMENT_COLLECTION] == before+++def test_migration_is_a_noop_on_a_clean_store():+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-plan",+ "Curated plan.",+ domain="strategy",+ filename="plan.md",+ source="plan.md",+ )++ assert _migrate(store) == 0+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in store.collections+ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {"plan.md"}+++def test_migration_does_not_match_a_curated_document_named_like_one():+ """`startswith`, not `in` — a real company document about attachments is+ not an attachment."""+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-policy",+ "How we handle attachments.",+ domain="operations",+ filename="attachments-policy.md",+ source="attachments-policy.md",+ )++ assert _migrate(store) == 0+ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {"attachments-policy.md"}+++def test_migration_writes_before_it_deletes():+ """The ordering is the safety property.++ Chroma spans no transaction across two collections. A crash after the+ write leaves a duplicate the next run collapses; a crash after a delete+ destroys the only copy of an attachment, which has no file on disk to be+ re-ingested from. So a failed write must leave COMPANY untouched.+ """+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "irreplaceable")+ store.add_failures.add(ChromaDBStore.ATTACHMENT_COLLECTION)++ try:+ _migrate(store)+ except RuntimeError:+ pass++ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {+ f"{ATTACHMENT_SOURCE_PREFIX}leak.md"+ }+++def test_migration_also_catches_rows_already_carrying_the_type_tag():+ """Rows written by an interim build land in COMPANY with the tag but no+ prefix guarantee; both markers have to be recognised."""+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-tagged",+ "text",+ domain=ATTACHMENT_DOMAIN,+ filename="oddly-named.md",+ source="oddly-named.md",+ type="attachment",+ )++ assert _migrate(store) == 1+ assert store.collections[ChromaDBStore.COMPANY_COLLECTION] == {}+++# ── retrieval isolation ───────────────────────────────────────────────────+++def _retrieve_collections_queried(**retrieve_kwargs: Any) -> list[str]:+ """Run the real `retrieve` and report which collections it asked for."""+ from unittest.mock import MagicMock++ from openexecutive.knowledge import retriever++ seen: list[str] = []++ def _query(query_text: str, collection: str, **kwargs: Any) -> list[dict[str, Any]]:+ seen.append(collection)+ return []++ store = MagicMock()+ store.query.side_effect = _query+ retriever.retrieve(+ query="what is the gross margin for the quarter, in detail?",+ store=store,+ **retrieve_kwargs,+ )+ return seen+++def test_retrieve_never_queries_the_attachment_collection():+ """Both the unfiltered Executive turn and a specialist-routed call."""+ for kwargs in ({"specialist_name": None}, {"specialist_name": "finance"}):+ seen = _retrieve_collections_queried(**kwargs)+ assert ChromaDBStore.COMPANY_COLLECTION in seen, "company still retrieved"+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in seen, (+ f"attachment collection was queried with {kwargs}"+ )+++def test_a_curated_upload_named_like_an_attachment_is_not_migrated():+ """The prefix is not proof of origin.++ A colon is legal in a filename and `POST /documents` passes one through,+ so a real company document can be called `attachment:q4-plan.md`. Moving+ it would strip it from the collection it belongs in, leave an undeletable+ copy behind, and — because the file is still on disk — have the boot+ reconcile re-index it as `general`, widening an HR document to every+ specialist. The legacy `domain` is what distinguishes the two, and+ UPLOAD_DOMAINS will never accept that value from an upload.+ """+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-curated",+ "Compensation bands for Q4.",+ domain="hr", # a real upload domain, not the legacy marker+ filename=f"{ATTACHMENT_SOURCE_PREFIX}q4-comp-plan.md",+ source=f"{ATTACHMENT_SOURCE_PREFIX}q4-comp-plan.md",+ )++ assert _migrate(store) == 0+ assert store.names(ChromaDBStore.COMPANY_COLLECTION) == {+ f"{ATTACHMENT_SOURCE_PREFIX}q4-comp-plan.md"+ }+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in store.collections+++def test_migration_reports_only_what_it_actually_removed():+ """`delete_by_ids` returns 0 when the delete raises — it says so in its own+ docstring precisely so a caller cannot claim rows it did not remove.++ Reporting `len(ids)` regardless would log "moved N chunks" on a boot where+ all N are still in COMPANY and still retrievable: the leak announced as+ closed while it is open.+ """+ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "text")+ store.delete_by_ids = lambda collection, ids: 0 # type: ignore[assignment]++ assert _migrate(store) == 0+++def test_migration_does_not_clobber_a_newer_copy():+ """Ids collide by design — md5 of the same source name on both sides.++ A row already in the destination was written by the post-fix path and is+ newer than the COMPANY copy, so upserting the old text over it would+ resurrect superseded content. Drop the stale original instead.+ """+ store = FakeStore()+ chunk_id = _seed_legacy_attachment(store, "notes.md", "OLD v1")+ store.seed(+ ChromaDBStore.ATTACHMENT_COLLECTION,+ chunk_id,+ "NEW v2",+ domain=ATTACHMENT_DOMAIN,+ filename=f"{ATTACHMENT_SOURCE_PREFIX}notes.md",+ source=f"{ATTACHMENT_SOURCE_PREFIX}notes.md",+ type="attachment",+ )++ assert _migrate(store) == 1+ assert store.collections[ChromaDBStore.COMPANY_COLLECTION] == {}+ assert store.collections[ChromaDBStore.ATTACHMENT_COLLECTION][chunk_id][+ "text"+ ] == "NEW v2"+++def test_unfiltered_retrieval_matches_every_domain_including_unrecognised_ones():+ """The bug itself, as a standing regression.++ This is the premise the old code got wrong: a domain nothing maps to was+ believed to exclude a row. It does not — a falsy filter is NO filter. If+ this ever stops holding, the isolation rationale needs rewriting, not the+ test.+ """+ store = FakeStore()+ store.seed(+ ChromaDBStore.COMPANY_COLLECTION,+ "id-x",+ "secret",+ domain="a-domain-no-specialist-maps-to",+ filename="x.md",+ )++ unfiltered = store.query("q", ChromaDBStore.COMPANY_COLLECTION, domain_filter=None)+ filtered = store.query(+ "q", ChromaDBStore.COMPANY_COLLECTION, domain_filter=["finance"]+ )++ assert len(unfiltered) == 1, "an absent filter must match every domain"+ assert filtered == [], "an explicit filter must still exclude"+++def test_migrated_attachment_is_no_longer_reachable_by_an_unfiltered_retrieve():+ """End to end: the leak reproduces before the migration and is gone after.++ Drives the real `retriever.retrieve` on the no-specialist path — the one+ that passes no domain filter — against a store that honours filters the+ way ChromaDB does.+ """+ from openexecutive.knowledge import retriever++ store = FakeStore()+ _seed_legacy_attachment(store, "leak.md", "ACME gross margin is 91 percent.")++ query = "what is the gross margin for the quarter, in detail?"+ before = retriever.retrieve(query=query, specialist_name=None, store=store)+ assert "91 percent" in before, "expected to reproduce the leak pre-migration"++ _migrate(store)++ after = retriever.retrieve(query=query, specialist_name=None, store=store)+ assert "91 percent" not in afterdiff --git a/packages/core/tests/unit/test_attachments.py b/packages/core/tests/unit/test_attachments.pyindex 26d26bc2..76dd71ce 100644--- a/packages/core/tests/unit/test_attachments.py+++ b/packages/core/tests/unit/test_attachments.py@@ -248,12 +248,29 @@ async def test_process_attachments_concatenates_multiple_texts():def _ingest_call(filename: str, data: bytes = b"# Notes\nRevenue grew."):"""Run `_schedule_ingest` to completion and return the `ingest_file` call."""+ return _ingest_and_store_call(filename, data)[0]+++def _ingest_and_store_call(filename: str, data: bytes = b"# Notes\nRevenue grew."):+ """As `_ingest_call`, plus the `ChromaDBStore(...)` construction call.++ The store constructor matters on its own: it is how the ingest picks+ which database to write to, and passing no argument silently sends the+ chunks somewhere nothing reads.+ """from openexecutive.integrations import attachments as att+ from openexecutive.knowledge.store import ChromaDBStoremock_ingest = AsyncMock(return_value=3)+ mock_store_cls = MagicMock()+ # Mock the constructor, not the collection names: those are data the code+ # under test reads, and a MagicMock attribute would make the assertion+ # compare two mocks and pass regardless of what the code actually chose.+ mock_store_cls.ATTACHMENT_COLLECTION = ChromaDBStore.ATTACHMENT_COLLECTION+ mock_store_cls.COMPANY_COLLECTION = ChromaDBStore.COMPANY_COLLECTIONwith (patch("openexecutive.knowledge.loader.ingest_file", mock_ingest),- patch("openexecutive.knowledge.store.ChromaDBStore", MagicMock()),+ patch("openexecutive.knowledge.store.ChromaDBStore", mock_store_cls),):async def _drive() -> None:@@ -265,7 +282,7 @@ def _ingest_call(filename: str, data: bytes = b"# Notes\nRevenue grew."):asyncio.run(_drive())mock_ingest.assert_called_once()- return mock_ingest.call_args+ return mock_ingest.call_args, mock_store_cls.call_argsdef test_attachment_is_indexed_under_its_real_name_not_the_temp_path():@@ -292,17 +309,55 @@ def test_attachment_name_is_stripped_to_a_bare_name():assert kwargs["source_name"] == "attachment:passwd.md"-def test_attachment_domain_stays_outside_the_specialist_domains():- """Pins a deliberate gap, so a later change has to be deliberate too.+def test_attachment_is_indexed_into_the_isolated_collection():+ """The isolation this path depends on, pinned.- "company_docs" is not one of the specialist domains, so these chunks match- no domain filter and never reach the Executive. Anyone who can attach a- file in an integration channel would otherwise be writing into every- specialist's RAG context, and these rows have no removal path — they are- never written to company/docs/, so GET /documents does not list them and- DELETE /documents/{filename} 404s before reaching the store."""- from openexecutive.knowledge.loader import UPLOAD_DOMAINS+ Attachments used to go to COMPANY_COLLECTION, kept out of retrieval by a+ domain outside the specialist set. That never worked: `query` builds a+ `where` clause only when a domain filter is truthy, and an+ Executive-level `retrieve` passes none — so the chunks matched and came+ back under "From your company documents". The collection is the boundary.+ """+ from openexecutive.knowledge.store import ChromaDBStore++ _, kwargs = _ingest_call("board-deck.md")++ assert kwargs["collection"] == ChromaDBStore.ATTACHMENT_COLLECTION+ assert kwargs["collection"] != ChromaDBStore.COMPANY_COLLECTION+++def test_attachment_rows_carry_the_removal_tag():+ """`type` is what makes these rows deletable by a `where` clause — Chroma+ matches exact values only, so without it a wipe means a full scan."""+ _, kwargs = _ingest_call("board-deck.md")++ assert kwargs["extra_metadata"]["type"] == "attachment"+++def test_attachment_domain_is_not_the_general_catch_all():+ """Belt-and-braces behind the collection.++ Nothing queries the attachment collection, so this domain is never read+ today. It is chosen so that if anything ever does, the default stays+ "not retrieved": `general` would be the worst possible value, because+ `retriever._with_general` fans it out to every specialist.+ """+ from openexecutive.knowledge.loader import GENERAL_DOMAIN, UPLOAD_DOMAINS_, kwargs = _ingest_call("board-deck.md")assert kwargs["domain"] not in UPLOAD_DOMAINS+ assert kwargs["domain"] != GENERAL_DOMAIN+++def test_attachment_ingest_uses_the_configured_vector_store():+ """The bug this pins: `ChromaDBStore()` defaults to a RELATIVE+ "./chroma_db" resolved against the process CWD, so with+ VECTOR_STORE_PATH set — every container deployment — attachments were+ written to a different database than the one the API reads."""+ from openexecutive.config import get_settings++ _, store_call = _ingest_and_store_call("board-deck.md")++ assert store_call is not None, "ChromaDBStore was never constructed"+ assert store_call.kwargs.get("persist_directory") == get_settings().vector_store_pathdiff --git a/packages/core/tests/unit/test_discord_bot.py b/packages/core/tests/unit/test_discord_bot.pyindex 09f5d9c3..75241f72 100644--- a/packages/core/tests/unit/test_discord_bot.py+++ b/packages/core/tests/unit/test_discord_bot.py@@ -2010,3 +2010,41 @@ def test_discord_mention_thread_threshold_rejects_negative():pytest.raises(ValidationError),):Settings() # type: ignore[call-arg]+++# ── roster gate on attachment processing ──────────────────────────────────+++def test_is_rostered_matches_the_handle_message_gate():+ """`_is_rostered` exists so `on_message` can skip downloading and indexing+ an unrostered sender's file, which previously happened before+ `_handle_message`'s gate ran. It must agree with that gate exactly."""+ from unittest.mock import patch++ from openexecutive.integrations import discord_bot as db++ with patch(+ "openexecutive.people.store.find_person_by_discord_id", return_value=object()+ ):+ assert db._is_rostered("123") is True++ with patch("openexecutive.people.store.find_person_by_discord_id", return_value=None):+ assert db._is_rostered("123") is False++ # Empty id is unrostered, matching `discord_user_id if discord_user_id else None`+ # in the gate — and no lookup is attempted.+ assert db._is_rostered("") is False+++def test_is_rostered_fails_closed_when_the_roster_lookup_raises():+ """A database error must not read as 'rostered'. Failing open here would+ restore the exact pre-gate behaviour for every sender during an outage."""+ from unittest.mock import patch++ from openexecutive.integrations import discord_bot as db++ with patch(+ "openexecutive.people.store.find_person_by_discord_id",+ side_effect=RuntimeError("db is locked"),+ ):+ assert db._is_rostered("123") is Falsediff --git a/packages/core/tests/unit/test_doc_code_consistency.py b/packages/core/tests/unit/test_doc_code_consistency.pyindex 08606a8e..267ae4d1 100644--- a/packages/core/tests/unit/test_doc_code_consistency.py+++ b/packages/core/tests/unit/test_doc_code_consistency.py@@ -72,3 +72,58 @@ def test_hitl_doc_and_code_agree_on_resume() -> None:"Resume status disagrees between resumer.py and architecture-facts.yaml ""(workflows.human_in_the_loop). Update both.")+++def _retriever_source() -> str:+ from openexecutive.knowledge import retriever++ return Path(retriever.__file__).read_text()+++def test_retriever_never_queries_the_attachment_collection() -> None:+ """The isolation is 'this collection is not queried', which is only ever+ one helpful edit away from being untrue. Coupled to the constant rather+ than the literal so a rename cannot quietly defeat it."""+ from openexecutive.knowledge.store import ChromaDBStore++ src = _retriever_source()+ assert "ATTACHMENT_COLLECTION" not in src, (+ "retriever.py now references ATTACHMENT_COLLECTION. Attachments are "+ "sender-chosen, unreviewed text with no delete path; retrieving them "+ "is a trust-boundary change that needs its own decision and an update "+ "to architecture-facts.yaml (knowledge.collections)."+ )+ assert ChromaDBStore.ATTACHMENT_COLLECTION not in src+++def test_attachment_facts_do_not_claim_domain_isolation() -> None:+ """The retired overclaim: that a non-specialist domain kept attachment+ chunks out of the Executive's context. An unfiltered retrieval builds no+ `where` clause, so it matched every domain."""+ attachments = _load_facts()["integrations"]["attachments"]++ assert "never reach the Executive" not in attachments+ assert "match no domain filter" not in attachments+ # And it must positively name the mechanism that does the work.+ from openexecutive.knowledge.store import ChromaDBStore++ assert ChromaDBStore.ATTACHMENT_COLLECTION in attachments+++def test_attachment_isolation_doc_and_code_agree() -> None:+ """Couple the two: the code isolates by collection, so the doc must say+ collection — not domain."""+ from openexecutive.integrations import attachments as att_mod+ from openexecutive.knowledge.store import ChromaDBStore++ code_isolates_by_collection = (+ "ATTACHMENT_COLLECTION" in Path(att_mod.__file__).read_text()+ )+ doc_names_collection = (+ ChromaDBStore.ATTACHMENT_COLLECTION+ in _load_facts()["integrations"]["attachments"]+ )+ assert code_isolates_by_collection == doc_names_collection, (+ "Attachment isolation disagrees between integrations/attachments.py "+ "and architecture-facts.yaml (integrations.attachments). Update both."+ )