@push.rocks/smartnftables 2.6.0 → 3.0.0

package/changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2026-09-28 - 3.0.0
+
+### Breaking Changes
+
+- The schema-v2 `routerEgress` compiler now keeps private endpoints, directed rules and leased egress grants in named sets and maps behind a fixed set of rules, and every scope keeps its `publishedPorts` the same way (see Features). The policy API is additive and policy digests are unchanged, but the compiled graph of every `routerEgress` table and of every scope with publications changes: reconcile, inspection or release against such a table applied by 2.x returns `Conflict`, because the new engine does not adopt the old graph. Recover and release each such table with the exact previous engine and its retained intent and receipt, under a traffic fence, before upgrading. Tables of other scopes and without publications are unchanged.
+- Rebalance the atomic replacement budget inside the unchanged 320,000-byte batch: the complete target (rules, chains and sets at most 100,000 bytes, plus set elements) may take 212,000 bytes beside a 107,520-byte handle-only deletion of the previous graph, instead of two fixed 100,000-byte halves for rules and elements. The hard ceiling is Linux's `sendmsg` limit, the socket send buffer (`net.core.wmem_max` doubled, 425,984 bytes by default); 320,000 bytes fits any `wmem_max` of at least 160,016.
+- Raise the router's input bounds to 128 private endpoints and links, 1024 private rules and 1024 egress grants, and the publication bound of both scopes to 1024. Schema-v1 policies keep their bounds, digests and compiled bytes.
+
+### Features
+
+- Router: a node of 64 workloads, each with local DNS, public TCP and UDP egress, four platform endpoints and one to three publications, compiles about 66,000 rule bytes and 105,000 element bytes (89 such workloads fit), where 2.x held three. Private links, indices, names and source prefixes, directed rules, and per-kind and per-shape leased zone, return and flow maps, with the generation labels in two exact sets, replace the per-endpoint guard chains, per-rule grants, per-grant classifiers and admissions and the per-generation state chains; every lookup keeps the operands the rules compared, a key's link index is proven with the interface name through `private_link`, and a decision corpus of about 133,000 packets frozen from the 2.6.0 compiler is reproduced exactly. Owner verification admits absence (inverted) lookups and exact maps, and interval elements without a distinct last key.
+- Add published port ranges to both hops of a schema-v2 publication: an optional `hostPortEnd` on `hostTransit.publishedPorts` and `transitPortEnd` on `routerEgress.publishedPorts` publish `port..end` with every port kept (the inside port must equal the first port). A range compiles to one interval match per classification, translation and admission and to address-only destination NAT, so it costs the same operations as one port. Inverted and one-port ranges, a range with a differing inside port, overlaps between publications of one protocol and overlaps with a leased source-port range on the translated address are refused.
+- Add `symmetric` publications on both hops: the workload may open flows from its published address and port(s) toward unprotected space, NEW (a SYN-only TCP opening) or ESTABLISHED with ESTABLISHED replies, source-translated to the transit address and published transit port in the router and to `hostIp` and the published uplink port on the host, so outbound flows leave from the port clients reach. The admissions follow the capture barrier, so the protected union stays denied; a symmetric publication's inside ports may not overlap another publication's on the same address or, on the host, a leased range of its target address.
+- Compile every publication, of both hops, as elements of CONSTANT concatenated interval sets and maps (the kernel's pipapo backend) behind a constant number of rules: at most eleven rules and four sets on the host and thirteen rules and six sets in the router, whatever the number of publications, instead of four and six rules per publication. Destination NAT is a map lookup (to address and port for one port, to the address alone for a range) and symmetric source NAT a map lookup to the outside address and port span. Owner verification now admits interval and map sets, reads back their concatenation, every element's bounds and data, and map lookups with their data register, so apply, inspection, adoption and recovery reject a changed element like a changed rule. Absent and empty publications, `hostPortEnd`, `transitPortEnd` and `symmetric` (and `symmetric: false`) keep the previous canonical policy and digest, and a scope without publications keeps its compiled bytes; a scope with publications compiles a different graph for the same digest.
+
+### Maintenance
+
+- Release tooling: pnpm 12.5.1, `@git.zone/cli` 7.3.0, `@git.zone/tsrust` 1.15.1, `@git.zone/tstest` 6.3.2, `@git.zone/tsrun` 3.0.1, `@types/node` 26.6.2 (pnpm 12.6.0 and `@types/node` 26.6.3 stay out until they clear the seven-day rule).
+
 ## 2026-09-25 - 2.6.0
 
 ### Features

package/dist_rust/smartnftables_linux_amd64_musl.tsrust-build.json

@@ -1,13 +1,13 @@
 {
   "format": "tsrust.build-provenance.v2",
-  "binarySha256": "8b0883d60ba14c1971ce50bd7ec45ea4cbb8a79c292e9063166fed168779dd52",
+  "binarySha256": "17c4308039280f584cd51d6cf9030e3c4512746d316561925b6da95bb3c67ff8",
   "buildInfo": {
     "projectName": "@push.rocks/smartnftables",
-    "projectVersion": "2.6.0",
-    "gitCommit": "8032aac9d7b1b78650f0947574e5aab783b2d5db",
+    "projectVersion": "3.0.0",
+    "gitCommit": "61c5a8be9c99a83cecde6509fb31c47f43e15bff",
     "gitDirty": false,
-    "builtAt": "2026-09-25T13:42:00.180Z",
-    "tsrustVersion": "1.15.0",
+    "builtAt": "2026-09-28T00:27:05.031Z",
+    "tsrustVersion": "1.15.1",
     "binary": "smartnftables",
     "target": "linux_amd64_musl"
   }

package/dist_rust/smartnftables_linux_arm64_musl.tsrust-build.json

@@ -1,13 +1,13 @@
 {
   "format": "tsrust.build-provenance.v2",
-  "binarySha256": "86d2a679f4f1968b9ae9e0a3681572f5c4a6dc913993747abf5422f3adf4916b",
+  "binarySha256": "3756fe460edc3bdea00c7f598a683081d8238f5172dad9776304a030508d4276",
   "buildInfo": {
     "projectName": "@push.rocks/smartnftables",
-    "projectVersion": "2.6.0",
-    "gitCommit": "8032aac9d7b1b78650f0947574e5aab783b2d5db",
+    "projectVersion": "3.0.0",
+    "gitCommit": "61c5a8be9c99a83cecde6509fb31c47f43e15bff",
     "gitDirty": false,
-    "builtAt": "2026-09-25T13:42:10.633Z",
-    "tsrustVersion": "1.15.0",
+    "builtAt": "2026-09-28T00:27:15.164Z",
+    "tsrustVersion": "1.15.1",
     "binary": "smartnftables",
     "target": "linux_arm64_musl"
   }

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartnftables',
-    version: '2.6.0',
+    version: '3.0.0',
     description: 'A TypeScript module for managing nftables rules including NAT, firewall, and rate limiting with a high-level API.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSwyQkFBMkI7SUFDakMsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLG1IQUFtSDtDQUNqSSxDQUFBIn0=

package/dist_ts/managed.egress.types.d.ts

@@ -65,9 +65,14 @@ export interface IManagedNftEgressGenerationV2 extends IManagedNftHandoffAllocat
  * `transitSourceAddress:transitPort`, this translates on to the workload. */
 export interface IManagedNftRouterPublishedPortV2 {
     protocol: 'tcp' | 'udp';
-    /** Published handoff port, 1–65535 and unique per protocol across the scope.
-     * It is the `targetPort` of the matching host-transit publication. */
+    /** Published handoff port, 1–65535; published ports never overlap per protocol across the
+     * scope. It is the `targetPort` of the matching host-transit publication. */
     transitPort: number;
+    /** Optional last port of a published range `transitPort..transitPortEnd`, greater than
+     * `transitPort`. A range keeps every port, so `endpointPort` must equal `transitPort`; like one
+     * port it is one interval set element per set, and its translation keeps the port. Absent for
+     * one port, which is its only canonical form. */
+    transitPortEnd?: number;
     endpointPort: number;
     /** Exact current workload endpoint address behind one veth endpoint of this
      * scope. Never a router-local address, a gateway or a platform endpoint. */
@@ -75,6 +80,12 @@ export interface IManagedNftRouterPublishedPortV2 {
     /** Exact leased transit source address of one current generation, present on
      * `handoff`. No wildcard, secondary-address or route inference. */
     transitSourceAddress: string;
+    /** Optional: the workload may open flows from `endpointAddress` and its published endpoint
+     * port(s) toward unprotected space, source-translated to `transitSourceAddress` and the
+     * published transit port (a range keeps the port). The protected union stays denied, and its
+     * endpoint ports may not overlap another publication's on the same address. Absent and
+     * `false` are the same canonical policy. */
+    symmetric?: boolean;
 }
 /** One exact host-origin flow: the node's own host network namespace dials one port of one local
  * workload at its lease address, from the transit host address of the current handoff. Compile the
@@ -137,13 +148,24 @@ export interface IManagedNftRouterEgressScopeV2 {
 /** One inbound uplink publication, compiled inside the same host-transit generation. */
 export interface IManagedNftPublishedPortV2 {
     protocol: 'tcp' | 'udp';
-    /** Published uplink port, 1–65535 and unique per protocol across the scope. */
+    /** Published uplink port, 1–65535; published ports never overlap per protocol across the scope. */
     hostPort: number;
+    /** Optional last port of a published range `hostPort..hostPortEnd`, greater than `hostPort`.
+     * A range keeps every port, so `targetPort` must equal `hostPort`; like one port it is one
+     * interval set element per set, and its translation keeps the port. Absent for one port, which
+     * is its only canonical form. */
+    hostPortEnd?: number;
     targetPort: number;
     /** Exact leased transit source address of one current allocation; it selects the handoff. */
     targetAddress: string;
     /** Exact current uplink address that publishes this port. No wildcard or route inference. */
     hostIp: string;
+    /** Optional: flows from `targetAddress` and the published target port(s) may leave through the
+     * uplink toward unprotected space, source-translated to `hostIp` and the published uplink port
+     * (a range keeps the port). The protected union stays denied, its target ports may not fall in
+     * a leased range of `targetAddress` or overlap another publication's. Absent and `false` are
+     * the same canonical policy. */
+    symmetric?: boolean;
 }
 /** Shared-host capture barrier and explicit outer SNAT; Docker forwarding remains a separate owner. */
 export interface IManagedNftHostTransitScopeV2 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartnftables",
-  "version": "2.6.0",
+  "version": "3.0.0",
   "private": false,
   "description": "A TypeScript module for managing nftables rules including NAT, firewall, and rate limiting with a high-level API.",
   "main": "dist_ts/index.js",
@@ -9,12 +9,12 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/cli": "7.2.2",
+    "@git.zone/cli": "7.3.0",
     "@git.zone/tsbuild": "^5.0.0",
-    "@git.zone/tsrun": "^3.0.0",
-    "@git.zone/tsrust": "1.15.0",
-    "@git.zone/tstest": "6.2.0",
-    "@types/node": "26.6.1",
+    "@git.zone/tsrun": "^3.0.1",
+    "@git.zone/tsrust": "1.15.1",
+    "@git.zone/tstest": "6.3.2",
+    "@types/node": "26.6.2",
     "typescript": "^7.0.2"
   },
   "dependencies": {

package/readme.md

@@ -264,8 +264,8 @@ allocation-pool guard policy kinds.
 
 | V2 scope | Required authority and behavior |
 | --- | --- |
-| `routerEgress` | Private `endpoints` and `rules`, one exact `links` binding per endpoint, a separate veth `handoff`, `protection`, and active `generations`. Private veth/TUN/local DNS and egress share one table so terminal private denial cannot override a separate egress table. Optional `publishedPorts` add the inbound second hop from the handoff to a workload endpoint; both directions are classified into the default conntrack zone ahead of every leased classifier, so a published endpoint port is dedicated to its publication and never becomes leased egress. Optional `hostGrants` forward exact host-origin flows from the handoff to a workload endpoint. Optional `workloadGrants` let one workload open one exact port of another, one way. |
-| `hostTransit` | Exact handoff `link`/`allocations` pairs, complete `protection`, an explicit veth or Ethernet `uplink`, and its current `snatAddress`. It checks each handoff's leased source address and protocol/port range, default conntrack zone, direction, uplink, and protected destinations before outer SNAT. Optional `publishedPorts` add inbound uplink destination NAT inside the same generation. Optional `hostGrants` let the host's own address on a handoff dial exact workload ports. Optional `localPlatformEndpoints` serve platform endpoints on the host's own addresses to leased flows. |
+| `routerEgress` | Private `endpoints` and `rules`, one exact `links` binding per endpoint, a separate veth `handoff`, `protection`, and active `generations`. Private veth/TUN/local DNS and egress share one table so terminal private denial cannot override a separate egress table. Optional `publishedPorts` add the inbound second hop from the handoff to a workload endpoint, one port or a port range; both directions are classified into the default conntrack zone ahead of every leased classifier, so a published endpoint port is dedicated to its publication and never becomes leased egress. A `symmetric` publication also lets the workload open flows from its published ports. Optional `hostGrants` forward exact host-origin flows from the handoff to a workload endpoint. Optional `workloadGrants` let one workload open one exact port of another, one way. |
+| `hostTransit` | Exact handoff `link`/`allocations` pairs, complete `protection`, an explicit veth or Ethernet `uplink`, and its current `snatAddress`. It checks each handoff's leased source address and protocol/port range, default conntrack zone, direction, uplink, and protected destinations before outer SNAT. Optional `publishedPorts` add inbound uplink destination NAT inside the same generation, one port or a port range, and a `symmetric` publication also carries the workload's own flows from its published ports out through the uplink. Optional `hostGrants` let the host's own address on a handoff dial exact workload ports. Optional `localPlatformEndpoints` serve platform endpoints on the host's own addresses to leased flows. |
 | `allocationPoolGuard` | An authenticated `authorityDigest` and complete current allocation-pool `prefixes`. Installs host-wide IPv4 destination denial before any handoff exists, without link, uplink or SNAT dependencies. Optional `hostGrants` are its only exceptions. Optional `localTcpPortOwners` restrict loopback TCP ports to one local user each. |
 
 `allocationPoolGuard` accepts 1–64 canonical, disjoint RFC1918 prefixes. Supply
@@ -317,7 +317,8 @@ handoffs, unmatched handoff traffic and IPv6 forwarding are denied.
 
 `hostTransit.publishedPorts` is optional. Absent and empty are the same canonical
 policy, so an unpublished scope keeps its exact previous digest and compiled bytes.
-Each entry is `{ protocol, hostPort, targetPort, targetAddress, hostIp }`. `hostIp`
+Each entry is `{ protocol, hostPort, targetPort, targetAddress, hostIp }`, with an
+optional `hostPortEnd` and an optional `symmetric`. `hostIp`
 must be an exact current uplink address, which rtnetlink verifies at apply, recovery
 and inspection; there is no wildcard, secondary-link or default-route inference.
 `targetAddress` must be a current leased `transitSourceAddress` of one allocation,
@@ -328,21 +329,59 @@ including across uplink addresses, and a port published on the `snatAddress` may
 fall inside any leased outbound source-port range of the same protocol, because outer
 SNAT translates to that same address.
 
-A publication compiles inside the generation: one destination NAT rule in this
-table's own prerouting `nat` chain at priority -100, plus three forward admissions
-placed ahead of the capture barrier — original direction NEW and ESTABLISHED, with
-opening TCP restricted to SYN with FIN/RST/ACK clear, and the ESTABLISHED reply.
-Every admission checks both links, the conntrack protocol, the default zone, the
-direction, the translated current address/port and the original conntrack
-destination, so foreign NAT cannot borrow the exception for another flow. Published
-traffic is not source-translated, so the workload observes the actual client address.
-The chain, its translation and its admissions are created, replaced and deleted with
-the generation: a target without the entry, a failed batch, or release removes them,
-and a caller never needs a separate teardown.
-
-Input bounds are 64 entries, but the atomic graph reserve binds first. A publication
-costs four operations and about 6,000 bytes, so roughly a dozen fit beside a small
-host-transit graph and `prepare()` rejects an excessive set before any kernel work.
+`hostPortEnd` publishes the range `hostPort..hostPortEnd`. It must be greater than
+`hostPort`, and `targetPort` must equal `hostPort`: a range keeps every port, so port
+`p` of the uplink reaches port `p` of `targetAddress`. One port has exactly one
+canonical form, without `hostPortEnd`. Ranges follow the same rules as single ports:
+no two publications of one protocol overlap anywhere in the scope, and no published
+port on the `snatAddress` falls inside a leased range. A range translates the
+address only, which never changes a port.
+
+Publications are set elements, not rules. The generation compiles CONSTANT named
+sets and maps of concatenated fields in which the port fields are inclusive
+intervals (the kernel's pipapo backend), so one element holds one port or a whole
+range: `published_port` maps a one-port publication's uplink address, protocols and
+port to its target address and port, `published_address` maps a range to its target
+address alone, and `published_forward` holds every publication's inbound tuple. A
+constant number of rules looks them up whatever the number of publications: one
+destination NAT rule per map in this table's own prerouting `nat` chain at priority
+-100, and four forward admissions ahead of the capture barrier — the ESTABLISHED
+original direction, a NEW opening per protocol with opening TCP restricted to SYN
+with FIN/RST/ACK clear, and the ESTABLISHED reply. Every rule checks the uplink, the
+default zone and the direction, and every key carries the exact handoff (index and
+name), the packet and conntrack protocols, the translated current address and port
+and the original conntrack destination, so foreign NAT cannot borrow the exception
+for another flow. Published traffic is not source-translated, so the workload
+observes the actual client address. The chain, its sets, its translations and its
+admissions are created, replaced and deleted with the generation: a target without
+the entry, a failed batch, or release removes them, and a caller never needs a
+separate teardown. Owner verification reads every set back with its description,
+every element with its interval bounds and map data, and every lookup with its
+registers, so apply, inspection, adoption and recovery reject a changed element
+exactly as they reject a changed rule.
+
+Without `symmetric`, a publication carries inbound flows only: a flow the workload
+opens from its target address and port toward the uplink is denied. With `symmetric:
+true`, a flow from exactly `targetAddress` and the published target port(s) on the
+exact handoff may leave through the uplink, NEW (a TCP opening only with SYN) or
+ESTABLISHED, with its ESTABLISHED replies, and outer source NAT translates it to
+`hostIp` and the published uplink port. These flows are elements of one more map,
+`published_symmetric`, keyed on the handoff, protocols and the live and original
+source and holding the uplink address and port span; four admissions look it up as a
+set and one postrouting rule translates through it. The workload's outbound flows therefore leave
+from the same address and port its clients reach, as Docker host-mode NAT kept them;
+a range keeps each port unless the host itself already holds that exact tuple on
+`hostIp`. The admissions follow the capture barrier, so every protected current or
+original destination, the platform endpoints included, stays denied. A symmetric
+target port may not fall inside a leased range of `targetAddress`, and may not overlap
+the target ports of another publication of the same address and protocol. Absent and
+`false` are the same canonical policy, digest and compiled graph.
+
+Input bounds are 1024 entries. The rule graph does not grow with them: with every
+kind of publication present the host compiles at most eleven rules and four sets,
+about 13,400 bytes of the 100,000-byte rule reserve, and each publication costs
+about 150 to 300 bytes of set elements, which share the target budget described
+under host grants. 64 symmetric ranges take about 19,600 element bytes.
 The caller still owns the route to `targetAddress` through that handoff, the
 workload listener, and every other packet owner on the host. As with leased egress,
 an ACCEPT here cannot override Docker's independent FORWARD DROP; the
@@ -366,7 +405,8 @@ There is no broad ESTABLISHED/RELATED bypass.
 `routerEgress.publishedPorts` is optional and is the second hop of a published
 host port. Absent and empty are the same canonical policy, so an unpublished scope
 keeps its exact previous digest and compiled bytes. Each entry is `{ protocol,
-transitPort, endpointPort, endpointAddress, transitSourceAddress }`.
+transitPort, endpointPort, endpointAddress, transitSourceAddress }`, with an
+optional `transitPortEnd` and an optional `symmetric`.
 `transitSourceAddress` must be a current leased generation address that is present
 on `handoff`, which rtnetlink verifies at apply, recovery and inspection; the
 handoff can carry several current leased addresses, so the arrival address is
@@ -379,11 +419,24 @@ published exactly once across the scope, and a published port may not fall insid
 any leased outbound source-port range of the same protocol on that transit address,
 because source NAT translates to that same address.
 
-A publication compiles inside the generation: one destination NAT rule in this
-table's own prerouting `nat` chain at priority -100, two raw classifications, and
-three forward admissions placed ahead of the capture barrier — original direction
-NEW and ESTABLISHED, with opening TCP restricted to SYN with FIN/RST/ACK clear,
-and the ESTABLISHED reply. The handoff ingress classification precedes the
+`transitPortEnd` publishes the range `transitPort..transitPortEnd`, the second hop of
+a host range. It must be greater than `transitPort`, and `endpointPort` must equal
+`transitPort`, so every port keeps its number on both hops; one port has exactly one
+canonical form, without `transitPortEnd`. No two publications of one protocol overlap
+anywhere in the scope, and no published port falls inside a leased range of its
+transit address. The destination NAT of a range translates the address only.
+
+Publications are set elements here too: `published_arrival` (protocol, transit
+address and port), `published_endpoint` (workload link, protocol, address and port,
+the union of every publication's workload ports as disjoint canonical intervals),
+the `published_port` and `published_address` translation maps and
+`published_forward`, with the port fields as inclusive intervals. A constant number
+of rules looks them up whatever the number of publications: one destination NAT
+rule per map in this table's own prerouting `nat` chain at priority -100, two raw
+classifications, and four forward admissions placed ahead of the capture barrier —
+the ESTABLISHED original direction, a NEW opening per protocol with opening TCP
+restricted to SYN with FIN/RST/ACK clear, and the ESTABLISHED reply. The handoff
+ingress classification precedes the
 barrier's protected-source denial, because the uplink or management network that
 reaches a published port is itself protected space. The endpoint ingress
 classification matches the exact workload link, address and published endpoint
@@ -393,24 +446,47 @@ would otherwise carry the workload's published packets into that generation, whe
 the publication's flow does not exist. Both classifications match the arriving
 tuple only, set no generation zone and leave the flow in the default conntrack
 zone. The private anti-spoof guards still run first, and every admission checks
-both links, the conntrack protocol, the default zone, the direction, the
-translated current address/port and the original conntrack destination.
+the handoff, the default zone and the direction, and looks up the exact workload
+link (index and name), both protocols, the translated current address/port and the
+original conntrack destination.
 
-A published `endpointPort` is therefore dedicated to its publication: a new
+A published endpoint port is therefore dedicated to its publication: a new
 outbound flow that the workload opens from that exact address and port on that
-exact link stays in the default zone too and is not translated by the leased
-outbound source NAT. Published traffic is not source-translated on either hop, so
-the workload observes the actual client address. The chain, its translation, its
-classifications and its admissions are created, replaced and deleted with the
-generation: a target without the entry, a failed batch, or release removes them.
-
-Input bounds are 64 entries, but the atomic graph reserve binds first. A router
-publication costs six operations and about 7,600 bytes, so a combined
-two-endpoint router policy leaves room for roughly five, and `prepare()` rejects an
-excessive set before any kernel work. The caller still owns both hops: the exact
-matching `hostTransit` publication, the route to the workload through this router,
-the workload listener and every other packet owner. A publication grants no egress;
-outbound flows still need their leased grants.
+exact link stays in the default zone too and is never translated by the leased
+outbound source NAT. Without `symmetric` such a flow is denied. Inbound published
+traffic is not source-translated on either hop, so the workload observes the actual
+client address. The chain, its sets, its translations, its classifications and its
+admissions are created, replaced and deleted with the generation: a target without
+the entry, a failed batch, or release removes them.
+
+With `symmetric: true` the workload may open flows from exactly `endpointAddress`
+and the published endpoint port(s) on its exact link toward the handoff, NEW (a TCP
+opening only with SYN) or ESTABLISHED, with their ESTABLISHED replies, and source
+NAT translates them to `transitSourceAddress` and the published transit port. With
+the matching symmetric `hostTransit` publication the flow reaches the uplink from
+`hostIp` and the published uplink port, the same address and port its clients
+reach, as Docker host-mode NAT kept it; a range keeps each port unless that exact
+tuple is already taken on the translated address. These flows are elements of the
+`published_symmetric` map, keyed on the workload link, protocols and the live and
+original source and holding the transit address and port span, behind four
+admissions and one postrouting translation. Both directions are already in the
+default zone through the publication's endpoint and handoff classifications, so no
+leased classifier can capture them. The admissions follow the capture barrier, so
+every protected current or original destination, the platform endpoints included,
+stays denied; outbound flows anywhere else still need their leased grants. The
+endpoint ports of a symmetric publication may not overlap the endpoint ports of
+another publication of the same address and protocol, since each flow has exactly
+one published source. Absent and `false` are the same canonical policy, digest and
+compiled graph.
+
+Input bounds are 1024 entries. The rule graph does not grow with them: with every
+kind of publication present the router compiles at most thirteen rules and six sets,
+about 15,100 bytes of the 100,000-byte rule reserve, and each publication costs
+about 250 to 450 bytes of set elements, which share the target budget with the
+router's endpoints, rules and grants. 64 symmetric ranges take about 28,000 element
+bytes. The caller still owns both hops: the exact matching `hostTransit`
+publication, the route to the workload through this router, the workload listener
+and every other packet owner.
 
 #### Host grants
 
@@ -466,7 +542,7 @@ foreign set exactly as they reject a changed rule; a bound CONSTANT set also
 refuses element changes from any other socket.
 
 Absent and empty are the same canonical policy, so a scope without grants keeps its
-exact previous digest and compiled bytes and has no set. Withdrawing a grant is an
+exact previous digest and compiled bytes and has no host grant set. Withdrawing a grant is an
 ordinary atomic replacement: the batch deletes the previous rules, chains and sets
 by handle and creates the complete target, so a target without the entry, a failed
 batch or release removes it, and an established flow stops with it. Apply grants
@@ -531,9 +607,9 @@ tuple in the CONSTANT set `workload_grant`, so a spoofed, renamed or translated
 never matches and the destination can never open toward the source. Endpoint prefixes
 are protected, so both directions stay in the default zone ahead of every leased
 classifier. Owner verification reads both sets back element by element. Up to 1024
-grants fit; the sets share the scope's 100,000-byte element budget with `hostGrants`,
-so 1024 of each do not fit together and preparation refuses that before any kernel
-work. Absent and empty are the same canonical policy, digest and compiled bytes, and
+grants fit; the sets share the scope's target budget with `hostGrants` and every
+other set, and 1024 of each fit together beside the reference router; a scope
+beyond the budget is refused before any kernel work. Absent and empty are the same canonical policy, digest and compiled bytes, and
 withdrawal is an ordinary atomic replacement that also stops established flows.
 
 These flows need no private `rules`. A private rule is stateless: answering through
@@ -588,13 +664,20 @@ applied, retained, recovered and released with the rest of the guard's table; af
 a reboot the caller applies its retained intent again, like every other member.
 
 Input bounds are 1024 grants per scope, the maximum a network projection carries.
-Elements have their own 100,000-byte budget beside the 100,000-byte rule graph, and
-are sent 256 to a message. At 1024 grants the reference router needs about 94 KB
-of elements (two sets), host transit about 66 KB and the guard about 45 KB. A
-replacement batch — handle-only deletion of a previous maximum graph, a maximum
-rule graph and maximum elements — stays below 320,000 bytes, which the kernel
-accepts with any `net.core.wmem_max` of at least 160,016 (the Linux default is
-212,992). The private facade IPC carries up to three complete policies in one
+Elements are sent 256 to a message. At 1024 grants the reference router needs about
+98 KB of elements (two sets), host transit about 66 KB and the guard about 45 KB.
+
+Every replacement is one nfnetlink batch in one `sendmsg`, and Linux refuses a
+netlink message larger than the socket send buffer: the requested 1 MiB `SO_SNDBUF`
+is clamped to `net.core.wmem_max` and doubled, 425,984 bytes with the Linux default
+of 212,992. That is the hard ceiling. This package bounds a batch at 320,000 bytes,
+which fits every `wmem_max` of at least 160,016, and splits it: at most 64 bytes of
+batch framing, at most 107,520 bytes for the handle-only deletion of the previous
+graph (fewer than 768 rules, chains and sets of at most 140 bytes each), and
+212,000 bytes for the complete target, of which rules, chains and sets may take at
+most 100,000 and set elements the rest. Scopes that grow with their inputs keep
+those inputs in set elements, so the element share grows where the rule share
+shrinks; `prepare()` refuses a target beyond either bound before any kernel work. The private facade IPC carries up to three complete policies in one
 status and is bounded at 1,048,576 bytes per line; the facade captures at most
 1,000,000 JSON bytes and 65,536 values per request or result. The caller owns the host route
 to the workload through the handoff, selecting the transit host address as the
@@ -602,18 +685,56 @@ socket's source, the workload listener and every other packet owner.
 
 Active overlapping classifiers, duplicate zones/labels and conflicting handoff
 allocations reject. Empty router generations retain private routing while denying
-egress. Input bounds include 32 private endpoints, 128 private rules, 32 active
-generations, 128 total egress grants, 128 protected prefixes, 96 platform endpoints,
-16 ranges per allocation, and 32 host handoffs/active allocations. The complete
-compiled graph still must fit 768 operations and 100,000 bytes; cross-products can
-reach that limit before individual input limits. Exhausted source-port ranges
-drop new flows rather than allocate outside the lease.
-
-The router compiler shares original-direction connection-state and label checks
-per generation and protocol. Each jump still checks the complete current/original
-tuple, links, zone and direction; replies and source NAT keep their exact checks.
-A combined two-endpoint policy with six private rules, five protected prefixes and
-six workload/router grants fits the existing atomic graph limit.
+egress. Router input bounds are 128 private endpoints and links, 1024 private
+rules, 32 active generations and 1024 total egress grants; other bounds include 128
+protected prefixes, 96 platform endpoints, 16 ranges per allocation, and 32 host
+handoffs/active allocations. The complete target must fit the budget above; the
+router's rules grow only with its protected prefixes, so its elements bind first.
+Exhausted source-port ranges drop new flows rather than allocate outside the lease.
+
+The router compiles its private endpoints, directed rules and leased grants into
+named sets and maps behind a fixed set of rules, whatever the number of workloads:
+- `private_link` holds every endpoint link (index and name) and the absent
+  interface of router-local traffic; `private_index` and `private_name` hold every
+  endpoint index and name for the terminal denials, either alone enough to deny;
+  `private_source` holds each link index with its source prefixes. The anti-spoof
+  guard drops a packet on an endpoint link whose address is not one of its
+  prefixes, and anything but IPv4 there.
+- `private_any` and `private_port` hold the directed rules: incoming and outgoing
+  link index (0 for the router itself), addresses, and for a transport rule the
+  protocol and ports.
+- Per kind (platform ahead of the protected barrier, public behind it) and per
+  shape (whether the grant names a source port), `leased_*_zone` maps a workload
+  or router flow's link, protocol and tuple to its generation zone before conntrack,
+  `leased_*_return` maps a translated return to its zone, and `leased_*_flow` maps
+  the link, both protocols, the live and originally tracked tuple and the zone to
+  the grant's source NAT; the filter admissions look it up as a set.
+  `leased_label` holds each generation's zone and label, and `leased_generation`
+  maps a zone to the label a fresh flow receives.
+A key's link index names its link because the rule also finds the interface's
+index and name in `private_link`, whose indices are unique. Every element is
+checked, like every rule, on apply, inspection, adoption and recovery. A decision
+corpus of about 133,000 packets across five router fixtures, frozen from the
+per-rule compiler of 2.6.0, is reproduced exactly by the set-backed compiler.
+
+A router of 64 workloads, each with local DNS, public TCP and UDP egress, grants to
+four platform endpoints and one to three publications, compiles about 66,000 rule
+bytes and 105,000 element bytes; 89 such workloads fit the target budget:
+
+| Workloads | Router rules | Router elements | Host rules | Host elements |
+| --- | --- | --- | --- | --- |
+| 1 | 65,820 | 4,968 | 42,944 | 1,128 |
+| 8 | 65,820 | 16,056 | 42,944 | 2,528 |
+| 32 | 65,820 | 54,072 | 42,944 | 7,328 |
+| 64 | 65,820 | 104,760 | 42,944 | 13,728 |
+
+**Upgrading from 2.x:** version 3 changes the compiled identity of every schema-v2
+`routerEgress` table and of every scope with `publishedPorts`, while their policy
+digests stay unchanged. Reconcile or release against such a table applied by 2.x
+returns `Conflict`: the new engine cannot adopt the old graph. Recover and release
+each such table with the exact previous engine and its retained intent and
+receipt, under the same traffic fence as below, before upgrading; tables of other
+scopes and without publications are unchanged.
 
 **Upgrading from 1.x:** version 2 changes the compiled identity of schema-v2
 `routerEgress` tables. Retained router tables and their receipts cannot be adopted
@@ -732,6 +853,27 @@ A client whose source port equals a leased grant's destination port on that gran
 public address completes the published TCP handshake and receives its UDP reply
 from the published address, so the leased classifiers of the same generation cannot
 capture the workload's published packets.
+Published ranges and symmetric publications are qualified across both hops in the
+same topology, with every publication a set element whose kernel dump matches the
+compiled sets and maps: the first, middle and last port of a UDP range reach their listeners
+with the client address preserved and answer from the published address, the ports
+just outside the range stay dark against pre-policy positive controls, symmetric UDP
+from a range port and from the signalling port and symmetric TCP from the signalling
+port reach the uplink peer from the published address with the same port, a later
+request from that peer reaches the workload on the same flow, the plain publication's
+workload port opens nothing, symmetric flows into the protected union stay denied
+against a pre-policy positive control, leased egress keeps its leased range, and the
+range goes dark with release.
+A 64-workload router is qualified in one batch, every workload in its own namespace
+with local DNS, public TCP and UDP egress, four platform endpoints and a
+publication, the first with the SIP shape: the kernel dumps every private, leased
+and published element and the owner verifies it, and on the first, middle and last
+workload local DNS answers, public UDP egress leaves from the leased range, UDP and
+TCP platform endpoints answer through both hops, the publication reaches its
+listener with the client address preserved, and another workload, a protected
+address outside the platform endpoints and an ungranted platform port stay denied
+against pre-policy positive controls, as does another workload's source address.
+The router compiles 82 rules for the 64 workloads.
 Host grants are qualified across all three tables in the same four-namespace
 topology with leased public egress on every port of both protocols and 1024 grants
 in every scope: a member far from the probed tuples passes, the tuple just outside