Skip to content

Implementation assessment

Reviewed engine revision: e7de140, 2026-10-13. This assessment compares an earlier review with the current implementation and includes three small synthetic probes. It is not a complete security audit or release qualification. Runtime test success does not close the behavioral gaps below.

Prioritize these remaining defects

  1. Strict lexical retrieval can fail on ordinary broad terms. The lexical adapter sets complete=False when more than the 80-per-kind result cap matches (src/tychora/adapters/sqlite/lexical.py:103-116); strict query processing maps any incomplete channel to INDEX_INCOMPLETE (src/tychora/application/query.py:700-708). The test asserts this conflation (tests/retrieval/test_lexical.py:205-218). Separate intentional candidate truncation from index corruption/unavailability and add a strict-mode regression case.
  2. Cutoff queries can invent a decision. Edition eligibility selects the maximal dated key, then warns whenever any two editions remain, even with one winner (src/tychora/retrieval/eligibility.py:95-106). Query turns that warning into DecisionRequirement (src/tychora/application/query.py:989-995). Warn on tied or genuinely overlapping winners; test unique historical selection and unknown dates.
  3. History/diagnostic retention is unenforced and documented commands are dead. CLI accepts purge-history and purge-cache (src/tychora/interfaces/commands/manage.py:215-225), while maintenance dispatch has no corresponding operation branch (src/tychora/application/maintenance.py:99-315). HistoryRepository.purge and JobRepository.expire_diagnostics exist without production callers (src/tychora/adapters/sqlite/history.py:219, src/tychora/adapters/sqlite/jobs.py:444). The earlier operations guide described both commands as working; the current guide now records the limitation. Implement and schedule retention, or correct the CLI/docs until supported.
  4. Vector family identity is configuration-derived and record IDs omit the family. Text/image creation_uuid uses UUID5 of workspace and configuration (src/tychora/indexing/coordinator.py:416-421,575-578); expected text/visual record IDs use input and space but no family (:470-477,687-697). The contract helper already includes family ID (src/tychora/contracts/identity.py:112-114). A new family with equal configuration cannot get an independent namespace; distinct families in one space can collide. Persist a creation nonce and use family-qualified record IDs, with migration implications assessed first.
  5. Second standalone owner receives the wrong error. Standalone publish writes no authority (src/tychora/application/runtime.py:154-164), while client delegation reads record['authority'] and converts the resulting KeyError to INTEGRITY_ERROR (src/tychora/interfaces/http/client.py:944-960). Return retryable WORKSPACE_BUSY for a live owner without an HTTP endpoint, with a two-process test.
  6. Requested query trace remains absent. The response contract defaults trace to None (src/tychora/contracts/evidence.py:238); QueryService does not populate it, including when request trace is true (src/tychora/contracts/requests.py:348). Wire bounded policy/statistics/selection trace information with scope filtering, or remove the advertised option.

The first five affect correctness or lifecycle behavior. The trace gap is an exposed but incomplete observability feature. These are priority suggestions, not a claim that every point is a release blocker without product acceptance criteria.

The first three findings were reproduced with the engine's existing development Python, PYTHONDONTWRITEBYTECODE=1, and in-memory/synthetic fixtures. No provider or owner was started and no repository files were changed:

Probe Observed at e7de140 Limit
SQLite FTS fixture with 81 distinct eligible sources matching alpha, candidate_limit=80 distinct_candidate_count=81, 80 returned, complete=False Confirms lexical cap classification; strict query's INDEX_INCOMPLETE conversion is code inspection, not an end-to-end query run.
Two dated editions of one synthetic source, with a 2023 publication cutoff Only the newer edition selected, yet warning says “Overlapping retained editions” Confirms temporal warning; query's DecisionRequirement conversion is code inspection.
Synthetic management grant and MaintenanceService.run for history-purge and cache-purge Both return CAPABILITY_MISSING, “Maintenance operation is unavailable” Confirms service dispatch; no CLI subprocess or workspace was opened.

Other findings still supported by current code

  • inspect relations ID remains unavailable through the CLI: relations is in _DISCOVERY, not _RECORDS (src/tychora/interfaces/commands/inspect.py:9-21); API traversal is a separate operation. collections is absent from SUBJECTS (src/tychora/application/discovery.py:44-59). These are interface-coverage gaps.
  • Code context_excerpts carry unit ID, range, and text but no locator or reason (src/tychora/contracts/evidence.py:123-125), despite a reason being generated during reranking (src/tychora/retrieval/rerank.py:607-626). Language adapter has no per-language resolve method (src/tychora/ports/language.py:238-246). These reduce explanation and extension capacity, respectively.
  • Full request-history retention has a constructor flag (src/tychora/adapters/sqlite/history.py:45-61), but default query service construction does not expose it (src/tychora/application/query.py:250). This should be a documented opt-in or be removed from the public promise.
  • dashboard=false still has no literal capability in source/discovery. Whether to emit it depends on whether the global design-spec constraint remains binding; it is a small spec conformance task, not a runtime defect.
  • No named code contextual/independent embedding profiles or completed model comparison are evidenced in the reviewed tree. The current evaluation documentation says independently reviewed labels and provisioned models are still required (docs/evaluation.md, “Scores and release use”). Treat this as an uncompleted qualification gate, not proof that retrieval quality is poor.
  • Several contract/CLI deviations remain visible in the audit and should be triaged against intended public API before changing code: --offline semantics, Typer usage-error JSON envelope, output-profile labels/aliases, default_lane handling, and unknown TOML fields. The original report's line references indicate where to start, but this assessment did not reproduce each behavior.

Fixed or overtaken since the review

  • The sole asserted non-asset default-suite failure, missing revision with --original returning NOT_FOUND instead of FORBIDDEN_SCOPE, has a direct fix in e7de140: src/tychora/application/inspection.py:611-614 now invokes _deny() for a missing revision. This was checked in code, not rerun as a test here.
  • Parse reuse, read scope, separate vector candidate pools and matched windows, and reranker asset setup are committed in 71f32ce; the missing-revision correction and PDF fixture provisioning are in e7de140. Findings about their earlier unfinished state are superseded.
  • Earlier failed-suite totals are not current results. Asset-dependent tests remain in ingestion, API, documentation and retrieval suites; run with declared asset variables and report the selected gates.

Historical or unverified release claims

  • “No CI workflow has ever executed,” “Linux never built,” and the reported local frozen binary state are time-sensitive and cannot be established from a code checkout. Recheck CI runs and current artifacts before publishing release claims. The workflows' existence is visible, but execution is an external fact.
  • The review's 2026-10-08 lint/type/format results and 15-minute pytest runs are historical. The reported missing model/tokenizer/Docling assets explain those runs; they do not establish current suite status.
  • Potential GC leaks around pinned evaluation/query generations, restore receipt omissions, incomplete startup integrity checks, compressed archive limits, and mixed-scope importer behavior merit targeted follow-up. The review identified concrete code paths, but this bounded assessment did not reproduce failure scenarios at e7de140.

Remaining review inventory for targeted triage

These are substantive points from the original audit that were not individually rerun here. They should stay in an issue backlog with the original audit's file references, not be published as newly verified defects.

  • Interfaces and configuration: asynchronous open may block the event loop; delegated clients read canonical SQLite directly; MCP tool descriptions lack input examples; HTTP oversized-body code may differ from the registered error; source definition documents may silently accept unknown fields; role IDs can be overridden; formatting settings omit labels/aliases and ignore locale; inspect config may redact origins even for local owners; schema-node budget is shared across a pack; profile error messages conflate incompatible causes.
  • Publication and storage: index batches are inserted ready rather than visibly pending/building; GC may ignore pinned evaluation/query generations; receipt checks occur before the activation transaction; lexical binding publication inserts one row and bumps epoch per row; payloads use flat CAS paths under artifacts/, with sibling staging/ under the workspace root. The latter layout choices are spec differences, while the first three need a crash/recovery test to establish practical impact.
  • Retrieval: latest-edition ordering mixes effective and publication dates; permissive unknown-date editions are merged into selected winners; image ANN uses an 80-record cap rather than the specified 24; linked source units receive visual votes; PDF/code neighbour expansion is restricted; anchor origins use a different vocabulary; requests cannot lower some graph/visual limits and ignore previous-unit IDs; graph budget truncation can mark overall coverage partial; unit/document ranking metrics are narrower than the spec. Each requires a fixture tied to the expected contract before assigning priority.
  • Code retrieval: import binding uses short-name matching across files, so its rule name can overclaim provenance; overload keys always use start byte; sibling admission may spend slots on already ranked hits; repository capture commit/dirty status is not queryable; adapter dialect lists are hard-coded; structural relation view is not typed on traversal; benchmark telemetry omits several requested counters. These are a mix of traceability, quality, and evaluation gaps.
  • Recovery and distribution: restore receipts do not enumerate unavailable channels and interrupted jobs; startup checks cover less than explicit health; backup manifest omits several inventory fields; removal returns aggregate rather than per-binding outcomes; verification proofs live outside export; no decompression-ratio cap; compare requested kill/crash acceptance cases with the later final frozen qualification before calling them missing; Linux missing-Git behavior is not exercised by the macOS-only test; machine-readable SBOM and independently executed baseline qualification remain to verify. The review also noted disclosed dependency advisories; check the current audit before making a present-tense statement.

Spec discrepancies to decide rather than fix mechanically

The original review mixes behavioral defects with choices that may be intentional: workspace.toml versus the spec filename; ip versus cosine HNSW with normalized vectors; collection/artifact/staging naming; reranker model version; receipt-verification transaction ordering; fewer ingestion stage names; LanguageAdapter.resolve delegation; absent optional metrics or named embedding profiles. Compare each to the current user-facing contract and update the spec or implementation together. The example profile in the original design spec reportedly fails under current preset merge rules; that should be tested separately before changing merge behavior.

The operational guide has been corrected for retention and trace availability. The engine defects listed above remain open; this documentation update does not claim to repair them.