---
name: manifest-doc-comment-is-a-published-schema-description
description: "A `///` on a JsonSchema-derived manifest type IS the published schema description — a wrong one ships to the docs site and release assets, and the CLAP-only memories say `///` on non-CLI types is safe"
metadata: 
  node_type: memory
  type: project
  originSessionId: 1be32cdd-c16e-48bb-80d4-de5bf5948892
  modified: 2026-08-28T06:13:10.431Z
---

`crates/spt-runtime/src/manifest.rs`'s types derive `JsonSchema`, so every `///` on a manifest
struct or field is copied VERBATIM into `crates/spt-runtime/manifest.schema.json` — the file that
ships to the docs-site root and the release assets, and the one adapter authors validate against.
The doc comment is not internal commentary about the type; it is the type's PUBLIC documentation,
and it is the only documentation a machine consumer ever reads.

**Measured 2026-08-27, IO-PARSER docs lane.** `Io::shortform`'s comment said the field opts out of
core-side `@<…@>` shortform parsing. The gate covers BOTH markers — `crates/spt/src/api/delivery.rs`
guards `dispatch_ingest_shortform` AND `dispatch_ingest_seal_mints` off that one bool — so the
published schema understated the field's blast radius. Every prose page (`frames.md`) said "one
switch, both markers" correctly; only the generated surface was wrong, which is exactly the surface
nobody re-reads.

⚠ THE TRAP IS THE REASSURANCE IN A SIBLING MEMORY. [[clap-doc-comment-leaks-req-tag]] ends with
"Library rustdoc `///` on non-CLI structs/fns is fine — it never reaches `spt --help`". That is TRUE
and it is about the CLAP gate; read as a general permission it is false for every `JsonSchema`
(and any other doc-comment-harvesting) derive. Two memories about `///` both scoped to clap read
like coverage of the whole class.

**How to apply.** When a docs pass touches a manifest field's MEANING, fix the `///` too and
regenerate: `SPT_BLESS=1 cargo test -p spt-runtime --lib checked_in_schema_is_current`, then re-run
it WITHOUT the bless (the drift gate) and read both exit files. `git diff` the schema — porcelain is
useless here, autocrlf marks the regenerated file M on EOL alone. And when auditing a documented
contract, read the GENERATED description beside the prose page: they drift independently, and the
generated one is the machine's only copy. Kin: [[cli-command-docs-drift]],
[[an-undiscoverable-shipped-surface-reads-as-missing]].