feat(ip6): operator override for the RFC 6724 policy table (R11)

Make the RFC 6724 §10.3 address-selection policy table (source/dest
precedence + label) operator-overridable at runtime — the PyTCP analogue
of Linux 'ip addrlabel'. A whole precedence/label table is not a scalar,
and Linux exposes it via a dedicated netlink control surface rather than
'/proc/sys', so this is a small dedicated control API on the policy-table
module, not a scalar sysctl:

  - set_policy_table(entries)  -> install a custom table (rejects a table
    with no ::/0 catch-all so 'lookup' stays total)
  - reset_policy_table()       -> restore the RFC §10.3 default
  - get_policy_table()         -> immutable snapshot of the active table

'lookup' now reads the active table each call, so the §5 rule-6
source-selection consumer picks up an override live without a restart.
The override is a copy-on-write reference swap of the whole tuple —
readers always see a complete immutable snapshot (a frozen tuple of
frozen PolicyEntry records), so it is lock-free-safe under free-threading
(the no-GIL COW pattern).

Tests-first at test__ip6__policy_table.py::TestIp6PolicyTableOverride:
override changes 'lookup' live, reset restores the default, get returns
the active snapshot, and a table with no ::/0 catch-all is rejected.
Pre-fix the tests error on the missing symbols; post-fix they pass.

Adherence rfc6724__default_address_selection updated in lockstep (§2.1 /
§10.3 flipped to met, stale 'lib/ip6_policy_table.py' paths corrected to
'protocols/ip6/ip6__policy_table.py') plus the rfc6724_source_selection.md
tracker. Phase-3 note: daemon-IPC exposure of this control surface is a
deferred follow-on (in-process only today).

Reference: RFC 6724 §2.1 (administrator-configurable policy table).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ccie18643

docs/refactor/host_refinements_backlog.md

@@ -56,6 +56,19 @@ until the user says "push".
   `test__icmp6__mld1_compat.py::TestIcmp6MldForcedVersion`. Adherence:
   `rfc2710__mld_v1`. (R10's RFC 2710 §4 Report-suppression part remains —
   optimization only.)
+- [x] **RFC 6724 policy-table override (R11)** — `set_policy_table` /
+  `reset_policy_table` / `get_policy_table` on
+  `protocols/ip6/ip6__policy_table.py` — the PyTCP analogue of Linux
+  `ip addrlabel` (a dedicated control API, not a scalar sysctl, since a
+  whole table is not a scalar). `lookup` reads the active table live
+  (copy-on-write reference swap, lock-free under free-threading) so the
+  §5 rule-6 selector picks up an override without a restart;
+  `set_policy_table` rejects a table with no ::/0 catch-all so `lookup`
+  stays total. Unit tests:
+  `test__ip6__policy_table.py::TestIp6PolicyTableOverride`. Adherence:
+  `rfc6724__default_address_selection` (§2.1 / §10.3 flipped to met,
+  stale `lib/` paths corrected). Phase-3 note: daemon-IPC exposure of
+  this control surface is a follow-on (in-process only today).
 
 **The canonical SO_RCVBUF guard pattern** (mirror for any new datagram socket):
 
@@ -227,19 +240,17 @@ stay text-only (Linux `sysctl` has no `-j` either).
   marginal value. Tests-first in `tests/integration/protocols/icmp6/`.
 - **Effort:** small. **Risk:** low. **Value:** marginal.
 
-### R11 — RFC 6724 `ip.policy_table` sysctl override (small-medium)
+### R11 — RFC 6724 policy-table override — SHIPPED (see "Shipped" above)
 
-- **Why:** the RFC 6724 §2.1 policy table (source/dest address selection
-  precedence/label) is hard-coded; Linux exposes it as a writable table
-  (`/proc/sys/net/ipv6/...` / `ip addrlabel`). Source:
-  `rfc6724_source_selection.md` non-blocking arc extension.
-- **Scope:** make the policy table operator-overridable (a sysctl entry or a
-  small dedicated API), re-resolved live per the qualified-module-access
-  pattern.
-- **Tests-first:** unit tests asserting source-selection changes when the
-  policy table is overridden.
-- **Effort:** small-medium. **Risk:** low. **Value:** low-medium (rarely
-  tuned on a host).
+- Implemented as a small dedicated control API on
+  `protocols/ip6/ip6__policy_table.py` (`set_policy_table` /
+  `reset_policy_table` / `get_policy_table`) rather than a scalar sysctl —
+  a whole precedence/label table is not a scalar, and Linux itself exposes
+  it via `ip addrlabel` (netlink), not `/proc/sys`. Copy-on-write
+  reference swap, read live by `lookup`.
+- **Follow-on (deferred):** expose the control API over the daemon IPC
+  boundary for Phase-3 (in-process only today), and the corresponding
+  `pytcp` CLI verb. Low value; do on appetite.
 
 ### Ongoing hygiene (not a discrete scheduled item)
 
@@ -275,8 +286,8 @@ so this backlog's boundary is explicit.
 1. ~~**R1** (ping SO_RCVBUF)~~ — SHIPPED; the SO_RCVBUF symmetry is closed.
 2. Small self-contained wins, any order: ~~**R5** (CLI JSON — all four
    observation commands)~~ SHIPPED, ~~**R10** mld.version knob~~ SHIPPED
-   (R10 §4 suppression remains, marginal), **R11** (RFC 6724 policy
-   table), or dip into **R2** (setsockopt sweep).
+   (R10 §4 suppression remains, marginal), ~~**R11** (RFC 6724 policy
+   table)~~ SHIPPED, or dip into **R2** (setsockopt sweep).
 3. **R4** (IPv6 SSM) — the big-value track; do it as its own phased effort.
 4. Medium items as appetite allows: **R3** (SO_SNDBUF/SNDTIMEO), **R6**
    (HyStart++), **R7** (DF-guarded probe), **R8** (IP_RECVERR over daemon),
@@ -292,4 +303,5 @@ None block a 3.0.8 release. Everything here can equally slip to 3.0.9.
   this backlog plan).
 - **Unpushed:** `f5ecd901` (R1 ping SO_RCVBUF), `2750afb5` (R5 address
   JSON), `9b465047` (footer refresh), `2ecaf708` (ss/route/neighbor JSON),
-  + the `mld.version` knob (R10) commit. Hold until the user says "push".
+  `3bf8315d` (R10 mld.version knob), + the R11 policy-table override
+  commit. Hold until the user says "push".

docs/refactor/rfc6724_source_selection.md

@@ -212,8 +212,13 @@ Ships:
   `lookup(address) → (precedence, label)` function. (Shipped as
   `packages/pytcp/pytcp/protocols/ip6/ip6__policy_table.py`, not the
   planned `lib/ip6_policy_table.py`.)
-- Optional sysctl-driven override (deferred to §12c.3.b
-  if needed).
+- Operator override — **shipped** as `set_policy_table` /
+  `reset_policy_table` / `get_policy_table` on the policy-table
+  module (the `ip addrlabel` analogue, a dedicated control API
+  rather than a scalar sysctl since a whole table is not a
+  scalar; copy-on-write reference swap, lock-free under
+  free-threading). `lookup` reads the active table live so the
+  rule-6 selector picks up an override without a restart.
 - Rule 6 wired into `_select_ip6_source`.
 
 ## §12c.4 — IPv4 source-selection symmetry

docs/rfc/ip6/rfc6724__default_address_selection/adherence.md

@@ -8,7 +8,7 @@
 | Date        | September 2012                                                   |
 | Source text | [`rfc6724.txt`](rfc6724.txt)                                     |
 
-## Status: PARTIAL (source-selection rules 1, 2, 3, 6, 7, 8 shipped; IPv4 symmetry shipped; DAS / sysctl override deferred)
+## Status: PARTIAL (source-selection rules 1, 2, 3, 6, 7, 8 shipped; IPv4 symmetry shipped; policy-table override shipped; DAS deferred)
 
 PyTCP runs the RFC 6724 §5 default source-address-selection
 algorithm on every outbound IPv6 packet whose source is
@@ -20,7 +20,8 @@ lexicographic sort encoded with rules 1, 2, 3, 6, 7, and 8,
 and returns the winner. The pure helpers — RFC 4007/4291
 scope extraction and the §2.2 CommonPrefixLen — live in
 `packages/pytcp/pytcp/lib/ip6_source_selection.py`; the §10.3 default policy
-table backing rule 6 lives in `packages/pytcp/pytcp/lib/ip6_policy_table.py`.
+table backing rule 6 lives in
+`packages/pytcp/pytcp/protocols/ip6/ip6__policy_table.py`.
 Rules 4 (home address), 5 (outgoing interface), and 5.5
 (next-hop) are no-ops on a single-interface host stack.
 
@@ -36,10 +37,16 @@ Rule 6 consults the RFC 6724 §10.3 default policy table.
 Default labels follow the RFC figure verbatim (label 0 for
 ::1/128, label 1 for the catch-all ::/0, label 2 for 6to4
 2002::/16, label 4 for IPv4-mapped, label 5 for Teredo, label
-13 for ULA fc00::/7, etc.). A future Phase §12c.3.b may add a
-sysctl-driven override of the default table; the framework
-is shaped so that swap-out is a one-symbol change in the
-selector.
+13 for ULA fc00::/7, etc.). An operator may replace the active
+table at runtime through `set_policy_table` /
+`reset_policy_table` / `get_policy_table` on
+`ip6__policy_table` — the PyTCP analogue of Linux
+`ip addrlabel` (a dedicated control surface, not a `/proc/sys`
+scalar, since a whole table is not a scalar sysctl). `lookup`
+reads the active table each call (a copy-on-write reference
+swap, lock-free under free-threading) so an override resolves
+live for the rule-6 selector; `set_policy_table` rejects a
+table with no ::/0 catch-all so `lookup` stays total.
 
 The selector is invoked for both unicast and multicast
 destinations with an unspecified source — a DHCPv6 SOLICIT to
@@ -56,7 +63,7 @@ Per-RFC mechanism inventory:
 
 | §          | Mechanism                                                  | Status                             | Where                                                                                            |
 |------------|------------------------------------------------------------|------------------------------------|--------------------------------------------------------------------------------------------------|
-| §2.1       | Configurable address-selection policy table                | met (default table)                | `packages/pytcp/pytcp/lib/ip6_policy_table.py` exposes `DEFAULT_POLICY_TABLE`; sysctl override deferred         |
+| §2.1       | Configurable address-selection policy table                | met                                | `packages/pytcp/pytcp/protocols/ip6/ip6__policy_table.py` exposes `DEFAULT_POLICY_TABLE` + operator override (`set_policy_table` / `reset_policy_table` / `get_policy_table`, the `ip addrlabel` analogue) |
 | §2.2       | CommonPrefixLen helper                                     | met                                | `common_prefix_len` (`packages/pytcp/pytcp/lib/ip6_source_selection.py`)                                        |
 | §3.1       | Scope comparisons                                          | met                                | `ip6_address_scope` returns RFC 4007 / 4291 codepoints                                           |
 | §5 rule 1  | Prefer same address                                        | met                                | `_select_ip6_source` short-circuits when the destination is owned                                |
@@ -70,7 +77,7 @@ Per-RFC mechanism inventory:
 | §5 rule 8  | Use longest matching prefix                                | met                                | sort-key tiebreak after rules 1/2/3                                                              |
 | §6 (v4)    | IPv4 source-selection symmetry                             | met (rules 1, 2, 8)                | `_select_ip4_source` mirrors `_select_ip6_source` for the v4 family at TX                        |
 | §6 (DAS)   | Destination address selection                              | not implemented                    | DNS-resolution selection (rules D1-D8) is out of scope at the stack layer                        |
-| §10.3      | Default policy table                                       | met                                | `DEFAULT_POLICY_TABLE` mirrors RFC figure verbatim; sysctl-driven override deferred              |
+| §10.3      | Default policy table                                       | met                                | `DEFAULT_POLICY_TABLE` mirrors RFC figure verbatim; operator override via `set_policy_table` (rejects a table with no ::/0 catch-all) |
 
 ## Test coverage
 
@@ -114,13 +121,17 @@ Per-RFC mechanism inventory:
     — the TX path runs §5 selection for a multicast
     destination (link-local source filled in for `ff02::1:2`)
     rather than dropping it
-- `packages/pytcp/pytcp/tests/unit/lib/test__lib__ip6_policy_table.py`
+- `packages/pytcp/pytcp/tests/unit/protocols/ip6/test__ip6__policy_table.py`
   - `TestIp6PolicyTableLookup` — RFC §10.3 (precedence, label)
     pairs for ::1, 6to4, Teredo, ULA, deprecated site-local,
     deprecated 6bone, IPv4-mapped, IPv4-compatible,
     catch-all GUA, and link-local (falls through to ::/0)
   - `TestIp6PolicyTableShape` — 9-entry default table,
     typed records, ::/0 catch-all present
+  - `TestIp6PolicyTableOverride` — `set_policy_table` overrides
+    `lookup` live, `reset_policy_table` restores the default,
+    `get_policy_table` returns the active snapshot, and a table
+    with no ::/0 catch-all is rejected
 - `packages/pytcp/pytcp/tests/integration/protocols/ip6/test__ip6__rfc6724_source_selection_rule_6.py`
   - `TestRfc6724Rule6PolicyLabel` — matching label outranks
     longer non-matching prefix (rule 6 > rule 8); ULA

packages/pytcp/pytcp/protocols/ip6/ip6__policy_table.py

@@ -32,9 +32,13 @@
 first hit. The default contents match the RFC §10.3 figure
 verbatim and Linux's /etc/gai.conf default preset.
 
-A future Phase §12c.3.b may add a sysctl-driven runtime
-override, but the default table is sufficient for the §5
-rule-6 consumer to stop being a no-op.
+An operator may replace the active table at runtime through
+'set_policy_table' / 'reset_policy_table' (the PyTCP analogue
+of Linux 'ip addrlabel', which is a dedicated netlink control
+surface rather than a '/proc/sys' scalar — a whole table is
+not a scalar sysctl). 'lookup' reads the active table each
+call so an override resolves live for the §5 rule-6
+source-selection consumer.
 
 pytcp/protocols/ip6/ip6__policy_table.py
 
@@ -79,17 +83,61 @@ class PolicyEntry:
 )
 
 
+# The currently-active policy table. Defaults to the RFC
+# §10.3 table; an operator override swaps the whole tuple
+# reference (copy-on-write). Readers ('lookup' / the rule-6
+# consumer) read this module global each call and always see
+# a complete immutable snapshot — a frozen tuple of frozen
+# 'PolicyEntry' records — so the reference swap is safe under
+# free-threading without a lock (the no-GIL COW pattern).
+_active_policy_table: tuple[PolicyEntry, ...] = DEFAULT_POLICY_TABLE
+
+
 def lookup(address: Ip6Address, /) -> tuple[int, int]:
     """
     Return the (precedence, label) pair from the most-specific
-    policy-table entry that contains the given IPv6 address.
-    The table's terminating ::/0 entry guarantees a hit for
-    every address, so the function is total.
+    active-policy-table entry that contains the given IPv6
+    address. The table's terminating ::/0 entry guarantees a
+    hit for every address, so the function is total.
     """
 
-    for entry in DEFAULT_POLICY_TABLE:
+    for entry in _active_policy_table:
         if address in entry.network:
             return (entry.precedence, entry.label)
     # Unreachable because of the ::/0 catch-all; the assert
     # makes the invariant explicit for static analysis.
     raise AssertionError("RFC 6724 §10.3 policy table missing ::/0 catch-all")
+
+
+def get_policy_table() -> tuple[PolicyEntry, ...]:
+    """
+    Return the currently-active policy table as an immutable
+    snapshot (a frozen tuple of frozen 'PolicyEntry' records).
+    """
+
+    return _active_policy_table
+
+
+def set_policy_table(entries: tuple[PolicyEntry, ...], /) -> None:
+    """
+    Replace the active policy table with 'entries' — the PyTCP
+    analogue of Linux 'ip addrlabel'. Entries are matched
+    most-specific-first, so order them longest-prefix-first.
+    The table MUST contain a ::/0 catch-all so 'lookup' stays
+    total; a table without one is rejected.
+    """
+
+    if not any(entry.network == Ip6Network("::/0") for entry in entries):
+        raise ValueError("policy table must contain a ::/0 catch-all entry so 'lookup' stays total")
+    global _active_policy_table
+    _active_policy_table = tuple(entries)
+
+
+def reset_policy_table() -> None:
+    """
+    Restore the RFC 6724 §10.3 default policy table, discarding
+    any operator override.
+    """
+
+    global _active_policy_table
+    _active_policy_table = DEFAULT_POLICY_TABLE

packages/pytcp/pytcp/tests/unit/protocols/ip6/test__ip6__policy_table.py

@@ -31,13 +31,17 @@
 ver 3.0.8
 """
 
+from typing import override
 from unittest import TestCase
 
-from net_addr import Ip6Address
+from net_addr import Ip6Address, Ip6Network
 from pytcp.protocols.ip6.ip6__policy_table import (
     DEFAULT_POLICY_TABLE,
     PolicyEntry,
+    get_policy_table,
     lookup,
+    reset_policy_table,
+    set_policy_table,
 )
 from pytcp.tests.lib.parameterized import parameterized_class
 
@@ -197,3 +201,104 @@ def test__lib__ip6_policy_table__catch_all_entry_present(self) -> None:
             (40, 1),
             msg="The ::/0 catch-all must have precedence 40 and label 1.",
         )
+
+
+class TestIp6PolicyTableOverride(TestCase):
+    """
+    The RFC 6724 §10.3 operator policy-table override tests.
+    """
+
+    @override
+    def setUp(self) -> None:
+        """
+        Restore the default policy table after every test so an
+        override cannot leak into a sibling test.
+        """
+
+        self.addCleanup(reset_policy_table)
+
+    def test__set_policy_table_overrides_lookup(self) -> None:
+        """
+        Ensure installing a custom policy table makes 'lookup' resolve a
+        destination's (precedence, label) from the custom table — an
+        operator override the source-selection rule-6 consumer reads live.
+
+        Reference: RFC 6724 §2.1 (Policy table is administrator-configurable).
+        """
+
+        set_policy_table(
+            (
+                PolicyEntry(network=Ip6Network("2001:db8::/32"), precedence=99, label=7),
+                PolicyEntry(network=Ip6Network("::/0"), precedence=40, label=1),
+            )
+        )
+
+        self.assertEqual(
+            lookup(Ip6Address("2001:db8::1")),
+            (99, 7),
+            msg="After an override, 'lookup' must resolve from the custom policy table.",
+        )
+
+    def test__reset_policy_table_restores_default(self) -> None:
+        """
+        Ensure 'reset_policy_table' restores the RFC §10.3 default table
+        after an operator override.
+
+        Reference: RFC 6724 §10.3 (Default policy table).
+        """
+
+        set_policy_table(
+            (
+                PolicyEntry(network=Ip6Network("2001:db8::/32"), precedence=99, label=7),
+                PolicyEntry(network=Ip6Network("::/0"), precedence=40, label=1),
+            )
+        )
+        reset_policy_table()
+
+        self.assertEqual(
+            lookup(Ip6Address("2001:db8::1")),
+            (40, 1),
+            msg="After reset, 'lookup' must resolve from the RFC default table again.",
+        )
+
+    def test__set_policy_table_rejects_missing_catch_all(self) -> None:
+        """
+        Ensure 'set_policy_table' rejects a table with no ::/0 catch-all
+        entry, since 'lookup' must stay total (every address must yield a
+        (precedence, label) pair without raising).
+
+        Reference: RFC 6724 §10.3 (::/0 default catch-all keeps lookup total).
+        """
+
+        with self.assertRaises(ValueError) as ctx:
+            set_policy_table((PolicyEntry(network=Ip6Network("2001:db8::/32"), precedence=99, label=7),))
+
+        self.assertIn(
+            "::/0",
+            str(ctx.exception),
+            msg="The rejection message must name the missing ::/0 catch-all requirement.",
+        )
+
+    def test__get_policy_table_returns_active_table(self) -> None:
+        """
+        Ensure 'get_policy_table' returns the currently-active table — the
+        default before any override, and the custom table after one.
+
+        Reference: PyTCP test infrastructure (no RFC clause).
+        """
+
+        self.assertEqual(
+            get_policy_table(),
+            DEFAULT_POLICY_TABLE,
+            msg="Before any override 'get_policy_table' must return the default table.",
+        )
+        custom = (
+            PolicyEntry(network=Ip6Network("2001:db8::/32"), precedence=99, label=7),
+            PolicyEntry(network=Ip6Network("::/0"), precedence=40, label=1),
+        )
+        set_policy_table(custom)
+        self.assertEqual(
+            get_policy_table(),
+            custom,
+            msg="After an override 'get_policy_table' must return the custom table.",
+        )