Expand description
instruction-md — the instruction.md specification’s first edition (instruction/1) in Rust: the reader and
its checks, the inline syntax, composition into the resolved artifact and the agent’s text, the registry, the
formatter, digests and signature verification.
It is a port of the Go SDK (sdks/go), itself a port of the TypeScript reference (@instruction-md/spec), held to
them by the specification’s conformance cases and the reference’s vectors.
use instruction_md::{read, ReadOptions, check_reading};
let doc = "---\nspec: \"1\"\nparameters:\n tz: { type: string, default: UTC }\n---\n\
MUST: plan the day in ${tz}.\nBECAUSE: the owner reads the brief at 7.\n";
let r = read(doc, &ReadOptions::default());
assert!(check_reading(&r).is_empty());
assert_eq!(r.text(None), "MUST: plan the day in UTC.\nBECAUSE: the owner reads the brief at 7.\n");Every function takes untrusted text: none panics, and every problem is a Diagnostic with a stable code.
Cargo features: verify (default) is signature verification (verify_author, verify_delivery) and signing
for tests and tooling, by ring; without it the crate depends on serde and serde_json alone.
Re-exports§
pub use attributes::parse_attributes;pub use check::Target;pub use check::check;pub use check::check_reading;pub use check::inline_diagnostics;pub use check::resolve_target;pub use check::workflows_diagnostics;pub use digest::digest;pub use digest::digest_text;pub use digest::front_matter_id;pub use digest::sha256_hex;pub use inline::InlineToken;pub use inline::TokenType;pub use inline::inline_tokens;pub use inline::split_wiki;pub use jcs::canonical_json;pub use jcs::json_digest;pub use legacy::LEGACY_SYNTAX;pub use legacy::legacy_diagnostics;pub use lines::LineInfo;pub use lines::classify_lines;pub use lines::format;pub use objects::ConfigurationBlock;pub use objects::ConnectedObject;pub use objects::Location;pub use objects::carries_configuration;pub use objects::configuration_blocks;pub use objects::connected_objects;pub use objects::is_connected;pub use objects::is_layout;pub use objects::walk;pub use pattern::Pattern;pub use policy::AUTHOR_POLICY_KEY;pub use policy::HOST_POLICY_KEY;pub use policy::INTEGRATED_KINDS;pub use policy::LayerProblem;pub use policy::NamedTools;pub use policy::Policy;pub use policy::PolicyFrom;pub use policy::PolicyLayer;pub use policy::ServerPolicy;pub use policy::ServerTools;pub use policy::ToolDefault;pub use policy::host_block;pub use policy::layer_of;pub use policy::merge_policy;pub use policy::named_tools;pub use policy::normalize_target;pub use policy::remote_targets;pub use policy::with_host_block;pub use read::ReadOptions;pub use read::Reading;pub use read::SplitBackmatter;pub use read::Stripped;pub use read::read;pub use read::split_backmatter;pub use read::strip_comments;pub use read::value_fits;pub use read::value_from;pub use registry::AttrSpec;pub use registry::KindSpec;pub use registry::Registry;pub use registry::all_families;pub use registry::attr_spec;pub use registry::canonical_kind;pub use registry::inline_attr_spec;pub use registry::is_rule;pub use registry::registry;pub use resolve::Dependency;pub use resolve::ExtensionBinding;pub use resolve::Loader;pub use resolve::Manifest;pub use resolve::Provenance;pub use resolve::RESOLVED_FORMAT;pub use resolve::Resolution;pub use resolve::ResolveOptions;pub use resolve::Resolved;pub use resolve::ResolvedDocument;pub use resolve::Selector;pub use resolve::Source;pub use resolve::references_of;pub use resolve::resolve;pub use resolve::resolve_tree;pub use resolve::resolve_uri;pub use resolve::resolve_with;pub use resolve::slug;pub use text::Known;pub use text::ReferenceRecord;pub use text::TextOptions;pub use text::to_text;pub use text::value_text;pub use types::Attrs;pub use types::Diagnostic;pub use types::Document;pub use types::Form;pub use types::Identity;pub use types::Metadata;pub use types::Node;pub use types::NodeType;pub use types::Object;pub use types::Parameter;pub use types::Range;pub use types::Severity;pub use types::StructuredValue;pub use types::TREE_FORMAT;pub use verify::DeliveryVerifyOptions;pub use verify::Jwk;pub use verify::SigningKey;pub use verify::VERIFY_CODES;pub use verify::VerifyOptions;pub use verify::VerifyResult;pub use verify::public_jwk;pub use verify::sign_jws;pub use verify::verify_delivery;pub use workflow::WORKFLOW_DIALECT;pub use workflow::WORKFLOW_SCOPES;pub use workflow::WorkflowKind;pub use workflow::WorkflowLimits;pub use workflow::WorkflowRegistry;pub use workflow::workflow_diagnostics;pub use workflow::workflow_registry;pub use workflow::workflow_scope;pub use yaml::parse_yaml;
Modules§
- allowance
- S29 (first edition §10.1): an allowance’s own checks, what makes a changed one wider, and the fixed sentence it is
delivered as — the port of
packages/spec/src/allowance.ts, held to its vectors (vectors/allowance). The reader runsproblemson the values as written (a${parameter}is left for later); the composer runs it again once parameters resolve, checks the references, and compares an inherited allowance with what replaced it (widenings). - attributes
- Attribute lists (§5.2):
{id=x class="a,b" title="A title"}, with{#x .a .b}as sugar. - bindings
- S28 bindings as data: a
bindingextension manifest read (itsprovides.protocol), and the manifests this crate ships so a host need not hard-code a protocol’s stable versions. The port ofpackages/spec/src/bindings.ts. The core names no protocol; these are extensions, versioned on their own, and a host may load others the same way. - check
- The inline checks (§11.1, §12), over the prose the reader found: an inline kind this specification or the
document’s extensions do not define, a missing required attribute or label, a typed reference to an id the
document does not have or to one of another kind, a citation of a source the backmatter does not record, an
undeclared parameter, a footnote without its definition.
checkis the reader’s diagnostics with these, in source order — what an editor shows and what a renderer reports. - digest
- Digests (§14.1, §19): SHA-256 over a source’s original bytes — no line endings normalized, no metadata removed —
written
sha256:<lower-hex>. An author signature covers the authored digest, a delivery signature the delivered text’s. - inline
- Inline syntax (§11.1, §12), read where CommonMark reads text — never inside code, raw HTML, an autolink, a link destination or title, or a definition:
- jcs
- RFC 8785 (JCS), the canonical JSON the resolved artifact’s digest and the text profile’s attribute lines use (§14.1, §14.2): object keys in UTF-16 code-unit order, no whitespace, ECMAScript’s number and string serialization.
- legacy
- Specification 1.1 syntax this edition reads differently (
instruction.md/legacy-syntax): the TypeScript package’slegacyDiagnostics(its upgrade.tslegacyLines), line for line. A 1.1 block:::!kind{…}is not a directive here — it reads as prose, and the agent receives it as written — so a reader that delivers a document reports it rather than deliver what its author did not mean. This crate reports; the conversion (upgrade) is the TypeScript package’s. - lines
- What each source line of a document is, for editors that colour or fold Markdown source, and for the formatter. Every class comes from the reader’s own tree — its metadata ranges, its directives’ opening and closing lines, its rules, reasons and alerts, its comments — so an editor cannot show a line as a rule that the reader reads as prose. Only inside a Markdown node does a line’s own text decide (a heading, a code fence).
- objects
- A typed view of what a document declares beyond its guidance: its connected objects (§10) and the blocks that carry configuration (§9.1), found by the registry’s families, with a walker over a tree’s directives.
- pattern
- A small regular-expression engine for the specification’s patterns (the registry’s grammar and attribute patterns) and the reader’s line grammar: RE2’s syntax subset those use, matched by a Pike VM — leftmost-first like RE2 and ECMAScript, in time linear in the input, so no document can make a pattern backtrack exponentially.
- policy
- The integrations policy in the front matter (proposal S34): which of a document’s MCP servers, skills and agents
may be used, and which of a server’s tools. Two layers, one shape:
host-integrations, which only the host that serves the document writes (a workspace’s policy, put in at serve time), andintegrations, which the author may write to narrow it. The effective policy (Policy,crate::Reading::policy) is both at once: a target is allowed only where every layer that lists targets lists it, and a tool is blocked where any layer blocks it, so an author can narrow the host’s policy and never widen it. A port of the reference’spolicy.ts(packages/spec). - protocol
- S28: a protocol value (
nameorname/v1,v2) parsed, and the versions two sides share under a binding’scompatrule — what a host needs to decideprotocol-unsupported. The port ofpackages/spec/src/protocol.ts. A reader checks only the syntax (protocol-syntax); choosing a version is the host’s. - read
- The reader: source → the authored tree of §2 and the diagnostics of §18.
- registry
- The registry (instruction/1, §7 and §20): every built-in block and inline kind, its body, forms and typed
attributes, the rule keywords and the grammar’s patterns. The data is the specification’s
registry.json, embedded as vendored (CC BY 4.0, instruction.md); this module only types it and answers what the reader, the text profile and the checks ask of it. - resolve
- The resolution transaction (§13, §14.1): a document, its bases and its includes become one resolved artifact
(
instruction-resolved/1) and its agent text (instruction-text/1). - text
- The text profile
instruction-text/1(§14.2): the agent’s representation of a document. Every generated unit — a rule with its reason, a### Label: Titleheading with its attribute line and children, an authored Markdown segment — is separated from the next by exactly one blank line; an authored segment is copied unchanged except that typed inline references read aslabel (kind; target), annotations as their label, and parameters as their values. Metadata and comments are never instructional body. A resolved document adds its resolved references and its composition changes after the body. - types
- The authored tree (§2) —
{format, metadata, body}, the shapeinstruction.schema.jsonvalidates — and the reader’s sidecar: diagnostics (§18), identities and parameters, which the tree itself does not carry. - verify
- Attestations: JWS/EdDSA author and delivery signatures (Ed25519, by
ring). An author signature binds a version’s authored digest; a delivery signature binds what one reader received — the delivered text’s digest — and the resolution it came from (its manifest: the resolved artifact’s format, status, document, dependencies and digest, never its body), with the author signature embedded so the chain is checked in one place. - workflow
- The checks a
:::workflow{dialect="instruction/workflow"}body is held to (§9.1, the specification’s reference/workflows.md): its steps against the specification’s workflow registry (workflow-registry.json, vendored unchanged assrc/workflow-registry.json) and its graph. A host must refuse each of these before activation, so each is an error:invalid-workflow(§18: dialect schema, dependency graph or routing invalid),limit-exceededfor the registry’s published limits,extension-unavailablefor a namespaced node whose alias the document doesn’t declare. - yaml
- Metadata and structured bodies (§3.3): YAML 1.2.2’s Core Schema restricted to JSON-compatible values. Duplicate keys, non-string keys, custom tags, anchors and aliases, non-finite numbers and a second document are errors; dates stay strings (the Core Schema infers no timestamps) and no constructor runs. JSON bodies are RFC 8259 JSON without duplicate keys; CSV bodies RFC 4180 with a header.
Constants§
- SPEC_
COMMIT - The specification commit the vendored registry and conformance data are from.
Functions§
- deliver
- Reads a document and gives its agent text with its declared defaults — the shortcut a runtime needs: the text an
agent receives (
instruction-text/1) and every diagnostic: the reader’s, the inline checks’, a native workflow’s (workflows_diagnostics) and the lines written in Specification 1.1 (legacy_diagnostics), as the TypeScript CLI reports them. An error among the diagnostics means the document should not be delivered. - js_
number - How ECMAScript writes a number (
Number.prototype.toString, which JSON and RFC 8785 also use).