Skip to content

Revamps the README for the landed surface - #31

Merged
johnnyt merged 1 commit into
mainfrom
enc-ajj-readme-revamp
Aug 28, 2026
Merged

Revamps the README for the landed surface#31
johnnyt merged 1 commit into
mainfrom
enc-ajj-readme-revamp

Conversation

@johnnyt

@johnnyt johnnyt commented Aug 28, 2026

Copy link
Copy Markdown
Member

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 use macro, Encryptor.Kdf including extract/2 and salted_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

  • A pre-1.0 stability notice at the top, in the operator's commissioned
    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.
  • A real library README structure: what it is, the security model in
    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.
  • Installation now names the target: the reserved encryptor 0.1.0 on
    Hex 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 the
    authority on the point.
  • A quickstart that runs. Every claim in it was executed against the
    compiled library rather than transcribed from memory - see Notes.
  • What does not exist yet, stated rather than implied: there is no
    Argon2id surface (enc-dtv), and ADR-0006 telemetry is proposed, not
    accepted, 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.
  • The :derivation_salt rotation cost stated plainly: rotating it is a
    full reindex, because every value ever derived under the old salt changes.

No version bump, no mix.exs release fields touched, no ADR status changed.

Notes

Every factual claim was machine-checked against the compiled library, not
against the guides:

  • The quickstart was executed end to end via mix run. The describe/1
    output printed in the README (committed?: true, encrypted_data_keys: [%{key_name: "card/v1", provider_id: "acme_payments"}], the three-pair
    context) is the actual return, and both printed refusals -
    {:missing_required_context_keys, ["column"]} and :decrypt_failed on a
    substituted context - are actual returns too.
  • The derived-subkey example was executed against a vault configured with a
    :derivation_salt, as was the {:missing_config, [:derivation_salt]} path.
  • Every module and function named in the surface-map table was checked with
    function_exported?/3 against the compiled beams. One probe miss was mine,
    not the README's: Encryptor.Error.describe/1 is private, and the README
    makes no claim about it.
  • :telemetry is confirmed absent from the loaded applications, which is what
    makes "proposed, not emitted" a checked statement.
  • The refused key-material use options, the 20 * max_age recycler default,
    the two accepted algorithm suites and the ~> 1.18 Elixir requirement were
    each read off the source rather than the prose.

Noted, not touched (outside this bead's scope, flagged rather than fixed):
CLAUDE.md still 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.GuidesTest already executes; the independent mix run
above 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 under lib/, test/, config/, mix.exs,
mix.lock). A full mix quality was 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

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
@johnnyt
johnnyt merged commit 1c9d591 into main Aug 28, 2026
1 check passed
@johnnyt
johnnyt deleted the enc-ajj-readme-revamp branch August 28, 2026 11:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant