HarperZ9/telosExplainer, built from commit 5f59ff5All repository explainers

telos

One workbench, and packets that recompute their own claims.

What it does for you

telos is a local workbench for AI work, served to any MCP host as one surface over five tools: gather, index, forum, crucible and telos itself. Its proof packets carry the materials behind a claim, and a verifier recomputes every load-bearing value from those materials. A packet that brings its own MATCH cannot pass with it: the verdict is derived, never read.

Source: README.md at 5f59ff5 (version 0.9.0)

Watch

A passing check can still be wrong (2 min 24 s, narrated, captioned). Telos scores a render against a criterion the loop did not write, so a pass has to be earned. Transcript, sources and recall questions.

Video walkthrough: coming with the next release.

How it works, one step at a time

Scroll, or use the step buttons. The panel follows two of telos's own demos: demo/run.mjs, the loop that explains the idea, and demo/proof.mjs, an agent-action proof packet. Every line is output from telos at commit 5f59ff5, run with Node and no network.

  1. 01

    A criterion the loop did not write

    The loop renders a 4-D cube, a tesseract, and must recover its shape from the picture. The criterion is fixed outside the loop: 16 vertices and 32 edges.

    Two channels read the render independently: a geometric channel and a pixel channel. CERTIFIED needs every channel to agree and to match the criterion.

    Source: demo/run.mjs

  2. 02

    Run A: perceive, check, amplify

    The first reading is not unanimous, so the loop amplifies: it tries more views and a sound channel, each step witnessed. At the fourth step every channel agrees with the criterion and the certificate reads CERTIFIED.

    recheck() then re-derives the verdict from the stored evidence alone and returns true.

    Source: demo/run.mjs, run A

  3. 03

    Run B: a render too small to read

    Run B renders the same cube at 8 by 8 pixels, far too coarse to resolve 16 vertices. The channels never agree, so after the same amplification steps the certificate reads UNVERIFIABLE.

    The loop does not guess. A verifier that cannot fail is not a verifier, and this run is the proof that this one can.

    Source: demo/run.mjs, run B

  4. 04

    A proof packet carries its materials

    node demo/proof.mjs agent-action --demo assembles a packet for one admitted action: the objective, two source refs with content hashes, a context envelope, the route that decided it, the admission decision, the action's side effect, the output digests and the artifact text itself.

    The packet embeds what is needed to recompute its claims, so a verifier never has to trust the run that made it.

    Source: demo/proof.mjs; docs/PROOF-LANES.md

  5. 05

    Verify it from the packet alone

    proof.mjs verify runs a fixed set of checks: required fields, source and context refs, the state model, the packet hash, artifact digests, the join between admission and action, and their order. The verdict is folded out of the checks: MATCH.

    The witness here is a second reader, Emet, that is not installed on this machine. The packet records it as unavailable, so the MATCH stands on the verifier alone and says so.

    Source: demo/proof.mjs, demo/proof-witness.mjs

  6. 06

    Every edit is named

    Change the packet and verify again. Pick each edit in the panel. Every one comes back DRIFT, and each finding names the check that failed and where.

    The last case edits the artifact and also writes MATCH into the packet's own verdict. It does not help: the embedded verdict disagrees with the derived one, and that disagreement is itself a finding.

    Source: demo/proof.mjs; README.md, "Worked example: a proof packet that can fail"

Walkthrough

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

  1. Install

    Run the MCP server without cloning, or clone to run the demos. Node 20 or newer, no dependencies.

    $ npx -y project-telos-mcp
$ git clone https://github.com/HarperZ9/telos.git && cd telos

  2. First run: two renders

    The demo checks an honest render and a broken one against a criterion the loop did not write.

    $ node demo/run.mjs
  RUN A (honest render)  : CERTIFIED      recheck=true
  RUN B (broken render)  : UNVERIFIABLE   recheck=true

  3. Make a proof packet and verify it

    Write a packet for an agent action, then verify it from the packet alone.

    $ node demo/proof.mjs agent-action --demo --json > packet.json
$ node demo/proof.mjs verify packet.json
verdict       MATCH
witness       unavailable / UNVERIFIABLE

  4. An edited packet is named

    Change the packet and verify again.

    $ node demo/proof.mjs verify edited.json
packet_hash_mismatch (DRIFT)
artifact_digest_mismatch (DRIFT) outputs[0].digest
embedded_verdict_not_derived (DRIFT)

Output from telos at 5f59ff5 on Windows with Node 25. The README shows the witness line as witnessed / MATCH where Emet is installed; it was not installed here. project-telos-mcp 0.9.0 is the current npm release.

What it does not do

Source: README.md at 5f59ff5, "What it does" and "Worked example"; demo/run.mjs output

Check what stuck

Answer each one in your head before you open it.

What does CERTIFIED require in the tesseract loop?

Every channel must agree and match the criterion of 16 vertices and 32 edges, which the loop did not write.

Why does run B end UNVERIFIABLE and not DRIFT?

At 8 by 8 pixels the channels cannot resolve the shape, so the loop cannot verify either way. It reports that, and makes no guess.

A packet carries MATCH in its own verdict but its artifact was edited. What does verify say?

DRIFT. The verdict is derived from the checks, and an embedded verdict that disagrees is itself a finding.

What does witness unavailable mean for a MATCH?

The verdict stands on the verifier alone, and the packet discloses that no second reader checked it.