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 --> Discover: not on crates.io, no docs.rs page

Bottom line: every step from “Pick layer” onward is well documented and cited; the entire persona-2 gap is concentrated at “Add dependency” (no crates.io/docs.rs presence) and its downstream consequence for “Ship.” This is the same T-17 gate the roadmap already tracks — this persona view just shows it’s not only a publishing-hygiene item, it’s a hard stop partway through a concrete adoption path.

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

Bottom line: persona 4’s gap is concentrated entirely at “Install”/“Ship,” structurally identical to persona 2’s crates.io gap — both are the same class of problem (real, working code with no registry presence yet), both explicitly gated on a separate owner request (T-164 mirrors T-17), not a new finding requiring its own task.

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.
• Crates.io/docs.rs absence (persona 2) is the one gap in this whole document still open - tracked at the construction level as T-17, explicitly re-confirmed as still gated on a separate owner request when T-18/T-119 was scoped (GitHub Release ≠ crates.io publish, confirmed via AskUserQuestion rather than assumed to mean both).
• 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. Three (uacrypt keygen, T-115; the cross-compile check, T-116; prebuilt binaries, T-18/T-119) have since been triaged and closed; crates.io publication (T-17) remains open, still explicitly gated on an owner request.
• 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, both closed the same session — persona 4’s registry-install gap turned out to be structurally identical to persona 2’s (T-164 mirrors T-17, both owner-gated), and persona 5’s onboarding gap was closed immediately via T-165 (a docs/CONTRIBUTING.md section had never existed for bindings at all). 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.