Error Knowledge Protocol v1

Every engineering team re-solves the same errors. Logs get lost, Slack threads fade, and “what actually fixed this” lives only in a few people’s heads. EKP defines a shared schema so error-and-fix data can be captured from shells, CI, CLIs, and agents; deduplicated across machines and users; and queried by both humans and LLM agents without leaking secrets.

Every EKP document is wrapped in an envelope:

{
  "schema": "fuku.ekp",
  "version": 1,
  "ontology": { ... }
}

schema MUST be the literal string fuku.ekp. version is an integer. Unknown top-level fields MUST be ignored by consumers.

Required fields: adapter, category, fingerprint, occurred_at. Optional fields include severity, signals, entities, tags, raw_excerpt, source_lineage.

{
  "adapter": "kubernetes",
  "category": "kubernetes.image_pull",
  "severity": "blocking",
  "fingerprint": "blake3:7f9c…",
  "occurred_at": "2026-04-18T10:22:31Z",
  "signals": { "exit_code": 1, "error_code": "ImagePullBackOff" },
  "entities": [
    { "type": "cluster", "value": "prod-us-east", "redacted": false },
    { "type": "image", "value": "***", "redacted": true }
  ],
  "tags": ["kubernetes", "image-pull"],
  "raw_excerpt": "Failed to pull image ***"
}

An adapter parses raw invocation context (command, exit code, stderr, cwd, env) and emits an EKP ontology. Fukura ships four built-in adapters: cargo, git, kubernetes, and a generic fallback that guarantees every captured error yields an EKP document.

Adapters MUST be side-effect free, MUST never emit unredacted secrets, and SHOULD declare a priority so the registry can disambiguate overlapping matches.

The fingerprint identifies “the same logical error”. It is computed from the adapter ID, the category, stable signals (error code, command head, normalised stderr pattern), and entity types (not values). The signature is hashed with BLAKE3 (or SHA-256) and the hex digest is prefixed with the algorithm name: blake3:7f9c….

Adapters MUST NOT include variable values (paths, UUIDs, timestamps, hostnames) in the signature, so the same logical error produces the same fingerprint across machines and users.

Producers MUST apply redaction before serialising an EKP document. The default set covers credentials, tokens, private keys, database URLs, emails, and IPs. Adapters MAY contribute environment-specific patterns.

A separate document type, fuku.ekp.attempt, describes whether a fix actually worked. Producers (shell hooks, agents) record what followed an error and whether the next successful command resolved it. This yields a measured success rate per solution, per fingerprint.

The wire shape for attempts is defined in the Hub API §5.2; the CLI side is usable today — see /docs/effectiveness.

A producer is EKP v1 conformant if it emits valid envelopes, provides at least a generic fallback adapter, computes fingerprints per §6, and applies redaction per §7. A consumer is conformant if it accepts valid envelopes without error, treats unknown optional fields as permissible, and treats unknown enum values as unknown.