An evidence-first knowledge architecture for humans and AI agents.
Source provenance, governed retrieval, citations, and fail-closed access by design.
Important
This is the public design surface for the DOO MADE knowledge system. It contains architecture, contracts, synthetic examples, and agent guidance. It does not contain private evidence, credentials, infrastructure identities, evaluation questions, backups, or deployment state.
AI agents can produce convincing answers long before they can produce trustworthy ones.
A useful company knowledge system must answer four questions before it generates a response:
- Where did this evidence come from?
- Is the requester allowed to retrieve it?
- Is it still active and current?
- Can the answer point back to a real source location?
This repository documents a practical architecture built around those questions. Original source systems remain authoritative. The knowledge database is a governed query index, not a replacement for source evidence.
The architecture separates four jobs:
| Layer | Responsibility | Core rule |
|---|---|---|
| Approved sources | Documents, media, conversations, and meeting evidence | Nothing enters without explicit authorization |
| Governance | Stable identity, checksums, provenance, deletion, and policy | Invalid metadata fails closed |
| Governed index | PostgreSQL records, structural chunks, full-text search, and pgvector | Filters never replace authorization |
| Authorized answers | Fusion, local reranking, relevance gates, and citations | Weak evidence produces abstention, not invention |
Read the deeper architecture note in docs/ARCHITECTURE.md.
| Path | Purpose |
|---|---|
AGENTS.md |
Operating contract for AI coding agents |
.github/SECURITY.md |
Private vulnerability-reporting policy |
docs/ARCHITECTURE.md |
Components, data lifecycle, and portability |
docs/SECURITY_MODEL.md |
Threat boundaries and fail-closed invariants |
docs/SOURCE_WIRE_ADAPTER_STORY_1.md |
Prepared design for the read-only Source Wire adapter seam |
schemas/authorized-evidence-snapshot.schema.json |
Complete provider-owned snapshot required before Source Wire mapping |
src/index.ts |
Private-package, synthetic-only KnowledgeProvider v1 adapter |
tests/source-wire-adapter.test.ts |
Ordered search, exact fetch, authority separation, and fail-closed tests |
schemas/evidence-record.schema.json |
Normalized evidence and provenance contract |
schemas/retrieval-response.schema.json |
Citation-first retrieval response contract |
examples/ |
Synthetic, publication-safe contract examples |
scripts/validate_repo.py |
Zero-dependency repository validator |
The model does not get first access to the question. Retrieval establishes the evidence boundary first:
- Bind the requester to an authorized scope.
- Retrieve candidates with full-text and vector search.
- Fuse independent rankings.
- Rerank evidence locally where practical.
- Reject weak support.
- Construct source-ready citations.
- Permit optional synthesis only inside an approved privacy boundary.
A query with no authorized evidence must return an honest abstention.
The system returns evidence records and citations before it asks any model to write prose.
Every record carries a stable source identity, checksum, source timestamp, content type, and citation-ready locator. Provenance is not optional metadata added later.
Project names and UI filters are not security boundaries. Runtime access is tied to a least-privilege identity and an explicit entitlement.
When source evidence is deleted, active retrieval views stop exposing its derived artifacts and chunks. Physical retention can follow a separate policy.
Real questions are kept in protected evaluation sets outside Git. Public fixtures are synthetic. Ranking changes must survive unseen challenge cases before promotion.
The index accelerates retrieval. It does not silently become the master copy of a document, meeting, message, or media file.
The boundary is deliberate:
Safe to publish
- Architecture and design principles
- Interface and schema contracts
- Synthetic examples
- Generic validation tools
- Agent contribution guidance
Must remain private
- Business documents and extracted evidence
- Credentials, endpoints, and database identities
- Real evaluation questions and reports
- Embeddings, corpora, caches, and model artifacts
- Backups, recovery files, and deployment receipts
See docs/SECURITY_MODEL.md before contributing anything that resembles runtime data.
Source Wire is a separate governed-memory layer. This knowledge base remains an optional external evidence system around it.
The planned integration is read-only:
- An owner-controlled adapter implements Source Wire's authoritative
KnowledgeProvider v1contract against the knowledge-base retrieval surface. - Source Wire policy calls that adapter with an authorized identity, capability, and namespace.
- The adapter returns evidence and provenance. It does not expose database access.
- Provider evidence may support a pending memory candidate, but it cannot approve or promote trusted memory.
- Source Wire does not write evidence into this knowledge base, and no private data flows into this public documentation repository.
@source-wire/contracts@0.2.0 is now the stable published contract dependency.
This repository includes a private, publication-safe synthetic adapter package
that imports that exact release and maps a provider-owned authorized evidence
reader into KnowledgeProvider v1. It contains no live database connection,
credential, endpoint, entitlement engine, ranking implementation, or real
evidence. Source Wire still does not include live knowledge connectors.
Start with AGENTS.md, then read the two documents in this order:
Before proposing a change, an agent must be able to state:
- Which trust boundary changes
- Which invariant protects that boundary
- Which schema or synthetic fixture changes
- How the change is validated
- Why no private operating data enters Git
Validate the repository with:
python3 scripts/validate_repo.py
npm ci
npm testCurrent release: public reference architecture and contracts.
Current integration boundary: the synthetic adapter and complete authorized
snapshot contract are implemented locally against
@source-wire/contracts@0.2.0. Cross-repository conformance must still prove
the unchanged Source Wire local CLI can load the packed adapter and release
synthetic evidence only after its protected audit and receipt path.
Planned public work:
- System architecture and trust-boundary diagrams
- AI-agent operating contract
- Evidence and retrieval schemas
- Synthetic examples and repository validation
- Read-only Source Wire adapter design and risk-ordered story slices
- Synthetic read-only Source Wire
KnowledgeProvider v1adapter implementation - Live owner-controlled knowledge-base reader
- Sanitized reference ingestion path
- Reproducible local evaluation harness
- Runnable starter deployment after security review
This roadmap is intentionally staged. The public repo will not receive a hurried copy of the private production implementation.
Publish the pattern. Protect the evidence.
The goal is not to make another chatbot wrapper. The goal is to make evidence retrieval understandable, governable, testable, and useful to both people and software agents.
Issues and focused pull requests are welcome. Read CONTRIBUTING.md and AGENTS.md first.
Report vulnerabilities through the private security process, never through a public issue.
Never submit real company evidence, secrets, internal endpoint names, production identifiers, private benchmark questions, or generated embeddings.
Apache License 2.0. See LICENSE.
The license applies to the public material in this repository. It does not grant access to any private DOO MADE data, infrastructure, or unpublished implementation.