---
id: implementation/vendor-crate-scaffolding
name: "Vendor (crate scaffolding: Cargo.toml, lib.rs, vendor module skeleton, license notice)"
status: completed
depends_on: []
scope: narrow
risk: low
impact: project
level: implementation
---

## Description

Create the `alksocks` crate skeleton so the vendor extraction tasks have
their targets. This is the first implementation work in the repo, as `src/`
does not exist yet. The crate is born wasm-clean: the default build is
protocol-only with zero kernel-net code (ADR-009 §Amendment, ADR-011
§Amendment), so the wasm check must be green from the first commit.

Deliverables:

1. **`Cargo.toml`** mirroring the sibling crates' posture
   (`/workspace/@alkdev/alktunnels`, `/workspace/@alkdev/alktty`):
   - `name = "alksocks"`, `version = "0.1.0"`, `edition = "2021"`,
     `rust-version = "1.88"`, `license = "MIT OR Apache-2.0"`,
     description/keywords/categories/repository per the siblings.
   - `[features]`: `default = []`, `local = []`, `composed = []`,
     declared empty now (ADR-009 pins the two-feature layout; the
     features are populated by their modules' later tasks; `composed`
     will add the alktunnels dep, `local` will add `tokio/net` +
     `socket2`).
   - `[dependencies]`: `tokio = { version = "1", default-features = false,
     features = ["rt", "sync", "io-util", "macros", "time"] }` (the
     wasm-clean subset per AGENTS.md convention 4, so **never
     `features = ["full"]`**), `thiserror = "2"`, `tracing = "0.1"`.
     **No `alkcall` yet**, since the vendor does not need it; the
     producer/consumer tasks pin `alkcall = "0.8.0"` when they land.
   - `[dev-dependencies]`: `tokio = { version = "1", features = ["full",
     "test-util", "macros"] }` (tests are native-only; they are not
     part of the wasm-clean surface).
2. **`src/lib.rs`**: `#![forbid(unsafe_code)]`, brief crate docs
   (what the crate is, pointing at `docs/architecture/overview.md`
   since doc comments are fine and expected), `pub mod vendor;`.
3. **`src/vendor/` skeleton** preserving upstream file names so per-file
   diffs against the reference checkout stay mechanical (the
   maintenance posture, vendor.md §Maintenance Posture):
   - `src/vendor/mod.rs`: a module doc carrying the provenance note:
     extracted from fast-socks5 **v1.0.0** (MIT, third-party upstream),
     per ADR-011; the extraction cut + carried changes are recorded in
     `docs/architecture/vendor.md`; submodule declarations for `server`,
     `client`, `util` (stub files, filled by the extraction tasks).
   - `src/vendor/server.rs`, `src/vendor/client.rs`,
     `src/vendor/util/mod.rs`, `src/vendor/util/stream.rs`,
     `src/vendor/util/target_addr.rs`: empty stubs.
4. **Bundled license notice** at `src/vendor/LICENSE`: the upstream MIT
   license text plus attribution (fast-socks5 v1.0.0,
   github.com/dizda/fast-socks5), referenced from the vendor module doc
   (ADR-011's license obligation; upstream has no per-file headers, so
   the bundled notice is the obligation's carrier).

## Acceptance Criteria

- [x] `cargo test` passes (empty crate compiles and runs)
- [x] `cargo clippy --all-targets -- -D warnings` clean
- [x] `cargo fmt --check` clean
- [x] `cargo check --target wasm32-unknown-unknown` clean (the wasm gate
      is green from birth, with no `mio`/`socket2`/`tokio::net` in the graph)
- [x] `cargo clippy --target wasm32-unknown-unknown -- -D warnings` clean
- [x] `Cargo.toml` has no `alkcall`, no `anyhow`, no `log`, no
      `async-trait`, no `tokio-stream`, no `socket2` in `[dependencies]`
- [x] `src/vendor/LICENSE` exists with the MIT text + v1.0.0 attribution,
      referenced from the vendor module doc
- [x] `#![forbid(unsafe_code)]` present in `lib.rs`

## References

- docs/architecture/vendor.md (the vendor spec)
- docs/architecture/decisions/011-inline-vendor.md §Amendment (the
  extraction posture, license obligation, wasm gate)
- docs/architecture/decisions/009-feature-gates.md (the feature layout)
- docs/architecture/overview.md §Dependencies (the tokio subset)
- Sibling Cargo.toml posture: `/workspace/@alkdev/alktunnels/Cargo.toml`,
  `/workspace/@alkdev/alktty/Cargo.toml`
- Upstream license: `/workspace/fast-socks5/Cargo.toml` (v1.0.0, MIT) +
  `/workspace/fast-socks5/LICENSE`

## Notes

- **Cargo.toml** follows the alktunnels posture (the closer sibling with
  the same tokio wasm-clean subset incl. `time`, same dev-dep tokio
  shape): `exclude` mirrors alktunnels (docs/research/ + tasks/ +
  sdd_process.md); keywords/categories/description point at the
  SOCKS5 story; repository is the git.alk.dev remote. `[features]`
  declares `default`/`local`/`composed` empty (ADR-009 §Amendment,
  to be populated by their modules' tasks); `[dependencies]` is exactly the
  task's trio (tokio wasm-clean subset, tracing, thiserror, i.e. no
  alkcall and no net-shaped anything). A `[lib]` section pins the crate
  name, matching the siblings.
- **lib.rs**: `#![forbid(unsafe_code)]`, crate docs (what the crate
  is, the never-binds posture, the vendor provenance pointer, the
  overview.md link), `pub mod vendor;`. Nothing else: later tasks add
  their own modules + re-exports.
- **src/vendor/** skeleton preserves upstream v1.0.0 file names for
  mechanical per-file diffs: `mod.rs` (provenance module doc +
  submodule declarations), `server.rs`, `client.rs`,
  `util/{mod,stream,target_addr}.rs`: the five files the extraction
  tasks fill. Stubs carry one-line module docs naming their filling
  task and (for the util files) the cut-region note; `util/mod.rs`
  pre-declares `stream` + `target_addr` exactly as upstream does.
  `socks4/` is deliberately absent (the cut).
- **src/vendor/LICENSE**: the upstream MIT text verbatim (Copyright
  (c) 2025 Jonathan Dizdarevic, per `/workspace/fast-socks5/LICENSE`)
  under a provenance header (v1.0.0, github.com/dizda/fast-socks5,
  ADR-011 pointer, vendor.md pointer); referenced from the `mod.rs`
  module doc via an intra-doc link. The upstream license has no
  "MIT License" body-text title line; it opens with "MIT License"
  + copyright, and the notice keeps that text verbatim after the header.
- Verification ran clean: `cargo test` (0 tests, compiles + runs),
  clippy `--all-targets -- -D warnings`, `cargo fmt --check`,
  `cargo check --target wasm32-unknown-unknown`, and
  `cargo clippy --target wasm32-unknown-unknown -- -D warnings`, so
  the wasm gate is green from birth (the dep graph is tokio-wasm-
  subset + tracing + thiserror only).

## Summary

Created the `alksocks` 0.1.0 crate skeleton per the task: `Cargo.toml`
(sibling posture; empty `local`/`composed` features declared; tokio
wasm-clean subset `rt/sync/io-util/macros/time`, `tracing`,
`thiserror`; no alkcall/net-shaped deps; full tokio dev-deps for
native tests), `src/lib.rs` (`#![forbid(unsafe_code)]`, crate docs
pointing at the architecture spec set, `pub mod vendor;`), the
`src/vendor/` skeleton preserving upstream fast-socks5 v1.0.0 file
names (`mod.rs` with the provenance/extract-not-copy module doc +
`server`/`client`/`util` declarations; five stub files for the
extraction tasks; `socks4/` cut), and `src/vendor/LICENSE` (upstream
MIT text + v1.0.0 attribution header, referenced from the vendor
module doc). All acceptance criteria verified: test/clippy/fmt clean
natively, both wasm checks clean, dep surface clean, license notice
in place, forbid-unsafe present.