instruction-md (Rust)
The official Rust SDK for instruction.md: the specification's first edition
(instruction/1, spec: "1"). It reads a document into its authored tree with the reader's diagnostics, checks it
(the inline checks too), gives the agent's text (instruction-text/1), resolves a document with its bases and includes
into the resolved artifact (instruction-resolved/1), and verifies author and delivery signatures (JWS, Ed25519).
It is a port of the Go SDK (sdks/go), itself a port of the TypeScript reference
(packages/spec), and is held to them by the specification's conformance cases and the
reference's vectors, vendored in conformance/ (specification commit bf4f9a0).
- Dependencies:
serde,serde_jsonand, for signature verification,ringonly. Nounsafe. - Features:
verify(default) isverify_author,verify_deliveryand signing (for tests and tooling), the only use ofring.default-features = falsereads, checks, resolves and digests (its SHA-256 is its own) with noring. - Every entry point takes untrusted text and never panics: a problem is a [
Diagnostic] with a stable code (the codes the Go and TypeScript readers emit:unclosed-directive,invalid-attributes,reference-optional, …). - Edition 2024, Rust 1.96 or later.
[]
= "0.5"
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!;
instruction_md::deliver(text, params) does both in one call: (agent text, diagnostics), with the lines written in
Specification 1.1 (legacy_diagnostics, code instruction.md/legacy-syntax, an error: a :::!kind block reads as
prose here) as the TypeScript CLI reports them. reading.changes_text() says whether the agent text differs from the
source at all (plain prose and canonical rules are handed on as written).
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);
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
(src/workflow-registry.json) 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 (512 steps in a scope, bodies nested deeper than
4, retry.max over 20) and extension-unavailable (an alias:node kind whose alias isn't declared), each 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, from reference/workflows.md, since the registry doesn't say); 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 (S34)
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 only narrows it. The reader
merges them into Reading::policy (a target is allowed only where every layer that lists targets lists it; a tool is
blocked where any layer blocks it) and warns, never refuses: tool-blocked (a tool 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 are 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
use HashMap;
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)
resolve_with takes sources already loaded (a map by resolved URI), resolve_tree resolves JSON trees.
Verify a signed read
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; 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).
verify_author checks an author signature over the authored bytes; public_jwk makes a JWK of a raw 32-byte Ed25519
key, and SigningKey + sign_jws sign (for tests and tooling).
For agentd: agentd-instruction → instruction-md
agentd-instruction reads the 1.1 syntax; this crate reads instruction/1. Where a concept carried over, its
equivalent:
| 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 vendored 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) |
Not in this crate
- The follower and its MCP transport (the Go SDK's
follow.go,mcphttp.go): following an instruction a registry serves, and reporting what was applied. They need an HTTP client; this crate does no I/O. - The upgrade from the 1.1 syntax (this crate reports its lines,
legacy_diagnostics; the conversion is the TypeScript package's), the editor's fixes and the extension manifests' binding.
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 TypeScript 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 (a Pike VM over the specification's patterns), linear in its input.
- Guards for hostile input: directives nest at most 128 deep (deeper openers stay prose, with an
invalid-nestingdiagnostic), YAML nests at most 256 deep, and directive labels are scanned for nested forms 32 deep. - Offsets (
InlineToken::start, …) are byte offsets into the source, as in Go.
Tests
NO_PANIC_ROUNDS=2000
conformance/ holds copies of the specification's conformance cases, schemas and samples and of the reference's
vectors (see conformance/README.md); tests/data/home holds the repository's home examples
with the agent text and tree the Go SDK gives for them.
Licence
Licensed under either of the MIT licence 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. This crate is permissively licensed although the repository around it is not (see NOTICE). The
embedded registry (src/registry.json) is the specification's, under CC BY 4.0 (see NOTICE).