instruction-md
Read, check, resolve and verify instruction.md documents in Rust: the reader for the
specification's first edition (instruction/1), the exact text an agent receives, composition, and signature
verification.
crates.io · docs.rs · Specification · Documentation · License: MIT OR Apache-2.0
At a glance
What it is. An instruction is a Markdown document that tells an AI agent what to do, with binding rules
(MUST:, SHOULD:, NEVER:), parameters, and the MCP servers, skills and agents it may use. People write and
release instructions on instruction.md; agents read them over MCP. This crate is the Rust implementation of the
open instruction.md specification, first edition.
What it does.
- Reads a document into its tree, with diagnostics that have stable codes.
- Checks it: the reader's checks, the inline checks, native workflows, and the integrations policy.
- Gives the agent text (
instruction-text/1): what an agent actually receives, parameters filled in. - Resolves a document with its bases and includes into the resolved artifact (
instruction-resolved/1). - Verifies author and delivery signatures (JWS, Ed25519), so a runtime knows who published what it follows.
- Lists the connected objects (MCP servers, tools, skills, agents, services) and configuration blocks, for a host that wires them up.
Who it is for. Teams building agent runtimes, hosts, gateways, editors or CI checks in Rust that need to read instruction files the same way instruction.md does.
What it does not do. It does no I/O. It does not talk to a registry, follow an instruction over MCP, or report
what was applied. Your code fetches the text (from a file, the registry, an editor) and hands it to the crate. To
follow an instruction from a registry today, use the npm package instruction.md
or the Python package instruction.md, or connect your agent to
https://instruction.md/mcp (Connect an agent).
How it is held to the reference. It is a port of the Go SDK, itself a port of the TypeScript reference
implementation. Its test suite runs the specification's conformance cases and the reference's implementation
vectors (specification commit 4bb0328, exposed as SPEC_COMMIT) and must agree with them byte for byte.
Status. Pre-1.0 (current version 0.6.1), published on crates.io. The reader and the agent text are complete for the first edition and conformance-tested. Minor versions may still break the API; each break is marked in the changelog. The signature verification follows the specification and is tested against the reference, but it has not had an independent security review.
License. MIT OR Apache-2.0, at your option: you may use, change and ship it in open or closed software. The
embedded registries are the specification's, under CC BY 4.0 (see NOTICE); they travel with the crate
and need no action from you beyond keeping the notice.
Quality guarantees.
- No
unsafe(#![forbid(unsafe_code)]). - Every entry point takes untrusted text and never panics. A problem is a
Diagnosticwith a stable code. A randomized test feeds every vector and sample, whole, truncated and mutated, to the entry points. - Linear-time pattern matching, and depth limits for hostile input (see Limits).
- Dependencies:
serde,serde_json, andringfor signatures only.
Support. Questions and bugs: GitHub issues on the specification's repository; start the title with "Rust SDK". Security problems and anything else: Contact us.
Source. The crate's full source ships in the crates.io package; browse it on docs.rs. Its own repository is not public yet, so the "Repository" link on crates.io does not open for now.
Install
or in Cargo.toml:
[]
= "0.6"
Without signature verification (no ring; the crate then depends on serde and serde_json only):
[]
= { = "0.6", = false }
The library is imported as instruction_md.
Requirements
- Rust 1.96 or later (edition 2024).
- Any platform Rust supports. With the default
verifyfeature, any platformring0.17 builds on. - No runtime, no async. Every function is synchronous, and nothing touches files, the network or environment
variables. Two exceptions, both in the
verifyfeature: verification reads the system clock unless you passnow, andSigningKey::generate()uses the operating system's random number generator.
Cargo features
| Feature | Default | What it adds |
|---|---|---|
verify |
yes | The verify module: verify_author, verify_delivery, VerifyResult, VERIFY_CODES, Jwk, public_jwk, and signing for tests and tooling (SigningKey, sign_jws). The only use of ring. |
Without verify the crate still reads, checks, resolves and computes digests. Its SHA-256 is its own.
Quickstart
Create a project and add the crate:
&&
Put this in src/main.rs:
use ;
Run it:
It prints the agent text, with the default for tz filled in and the front matter gone:
# Morning brief
MUST: plan the day in UTC.
BECAUSE: the owner reads the brief at 7.
NEVER: book a meeting before 9.
The BECAUSE: line stays with the rule it explains, and the next rule starts a new paragraph.
To check a file instead, read it with std::fs::read_to_string and pass the text to read.
Usage
Read, check, and give the agent its text
use ;
let doc = "---\nspec: \"1\"\nparameters:\n tz: { type: string, default: UTC }\n---\n\
::person{id=owner title=\"Alex\"}\n\n\
MUST (if a meeting moves): tell :person[Alex]{ref=#owner} in ${tz}.\n\
BECAUSE: the owner plans the day around it.\n";
let reading = read;
let diagnostics = check_reading; // the reader's and the inline checks', in source order
for d in &diagnostics
assert!;
let text = reading.text; // instruction-text/1, declared defaults substituted
assert!;
read returns a Reading: the tree (reading.document), the reader's own diagnostics (reading.diagnostics),
the identities, the declared parameters, and the effective integrations policy. check_reading adds the inline
checks and the workflow checks. An error among the diagnostics means the document should not be delivered.
reading.changes_text() says whether the agent text differs from the source at all. Plain prose and rules already
in canonical form (MUST: …) are handed on as written, so a host may pass the source on unchanged.
One call for a runtime: deliver
let = deliver;
assert_eq!;
assert!;
deliver(text, params) reads, checks and gives the agent text in one call. Its diagnostics also include lines
written in the older Specification 1.1 syntax (legacy_diagnostics, code instruction.md/legacy-syntax, an
error: a :::!kind block reads as prose here), ordered as the TypeScript CLI reports them.
Supply parameter values
use ;
let doc = "---\nparameters:\n tz: { type: string, default: UTC }\n---\nMUST: plan the day in ${tz}.\n";
let reading = read;
let mut params = new;
params.insert;
assert_eq!;
// A value typed on a command line, read as the parameter's declared type:
let tz = reading.parameter.unwrap;
let value = value_from;
assert!;
A supplied value replaces the declared default. Object is serde_json::Map<String, serde_json::Value>.
Diagnostics as JSON
Every diagnostic has a stable code, a severity (Error, Warning, Info), a message for a person, and
optionally a range (1-based lines), uri, target and remedy. to_json() gives the specification's shape,
for CI output or an editor:
use ;
let diagnostics = check;
let json: = diagnostics.iter.map.collect;
assert_eq!;
assert_eq!;
The codes are the ones the Go and TypeScript readers emit (unclosed-directive, invalid-attributes,
reference-optional, invalid-workflow, tool-blocked, …).
Connected objects, configuration and workflows
use ;
let r = read;
for o in connected_objects
assert!; // config, workflow, schedule, sandbox, test, eval, data, properties
Connected objects are the kinds a typed reference names (the registry's connected family, and resource): a
person, role, skill, MCP server, tool, agent, service, source or resource. Configuration blocks are the technical
family's structured bodies. walk(body, visitor) visits every directive with the directives that hold it;
Node::body_source() is a container's body exactly as written; split_backmatter(text) cuts a document at its
backmatter's --- separator, where Reading::back_range starts.
check_reading holds every :::workflow{dialect="instruction/workflow"} body to the specification's workflow
registry and graph rules, as the TypeScript and Go readers do:
invalid-workflow: an unknown kind or field, a missing required field, a step that depends on nothing but is not a trigger, a missing dependency or route, a cycle, no trigger or finish, an unreachable step.limit-exceeded: more than 512 steps in a scope, bodies nested deeper than 4,retry.maxover 20.extension-unavailable: analias:nodekind whose alias isn't declared.
Each is an error on the line of the key it is about. The specification lists no host events, so an event
trigger's on is the host's to check. Only the scoping kinds' body or branches hold nested steps
(WORKFLOW_SCOPES, workflow_scope: foreach, batch, iterate, subgraph; parallel, race). Another
kind's field of that name, such as an http request's body, is data. workflow_diagnostics(definition, extensions) checks a definition on its own.
The integrations policy
A workspace's integrations policy travels in the front matter: host-integrations, which only the host that serves
the document writes (outside the author-signed bytes), and integrations, the author's, which can only narrow it.
The reader merges them into Reading::policy: a target is allowed only where every layer that lists targets lists
it, and a tool is blocked where any layer blocks it. The reader warns, never refuses: tool-blocked (a tool that an
mcp's tools or allow, or a tool on its server, names) and integration-not-allowed (an mcp, skill,
agent or service outside the allowed targets). A layer of the wrong shape is invalid-metadata.
use ;
let served = "---\nhost-integrations:\n allowed: [\"https://cal.example.org/mcp\"]\n servers:\n \
\"https://cal.example.org/mcp\": {\"blocked\": [\"events.delete\"]}\n---\n\n\
::mcp{id=cal src=\"https://cal.example.org/mcp\" tools=\"events.list,events.delete\"}\n";
let r = read;
let policy = r.policy.as_ref.unwrap; // None when the document has neither key
assert!; // targets compared normalized
assert!;
let d = &check_reading;
assert_eq!;
ReadOptions::host reads a document as if it were served with a host's layer (an editor before serving).
remote_targets(kind, attrs), named_tools(node, body) and normalize_target are what the checks compare.
layer_of, merge_policy, host_block and with_host_block build the layers and the host's block.
authored_candidates takes the block out of a served text again (verify_author does).
Resolve bases, includes and parameters
A document can extend others (extends: in the front matter) and include parts of them. The resolver fetches
nothing itself: you hand it a loader, or the sources already loaded.
use ;
let load = ;
let r = resolve;
// r.ok: no error; r.text: the agent text; r.resolved: the instruction-resolved/1 artifact (to_json(), resolved_digest)
The same with the sources in memory, which runs as written:
use HashMap;
use ;
let base = Source ;
let sources = from;
let r = resolve_with;
assert!;
assert_eq!;
assert!;
resolve_tree resolves JSON trees (the specification's resolution cases are trees). Composition is bounded: by
default 8 levels deep and 64 sources (max_depth, max_sources). Past either is an error, never a silently
truncated result.
Verify a signed read
instruction.md signs every release. An author attestation signs the authored bytes. A delivery attestation signs the text one reader received and the resolution's manifest, and embeds the author signature. See Signing and trust.
use ;
The delivery signature binds the delivered text's digest, the audience, the resolution manifest and the embedded
author signature, whose digest must be the resolved document's. The delivered capabilities may not exceed the
author's. Resolved::manifest() is what a delivery signs of its resolution (Manifest::to_json() is the
manifest claim).
An author signature on its own, signed and verified end to end. This example builds the claims with serde_json,
so add it to your project first (cargo add serde_json):
use ;
use json;
let doc = "---\nspec: \"1\"\n---\nMUST: be brief.\n";
let key = generate.unwrap; // a registry signs with its own keys; this is for tests
let jwk = key.public_jwk;
let now = now.duration_since.unwrap.as_secs;
let claims: Object = json!.as_object.unwrap.clone;
let jws = sign_jws;
let opts = VerifyOptions ;
let r = verify_author;
assert!;
let tampered = verify_author;
assert_eq!;
Pin the publisher. Without publisher you learn that somebody signed the document; with it, that the publisher
you expected did. An organization's public keys are published at instruction://pub/<owner>/keys.json. Which keys
to trust (active, retired, revoked) is your decision: the crate verifies against the key set you pass.
Digests, formatting and older syntax
use ;
let doc = "---\nid: acme/brief\n---\nMUST: be brief. \r\n";
assert!; // sha256:<64 lower hex>
assert_eq!; // the stored bytes, as they are
assert_eq!;
// The conservative formatter: LF endings, one final newline; never what an agent receives
assert_eq!;
// Lines written in Specification 1.1, each an error with what it needs
let legacy = legacy_diagnostics;
assert_eq!;
This crate reports 1.1 lines; converting them is done by upgrade() in the npm package
instruction.md.
Reference
Everything below is exported from the crate root unless a module path is given. Full signatures and field docs are on docs.rs.
Constants
| Name | Value | Meaning |
|---|---|---|
SPEC_COMMIT |
"4bb0328" |
The specification commit the embedded registries and conformance data are from. |
TREE_FORMAT |
"instruction/1" |
The authored tree's format. |
RESOLVED_FORMAT |
"instruction-resolved/1" |
The resolved artifact's format. |
LEGACY_SYNTAX |
"instruction.md/legacy-syntax" |
The diagnostic code of a line in Specification 1.1 syntax. |
WORKFLOW_DIALECT |
"instruction/workflow" |
The workflow dialect check_reading checks. |
WORKFLOW_SCOPES |
&[(&str, &str)] |
Scoping workflow kinds and the field holding their nested steps. |
HOST_POLICY_KEY |
"host-integrations" |
The front matter key only the serving host writes. |
AUTHOR_POLICY_KEY |
"integrations" |
The front matter key an author writes to narrow the host's policy. |
INTEGRATED_KINDS |
["mcp", "skill", "agent", "service"] |
The kinds the integrations policy applies to. |
VERIFY_CODES |
15 codes | Every VerifyResult::code (feature verify, see below). |
Reading and checking
| Item | Signature | What it does |
|---|---|---|
read |
fn(&str, &ReadOptions) -> Reading |
Reads a document into its tree, with the reader's diagnostics in source order. |
check |
fn(&str, &ReadOptions) -> Vec<Diagnostic> |
Reads and checks: the reader's, the inline and the workflow diagnostics. |
check_reading |
fn(&Reading) -> Vec<Diagnostic> |
check for a document already read. |
inline_diagnostics |
fn(&Reading) -> Vec<Diagnostic> |
The inline checks only, prose node by prose node. |
workflows_diagnostics |
fn(&Reading) -> Vec<Diagnostic> |
Each instruction/workflow body's diagnostics, on the body's lines. |
deliver |
fn(&str, Option<&Object>) -> (String, Vec<Diagnostic>) |
Agent text with declared defaults, plus every diagnostic including 1.1 lines. |
legacy_diagnostics |
fn(&str) -> Vec<Diagnostic> |
The lines written in Specification 1.1 syntax, each an error. |
resolve_target |
fn(&Reading, kind: &str, reference: &str) -> Target |
Where a typed reference points: Target::Local { id, kind, matches }, Missing { id } or External { uri }. |
split_backmatter |
fn(&str) -> SplitBackmatter |
Cuts a document at its backmatter: before, backmatter, range, data, diagnostics. |
strip_comments |
fn(line: &str, open: bool) -> Stripped |
Removes comment bytes from one line: text, still_open, opened, only. |
value_from |
fn(&Parameter, &str) -> Value |
A value written as text, read as the parameter's declared type. |
value_fits |
fn(&Parameter, &Value) -> bool |
Whether a value satisfies a parameter's declared type. |
read::requires_of |
fn(&Reading) -> Vec<String> |
The capabilities an author attestation names: the families used, plus agents and spending grants. |
classify_lines |
fn(&Reading) -> Vec<LineInfo> |
One class per line (front-matter, code, heading, directive, keyword, prose, …) for an editor. |
format |
fn(&str) -> String |
The conservative formatter: LF endings, one final newline, no trailing whitespace on directive lines. |
inline_tokens |
fn(&str) -> Vec<InlineToken> |
The inline forms in Markdown (directive, wiki, embed, footnote, math, param), byte offsets. |
split_wiki |
fn(&str) -> (String, String, bool) |
Splits a wiki link's text into target, label, and whether it was piped. |
parse_attributes |
fn(&str, spec_of, strict: bool) -> (Attrs, Vec<String>) |
Parses an attribute list's text into attributes and problems. |
parse_yaml |
fn(&str) -> Result<Value, String> |
YAML 1.2 Core Schema, JSON-compatible values only, as metadata is read. |
ReadOptions (all Default):
| Field | Type | Default | Meaning |
|---|---|---|---|
fragment |
bool |
false |
Read a part of a document, with no metadata regions. |
uri |
String |
"" |
The document's URI, which the tree carries. |
host |
Option<PolicyLayer> |
None |
Read as if served with this host-integrations layer. One in the front matter wins. |
Reading fields: document: Document, diagnostics: Vec<Diagnostic>, identities: Vec<Identity>,
parameters: Vec<Parameter>, footnotes: BTreeMap<String, u32>, comments: BTreeSet<u32> (comment-only lines),
lines: Vec<String>, front_range: Option<Range>, back_range: Option<Range>, policy: Option<Policy>.
Methods: text(Option<&Object>) -> String, changes_text(), has_errors(), identity(id), parameter(name),
source(), line_offset(line).
Agent text
| Item | Signature | What it does |
|---|---|---|
Reading::text |
fn(&self, Option<&Object>) -> String |
The agent text (instruction-text/1) with supplied parameter values. |
to_text |
fn(&Document, &TextOptions) -> String |
The text profile of any tree, for example a resolved body. |
value_text |
fn(&Value) -> Option<String> |
How a parameter value reads in text; None for null. |
TextOptions (all Default): params: Option<Object>, parameters: Vec<Parameter>, use_prose: bool,
identities: Option<Vec<Identity>> (None: no #id is checked), known: Option<Known> (for a resolved body:
does an instance have an id). A reference to a missing id reads [unresolved].
Tree types
| Type | What it is |
|---|---|
Document |
format, uri, metadata: Metadata { front, back }, body: Vec<Node>. new(body), to_json(), from_json(&Value). |
Node |
node_type: NodeType (Markdown, Directive), kind, form: Option<Form>, attrs, children, value: Option<StructuredValue>, source, range, instance. Methods: markdown(..), directive(..), is_markdown, is_directive, keyword, reason_range, is_prose, body_source, children(), attr_str, to_json, from_json. |
Form |
Container (:::kind … :::), Leaf (::kind{…}), Keyword (MUST: …), Alert (> [!TIP]). as_str, parse. |
StructuredValue |
A structured body: format (yaml, json, csv, text, html, code), source, data: Option<Value>. |
Range |
1-based inclusive lines: start, end. new, line, to_json. |
Diagnostic |
code: &'static str, severity: Severity, message, uri, range, target, remedy. line(), is_error(), to_json(), Display. |
Severity |
Error, Warning, Info. |
Identity |
An explicit id: id, kind, line. |
Parameter |
name, param_type, required, values, default, example, description, source, line (0: front matter). |
Object, Attrs |
serde_json::Map<String, Value>. |
LineInfo |
class, label_end, keyword, kind. |
InlineToken, TokenType |
An inline form: token_type, start, end (byte offsets), kind, label, attributes, target, piped, formula, name. |
Connected objects and configuration
| Item | Signature | What it does |
|---|---|---|
connected_objects |
fn(&[Node]) -> Vec<ConnectedObject> |
Every connected object in document order, wherever it stands. |
configuration_blocks |
fn(&[Node]) -> Vec<ConfigurationBlock> |
Every configuration block in document order. |
walk |
fn(&[Node], &mut dyn FnMut(&Node, &[&Node]) -> bool) |
Visits every directive with its ancestors; return false to skip its children. |
is_connected, carries_configuration, is_layout |
fn(kind: &str) -> bool |
A kind's role, by the registry's families. |
ConnectedObject: node, kind, form, id, title, description, src, endpoint, attrs, body,
location; attr(key), list(key) (tools, allow, deny, skills). ConfigurationBlock: node, kind,
id, title, dialect, adapter, target, schema, schema_sha256, format, data, body, attrs,
location; attr(key). Location: range, parents (kinds, outermost first), instance; in_layout(),
line().
Integrations policy
| Item | What it is |
|---|---|
Policy |
The effective policy: allowed: Option<Vec<String>>, servers: BTreeMap<String, ServerPolicy>, from: PolicyFrom { host, author }. tool_blocked(targets, tool), targets_allowed(targets), to_json(). |
PolicyLayer |
One layer as written: allowed, servers: Option<BTreeMap<String, ServerTools>>. |
ServerTools |
allowed, blocked, default: Option<ToolDefault>. |
ServerPolicy |
blocked, default: ToolDefault, allowed. |
ToolDefault |
Allowed (the default) or Blocked (new tools blocked until reviewed). |
LayerProblem |
key, message: an invalid-metadata error. |
NamedTools |
targets, tools. |
layer_of(&Value, key) |
A layer from its front matter value, with its problems. |
merge_policy(host, author) |
The layers merged; None when neither is given. |
normalize_target(&str) |
A target as compared: an http(s) URL as the WHATWG parser serializes it, without default port, credentials, fragment or trailing slash; anything else trimmed and lower-cased. |
remote_targets(kind, &Attrs) |
The targets by which an object reaches outside its document. |
named_tools(&Node, body) |
The tools an object names, and its server's targets. |
host_block(layer), with_host_block(text, block) |
The host's host-integrations lines, and the text as served with them. |
authored_candidates(&[u8]) |
What an author may have signed, given a served text. |
Resolution
| Item | Signature | What it does |
|---|---|---|
resolve |
fn(&str, &ResolveOptions) -> Resolution |
Reads, loads what the document composes through opts.load (each source once), composes. |
resolve_with |
fn(&str, &HashMap<String, Source>, &ResolveOptions) -> Resolution |
The same over sources already loaded, by resolved URI. |
resolve_tree |
fn(&Document, &HashMap<String, Document>, &ResolveOptions) -> Resolution |
Resolves JSON trees; a tree's digest is its canonical JSON's. |
references_of |
fn(&Reading, base: &str) -> Vec<String> |
The sources a document composes (its bases and includes), as resolved URIs. |
resolve_uri |
fn(reference: &str, base: &str) -> String |
RFC 3986 reference resolution. |
slug |
fn(&str) -> String |
A heading's generated anchor. |
resolve::allowance_of |
fn(text, id, &sources, &ResolveOptions) -> Option<(Object, Vec<Diagnostic>)> |
One allowance as a host applies it, parameters filled in. |
ResolveOptions (all Default):
| Field | Type | Default | Meaning |
|---|---|---|---|
uri |
String |
"document.md" when empty |
The document's URI; relative references resolve against it. |
version |
String |
"" |
The document's version, recorded in the artifact. |
params |
Object |
empty | Parameter values. A base gets its record's with. |
load |
Option<Loader> |
None |
&dyn Fn(&str) -> Option<Source>; resolve only. None from it: absent or not readable. |
max_depth |
usize |
8 when 0 | Deepest composition. |
max_sources |
usize |
64 when 0 | Most sources. |
Source { uri, text, version }. Resolution { ok, resolved: Resolved, text, diagnostics, root: Reading }.
Resolved { format, status ("complete" or "partial"), document: ResolvedDocument { uri, sha256, version }, body, extensions, objects, resources, dependencies, provenance, diagnostics, resolved_digest }, with manifest() and
to_json(). Manifest { format, status, document, dependencies, resolved_digest }. Dependency, Provenance,
ExtensionBinding, Selector (Id, Heading, Lines), ReferenceRecord: each with to_json().
Signatures (feature verify)
| Item | Signature | What it does |
|---|---|---|
verify_author |
fn(jws, authored: &[u8], keys: &[Jwk], &VerifyOptions) -> VerifyResult |
Verifies an author signature over the authored bytes. A served text's host-integrations block is outside them. |
verify_delivery |
fn(jws, delivered: &[u8], delivery_keys, author_keys, &DeliveryVerifyOptions) -> VerifyResult |
Verifies a delivery signature, then the embedded author signature. |
public_jwk |
fn(public_key: &[u8], kid: &str) -> Jwk |
The JWK (OKP, Ed25519) of a raw 32-byte public key. |
SigningKey |
from_seed(&[u8]), generate(), public_key(), public_jwk(kid) |
An Ed25519 key, for tests and tooling. |
sign_jws |
fn(&Object, &SigningKey, typ: &str) -> String |
Signs claims as a compact EdDSA JWS. |
verify::b64url_encode, verify::b64url_decode |
Base64url without padding. |
Jwk is Object. VerifyOptions: doc (the expected doc claim; empty: any), publisher (the pinned pub;
empty: any), now: Option<i64> (Unix seconds; None: now). DeliveryVerifyOptions: aud (required: this
reader's audience), authored: Option<Vec<u8>> (when known, the author digest must be theirs), publisher, now.
VerifyResult { ok, code, claims, author, reason }.
code |
When |
|---|---|
ok |
Verified. |
malformed |
Not a compact JWS, or a part that is not base64url JSON. |
unknown-key |
No key in the set is an Ed25519 JWK to try. |
bad-algorithm |
The header's alg is not EdDSA. |
bad-signature |
No key in the set verifies the signature. |
unknown-format |
The spec claim is not instruction/1. |
typ-mismatch |
The typ claim (or header) is not the attestation expected. |
expired |
The exp claim is past. |
digest-mismatch |
A digest is not the bytes': authored, delivered, or the resolved document's. |
doc-mismatch |
The author's doc is not the expected one, or not the delivery's. |
unpinned-publisher |
The pub claim is not the pinned publisher. |
audience-mismatch |
The delivery's aud is not this reader. |
manifest-invalid |
The delivery does not name its resolution. |
author-missing |
The delivery embeds no author signature. |
capabilities-exceeded |
The delivery's capabilities exceed the author attestation's. |
A delivery whose embedded author signature fails has that signature's code.
Digests and canonical JSON
| Item | What it does |
|---|---|
digest(&[u8]) |
sha256:<hex> of bytes. |
digest_text(&str) |
The digest of a text's UTF-8 bytes. |
author_digest(&[u8]) |
The digest an author signature binds: the stored bytes as they are. Same as digest. |
front_matter_id(&[u8]) |
The front matter's id, the value an attestation's doc claim names. |
sha256_hex(&[u8]), digest::sha256(&[u8]) |
Lower-hex and raw SHA-256 (the crate's own, no ring). |
canonical_json(&Value), json_digest(&Value) |
RFC 8785 canonical JSON, and its digest. |
js_number(f64) |
How ECMAScript writes a number. |
Registry
| Item | What it does |
|---|---|
registry() |
The embedded specification registry, typed (Registry: format, spec, common_attributes, kinds, inline, keywords, keyword_flags; kind(name) and the grammar's patterns). |
registry::kind(name) |
A block kind's KindSpec: body, forms, attributes, required, family, alias, flags, parent, opaque, formats. |
attr_spec(kind, key), inline_attr_spec(kind, key) |
An attribute's AttrSpec (attr_type, enum_values, pattern, minimum, maximum, items). |
canonical_kind(kind), is_rule(kind), all_families() |
A kind's normalized meaning (always → must), whether it is a rule, every family. |
registry::{RULES, TYPED_REFERENCES, FRONT_MATTER_KEYS, BACKMATTER_KEYS, PRESENTATION_ATTRS, REGISTRY_JSON, inline_required} |
The registry's lists, and the raw JSON. |
Pattern |
The crate's linear-time regular expressions: new, is_match, find, find_str, captures, find_iter, captures_iter, replace_all, captures_at. |
Workflows
| Item | What it does |
|---|---|
workflow_diagnostics(&Value, extensions: Option<&Object>) |
A workflow definition's diagnostics, without lines. |
workflow_registry() |
The embedded workflow registry (WorkflowRegistry: format, dialect, revision, kinds: WorkflowKind, common_fields, limits: WorkflowLimits { steps, body_depth, retry_max }). |
workflow_scope(kind) |
The field that holds a scoping kind's nested steps. |
Modules for hosts
These are public modules, used by path:
allowance: spending allowances, the first edition'sallowanceblocks (§10.1).typed(&Map) -> Allowance(id,title,wallets,currency,max,budget,per,times,payees,categories,from,until,approve_above,approver; amounts are decimal strings, never floats),problems,unresolved,widenings(before, after),sentence,instant,list,protocol_ok,PERIODS,PARAMETER_KEYS,Problem { code, message }.protocol: protocol values such asa2aorx402/1,2, and the versions two sides share (what a host needs to decideprotocol-unsupported).parse(&str) -> Option<Protocol { name, versions }>,Compat(Exact,SemverMinor,Date),compatible(compat, want, have),shared_versions.bindings: protocol bindings.known(name),x402(),openapi(),binding_from(&Value),Binding { id, version, name, versions, compat, kinds, meaning }withstable(),Maturity(Draft,Stable,Deprecated).jcs,digest,inline,lines,objects,policy,read,registry,resolve,text,types,verify,workflow,yaml,check,attributes,legacy: the modules behind the root re-exports.
The crate reads no environment variables and no configuration files.
Limits
Guards for hostile input:
- Directives nest at most 128 deep. A deeper opener stays prose, with an
invalid-nestingdiagnostic. - YAML nests at most 256 deep.
- Directive labels are scanned for nested forms 32 deep.
- Patterns run on a Pike VM, linear in their input.
- Composition stops at 8 levels and 64 sources by default, with an error.
Offsets (InlineToken::start, …) are byte offsets into the source.
Security
- No I/O. The crate opens no files and no connections and reads no environment variables. What it reads is
what you pass. With the
verifyfeature it reads the system clock (unless you passnow) and, inSigningKey::generate(), the operating system's random number generator. - Untrusted input. Every entry point is meant for untrusted text: no panics, no
unsafe, bounded nesting. - Signatures. Ed25519 over compact JWS (
alg: EdDSA), throughring. Other algorithms are refused (bad-algorithm). Pin the publisher and the document (VerifyOptions::publisher,doc) or you only learn that someone signed. Key state (active, retired, revoked) is yours to apply before you pass the key set. - Not reviewed. The verification has not had an independent security review yet.
- What a signature means. It proves who published the bytes, not that following them is safe. See Signing and trust.
Report a vulnerability privately, not in a public issue: write to us through Contact us and say it is a security report. Include what you found, how to reproduce it (a document or code that shows it) and the crate version. Fixes go into the latest release.
Compatibility and versioning
- The crate follows semantic versioning. While it is 0.x, a minor version (0.5 → 0.6) may break the API, and a patch version does not. The changelog marks every break as Breaking.
- Build option structs with
..Default::default()(ReadOptions,ResolveOptions,VerifyOptions,DeliveryVerifyOptions,TextOptions): new fields have been added in minor versions. - It reads the specification's first edition,
instruction/1(spec: "1"). Documents in the older 1.1 syntax are reported (instruction.md/legacy-syntax), not converted. - Each release names the specification commit it implements (
SPEC_COMMIT). - The minimum Rust version is 1.96. Raising it is a minor-version change.
How it differs from the Go SDK
- The YAML reader is this crate's own (Go wraps
gopkg.in/yaml.v3). The values and every refusal the specification names (repeated keys, anchors and aliases, tags, non-string keys, non-finite numbers, a second document) are the reference's, with its messages; a syntax error's wording is this reader's. Where yaml.v3 (a YAML 1.1 reader) and the reference's YAML 1.2 reader disagree, this crate reads as the reference does:?inside a plain scalar in a flow collection ({ uri: https://example.org/?q }) andkey:[…]in a flow mapping are values, and a flow collection's or quoted scalar's continuation lines must be indented past their block collection. - The inline tokenizer is a hand-written scanner with micromark's precedence (Go ports micromark itself): code spans, escapes, autolinks, raw HTML, link destinations and titles, definitions, tables and GFM autolink literals hide the forms, as there. It passes every inline vector and the read vectors.
- Patterns use this crate's small regular-expression engine.
- Policy targets: a host with non-ASCII characters is lower-cased, not converted to its IDNA (punycode) form.
Coming from agentd-instruction
agentd-instruction reads the 1.1 syntax; this crate reads instruction/1. Where a concept carried over:
| agentd-instruction | instruction-md | Note |
|---|---|---|
parse(text) -> Result<Document, Vec<Refusal>> |
read(text, &ReadOptions) -> Reading |
reading.document is the tree; reading.diagnostics (plus check_reading for the inline checks) replace the Err; reading.has_errors() |
Refusal { line, code, message } |
Diagnostic { code, severity, message, range, uri, … } |
same stable codes as the Go/TS readers; d.line() is range.start; warnings too, not only refusals |
deliver(&doc, &ctx) -> Delivery { text, manifest } |
reading.text(params), or resolve(...) -> Resolution { text, resolved, ok, diagnostics } |
deliver(text, params) is the one-call shortcut |
Context { params, resolve_include, .. } |
ResolveOptions { params, load, uri, .. }, TextOptions { params, .. } |
instruction/1 has no grants, facts or variants |
Manifest (§7.4) |
Resolved::manifest() -> Manifest |
format, status, document (the authored digest and version), dependencies (the includes and bases), resolved_digest; no facts or variants in instruction/1 |
digest(&[u8]) |
digest(&[u8]) |
sha256:<hex> |
author_digest(&[u8]) |
author_digest(&[u8]) |
the stored bytes as they are: in instruction/1 no signature: line is left out |
front_matter_id(&[u8]) |
front_matter_id(&[u8]) |
read from the front matter by the YAML reader |
doc::Node, doc::Block |
Node (node_type: Markdown or Directive) |
a block is a directive node: kind, form, attrs, children, value, range |
doc::Form |
Form (Container, Leaf, Keyword, Alert) |
no sets or sections in instruction/1 |
doc::BodyKind |
KindSpec::body (markdown, yaml, none) and StructuredValue::format (yaml, json, csv, text, html, code) |
from registry().kind(name) |
doc::Disposition |
is_connected, carries_configuration, is_layout |
by the registry's families: connected_objects, configuration_blocks, walk |
doc::all_families() |
all_families() |
the registry's families |
doc::lookup(kind), registry() |
registry::kind(kind), registry() |
the embedded registry.json, typed |
tree_json(&doc) |
Document::to_json() |
the tree instruction.schema.json validates |
validate(&doc, &ctx) |
check_reading(&reading) |
|
yaml::parse(src) -> Result<Value, YamlError> |
parse_yaml(src) -> Result<Value, String> |
YAML 1.2 Core Schema, JSON-compatible values only |
sign::verify_author, sign::verify_delivery, sign::verify_document |
verify_author, verify_delivery |
keys as JWKs (public_jwk(raw, kid)); results are VerifyResult { ok, code, claims, author, reason } |
sign::Claims |
VerifyResult::claims (a JSON object) |
Troubleshooting and FAQ
cargo says the crate needs a newer Rust. It needs Rust 1.96 or later. Run rustup update stable.
ring fails to build on my target. Turn the verify feature off (default-features = false). Reading,
checking, resolving and digests still work.
verify_author and friends are not found. They need the verify feature, which is on by default. Check that
you did not set default-features = false.
My struct literal for ReadOptions stopped compiling after an upgrade. A field was added. Write
ReadOptions { uri: "…".into(), ..ReadOptions::default() }.
A :::!policy block reads as plain text. That is the 1.1 syntax. deliver and legacy_diagnostics report
each such line as instruction.md/legacy-syntax. Convert the file with upgrade() from the npm package
instruction.md.
resolve reports a base or include as missing. The resolver fetches nothing. Your loader got the resolved URI
(relative to ResolveOptions::uri, without a fragment) and returned None. Log the URIs it is asked for, or use
references_of to list them first.
verify_delivery says audience-mismatch. DeliveryVerifyOptions::aud must be exactly the audience the
delivery was signed for (the reader's principal).
Can this crate follow an instruction over MCP? No, it does no I/O. Use the npm or Python package, or connect
your agent to https://instruction.md/mcp. See Connect an agent.
Contributing
Bug reports and fixes are welcome. Open an issue (start the title with "Rust SDK") with the document or code you ran, what came out, what you expected, and the crate version; a failing test is best. For a new API, open an issue first so we can agree on its shape.
The crate is held to the TypeScript reference and the Go SDK byte for byte, so a fix that makes it disagree with
them needs the same fix there. It keeps three rules: no unsafe and no panic on any input, no I/O, and no new
dependencies without discussion. The tests read the conformance data in the crate's source repository (it is left
out of the crates.io package):
NO_PANIC_ROUNDS=2000
A change to what the language means belongs in the specification, not here.
Changelog
See CHANGELOG.md. Releases are tagged rust-sdk-v<version> and published to
crates.io.
License
Licensed under either of the MIT license or the Apache License, Version 2.0, at your option. Unless you say otherwise, a contribution you submit for inclusion in this crate is licensed as above, without other terms.
The embedded registries (src/registry.json, src/workflow-registry.json) are the instruction.md specification's,
redistributed verbatim under CC BY 4.0. See NOTICE.
Copyright (c) 2026 TSOK Inc.