alksocks/tasks/implementation/vendor-crate-scaffolding.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
implementation/vendor-crate-scaffolding	Vendor (crate scaffolding: Cargo.toml, lib.rs, vendor module skeleton, license notice)	completed		narrow	low	project	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

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