catproof. docs
Architecture / CATPROOF DOCUMENTATION

The reconciliation architecture

CatProof reconciliation separates collection, source evidence, canonical identity, human review and durable business decisions through explicit transactional boundaries.

Five responsibilities, one identity spine

1 / Read supported sources outside transactions↓ validate scope, completeness and generation2 / Save observations + original source IDs↓ deterministic candidates, no automatic merge3 / Review evidence and business context↓ authorize + lock + compare revisions4 / Commit binding + decision + audit together↓5 / Read ownership, history and explicit relationships

Non-negotiable invariants

  • Every agent observation has exactly one tenant-scoped canonical binding at commit.
  • Source observations and business owner/purpose/lifecycle decisions have separate authority.
  • No name-based automatic merge; no hidden movement of an unselected identity.
  • Provider fetches happen outside database transactions. Authorization and source generation are checked again before applying results.
  • Review, binding changes and audit events commit atomically.
  • Seeded and non-seeded records remain separate.
  • Related assets and observed runtime behavior are distinct concepts.

Read model

The current engine derives a queue from the authenticated workspace snapshot and saved review rows. It uses allowlisted evidence, qualified identity rules and bounded pair examination. The relationship graph is another read-only projection of stored associations; it is not a second authority or a separate graph database.

Write model

A decision command rechecks authorization and workspace scope under the registry writer lock. It validates expected review revision, recomputed fingerprint, source eligibility, selected identity and exact destination decisions. A binding move increments its monotonic revision. The latest review and successive audit events share the commit boundary. See transaction and concurrency details.

Failure model

Provider failures retain prior observations. A missing scan result is not deletion proof; adapter completeness semantics determine absence state. A review conflict asks for fresh human review. Audit failures roll back the associated mutation. PostgreSQL availability is required; there is no silent fallback to SQLite.

Current versus target architecture

Current matching and refresh scheduling are request-driven. Inventory reads materialize a workspace. A durable worker queue, transactional outbox, incremental candidate indexes and paginated history are planned architecture, not existing components. See the scale design and acceptance gates.

Find a guide