alksocks/tasks/implementation/core-params-errors.md at a2483e4a847051f95233f368eedabe6080d626a1

0 Fork 0

Files

T

glm-5.3-flash a2483e4a84 tasks: decompose the protocol-core group — thirteen dependency-ordered tasks

Batch 1 of the Phase 1 decomposition: the default, wasm-clean crate
(producer + consumer + wire + seams + params/errors), per the
architecture spec set (ADRs 001-013) and the three POCs' validated
shapes. The assembly layer (local/composed providers, front doors) is
batch 2, decomposed after review-protocol-core opens.

- foundation: crate-deps (alkcall 0.8.0 first consumption), wire-codec
  (the ASSOCIATE frame + the joint bound), seam-types (the three
  ADR-004 seams), params-errors (the one-way-door surface)
- harness: duplex transport + identities + in-process seams (the
  alkcall 0.8.0 establishment surface proven before the producer)
- verticals: producer/consumer splits per command (CONNECT,
  ASSOCIATE, BIND) — each POC's scope, producer tasks test via the
  raw RFC client, consumer tasks e2e through the harness
- closing: integration suite (three-command regression, teardown
  matrix, identity matrix, docs sync) + review-protocol-core (the
  batch gate)

taskgraph: 8 generations, no cycles, risk path 2.55 (no high-risk
tasks). Also records the wire.md/bast.md len=0 residue (payload-level
F-2 is the operative invariant) as a doc-sync deliverable of the
wire-codec task.

Verification: cargo test (76 passed), fmt clean; taskgraph
validate/cycles/parallel/critical clean.

2026-09-23 07:38:27 +00:00

3.5 KiB

Raw Blame History

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

name

status

depends_on

scope

risk

impact

level

implementation/core-params-errors

Core — params schema + scope constants + typed error surface

pending

implementation/core-crate-deps

narrow

low

component

implementation

Description

Implement src/params.rs and src/error.rs per wire.md §The Open Op, ADR-001, and ADR-006 — the wire-stable surface (the one-way door) and the typed open-error vocabulary. Template: /workspace/@alkdev/alktunnels/src/params.rs (the sibling's spec builder + scope-constant posture).

Deliverables:

src/params.rs:
- Constants: OP_SOCKS5_OPEN = "channels/socks5/sub", SOCKS5_ALPN = "alk/socks5", SOCKS5_OPEN_SCOPE = "socks5:open", SOCKS5_BIND_SCOPE = "socks5:bind" (ADR-001/ ADR-006; the scope-string convention <alpn-family>: <capability>; stable once published).
- socks5_open_spec() -> OperationSpec — Sub-typed, external, channel-open marker on SOCKS5_ALPN, trivial params: input schema {type: object}, additionalProperties: false (empty params stay valid forever — ADR-001's additive-only extension rule); reply schema {"channel_id": integer, minimum 1}; required_scopes = ["socks5:open"]. Follow the alktunnels spec-builder shape exactly (the registry validates against these schemas).
- The trivial params struct (Socks5Params {} — serde deny_unknown_fields, empty) for the consumer's open call.
src/error.rs — the typed open-error surface (alkcall ADR-049 §4):
- SocksOpenError — the consumer-side open-failure vocabulary mapping the channel:open_failed reasons (dial_failed / unknown_resource / resource_shortage / handler_error / timeout) plus the registry's FORBIDDEN/INVALID_INPUT classes, shaped on alktunnels' TunnelOpenError + establishment_reason helper.
- The session-level error type for the consumer sessions (SocksSessionError-shaped: open errors vs in-stream SocksError vs I/O) — the exact variant set is the task's judgment; keep it faithful to what the sessions actually surface (a refused session never yields a phantom channel; a refused target is an RFC reply code surfaced through the session type — consumer.md §Error surface).
lib.rs re-exports for the new public surface (convention 15).

Tests: spec-builder shape assertions (op id, ALPN marker, scopes, schemas — the trivial-params schema rejects unknown fields), params serde round-trip (empty object valid; unknown field rejected), the error-reason mapping table.

Acceptance Criteria

Constants + spec builder per ADR-001/ADR-006 exactly (op id, ALPN, both scopes, trivial schemas)
Input schema rejects unknown fields (the loud-rejection posture)
Typed open-error surface maps the ADR-049 §4 reasons
lib.rs re-exports the public surface
cargo test green; clippy/fmt clean; both wasm checks clean

References

docs/architecture/wire.md §The Open Op (the normative op shape)
docs/architecture/decisions/001-alpn-and-open-op.md (trivial params; the one-way door)
docs/architecture/decisions/006-access-control.md (the two scopes)
docs/architecture/decisions/011-inline-vendor.md §4 (the typed open-error surface)
Template: /workspace/@alkdev/alktunnels/src/params.rs (tunnel_open_spec, the scope constants, establishment_reason)
POC sketch: /workspace/alksocks-connect-poc/src/params.rs

Notes

To be filled by implementation agent

Summary

To be filled on completion

3.5 KiB Raw Blame History