{
  "$schema": "https://maksim.sh/knowledge/schemas/protocol.schema.json",
  "id": "https://maksim.sh/knowledge/protocols/temporal-knowledge.json",
  "type": "KnowledgeProtocol",
  "name": "Temporal Knowledge",
  "slug": "temporal-knowledge",
  "version": "1.0.0",
  "status": "experimental",
  "summary": "Represent knowledge as sourced assertions with transaction time, validity intervals, supersession, and policy weights.",
  "purpose": "Prevent a knowledge base from flattening changing claims into timeless truth by preserving when an assertion was recorded, when it applies, what supersedes it, and how its influence was calculated.",
  "authority": {
    "instruction_priority": "reference-only",
    "may_override_system": false,
    "may_override_user": false,
    "requires_policy_compliance": true
  },
  "use_when": [
    "Facts change over time or have bounded validity periods.",
    "Multiple sources assert different values for the same entity and attribute.",
    "An agent must answer current-state, history, or as-of questions."
  ],
  "avoid_when": [
    "A policy weight would be misrepresented as an objective probability of truth.",
    "The domain requires a formally validated temporal or probabilistic model not supplied here."
  ],
  "input_schema": {
    "type": "object",
    "required": ["operation", "assertions"],
    "properties": {
      "operation": { "enum": ["assert", "retract", "corroborate", "query-current", "query-as-of", "query-history"] },
      "assertions": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["entity", "attribute", "value", "source"],
          "properties": {
            "entity": { "type": "string" },
            "attribute": { "type": "string" },
            "value": {},
            "source": { "type": "string" },
            "valid_from": { "type": ["string", "null"] },
            "valid_until": { "type": ["string", "null"] }
          }
        }
      },
      "as_of": { "type": ["string", "null"] }
    },
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "required": ["transaction", "current_assertions", "conflicts", "weight_semantics"],
    "properties": {
      "transaction": {
        "type": "object",
        "required": ["id", "recorded_at"],
        "properties": {
          "id": { "type": "string" },
          "recorded_at": { "type": "string" }
        }
      },
      "current_assertions": { "type": "array", "items": { "type": "object" } },
      "conflicts": { "type": "array", "items": { "type": "object" } },
      "history": { "type": "array", "items": { "type": "object" } },
      "weight_semantics": { "const": "policy-heuristic-not-truth-probability" }
    },
    "additionalProperties": false
  },
  "procedure": [
    { "step": 1, "operation": "Store each assertion as an append-only entity-attribute-value event with source and transaction time." },
    { "step": 2, "operation": "Store valid-from and valid-until separately from the time the system recorded the assertion." },
    { "step": 3, "operation": "Represent retraction and corroboration as new events rather than destructive updates to history." },
    { "step": 4, "operation": "Treat a different value for the same entity and attribute as an explicit conflict candidate, not automatic semantic contradiction." },
    { "step": 5, "operation": "Resolve current or as-of views from ordered events and declared validity boundaries." },
    { "step": 6, "operation": "Expose source trust, decay, corroboration, and anomaly thresholds as inspectable policy parameters."
    }
  ],
  "invariants": [
    "Transaction time and valid time remain distinct.",
    "History is append-only and prior assertions remain inspectable.",
    "Every assertion retains source provenance.",
    "Weights and lifecycle labels are explicitly identified as policy heuristics."
  ],
  "failure_modes": [
    {
      "mode": "A different string value is treated as a semantic contradiction without normalization or domain logic.",
      "mitigation": "Label it a conflict candidate and apply domain-specific equivalence or contradiction rules separately."
    },
    {
      "mode": "Recency or repeated assertion is interpreted as truth.",
      "mitigation": "Keep source quality, corroboration independence, evidence, and policy weight as separate fields."
    }
  ],
  "composition": {
    "before": ["reality-check", "evidence-ladder"],
    "after": ["disagreement-preserving-convergence"]
  },
  "provenance": [
    {
      "title": "Nexus Gravitas",
      "url": "https://github.com/Gonzih/nexus-gravitas",
      "relationship": "Implementation source",
      "qualification": "The contract generalizes the implementation while explicitly labeling its weighting constants and anomaly thresholds as policy."
    },
    {
      "title": "Gravitas weighting implementation",
      "url": "https://github.com/Gonzih/nexus-gravitas/blob/main/src/weight.ts",
      "relationship": "Heuristic provenance",
      "qualification": "Corroboration, contradiction, floor, ceiling, and decay values are implementation constants, not calibrated probabilities."
    }
  ],
  "limitations": [
    "Entity resolution, semantic normalization, and independent-source detection are outside this contract.",
    "Temporal correctness depends on trustworthy clocks and correctly modeled validity intervals.",
    "Policy weights require domain evaluation before consequential use."
  ],
  "example": {
    "input": {
      "operation": "assert",
      "assertions": [
        {
          "entity": "service/api",
          "attribute": "protocol-version",
          "value": "2",
          "source": "deployment-discovery",
          "valid_from": "2026-08-14T00:00:00Z",
          "valid_until": null
        }
      ],
      "as_of": null
    },
    "output": {
      "transaction": { "id": "tx-42", "recorded_at": "2026-08-14T00:01:00Z" },
      "current_assertions": [
        { "entity": "service/api", "attribute": "protocol-version", "value": "2", "source": "deployment-discovery" }
      ],
      "conflicts": [],
      "history": [],
      "weight_semantics": "policy-heuristic-not-truth-probability"
    }
  },
  "rights": {
    "copyright_holder": "Maksim Soltan",
    "copyright_year": 2026,
    "license": "All Rights Reserved",
    "attribution": "Maksim Soltan — https://maksim.sh/",
    "intended_machine_use": ["indexing", "retrieval", "citation", "protocol selection"]
  }
}