Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

Harden Notion sync: residual review items from #52

Claude0035765ed8a1
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 4d6d9393..45564b35 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -2724,7 +2724,13 @@ clients:
later phase.)
- Slot ops share the fixture switcher's destructive-op lock
(_FIXTURE_OP_LOCK) — fixture loads, snapshots, resets, and slot
- switches serialize against each other.
+ switches serialize against each other. The Notion sync tick
+ coordinates with the same lock without queueing on it — it skips the
+ tick when the lock is held, fetches from Notion unlocked, then takes
+ the lock only for its short local write phase, aborting (no writes)
+ if the active client changed while it was fetching. In-process only —
+ a CLI run is a separate process the lock cannot see (known
+ limitation).
- A fixture and a client are never active simultaneously - slot ops
refuse (409) while a fixture is loaded.
- generated_fixtures is operator-level (the demo library), not client
diff --git a/packages/core/openexecutive/architecture/prebuilt/clients.json b/packages/core/openexecutive/architecture/prebuilt/clients.json
index fddab1e6..50e41586 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.\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. 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- 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\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* \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.\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- 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\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.",
"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-06-10T00:00:00Z"
}
\ No newline at end of file
diff --git a/packages/core/openexecutive/knowledge/notion_sync.py b/packages/core/openexecutive/knowledge/notion_sync.py
index 4f0b163d..c51b1c82 100644
--- a/packages/core/openexecutive/knowledge/notion_sync.py
+++ b/packages/core/openexecutive/knowledge/notion_sync.py
@@ -19,13 +19,14 @@ import asyncio
import json
import logging
import re
+from dataclasses import dataclass, field
from datetime import UTC, datetime, timedelta
from pathlib import Path
from typing import Any
import httpx
-from openexecutive.config import get_settings
+from openexecutive.config import Settings, get_settings
from openexecutive.knowledge.loader import DOMAIN_MAP, ingest_text_sync
from openexecutive.knowledge.store import ChromaDBStore
from openexecutive.memory.episodic import insert_scheduled_action
@@ -272,11 +273,16 @@ async def list_shared_pages(
client: httpx.AsyncClient,
*,
max_pages: int,
-) -> tuple[list[dict[str, Any]], bool]:
- """Return (pages, truncated). ``truncated`` means the safety cap hid more."""
+) -> tuple[list[dict[str, Any]], str | None]:
+ """Return (pages, truncated).
+
+ ``truncated`` is ``None`` for a complete listing, else a short
+ human-readable cause — callers must treat any non-None value as "more
+ pages exist that this listing did not return".
+ """
pages: list[dict[str, Any]] = []
cursor: str | None = None
- truncated = False
+ truncated: str | None = None
data: dict[str, Any] = {}
max_iters = max(2, (max_pages // 100) + 2)
for _ in range(max_iters):
@@ -291,7 +297,7 @@ async def list_shared_pages(
safe_cursor = sanitize_cursor(cursor)
if not safe_cursor:
logger.warning("notion_sync: dropping unsafe search cursor")
- truncated = True
+ truncated = "unsafe pagination cursor dropped"
break
body["start_cursor"] = safe_cursor
data = await _request(client, "POST", f"{NOTION_API}/search", json_body=body)
@@ -304,16 +310,21 @@ async def list_shared_pages(
break
cursor = data.get("next_cursor")
if not cursor:
+ # has_more with no cursor: the listing is incomplete but cannot
+ # be continued. Mark it truncated so reconciliation is skipped —
+ # otherwise still-shared pages beyond this point would be purged
+ # as "missing".
+ truncated = "Notion returned has_more with no next_cursor"
break
if len(pages) >= max_pages:
- truncated = True
+ truncated = f"listing hit the safety cap of {max_pages} pages"
break
await _sleep()
else:
- truncated = True
+ truncated = "search pagination hit the iteration cap"
logger.warning("notion_sync: search pagination hit iteration cap")
- if data.get("has_more") and len(pages) >= max_pages:
- truncated = True
+ if data.get("has_more") and len(pages) >= max_pages and truncated is None:
+ truncated = f"listing hit the safety cap of {max_pages} pages"
return pages, truncated
@@ -389,7 +400,6 @@ async def fetch_block_children(
list_index += 1
line = block_to_markdown(block, list_index=list_index)
else:
- list_index = 0
if btype == "table":
child_id = str(block.get("id") or "")
row_blocks: list[dict[str, Any]] = []
@@ -403,6 +413,11 @@ async def fetch_block_children(
dropped.add("table")
else:
line = block_to_markdown(block)
+ # Only a block that produces visible output ends a numbered list.
+ # An empty paragraph between items (common Notion editing artifact)
+ # must not restart the numbering at 1.
+ if line:
+ list_index = 0
if line:
lines.append(line)
elif btype and btype not in _SILENT_EMPTY_TYPES:
@@ -498,12 +513,37 @@ def _safe_filename(name: str) -> str | None:
return None
+def _build_file_index() -> dict[str, list[Path]]:
+ """One directory pass: map each synced page id to its on-disk file(s).
+
+ Reading every file head is the unavoidable cost of orphan detection;
+ building the index once per operation keeps ``purge_page`` /
+ ``reconcile_missing_pages`` from re-scanning the directory per page.
+ """
+ index: dict[str, list[Path]] = {}
+ for path in _docs_dir().glob("notion-*.md"):
+ try:
+ head = path.read_text(encoding="utf-8", errors="replace")[:4000]
+ except OSError:
+ continue
+ found = _PAGE_ID_COMMENT.search(head)
+ file_id = sanitize_notion_id(found.group(1)) if found else None
+ if file_id:
+ index.setdefault(file_id, []).append(path)
+ return index
+
+
def purge_page(
page_id: str,
store: ChromaDBStore,
state: dict[str, Any] | None = None,
+ file_index: dict[str, list[Path]] | None = None,
) -> bool:
- """Remove one synced page's file, chunks, and state record."""
+ """Remove one synced page's file, chunks, and state record.
+
+ ``file_index`` (from :func:`_build_file_index`) avoids a per-call
+ directory scan; direct callers may omit it and one is built here.
+ """
pid = sanitize_notion_id(page_id)
if not pid:
logger.warning("notion_sync: refuse to purge unsafe page id %r", page_id)
@@ -527,14 +567,9 @@ def purge_page(
store.delete_documents(ChromaDBStore.COMPANY_COLLECTION, {"notion_page_id": pid})
if filename:
(docs / filename).unlink(missing_ok=True)
- for path in docs.glob("notion-*.md"):
- try:
- head = path.read_text(encoding="utf-8", errors="replace")[:4000]
- except OSError:
- continue
- found = _PAGE_ID_COMMENT.search(head)
- if found and sanitize_notion_id(found.group(1)) == pid:
- path.unlink(missing_ok=True)
+ index = file_index if file_index is not None else _build_file_index()
+ for path in index.get(pid, []):
+ path.unlink(missing_ok=True)
if pages is not None:
pages.pop(pid, None)
pages.pop(page_id, None)
@@ -547,25 +582,32 @@ def reconcile_missing_pages(
store: ChromaDBStore,
state: dict[str, Any],
) -> int:
- """Purge pages (and orphan files) the integration no longer sees."""
+ """Purge pages (and orphan files) the integration no longer sees.
+
+ Blocking file and Chroma I/O throughout — callers on the event loop
+ must run this via ``asyncio.to_thread`` (the sync tick does).
+ """
pages = state.setdefault("pages", {})
if not isinstance(pages, dict):
state["pages"] = {}
pages = state["pages"]
+ file_index = _build_file_index()
stale = [pid for pid in list(pages) if sanitize_notion_id(str(pid)) not in visible_ids]
purged = 0
+ purged_ids: set[str] = set()
for pid in stale:
- if purge_page(str(pid), store, state):
+ if purge_page(str(pid), store, state, file_index=file_index):
purged += 1
- docs = _docs_dir()
- for path in docs.glob("notion-*.md"):
- try:
- head = path.read_text(encoding="utf-8", errors="replace")[:4000]
- except OSError:
- continue
- found = _PAGE_ID_COMMENT.search(head)
- file_id = sanitize_notion_id(found.group(1)) if found else None
- if file_id and file_id not in visible_ids and purge_page(file_id, store, state):
+ safe = sanitize_notion_id(str(pid))
+ if safe:
+ purged_ids.add(safe)
+ # Orphan files: on disk with a page-id comment but absent from state.
+ for file_id in list(file_index):
+ if (
+ file_id not in visible_ids
+ and file_id not in purged_ids
+ and purge_page(file_id, store, state, file_index=file_index)
+ ):
purged += 1
return purged
@@ -588,6 +630,202 @@ def _clear_legacy_company_notion(store: ChromaDBStore) -> None:
store.delete_documents(ChromaDBStore.COMPANY_COLLECTION, {"type": "notion"})
+@dataclass
+class _TickFetch:
+ """Everything the network phase of a tick learned, ready to apply locally."""
+
+ visible_ids: set[str] = field(default_factory=set)
+ truncated: str | None = None
+ # (page, page_id, last_edited, markdown) per successfully fetched page.
+ fetched: list[tuple[dict[str, Any], str, str, str]] = field(default_factory=list)
+ # last_edited times of pages left unsynced (fetch failure / cap overflow),
+ # which pin the watermark below them.
+ unresolved_times: list[str] = field(default_factory=list)
+
+
+def _note_reconcile_skip(state: dict[str, Any], cause: str) -> None:
+ """Record and log one more consecutive tick without reconciliation.
+
+ Reconciliation is what purges pages whose sharing was revoked, so a
+ persistent skip streak means revoked content is lingering locally —
+ surface the streak length instead of logging each skip in isolation.
+ """
+ raw = state.get("reconcile_skips")
+ skips = (raw if isinstance(raw, int) else 0) + 1
+ state["reconcile_skips"] = skips
+ logger.warning(
+ "notion_sync: skipping reconciliation — %s "
+ "(%d consecutive skip(s); revoked pages are not purged until "
+ "reconciliation runs)",
+ cause,
+ skips,
+ )
+
+
+async def _fetch_tick(
+ *,
+ client: httpx.AsyncClient,
+ settings: Settings,
+ state: dict[str, Any],
+ reconcile_only: bool,
+ stats: dict[str, int],
+) -> _TickFetch:
+ """Network phase: list visible pages and download dirty page content.
+
+ Reads ``state`` only to decide which pages are already current; all
+ state mutation happens later in :func:`_apply_tick`.
+ """
+ fetch = _TickFetch()
+ pages, fetch.truncated = await list_shared_pages(
+ client, max_pages=_MAX_VISIBLE_PAGES
+ )
+ stats["seen"] = len(pages)
+
+ dirty: list[dict[str, Any]] = []
+ for page in pages:
+ page_id = sanitize_notion_id(str(page.get("id") or ""))
+ if not page_id:
+ logger.warning(
+ "notion_sync: skipping page with unsafe id %r", page.get("id")
+ )
+ stats["failed"] += 1
+ continue
+ fetch.visible_ids.add(page_id)
+ edited = str(page.get("last_edited_time") or "")
+ recorded = _page_record(state, page_id)
+ if recorded.get("last_edited") == edited:
+ stats["skipped"] += 1
+ continue
+ dirty.append(page)
+
+ if reconcile_only:
+ return fetch
+
+ ingest_cap = max(0, settings.notion_max_pages_per_scan)
+ dirty.sort(
+ key=lambda p: str(p.get("last_edited_time") or ""),
+ reverse=True,
+ )
+ overflow = dirty[ingest_cap:]
+ to_ingest = dirty[:ingest_cap]
+ if overflow:
+ stats["capped"] = len(overflow)
+ logger.warning(
+ "notion_sync: %d page(s) need ingest, cap is %d — "
+ "overflow will retry next tick (watermark not advanced past them)",
+ len(dirty),
+ ingest_cap,
+ )
+ fetch.unresolved_times = [
+ str(p.get("last_edited_time") or "")
+ for p in overflow
+ if p.get("last_edited_time")
+ ]
+ for page in to_ingest:
+ page_id = sanitize_notion_id(str(page.get("id") or ""))
+ if not page_id:
+ stats["failed"] += 1
+ continue
+ edited = str(page.get("last_edited_time") or "")
+ try:
+ await _sleep()
+ lines = await fetch_block_children(client, page_id)
+ except Exception:
+ stats["failed"] += 1
+ if edited:
+ fetch.unresolved_times.append(edited)
+ logger.exception("notion_sync: failed to fetch page %s", page_id)
+ continue
+ fetch.fetched.append((page, page_id, edited, "\n\n".join(lines)))
+ return fetch
+
+
+async def _apply_tick(
+ *,
+ store: ChromaDBStore,
+ fetch: _TickFetch,
+ now: datetime | None,
+ reconcile_only: bool,
+ stats: dict[str, int],
+) -> None:
+ """Local write phase — the caller must hold ``_FIXTURE_OP_LOCK``.
+
+ Nothing here touches the network: it is bounded file, state, and
+ Chroma work, so the lock hold stays short even for a large wiki.
+ """
+ # Reload instead of reusing the pre-fetch snapshot: a fixture load or
+ # reset may have replaced the state file while the network phase ran,
+ # and saving a stale snapshot would resurrect purged page records.
+ state = load_state()
+ watermark = state.get("watermark") if isinstance(state.get("watermark"), str) else None
+ await asyncio.to_thread(_clear_legacy_company_notion, store)
+
+ known = state.get("pages") if isinstance(state.get("pages"), dict) else {}
+ if fetch.truncated:
+ _note_reconcile_skip(
+ state,
+ f"page listing incomplete ({fetch.truncated}), "
+ "so unseen pages must not be purged as missing",
+ )
+ elif not fetch.visible_ids and known:
+ _note_reconcile_skip(
+ state,
+ f"search returned 0 pages while {len(known)} are on record "
+ "(refusing a mass purge on a blank listing)",
+ )
+ else:
+ # File-head scanning plus Chroma deletes — keep it off the event
+ # loop so a large or bulk-unshared wiki cannot stall the API.
+ stats["purged"] = await asyncio.to_thread(
+ reconcile_missing_pages, fetch.visible_ids, store, state
+ )
+ state["reconcile_skips"] = 0
+
+ if not reconcile_only:
+ unresolved_times = list(fetch.unresolved_times)
+ for page, page_id, edited, markdown in fetch.fetched:
+ try:
+ chunks = await ingest_page(page, markdown, store)
+ filename = slugify(page_title(page), page_id)
+ state.setdefault("pages", {})[page_id] = {
+ "last_edited": edited,
+ "title": page_title(page),
+ "filename": filename,
+ }
+ stats["updated"] += 1
+ logger.info(
+ "notion_sync: indexed %s (%d chunks)", page_title(page), chunks
+ )
+ except Exception:
+ stats["failed"] += 1
+ if edited:
+ unresolved_times.append(edited)
+ logger.exception("notion_sync: failed page %s", page_id)
+
+ if unresolved_times:
+ # Leave watermark strictly below the earliest unresolved edit
+ # so those pages stay eligible. Successfully recorded pages
+ # are skipped via the pages dict, not the watermark.
+ logger.info(
+ "notion_sync: watermark held at %s (%d unresolved page(s))",
+ watermark,
+ len(unresolved_times),
+ )
+ else:
+ recorded_times = [
+ str(rec.get("last_edited") or "")
+ for rec in (state.get("pages") or {}).values()
+ if isinstance(rec, dict) and rec.get("last_edited")
+ ]
+ if recorded_times:
+ candidate = max(recorded_times)
+ if watermark is None or candidate > watermark:
+ state["watermark"] = candidate
+
+ state["last_run"] = (now or datetime.now(UTC)).isoformat()
+ save_state(state)
+
+
async def run_notion_sync(
*,
store: ChromaDBStore | None = None,
@@ -612,127 +850,56 @@ async def run_notion_sync(
logger.warning("notion_sync: enabled but NOTION_API_KEY is empty — skipping")
return stats
+ # A sync tick writes the active client's docs, vector collections, and
+ # sync-state file, so its writes must not interleave with an in-process
+ # fixture load / client rotation — those swap that state wholesale and a
+ # mid-rotation tick would write one client's wiki into another's
+ # collection. Holding the destructive-op lock across the whole tick
+ # would let slow Notion I/O block /fixtures/* and /clients/* (and, via
+ # the rotation pause marker, the entire scheduler), so instead: skip
+ # the tick when a destructive op is already running, fetch from Notion
+ # unlocked, and take the lock only for the local write phase. A CLI
+ # invocation is a separate process this lock cannot see — that
+ # cross-process race is a known, accepted limitation.
+ from openexecutive.cli.fixture_loader import _FIXTURE_OP_LOCK
+ from openexecutive.clients.slots import get_active_client
+
+ if _FIXTURE_OP_LOCK.locked():
+ logger.info(
+ "notion_sync: fixture/rotation operation in progress — "
+ "skipping this tick, will retry on the next interval"
+ )
+ return stats
+
if store is None:
store = ChromaDBStore(persist_directory=settings.vector_store_path)
- state = load_state()
- watermark = state.get("watermark") if isinstance(state.get("watermark"), str) else None
+ generation = get_active_client(settings)
own_client = client is None
if client is None:
client = httpx.AsyncClient(headers=_headers(api_key), timeout=60.0)
-
try:
- await asyncio.to_thread(_clear_legacy_company_notion, store)
- pages, truncated = await list_shared_pages(
- client, max_pages=_MAX_VISIBLE_PAGES
+ fetch = await _fetch_tick(
+ client=client,
+ settings=settings,
+ state=load_state(),
+ reconcile_only=reconcile_only,
+ stats=stats,
)
- stats["seen"] = len(pages)
- if truncated:
- logger.warning(
- "notion_sync: visible page list hit safety cap %d — "
- "skipping reconciliation this tick so unseen pages are not purged",
- _MAX_VISIBLE_PAGES,
- )
-
- visible_ids: set[str] = set()
- dirty: list[dict[str, Any]] = []
- for page in pages:
- page_id = sanitize_notion_id(str(page.get("id") or ""))
- if not page_id:
+ async with _FIXTURE_OP_LOCK:
+ if get_active_client(settings) != generation:
logger.warning(
- "notion_sync: skipping page with unsafe id %r", page.get("id")
+ "notion_sync: active client changed while fetching — "
+ "discarding this tick's results"
)
- stats["failed"] += 1
- continue
- visible_ids.add(page_id)
- edited = str(page.get("last_edited_time") or "")
- recorded = _page_record(state, page_id)
- if recorded.get("last_edited") == edited:
- stats["skipped"] += 1
- continue
- dirty.append(page)
-
- known = state.get("pages") if isinstance(state.get("pages"), dict) else {}
- if truncated:
- pass
- elif not visible_ids and known:
- logger.warning(
- "notion_sync: search returned 0 pages while %d are on record — "
- "skipping reconciliation to avoid a mass purge on a blank listing",
- len(known),
+ return stats
+ await _apply_tick(
+ store=store,
+ fetch=fetch,
+ now=now,
+ reconcile_only=reconcile_only,
+ stats=stats,
)
- else:
- stats["purged"] = reconcile_missing_pages(visible_ids, store, state)
-
- if not reconcile_only:
- ingest_cap = max(0, settings.notion_max_pages_per_scan)
- dirty.sort(
- key=lambda p: str(p.get("last_edited_time") or ""),
- reverse=True,
- )
- overflow = dirty[ingest_cap:]
- to_ingest = dirty[:ingest_cap]
- if overflow:
- stats["capped"] = len(overflow)
- logger.warning(
- "notion_sync: %d page(s) need ingest, cap is %d — "
- "overflow will retry next tick (watermark not advanced past them)",
- len(dirty),
- ingest_cap,
- )
- unresolved_times = [
- str(p.get("last_edited_time") or "")
- for p in overflow
- if p.get("last_edited_time")
- ]
- for page in to_ingest:
- page_id = sanitize_notion_id(str(page.get("id") or ""))
- if not page_id:
- stats["failed"] += 1
- continue
- edited = str(page.get("last_edited_time") or "")
- try:
- await _sleep()
- lines = await fetch_block_children(client, page_id)
- chunks = await ingest_page(page, "\n\n".join(lines), store)
- filename = slugify(page_title(page), page_id)
- state.setdefault("pages", {})[page_id] = {
- "last_edited": edited,
- "title": page_title(page),
- "filename": filename,
- }
- stats["updated"] += 1
- logger.info(
- "notion_sync: indexed %s (%d chunks)", page_title(page), chunks
- )
- except Exception:
- stats["failed"] += 1
- if edited:
- unresolved_times.append(edited)
- logger.exception("notion_sync: failed page %s", page_id)
-
- if unresolved_times:
- # Leave watermark strictly below the earliest unresolved edit
- # so those pages stay eligible. Successfully recorded pages
- # are skipped via the pages dict, not the watermark.
- logger.info(
- "notion_sync: watermark held at %s (%d unresolved page(s))",
- watermark,
- len(unresolved_times),
- )
- else:
- recorded_times = [
- str(rec.get("last_edited") or "")
- for rec in (state.get("pages") or {}).values()
- if isinstance(rec, dict) and rec.get("last_edited")
- ]
- if recorded_times:
- candidate = max(recorded_times)
- if watermark is None or candidate > watermark:
- state["watermark"] = candidate
-
- state["last_run"] = (now or datetime.now(UTC)).isoformat()
- save_state(state)
finally:
if own_client:
await client.aclose()
@@ -747,22 +914,24 @@ def purge_all_synced(store: ChromaDBStore, state: dict[str, Any] | None = None)
raw_pages = current.get("pages")
pages = raw_pages if isinstance(raw_pages, dict) else {}
ids = list(pages)
+ file_index = _build_file_index()
purged = 0
+ purged_ids: set[str] = set()
for pid in ids:
- if purge_page(str(pid), store, current):
+ if purge_page(str(pid), store, current, file_index=file_index):
purged += 1
- docs = _docs_dir()
- for path in docs.glob("notion-*.md"):
- try:
- head = path.read_text(encoding="utf-8", errors="replace")[:4000]
- except OSError:
- continue
- found = _PAGE_ID_COMMENT.search(head)
- file_id = sanitize_notion_id(found.group(1)) if found else None
- if file_id:
- if purge_page(file_id, store, current):
- purged += 1
- else:
+ safe = sanitize_notion_id(str(pid))
+ if safe:
+ purged_ids.add(safe)
+ for file_id in file_index:
+ if file_id not in purged_ids and purge_page(
+ file_id, store, current, file_index=file_index
+ ):
+ purged += 1
+ indexed_paths = {p for paths in file_index.values() for p in paths}
+ for path in _docs_dir().glob("notion-*.md"):
+ # Files with no readable page-id comment are junk — remove them.
+ if path not in indexed_paths:
path.unlink(missing_ok=True)
purged += 1
store.delete_notion_docs()
diff --git a/packages/core/openexecutive/scheduler/runner.py b/packages/core/openexecutive/scheduler/runner.py
index cf2164a7..8ae35ef4 100644
--- a/packages/core/openexecutive/scheduler/runner.py
+++ b/packages/core/openexecutive/scheduler/runner.py
@@ -535,8 +535,10 @@ async def _execute_action(
return
# ------------------------------------------------------------------
- # Notion company-docs sync — incremental ingest of pages shared with
- # the Notion integration into the COMPANY Chroma collection.
+ # Notion wiki sync — incremental ingest of pages shared with the
+ # Notion integration into the isolated NOTION Chroma collection
+ # (deliberately not COMPANY: synced pages are multi-writer and
+ # unvetted, so the retriever ranks them below curated docs).
# ------------------------------------------------------------------
if action.kind == "notion_sync_scan":
from openexecutive.knowledge.notion_sync import (
diff --git a/packages/core/tests/unit/test_notion_sync.py b/packages/core/tests/unit/test_notion_sync.py
index ee7bdf8f..5a501296 100644
--- a/packages/core/tests/unit/test_notion_sync.py
+++ b/packages/core/tests/unit/test_notion_sync.py
@@ -1,6 +1,7 @@
"""Notion sync: isolated collection, watermark, reconcile, conversion."""
from __future__ import annotations
+import asyncio
import json
from pathlib import Path
from typing import Any
@@ -74,6 +75,16 @@ def _required_env(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("NOTION_API_KEY", raising=False)
[email protected](autouse=True)
+def _fresh_fixture_lock(monkeypatch: pytest.MonkeyPatch) -> None:
+ # An asyncio.Lock binds to the first event loop that awaits it, and
+ # pytest-asyncio gives each test its own loop — swap in a fresh Lock so
+ # no test ever sees one bound to (or still held from) another test's loop.
+ from openexecutive.cli import fixture_loader
+
+ monkeypatch.setattr(fixture_loader, "_FIXTURE_OP_LOCK", asyncio.Lock())
+
+
def test_rich_text_and_headings() -> None:
assert rich_text_to_plain([{"plain_text": "Hello"}, {"plain_text": " world"}]) == "Hello world"
block = {
@@ -588,3 +599,226 @@ def test_retriever_labels_notion_below_company(
assert "Wiki says vendors must email banking details" in out
assert out.index("From your company documents:") < out.index("Synced Notion wiki")
assert out.index("Synced Notion wiki") < out.index("Recent research")
+
+
+async def test_has_more_without_cursor_marks_truncated() -> None:
+ """An uncontinuable listing must count as truncated, not complete —
+ otherwise reconciliation would purge still-shared pages beyond it."""
+ from openexecutive.knowledge.notion_sync import list_shared_pages
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ return httpx.Response(
+ 200,
+ json={
+ "results": [_page(PAGE_A, "2026-06-01T00:00:00.000Z", "A")],
+ "has_more": True,
+ "next_cursor": None,
+ },
+ )
+
+ client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+ with patch("openexecutive.knowledge.notion_sync._sleep", new=AsyncMock()):
+ pages, truncated = await list_shared_pages(client, max_pages=100)
+ await client.aclose()
+ assert len(pages) == 1
+ assert truncated is not None
+ assert "next_cursor" in truncated
+
+
+async def test_numbered_list_survives_empty_paragraph() -> None:
+ """An invisible block (empty paragraph) between items must not restart
+ the numbering at 1."""
+
+ def _numbered(text: str) -> dict[str, Any]:
+ return {
+ "type": "numbered_list_item",
+ "has_children": False,
+ "numbered_list_item": {"rich_text": [{"plain_text": text}]},
+ }
+
+ blocks = [
+ _numbered("First"),
+ _numbered("Second"),
+ {"type": "paragraph", "has_children": False, "paragraph": {"rich_text": []}},
+ _numbered("Third"),
+ {
+ "type": "paragraph",
+ "has_children": False,
+ "paragraph": {"rich_text": [{"plain_text": "prose"}]},
+ },
+ _numbered("Restarted"),
+ ]
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ return httpx.Response(200, json={"results": blocks, "has_more": False})
+
+ client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+ with patch("openexecutive.knowledge.notion_sync._sleep", new=AsyncMock()):
+ lines = await fetch_block_children(client, PAGE_A)
+ await client.aclose()
+ assert lines == ["1. First", "2. Second", "3. Third", "prose", "1. Restarted"]
+
+
+async def test_reconcile_runs_off_event_loop(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """run_notion_sync must dispatch reconciliation through a worker thread."""
+ import threading
+
+ seen_threads: list[bool] = []
+ main = threading.main_thread()
+
+ def _spy(visible_ids, store, state): # noqa: ANN001
+ seen_threads.append(threading.current_thread() is not main)
+ return 0
+
+ monkeypatch.setattr(
+ "openexecutive.knowledge.notion_sync.reconcile_missing_pages", _spy
+ )
+ stats, _, _ = await _run_sync(
+ tmp_path=tmp_path,
+ monkeypatch=monkeypatch,
+ pages=[_page(PAGE_A, "2026-06-01T00:00:00.000Z", "A")],
+ )
+ assert seen_threads == [True]
+ assert stats["seen"] == 1
+
+
+async def test_sync_tick_skips_while_fixture_lock_held(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A tick must not interleave with a fixture load / client rotation:
+ it skips immediately (no network traffic, no writes) instead of
+ queueing behind the destructive op and retries on the next interval."""
+ from openexecutive.cli import fixture_loader
+
+ state_file = _sync_env(tmp_path, monkeypatch)
+ state_file.write_text(
+ json.dumps({"watermark": None, "pages": {}}) + "\n", encoding="utf-8"
+ )
+ requests_seen: list[str] = []
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ requests_seen.append(request.url.path)
+ return httpx.Response(200, json={"results": [], "has_more": False})
+
+ client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+ docs = tmp_path / "docs"
+ docs.mkdir(exist_ok=True)
+ with (
+ patch("openexecutive.knowledge.notion_sync._state_path", return_value=state_file),
+ patch("openexecutive.knowledge.notion_sync._docs_dir", return_value=docs),
+ patch("openexecutive.knowledge.notion_sync._sleep", new=AsyncMock()),
+ ):
+ await fixture_loader._FIXTURE_OP_LOCK.acquire()
+ try:
+ stats = await run_notion_sync(store=FakeStore(), client=client) # type: ignore[arg-type]
+ finally:
+ fixture_loader._FIXTURE_OP_LOCK.release()
+ await client.aclose()
+ assert requests_seen == []
+ assert stats == {
+ "seen": 0,
+ "updated": 0,
+ "skipped": 0,
+ "failed": 0,
+ "purged": 0,
+ "capped": 0,
+ }
+
+
+async def test_sync_discards_tick_when_active_client_changes(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A rotation that swaps the active client between the fetch phase and
+ the write phase must abort the tick: nothing fetched under the old
+ client may be written into the new client's collection or state."""
+ calls = {"n": 0}
+
+ def _generation(settings: Any) -> str:
+ calls["n"] += 1
+ return "alpha" if calls["n"] == 1 else "beta"
+
+ monkeypatch.setattr(
+ "openexecutive.clients.slots.get_active_client", _generation
+ )
+ stats, store, state_file = await _run_sync(
+ tmp_path=tmp_path,
+ monkeypatch=monkeypatch,
+ pages=[_page(PAGE_A, "2026-06-01T00:00:00.000Z", "A")],
+ )
+ assert calls["n"] == 2
+ assert stats["seen"] == 1 # the fetch phase ran...
+ assert stats["updated"] == 0 # ...but nothing was written
+ assert store.collections.get(ChromaDBStore.NOTION_COLLECTION, []) == []
+ state = json.loads(state_file.read_text(encoding="utf-8"))
+ assert state["pages"] == {}
+
+
+async def test_truncated_listing_skips_reconcile_and_counts(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A truncated listing must skip reconciliation (keeping unseen pages)
+ and grow the consecutive-skip counter; a complete listing reconciles
+ and resets it."""
+ state_file = _sync_env(tmp_path, monkeypatch)
+ state_file.write_text(
+ json.dumps(
+ {
+ "watermark": None,
+ "pages": {
+ PAGE_GONE: {
+ "last_edited": "2026-01-01T00:00:00.000Z",
+ "filename": "notion-33333333-gone.md",
+ "title": "Gone",
+ }
+ },
+ }
+ )
+ + "\n",
+ encoding="utf-8",
+ )
+ truncate = {"on": True}
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ if request.url.path.endswith("/search"):
+ return httpx.Response(
+ 200,
+ json={
+ "results": [_page(PAGE_A, "2026-06-01T00:00:00.000Z", "A")],
+ "has_more": truncate["on"],
+ "next_cursor": None,
+ },
+ )
+ if "/blocks/" in request.url.path:
+ return _children_ok()
+ return httpx.Response(404, json={"message": request.url.path})
+
+ client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+ docs = tmp_path / "docs"
+ docs.mkdir(exist_ok=True)
+ store = FakeStore()
+ with (
+ patch("openexecutive.knowledge.notion_sync._state_path", return_value=state_file),
+ patch("openexecutive.knowledge.notion_sync._docs_dir", return_value=docs),
+ patch("openexecutive.knowledge.notion_sync._sleep", new=AsyncMock()),
+ ):
+ stats = await run_notion_sync(store=store, client=client) # type: ignore[arg-type]
+ state = json.loads(state_file.read_text(encoding="utf-8"))
+ assert stats["purged"] == 0
+ assert PAGE_GONE in state["pages"]
+ assert state["reconcile_skips"] == 1
+
+ truncate["on"] = False
+ stats = await run_notion_sync(store=store, client=client) # type: ignore[arg-type]
+ state = json.loads(state_file.read_text(encoding="utf-8"))
+ assert stats["purged"] == 1
+ assert PAGE_GONE not in state["pages"]
+ assert state["reconcile_skips"] == 0
+ await client.aclose()