Attestation

When to use it

Your survey refused a read you know is safe and useful: a filtered list, a read that returns a view object the structure cannot tie to an entity, a read that delegates to a remote service. Structure cannot prove what it selects or returns, so discovery will never expose it. A person who knows can say so, on the record.

Attestation shipped in 0.3.0. It adds to discovery and never changes it: every attestation phase measured byte-identical generated output on all three benchmarks.

What the tool still proves

An attestation replaces one missing fact, not the whole proof. Around every entry the tool still checks:

• the target resolves to exactly one method declaration in your source, and the binding is structural;
• the input types, and that your entry covers every modeled input exactly;
• read-safety over everything it read: if it sees a write there, the entry is refused;
• that the subject entity you name exists, and that your claim does not contradict what the code provably reads;
• a by-primary-key load, wherever your entry claims an identifier.

If the structural evidence contradicts an assertion, at intake or after a code change, the attestation is refused loudly and nothing ships. The tool never silently prefers either side.

The four categories

An entry

The record lives at tibyan/attestations.json in your application, a JSON array, committed beside the source it describes.

[
  {
    "target": "com.example.billing.service.InvoiceServiceImpl#getInvoicesByBuilding(String, Integer, Integer)",
    "category": "predicate",
    "name": "invoicesByBuilding",
    "resultSemantic": "Invoices belonging to one building, ordered by date descending and returned one page at a time.",
    "parameters": {
      "buildingId": "The numeric identifier of the building whose invoices are returned, passed as a string.",
      "pageNum": "paging",
      "pageSize": "paging"
    },
    "provenance": {
      "assertedBy": "a.reviewer",
      "origin": "human-authored",
      "date": "2026-09-01",
      "fingerprint": ""
    }
  }
]

Writing the sentence

The tool description an agent reads is built from resultSemantic, behind the label "Human-attested, not tool-verified". A vague sentence produces confident wrong answers. A good one says what comes back and how many, what is silently excluded, what an omitted parameter defaults to, and whether the result is paged or capped.

The workflow

1. Write the entry in tibyan/attestations.json.
2. Stamp it. This computes the fingerprint of the code the claim is about and writes it into the file.
3. Re-scan. The survey reports the entry as attested, or refuses it with a located reason.
4. Commit the file and review it like code. Your next build carries it into the manifest.

tibyan attest /path/to/app --date 2026-09-01
tibyan scan /path/to/app

The command reference is in the CLI docs.

Fingerprints and drift

The fingerprint is a SHA-256 over the structural slice the claim covers. It is recomputed on every scan. When the code under an attestation changes, the attestation stops matching and is refused loudly rather than carried, so a claim can never silently outlive the code it was made about. Re-read the method, confirm the sentence is still true, and stamp again.

Drafts

An entry whose origin is ai-draft is a third thing, neither attested nor refused. It is queued in the survey, counted apart, and ships nothing: no capability, no manifest entry, no OpenAPI operation. Any drafter works, human or otherwise, so long as the entry carries that origin. Confirmation is a per-entry, named human act:

tibyan attest /path/to/app --confirm "<target>" --by a.reviewer

There is deliberately no confirm-all, in the CLI or the API beneath it. If you want an AI agent to do the drafting, the repository has a guided adoption prompt (opens in a new tab) that keeps every entry a draft until a person confirms it.

What ships, and how it is labeled

• The MCP tool name itself starts with attested_, so the class is readable before any description is.
• Every description and document says human-attested. It is never presented as verified and never counted among the verified capabilities.
• The OpenAPI document serves attested capabilities under /attested/<name>.
• An attested capability executes exactly like a verified one, with the same access. The label changes what the tool claims about a call, never how the call is made.

Exposure controls

Three runtime properties decide what registers: tibyan.attested.expose (default true), tibyan.attested.exposeSecurityUnverifiable (default false), and tibyan.attested.exposeBoundary (default false). They are described in the runtime reference.

Who owns what