This specification defines versioning interpreted as semiotic interaction. It is a convention specification (per semiotic-specification) in the same family as semiotic-git, semiotic-markdown, and semiotic-project-management.
Specification category: convention specification. Canonicalization and wire-format determinism sections do not apply.
Versioning is not a bureaucratic convention layered on top of software. It is a semiotic act: assigning a version is declaring that a set of commitments has stabilized. A version number is a handle for a stable fragment. A breaking change is a change that violates commitments the stable fragment made. These identifications are formal and carry operational consequences.
0. Scope
This specification applies to versioning of any artifact in the emsemioverse: specifications, software releases, formal definitions, and content that carries stability commitments. It does not replace Semantic Versioning (Preston-Werner, 2013) but interprets it: semver’s rules are operational consequences of the semiotic model described here.
1. Semantic carrier
1.1 Version identity
A version is a named element of the semantic carrier H — an ancestry-closed subset of the artifact’s history that has been declared stable. In semiotic-git terms, a version is the ancestry cone of an annotated tag: the set of all commits reachable from the tag, closed under ancestry.
A version is not a snapshot. It is a commitment: a declaration that the interaction surface of the artifact at this point will be preserved. The version number is a handle for this commitment.
1.2 The interaction surface of a version
What a version commits to preserving is the artifact’s interaction surface — the set of typed relations and behaviors that other artifacts depend on. For a specification, this is the set of normative statements (MUST/SHOULD/MAY). For a software library, this is the public API. For a formal definition, this is the set of properties asserted.
The interaction surface is what other artifacts see when they depend on this version. A version’s commitments are exactly: the interaction surface will not change in ways that violate existing dependencies.
1.3 Version numbers as structure
Semantic versioning’s three-part number MAJOR.MINOR.PATCH encodes
the relationship between a version’s interaction surface and its
predecessor’s:
- PATCH: the interaction surface is identical. Only internal structure changed (bug fixes, clarifications, performance). No dependency is violated.
- MINOR: the interaction surface is extended. New relations are added, but no existing relation is removed or changed. Existing dependencies are preserved; new dependencies become possible.
- MAJOR: the interaction surface has changed in ways that may violate existing dependencies. Some commitments from the previous major version are withdrawn.
This is a monotonicity classification:
- PATCH changes are identity on the interaction surface
- MINOR changes are monotone extensions (the surface only grows)
- MAJOR changes are non-monotone (the surface may shrink or restructure)
2. Modality and trace
2.1 Stability as modality (j)
The stability field on an artifact declares its modal status:
- draft: the artifact is outside the stable fragment. Its interaction surface may change without notice. Depending on a draft is depending on something unstable.
- candidate: the artifact is proposed for the stable fragment. Its interaction surface is believed complete but not yet committed. Review may change it.
- stable: the artifact is in the stable fragment. Its interaction surface is committed. Changes require versioning (MINOR or MAJOR increment).
- deprecated: the artifact is still in the stable fragment but marked for eventual removal. It will not receive new features. A superseding artifact exists or is planned.
The transition draft → candidate → stable is the application of
the modal closure operator j: the artifact moves from contingent
to necessary. Once stable, the commitment persists — it can be
superseded but not retracted.
The transition stable → deprecated is not removal from the stable
fragment. Deprecated artifacts remain committed; they are marked as
no longer the preferred path. Actual removal (the artifact no longer
exists) requires a MAJOR version increment of whatever depends on
it.
2.2 Trace as changelog
The trace operator G applied to versioning is the changelog: a record of what changed between versions and why. Each changelog entry is a trace step — it records which elements of the interaction surface were added, changed, or removed, and the derivation (the reasoning) behind the change.
A changelog is intensional: it records the path through version space, not just the destination. Two artifacts at the same version number with different changelogs have different provenance — they arrived at the same interaction surface through different histories.
Changelog categories (per Keep a Changelog convention):
- Added: monotone extension of the interaction surface (MINOR)
- Changed: modification of existing surface elements (may be MINOR if backward-compatible, MAJOR if not)
- Fixed: PATCH-level correction (interaction surface unchanged)
- Removed: non-monotone reduction of the interaction surface (MAJOR)
- Deprecated: marking surface elements for future removal (MINOR — the surface is not yet reduced)
2.3 Provenance
A version’s provenance is the chain of derivations from prior versions. In the semiotic-git model, this is the ancestry cone. In practice, provenance is recorded as:
- The version number (which encodes the kind of change)
- The changelog (which records what changed and why)
- The dependency graph (which records what depends on this version)
- The commit history (which records the detailed development path)
3. Operators and interactions
3.1 Release as publication
A release is the act of applying j to an artifact: declaring that its current state is stable and publishing it under a version number. In semiotic-github terms, a release is a projection of the stable fragment plus attached artifacts.
A release creates a new element in H: the ancestry cone of the new tag. This element includes all prior stable versions (they are ancestors). The stable fragment grows monotonically — releases accrete, they do not replace.
3.2 Deprecation as supersession
Deprecation marks an element of the interaction surface for future removal. It is a signal that the closure pressure has shifted — a new approach better satisfies the system’s closure conditions, and the old approach should be phased out.
Deprecation is a MINOR change (the surface is not yet reduced). Actual removal is a MAJOR change. The gap between deprecation and removal is the deprecation window — the period during which dependents can migrate.
3.3 Breaking change as surface violation
A breaking change is a change that violates commitments the stable fragment made. It is a change to the interaction surface that existing dependencies did not anticipate. Breaking changes require a MAJOR version increment because they are non-monotone: something that was true of the interaction surface is no longer true.
The semiotic interpretation makes “breaking” precise: a change is
breaking if and only if it removes or alters an element of the
interaction surface that another artifact’s requires: or
extends: relation points to.
3.4 Backward compatibility as monotonicity
Backward compatibility is the property that a newer version’s interaction surface is a monotone extension of the older version’s. Every commitment the old version made is preserved; new commitments may be added. This is exactly MINOR-level change.
Backward compatibility is the default expectation within a MAJOR version series. MINOR and PATCH changes MUST be backward-compatible. Only MAJOR changes may break compatibility.
4. Application to this repository
4.1 Specifications
Specifications follow
semiotic-specification: they
declare spec-id, version, and stability in frontmatter. The
versioning semantics defined in this document apply to the normative
statements in specs — those are the interaction surface.
4.2 Plans and decisions
Plans have a lifecycle (draft → proposed → accepted → active →
completed) but not version numbers. Plans are not versioned because
they are not depended on — nothing has a requires: plan-0017
relation. If a plan’s approach changes, the change is recorded in
the log section, not as a version increment.
Decision records are append-only and carry status (accepted, superseded, deprecated). Supersession creates a new record that references the old one — this is the decision-level equivalent of a MAJOR version increment.
4.3 Content
Most vault content (terms, concepts, texts) does not carry explicit
version numbers. Content is implicitly versioned through git
history. The date-updated frontmatter field marks substantive
edits. Content does not need explicit versioning unless other
artifacts depend on its specific interaction surface — in which
case it should be promoted to a specification.
4.4 Software artifacts
Scripts, MCP servers, and other software artifacts in this repository SHOULD use semantic versioning when they have external dependents. Internal tooling that only the repository itself uses MAY rely on git-level versioning (annotated tags on the repository itself).
Glossary
- Breaking change: a change that removes or alters an element of the interaction surface that existing dependencies point to. Requires a MAJOR version increment.
- Backward compatibility: the property that a newer version’s interaction surface is a monotone extension of the older version’s.
- Changelog: the trace of a version history — a record of what changed between versions and why.
- Deprecation: marking an element of the interaction surface for future removal. A MINOR change (the surface is not yet reduced).
- Deprecation window: the period between deprecation and removal, during which dependents can migrate.
- Interaction surface (of a version): the set of typed relations and behaviors that other artifacts depend on.
- Release: the act of applying the modal closure operator j to an artifact, declaring it stable and publishing it under a version number.
- Stability: the modal status of an artifact (draft, candidate, stable, deprecated).
- Version: a named element of the semantic carrier — an ancestry-closed subset of the artifact’s history that has been declared stable.
Rationale (non-normative)
Semantic versioning is widely used but rarely grounded. The standard (semver.org) specifies rules for when to increment which number but does not explain why those rules are what they are. The rules feel arbitrary until you see the semiotic structure behind them:
PATCH is identity on the interaction surface. MINOR is monotone extension. MAJOR is non-monotone change. These are not arbitrary categories — they are the only three possible relationships between an old interaction surface and a new one: unchanged, extended, or restructured.
Similarly, the stability lifecycle (draft → candidate → stable → deprecated) is not a workflow convention — it is the application of the modal closure operator. Moving from draft to stable IS applying j: the artifact moves from contingent to necessary. Once necessary, it cannot be retracted, only superseded.
Grounding versioning in semiotic structure makes it applicable beyond software. Specifications, formal definitions, policies, and governance structures all version in the same way — they all have interaction surfaces, stability transitions, and provenance.
Relationship to other specs
- Follows: semiotic-specification (this is a convention specification).
- Requires: semiotic-markdown (versioned artifacts are markdown files with typed frontmatter).
- Extends: semiotic-git’s model of annotated tags as the modality operator j (this spec generalizes that model beyond git).
- Extends: semiotic-github’s model of releases as stable fragment projections.
- Interprets: Semantic Versioning 2.0.0 (Preston-Werner, 2013) — semver’s rules are operational consequences of the model here.