Skip to content
Khala Khala

Archon

Archon is the authority window over domain truth: the one place a person or an agent asks “what is true here, and on whose authority?” and gets an answer grounded in a governed source, with its freshness and confidence stated plainly.

Non-engineers constantly touch the system’s preconditions in meetings (limits, policies, invariants), but have no fast way to confirm the current value. They corner an engineer, or trust a stale Notion page, and decisions pile up on wrong premises. Archon can’t be always correct, but it is calibrated: it never presents a soft or stale answer as a hard one. It reads each value from its source, a code constant, at query time, so it can’t go stale. What it knows, it states plainly; what it can’t verify, it declines to answer.

In short: domain value, invariant, and authority governance, built on Nexus. It guards against the failure mode where a model confidently invents what your own business rules mean.

› max retry limit? READ CONSTANT config/limits.py:12 MAX_RETRIES = 5 content-hash 3f9a2c ✓ matches approved GROUNDED ANSWER MAX_RETRIES = 5 → config/limits.py:12 read at query time · calibrated ✓ VERIFIED · no drift

Core concepts

  • Concepts are the spine; facts hang off them. A registry of terms / actors / objects (ubiquitous language) is the foundation. Values, invariants, and requirements are claims that reference those concepts.
  • Claim. A new resource kind. Its kind distinguishes goal | invariant | requirement; value-bearing claims carry a value that points at a value_source (e.g. a code_constant).
  • Reliability = calibration (honesty). The achievable, sufficient definition of trust: the system never lies — it does not present a soft or stale answer as a hard one. (This is precisely what Notion cannot do.)
  • Point, don’t copy (anti-shelfware). Values are never copied into storage where they rot. A claim points at the authoritative source and reads the current value on demand, tagging freshness.
  • Claim ↔ code drift. Each code symbol is hashed by (file path + symbol name); when the hash changes after a claim’s last-verified commit, the claim is flagged (e.g. claim_code_drift).
  • System decides, LLM narrates. (Inherited from Nexus.) Classification, verification, and routing are deterministic code; the LLM only proposes and summarizes — never final authority.

Quickstart

Archon is the nexus/claims/ package inside the Nexus repo, on master. It reuses the Nexus stack (PostgreSQL). The code-value resolver reads constants from a target repo set via config.yaml → code_source.repo_path.

1. Bring up Nexus

Terminal window
git clone https://github.com/LivingLikeKrillin/khala.git
cd khala
task up          # starts containers, runs DB migrations, pulls the model (see the Nexus quickstart for the no-Task path)

Then set code_source.repo_path in nexus/config.yaml to the codebase whose constants you want Archon to read. Leave it empty and value lookup stays disabled.

2. Seed your domain claims

claims.yaml defines invariants/values, each pointing at a value_source (a code constant). Seeding snapshots the current code hash of each source.

Terminal window
nexus claim-seed claims.yaml

(Note: the top-level claims.yaml shipped in the repo is a seed example, not the package.)

3. Ask for a current value

Terminal window
nexus claim-value Basic

Archon reads the value from the code constant at query time and answers with confidence + freshness — asserting the certain, declining on the unknown.

How-to

Look up a domain value

Terminal window
nexus claim-value Basic        # e.g. "basic tier max projects?"
nexus claim-value Task         # task limit, etc.

Returns the current value with a calibrated label: high-confidence when read cleanly from the code constant, an honest “couldn’t verify” otherwise, and a drift warning if the source changed since last verified.

Derive grade / role authority (emergent questions)

Terminal window
nexus grade-authority --enum GradeType
nexus grade-authority --enum GradeType --subpath some/scope

Extracts permission gates from code (via free tree-sitter AST, no CodeQL) and derives, by complement, which actions each grade is blocked from. Fixed-gate complements are reported as certain (high); “action-guard vs filter” semantics are flagged as needing confirmation (medium) — honestly distinguished.

Query from an AI agent (MCP)

Archon exposes MCP tools so agents answer domain questions from the governed source instead of guessing:

  • archon_claim_value(concept, tenant, classification_max) — current value of a concept’s invariant/value.
  • archon_grade_authority(grade, enum_name, subpath) — emergent/complement authority questions (“what can MEMBER do?”).

Reference

  • Repo: github.com/LivingLikeKrillin/khala, branch master.
  • Package: nexus/claims/ (seed.py, value_query.py, grade_authority.py, answer.py, repository.py). CLI in nexus/cli.py; HTTP in nexus/api.py; MCP tools in nexus/mcp/server.py.