Implement native PacketDump capture (#87)

programs/README.md

@@ -9,7 +9,7 @@ here so a source entry is never mistaken for a completed port.
 | --- | --- | --- |
 | `osd-inspector` | OSDInspector | Implemented and tested offline |
 | `simple-bot` | SimpleBot | Implemented with live and deterministic fake-grid modes |
-| `packet-dump` | PacketDump | Pending milestone 11 issue #87 |
+| `packet-dump` | PacketDump | Implemented with live and deterministic fake-grid capture |
 | `prim-inspector` | PrimInspector | Pending milestone 11 issue #88 |
 | `inventory-explorer` | InventoryExplorer | Pending milestone 11 issue #89 |
 | `irc-gateway` | IRCGateway | Pending milestone 11 issue #90 |
@@ -100,3 +100,51 @@ suite and the related runtime compatibility cases with:
 cargo test -p libremetaverse-programs --test simple_bot_cli --locked
 cargo test --manifest-path tests/compat/Cargo.toml --test core_runtime_shims --locked
 ```
+
+## PacketDump
+
+`packet-dump` preserves the upstream live arguments and its 20-second login
+timeout while adding safe, bounded capture controls:
+
+```text
+packet-dump FIRSTNAME LASTNAME PASSWORD SECONDS
+  [--direction incoming|outgoing|both]
+  [--packet-type NAME]... [--raw]
+  [--output FILE] [--max-output-bytes BYTES] [--max-packets COUNT]
+```
+
+`SECONDS=0` captures until Ctrl-C. Credentials can instead come from
+`GRID_FIRST_NAME`, `GRID_LAST_NAME`, and `GRID_PASSWORD`; `GRID_LOGIN_URL` or
+`--login-uri` selects a login endpoint. The client disables multiple simulator
+connections and sends zero land, wind, and cloud throttles like the source
+program. Incoming decoded callbacks retain their original datagrams, while
+outgoing callbacks are decoded through the public packet factory. Records show
+direction, packet type, simulator, byte count, sequence, frequency, ID, and
+header flags. Exact packet-type filters may be repeated.
+
+Raw hexadecimal output is opt-in. Live capture masks the password and native
+session identifiers wherever they occur in a datagram, and suppresses raw
+payloads containing URLs, authorization terms, capability terms, or token
+assignments. Login and disconnect messages use the same text redaction.
+Output defaults to stdout, may be redirected to a newly truncated file, and is
+bounded to 16 MiB and 100,000 matching packets unless lower or higher explicit
+limits are supplied. A complete line is either written or rejected at the byte
+limit.
+
+Offline validation uses `--fake-script FILE` with records of this form:
+
+```text
+incoming<TAB>simulator<TAB>hex-bytes
+outgoing<TAB>simulator<TAB>hex-bytes
+```
+
+Scripts are capped at 8 MiB and individual datagrams at 64 KiB. Each datagram
+is passed through the native wire decoder; malformed and unknown packets are
+reported without aborting the capture. The issue-focused and related translated
+wire tests are:
+
+```sh
+cargo test -p libremetaverse-programs --test packet_dump_cli --locked
+cargo test -p libremetaverse --test packet_wire --locked
+cargo test --manifest-path tests/compat/Cargo.toml --test wire_semantics --locked
+```