Skip to main content

Crate instruction_md

Crate instruction_md 

Source
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::author_digest;
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::authored_candidates;
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_author;
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 runs problems on 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 binding extension manifest read (its provides.protocol), and the manifests this crate ships so a host need not hard-code a protocol’s stable versions. The port of packages/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. check is 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’s legacyDiagnostics (its upgrade.ts legacyLines), 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), and integrations, 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’s policy.ts (packages/spec).
protocol
S28: a protocol value (name or name/v1,v2) parsed, and the versions two sides share under a binding’s compat rule — what a host needs to decide protocol-unsupported. The port of packages/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: Title heading 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 as label (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 shape instruction.schema.json validates — 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 as src/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-exceeded for the registry’s published limits, extension-unavailable for 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).