Adds the getting-started guide and rotation runbook - #29
Merged
Conversation
Two guides, both required before a first release, written after the envelope because a getting-started guide for an unimplemented package is a promise rather than a document. The getting-started guide stands up a single-key vault and then a per-tenant one. It states where key material may come from - the init/1 callback, never use options and never a config file - when to configure 0x0478 and when to keep the signing default, and why :max_age is required with no default: it is the answer to how long a crypto-shred takes to take effect on a running node. It requires two root secrets from day one, holding the same bytes. A deployment that provisions both at install never performs P1 step 0, which is the most destructive-looking no-op in the design: generating a fresh reference root rather than copying moves every tenant reference in the deployment. The rotation runbook is the four procedures with their preconditions, steps, independent verification and rollback, both blast radius tables, and the two-vocabulary mapping across the packages. Every step says whether it is a function this package ships or an action on a store it does not own, and cache drainage is a step inside each destructive procedure rather than a follow-up. It carries the honest wording on shredding: a shred destroys plaintext, not attribution. Every code block in both guides is executed by Encryptor.GuidesTest against modules transcribed from the printed text, so a guide that drifts from the landed surface fails the gate. README reports the package as built rather than as a scaffold and gives the installation form as a SHA-pinned git dependency; the reserved 0.1.0 on Hex holds no implementation. Refs: enc-nsi
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.
The two guides the B3 graph puts after the envelope:
guides/getting-started.mdand
guides/rotation-runbook.md. Both are required before a first release, andboth are written against the package as it exists on
mainrather than againstthe records alone.
The six statement-decisions the bead asks the guides to carry
Stated, not re-decided. Each is a claim the accepted records already fix, and
each now has a place a reader meets it:
init/1and never throughuseoptions ora config file. The getting-started guide shows the compile-time refusal.
0x0478, and the required:max_agewith nodefault - framed as the answer to how long a crypto-shred takes to take
effect on a running node, which is why the package will not pick one.
question 5). A deployment that provisions both never performs P1 step 0,
the most destructive-looking no-op in the design: generating a fresh
reference root rather than copying it moves every tenant reference in the
deployment.
verification and rollback, plus both blast radius tables (ADR-0003
decision 10's attacker table, and ADR-0005's per-step table).
package does not own, labelled per step, with cache drainage inside each
destructive procedure rather than as a follow-up.
attribution. The header pseudonym is permanent, and the holder of the
reference subkey can re-identify it by guess-and-confirm forever, in every
retained backup. Deleting the tenant's ciphertext rows is
compliance-mandatory wherever tenant attribution is itself personal data,
and the shred claim must never be stated as full erasure.
The runbook also carries ADR-0005 decision 1's two-vocabulary mapping table,
decision 2's window, decision 3's "rotation adds a name, a shred removes one,
pruning is manual", decision 6's seam, and ADR-0004 decision 10's division of
labour with
encryptor_ecto- the statements the B3 graph lists as carried byD1 rather than implemented by a bead.
Every code block runs
test/guides_test.exsexecutes the guides againstEncryptor.GuideVaults,which transcribes the printed vault modules, the printed store and the printed
provider. 25 tests, one per guide claim, named after the claim. A guide that
drifts from the landed surface fails the gate rather than misleading a reader.
Two deliberate differences from the printed text, recorded in the support
module's moduledoc: the non-secret configuration the guides show in
config/config.exsis passed asuseoptions in the suite, andMyApp.MerchantKeysis anAgentrather than a table (this package defines nostorage).
Documentation currency
README.mdmoves from "designed, not built" to "built, not released", linksboth guides, and gives the installation form as a SHA-pinned git dependency.
The reserved
encryptor 0.1.0on Hex is a name reservation holding noimplementation, and neither the README nor either guide tells a reader to
depend on it.
Encryptor's moduledoc had two stale sentences (contracts "underway", entry points "not built yet"); both are corrected and the guides are
named from there.
Nothing is asserted from ADR-0006, which is at Proposed: the guides mention no
telemetry at all.
Gate
Full
mix quality, foreground, under the fleet gate lock:mix docsbuilds both guides as ExDoc extras under aGuidesgroup with nowarnings referencing them.
Sabotage: 25 mutations, one at a time,
mix compile --forcebetween each,every one observed red for the test that cites it and reverted. The kit's
scan reports no missing and no unverifiable notes. One mutation was rejected
and replaced: removing
Envelope.require_binding/4is not red for thecopied-wrapping test, because the vault-side comparison catches it too. The
note on that test records the double defence, and the mutation that does go
red drops the tenant-ref pair from
Envelope.binding/3./wurk:verify --unattended: backlog empty (this bead has no plan document).Own-claim machine checks run instead, all clean - no non-ASCII in any new or
changed file, no
{:encryptor, "~> 0.1"}dependency form anywhere, notelemetry claim, and every error reason and function the guides cite checked
against
Encryptor.Error.reason/0andlib/.Terminology firewall: four scans clean over the worktree, the outbound diff,
the commit message, and the example-domain drift terms, with a positive control
confirming the pipeline can hit (20 in the guide, 101 in the diff). The two
worked domains are the canonical ones: card processing throughout, and the
signup wizard for the payload-with-no-table context example.
Flagged for the reviewer
README.mdandEncryptor's moduledoc were edited outside a strictreading of "two guides". Both contradicted the landed package and both are
the first thing a reader of the guides arrives from; a getting-started guide
that disagrees with the README it is linked from is worse than neither.
CLAUDE.mdstill says "Nothing is implemented yet" and still describesthe package as a scaffold. Left alone deliberately - it is agent instruction
rather than user documentation, and correcting it is not this bead's. Worth
its own bead.
.quality.exsandcoveralls.jsonstill carry the moduledoc-only scaffolddeviation (
treat_no_relevant_lines_as_covered), whose own comment says todrop it once the package has real code. Not touched here; also worth a bead.
Refs: enc-nsi