# Version Plan
This plan describes the intended post-`0.6.0` direction for `hashavatar`.
Each version has a concrete finish line so the project can stop, review, and
release without letting exploratory work blur into the release criteria.
## Guiding Principles
- Keep the default path conservative and deterministic.
- Prefer explicit opt-in features over broad default dependency growth.
- Do not add custom unsafe SIMD code to this crate.
- Use vetted dependencies for optimized algorithms when they have a clear
security and maintenance story.
- Prefer latest compatible stable crate releases; check crates.io, docs.rs,
upstream repositories, and RustSec advisories before adding or upgrading
dependencies.
- Keep web/API concerns in `hashavatar-api`; keep this crate focused on
reusable avatar generation.
- Treat self-testing as part of implementation, not a follow-up task.
- Keep GitHub CodeQL on the repository default setup unless there is a
documented reason to move to advanced setup.
- Treat visual-output changes as compatibility events and document them in
release notes.
- Derive enum-based choices from a single variant list instead of hard-coded
modulo counts.
## 0.7.0: Pluggable Identity Hashing
Status: implemented in `0.7.0`.
Goal: make identity hashing explicit and extensible while keeping SHA-512 as
the stable default.
### Scope
- Add an `AvatarHashAlgorithm` enum.
- Add an `AvatarIdentityOptions` or equivalent options type.
- Keep `Sha512` as the default hash algorithm.
- Add optional `BLAKE3` support behind an explicit Cargo feature.
- Add optional `XXH3-128` support behind an explicit Cargo feature.
- Include the selected algorithm in the length-prefixed hash domain input.
- Preserve existing default SHA-512 output unless the caller opts into another
algorithm.
- Document that `XXH3-128` is non-cryptographic and intended only for
non-adversarial identity distribution.
### Candidate API Shape
```rust
pub enum AvatarHashAlgorithm {
Sha512,
Blake3,
Xxh3_128,
}
pub struct AvatarIdentityOptions {
pub namespace: AvatarNamespace<'static>,
pub algorithm: AvatarHashAlgorithm,
}
```
The exact lifetime/API shape can change during implementation. The important
contract is that algorithm choice is explicit, typed, and included in the
deterministic identity input.
### Dependency Policy
- `sha2` remains the default dependency.
- `blake3` is optional.
- `xxhash-rust` or another reviewed XXH3 provider is optional.
- Optional hash dependencies must pass `cargo deny`, `cargo audit`, license
checks, and package-size review.
- Do not enable optional hash dependencies by default unless there is a clear
project decision and release-note justification.
### SIMD Policy
- SIMD may be used only through admitted dependency implementations such as
`blake3`.
- No custom AVX2, AVX-512, NEON, or wasm SIMD implementation is added to
`hashavatar`.
- README/docs must explain that hardware acceleration, when available, comes
from the selected hash dependency and platform support.
### Finish Line
`0.7.0` is done when:
- Default SHA-512 fingerprints are unchanged from `0.6.0`.
- BLAKE3 and XXH3 identity modes have dedicated tests.
- Oversized identity and namespace inputs are rejected for every algorithm.
- Algorithm separation tests prove the same identity does not collide across
algorithm domains.
- README, release notes, dependency docs, and security controls document the
default and optional hash algorithms.
- `scripts/stable_release_gate.sh check` passes.
- crates.io publish dry run passes.
## 0.8.0: Core Boundary Preparation
Goal: separate deterministic avatar decisions from encoding/integration
concerns so a future `no_std + alloc` core is realistic.
### Scope
- Identify the minimum deterministic core:
- validated avatar specs
- identity and namespace validation
- hash algorithm selection
- avatar genome derivation
- geometry/layout primitives
- color values
- Reduce direct coupling between that core and `image::RgbaImage`.
- Introduce an internal drawing target trait if it makes the core boundary
cleaner.
- Normalize public enum variant lists and byte-to-variant helpers before new
visual layers are added.
- Keep the public crate behavior stable unless a breaking change is explicitly
worth making before `1.0`.
- Keep raster encoding in the main crate, not in the future core.
### Non-Goals
- Do not promise `no_std` in `0.8.0`.
- Do not split the crate unless the internal boundary is already clean enough
to maintain.
- Do not add custom SIMD code.
### Finish Line
`0.8.0` is done when:
- The code has a clear internal boundary between deterministic avatar planning
and output encoding.
- Raster and SVG outputs still pass golden fingerprint and safety tests.
- The dependency graph is no larger than `0.7.0` unless explicitly justified.
- Public enum derivation does not rely on duplicated magic counts such as
`value % 23`; it uses `ALL.len()` or an equivalent single source of truth.
- Tests fail if public enum variant lists drift from parser/display behavior.
- The README explains that `no_std` is planned but not yet a public contract.
- `docs/DEPENDENCIES.md` explains which dependencies block or belong outside
a future core crate.
- `scripts/stable_release_gate.sh check` passes.
- crates.io publish dry run passes.
## 0.9.0: `hashavatar-core` Experiment
Goal: publish or prepare a constrained core API that can work in
`no_std + alloc` environments without image encoders.
### Scope
- Create one of:
- a separate `hashavatar-core` crate, or
- a feature-isolated internal module that can later become a crate.
- Target `no_std + alloc` for the core boundary.
- Keep SVG string generation only if `alloc` is available and the API remains
clean.
- Keep raster encoding, `image`, and format-specific encoders in the main
`hashavatar` crate.
- Provide structured output or drawing commands if that is cleaner than
exposing image buffers from the core.
### Likely Dependency Changes
- Replace or isolate `palette` usage if it blocks `no_std`.
- Replace `StdRng` usage with a deterministic, small, reviewable internal
generator or an admitted `no_std` RNG dependency.
- Keep cryptographic hashing behind dependency features that support the core
target.
### Finish Line
`0.9.0` is done when:
- The core boundary builds without `std`.
- The main crate still provides ergonomic raster/SVG APIs on top of the core.
- Golden fingerprints prove the refactor did not accidentally change default
output, or release notes clearly document intentional changes.
- `no_std + alloc` support is documented precisely, including what is not
available.
- Fuzz harnesses cover the core identity and rendering-plan boundary.
- `scripts/stable_release_gate.sh check` passes.
- crates.io publish dry run passes for every crate intended to be published.
## 0.10.0: Visual Layer Model
Goal: expand avatar variety with explicit, deterministic visual layers before
the public API is frozen.
### Scope
- Add new option enums for visual layers:
- `AvatarAccessory`
- `AvatarColor`
- `AvatarExpression`
- `AvatarShape`
- Add a higher-level options type, for example `AvatarStyleOptions`, that can
carry kind, background, accessory, color palette, expression, and frame
shape together.
- Keep existing `AvatarOptions` working during the transition if practical.
- Define a deterministic derivation path for each layer from identity bytes
when the caller chooses an automatic/default mode.
- Reserve distinct identity digest offsets for top-level automatic choices so
kind, background, accessory, palette, expression, and frame shape do not all
depend on the same byte.
- Make every new enum parseable and displayable like the existing public
enums.
- Derive automatic layer choices from each enum's variant list rather than
hard-coded modulo counts.
- Document how layer choices affect the deterministic output tuple.
### Candidate API Shape
```rust
pub enum AvatarAccessory {
None,
Glasses,
Hat,
Headphones,
Crown,
Bowtie,
Eyepatch,
Scarf,
Halo,
Horns,
}
pub enum AvatarColor {
Default,
NeonMint,
PastelPink,
Crimson,
Gold,
DeepSeaBlue,
}
pub enum AvatarExpression {
Default,
Happy,
Grumpy,
Surprised,
Sleepy,
Winking,
Cool,
Crying,
}
pub enum AvatarShape {
Square,
Circle,
Squircle,
Hexagon,
Octagon,
}
```
The exact enum names can change during design review. The important contract is
that visual layers are typed, deterministic, documented, and covered by golden
tests.
### Compatibility Policy
- Existing callers should either keep the old default visual behavior or get a
clearly documented migration path.
- If default output changes, release notes must state that `0.10.0` is a
visual-output compatibility release.
- The `style_version` guidance in `VERSIONING.md` must be updated so services
can roll out layered avatars deliberately.
### Enum Derivation Policy
- Prefer small hand-maintained `ALL` lists or `all()` accessors as the single
source of truth for public enum variants.
- Avoid `strum` or other enum-reflection dependencies unless the boilerplate
becomes large enough to justify the additional dependency and audit surface.
- Any byte-to-variant helper should index through the variant list, for
example `Self::ALL[(value as usize) % Self::ALL.len()]`, so adding a variant
cannot silently leave it unreachable.
### Automatic Derivation Schedule
Automatic layer choices must use an explicit schedule of identity digest bytes
or domain-separated sub-derivations. The simple baseline is one distinct digest
byte per top-level choice:
```rust
let kind = AvatarKind::from_byte(identity.byte(0));
let background = AvatarBackground::from_byte(identity.byte(1));
let accessory = AvatarAccessory::from_byte(identity.byte(2));
let color = AvatarColor::from_byte(identity.byte(3));
let expression = AvatarExpression::from_byte(identity.byte(4));
let shape = AvatarShape::from_byte(identity.byte(5));
```
The exact offsets can change during implementation, but the schedule must be
documented and covered by tests. Reusing a byte for unrelated top-level traits
is avoided because it creates visible correlation, such as one background being
overrepresented with one accessory.
### Finish Line
`0.10.0` is done when:
- Every visual layer enum has `ALL`, `as_str`, `Display`, and `FromStr`.
- Every automatic public enum choice uses the enum's variant list instead of a
duplicated literal count.
- Top-level automatic traits use distinct identity digest offsets or explicit
domain-separated derivations.
- Tests prove changing the digest byte reserved for one top-level trait does
not alter the other automatic trait selections.
- Automatic layer derivation is deterministic and covered by tests.
- Manual layer selection is covered by tests.
- Raster and SVG renderers support all selected baseline layers.
- Golden fingerprints cover representative combinations of kind, background,
accessory, color palette, expression, and frame shape.
- README includes examples for automatic and manual visual layers.
- Release notes clearly state whether default visuals changed.
- `scripts/stable_release_gate.sh check` passes.
- crates.io publish dry run passes.
## 0.11.0: Visual Layer Coverage And Polish
Goal: make the visual layer system feel complete across avatar families rather
than merely supported by the API.
### Scope
- Expand accessory rendering across all avatar families where the accessory
makes visual sense.
- Define fallback behavior for combinations that do not make sense, such as
accessories that conflict with a particular family shape.
- Refine color palettes so they are accessible and readable on all supported
backgrounds.
- Refine expression support so the common expressions are visually distinct
across face-like families.
- Ensure frame shapes clip or mask raster and SVG output consistently.
- Add documentation for recommended layer combinations and public endpoint
query mapping.
### Non-Goals
- Do not add user-supplied SVG fragments, arbitrary colors, arbitrary paths,
or external assets.
- Do not make the crate responsible for HTTP query parsing.
- Do not add an unbounded combinatorial golden test matrix; use representative
coverage plus targeted unit tests.
### Finish Line
`0.11.0` is done when:
- Every avatar family has reviewed behavior for every visual layer.
- Unsupported or awkward layer/family combinations have deterministic,
documented fallback behavior.
- Raster and SVG outputs are visually consistent for frame shapes.
- Tests cover fallback behavior and representative cross-family combinations.
- README and docs explain the full layer model.
- `hashavatar-api` has enough documented guidance to expose the new layers
safely when that project is ready.
- `scripts/stable_release_gate.sh check` passes.
- crates.io publish dry run passes.
## 0.12.0: Variant Expansion
Goal: broaden the built-in avatar and background catalog once the visual layer
model is in place and tested.
### Scope
- Add new `AvatarKind` families where they can be rendered with the same
deterministic, asset-free approach as the existing variants.
- Candidate animal variants:
- `Bear`
- `Monkey`
- `Penguin`
- `Dinosaur`
- `Unicorn`
- `Bat`
- `Turtle`
- Candidate fantasy and sci-fi variants:
- `Dragon`
- `Ninja`
- `Vampire`
- `Cyborg`
- `Astronaut`
- Candidate object variants:
- `Diamond`
- `Gemstone`
- `CoffeeCup`
- `Sword`
- `Shield`
- `Crown`
- Add new `AvatarBackground` modes where they do not require external assets
or unbounded procedural work.
- Candidate pattern backgrounds:
- `PolkaDot`
- `Striped`
- `Checkerboard`
- `Grid`
- `Wavy`
- Candidate gradient backgrounds:
- `Sunrise`
- `Synthwave`
- `Ocean`
- Candidate environment backgrounds:
- `Starry`
- `Pixel`
- `Cloudy`
### Admission Policy
- Each new variant must be visually distinct at small sizes such as 64x64 and
128x128.
- Each new variant must work in raster and SVG output.
- New backgrounds must be bounded, deterministic, and safe for untrusted
identities.
- Pattern and environment backgrounds must not make foreground avatars hard to
read; use contrast tests or reviewed golden outputs where practical.
- Variant expansion must update enum `ALL` lists, parser/display tests,
README examples, and release notes together.
- Adding variants may change automatic distribution only in a documented
visual-output compatibility release. Services that need stable old output
should pin the older `style_version` until they intentionally migrate.
### Finish Line
`0.12.0` is done when:
- The accepted `AvatarKind` and `AvatarBackground` variants are implemented in
both raster and SVG paths.
- Every new public variant has `as_str`, `Display`, `FromStr`, and `ALL`
coverage.
- Automatic selection uses the enum variant lists, not duplicated literal
counts.
- Golden fingerprints cover representative new avatar families and
backgrounds.
- Small-size visual review confirms each accepted variant is recognizable.
- README and docs describe the expanded catalog without promising variants
that were rejected or deferred.
- Release notes clearly state any deterministic output impact.
- `scripts/stable_release_gate.sh check` passes.
- crates.io publish dry run passes.
## 1.0.0: Stability Contract
Goal: freeze a professional, security-oriented public API and rendering
contract.
### Scope
- Decide whether `hashavatar-core` is public and versioned independently.
- Freeze default hash algorithm and default visual style version.
- Freeze the visual layer option model.
- Freeze the baseline avatar kind and background catalog intended for `1.0`.
- Freeze error types and constructor behavior.
- Define a stable policy for when visual output may change.
- Define semver rules for adding avatar families, visual layers, hash
algorithms, and output formats.
### Finish Line
`1.0.0` is done when:
- The public API has no known avoidable breaking changes left.
- Security controls, dependency policy, panic policy, and release process are
complete and current.
- README and docs.rs examples compile and reflect the final API.
- Release notes clearly state the stability contract.
- `scripts/stable_release_gate.sh release` passes.
- crates.io publish dry run passes.
## Deferred Until Evidence Exists
These are intentionally not committed to a specific version:
- Custom SIMD inside `hashavatar`.
- Async APIs in this crate.
- HTTP server or demo code in this crate.
- AVIF/JPEG XL output.
- Enabling BLAKE3 or XXH3 by default.
- Raising identity length limits.
Each item needs concrete use cases, dependency review, tests, and release-note
justification before admission.