// SPDX-License-Identifier: CC-BY-SA-4.0
= Inline Annotations
:status: Draft v0.1.0

Structured metadata embedded in source-code comments. Annotations declare
trust, contract, and grade claims that travel with the code they describe.

== Why

The innervation architecture moves metadata off static files and into the
code itself. An `@trust(level=proven, prover=idris2)` annotation on a Rust
function is more durable than a paragraph in META.a2ml — it cannot drift out
of sync with the code because it *is* the code's comment.

== Files

[cols="1,2",options="header"]
|===
| File | Purpose

| `SPEC.adoc` | Normative specification (v0.1.0 draft)
| `examples/sources.md` | Example annotations in 8 languages
| `examples/output.a2ml` | Example extractor A2ML output
| `examples/octad-mapping.a2ml` | Annotation → VeriSimDB octad walkthrough
| `extractor/` | Rust reference extractor (to be written)
|===

== Quick Reference

[source]
----
// @trust(level=tested, prover=cargo-test, since=2026-04-01)
// @grade(value=B, basis="47 tests pass", assessed=2026-04-04)
// @contract(obligation=must, clause="SHA-pinned actions only", severity=critical)
----

== Output Format

The extractor emits **A2ML**, not JSON. Each annotation becomes one
VeriSimDB `inline-annotation` octad with four modalities (Semantic, Temporal,
Provenance, Graph).

== Status

- v0.1.0 spec: draft
- Reference extractor: not yet written (planned: Rust, ~200 LOC)
- VeriSimDB octad schema: defined in `standards/.verisimdb/config.toml`
- Hypatia verification rules: not yet written
