statecraft.
Catalog/spec-spine

074-a-governed-read-names-its-version

A governed read names its version

Lifecycle approvedImplementation completeVerification unknownQualification unknown

`docs/api.md` states that every JSON this tool emits is pretty-printed with sorted keys, and spec 034 gave every verdict verb a versioned envelope. The read verbs got neither. Measured at 0.19.0: thirteen read documents across ten verbs, of which twelve carry no version member at all and seven emit keys in struct declaration order, because they serialize with `serde_json::to_string_pretty` while every committed artifact goes through the canonical writer. A consumer therefore pins a document whose shape it cannot dispatch on and whose key order is an implementation detail of a Rust struct. This spec routes every read document through one emitter that sorts keys and stamps a new `READ_SCHEMA_VERSION`, and decides note 04's D7: the version is an additive member on an object document, and the documents that are not objects today become objects so they can carry one. Four documents across three verbs change shape breakingly, and two of the four are contracts approved specs state, so this spec carries `amends` edges to 010 and 060 rather than editing them.

Read the full pinned specification ↗

Relationships

Claimed units

  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-core/src/read.rs"
}
  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-core/tests/read.rs"
}
  • extends
    {
  "nature": "additive",
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/lib.rs"
  }
}
  • extends
    {
  "nature": "corrective",
  "spec": "002-registry-query",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_registry.rs"
  }
}
  • extends
    {
  "nature": "corrective",
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_index.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "034-machine-readable-verdicts",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/version.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "034-machine-readable-verdicts",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/lib.rs"
  }
}
  • extends
    {
  "nature": "corrective",
  "spec": "047-effective-config-is-a-governed-read",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_config.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "057-the-docs-name-what-adopters-derived",
  "unit": {
    "kind": "file",
    "path": "docs/schema-versioning.md"
  }
}
  • extends
    {
  "nature": "corrective",
  "spec": "029-ownership-coverage",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/tests/coverage.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "034-machine-readable-verdicts",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/tests/cli.rs"
  }
}

Source headings

  1. 074: A governed read names its version
  2. 1. Purpose
  3. 1.1 Two guarantees that stop at the verdict verbs
  4. 1.2 What an unversioned read costs a consumer
  5. 1.3 A read is not a verdict
  6. 2. Territory
  7. 3. Behavior
  8. 3.1 What a read document is
  9. 3.2 One emitter
  10. 3.3 Every read document is an object
  11. 3.4 The version axis
  12. 3.5 Sorted keys, stated once and true
  13. 3.6 The breaking changes, named
  14. 3.7 `config show` keeps its own version member
  15. 3.8 The tests
  16. 4. Out of scope
  17. 5. Resolved decisions
  18. Verification

Frozen anchors

No frozen anchors declared.