Persona-based user-journey gap analysis

Requested 2026-07-25, written 2026-07-26 (docs/TASKS.md T-114). Distinct from the two gap analyses that already exist: docs/release-readiness.md is organized by construction (is this mode of operation current/safe), and docs/dstu-crypto-project.md’s “Concrete API shape” table is organized by libsodium function name. This document is organized by persona and the sequence of states they walk through — discover, integrate, configure, verify, ship — because an existing, correctly-built feature can still leave a persona stuck if the doc or tooling connecting the steps around it is missing. This document’s value is that framing itself, not a fourth copy of the same feature list — every “have” cell below cites the file that already says so rather than restating its content.

Five personas: the original three from docs/TASKS.md T-114, plus two added 2026-08-03 (docs/TASKS.md T-166) once every planned language binding (Python, Node.js, Ruby, PHP, .NET, Java, Go, C++) and the C ABI crate existed — the original three predate all of Phase 3 and have no persona for “uses uacrypt from another language” or “contributes to a binding.”

Persona 1 — binary user, performance-focused

Picks up uacrypt to encrypt/hash/benchmark files from the CLI. Cares about throughput and getting a runnable binary quickly; does not care about the Rust API or hazmat/crypto_* split.

stateDiagram-v2
    [*] --> Discover
    Discover --> Acquire
    Acquire --> GenerateKey
    GenerateKey --> RunCommand
    RunCommand --> Verify
    Verify --> Ship
    Ship --> [*]

Acquire’s and GenerateKey’s back-edges to Discover (both present in the original 2026-07-25 version of this diagram, labeled “no prebuilt binary found” and “no keygen tool found” respectively) are both removed now - docs/TASKS.md T-18/T-119 and T-115 close each path, see the table below.

Bottom line: this persona’s journey is now unblocked end to end. Both the original blockers (Acquire without a Rust toolchain, GenerateKey even with one) closed the same session they were found in, T-18/T-119 and T-115 respectively - a real example of this document’s stated purpose: gaps neither release-readiness.md’s construction-level view nor dstu-crypto-project.md’s API-mapping table would have framed as “blocking a specific persona,” found and closed by walking the journey directly.

Persona 2 — library user, performance-focused

Depends on dstu-core directly from Cargo.toml. Cares about the crypto_*/hazmat split, ExpandedKey-style cached-schedule paths, and docs/PERFORMANCE.md’s numbers.

stateDiagram-v2
    [*] --> Discover
    Discover --> AddDependency
    AddDependency --> PickLayer
    PickLayer --> ChooseConstruction
    ChooseConstruction --> Configure
    Configure --> Verify
    Verify --> Ship
    Ship --> [*]

AddDependency’s back-edge to Discover (present in the original 2026-07-25 version of this diagram, labeled “not on crates.io, no docs.rs page”) is removed as of T-17’s closure, 2026-08-09 - see the table below.

Bottom line, updated 2026-09-17: persona 2’s journey is now unblocked end to end. The original gap (“Add dependency”/“Ship”, no crates.io/docs.rs presence) was the one open item in this whole document as of when it was written - closed 2026-08-09 when T-17 landed (docs/DECISIONS.md D-114). This paragraph is kept, corrected in place rather than deleted, as the historical record of what this persona’s blocking gap used to be.

Persona 3 — constrained-target (microcontroller) user

Needs the no_std/small-tables minimal-footprint variant for an STM32/ESP32-class target. Cares about flash/RAM budget and build-time feature selection, not raw throughput.

stateDiagram-v2
    [*] --> Discover
    Discover --> PickProfile
    PickProfile --> ConfigureFeatures
    ConfigureFeatures --> CrossCompile
    CrossCompile --> VerifyFlashSize
    VerifyFlashSize --> Ship
    Ship --> [*]

CrossCompile’s back-edge to Discover (present in the original 2026-07-25 version of this diagram, labeled “no target ever actually built here”) is removed as of docs/TASKS.md T-116 - real cross-compiles now exist for two target families, see the table below. VerifyFlashSize still has no real linked-artifact measurement behind it (see that row) - not yet a fully closed state.

Bottom line: persona 3’s journey now has real cross-compiled evidence behind the “compiles for microcontroller targets” claim (T-116), closing this document’s sharpest original finding. What remains open is narrower than before: Xtensa specifically (needs espup, not attempted), and a true linked flash-size measurement (needs a firmware binary crate this repo doesn’t have) - both smaller asks than the original “has anyone ever tried this” gap.

Persona 4 — binding user, non-Rust developer

Uses uacrypt/dstu-core from their own language (Python, Node.js, Ruby, PHP, .NET, Java, Go, or C++) without touching Rust directly. Cares about that language’s own idiomatic API and normal package-registry install path, not hazmat/crypto_* internals.

stateDiagram-v2
    [*] --> Discover
    Discover --> PickLanguage
    PickLanguage --> Install
    Install --> RunAPI
    RunAPI --> Verify
    Verify --> Ship
    Ship --> [*]

    Install --> Discover: not on any package registry (5 of 8 bindings still)

Updated 2026-08-3x/09-17: the back-edge above narrowed, not closed - Python/Node.js/Ruby are now on PyPI/npm/RubyGems (see the table below), the remaining five (PHP/.NET/Java/Go/C++) still build-from-source only.

Bottom line, updated 2026-09-17: persona 4’s gap narrowed, didn’t close - three of eight languages (Python/Node.js/Ruby) got the same registry closure persona 2’s crates.io gap got (T-164/D-194), the remaining five (PHP/.NET/Java/Go/C++) are still exactly the gap this section originally described in full, each gated on its own separate registry setup.

Persona 5 — binding contributor

Wants to fix, extend, or add a language binding under bindings/ (or the C ABI crate it’s built on) — distinct from persona 4, who only consumes a binding.

stateDiagram-v2
    [*] --> Discover
    Discover --> ReadProcess
    ReadProcess --> Scaffold
    Scaffold --> Implement
    Implement --> TestAndCrossArch
    TestAndCrossArch --> DocumentAndShip
    DocumentAndShip --> [*]

Bottom line: persona 5’s only real gap — no onboarding entry point in docs/CONTRIBUTING.md — closed in the same session this persona was added, via T-165. A live instance of this document’s own stated methodology: framing the journey surfaced a gap that a construction-level view (the standard steps already existed) wouldn’t have flagged as “blocking a specific persona from ever finding the process.”

Cross-persona findings

• The single highest-value finding when this document was first written: persona 3’s cross-compile gap. It sat directly behind a claim README.md already made in careful, hedged language — the hedge was correct, but the thing it was hedging against verifying had never been attempted. Closed 2026-07-26, see docs/TASKS.md T-116 — real cross-compiles now exist for two target families (thumbv7em/STM32, riscv32imc/ESP32-C3-class), no hardware required to get there.
• uacrypt keygen’s absence (persona 1) was already-tracked at the construction level (randombytes “Done”) but read very differently once framed as “can this specific persona finish their journey” — the answer was no, at the very first concrete step. Closed 2026-07-26, see docs/TASKS.md T-115 — the project owner triaged this candidate into a real task the same day it was found.
• Persona 1’s Acquire gap (no prebuilt binary, T-18) was explicitly gated on an owner request, same as T-17 - and the owner made that request directly (“зроби реліз на гітгабі бінарника і бібліотек”), 2026-07-26. Closed the same day, see docs/TASKS.md T-18/T-119 - real GitHub Release v0.1.0, three platform binaries plus the dstu-core source distribution, verified against the actual downloaded assets.
• Updated 2026-09-17: crates.io/docs.rs absence (persona 2) is closed, not open any more. T-17 landed 2026-08-09 (docs/DECISIONS.md D-114) - dstu-core/uacrypt are both live on crates.io, docs.rs/dstu-core builds. This was the one gap this document tracked as genuinely still open when first written; it no longer is. Paragraph kept as the historical record of what that gap used to be, not deleted.
• The findings above were not proposed as new task numbers when this document was first written, per T-114’s own scope (“this task’s value is the persona/journey framing itself”) — they were recorded as candidates for the project owner to triage. Four (uacrypt keygen, T-115; the cross-compile check, T-116; prebuilt binaries, T-18/T-119; crates.io publication, T-17) have since been triaged and closed - the only originally-open item from this list left is persona 4’s registry-install gap, and even that one is now three-eighths closed (see below).
• Personas 4 and 5, added 2026-08-03 (docs/TASKS.md T-166): the original three personas predated every language binding; walking the binding-user and binding-contributor journeys directly surfaced two gaps. Persona 5’s onboarding gap was closed immediately via T-165 (a docs/CONTRIBUTING.md section had never existed for bindings at all). Persona 4’s registry-install gap turned out to be structurally identical to persona 2’s (T-164 mirrors T-17, both owner-gated) - updated 2026-09-17: three of eight languages (Python/Node.js/Ruby) are now closed the same way persona 2’s crates.io gap was (T-164/D-194); PHP/.NET/Java/Go/C++ remain open, each needing its own registry setup. Note: the root README.md’s stale repo tree (missing bindings/ruby/bindings/php/crates/dstu-core-capi) is tracked separately under T-162, deliberately deferred until every binding lands — not a new finding here.
• Methodology note, 2026-07-26 (docs/TASKS.md T-117): this document’s original findings were produced by reading the cross-referenced docs and reasoning about the journey, not by actually executing each persona’s steps. A follow-up pass that did — real gh release list (empty at the time; not anymore, see T-18/T-119 above), a real cargo add dstu-core, a real scratch crate consuming dstu-core via a path dependency, the actual release binary run end to end for persona 1 — re-confirmed every finding above as genuinely true (not assumed), and surfaced one the reading-only pass missed entirely: crates/dstu-core/README.md’s own top-level ## Example did not compile (SecretKey::generate/seal both return Result, the example didn’t handle it) - invisible to cargo test since the README isn’t wired in as a doctest, and invisible to a documentation review since the example reads correctly, it just doesn’t compile. Fixed the same session. The general lesson: for this kind of gap analysis, actually running a persona’s steps finds a different class of bug than reading the docs that describe them, even when the docs are accurate about everything else.