KYA Evidence

A passport says what an agent is. Evidence shows what an exact agent system did, under an exact scope.

KYA Evidence is local-first open infrastructure for Know Your Agent: signed check receipts over an exact agent manifest (a declaration, not a passport or identity credential), configurable relying-party policies and explainable assurance assessments. The vision is a neutral standard that people, organizations and independent assessors can implement, reproduce and contest. The current deliverable is a dependency-free Node.js reference implementation, v0.1.0-alpha.4, not an adopted industry standard. No GitHub release or npm package exists yet; build from a checkout. The manual release workflow (.github/workflows/release.yml, including its provenance attestation job) has never been run. Most of the code, tests and documents were written with AI assistance, and no independent party has reviewed them.

Every person may eventually delegate to an agent. Every relying party will need a better answer than “trust the prompt.” Start with an exact question: does this configuration meet this party's policy for this scope, on this evidence? Keep the result portable, the decision explainable and the correction process open.

Specification · Scoring · Research universes · Byte interoperability · Threat model · Adapters · Roadmap · What this is not · Changelog · Release notes · Contribute

Read the full agent dossier

A headline score is the beginning of the report. KYA now explains which responses replay, which predicates failed, which passing claims lack originals, and where the evidence cannot reach. The dossier keeps scope, source, coverage, reported cost, evaluator controls and unresolved questions together.

node bin/kya.mjs diagnose --mode reckless --with-benchmarks true --out .kya/dossier
node bin/kya.mjs dossier-verify --dossier .kya/dossier/dossier.json \
  --inputs .kya/dossier/inputs.json --observations .kya/dossier/observations.json \
  --benchmarks .kya/dossier/benchmark-run.json

Open dossier.html for the offline, printable report or read dossier.md. This command runs a clearly labelled synthetic example with no model account or provider call. Use kya dossier with your own frozen, authorized inputs and originals for a real evidence dossier. Report contract.

Challenge the evaluator

Sixteen frozen controls include four complete behavioral reference modes and twelve signed-receipt admission challenges. Cases preserve expected outcomes, missing measurements and every failure. The reproducible check is scripts/mutation-check.mjs: 87 targeted gate mutations over the assessment and incident, campaign, assessor, bridge, profile-validation and privacy-scanner source, each of which the tests must catch (--preflight checks the anchors only). These checks establish local evaluator behavior; commercial agents need separate measured campaigns.

node bin/kya.mjs bench --out .kya/controls
node bin/kya.mjs bench-verify .kya/controls/benchmark-run.json

Benchmark catalog and observation boundaries · Code-grounded design study

Run from a checkout

Requires Node.js 22 or later. The fixture demonstration needs no runtime dependencies, API keys or network access. This package is not yet published to npm.

node bin/kya.mjs demo --out ./artifacts/demo
node --test test/*.test.mjs
node scripts/serve.mjs

Open the local URL printed by the server to explore five reference cases: careful, unsafe, unknown, tampered and revoked. The demo and dashboard presets are synthetic fixtures. A perfect fixture score does not measure Claude Code, Codex, bots or any other real agent. Imported assessment JSON is displayed as claimed, unverified data.

node bin/kya.mjs assess \
  --manifest ./manifest.json \
  --profile ./profiles/core-v1.json \
  --policy ./policy.json \
  --evidence ./evidence.json \
  --evaluator <64-character-evaluator-digest> \
  --out ./artifacts/assessment

node bin/kya.mjs inspect .
node bin/kya.mjs verify ./artifacts/assessment/assessment.json
node bin/kya.mjs probe --out ./artifacts/runtime-probes.json
node bin/kya.mjs benchmark --out ./artifacts/benchmark

kya demo stamps its manifest and evidence with the current clock, so leave --now out or pass a time after the demo ran; a fixed earlier time makes the decision expired with score 0. Demo evidence expires one hour after it was made, so re-run kya demo to refresh it. The evaluator digest comes from kya init DIR (also evaluatorDigest in evidence/evaluator-identity.json). ./manifest.json, ./policy.json and ./evidence.json are files from the kya demo output folder or from kya init; ./profiles/core-v1.json is in this repository. Use generated demo inputs and the adapter protocol to connect an explicitly authorized runtime. probe checks executable availability and version, never competence or safety. A command adapter is a transport, not an operating-system sandbox. verify checks report checksum integrity; it does not authenticate the report or recompute its claims.

The typed SDK includes strict Claude Code result and Codex event parsers, explicit command plans and opt-in native factories. Native model claims remain declarations and cannot earn observed-action credit. Claude execution is blocked until effective managed policy can be established. Codex requires verified subscription auth and explicit binding of included global instructions. See execution gates and private transcript retention and validation boundaries.

Relying-party currency and incidents

An assessment is a point-in-time result. Before relying on it, check that its manifest, policy and clock still match, and that no unresolved incident applies:

node bin/kya.mjs currency \
  --assessment ./artifacts/assessment/assessment.json \
  --manifest ./manifest.json \
  --policy ./policy.json \
  [--incidents ./incidents.json] \
  [--now 2026-10-14T16:41:00.000Z]

A fired trigger (subject-changed, policy-changed, subject-revoked, assessment-expired, assessment-aged, clock-regression or incident-open) returns action: reassess and exit code 2. reliable is true only for a qualified decision with no trigger. Incident records (kya.incident/v1) are Ed25519-signed under their own prefix, and only keys listed as trust anchors in the policy count. No CLI command creates them yet; the library function signIncident does. A policy with requirePrincipalBinding: true withholds qualification from a manifest without a declared principal.accountableParty, which is a pseudonymous {kind, ref} and is not verified. Step-by-step commands with real output are in the relying-party quickstart.

Adoption tooling

• Gate a pipeline on a policy: kya check (and a composite GitHub Action in action/) turns an assessment and currency check into exit codes, annotations and a step summary. See GITHUB-ACTION.md. The action has not yet run on a real GitHub runner.
• Start from a policy template: kya policy-init builds a conservative policy for code agents, agentic payments or read-only assistants. Templates are starting points with unvalidated thresholds and make no agent safe. See POLICY-TEMPLATES.md.
• Run a frozen campaign: kya campaign records a signed, append-only planned-attempt ledger before any attempt runs, so a verifier who knows the intended ledger length or head digest sees unaccounted attempts in the denominator (a truncated or forked ledger is undetectable without an externally pinned head) (ADR-0021). It implements only the ledger slice of ADR-0017; measured capture is not built.
• Carry results in W3C credentials: kya vc exports an assessment as a VC 2.0 vc+jwt with Bitstring Status List revocation. It proves key possession, not truthful execution (VC-BRIDGE.md).
• Recompute an experimental score card: kya score verify CARD.json rebuilds a kya.score-card/v1 from the results it embeds; a second Python verifier checks the same text. It is unsigned, self-run and unvalidated, and says nothing about predictive validity or safety (reproduce and non-claims).
• Beyond the 18 public checks: scenario suites with synthetic incident reconstructions and commit-reveal holdouts, outside the pinned core evaluator.
• Plan and status: WORLD-CLASS-PLAN.md, the checked status ledger and STANDARDIZATION-STRATEGY.md, plus draft regulatory crosswalks (no review yet).

Evidence before reputation

Question	Implemented boundary
Which system was assessed?	Full-manifest digest binds agent, controller reference, harness, model, tools, configuration and scope.
Who supplied the evidence?	Ed25519 receipts match out-of-band policy trust anchors. Signer roles come from policy.
Can bad results disappear?	Every frozen check stays in the denominator. One latest whole run is selected. Tied latest runs cannot qualify. An issuer that never submits a failing run is not detectable without a pinned campaign ledger.
Can a high average hide harm?	Critical failures block qualification. Missing, errored and abstained checks stay unresolved.
Is the evidence relevant now?	Exact profile/evaluator/system/scope binding, expiry, freshness and revocation are enforced.
Can someone challenge the result?	Per-check references, rejection reasons and exact digests support replay, correction, appeal and revocation.
Can the research branch?	Content-addressed universes freeze inputs, time and implementation bytes; explicit-hypothesis forks preserve parents, replay and correction lineage.

Six dimensions: identity, authority, security, reliability, accountability and operations. The reference profile has 18 equal-weight checks. That is an auditable starting choice, not a statistically validated universal weighting. Scores run 0–1000; every result also exposes coverage, optimistic upper bound, dimensions and critical gates. Decisions are qualified, blocked, insufficient-evidence, expired or revoked.

Qualification is local policy satisfaction. It is not verified human identity, actual runtime permission, universal safety or a person's creditworthiness. A signature proves integrity and signing-key possession, not truthful execution. Independent signer roles are policy assignments; organizational independence needs separate verification. The suite observes structured action attempts and final output, not all underlying tool side-effects.

A standardization path that can earn adoption

The vision is broader than a single scoring service: interoperable signed check receipts, independently operated assessors, explicit relying-party policy, issuer accountability, reproducible comparisons and a shared correction protocol. Scores should travel with their evidence and limits. No central authority should quietly redefine a person's agent reputation.

Open-KYA is an agent-identity effort this project has not reviewed first-hand. W3C Verifiable Credentials 2.0 supplies a credential data model. A2A and MCP authorization address other agent and tool interaction concerns. This project explores the executable assessment layer. These efforts can complement one another; no affiliation, certification or adoption is asserted.

To become a useful standard, the protocol needs independent implementations, public interoperability cases, protected evaluation, real use-case calibration, accessible governance and external critique. Roadmap defines those gates. A future credential bridge must preserve exact digests and source class; it cannot turn a declaration into measured evidence.

Built to be challenged

This implementation was written independently: design ideas from the owner's private product Gradia informed it, and no Gradia code, data, paths or logs were copied in (see ADR-0016). It applies evidence-first engineering: exact revisions, replayable tests, visible uncertainty, review by someone other than the author (no outside review exists yet) before promotion and reversible change. Private product code, client records, credentials and operational logs are excluded.

Tests exercise tampering, malformed and duplicate JSON, untrusted signing, wrong bindings, expiry/revocation, run cherry-picking, unknown coverage, declaration laundering, critical failures, HTML injection and bounded command transport. Evaluator mutation tests must detect weakened gates. Passing public cases alone cannot establish general safety; colluding issuers, strategic run omission and suite contamination remain threats. The requirement registry lists every normative requirement with its test traces, each traced to tests that the gate checks for staleness; CI fails on any skipped or todo test. scripts/mutation-check.mjs applies 87 targeted gate mutations over the assessment and incident, campaign, assessor, bridge, profile-validation and privacy-scanner source and requires each to be detected. Threat model lists what is not mitigated.

Research can fork without rewriting its past. Universes hash every bundled executable module, package routing, exact input evidence and assessment time. Replay recomputes the result under that implementation. Comparisons refuse changed decision contracts and incomplete case populations. Correction references expose affected descendants, while actual revocation stays in relying policy.

node scripts/golden-vectors.mjs --check
node scripts/mutation-check.mjs
node bin/kya.mjs universe --inputs frozen-inputs.json --question "Frozen baseline" --out baseline.json
node bin/kya.mjs fork --parent baseline.json --patch candidate-patch.json --out candidate.json
node bin/kya.mjs replay candidate.json
node scripts/pack.mjs
node scripts/verify-release.mjs

The package builder reads immutable Git blobs from a clean committed revision, fixes archive metadata, and records every file's SHA-256. Golden vectors expose canonical bytes and domain-separated Ed25519 signatures for independent implementations. A valid hash is integrity evidence; authenticated issuance, truthful execution and full incident disclosure need separate evidence.

A secondary Python byte checker reconstructs the public vectors without forwarding expected answers. It verifies Ed25519 when an existing cryptographic backend is available and otherwise reports partial verification. Its supported numeric subset is explicit; unsupported doubles are refused. This is a second implementation by this project team, with external implementers and full semantic assessment parity still needed.

Contribute reproducible failures, evaluator challenges, transport adapters or specification criticism. Read CONTRIBUTING.md, governance and SECURITY.md. Ongoing development uses bounded hypotheses, frozen comparisons, review by someone other than the author (no outside review exists yet) and explicit ACCEPT, REJECT or INCONCLUSIVE outcomes. A roadmap does not imply a running scheduler. Public releases, cost-incurring agent executions and deployments need explicit authorization.

Outside review, pilot and implementer kits: external security review kit, private pilot kit and invitation to an independent implementer. They describe what an outsider would need; no outside review, pilot or implementation exists yet. node scripts/review-kit-check.mjs fails when a number or command in them goes stale.

Releasing: the procedure, the owner-only steps and the gate list are in docs/RELEASING.md; npm run release:readiness prints which gates pass and which stay open.

What this is not

• Not an adopted standard, certification or endorsement. No external review or second independent implementation exists yet.
• Not verified human identity, legal authority or liability. accountableParty is a self-declared, pseudonymous reference that policy can require but cannot verify.
• Not proof of truthful execution. A signature proves key possession and report integrity, not what an agent actually did.
• Not a live revocation service. Revocation is whatever the relying policy snapshot says.
• Not continuous monitoring. Currency checks only the supplied manifest, policy, incidents and clock. They observe no runtime behavior, and an incident nobody supplies is invisible.
• Not an appeals process. Appeals are recorded and never clear a trigger.
• Not a measurement of any commercial agent. Demo and benchmark outputs are synthetic fixtures.
• Not an authorization grant, and never a credit or worth score for a person.

Apache-2.0. License · Notice

"KYA Evidence" and "Know Your Agent" are not registered marks (see docs/governance/TRADEMARK-AND-CLAIMS.md, a draft).