feat(zones): add 'incoming' quarantine zone

[vilosource]

Why

kb had only active|established|archive (enforced by a SQLite CHECK). Downstream, mykb-curator assumed an incoming quarantine zone for unverified LLM/agent-proposed entries that never existed — --zone incoming wrote the JSONL line and then crashed on the CHECK constraint, splitting JSONL vs db (mykb-curator#2; kb gotcha vwpvk7lQ).

What

• types.ts: Zone gains Incoming='incoming' (lifecycle: incoming → active → established; archive out-of-circulation).
• db.ts: SCHEMA_SQL CHECK includes 'incoming'. kb rebuild (unlinks + recreates db from JSONL) is the migration path for existing brains.
• knowledge-store.persistEntry: validates the zone is a known Zone before the JSONL append → invalid zone throws cleanly, no orphaned JSONL line (closes the split-brain hazard for any invalid zone).
• knowledge-store.verifyEntry: on an entry currently in zone incoming, also moves it to active (verifying falsifies the unverified predicate that placed it there). Verify on other zones stays provenance-only.
• cli.ts / kb-load.ts: --zone help + tool enum list incoming.

kb add still defaults to active — quarantine is opt-in via --zone incoming. Design decisions recorded in kb (mykb area): J2N6eo8S (default stays active; opt-in), ei2k4oZF (verify(incoming)→active).

Tests

+6 incoming-zone cases in knowledge-store.test.ts (accepts incoming; default stays active; verify(incoming)→active; verify non-incoming unchanged; invalid zone rejected pre-JSONL). Full suite 655/655, tsc + eslint + prettier clean.

Enables mykb-curator#2.

Summary by CodeRabbit

Release Notes

• New Features

  • Added "incoming" zone support for knowledge base entries. Incoming entries can be verified and automatically promoted to active status.

• Bug Fixes

  • Implemented zone value validation to prevent invalid zones from corrupting knowledge base storage.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR adds an "incoming" zone state to the knowledge base system. Entries can now be created in the incoming zone, which serves as a quarantine state before verification transitions them to active. The change updates the database schema, type definitions, CLI and tool schemas, adds zone validation logic, implements state transitions on verification, and includes comprehensive test coverage.

Changes

Incoming Zone Feature

Layer / File(s)	Summary
Schema, types, and tool definitions src/core/db.ts, src/core/types.ts, src/cli/cli.ts, src/tools/kb-load.ts	Database CHECK constraint now allows incoming; Zone enum includes documentation describing the lifecycle ordering from incoming through active, established, and archive; CLI help and kb-load tool schema expose incoming as a valid zone parameter.
Validation and state transition logic src/core/knowledge-store.ts	persistEntry validates zone values against the Zone enum and throws EntryValidationError before appending to prevent JSONL corruption; verifyEntry transitions incoming entries to active while setting provenance to verified; non-incoming zones receive provenance-only updates.
Test coverage for incoming zone behavior tests/core/knowledge-store.test.ts	New test suite covers incoming zone persistence consistency between JSONL and database, default zone behavior, state transitions on verification, zone preservation for non-incoming entries, and validation error prevention before writes.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant persistEntry
  participant verifyEntry
  participant updateEntry
  Client->>persistEntry: addFact(entry with zone)
  persistEntry->>persistEntry: validate zone in Zone enum
  alt zone is invalid
    persistEntry-->>Client: throw EntryValidationError
  else zone is valid
    persistEntry->>updateEntry: appendEntry + dbUpsert
  end
  Client->>verifyEntry: verifyEntry(entryId)
  verifyEntry->>verifyEntry: check if zone is Incoming
  alt zone is Incoming
    verifyEntry->>updateEntry: update zone to Active + provenance to Verified
  else zone is not Incoming
    verifyEntry->>updateEntry: update provenance to Verified only
  end
  updateEntry-->>Client: entry updated

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• kb zone vocabulary is fictional: incoming/archived never match real data; agent proposals not quarantined mykb-curator#2: The PR implements the missing "incoming" zone by adding it to the database schema CHECK constraint, Zone enum, CLI help, tool schemas, and verification logic to enforce zone validation and state transitions.

Poem

A quarantine zone for facts to rest, 🐰
Before verification puts them to the test,
From incoming flows to active they shall bloom,
With provenance sealed—no JSONL gloom! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(zones): add 'incoming' quarantine zone' clearly and specifically summarizes the main change: introducing a new 'incoming' zone to the zones feature.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}