HTTP API: knowledge_base

Where the age of a candidate in the review queue was read from. A candidate's date is the day of the evidence it came from, deliberately, so that the same evidence yields the same bytes; the day it entered the queue is a different fact and is read from the ledger first, then from git, and only then from the record.

use majordomus_cli::capability::builtin::knowledge_base::AgeSource;
let from_ledger: AgeSource = serde_json::from_str(r#""derivation""#).unwrap();
assert_eq!(from_ledger, AgeSource::Derivation);
assert!(AgeSource::Derivation < AgeSource::Date, "the ledger is asked before the record");

One candidate record awaiting review: what a reader needs to decide whether to open it.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeCandidate;
let c: KnowledgeCandidate = serde_json::from_str(r#"{
  "id": "e1-0123456789ab", "uri": "majordomus://knowledge/e1-0123456789ab",
  "path": ".ai/repo/knowledge/candidates/e1-0123456789ab.md", "class": "convention",
  "status": "candidate", "epistemics": "decided", "title": "Tests run in disposable repositories",
  "date": "2026-09-12", "derived_from": ["session:e1"], "episode": "e1",
  "freshness": "unknown", "freshness_reason": "no timestamp", "age_source": "date"
}"#).unwrap();
assert_eq!(c.episode, "e1");
assert_eq!(c.branch, None, "an episode this checkout never saw has no branch, and says so");

The candidates awaiting review, against the policy's cap.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeCandidates;
let empty: KnowledgeCandidates = serde_json::from_str(
    r#"{"total":0,"on_this_branch":0,"unattributed":0,"branch":"master","candidates":[],"over_cap":false}"#,
).unwrap();
assert_eq!(empty.total, 0, "an empty queue is an answer");
assert_eq!(empty.cap, None, "and a policy without the key declares no cap");

The records under one subject: every candidate awaiting review and every rejected one, with the episodes behind them (ADR 0118). Recurrence is read here, never written: each record stays one episode's own file, and a group is how several of them read as one thing.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeGroup;
let g: KnowledgeGroup = serde_json::from_str(
    r#"{"about":"lib/a.sh","route":"project","candidates":["e1-a","e2-b"],"episodes":["e1","e2"]}"#,
).unwrap();
assert_eq!(g.episodes.len(), 2, "two episodes observed it");
assert!(g.rejected.is_empty(), "and nobody rejected it");

One knowledge record, with every reference it names resolved.

objects.get already serves the same file as metadata and content. What this adds is the resolution: which of the record's references answer, through which reader, and which dangle — the question a reviewer asks before promoting a candidate, and the question the integrity validator asks of every record.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecord;
let r: KnowledgeRecord = serde_json::from_str(r#"{
  "id": "e1-0123456789ab", "uri": "majordomus://knowledge/e1-0123456789ab",
  "path": ".ai/repo/knowledge/candidates/e1-0123456789ab.md", "source_class": "candidates",
  "class": "convention", "status": "candidate", "epistemics": "decided", "origin": "extracted",
  "date": "2026-09-12", "title": "An assertion", "resolved": true, "content": "---\n---\n"
}"#).unwrap();
assert!(r.derived_from.is_empty(), "a record that names nothing has nothing to resolve");
assert_eq!(r.superseded_by, None, "and is not superseded");

Whether the deriver is still writing, and what it last wrote.

The judgement is ADR 0052's, applied to this writer: while episodes keep closing, a derivation follows every close. It compares episode ids, never line order or timestamps between the two events, because the close derives before it appends session.closed. It is the freshness half of the judgement only; whether the close path and the compaction adapter still call the deriver is read from the source by the shell validator, which is where the source is.

use majordomus_cli::capability::builtin::knowledge_base::KnowledgeStatus;
let fresh: KnowledgeStatus = serde_json::from_str(r#"{
  "present": false, "branch": "master", "closed_without_derivation": 0, "candidates": 0,
  "on_this_branch": 0, "freshness": "unknown", "freshness_reason": "no episode has closed here",
  "judged": false, "stopped_writer": false, "knowledge_on_end": true, "knowledge_on_compact": true
}"#).unwrap();
assert!(!fresh.present, "a fresh clone has no ledger, and that is not a fault");
assert!(!fresh.stopped_writer);

One ledger line that matters to the judgement: when, and which episode.

use majordomus_cli::capability::builtin::knowledge_base::LedgerMark;
let m: LedgerMark = serde_json::from_str(r#"{"ts":"2026-09-12T10:00:00Z","episode":"e1"}"#).unwrap();
assert_eq!(m.episode, "e1");

How a typed reference resolved.

Four words and no fifth: a reference names an object of the index, or something only the ledger and git can vouch for, or a file the tree no longer holds and git history does, or nothing. external is not a weaker object — a commit or a task is exactly as real as a rule — it says which reader answered; historical resolves as well, and is named apart so a reader sees which provenance outlived its file (I1987).

use majordomus_cli::capability::builtin::knowledge_base::ReferenceResolution;
let r: ReferenceResolution = serde_json::from_str(r#""external""#).unwrap();
assert_eq!(r, ReferenceResolution::External);
assert!(r.resolves(), "vouched for by the ledger or git is resolved");
assert!(!ReferenceResolution::Missing.resolves());

One derived_from reference of a record, with how it resolved and against what.

use majordomus_cli::capability::builtin::knowledge_base::{ReferenceResolution, ResolvedReference};
let r: ResolvedReference = serde_json::from_str(
    r#"{"reference":"task:none","resolution":"missing","reason":"`none` is not a task"}"#,
).unwrap();
assert_eq!(r.resolution, ReferenceResolution::Missing);
assert_eq!(r.target, None);

One relations entry, resolved the same way.

use majordomus_cli::capability::builtin::knowledge_base::{ReferenceResolution, ResolvedRelation};
let r: ResolvedRelation = serde_json::from_str(
    r#"{"relation_type":"relates_to","reference":"file:docs/CLI.md","resolution":"object","target":"docs/CLI.md"}"#,
).unwrap();
assert_eq!(r.relation_type, "relates_to");
assert!(r.resolution.resolves());