Skip to content

Conformance

An implementation claims conformance only for named classes, and names the edition. It MUST say which optional extensions it does not support, and MUST NOT present reading a declaration as having applied it. A class that applies a field applies its defaults too, unless the manifest turns them off.

Classes

Class Obligations Vectors
Read-only consumer Lists and reads overlay files; treats an absent manifest as valid; says when it ignored an unreadable one. Shows an OVERLAY.md as a viewer does, and lists skills from elsewhere as named, not as present. The split's cases of front_matter.json
Manifest reader Reads OVERLAY.md and overlay.cfg as Manifest says: the split, the format line, TOML and restricted YAML, the data model, static reading, limits. States which optional formats it reads. Preserves unknown top-level keys. reading.json, front_matter.json
Validator Validates the data model against the schema and the semantic rules, including that named files exist, that an overlay has one manifest and, given the files, that env sets no variable the default paths adds to; flags each skill name neither bundled nor sourced; reports problems under about without stopping the manifest from applying. validation.json
Environment Builds the environment from root variables, env, env_files and paths in the order of application, substituting each text value as it is set; resolves secret references or refuses; reads env-script output; reports non-default settings. effective.json, compose.json, the dotenv (substitution included) and env-script cases of reading.json
Runtime and setup Selects variants per OS and default scripts, probes what an overlay needs, runs setup in its phases as Runtime and setup says, reports non-default settings. effective.json
Hooks Reads hooks and the hook.<ext> default; keeps an overlay's hooks and env scripts off until the user allows them at its digest and lists them before installing; fires each Core event on every harness, and each Extended one the harness allows, or reports it; sends each event's payload and nothing else; applies outputs, an allow only where the user's own refusals still win, and combines decisions to the tightest, reports what it cannot apply; bounds time, output, payload and added context; runs an event's hooks in composition order, then the user's and the project's, each in the session's folder with the session's environment; fails a guard closed. hooks.json, the pre_env cases of compose.json, the hooks cases of validation.json
Templating Replaces ${NAME} as Templating says, in the context it assembles and in the body of each bundled skill it serves, when it serves them and never in an installed file; replaces the five AOS_ names and the overlay's options and leaves every other placeholder as written; reads $${ as ${; never puts a sensitive option in context; refuses a configured value of the wrong type. templating.json, the options cases of validation.json
Knowledge Required of every consumer that runs an agent session with overlays active, where its harness can connect to an MCP server. Offers kb_list and kb_read with the input schemas of the vectors, over the overlays' knowledge and nothing else; reads paths as relative paths, never leaves the root, refuses a link; orders and counts lines as the text says and bounds a read; writes served text out; serves a markdown file in the expanded format unless its first line names another format: ${NAME} replaced and @path included inside the overlay, to a depth, never in code and never out of the root; markdown, md and raw as written; a file that is not markdown as written, whatever its first line; envsubst (GNU's by default) and mustache (the specification's), with the options of their first line, rendered with the facts where it has them, and an engine it does not have served as it is with the context in a front matter, never refused; counts the lines of that served text in kb_read, kb_list and search; says an overlay is served only when it left its rules and context out of the context. A consumer that serves a search also declares its modes, answers in the result shape and order, and never returns a passage that is not of a served file. knowledge.json, knowledge_search.json, the knowledge cases of validation.json
Integrity Computes the tree digest and enforces pins. digest.json
Resolver Parses sources, validates and normalizes identities, resolves requires, orders the active overlays; resolves skill names through catalogs, reporting each missing and ambiguous one. source.json, names.json, compose.json, skills.json
Manager Installs, updates and removes overlays; documents scopes, merge targets, collisions and execution policy; protects user-owned data; never runs code because an overlay was fetched; fetches and checks an overlay's skills from elsewhere only after the user accepts them, or reports each as not delivered. skills.json
Store Reads catalogs in both forms, their overlays and skills, resolves their sources, refuses entries alone and leaves out invalid informational fields; lists several catalogs by label, qualifying names they share; shows about and icons as that section says; treats a catalog as advertising and shows what an overlay would do from its fetched manifest before installing. catalog.json, the catalog cases of reading.json, the about cases of validation.json

Vectors

The vectors are JSON files in tests/vectors/, data rather than code, so an implementation in any language reads them with its own JSON library and compares its results. Each file has a description, the spec section it tests, and cases, each with an id, its input and an expect.

  • Types are part of a value. 30 and 30.0 differ, and so do 1 and true.
  • Mapping order carries no meaning; array order does.
  • Errors are classes, such as parse-error or symlink. An implementation maps its own errors to them; where two classes are right, expect.error lists both, and where reading and refusing are both right, expect has both data and error.
  • A refusal's subject is safe to show. Where a vector records the subject of a refusal (effective.json), it is the variable, path or key the refusal is about, with each control, format, line-separator, paragraph-separator, surrogate, private-use or unassigned character (Unicode general categories Cc, Cf, Zl, Zp, Cs, Co and Cn) written as \xNN below U+0100, \uNNNN below U+10000 and \UNNNNNNNN above, in lowercase hexadecimal, and the whole cut to 256 characters, which are counted after the escapes, with ... after them when it was cut.
  • A file names every input it needs: file contents, an OS, an environment, secrets. No vector reads the filesystem or the network, except that digest.json trees can also be built on a filesystem that can hold them.
File Input Expect
reading.json Document bytes (text or base64), format (aos, dotenv, env-script for an env script's output, or catalog with the file name), optional limits; for dotenv, optional env, os and secret_variables to substitute against data, or error
front_matter.json Document bytes (text, base64, or parts to concatenate, for what is too large to write out) with optional limits; a context_file; or an overlay's files The split's and the reading's case, the metadata and body with their offsets and lines, the format, the data or the error and line; the context's text; or the manifest and the file it came from, the context in order, what was ignored, the problems and the digest
skills.json overlays, requested, optional files, catalogs, order and fetches; or a fetched skill's files, its name and an optional pin Each skill with its origin and source, the missing, ambiguous, unpinned and not-fetched names, what is delivered and the collisions; or the fetched tree's digest, the front matter keys it reports and the files the digest covers, or the refusal
validation.json A data model document, optional files valid, and for a valid one the pointers of any names flags picks out; for an invalid one the pointer at of the offending value, and its class where the text names one; where about is written, whether the manifest still applies
names.json An overlay name valid, normalized, variable
source.json A source string kind, location, ref, path, or error
digest.json A tree of files, directories, links and special files digest and its lines, or error
compose.json overlays by identity, requested, optional files (each overlay's files, for defaults) and facts, which may give each overlay's installed packages, the overlays removed, and what each overlay's pre_env hook did The visiting order, the composition order, missing requirements, contributions, the environment; the dependency environments, their conflicts, the overlays blocked by them and what a removed overlay leaves; the hooks' reports; or the cycle
hooks.json A manifest or an overlay's files, and the consumer's facts (OS, interpreters, scope, digest or a project's tree, the digest allowed, the events it can fire, in full or in part); an event and what the consumer knows; a match and a reason or tool kind; one hook's run; an event's runs, what the consumer applies on the harness, limits, the OS and the context_used so far; the overlays and the hooks of an event to put in order; or an environment for one hook Each hook with its script, match, sets, timeout and payload keys, whether they are on and the overlay activates, the reports and non-default settings; the payload; whether the hook runs; the output that applies or the cause of the failure; the decision, by whom, the context, the variables, the reports; the order of the hooks; the environment a hook runs with
templating.json A kind (context or skill), the file's bytes (text or base64), the overlay's manifest (its options) and the consumer's facts: root, state, name, scope, project and the options the user configured The text the agent receives, or the error class
catalog.json A catalog (file name, text, and the base it was read from); several catalogs, each with its label, and names to choose; or an icon (name, base64, optional limits) The form, informational fields, entries with absolute sources, skills where the catalog has them, refused entries and ignored fields, or the error; the listing, collisions and what each name picks; the icon's format and dimensions, or the refusal
knowledge.json The tools a server offers for its declared modes and limits; a tool call's arguments; or a tool call on the session's overlays (each with its manifest, its tree as digest.json writes it, whether it is served, and its template facts), with the caller's facts (caller, env, env_allow) and limits; a handler's outcome as MCP's result; or a manifest and files with the user's choice The tools and their input schemas; the arguments with their defaults, or invalid-arguments; the listing or the lines read, or the error class; the MCP result; whether the overlay is served and which files it leaves out of the context
knowledge_search.json The session's overlays, the call's arguments, the declared modes and an answer response; or passages The ids of the rules the answer breaks, none when it conforms; or the passages in the order a search gives them
effective.json One manifest and the consumer's facts, the overlay's files, the interpreters it has among them and its installed packages; for setup phases, the change (add, sync, activate, remove), the digest, the allowed digest, the record and the step that fails The environment, the selected setup and runtime variants, the dependencies, what a probe needs, the non-default settings, the reports (an env script the allowance does not cover), and the setup phase, its arguments, the steps in order, the record afterwards and whether the digest activates; or the refusal

This repository runs every vector through a small Python reader (tests/aos_reference.py, python -m pytest), and the digest vectors were also checked with an independent shell implementation. A vector that disagrees with the text is a bug in the vector.

Passing the vectors does not make an overlay safe, or a consumer secure: they check that implementations agree.