knowledge_base.record

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The record id, as the file name and `majordomus://knowledge/<id>` carry it."
    }
  },
  "required": [
    "id"
  ],
  "description": "Which knowledge record: the input of `knowledge_base.record`. The id is the file name\nand the identity the index keys the record by, so one string names it on every surface.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecordInput;\nlet input: KnowledgeRecordInput = serde_json::from_str(r#\"{\"id\":\"e1-0123456789ab\"}\"#).unwrap();\nassert_eq!(input.id, \"e1-0123456789ab\");\n// a key the input does not declare is refused, never ignored\nassert!(serde_json::from_str::<KnowledgeRecordInput>(r#\"{\"id\":\"x\",\"uri\":\"y\"}\"#).is_err());\n```",
  "title": "KnowledgeRecordInput"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The record id."
    },
    "uri": {
      "type": "string",
      "description": "`majordomus://knowledge/<id>`."
    },
    "path": {
      "type": "string",
      "description": "Repository-relative path."
    },
    "source_class": {
      "type": "string",
      "description": "The source class that discovered it: `candidates` or `curated`."
    },
    "class": {
      "type": "string",
      "description": "`fact`, `convention`, `constraint`, `memory` or `lesson`."
    },
    "status": {
      "type": "string",
      "description": "`candidate`, `verified` or `superseded`."
    },
    "epistemics": {
      "type": "string",
      "description": "`observed`, `inferred` or `decided`."
    },
    "origin": {
      "type": "string",
      "description": "`authored` or `extracted`; empty when the record carries no provenance."
    },
    "date": {
      "type": "string",
      "description": "The day the record reached its status."
    },
    "title": {
      "type": "string",
      "description": "The assertion."
    },
    "derived_from": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ResolvedReference"
      },
      "description": "Every `provenance.derived_from` reference, resolved, in the record's order."
    },
    "relations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ResolvedRelation"
      },
      "description": "Every `relations` entry, resolved, in the record's order."
    },
    "superseded_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "The record that replaced this one, when the status is `superseded`."
    },
    "resolved": {
      "type": "boolean",
      "description": "True when every reference above resolved. The one bit a reviewer reads first.",
      "default": false
    },
    "content": {
      "type": "string",
      "description": "The whole file, front matter and body."
    }
  },
  "required": [
    "id",
    "uri",
    "path",
    "source_class",
    "class",
    "status",
    "epistemics",
    "date",
    "title",
    "content"
  ],
  "description": "One knowledge record, with every reference it names resolved.\n\n`objects.get` already serves the same file as metadata and content. What this adds is\nthe resolution: which of the record's references answer, through which reader, and which\ndangle — the question a reviewer asks before promoting a candidate, and the question the\nintegrity validator asks of every record.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::KnowledgeRecord;\nlet r: KnowledgeRecord = serde_json::from_str(r#\"{\n  \"id\": \"e1-0123456789ab\", \"uri\": \"majordomus://knowledge/e1-0123456789ab\",\n  \"path\": \".ai/repo/knowledge/candidates/e1-0123456789ab.md\", \"source_class\": \"candidates\",\n  \"class\": \"convention\", \"status\": \"candidate\", \"epistemics\": \"decided\", \"origin\": \"extracted\",\n  \"date\": \"2026-09-12\", \"title\": \"An assertion\", \"resolved\": true, \"content\": \"---\\n---\\n\"\n}\"#).unwrap();\nassert!(r.derived_from.is_empty(), \"a record that names nothing has nothing to resolve\");\nassert_eq!(r.superseded_by, None, \"and is not superseded\");\n```",
  "title": "KnowledgeRecord",
  "$defs": {
    "ResolvedReference": {
      "type": "object",
      "properties": {
        "reference": {
          "type": "string",
          "description": "The reference as written: `<prefix>:<value>`."
        },
        "resolution": {
          "$ref": "#/$defs/ReferenceResolution",
          "description": "How it resolved."
        },
        "target": {
          "type": [
            "string",
            "null"
          ],
          "description": "What it resolved to: a URI for an object, a path for a file, the reader that vouched\nfor an external reference. Absent when nothing did."
        },
        "reason": {
          "type": "string",
          "description": "Why it did not resolve, when it did not."
        }
      },
      "required": [
        "reference",
        "resolution"
      ],
      "description": "One `derived_from` reference of a record, with how it resolved and against what.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::{ReferenceResolution, ResolvedReference};\nlet r: ResolvedReference = serde_json::from_str(\n    r#\"{\"reference\":\"task:none\",\"resolution\":\"missing\",\"reason\":\"`none` is not a task\"}\"#,\n).unwrap();\nassert_eq!(r.resolution, ReferenceResolution::Missing);\nassert_eq!(r.target, None);\n```"
    },
    "ReferenceResolution": {
      "oneOf": [
        {
          "type": "string",
          "const": "object",
          "description": "An object of the index: the `target` is its URI, or its path for a file."
        },
        {
          "type": "string",
          "const": "external",
          "description": "Vouched for by the ledger, the task store or git: a session, a task, a decision, a commit."
        },
        {
          "type": "string",
          "const": "historical",
          "description": "A `file:` or `test:` the tree no longer holds and git history does: cited before the\nfile was deleted, or pinned as `file:<path>@<commit>`. The `target` is the blob that\nanswers, `<commit>:<path>`, which `git show` reads."
        },
        {
          "type": "string",
          "const": "missing",
          "description": "Nothing answers to it. A dangling reference is the integrity validator's finding."
        }
      ],
      "description": "How a typed reference resolved.\n\nFour words and no fifth: a reference names an object of the index, or something only\nthe ledger and git can vouch for, or a file the tree no longer holds and git history\ndoes, or nothing. `external` is not a weaker `object` — a commit or a task is exactly as\nreal as a rule — it says which reader answered; `historical` resolves as well, and is\nnamed apart so a reader sees which provenance outlived its file (I1987).\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::ReferenceResolution;\nlet r: ReferenceResolution = serde_json::from_str(r#\"\"external\"\"#).unwrap();\nassert_eq!(r, ReferenceResolution::External);\nassert!(r.resolves(), \"vouched for by the ledger or git is resolved\");\nassert!(!ReferenceResolution::Missing.resolves());\n```"
    },
    "ResolvedRelation": {
      "type": "object",
      "properties": {
        "relation_type": {
          "type": "string",
          "description": "`relates_to`, `depends_on`, `documents`, `supports`, `contradicts`, `supersedes` or `derived_from`."
        },
        "reference": {
          "type": "string",
          "description": "The target as written."
        },
        "resolution": {
          "$ref": "#/$defs/ReferenceResolution",
          "description": "How it resolved."
        },
        "target": {
          "type": [
            "string",
            "null"
          ],
          "description": "What it resolved to, when something did."
        },
        "reason": {
          "type": "string",
          "description": "Why it did not resolve, when it did not."
        }
      },
      "required": [
        "relation_type",
        "reference",
        "resolution"
      ],
      "description": "One `relations` entry, resolved the same way.\n\n```\nuse majordomus_cli::capability::builtin::knowledge_base::{ReferenceResolution, ResolvedRelation};\nlet r: ResolvedRelation = serde_json::from_str(\n    r#\"{\"relation_type\":\"relates_to\",\"reference\":\"file:docs/CLI.md\",\"resolution\":\"object\",\"target\":\"docs/CLI.md\"}\"#,\n).unwrap();\nassert_eq!(r.relation_type, \"relates_to\");\nassert!(r.resolution.resolves());\n```"
    }
  }
}