knowledge_base.status

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "Freshness": {
      "description": "How old a record is, judged against `session.freshness` in the policy.\n\nThis is the second of two independent judgements every record carries, and it exists\nbecause the first one cannot answer this question. `Divergence` says where a record's\ncommit sits relative to HEAD; `advanced` means that commit is an ancestor of this one,\nwhich sounds like agreement and is identically true on the day the record is written and\na month later. Between 2026-09-05 and 2026-09-11 this repository served a handover that\nwas `advanced` and six days dead, and every surface that read this model — MCP, the HTTP\nAPI, the Cockpit — presented its `Next Action` as the thing to do (ADR 0052).\n\nThe thresholds are policy and are read, never restated here: a constant in this file\nwould be a second source of truth for a number the policy owns, and a repository whose\npolicy predates the key is reported as `Freshness::Unknown` naming the missing key\nrather than judged against a default nobody declared.\n\nThe five words divide into two groups, and the division is the one a caller acts on:\n`fresh` and `aging` are current and may be presented as the instruction, `stale` and\n`invalid` must be shown as history, and `unknown` is neither — a record nobody can date\nis not thereby an old record, and treating it as one would quietly discard a briefing\nthat is perfectly good. `Freshness::history` is that division, and it is the only\nplace it is decided.\n\n```\nuse majordomus_cli::capability::builtin::continuity::Freshness;\n\n// the two renderings are one value: the serialised word is the word `as_str` gives,\n// so a reader who met `stale` from MCP and from the command line met one fact\nlet stale = serde_json::to_value(Freshness::Stale).unwrap();\nassert_eq!(stale, serde_json::json!(\"stale\"));\nassert_eq!(stale.as_str(), Some(Freshness::Stale.as_str()));\n\n// and the division a caller acts on: absence of a judgement is not a bad judgement\nassert!(Freshness::Stale.history() && Freshness::Invalid.history());\nassert!(!Freshness::Unknown.history(), \"undated is not old\");\nassert!(!Freshness::Fresh.history() && !Freshness::Aging.history());\n```",
      "oneOf": [
        {
          "const": "fresh",
          "description": "Inside `session.freshness.fresh_minutes`. Current; act on it.",
          "type": "string"
        },
        {
          "const": "aging",
          "description": "Between the two thresholds. Still current, but its age is worth stating.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "At or beyond `session.freshness.stale_minutes`. History, never current.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Nothing to judge it by: no timestamp, or no thresholds declared.",
          "type": "string"
        },
        {
          "const": "invalid",
          "description": "A timestamp that does not parse, or one in the future.",
          "type": "string"
        }
      ]
    },
    "LedgerMark": {
      "description": "One ledger line that matters to the judgement: when, and which episode.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::LedgerMark;\nlet m: LedgerMark = serde_json::from_str(r#\"{\"ts\":\"2026-09-12T10:00:00Z\",\"episode\":\"e1\"}\"#).unwrap();\nassert_eq!(m.episode, \"e1\");\n```",
      "properties": {
        "episode": {
          "description": "The episode the line is about; empty when the line names none.",
          "type": "string"
        },
        "ts": {
          "description": "The line's timestamp, RFC 3339 in UTC.",
          "type": "string"
        }
      },
      "required": [
        "ts"
      ],
      "type": "object"
    }
  },
  "description": "Whether the deriver is still writing, and what it last wrote.\n\nThe judgement is ADR 0052's, applied to this writer: while episodes keep closing, a\nderivation follows every close. It compares episode ids, never line order or timestamps\nbetween the two events, because the close derives before it appends `session.closed`.\nIt is the freshness half of the judgement only; whether the close path and the\ncompaction adapter still call the deriver is read from the source by the shell\nvalidator, which is where the source is.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::KnowledgeStatus;\nlet fresh: KnowledgeStatus = serde_json::from_str(r#\"{\n  \"present\": false, \"branch\": \"master\", \"closed_without_derivation\": 0, \"candidates\": 0,\n  \"on_this_branch\": 0, \"freshness\": \"unknown\", \"freshness_reason\": \"no episode has closed here\",\n  \"judged\": false, \"stopped_writer\": false, \"knowledge_on_end\": true, \"knowledge_on_compact\": true\n}\"#).unwrap();\nassert!(!fresh.present, \"a fresh clone has no ledger, and that is not a fault\");\nassert!(!fresh.stopped_writer);\n```",
  "properties": {
    "age_minutes": {
      "description": "That age in whole minutes, when it could be measured.",
      "format": "int64",
      "type": [
        "integer",
        "null"
      ]
    },
    "branch": {
      "description": "The branch this checkout is on, or `DETACHED`.",
      "type": "string"
    },
    "candidates": {
      "description": "How many records carry `status: candidate` under the candidates class.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "closed_without_derivation": {
      "description": "How many closed episodes in this ledger no `knowledge.derived` line names.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "findings": {
      "description": "What a reader should know: why the judgement was withheld, or what it found.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "freshness": {
      "$ref": "#/$defs/Freshness",
      "description": "How old the newest closed episode is, judged against `session.freshness`."
    },
    "freshness_reason": {
      "description": "Why it was judged that way. Never empty.",
      "type": "string"
    },
    "judged": {
      "description": "Whether the stopped-writer judgement was made at all. False, with the reason among\n`findings`, while no episode has closed here, while the switch is off, or while no\nderivation has yet run in this checkout.",
      "type": "boolean"
    },
    "knowledge_on_compact": {
      "description": "`session.knowledge_on_compact`, likewise.",
      "type": "boolean"
    },
    "knowledge_on_end": {
      "description": "`session.knowledge_on_end`, as the policy declares it; absent means on.",
      "type": "boolean"
    },
    "last_closed": {
      "anyOf": [
        {
          "$ref": "#/$defs/LedgerMark"
        },
        {
          "type": "null"
        }
      ],
      "description": "The newest `session.closed` line, or `None` when no episode has closed here."
    },
    "last_derived": {
      "anyOf": [
        {
          "$ref": "#/$defs/LedgerMark"
        },
        {
          "type": "null"
        }
      ],
      "description": "The newest `knowledge.derived` line, or `None` when the deriver has never run here."
    },
    "on_this_branch": {
      "description": "How many of those came from an episode on this branch.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "present": {
      "description": "Whether anything is here to judge: a ledger line or a candidate. False in a fresh clone.",
      "type": "boolean"
    },
    "stopped_writer": {
      "description": "The finding: episodes close here and no derivation followed the newest one within\nthe stale threshold. True only when `judged`.",
      "type": "boolean"
    }
  },
  "required": [
    "present",
    "branch",
    "closed_without_derivation",
    "candidates",
    "on_this_branch",
    "freshness",
    "freshness_reason",
    "judged",
    "stopped_writer",
    "knowledge_on_end",
    "knowledge_on_compact"
  ],
  "title": "KnowledgeStatus",
  "type": "object"
}