KNOBE Protocol v1 Frozen

This document is the normative specification for KNOBE Protocol v1. It defines what a conforming file must contain, how integrity is computed and verified, and what a conforming verifier must report. The white paper provides motivation and context; this document provides the contract.

§1Status and versioning

KNOBE Protocol v1.0 is frozen. The file format, required fields, canonical hash rule, and verification semantics defined here will not change in any v1.x release. Backward-compatible additions (new optional payload fields, new open-vocabulary values) may be issued as v1.x updates. Any change that would cause a currently valid KNOBE to fail verification under a conforming v1.x verifier constitutes a breaking change and requires a v2.0 declaration.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used as defined in RFC 2119.

§2File overview

A KNOBE is a single plain-text file, conventionally named with the suffix .knobe.md. It consists of three layers:

• YAML frontmatter: human-scannable metadata delimited by --- markers.
• Markdown body: the human-readable content. Free-form; no schema.
• Base64 JSON payload: a machine-readable record delimited by BEGIN/END markers, carrying structured provenance, interpretive context, and an integrity hash.

A file is valid at the protocol layer when its payload decodes, parses, contains the ten required fields, and its payload_hash matches the computed canonical hash. Validity does not imply truth, accuracy, or trustworthiness of the content.

§3File structure

3.1 YAML frontmatter

The file MUST begin with a YAML frontmatter block delimited by lines containing exactly ---. At minimum, spec_version MUST appear in the frontmatter. All other frontmatter fields are optional; they serve human scanners and are not part of the integrity-sealed record.

---
title: "Example KNOBE"
spec_version: "1.0"
---

3.2 Markdown body

The body MAY be any valid UTF-8 text. It is not validated by a conforming verifier except when an optional body_hash is present in the payload (see §6). A body is not required; a KNOBE with an empty body is valid.

3.3 Payload block

The payload block MUST appear after the body. Its delimiters are:

-----BEGIN KNOBE B64-----
{base64-encoded JSON}
-----END KNOBE B64-----

The content between the delimiters is standard Base64 (RFC 4648 §4) encoding of a UTF-8 JSON object. Line breaks within the Base64 block MUST be ignored by decoders. If multiple payload blocks are present, verifiers MUST use the last one to compute verification state, and MUST surface a warning to the receiver containing the total count of blocks and the index of the block evaluated (e.g., "evaluated block 2 of 2"). A conforming file SHOULD contain exactly one payload block; multiple blocks can occur legitimately (email quoting, archive concatenation, copy-paste) but can also indicate shadow-payload injection. The warning is interpretation, not just information: it tells the receiver that the file's structure is anomalous.

§4Payload fields

4.1 Required fields

The following ten fields MUST be present in the payload. A payload missing any of them is invalid at the protocol layer regardless of whether its hash matches.

Required fields

Field	Type	Notes
spec_version	string	The protocol version under which this file was sealed. "1.0" for this specification.
title	string	Human-readable title of the knowledge object.
summary	string	One-paragraph description of the object's content and purpose.
content_type	string	Declared content category. See §8 for open vocabulary.
created_date	string	ISO 8601 date of original creation (YYYY-MM-DD).
license	string	Declared license identifier (e.g. "CC BY 4.0").
privacy_level	string	Declared privacy posture. See §8.
quarantine_status	string	Declared trust posture. See §8. New/external KNOBEs SHOULD default to "quarantine".
attribution	object	Must contain a sources array with at least one entry. Each source entry SHOULD include author and contribution. AI contributors SHOULD carry "rights_bearing": false.
payload_hash	string	SHA-256 hex digest of the canonical JSON payload (excluding this field). Format: exactly 64 lowercase hexadecimal characters. See §5.

4.2 Receiver-facing optional fields

These optional fields carry interpretive context written for the receiver: the next human or agent to encounter the object. They are not required for validity but are central to the protocol's purpose.

Receiver-facing optional fields

Field	Notes
fidelity_limits	How far the object may be trusted as a representation of its source. Suggested sub-fields: represents, trust_as, do_not_infer (array).
use_conditions	Originator-declared terms for downstream use. Suggested sub-fields: license, permitted (array), requested_preservations (array), consent_note.
accessibility	Adaptation lineage. Each entry SHOULD include adapted_from (source payload_hash), adaptation_type, adaptation_contributor, review_date.

4.3 Additional optional fields

Additional optional fields

Field	Notes
body_hash	SHA-256 of the normalized body text. See §6.
parents	Array of objects linking to source KNOBEs by payload_hash. Each entry SHOULD include payload_hash, title, and relationship. Any payload_hash value MUST follow the format constraint in §4.1: exactly 64 lowercase hexadecimal characters.
transformation_history	Array of transformation receipts. Each entry SHOULD include date, who, strategy, notes.
identity_status	Declared identity posture. See §8. "declared" means attribution is self-reported; "signed" is a forward placeholder for cryptographic signing in future tiers.
key_concepts	Array of {"name": "...", "definition": "..."} objects.
version_history	Array of {"version": "...", "date": "...", "notes": "..."} objects.
is_seed	Boolean. true indicates this KNOBE is intended as a teaching or bootstrapping artifact.
language	BCP 47 language tag (e.g. "en").
tags	Array of lowercase strings.
subtitle	String. Secondary title.
id	String. Stable local identifier for this object.
canonical_url	String. Authoritative URL if published.
license_url	String. URL to the full license text.
build_recipes	Array of instructions for constructing derivative KNOBEs. Informative only in v1; not normative.

§5Canonical hash rule

The payload_hash is computed by applying the following algorithm to the payload object:

Interoperability constraints

Two constraints close cross-language canonicalization gaps that would otherwise allow conforming Python and JavaScript implementations to compute different hashes for visually-identical payloads.

Reference implementations

Python 3:

import json, hashlib, unicodedata

def nfc(x):
    if isinstance(x, str): return unicodedata.normalize("NFC", x)
    if isinstance(x, dict): return {nfc(k): nfc(v) for k, v in x.items()}
    if isinstance(x, list): return [nfc(v) for v in x]
    return x

obj = {k: v for k, v in payload.items() if k != "payload_hash"}
obj = nfc(obj)
canon = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
payload_hash = hashlib.sha256(canon.encode("utf-8")).hexdigest()

JavaScript:

function nfc(x) {
  if (typeof x === "string") return x.normalize("NFC");
  if (Array.isArray(x)) return x.map(nfc);
  if (x !== null && typeof x === "object") {
    const out = {};
    for (const k of Object.keys(x)) out[k.normalize("NFC")] = nfc(x[k]);
    return out;
  }
  return x;
}
function canonicalize(obj) {
  if (obj === null || typeof obj !== "object") return JSON.stringify(obj);
  if (Array.isArray(obj)) return "[" + obj.map(canonicalize).join(",") + "]";
  const keys = Object.keys(obj).sort();
  const pairs = keys.map(k => JSON.stringify(k) + ":" + canonicalize(obj[k]));
  return "{" + pairs.join(",") + "}";
}
// Strip payload_hash at top level only, normalize, then canonicalize.
const { payload_hash, ...rest } = payload;
const canon = canonicalize(nfc(rest));
// Then SHA-256 canon as UTF-8 bytes.

§6Body hash (optional)

The optional body_hash payload field seals the markdown body at the time the KNOBE is created. When present, a conforming verifier checks it and reports accordingly (see §7). A mismatch does not cause a failed result; it produces verified-body-modified.

Body normalization

The body is extracted as the text immediately following the second line containing exactly --- (the closing delimiter of the YAML frontmatter), down to the -----BEGIN KNOBE B64----- marker. This rule is explicit because markdown bodies frequently contain --- as a horizontal rule; counting --- lines rather than searching for the first match prevents misidentifying a body horizontal rule as the frontmatter terminator. If a verifier cannot locate two --- lines before the -----BEGIN KNOBE B64----- marker, it MUST report unreadable rather than attempt body hash computation. Before hashing, apply the following normalization in order:

§7Verification states

A conforming verifier MUST report exactly one of the following four states.

Verification states

State	Conditions	Meaning
verified	Payload decodes and parses. All required fields present. payload_hash matches computed hash. body_hash absent or matching.	The sealed payload record is intact. If a body hash was present, the body is also intact.
verified-body-modified	Payload hash matches. body_hash is present and does not match the normalized body.	The structured payload record is intact. The markdown body has changed since sealing. This is not automatically a sign of tampering; bodies are often legitimately edited. Inspect before relying.
failed	Payload decodes and parses, but the computed canonical hash does not match payload_hash.	The structured record has been altered since sealing.
unreadable	No payload block found, or the block cannot be decoded or parsed as JSON.	The file does not contain a verifiable KNOBE payload.

Two-layered verification

KNOBE verification is two-layered. The primary status output reports sealed payload integrity. The secondary body_verified output reports whether the human-readable markdown body was sealed and, if so, whether it still matches. The two layers are reported independently so that receivers can tell what was actually checked. A result of status: verified · body_verified: omitted is not contradictory: it means the payload is intact and no body integrity claim was sealed by the author.

Conformance, distinct from integrity

The four verification states report integrity: whether the sealed payload is byte-identical to what was hashed at sealing. They do not, by themselves, report conformance: whether the payload structure and field values satisfy the schema and constraints in this specification. A file can have a hash that matches its payload (integrity is verified) and still violate the spec: for example, created_date: "yesterday" instead of an ISO date, or a numeric value where the spec requires a string, or a malformed parent hash.

Verifiers MUST report conformance as a separate dimension from integrity. This preserves the four-state integrity model while allowing schema validation to be reported honestly without collapsing the two layers.

The independence of status and conformance is deliberate. A file with status: verified · conformance: invalid tells the receiver: the sealed bytes are intact, but the author or sealing tool did not follow the spec. The protocol does not silently collapse this into failed, which would conflate cryptographic tampering with schema noncompliance.

Quarantine semantics

Verification state is independent of quarantine_status. A KNOBE may be verified and still carry quarantine_status: "quarantine". Verification tells the receiver whether the payload is intact; it does not authorize use. Implementations SHOULD treat any external or newly received KNOBE as quarantined regardless of its declared status until a human or governed system reviews it.

§8Open vocabularies

The following fields use open vocabularies. The values listed here are canonical and recommended. Implementations MAY define additional values. Verifiers MUST NOT fail a file because an unrecognized vocabulary value is present.

content_type

original · synthesis · adaptation · compression · annotation · seed · collection · translation

quarantine_status

quarantine (default for new/external) · trusted · rejected

quarantine_status is a declared sender-side or originator-side trust posture. Receivers MUST NOT treat quarantine_status: "trusted" as local authorization unless it is established by their own review process or a governed trust registry. A malicious author can declare any value here; the field communicates the originator's posture, not a receiver's clearance.

privacy_level

public · internal · sensitive · restricted

privacy_level is declarative. It does not override law, policy, consent, IRB conditions, FERPA, HIPAA, or institutional classification. A file may declare public and still contain regulated content; the field records the originator's posture, not legal or institutional authorization. Downstream systems with privacy obligations MUST apply their own classification policy regardless of the declared value.

identity_status

declared (self-reported; default in v1) · signed (placeholder for future cryptographic signing)

accessibility.adaptation_type

caption · simplification · alt-text · translation · multimodal

parents.relationship

adaptation_of · compression_of · synthesis_input · derived_from · responds_to · supersedes

§9Versioning semantics

The spec_version field in the sealed payload records the protocol version under which the file was sealed. Verification semantics follow the sealed version, not the verifier version.

• A v1.x verifier MUST verify v1.0 files using v1.0 semantics.
• A v1.x update MUST NOT introduce a new required field or change the canonical hash algorithm.
• A v1.x update MAY add new optional fields and new open-vocabulary values.
• A v1.x verifier encountering a spec_version it does not recognize SHOULD report this clearly rather than silently applying its own semantics.
• v2.0 would constitute a new protocol and would not be backward-compatible with v1.x files.

§10Conformance

The reference verifier lens.py is the canonical implementation for resolving serialization ambiguity under §5. This written specification remains normative in all other respects. Test vectors for all four states are available in the test-vectors/ directory. An implementation that produces the expected state for all nine conformance vectors is considered conforming.

§11Limits

This specification defines a format and a verification algorithm. It does not provide:

• Identity verification. Attribution and identity are declared in v1, not cryptographically proven. identity_status: "signed" is a forward placeholder.
• Timestamps. created_date is self-reported. The protocol provides no proof of when a file was sealed. Ledger anchoring (available in application tiers) can provide existence-at-a-time proof; the open protocol cannot.
• Trust. A verified result means the payload is intact since sealing. It does not mean the content is accurate, the attribution is honest, or the object is appropriate for any purpose.
• Enforcement. The protocol declares interpretive obligations (fidelity limits, use conditions, quarantine status). It does not enforce them. A receiver is free to ignore declared conditions; the protocol cannot prevent this.
• Lineage truth. The protocol verifies that a lineage claim is intact at the time of sealing; it does not verify that claimed parent objects exist or actually possess the cited payload hashes. An author can list any string as a parent hash. A graph-traversal application attempting to resolve the parent chain will surface the error (parent not found, or parent hash mismatch); the open protocol layer does not perform that traversal.
• Automatic verification. Verification is the receiver's responsibility, not the protocol's. The substrate KNOBE lives in (text editors, AI assistants, ingestion pipelines, ordinary markdown tools) does not check seals by default. A KNOBE with a broken or missing payload will be opened, displayed, summarised, and indexed by most consumers without any warning. This is a property of the substrate, not a defect of the protocol: the same characteristics that make KNOBE portable across these tools are the ones that make verification optional rather than enforced. Tools that want fail-closed behaviour on broken KNOBEs must integrate lens.py or an equivalent verifier at the point of ingestion.
• AI interpretability. KNOBE carries human-supplied context around AI-mediated knowledge work. It does not expose a model's internal reasoning.

Integrity, not truth

KNOBE uses standard SHA-256 hashing. There is no cryptographic novelty here, and no claim that a hash can solve trust. The hash proves one narrow thing: the sealed payload has not changed since sealing. It does not prove the content is true, the author is who they say, attribution is honest, consent was obtained, or the object is safe to use. A liar can seal a lie; the seal then proves only that the lie has not changed.

This limit is a design principle, not a flaw to hide. It marks a distinction the rest of the protocol depends on:

The recommended posture is quarantine-first: treat external objects as untrusted until reviewed, even if they verify. Full semantics are in §11 above and the threat model.

For implementers

v1 file semantics are frozen. Everything needed to build a compatible verifier or tool is in this specification, the test vectors (nine files, known results), the reference verifier, and the source repository. Reproduce the nine test vectors and your implementation is canonically compatible with KNOBE Protocol v1.

For agent builders

Agent harness engineering governs execution policy, tool permissions, memory, and observability: the conditions around the agent. KNOBE comes at the problem from the other side, engineering what the object carries through any system rather than the system itself. Harness infrastructure governs the conditions around the agent. KNOBE governs the conditions carried by the artifact. If the artifact arrives stripped, no harness can reconstruct what was never carried.