alktls/tasks/crate-init.md

---
id: crate-init
name: Crate skeleton — module files, feature gates, error type, re-exports
status: completed
depends_on: []
scope: narrow
risk: low
impact: project
level: implementation
tags: [scaffold, crate-init]
---

## Description

Initialize the alktls module skeleton per ADR-006: replace the
placeholder `src/lib.rs` with the eight-module layout
(`identity`, `credentials`, `fingerprint`, `server`, `client`, `pem`,
`signing` + `lib.rs`), the feature gates per ADR-003
(`default = []`; `noq`, `tcp`, `acme`), and the `TlsError` type per
ADR-002. Modules may be stubs (`pub fn` bodies `todo!`-free — empty
with doc comments) but the module map, features, deps, and error enum
land now so subsequent tasks are additive, not structural.

### What lands here

- `Cargo.toml` final shape: deps per ADR-003's TOML block (`noq` +
  `noq-proto` optional, default-features off; `tokio-rustls`;
  `rustls-acme`; the always-present set per the overview's dependency
  posture).
- `src/lib.rs`: crate docs (the overview's shape), `TlsError` (the
  ADR-002 enum verbatim, including the `noq`-gated `NoqWrap` variant),
  and the re-export block (the documented public API surface).
- Empty module files with `//!` doc headers only — no function bodies.
- `.taskgraph.toml` not needed (default `./tasks` works).

### What does NOT land here

- Any ported logic (subsequent tasks).
- Any test beyond a compile assertion that the error enum matches.

## Work

1. Rewrite `Cargo.toml` features/deps per ADR-003.
2. Write `src/lib.rs` with the ADR-002 `TlsError` + module
   declarations + re-exports.
3. Create the seven module files with doc headers.
4. Verify the feature matrix compiles (all four combos below).

## Verification

- [ ] `cargo build` (default, `default = []`) passes
- [ ] `cargo test --all-features` passes (noq + tcp + acme all resolve)
- [ ] Each feature alone: `cargo check --features noq`, `--features tcp`,
      `--features acme`
- [ ] `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check`
- [ ] `TlsError` is `#[non_exhaustive]` with exactly the ADR-002
      variants (`CertLoad`, `SelfSigned`, `Rustls`, `VerifierBuild`,
      `NoqWrap` noq-gated, `AcmeConfig`)

## Acceptance Criteria

- [ ] The module map matches ADR-006 (one module per file, re-exported
      from `lib.rs`; public API surface is the re-export block)
- [ ] Feature gates match ADR-003 exactly
- [ ] No `todo!`/`unimplemented!`/panics in library code — stubs are
      empty or error-returning, never panicking

## References

- docs/architecture/decisions/002-tlserror-shape.md (the enum)
- docs/architecture/decisions/003-noq-replaces-quinn.md (features, deps)
- docs/architecture/decisions/006-module-layout-and-tests.md (module map)
- docs/architecture/overview.md (dependency posture)

## Notes

> Agent fills this during implementation. Document any decisions,
> deviations from architecture, or relevant context discovered.

### Decisions / deviations

1. **`VerifierBuild` source path: `rustls::client::VerifierBuilderError`,
   not `rustls::webpki::VerifierBuilderError`.** The ADR-002 sketch used
   the `rustls::webpki` path, but at the pinned rustls 0.23.44 that
   module is private — the type is re-exported publicly at
   `rustls::client` (verified in the 0.23.44 source: `mod webpki;` +
   `pub use crate::webpki::{VerifierBuilderError, ...}` inside
   `pub mod client`). Same type, public path; noted in the variant's
   doc comment. ADR-002 needs a one-line amendment (recorded for the
   review-impl docs-sync pass).
2. **Re-export block deferred per module.** `lib.rs` carries the module
   declarations now; the `pub use` block lands incrementally with each
   port task (a re-export of a not-yet-ported type cannot compile, and
   every intermediate commit must stay green). The final shape is
   ADR-006's map + overview.md's surface; port-client (the last module
   port) completes it.
3. **The `noq`-gated compile assertion** cannot construct
   `NoInitialCipherSuite` from outside noq-proto (private field), so the
   test is an existence proof via `matches!` on `Option<TlsError>` —
   compiles only when the variant + its `#[from]` source exist.
4. **`Cargo.toml` unchanged** — the scaffold's TOML already matched
   ADR-003's block exactly (features `default = []` / `noq` / `tcp` /
   `acme`; `noq` with `default-features = false, features = ["rustls"]`).
   Verified against ADR-003 line-by-line; no edits needed.

## Summary

> Agent fills this on completion. Brief description of what was
> implemented, files changed, and any follow-up needed.

### What landed

- `src/lib.rs`: crate docs + the ADR-002 `TlsError` verbatim (six
  variants, `#[non_exhaustive]`, `#[source]` chains; `NoqWrap`
  noq-gated) + module declarations + a compile-assertion test for the
  enum (`#[from]` conversions + `AcmeConfig` display) and the noq-gated
  `NoqWrap` existence test.
- The seven module files (`identity`, `credentials`, `fingerprint`,
  `server`, `client`, `pem`, `signing`) with `//!` doc headers only —
  no bodies, per "what does NOT land here".
- Feature matrix verified: default, `noq`, `tcp`, `acme`,
  `--all-features`.

### Verification

- `cargo build` (default) ✓; `cargo test` ✓ (1 test);
  `cargo test --features noq` ✓ (2 tests); `cargo check --features
  tcp|acme` ✓; `cargo test --all-features` ✓; `cargo clippy
  --all-targets --all-features -- -D warnings` ✓; `cargo fmt --check` ✓;
  `cargo doc --no-deps` ✓.

### Follow-up

- ADR-002 amendment note for the `VerifierBuilderError` path
  (review-impl docs sync).