From 81ef27179bf74f57478cc48012bc72800368efb2 Mon Sep 17 00:00:00 2001 From: George Coles Date: Tue, 15 Sep 2026 02:39:37 -0400 Subject: [PATCH] Add AGENTS.md with repo conventions and technical plans --- AGENTS.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ff30ca8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,21 @@ +# AGENTS.md + +## Repo shape +- Spec-only repo: `rfc.txt` (FRX — Federated Retrieval Exchange, Draft 0.3) is the entire content. No code, README, manifests, tests, CI, or build tooling — don't look for or invent build/lint/test commands. +- `frxd` (Rust: tokio, tantivy, axum, ed25519-dalek) is planned in §7 but does not exist here; treat it as design intent, not current structure. + +## Editing the spec +- Read all of `rfc.txt` before editing; it is the sole source of truth and is deliberately terse. +- Keep the plain-text single-file format. Don't restructure into Markdown files unless asked. +- Invariants I1–I9 (§2) are normative; proposals contradicting them (scores in responses, topic taxonomy, announce stream, dispute messages, replayable broadcast) are out of scope by design. +- Appendix B (Purge Log) is normative: a rejected mechanism may only be re-proposed if the written rationale is addressed. +- §10 Open Issues are known gaps, not oversights (e.g., signature canonicalization blocks Phase-1 interop). Check it before "fixing" something. +- Use the spec's vocabulary — member/querier/responder, citations/receipts/aggregates, source/enrichment members — not client/server or search-engine terms. + +## Technical plans (deliberately not in the RFC) +- Record plans here — not as spec edits — when they are implementation/demo choices rather than protocol surface. +- Demo plan: build a useful end-to-end demo on GDELT and Common Crawl (CC-NEWS; sometimes called "OpenCrawl" in discussion) as enrichment members / backfill seeding. RFC §6 and Appendix A already name both as example derived corpora, so no new mechanisms are required; enrichment members are metadata-only exposure and sit outside the citation market. +- Phase 1 remains the minimal two-node query/response demo (§7); the enrichment demo layers on top of it. +- Language: Rust (settled, matches §7). Decided by the engine requirement, not preference: Tantivy gives in-process Lucene-class BM25 + incremental indexing; C/C++ embedded alternatives are worse (Xapian GPL-2+, CLucene unmaintained, SQLite FTS5 thin), plus single static musl binaries for the install story and memory safety on the untrusted network/crypto path. Don't re-litigate. +- frxd modes (one binary, config toggles, no code required of publishers): querier (broadcast/local-first search), responder (match incoming queries against shared collections, sign), local index (watch dirs, extract text, explicit shared marking per I9). Use RFC terms querier/responder, not "subscriber/publisher". +- Matching accuracy is a project-health concern: start lexical (Tantivy), plan a hybrid cheap lexical gate + optional local embedding rerank (two-stage ingestion, Appendix A); embedding model stays local and replaceable (I2/I5).