Skip to content

AR-0010: Dependency Trust And Source Provenance

Field Value
Status Incubating
Opened 2026-08-27
Last reviewed 2026-09-03
Scope Core dependency closure / build provenance / release process
Trigger Tosumu relies on third-party cryptographic and storage-support crates but has no accepted policy for exact source identity beyond normal Cargo resolution
Related ADRs ADR-0001, ADR-0002
Related evidence Cargo.toml, Cargo.lock, SECURITY.md, RustCrypto dependency choices, workspace target builds

Architectural Question

What source identity, audit, feature-minimization, update, and release evidence is required for third-party code in Tosumu's authenticated storage and core format closure?

Context

Tosumu deliberately uses established RustCrypto primitives rather than implementing cryptography itself. Cargo manifests and the lockfile provide repeatable package resolution for the workspace, but they do not by themselves define Tosumu's complete source-review, update, publication, or offline-build policy.

A database engine also depends on non-cryptographic parsing, serialization, randomness, synchronization, and platform crates. Build scripts and procedural macros can participate in produced code even when they are not runtime dependencies. Treating every dependency identically would be expensive, while treating the whole closure as ordinary registry plumbing would understate the trust placed in format- and authentication-critical code.

This review evaluates the boundary. It does not assume that Git submodules, vendoring, registry checksums, or any other one mechanism is the correct answer.

Evidence

  • Tests or fuzzing: cryptographic known-answer tests, malformed-input tests, target builds, and fuzzing exercise behavior but do not establish source provenance.
  • Independent consumers: published-library and external-provider workflows make downstream reproducibility relevant.
  • Diagnostics or audits: SECURITY.md names the RustCrypto dependency and the unaudited composition risk; no retained recursive dependency audit exists.
  • Repeated implementation friction: dependency and feature changes affect native, WASM, fuzz, and generated browser artifacts through different closures.
  • Missing evidence: complete runtime/build/proc-macro closure inventory, selected-feature rationale, unsafe/build-script review, advisory process, offline-build requirements, update procedure, and publication consequences.

Ownership And Dependency Analysis

  • Tosumu owns the storage, format, authentication-boundary, and error semantics promised through its public APIs even when third-party code supplies mechanics.
  • Third-party types and errors must not become durable Tosumu vocabulary merely because a crate is convenient to use internally.
  • Core and authentication-critical dependencies carry a higher review burden than dev-only tools or presentation adapters.
  • Cargo, the Rust toolchain, operating systems, hardware, and registries remain trust inputs requiring separate policy; this review must state rather than hide those limits.
  • A dependency update is evidence-changing work even when upstream labels it a patch release, but the proportional update process remains unresolved.

Alternatives Considered

Alternative A: Rely on manifests, Cargo.lock, and registry checksums

  • Benefits: standard Rust workflow and straightforward publication.
  • Costs: limited retained source-review and offline provenance policy.
  • Failure mode: a critical closure or feature change is reviewed only through compilation and tests.

Alternative B: Require pinned repository submodules for the full core closure

  • Benefits: exact source is rooted in the Tosumu repository graph and available for direct inspection.
  • Costs: substantial transitive, procedural-macro, publication, and update complexity.
  • Failure mode: policy cost drives stale dependencies or creates a source path downstream consumers cannot reproduce.

Alternative C: Vendor the selected closure

  • Benefits: offline builds and repository-local source inspection.
  • Costs: copied source requires provenance, update, and generated-artifact discipline.
  • Failure mode: the vendor tree becomes an opaque generated snapshot whose upstream identity is poorly retained.

Alternative D: Use a risk-tiered provenance policy

  • Benefits: focuses stronger evidence on authenticated storage, format, unsafe, build-time, and public-vocabulary dependencies.
  • Costs: requires an explicit classification and machine-checkable inventory.
  • Failure mode: convenient dependencies are classified downward without a defensible trust analysis.

Findings

  • Lockfile pinning is useful resolution evidence but is not a complete source audit or release policy.
  • Mandatory submodules for the entire closure are not justified without a Tosumu-specific migration and publication study.
  • Cryptographic primitives, randomness, byte parsing, unsafe code, build scripts, procedural macros, and public foreign types deserve explicit inventory.
  • Correctness tests and vulnerability scanners support provenance review but do not replace architectural judgment about dependency ownership and exposure.

Disposition

Incubating. Begin with a generated dependency-closure inventory and a focused audit of authentication- and format-critical dependencies. Do not claim that the current build is fully source-audited, vendored, or reproducible offline.

Required Follow-Up

  • [x] Derive aggregate runtime, build, development, and procedural-macro closures from Cargo metadata for the unfiltered workspace and explicit Linux, Windows, macOS, and WASM targets.
  • [ ] Identify dependencies that affect authentication, format parsing, randomness, unsafe boundaries, or public API vocabulary.
  • [ ] Record selected features, licenses, source identity, build scripts, unsafe code, native/WASM implications, and update ownership for the first critical subset.
  • [ ] Compare lockfile-only, vendored, exact-Git, submodule, and risk-tiered policies against publication and offline-build needs.
  • [ ] Decide whether the result becomes an ADR, dependency-audit policy, CI check, or a combination of those artifacts.

The first concrete addition candidate is fs4 with only its synchronous feature for AR-0009's writer gate. Before admission, retain its exact resolved version and checksum, transitive Unix/Windows closure, unsafe/platform boundary, licenses, build scripts, selected features, Rust 1.75 result, native target matrix, and WASM exclusion or behavior. Do not enable async runtime features.

Focused Candidate Inventory: fs4 1.1.0

Concern Retained observation
Source identity crates.io fs4 1.1.0; archive SHA-256 7e72ed92b67c146290f88e9c89d60ca163ea417a446f61ffd7b72df3e7f1dfd5
License MIT OR Apache-2.0, matching Tosumu's license expression
Selected features default-features = false, features = ["sync"]; no async runtime or fs-err adapter
Declared MSRV Rust 1.75.0
Windows normal closure fs4 1.1.0 -> windows-sys 0.61.2 -> windows-link 0.2.1
Linux normal closure fs4 1.1.0 -> rustix 1.1.4 -> bitflags 2.13.1 + linux-raw-sys 0.12.1
Build/proc-macro closure No build dependency or procedural macro in the resolved normal/build tree; rustix does contain its own build.rs, which remains part of the source review
Unsafe/platform boundary Direct raw-handle Windows locking calls and Unix borrowed-fd conversion; platform calls are supplied by windows-sys or rustix
Public vocabulary Candidate remains private; fs4 types/errors must map into Tosumu-owned guard and typed error details
Native check Sync-only candidate compiled on x86_64-pc-windows-msvc in the isolated audit manifest
WASM check An unconditional dependency fails wasm32-unknown-unknown through rustix/errno; a cfg(any(unix, windows)) target dependency compiles while excluding the closure on WASM
Build scripts No fs4 build script observed; transitive source/build-script review remains required before final admission

The focused review additionally confirmed that the enabled path has no procedural macro or native-code compilation. rustix/build.rs probes compiler and target capabilities and emits cfg selections; it does not fetch sources. The actual locking boundary remains fs4's small raw-handle/borrowed-fd layer over the selected windows-sys or rustix calls. This does not constitute a general audit of those ecosystems, but it is proportionate to admitting this exact private, sync-only mechanism with lockfile checksums and target tests.

The candidate is admitted only for ADR-0004 under the constraints in the table. AR-0010 remains Incubating for the repository's broader dependency policy.

Reopening Triggers

  • A new dependency enters tosumu-core or the authenticated format path.
  • A dependency exposes foreign types through a durable public Tosumu API.
  • A build script, procedural macro, unsafe implementation, or generated source materially changes the trusted closure.
  • Release or incident response requires an offline or repository-rooted source build.
  • A vulnerability or upstream ownership change affects a critical dependency.

Review History

Cycle 1 -- 2026-08-27

  • Status entering review: Proposed
  • New evidence: current dependency claims and Cargo-based resolution were compared with Tosumu's authenticated-storage boundary.
  • Findings: provenance deserves focused evidence, but one mandatory source mechanism is not yet justified.
  • Disposition: Incubating
  • Resulting ADR or documentation change: none

Cycle 2 -- 2026-08-27

  • Status entering review: Incubating
  • New evidence: MVP+10 needs cooperative cross-process writer admission, while standard Rust file locking starts after Tosumu's declared MSRV. fs4 1.1.0 documents Rust 1.75 support for its sync feature and uses platform-specific locking beneath a sealed extension trait.
  • Findings: this is a format-adjacent core dependency even though it changes no authenticated bytes. Its platform and transitive closure must be retained before use; async features are unrelated and excluded.
  • Disposition: remain Incubating; admit no dependency until the focused inventory and target checks are recorded.
  • Resulting ADR or documentation change: AR-0009 names fs4 only as a candidate.

Cycle 3 -- 2026-08-27

  • Status entering review: Incubating
  • New evidence: exact archive identity, sync-only native closures, direct unsafe boundaries, and target checks were retained in the focused candidate table.
  • Findings: the candidate fits Rust 1.75 and the project license on native targets; unconditional use breaks wasm32-unknown-unknown, while a native- target-only dependency leaves the WASM closure empty.
  • Disposition: remain Incubating pending transitive source/build-script review and the AR-0009 decision about the public raw-WAL bypass.
  • Resulting ADR or documentation change: any future manifest entry must be target-specific to Unix/Windows and sync-only.

Cycle 4 -- 2026-08-27

  • Status entering review: Incubating
  • New evidence: the enabled platform locking source and rustix build script were inspected; raw WAL scope and sidecar semantics were settled in AR-0009.
  • Findings: exact private use has a bounded foreign/unsafe surface, preserves Rust 1.75 and WASM compilation when target-gated, and adds no async, proc- macro, or native compilation baggage.
  • Disposition: admit fs4 1.1.0 only for ADR-0004's native sync-only mechanism; retain Incubating status for general provenance policy.
  • Resulting ADR or documentation change: ADR-0004.

Cycle 5 -- 2026-09-03

  • Status entering review: Incubating
  • New evidence: a deterministic generator now binds an adjacent JSON inventory to the exact Cargo.lock SHA-256 identity and records 226 resolved packages across unfiltered workspace, Linux, Windows, macOS, and WASM profiles. It retains enabled features, registry checksums, license metadata, dependency roles, and build-script/procedural-macro target flags. CI and documentation workflows reject a stale retained artifact.
  • Findings: all 220 non-workspace packages have lockfile checksums; 46 packages declare build-script targets and 12 declare procedural-macro targets. These are resolution and candidate-review facts only. Unsafe behavior, advisory status, upstream ownership, update ownership, release/fuzz-specific closure, and platform qualification remain unestablished.
  • Disposition: remain Incubating. The generated closure satisfies the first follow-up but does not yet justify a general risk-tiered policy or ADR.
  • Resulting ADR or documentation change: retain docs/Notes/dependency-provenance-baseline-v1.md and its adjacent generated JSON artifact as Slice 1 evidence.

Cycle 6 -- 2026-09-03

  • Status entering review: Incubating
  • New evidence: a separate human-owned input classifies all 11 direct normal tosumu-core dependencies with tier floors, concerns, update ownership, and rationale. The generator binds this input by SHA-256 and rejects incomplete or structurally lowered classifications.
  • Findings: nine direct dependencies are provisionally critical and two are elevated. The zeroize declaration is directly enabled but not directly used by Tosumu source, so dependency presence cannot support a secret-erasure claim. The unfiltered graph traces exposure to 57 packages, including 10 with build-script and three with procedural-macro targets, but feature unification means that is not yet a named native release closure. The 215 remaining packages have deliberately not received inferred low-risk classifications.
  • Disposition: remain Incubating. Continue into transitive build, procedural- macro, feature, unsafe, and target review before proposing policy acceptance.
  • Resulting ADR or documentation change: add the provisional dependency-risk-classification-v1.json evidence input; no ADR.

Cycle 7 -- 2026-09-03

  • Status entering review: Incubating
  • New evidence: package-specific cargo tree profiles now separate tosumu-core target reachability from workspace-wide feature unification. Linux and macOS each resolve 41 packages with seven build-script candidates; Windows resolves 39 and WASM 35, each with five. Every target has one procedural-macro candidate.
  • Findings: the narrower profiles remove browser-feature contamination from native core closure evidence. They establish target/feature reachability, not actual build execution, artifact inclusion, runtime reachability, or assurance-critical participation.
  • Disposition: remain Incubating and review the seven exact build-script source identities before strengthening the claim.
  • Resulting ADR or documentation change: extend the generated baseline with core_artifact_profiles; no policy or artifact qualification is accepted.

Cycle 8 -- 2026-09-03

  • Status entering review: Incubating
  • New evidence: all seven tosumu-core target build-script candidates have human findings bound to exact build.rs SHA-256 identities. The generator rejects candidate drift, missing findings, and source-hash changes.
  • Findings: the scripts perform compiler/version probes, cfg selection, and in some cases OUT_DIR generation or target/platform probing. No network or non-rustc native compiler invocation was observed in the exact scripts. Helper build dependencies, referenced probe files, and the procedural macro prevent a complete build-execution review.
  • Disposition: remain Incubating with the build-script review explicitly attempted_incomplete; inspect the remaining executable inputs next.
  • Resulting ADR or documentation change: add dependency-build-script-review-v1.json; no policy acceptance.

Cycle 9 -- 2026-09-03

  • Status entering review: Incubating
  • New evidence: exact file-set identities and findings now cover version_check, the proc-macro2 and thiserror compiler probes, and the complete thiserror-impl Rust source tree.
  • Findings: the named helper/probe gaps are closed at source level. The derive macro itself performs token parsing and generation without observed direct filesystem, subprocess, network, unsafe-block, or runtime-initialization operations, but its four-package macro runtime closure remains unreviewed.
  • Disposition: remain Incubating and attempted_incomplete; source review is still not controlled-build execution evidence.
  • Resulting ADR or documentation change: add dependency-executable-input-review-v1.json; no policy acceptance.

Cycle 10 -- 2026-09-03

  • Status entering review: Incubating
  • New evidence: the selected four-package procedural-macro runtime closure is bound by feature set and complete Rust source-tree identity across 79 files and 59,731 lines.
  • Findings: bounded triage localizes unsafe implementation surfaces in proc-macro2, syn, and unicode-ident. It does not establish their invariants or constitute a complete source audit.
  • Disposition: remain Incubating and attempted_incomplete; next capture actual controlled-build execution and select unsafe surfaces for focused review.
  • Resulting ADR or documentation change: add dependency-proc-macro-runtime-review-v1.json; no policy acceptance.

Cycle 11 -- 2026-09-03

  • Status entering review: Incubating; C2 oracle toolchain unadmitted.
  • New evidence: the offline crypto oracle pins Go 1.26.8, x/crypto 0.56.0, and transitive x/sys 0.47.0. Go module sums cover both modules, and the compiled non-standard closure is seven packages. The checksum-verified local toolchain builds and passes the 14-case corpus.
  • Findings: the oracle is outside the Cargo workspace, performs no database I/O, ships in no release artifact, and exposes no runtime provider surface. This sharply bounds its role, but module checksums and package reachability are not complete source review or compiler/platform qualification.
  • Disposition: admit the exact toolchain and module versions for this evidence-only oracle. Any version, closure, execution-role, or artifact- inclusion change reopens review. General dependency policy remains Incubating.
  • Resulting ADR or documentation change: retain crypto-c2-oracle-provenance-v1.md; no product dependency or ADR.