Prepare hashavatar 1.0.0 candidate

eldryoth · eldryoth · commit b87e74c7b9af · 2026-05-18T14:29:32.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.0.0
+
+- Bumped the crate to `1.0.0`.
+- Declared the first stable public API and rendering contract for
+  `hashavatar`.
+- Added `docs/STABILITY.md` covering Cargo semver expectations, visual output
+  stability, automatic-style distribution, security/resource contracts, and
+  known residual risks.
+- Updated README guidance for the stable contract and controlled visual
+  rollouts through namespace `style_version` values.
+- Added `docs/STABILITY.md` to release metadata/package validation so future
+  releases keep the stability policy in the published crate.
+- Added 1.0 release notes.
+- No avatar families, backgrounds, visual layers, hash modes, output formats,
+  or runtime dependencies were added in this release.
+
 ## 0.13.0
 
 - Bumped the crate to `0.13.0`.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,9 +1,9 @@
 [package]
 name = "hashavatar"
-version = "0.13.0"
+version = "1.0.0"
 edition = "2024"
 rust-version = "1.95"
-description = "Deterministic procedural avatars in Rust with configurable identity hashing, patterned backgrounds, WebP, optional PNG/JPEG/GIF, and SVG export"
+description = "Stable deterministic procedural avatars in Rust with configurable identity hashing, WebP, optional PNG/JPEG/GIF, and SVG export"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/valkyoth/hashavatar"
 homepage = "https://github.com/valkyoth/hashavatar"
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ The crate starts conservative: validated avatar dimensions, bounded identity inp
 
 ## Current Status
 
-The current crate version is `0.13.0`.
+The current crate version is `1.0.0`.
 
 Implemented now:
 
@@ -64,40 +64,40 @@ Planned or intentionally external:
 | SVG posture | Generated numeric markup only; caller input is not inserted into SVG fragments |
 | Release evidence | fmt, clippy, tests, docs, deny, audit, fuzz harness compile, package check, SBOM, reproducibility |
 
-Security-control details live in [docs/SECURITY_CONTROLS.md](docs/SECURITY_CONTROLS.md). Dependency policy lives in [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md). Panic policy lives in [docs/PANIC_POLICY.md](docs/PANIC_POLICY.md).
+Security-control details live in [docs/SECURITY_CONTROLS.md](docs/SECURITY_CONTROLS.md). Dependency policy lives in [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md). Panic policy lives in [docs/PANIC_POLICY.md](docs/PANIC_POLICY.md). Stable API and rendering policy lives in [docs/STABILITY.md](docs/STABILITY.md).
 
-Future version planning for variant expansion and 1.0 stabilization lives in
-[docs/VERSION_PLAN.md](docs/VERSION_PLAN.md). `hashavatar` remains a single
-image-generation crate; low-level core planning is kept internal unless a
-future release has a concrete image-generation reason to split it.
+Future version planning lives in [docs/VERSION_PLAN.md](docs/VERSION_PLAN.md).
+`hashavatar` remains a single image-generation crate; low-level core planning
+is kept internal unless a future release has a concrete image-generation reason
+to split it.
 
 ## Install
 
 ```toml
 [dependencies]
-hashavatar = "0.13.0"
+hashavatar = "1.0.0"
 ```
 
 Optional identity hash modes and extra raster encoders are disabled by default.
 Hash modes are mutually exclusive, so enable at most one of `blake3` or `xxh3`:
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.13.0", features = ["blake3"] }
+hashavatar = { version = "1.0.0", features = ["blake3"] }
 ```
 
 Enable additional raster formats explicitly:
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.13.0", features = ["png", "jpeg", "gif"] }
+hashavatar = { version = "1.0.0", features = ["png", "jpeg", "gif"] }
 ```
 
 Or enable every optional raster encoder at once:
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.13.0", features = ["all-formats"] }
+hashavatar = { version = "1.0.0", features = ["all-formats"] }
 ```
 
 Combine these as needed, for example `features = ["blake3", "png"]`.
@@ -115,6 +115,20 @@ The crate is dual-licensed:
 license = "MIT OR Apache-2.0"
 ```
 
+## Stable Contract
+
+`1.0.0` freezes the crate's public API shape and documented rendering contract.
+Patch releases should not intentionally change output for the same explicit
+rendering tuple except for correctness or security fixes. Minor releases may
+add opt-in features, output formats, avatar families, backgrounds, or visual
+layer variants when they are documented and tested. Automatic style rendering
+can change distribution when public enum `ALL` lists grow, so services that
+need precise visual rollout control should use namespace `style_version`
+values deliberately.
+
+See [docs/STABILITY.md](docs/STABILITY.md) for the full semver and rendering
+policy.
+
 ## Limits
 
 | Limit | Value |
@@ -381,7 +395,7 @@ your namespace style version when intentionally migrating output.
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.13.0", features = ["blake3"] }
+hashavatar = { version = "1.0.0", features = ["blake3"] }
 ```
 
 ```rust
@@ -409,7 +423,7 @@ assert!(svg.contains("alien avatar"));
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.13.0", features = ["xxh3"] }
+hashavatar = { version = "1.0.0", features = ["xxh3"] }
 ```
 
 ```rust
@@ -614,32 +628,39 @@ AVIF and JPEG XL are not exposed because they add dependency or encoder maturity
 
 ## Determinism
 
-The output is deterministic for the tuple:
+For a concrete crate release, the output is deterministic for the tuple:
 
 ```text
 crate identity hash mode + namespace tenant + namespace style version + identity bytes + avatar kind + background + dimensions + seed
 ```
 
-This makes the crate suitable for stable CDN-backed avatar URLs and golden regression tests. Namespace hashing uses length-prefixed components, so embedded separator bytes cannot create tenant/style-version ambiguity. The default SHA-512 path keeps the pre-0.7 identity preimage stable; optional crate-wide hash modes are domain-separated.
+Within the `1.x` series, explicit output for that tuple should remain stable
+except for documented correctness or security fixes. This makes the crate
+suitable for stable CDN-backed avatar URLs and golden regression tests.
+Namespace hashing uses length-prefixed components, so embedded separator bytes
+cannot create tenant/style-version ambiguity. The default SHA-512 path keeps the
+pre-0.7 identity preimage stable; optional crate-wide hash modes are
+domain-separated.
 
 For style-aware rendering, the deterministic tuple also includes
 `accessory`, `color`, `expression`, and `shape`. Existing `AvatarOptions`
 entry points keep those extra layer choices at `none`, `default`, `default`,
 and `square`, so explicitly selected `AvatarOptions` output remains stable
-unless the selected family renderer changes. `0.13.0` adds new
-`AvatarBackground` values, so automatic style derivation can map some
-identities to different backgrounds than `0.12.0`; services that need the old
-automatic distribution should keep their existing namespace style version until
-they intentionally migrate. Some family/layer combinations are deterministic
-no-ops when the layer has no sensible anchor for that family.
+within a major release unless a documented correctness or security fix requires
+new output. Automatic style rendering derives choices through public `ALL`
+variant lists, so adding variants in a future minor release can change
+automatic distribution. Services that need controlled rollouts should keep
+their existing namespace style version until they intentionally migrate. Some
+family/layer combinations are deterministic no-ops when the layer has no
+sensible anchor for that family.
 
 Frame shapes are applied as masks in raster output and as SVG clip paths in SVG
 output. Non-square shapes therefore trim the background, avatar body, color
 accent, accessory layer, and expression layer consistently before drawing the
 frame border.
 
 The renderer still uses floating-point geometry in family-specific drawing
-paths. Frame-shape raster hit-testing uses integer arithmetic as of `0.13.0`,
+paths. Frame-shape raster hit-testing uses integer arithmetic as of `1.0.0`,
 which reduces one source of platform rounding variance. The project tests
 golden fingerprints on the release platform, but it does not yet claim formal
 bit-identical raster output across every CPU architecture, compiler backend,
diff --git a/docs/STABILITY.md b/docs/STABILITY.md
@@ -0,0 +1,67 @@
+# Stability Policy
+
+`hashavatar` 1.0.0 is the first stable release of the public crate API and the
+documented rendering contract.
+
+## Public API
+
+The crate follows Cargo semver for exported Rust API items:
+
+- Removing or renaming public items requires a major version.
+- Changing public function signatures, error types, constructor behavior, or
+  feature names requires a major version unless the change is strictly
+  additive and source-compatible.
+- Adding new enum variants to public non-exhaustive-style option enums such as
+  `AvatarKind`, `AvatarBackground`, `AvatarAccessory`, `AvatarColor`,
+  `AvatarExpression`, `AvatarShape`, or `AvatarOutputFormat` is allowed in a
+  minor release. Callers should include wildcard arms when matching these
+  enums if they want minor-version compatibility.
+- New optional Cargo features may be added in minor releases when they are
+  disabled by default and documented.
+
+## Rendering Contract
+
+For a concrete crate release and explicitly selected options, the intended
+stable rendering tuple is:
+
+```text
+crate identity hash mode + namespace tenant + namespace style version + identity bytes + avatar kind + background + accessory + color + expression + shape + dimensions + seed
+```
+
+Within a major release, patch releases should not intentionally change output
+for the same tuple except to fix a correctness or security bug. Minor releases
+may add variants or visual capabilities, and release notes must state whether
+automatic style distribution changes.
+
+`AvatarOptions` keeps `accessory = none`, `color = default`,
+`expression = default`, and `shape = square`. `AvatarStyleOptions` includes the
+full visual-layer tuple.
+
+Automatic style rendering derives options from public enum `ALL` lists. Adding
+a variant can change automatic distribution. Services that need controlled
+rollouts should use `AvatarNamespace::new(tenant, style_version)` and only bump
+`style_version` when they are ready for a new visual distribution.
+
+## Security And Resource Contract
+
+- Public dimensions remain bounded by `AvatarSpec`.
+- Identity and namespace input lengths remain bounded before hashing.
+- Public rendering APIs return typed errors for invalid inputs instead of
+  panicking.
+- The crate remains a pure library crate with no HTTP server, CLI, filesystem
+  writing API, async runtime, or network dependency.
+- The default build keeps SHA-512 identity hashing and WebP encoding.
+- Optional hash modes and extra raster encoders remain explicit Cargo feature
+  choices.
+
+## Known Residuals
+
+The renderer still uses floating-point arithmetic in family-specific geometry.
+Frame-shape hit-testing uses integer arithmetic, and golden fingerprints protect
+the release-platform output, but the crate does not claim formal bit-identical
+raster output across every CPU architecture and compiler backend.
+
+Rendering time, SVG size, and encoded raster size are not constant-time with
+respect to the identity digest. High-assurance services should use stable cache
+keys, CDN caching, rate limits, concurrency limits, and fixed-minimum-latency
+wrappers when their threat model requires it.
diff --git a/docs/VERSION_PLAN.md b/docs/VERSION_PLAN.md
@@ -489,6 +489,8 @@ reduce platform-sensitive geometry in frame-shape masking before `1.0`.
 
 ## 1.0.0: Stability Contract
 
+Status: release candidate.
+
 Goal: freeze a professional, security-oriented public API and rendering
 contract.
 
diff --git a/docs/release-notes/RELEASE_NOTES_1.0.0.md b/docs/release-notes/RELEASE_NOTES_1.0.0.md
@@ -0,0 +1,50 @@
+# hashavatar 1.0.0
+
+`1.0.0` is the first stable release of `hashavatar`.
+
+This release does not add new avatar families, backgrounds, visual layers,
+hash modes, output formats, or runtime dependencies. It freezes the public API
+shape and documents the rendering stability contract built through the 0.x
+series.
+
+## Stable Contract
+
+- Public Rust API changes now follow Cargo semver expectations.
+- Explicit rendering output is intended to remain stable within the `1.x`
+  series for the same active identity hash mode, namespace, identity, avatar
+  options, dimensions, and seed, except for documented correctness or security
+  fixes.
+- Automatic style rendering remains deterministic, but future minor releases
+  may change automatic distribution when public enum `ALL` lists gain new
+  variants.
+- Services that need deliberate visual rollouts should use
+  `AvatarNamespace::new(tenant, style_version)` and bump `style_version` only
+  when they are ready for a new visual distribution.
+
+## Documentation
+
+- Added `docs/STABILITY.md` with the stable API, rendering, security/resource,
+  and residual-risk policies.
+- Updated README guidance for the 1.0 stable contract.
+- Added the stability policy to release metadata validation so it remains part
+  of the published crate package.
+
+## Security Posture
+
+- The crate remains a pure library crate with no HTTP server, CLI, filesystem
+  writing API, async runtime, or network dependency.
+- Public dimensions, identity inputs, and namespace components remain bounded.
+- Public render APIs return typed errors for invalid inputs instead of
+  panicking.
+- The default build remains SHA-512 identity hashing plus WebP encoding.
+- Optional BLAKE3, XXH3-128, PNG, JPEG, and GIF support remain explicit Cargo
+  features.
+
+## Compatibility Notes
+
+- No visual variants were added in this release.
+- No intentional golden fingerprint changes were made for `1.0.0`.
+- The known residuals documented in `docs/STABILITY.md` and
+  `docs/SECURITY_CONTROLS.md` still apply: family-specific geometry uses some
+  floating-point arithmetic, rendering is not constant-time, and service-level
+  concurrency/rate limiting belongs in callers such as `hashavatar-api`.
diff --git a/fuzz/Cargo.lock b/fuzz/Cargo.lock
diff --git a/fuzz/Cargo.toml b/fuzz/Cargo.toml
@@ -8,7 +8,7 @@ publish = false
 cargo-fuzz = true
 
 [dependencies]
-hashavatar = { path = "..", version = "0.13.0", features = ["fuzzing"] }
+hashavatar = { path = "..", version = "1.0.0", features = ["fuzzing"] }
 libfuzzer-sys = "0.4"
 roxmltree = "0.21.1"
 
diff --git a/scripts/validate-release-metadata.sh b/scripts/validate-release-metadata.sh
@@ -60,6 +60,7 @@ test -s docs/DEPENDENCIES.md
 test -s docs/PANIC_POLICY.md
 test -s docs/RELEASE.md
 test -s docs/SECURITY_CONTROLS.md
+test -s docs/STABILITY.md
 test -s "docs/release-notes/RELEASE_NOTES_${cargo_version}.md"
 
 for required_script in \
@@ -113,6 +114,7 @@ for required_package_file in \
     "docs/PANIC_POLICY.md" \
     "docs/RELEASE.md" \
     "docs/SECURITY_CONTROLS.md" \
+    "docs/STABILITY.md" \
     "LICENSE-APACHE" \
     "LICENSE-MIT" \
     "README.md" \
