Revamps the README for the landed surface - #31
Merged
Conversation
Adds a pre-1.0 stability notice at the top: APIs, storage formats and derivation constants may change between releases without a deprecation cycle until 1.0.0, so pin an exact version and read the changelog. Replaces the built-not-released framing with a real library README: what the package is, the security model in brief, an installation section naming 0.2.0 as the first real release, a quickstart executed against the compiled library, a surface map covering the vault entry points, the provider behaviour and its conformance suite, the envelope, the KDF, the error vocabulary and the cache recycler, plus the derived-subkey surface and its salt-rotation cost. States what does not exist yet rather than leaving it implied: no Argon2id surface, and telemetry proposed but not emitted. Refs: enc-ajj
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The README was written when the package was a scaffold with accepted records
and no implementation. Campaign 009 landed the core - the vault surface and
its
usemacro,Encryptor.Kdfincludingextract/2andsalted_subkey/5,the derived-subkey vault surface, the envelope, the provider behaviour with
its conformance suite, the closed error vocabulary, the bounded cache and its
recycler, rekey - so the README's framing ("built, not released", an ADR table
as the main body) no longer describes what a reader gets.
It also gave a reader no signal about stability. The package is weeks from
1.0.0 and its storage formats and derivation constants are still moving, and
nothing in the README said so.
What
wording: APIs, storage formats and derivation constants may change between
releases without a deprecation cycle until 1.0.0; pin an exact version and
review the changelog before upgrading.
brief (the three-level hierarchy plus the six properties the package
enforces rather than documents), installation, a quickstart, a surface map,
derived subkeys, what does not exist yet, documentation pointers, the ADR
table with statuses, the family split, engine notes, contributing.
encryptor 0.1.0onHex holds no implementation, no release has been cut, and the first real
release is 0.2.0 - so a reader knows both what to pin today (a full SHA)
and what to move to later. This matches
CHANGELOG.md, which is theauthority on the point.
compiled library rather than transcribed from memory - see Notes.
Argon2id surface (
enc-dtv), and ADR-0006 telemetry is proposed, notaccepted, with no events emitted. Both were previously invisible to a
reader, and the second is the kind of gap someone builds a dashboard
against before discovering it.
:derivation_saltrotation cost stated plainly: rotating it is afull reindex, because every value ever derived under the old salt changes.
No version bump, no
mix.exsrelease fields touched, no ADR status changed.Notes
Every factual claim was machine-checked against the compiled library, not
against the guides:
mix run. Thedescribe/1output printed in the README (
committed?: true,encrypted_data_keys: [%{key_name: "card/v1", provider_id: "acme_payments"}], the three-paircontext) is the actual return, and both printed refusals -
{:missing_required_context_keys, ["column"]}and:decrypt_failedon asubstituted context - are actual returns too.
:derivation_salt, as was the{:missing_config, [:derivation_salt]}path.function_exported?/3against the compiled beams. One probe miss was mine,not the README's:
Encryptor.Error.describe/1is private, and the READMEmakes no claim about it.
:telemetryis confirmed absent from the loaded applications, which is whatmakes "proposed, not emitted" a checked statement.
useoptions, the20 * max_agerecycler default,the two accepted algorithm suites and the
~> 1.18Elixir requirement wereeach read off the source rather than the prose.
Noted, not touched (outside this bead's scope, flagged rather than fixed):
CLAUDE.mdstill carries scaffold-era text - "Nothing is implemented yet.The repository holds the scaffold only, so almost every convention below is
inherited rather than demonstrated" - and its "Read before writing any code
here" section still points at the ADR beads rather than the accepted
records. Same residue enc-nsi's landing flagged. It needs its own bead.
The README quickstart is transcribed from getting-started Part 1, whose code
blocks
Encryptor.GuidesTestalready executes; the independentmix runabove is the direct evidence for the README's own copy.
Gate: docs-only, so the kit reports no gate applicable
(
carve_out_reason: no changes underlib/,test/,config/,mix.exs,mix.lock). A fullmix qualitywas run anyway as evidence and was green:format, compile, deps, credo, dialyzer clean, 419/419 tests, 98.2% coverage.
Doctor, gettext and sobelow are the project's standing not-applicable skips.
Closes enc-ajj