Skip to content

docs: several design documents say IDs survive renames, which pointer-derived IDs don't #677

Closed

Description

@OmarAlJarrah

Problem

Operation IDs are built from the path (op/openapi/paths/~1pets/get) and component IDs from the component name, so renaming /pets to /animals or Pet to Animal changes the ID of the entity and of every anonymous node beneath it. Several places promise the opposite:

  • docs/architecture.md:189 (keys "which survive path and name churn")
  • docs/emitters/plan/overview.md ("A spec rename never orphans a plan entry"), docs/emitters/contract/shaping-hints.md ("a path rename never drops a hint"), docs/emitters/write-integrate.md, docs/emitters/surface-verification.md, docs/emitters/testing/mandatory-tests.md (T-8), docs/emitters/README.md
  • docs/ir/identity.md ("diffable across spec revisions")
  • docs/prior-art.md:46 and :91, docs/reference-learnings.md:174

#419 asks for the answer to be stated in docs/ir/open-questions.md; these statements elsewhere contradict it.

Expected

Narrow each claim to what holds (stable within one document; stable across revisions only when nothing on the pointer changes), or point it at the correlation mechanism once one exists (#679).

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P3Later emitters, M4 and up, 3.2-only, streaming, webhooks, rare constructstype:docsDocumentation only

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions