Files
EverOS/tests/integration/test_knowledge_integration.py
T
Kendrick-SongandClaude Opus 4.7 b1441da607 refactor(config): make [embedding] and [rerank] soft dependencies (#361)
* refactor(config): make [embedding] and [rerank] soft dependencies

Make [embedding] and [rerank] soft runtime dependencies so a
freshly-onboarded user can run EverOS end-to-end with only [llm]
configured. Previously the server refused to start without embedding,
locking out anyone who just wanted keyword-only search.

## Capability tiers

- Tier 1 ([llm] only)                   KEYWORD search, add/flush, md
                                        writes, cascade sync
- Tier 2 ([llm] + [embedding])          + VECTOR / HYBRID search,
                                        reflection, skill extraction,
                                        backfill
- Tier 3 ([llm] + [embedding] + rerank) + AGENTIC search, knowledge

Tier upgrades require a server restart (capability accessors cache
for the process lifetime). Tier downgrades are read-safe: a Tier-3
user who drops [rerank] can still read/rename/delete existing
knowledge documents; only write/search endpoints return 422.

## What changed

- Component accessors — component/{embedding,rerank,llm}/accessor.py
  are the single process-wide provider singletons. service/* never
  maintains parallel singletons; it consumes get_embedding_capability()
  / get_rerank_capability() / get_llm_client() directly. Build-time
  ValueError from the factory is logged as capability_build_failed
  (was silently swallowed).
- Error mapping — ProviderNotConfiguredError -> 422 with everos.toml
  section hints (never EVEROS_* env-var strings).
  LanceDBMigrationError fails loud with escalating recovery guidance
  (restart -> wipe index). LLMNotConfiguredError in search maps to
  None for KEYWORD degradation.
- Nullable-vector LanceDB migration — schema v2 makes the vector
  column nullable so Tier-1 rows can land without embeddings.
  Migration is guarded by a cross-process memory_root_lock
  (fcntl.flock + anyio.to_thread) and runs optimize() per table
  after Phase-1 backfill to reclaim manifest bloat.
- Cascade — knowledge handlers register unconditionally (Tier-3 ->
  Tier-2/1 downgrade no longer strands DELETE); embed-requiring
  strategies use body-guards that check capability.available at
  execution time. _TABLE_SPECS has an import-time drift assertion
  against BUSINESS_SCHEMAS_WITH_VECTOR.
- `everos cascade backfill` CLI — Phase-1 (embed missing vectors) /
  Phase-2 (emit synthetic events for cascaded processing) / Phase-3
  (sync new skill files). Exit codes: 0 / 1 / 2 / 3 (server running
  preflight) / 4 (COMPLETED_WITH_FAILURES — per-row failures rolled
  up) / 130 (SIGINT). OMEConfig.crash_recovery_enabled=False in
  backfill engines prevents stale-RUNNING rows re-enqueuing into a
  smaller strategy registry.
- /health — reports capabilities + disabled_features per tier so ops
  can distinguish "boots but degraded" from "boots and full".
- Presentation split — memory / service / infra never import typer /
  click. TyperPresenter Protocol + run_backfill() live in
  entrypoints/cli/commands/_backfill_cmd.py. Enforced by
  import-linter.
- Startup hint — unconditional count_rows(filter="vector IS NULL")
  sweep emits unbackfilled_memory_rows (event name + hint text
  pinned) when Tier-1 rows exist. ParserLifespanProvider warms the
  everalgo.parser import at boot so /health doesn't block on first
  call.
- Knowledge upload UTF-8 short-circuit — _looks_like_utf8_text()
  routes text/* mime and known plaintext extensions (md/txt/rst)
  straight to UTF-8 decode instead of the parser. Prevents 503
  Multimodal-not-configured when Tier 3 sans [multimodal] uploads a
  markdown doc.

## Sync history with main (2 merges collapsed into this squash)

Merged origin/main at 6dcd3eb (v1.1.4 -> v1.2.0 adds OTel tracing,
/api/v2 alias, TracingLifespanProvider, per-cascade-embedding span
fix, memory-op instrumentation) and later at 42629df (PR #366
backfills v1.1.4 CWE-22 knowledge path traversal fix + cascade
retry-budget rework + errors.py -> core.errors.ExternalServiceError).
Key merge decisions:
- service/search.py adopts single wrap site — component.llm accessor
  already applies UsageRecordingClient when observability is on;
  service layer never keeps a parallel LLM singleton (Round-1 CR
  rule: "service layer never maintains parallel singletons").
- Knowledge router prefix moved to /knowledge; create_app() mounts
  it under both /api/v1 and /api/v2.
- Cascade retry classification uses ExternalServiceError from
  core.errors (cascade/errors.py deleted). _MAX_TOTAL_RETRIES=12
  cross-cycle budget preserved.
- Fixed backport typo: MemoryRoot.default() -> MemoryRoot.resolve()
  (no .default() classmethod exists — main PR #366 shipped a broken
  call).

## Verified layering

    $ git grep -l "^import typer\|^from typer" src/everos/{memory,service,infra}
    # empty
    $ git grep -l "^import click\|^from click" src/everos/{memory,service,infra}
    # empty

Memory / service / infra layers clean of CLI presentation libraries.

## Review history

Three rounds of Fable 5 (opus) code review across the pre-squash
commit history closed 38 findings total:
- Round 1: 10 findings (fail-loud migration, backfill hardening,
  knowledge router gate scoping, SearchManager guards, profile
  throttle lift)
- Round 2: 13 findings (hermetic test env, hot-reload doc drift,
  knowledge handler registration, Phase 3 sync guarantee, Phase 2
  idempotency, profile event-first path, OMEConfig crash-recovery
  gate, cross-process migration lock, batch embed per-row fallback,
  LanceDB optimize, typer/click layer split)
- Round 3: 15 Minor cleanups (accessor unification, marker revert,
  episode query hygiene, --verbose subcommand, parser lifespan warm,
  task-number scrub, temporal-overlap test, real-SIGINT slow mark,
  4 design-note back-references)

Full per-round context lives in the PR description on GitHub.

## Test plan

- make lint (ruff + import-linter 3 contracts + assets +
  deprecated-names + github-docs + datetime + OpenAPI drift)
- Hermetic env full pytest — 2027 passed / 7 deselected (7 = slow +
  live_llm markers)
- Manual e2e across Tier 1/2/3 (21/21 assertions across v1/v2
  double-mount and Tier 3 -> Tier 2 downgrade)
- /health reports correct capabilities + disabled_features per tier

## Known follow-ups

- .superpowers/sdd/followup-http-bridge.md (gitignored) — Path A for
  spec §10's "backfill 期间 EverOS 完全可用" promise
- _TABLE_SCHEMA_VERSION docstring — v3+ migrations need a version
  dispatch table
- extract_user_profile.py throttle-counter block — replace LanceDB
  count_by_owner with a sqlite memcell count

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(review): close 3 blockers surfaced by round-4 review

N1. cluster_repo.find_cluster_id_for_member was cross-owner-unsafe.
Its reverse index (member_type, member_id) alone cannot disambiguate
two owners whose entry_id happens to collide — entry_id is
deliberately only per-owner unique (see entries.py:47:
'Cross-user uniqueness is handled at the database layer via a
composite <user_id>_<entry_id> field; it is not encoded into the
EntryId string itself'). Phase 2's _scan_all_rows crosses all
owners, so on any multi-owner root, same-day seq=1 episodes under
different owners would either false-hit each other's cluster or
be silently skipped from clustering. Add required (app_id,
project_id, owner_id) keyword args + JOIN Cluster (which already
carries scope) to filter by parent scope. Prior signature had zero
production callers except two the same PR just added, so the
API break is contained. Regression test: two owners persist a
cluster each around the same entry_id, each lookup resolves to
its own owner's cluster, a third owner's lookup returns None.

N2. Ctrl-C / EOF at the y/N prompt was landing on the generic
except Exception branch (exit 2 with rich traceback) instead of
the exit-130 interrupt path. Root cause: typer 0.15+ vendored
click under typer._click, so typer.Abort and the standalone
click.exceptions.Abort are distinct classes. The interrupt-branch
catch only listed the standalone one; every existing 'abort'
test was manually raising click.exceptions.Abort so the miss
was a false-positive guard rail. Widen the catch to
(typer.Abort, click.exceptions.Abort) and declare click as a
first-class dependency (it was only pulled in via uvicorn).
Regression test: raise real typer.Abort() at the confirm step
and assert exit 130 + INTERRUPTED banner.

N3. _looks_like_utf8_text used mime.startswith('text/'), which
caught text/html as well. HTML uploads then bypassed everalgo's
_aparse_html — losing clean_html_for_llm (strips <script>/<style>
/<nav>/<iframe> + HTML comments) and the 1 MiB output cap. A
40 MiB .html with <script> bodies and <!-- prompt injection -->
comments would flow straight into the extraction LLM. Replace
with explicit allowlist {text/plain, text/markdown, text/x-rst,
text/x-markdown}; text/html and any future text/* mime now
default to the parser path. Test matrix asserts text/html →
False (was regressed as True by the earlier commit).

Hermetic env full pytest: 2033 passed / 7 deselected (+6 tests
from these regressions).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(review): close round-4 major + minor + PR body errata

Round-4 review-driven cleanup. Blocker fixes (N1/N2/N3) landed in
561b5fe. This commit closes the remaining CONFIRMED items:

Major:
- J3 MemoryRoot.default() -> resolve() was a breaking public API
  rename this branch introduced (main still has default()). Adds
  default() as a backward-compat alias forwarding to resolve()
  with DeprecationWarning; CHANGELOG entry under Unreleased.
- J4 episode_repo.list_by_owner_after_ts(limit=N) truncates in
  fragment order (== insertion order), NOT newest-first. Docstring
  now spells out the trap so a future caller passing limit for a
  'newest N' window doesn't silently get the oldest N.
- J5.2 TyperPresenter.nothing_to_backfill picked colour via
  'could not be read' in message — a domain wording change
  would silently flip yellow -> green. Signature gains explicit
  scan_failed: bool kwarg; CLI colour-picks off the flag.
- J5.5 phase_header was Protocol-declared but never dispatched
  (run_backfill calls _print_phase_header directly). Removed the
  dead Protocol method + both no-op implementations.
- J6.3 3 inline from everos.core.errors import ... inside
  Phase 1/2/3 preflights promoted to a single top-level import.
- J7 subject-side embed failure was silently exit-0 because
  rows_processed advanced whenever any side wrote. Now: a row with
  a needed side still NULL counts as rows_failed (exit 4 =
  COMPLETED_WITH_FAILURES). Gated on spec.subject_of + row.needs_*
  + row.subject_text so non-Episode tables and subject-empty rows
  don't false-positive.
- J9 test_migration_cross_process.py did NOT actually test cross-
  process (all 5 tests mock memory_root_lock). Renamed to
  test_migration_lock_wiring.py; docstring now scopes it to
  'lock-invocation wiring' and points at test_core/…/test_locking.py
  for real flock coverage.
- J10 Phase 1 lacked the server-running preflight Phase 2/3 have.
  --phase all against a live server would burn Phase 1 embed API
  calls (real cost) before Phase 2 halted with exit 3. Phase 1 now
  probes _probe_ome_lock_available first; regression test in
  test_backfill_preflight.py; upgrade_path integration patches the
  probe so its in-process 'server + backfill' scenario stays valid.

Minor:
- M1 knowledge upload with NUL byte or filename > 255 bytes UTF-8
  used to raise ValueError/OSError at write_bytes → 500 with a
  half-written md left on disk. _safe_original_filename now
  rejects both up front with InvalidInputError (→ 400).
- M2 backfill optimize() now passes cleanup_older_than=timedelta(0)
  so older manifest versions are physically pruned (previous call
  compacted fragments but left the manifest chain on disk).
- M3 verify_business_schemas remediation text used to jump straight
  to 'rm -rf ~/.everos/.index/lancedb'; now walks restart → wipe.
- M5 multimodal/accessor.py capability_build_failed warning added
  so all four provider accessors log symmetrically (was silent).
- M7 test_knowledge_api parser-absence tests call
  parser_available.cache_clear() around the sys.modules patch so
  the lru_cache doesn't strand a stale True/False.
- M8 cascade_handler_embed_skipped (6 handlers) demoted INFO → DEBUG:
  Tier 1 imports were generating N × 6 handler-info lines per md.
- M10.1 test_drift_scenario_would_raise was a tautology (compared
  two hardcoded string sets, never touched the guard). Now
  monkey-patches BUSINESS_SCHEMAS_WITH_VECTOR to a superset and
  reloads _backfill, proving the import-time RuntimeError fires.
- M11 test_cascade_verbose_position subprocess.run calls gain
  env= — scrubs EVEROS_* from the developer environment so the
  same footgun as round-2 B1 doesn't re-appear inside subprocesses.
- M14 health() -> dict degraded the OpenAPI schema to
  additionalProperties: true. Introduce HealthResponse +
  HealthCapabilities Pydantic models so clients get real field
  shape; docs/openapi.json regenerated.
- M16 routes/knowledge.py:_require_knowledge_capabilities docstring
  claimed cascade.registry.build_handlers still gates
  knowledge_topic/knowledge_document, contradicting
  registry.py:177-194 (gate removed there, moved to HTTP layer).
  Rewritten to describe the current design accurately.

Hermetic env full pytest: 2037 passed / 7 deselected.

Explicitly deferred to followup:
- J1 lazy multimodal client (needs everalgo signature change)
- J2 tier definition (knowledge = Tier 3 whole)
- J5.1/3/4 broader presentation-split refactor
- J6.1/2 backfill dispatch and _backfill_table refactor
- J8 Phase 1 keyset pagination for bulk migration OOM
- M4 flock timeout/waiting log/re-entry (core/persistence refactor)
- M6 UTF-8 codec strategy (BOM/UTF-16/GBK)
- M9 count_by_owner monotonicity (latent, INTERVAL=1 short-circuits)
- M13 --phase all multi-phase combined-outcome test coverage
- M15 PR-marker rationale comments (16 occurrences, all inert)

M12 was refuted (both event names exist).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-07-29 11:05:23 +08:00

1242 lines
42 KiB
Python

"""End-to-end integration tests for the knowledge module.
Drives the full pipeline with real components except the embedding
provider (stubbed) and the knowledge extractor (mocked):
create_document -> KnowledgeWriter -> md files on disk
watchdog FSEvents -> CascadeWatcher -> md_change_state
CascadeWorker -> KnowledgeDocumentHandler + KnowledgeTopicHandler
-> SQLite rows + LanceDB rows
search_knowledge -> BM25 / vector recall -> SearchKnowledgeResult
Validates that the cascade pipeline correctly indexes knowledge
documents for both document-level and topic-level storage, and that
search retrieval works against the indexed data.
"""
from __future__ import annotations
import asyncio
import shutil
from collections.abc import AsyncIterator
from pathlib import Path
from unittest.mock import AsyncMock
import pytest
from everalgo.types import KnowledgeMemory, ParsedContent
from sqlmodel import SQLModel
from everos.component.embedding import EmbeddingProvider
from everos.component.rerank import RerankResult
from everos.component.tokenizer import build_tokenizer
from everos.core.persistence import MemoryRoot
from everos.infra.persistence.lancedb import (
KnowledgeTopic,
dispose_connection,
ensure_business_indexes,
)
from everos.infra.persistence.lancedb.lancedb_manager import get_table
from everos.infra.persistence.sqlite import (
DocumentUpsertPayload,
dispose_engine,
get_engine,
knowledge_document_repo,
knowledge_topic_sqlite_repo,
md_change_state_repo,
)
from everos.memory.cascade import CascadeConfig, CascadeOrchestrator
from everos.service.knowledge import (
ExtractionEmptyError,
create_document,
delete_document,
patch_document,
replace_document,
search_knowledge,
)
from tests.helpers.knowledge_md import find_doc_dir, read_document_md, read_topic_mds
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
class _StubEmbedder(EmbeddingProvider):
"""1024-dim deterministic vector; counts calls."""
dim = 1024
def __init__(self) -> None:
self.calls = 0
async def embed(self, text: str) -> list[float]:
self.calls += 1
return [float(i % 7) / 7.0 for i in range(self.dim)]
async def embed_batch(self, texts: list[str]) -> list[list[float]]:
return [await self.embed(t) for t in texts]
class _StubReranker:
"""Deterministic reranker — returns candidates in original order."""
async def rerank(
self,
query: str,
documents: list[str],
instruction: str | None = None,
) -> list[RerankResult]:
return [
RerankResult(index=i, score=1.0 - i * 0.01) for i in range(len(documents))
]
def _build_mock_extractor(
memories: list[KnowledgeMemory],
) -> AsyncMock:
"""Return a mock ``KnowledgeExtractor`` whose ``aextract`` returns *memories*."""
extractor = AsyncMock()
extractor.aextract.return_value = memories
return extractor
def _make_memories(
doc_id: str,
category_id: str = "Sports",
) -> list[KnowledgeMemory]:
"""Build a 3-node knowledge tree: root + 2 topic nodes."""
return [
KnowledgeMemory(
doc_id=doc_id,
topic_index=0,
topic="Olympics Plan",
summary="Overview of the 2028 Olympics plan.",
content="",
depth=0,
category_id=category_id,
topic_path="Olympics Plan",
),
KnowledgeMemory(
doc_id=doc_id,
topic_index=1,
topic="Budget",
summary="Budget overview for the Games.",
content="Total budget is $50B allocated across venues and operations.",
depth=1,
parent_index=0,
children_index=[],
topic_path="Olympics Plan > Budget",
content_labels=["finance", "planning"],
category_id=category_id,
),
KnowledgeMemory(
doc_id=doc_id,
topic_index=2,
topic="Venue",
summary="Venue plans for the Games.",
content="Three new stadiums will be constructed in downtown LA.",
depth=1,
parent_index=0,
children_index=[],
topic_path="Olympics Plan > Venue",
content_labels=["infrastructure"],
category_id=category_id,
),
]
# ---------------------------------------------------------------------------
# Fixtures
# ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
def _reset_lancedb_write_locks() -> None:
"""Drop per-table asyncio.Lock objects between tests."""
from everos.core.persistence.lancedb.repository import LanceRepoBase
LanceRepoBase._reset_locks_for_tests()
@pytest.fixture
async def cascade_runtime(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> AsyncIterator[MemoryRoot]:
"""Boot sqlite + lancedb against a tmp memory_root; dispose at teardown."""
monkeypatch.setenv("EVEROS_ROOT", str(tmp_path))
monkeypatch.setenv("EVEROS_EMBEDDING__MODEL", "stub-model")
monkeypatch.setenv("EVEROS_EMBEDDING__BASE_URL", "http://stub.invalid/v1")
monkeypatch.setenv("EVEROS_EMBEDDING__API_KEY", "stub-key")
await dispose_connection()
await dispose_engine()
engine = get_engine()
async with engine.begin() as conn:
await conn.run_sync(SQLModel.metadata.create_all)
await ensure_business_indexes()
(tmp_path / "ome.toml").write_text("# test\n")
yield MemoryRoot.resolve()
await dispose_connection()
await dispose_engine()
def _build_orchestrator(
monkeypatch: pytest.MonkeyPatch,
memory_root: MemoryRoot,
embedder: _StubEmbedder,
*,
scan_interval: float = 60.0,
) -> CascadeOrchestrator:
"""Factory for a tight-polling cascade orchestrator.
``KnowledgeTopicHandler`` fetches the embedder lazily via
``get_embedding_capability()`` rather than through the orchestrator
— patch the process-wide singleton so cascade never hits the fake
network target set up by ``cascade_runtime``.
"""
import everos.component.embedding.accessor as acc
import everos.component.rerank.accessor as rerank_acc
from everos.component.embedding import EmbeddingCapability
from everos.component.rerank import RerankCapability
monkeypatch.setattr(acc, "_capability", EmbeddingCapability(provider=embedder))
reranker = _StubReranker()
monkeypatch.setattr(rerank_acc, "_capability", RerankCapability(provider=reranker))
return CascadeOrchestrator(
memory_root=memory_root,
tokenizer=build_tokenizer(),
config=CascadeConfig(
scan_interval_seconds=scan_interval,
worker_batch_size=20,
worker_max_retry=2,
worker_poll_interval_seconds=0.05,
worker_retry_backoff_seconds=0.0,
),
)
async def _wait_drain(*, deadline: float = 20.0) -> None:
"""Poll until the cascade queue has no pending items."""
async with asyncio.timeout(deadline):
while True:
summary = await md_change_state_repo.queue_summary()
if summary.pending == 0:
return
await asyncio.sleep(0.05)
async def _wait_lance_rows(
doc_id: str,
expected: int,
*,
deadline: float = 20.0,
) -> None:
"""Poll until LanceDB has exactly *expected* rows for *doc_id*."""
table = await get_table(KnowledgeTopic.TABLE_NAME, KnowledgeTopic)
async with asyncio.timeout(deadline):
while True:
count = await table.count_rows(
filter=f"doc_id = '{doc_id}'",
)
if count == expected:
return
await asyncio.sleep(0.05)
async def _create_test_document(
memory_root: MemoryRoot,
*,
doc_id: str = "d_test12345678",
category_id: str = "Sports",
app_id: str = "default",
project_id: str = "default",
):
"""Convenience: create a document using the standard 3-node fixture."""
memories = _make_memories(doc_id, category_id)
extractor = _build_mock_extractor(memories)
knowledge_dir = memory_root.knowledge_dir(app_id, project_id)
result = await create_document(
extractor=extractor,
parsed=ParsedContent(text="Full document text about the Olympics."),
title="Olympics Plan",
knowledge_dir=knowledge_dir,
doc_id=doc_id,
category_id=category_id,
)
return result
# ---------------------------------------------------------------------------
# A. Document Creation
# ---------------------------------------------------------------------------
async def test_create_document_end_to_end(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Full pipeline: create -> md -> cascade -> SQLite + LanceDB."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_test12345678"
result = await _create_test_document(memory_root, doc_id=doc_id)
assert result.doc_id == doc_id
assert result.category_id == "Sports"
assert result.topic_count == 2
# Wait for cascade to process all files.
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
# -- Assert md files --
knowledge_dir = memory_root.knowledge_dir()
doc_dir = knowledge_dir / "Sports" / f"Olympics_Plan_{doc_id}"
assert doc_dir.is_dir()
assert (doc_dir / "index.md").is_file()
topic_files = sorted(f.name for f in doc_dir.iterdir() if f.name != "index.md")
assert len(topic_files) == 2
assert any("Budget" in f for f in topic_files)
assert any("Venue" in f for f in topic_files)
# -- Assert SQLite: knowledge_documents --
doc_row = await knowledge_document_repo.get_by_doc_id(doc_id)
assert doc_row is not None
assert doc_row.title == "Olympics Plan"
assert doc_row.category_id == "Sports"
# -- Assert SQLite: knowledge_topics --
topic_rows = await knowledge_topic_sqlite_repo.get_topics_by_doc_id(
doc_id,
)
assert len(topic_rows) == 2
topic_names = {r.topic_name for r in topic_rows}
assert "Budget" in topic_names
assert "Venue" in topic_names
# -- Assert LanceDB: knowledge_topic --
table = await get_table(KnowledgeTopic.TABLE_NAME, KnowledgeTopic)
lance_count = await table.count_rows(
filter=f"doc_id = '{doc_id}'",
)
assert lance_count == 2
# Verify vector dimension and token fields.
lance_rows = (
await table.query().where(f"doc_id = '{doc_id}'").limit(10).to_list()
)
for row in lance_rows:
assert len(row["vector"]) == 1024
assert row["summary_tokens"]
assert row["content_tokens"]
assert embedder.calls >= 2
# ── Truth layer (md files) verification ──
doc_dir = find_doc_dir(memory_root.knowledge_dir(), result.doc_id)
assert doc_dir is not None, "Document directory should exist"
index = read_document_md(doc_dir)
assert index["frontmatter"]["type"] == "knowledge_document"
assert index["frontmatter"]["doc_id"] == result.doc_id
assert index["frontmatter"]["title"] == "Olympics Plan"
assert len(index["body"]) > 10, "Document summary should be in body"
topics = read_topic_mds(doc_dir)
assert len(topics) == 2, "Should have 2 topic md files (Budget + Venue)"
for t in topics:
fm = t["frontmatter"]
assert fm["type"] == "knowledge_topic"
assert fm["doc_id"] == result.doc_id
assert fm["node_id"].startswith(result.doc_id + "_")
assert len(t["body"]) > 10, "Topic should have content body"
finally:
await orchestrator.stop()
# ---------------------------------------------------------------------------
# B. Search
# ---------------------------------------------------------------------------
async def test_search_finds_ingested_topic(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Keyword search finds topics after cascade indexing."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_search001"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
result = await search_knowledge(
query="budget",
method="keyword",
top_k=10,
)
assert result.hits, "Expected at least one search hit"
budget_hits = [h for h in result.hits if "Budget" in h.topic_name]
assert budget_hits, "Expected a hit with topic_name containing Budget"
assert budget_hits[0].score > 0
assert budget_hits[0].document.title == "Olympics Plan"
assert result.took_ms > 0
finally:
await orchestrator.stop()
async def test_search_include_content(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""include_content flag controls whether content is populated."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_content01"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
# Without content.
r_no = await search_knowledge(
query="budget",
method="keyword",
top_k=10,
include_content=False,
)
assert r_no.hits
assert r_no.hits[0].content is None
# With content.
r_yes = await search_knowledge(
query="budget",
method="keyword",
top_k=10,
include_content=True,
)
assert r_yes.hits
assert r_yes.hits[0].content
assert len(r_yes.hits[0].content) > 0
finally:
await orchestrator.stop()
async def test_search_score_threshold_filters(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""score_threshold filters out low-scoring results."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_thresh01"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
r_none = await search_knowledge(
query="budget",
method="keyword",
top_k=10,
score_threshold=None,
)
assert r_none.hits
r_high = await search_knowledge(
query="budget",
method="keyword",
top_k=10,
score_threshold=0.99,
)
assert len(r_high.hits) <= len(r_none.hits)
finally:
await orchestrator.stop()
async def test_search_app_project_isolation(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Documents in different app/project scopes are isolated in search."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_a = "d_iso_a00001"
doc_b = "d_iso_b00001"
# Create doc A in (app1, proj1).
memories_a = _make_memories(doc_a)
ext_a = _build_mock_extractor(memories_a)
await create_document(
extractor=ext_a,
parsed=ParsedContent(text="Doc A about Olympics."),
title="Olympics Plan",
knowledge_dir=memory_root.knowledge_dir("app1", "proj1"),
doc_id=doc_a,
category_id="Sports",
)
# Create doc B in (app2, proj2).
memories_b = [
KnowledgeMemory(
doc_id=doc_b,
topic_index=0,
topic="Quantum Computing",
summary="Overview of quantum computing.",
content="",
depth=0,
category_id="Technology",
topic_path="Quantum Computing",
),
KnowledgeMemory(
doc_id=doc_b,
topic_index=1,
topic="Qubits",
summary="Qubit fundamentals.",
content="A qubit is the basic unit of quantum information.",
depth=1,
parent_index=0,
children_index=[],
topic_path="Quantum Computing > Qubits",
category_id="Technology",
),
]
ext_b = _build_mock_extractor(memories_b)
await create_document(
extractor=ext_b,
parsed=ParsedContent(text="Doc B about quantum computing."),
title="Quantum Computing",
knowledge_dir=memory_root.knowledge_dir("app2", "proj2"),
doc_id=doc_b,
category_id="Technology",
)
await _wait_lance_rows(doc_a, expected=2, deadline=20.0)
await _wait_lance_rows(doc_b, expected=1, deadline=20.0)
await _wait_drain(deadline=20.0)
# Search in (app1, proj1) scope.
r1 = await search_knowledge(
query="budget stadium qubit",
method="keyword",
top_k=10,
app_id="app1",
project_id="proj1",
)
r1_doc_ids = {h.document.doc_id for h in r1.hits}
if r1.hits:
assert doc_b not in r1_doc_ids, "app1/proj1 must not see doc B"
# Search in (app2, proj2) scope.
r2 = await search_knowledge(
query="budget stadium qubit",
method="keyword",
top_k=10,
app_id="app2",
project_id="proj2",
)
r2_doc_ids = {h.document.doc_id for h in r2.hits}
if r2.hits:
assert doc_a not in r2_doc_ids, "app2/proj2 must not see doc A"
finally:
await orchestrator.stop()
# ---------------------------------------------------------------------------
# C. Delete
# ---------------------------------------------------------------------------
async def test_delete_document_end_to_end(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Manual directory removal + scanner detects deletion -> cleanup.
``delete_document`` reports the correct topic count. We then
manually remove the md directory and let the scanner (short
interval) detect the missing files and cascade-delete SQLite +
LanceDB rows.
"""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(
monkeypatch,
memory_root,
embedder,
scan_interval=2.0,
)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_del0000001"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
# Confirm pre-delete state.
assert await knowledge_document_repo.get_by_doc_id(doc_id) is not None
topic_count_before = await knowledge_topic_sqlite_repo.count_by_doc_id(
doc_id,
)
assert topic_count_before == 2
# Service-level delete reports correct counts.
del_result = await delete_document(
doc_id=doc_id,
app_id="default",
project_id="default",
)
assert del_result.doc_id == doc_id
assert del_result.deleted_topics == 2
# Manually remove the md directory to trigger cascade cleanup.
knowledge_dir = memory_root.knowledge_dir()
doc_dir = knowledge_dir / "Sports" / f"Olympics_Plan_{doc_id}"
if doc_dir.exists():
shutil.rmtree(doc_dir)
assert not doc_dir.exists()
# Wait for cascade scanner to detect + process deletions.
# LanceDB topic rows should be cleared first.
await _wait_lance_rows(doc_id, expected=0, deadline=20.0)
await _wait_drain(deadline=20.0)
# LanceDB: no topic rows.
table = await get_table(KnowledgeTopic.TABLE_NAME, KnowledgeTopic)
lance_count = await table.count_rows(
filter=f"doc_id = '{doc_id}'",
)
assert lance_count == 0
# SQLite: topic rows gone.
topic_count_after = await knowledge_topic_sqlite_repo.count_by_doc_id(
doc_id,
)
assert topic_count_after == 0
# The document row may need a second scanner pass if the FK
# constraint prevented deletion on the first attempt (index.md
# processed before topic files). Wait for the retry.
async with asyncio.timeout(15.0):
while True:
row = await knowledge_document_repo.get_by_doc_id(doc_id)
if row is None:
break
await asyncio.sleep(0.2)
assert await knowledge_document_repo.get_by_doc_id(doc_id) is None
finally:
await orchestrator.stop()
async def test_delete_document_cleans_up_after_downgrade(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Tier 3 → Tier 1 downgrade must not strand knowledge state.
Regression guard for PR #361 review blocker B3. Previously
``cascade.registry.build_handlers`` gated the two knowledge
handlers off as an atomic pair when embed OR rerank went missing.
On a Tier 3 → Tier 1 downgrade, ``service.knowledge.delete_document``
``shutil.rmtree``'d the md directory, the scanner enqueued
``deleted`` rows for every md — and the worker marked every one
``failed(retryable=False)`` because no handler was registered
for the kind. Phantom SQLite / LanceDB rows lingered forever;
``GET /documents`` kept listing them; ``cascade fix`` could not
recover.
The fix registers both knowledge handlers unconditionally. This
test seeds a document with both capabilities available, simulates
a full downgrade by pointing both accessor singletons at
``provider=None``, calls ``delete_document`` and asserts the
entire md + SQLite + LanceDB state clears and no permanent
failures accrue.
"""
import everos.component.embedding.accessor as embed_acc
import everos.component.rerank.accessor as rerank_acc
from everos.component.embedding import EmbeddingCapability
from everos.component.rerank import RerankCapability
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(
monkeypatch,
memory_root,
embedder,
scan_interval=2.0,
)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
# ── Tier 3 seed: capabilities available, full index. ────────
doc_id = "d_downgrd001"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
assert await knowledge_document_repo.get_by_doc_id(doc_id) is not None
assert await knowledge_topic_sqlite_repo.count_by_doc_id(doc_id) == 2
# ── Simulate downgrade: both capabilities unavailable. ──────
# Point the process-wide singletons the handlers read at
# ``provider=None``. ``embed_or_none`` returns ``None`` and
# ``handle_deleted`` never touches embed/rerank at all.
monkeypatch.setattr(
embed_acc, "_capability", EmbeddingCapability(provider=None)
)
monkeypatch.setattr(rerank_acc, "_capability", RerankCapability(provider=None))
# ── Delete through the service (bypass HTTP for test speed).
# ``delete_document`` rmtree's the md dir; scanner picks up
# the missing files and enqueues ``deleted`` rows for both
# kinds; worker must drain them cleanly.
del_result = await delete_document(
doc_id=doc_id,
app_id="default",
project_id="default",
)
assert del_result.doc_id == doc_id
assert del_result.deleted_topics == 2
knowledge_dir = memory_root.knowledge_dir()
doc_dir = knowledge_dir / "Sports" / f"Olympics_Plan_{doc_id}"
assert not doc_dir.exists(), "delete_document should have removed the md dir"
# ── Wait for cascade to drain the deletes. ──────────────────
await _wait_lance_rows(doc_id, expected=0, deadline=20.0)
await _wait_drain(deadline=20.0)
# ── LanceDB clean. ──────────────────────────────────────────
table = await get_table(KnowledgeTopic.TABLE_NAME, KnowledgeTopic)
assert await table.count_rows(filter=f"doc_id = '{doc_id}'") == 0
# ── SQLite topic rows gone. ─────────────────────────────────
assert await knowledge_topic_sqlite_repo.count_by_doc_id(doc_id) == 0
# ── SQLite document row gone (may need a scanner retry after
# topic deletes clear the FK dependency). ───────────────────
async with asyncio.timeout(15.0):
while True:
row = await knowledge_document_repo.get_by_doc_id(doc_id)
if row is None:
break
await asyncio.sleep(0.2)
assert await knowledge_document_repo.get_by_doc_id(doc_id) is None
# ── No permanent failures in md_change_state. ───────────────
# This is the load-bearing assertion: with the gate in place,
# every ``deleted`` row would land here as failed_permanent.
summary = await md_change_state_repo.queue_summary()
assert summary.failed_permanent == 0, (
f"downgrade + delete produced permanent failures: {summary}"
)
assert summary.failed_retryable == 0, (
f"downgrade + delete produced retryable failures: {summary}"
)
finally:
await orchestrator.stop()
async def test_delete_idempotent(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Deleting an already-deleted (or nonexistent) document is a no-op."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(
monkeypatch,
memory_root,
embedder,
scan_interval=2.0,
)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_idemp00001"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
# First delete (service) + manual rmtree + cascade cleanup.
await delete_document(
doc_id=doc_id,
app_id="default",
project_id="default",
)
knowledge_dir = memory_root.knowledge_dir()
doc_dir = knowledge_dir / "Sports" / f"Olympics_Plan_{doc_id}"
if doc_dir.exists():
shutil.rmtree(doc_dir)
await _wait_lance_rows(doc_id, expected=0, deadline=20.0)
await _wait_drain(deadline=20.0)
# Second delete: must not raise, reports 0.
result = await delete_document(
doc_id=doc_id,
app_id="default",
project_id="default",
)
assert result.deleted_topics == 0
finally:
await orchestrator.stop()
# ---------------------------------------------------------------------------
# D. Replace (PUT)
# ---------------------------------------------------------------------------
async def test_replace_document_end_to_end(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Replace = delete old + create new with same doc_id."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(
monkeypatch,
memory_root,
embedder,
scan_interval=2.0,
)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_repl000001"
knowledge_dir = memory_root.knowledge_dir()
# V1: 2 topics.
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
# Delete V1 (service + manual rmtree + cascade cleanup).
await delete_document(
doc_id=doc_id,
app_id="default",
project_id="default",
)
doc_dir_v1 = knowledge_dir / "Sports" / f"Olympics_Plan_{doc_id}"
if doc_dir_v1.exists():
shutil.rmtree(doc_dir_v1)
await _wait_lance_rows(doc_id, expected=0, deadline=20.0)
await _wait_drain(deadline=20.0)
# V2: 3 topics (same doc_id).
memories_v2 = [
KnowledgeMemory(
doc_id=doc_id,
topic_index=0,
topic="Olympics Plan V2",
summary="Updated overview.",
content="",
depth=0,
category_id="Sports",
topic_path="Olympics Plan V2",
),
KnowledgeMemory(
doc_id=doc_id,
topic_index=1,
topic="Budget V2",
summary="Updated budget overview.",
content="Revised budget is $60B.",
depth=1,
parent_index=0,
children_index=[],
topic_path="Olympics Plan V2 > Budget V2",
category_id="Sports",
),
KnowledgeMemory(
doc_id=doc_id,
topic_index=2,
topic="Venue V2",
summary="Updated venue plans.",
content="Four stadiums now planned.",
depth=1,
parent_index=0,
children_index=[],
topic_path="Olympics Plan V2 > Venue V2",
category_id="Sports",
),
KnowledgeMemory(
doc_id=doc_id,
topic_index=3,
topic="Transport",
summary="Transport infrastructure.",
content="New metro line connecting all venues.",
depth=1,
parent_index=0,
children_index=[],
topic_path="Olympics Plan V2 > Transport",
category_id="Sports",
),
]
ext_v2 = _build_mock_extractor(memories_v2)
await create_document(
extractor=ext_v2,
parsed=ParsedContent(text="Updated Olympic document."),
title="Olympics Plan V2",
knowledge_dir=knowledge_dir,
doc_id=doc_id,
category_id="Sports",
)
await _wait_lance_rows(doc_id, expected=3, deadline=20.0)
await _wait_drain(deadline=20.0)
# SQLite: 1 document row, title changed.
doc_row = await knowledge_document_repo.get_by_doc_id(doc_id)
assert doc_row is not None
assert doc_row.title == "Olympics Plan V2"
# SQLite: 3 topic rows.
topic_rows = await knowledge_topic_sqlite_repo.get_topics_by_doc_id(
doc_id,
)
assert len(topic_rows) == 3
# LanceDB: 3 rows.
table = await get_table(KnowledgeTopic.TABLE_NAME, KnowledgeTopic)
lance_count = await table.count_rows(
filter=f"doc_id = '{doc_id}'",
)
assert lance_count == 3
finally:
await orchestrator.stop()
# ---------------------------------------------------------------------------
# E. Patch
# ---------------------------------------------------------------------------
async def test_patch_title_updates_metadata(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""patch_document updates the title in SQLite without touching topics."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_patch00001"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
# Patch title.
p_result = await patch_document(
doc_id=doc_id,
app_id="default",
project_id="default",
title="New Title",
)
assert "title" in p_result.updated_fields
# SQLite: title updated.
doc_row = await knowledge_document_repo.get_by_doc_id(doc_id)
assert doc_row is not None
assert doc_row.title == "New Title"
# SQLite: topic count unchanged.
topic_count = await knowledge_topic_sqlite_repo.count_by_doc_id(doc_id)
assert topic_count == 2
finally:
await orchestrator.stop()
async def test_patch_category_updates_sqlite(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""patch_document with category_id updates the document row (SQLite-only MVP)."""
memory_root = cascade_runtime
embedder = _StubEmbedder()
orchestrator = _build_orchestrator(monkeypatch, memory_root, embedder)
await orchestrator.start()
await asyncio.sleep(0.3)
try:
doc_id = "d_patchcat01"
await _create_test_document(memory_root, doc_id=doc_id)
await _wait_lance_rows(doc_id, expected=2, deadline=20.0)
await _wait_drain(deadline=20.0)
p_result = await patch_document(
doc_id=doc_id,
app_id="default",
project_id="default",
category_id="Technology",
)
assert "category_id" in p_result.updated_fields
doc_row = await knowledge_document_repo.get_by_doc_id(doc_id)
assert doc_row is not None
assert doc_row.category_id == "Technology"
finally:
await orchestrator.stop()
# ---------------------------------------------------------------------------
# F. API Errors (service-level)
# ---------------------------------------------------------------------------
async def test_get_nonexistent_document_raises(
cascade_runtime: MemoryRoot,
) -> None:
"""get_document for a missing doc_id raises DocumentNotFoundError."""
from everos.service.knowledge import DocumentNotFoundError, get_document
with pytest.raises(DocumentNotFoundError):
await get_document(
doc_id="d_nonexistent",
app_id="default",
project_id="default",
)
async def test_search_empty_query_returns_empty(
cascade_runtime: MemoryRoot,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""An empty query string returns empty results (no crash)."""
import everos.component.embedding.accessor as embed_acc
import everos.component.rerank.accessor as rerank_acc
from everos.component.embedding import EmbeddingCapability
from everos.component.rerank import RerankCapability
monkeypatch.setattr(
embed_acc, "_capability", EmbeddingCapability(provider=_StubEmbedder())
)
monkeypatch.setattr(
rerank_acc, "_capability", RerankCapability(provider=_StubReranker())
)
result = await search_knowledge(
query="",
method="keyword",
top_k=10,
)
assert result.total == 0
assert result.hits == []
async def test_patch_nonexistent_raises(
cascade_runtime: MemoryRoot,
) -> None:
"""Patching a non-existent document raises DocumentNotFoundError."""
from everos.service.knowledge import DocumentNotFoundError
with pytest.raises(DocumentNotFoundError):
await patch_document(
doc_id="d_nonexistent",
app_id="default",
project_id="default",
title="Nope",
)
# ---------------------------------------------------------------------------
# G. Edge Cases
# ---------------------------------------------------------------------------
async def test_create_document_empty_result(
cascade_runtime: MemoryRoot,
) -> None:
"""Extractor returning [] raises ExtractionEmptyError; no files created."""
memory_root = cascade_runtime
knowledge_dir = memory_root.knowledge_dir()
extractor = _build_mock_extractor([])
with pytest.raises(ExtractionEmptyError):
await create_document(
extractor=extractor,
parsed=ParsedContent(text="Some content"),
title="Empty Doc",
knowledge_dir=knowledge_dir,
doc_id="d_empty00001",
category_id="Sports",
)
# No document directory should have been created for this doc.
doc_dir = knowledge_dir / "Sports" / "Empty_Doc_d_empty00001"
assert not doc_dir.exists()
# ---------------------------------------------------------------------------
# H. Truth-layer bug-exposing tests (xfail)
# ---------------------------------------------------------------------------
async def test_patch_title_updates_md(cascade_runtime: MemoryRoot) -> None:
"""PATCH title must update index.md frontmatter (truth layer)."""
memory_root = cascade_runtime
await _create_test_document(memory_root, doc_id="d_patch_title1")
doc_dir = find_doc_dir(memory_root.knowledge_dir(), "d_patch_title1")
assert doc_dir is not None
old_fm = read_document_md(doc_dir)["frontmatter"]
assert old_fm["title"] == "Olympics Plan"
await patch_document("d_patch_title1", "default", "default", title="New Title")
new_fm = read_document_md(doc_dir)["frontmatter"]
assert new_fm["title"] == "New Title"
async def test_patch_category_moves_directory(cascade_runtime: MemoryRoot) -> None:
"""PATCH category_id must move the document directory to the new category."""
memory_root = cascade_runtime
await _create_test_document(
memory_root, doc_id="d_patch_cat01", category_id="Sports"
)
knowledge_dir = memory_root.knowledge_dir()
old_dir = find_doc_dir(knowledge_dir, "d_patch_cat01")
assert old_dir is not None
assert "Sports" in str(old_dir)
await patch_document("d_patch_cat01", "default", "default", category_id="Finance")
new_dir = find_doc_dir(knowledge_dir, "d_patch_cat01")
assert new_dir is not None, (
"Document directory should still exist after category change"
)
assert "Finance" in str(new_dir), (
f"Directory should be under Finance/, got {new_dir}"
)
assert not old_dir.exists(), "Old Sports/ directory should be gone"
async def test_replace_failure_preserves_old_document(
cascade_runtime: MemoryRoot,
) -> None:
"""replace_document restores the original md directory when extraction fails.
White-box surfaces: md directory on disk, SQLite knowledge_documents row.
"""
memory_root = cascade_runtime
doc_id = "d_replace_fail"
result = await _create_test_document(memory_root, doc_id=doc_id)
knowledge_dir = memory_root.knowledge_dir()
doc_dir = find_doc_dir(knowledge_dir, doc_id)
assert doc_dir is not None, "Setup: original document directory must exist"
# replace_document checks SQLite before proceeding; simulate cascade sync.
await knowledge_document_repo.upsert_from_handler(
DocumentUpsertPayload(
doc_id=doc_id,
app_id="default",
project_id="default",
category_id=result.category_id,
title="Olympics Plan",
summary="test",
source_name=None,
source_type=None,
md_path=result.md_path,
)
)
failing_extractor = AsyncMock()
failing_extractor.aextract.return_value = []
with pytest.raises(ExtractionEmptyError):
await replace_document(
extractor=failing_extractor,
parsed=ParsedContent(text=""),
title="Should Fail",
doc_id=doc_id,
knowledge_dir=knowledge_dir,
)
# After failure, the original md directory must be restored.
assert doc_dir.exists(), "Original md must survive a failed PUT replacement"
async def test_dirname_collision_different_docs(cascade_runtime: MemoryRoot) -> None:
"""Two docs with titles that sanitize to the same dirname must not collide."""
memory_root = cascade_runtime
knowledge_dir = memory_root.knowledge_dir()
# Both titles sanitize to "Hello_World" after stripping punctuation.
memories1 = _make_memories("d_collision01", "Sports")
memories1[0] = memories1[0].model_copy(update={"topic": "Hello World!"})
ext1 = _build_mock_extractor(memories1)
await create_document(
extractor=ext1,
parsed=ParsedContent(text="doc1"),
title="Hello World!",
knowledge_dir=knowledge_dir,
doc_id="d_collision01",
category_id="Sports",
)
memories2 = _make_memories("d_collision02", "Sports")
memories2[0] = memories2[0].model_copy(update={"topic": "Hello World?"})
ext2 = _build_mock_extractor(memories2)
await create_document(
extractor=ext2,
parsed=ParsedContent(text="doc2"),
title="Hello World?",
knowledge_dir=knowledge_dir,
doc_id="d_collision02",
category_id="Sports",
)
dir1 = find_doc_dir(knowledge_dir, "d_collision01")
dir2 = find_doc_dir(knowledge_dir, "d_collision02")
assert dir1 is not None, "First doc directory should exist"
assert dir2 is not None, "Second doc directory should exist"
assert dir1 != dir2, "Different docs must have different directories"