gowalk-cicd 1.0.150 → 1.0.152

package/CLAUDE.md

@@ -441,6 +441,12 @@ node /path/to/gowalk-cicd/bin/cli.mjs
 
 ## Scoped backend diagnosis
 
+Backend network preparation and `operation: network-diagnostics` follow `docs/BACKEND_NETWORKS.md`.
+Keep allocation inside verified existing daemon pool bases, preserve all existing and authored networks,
+and hold the host allocation lock only through creation/readback. Never restart/reconfigure Docker,
+prune networks, or invent a free private range. Remote modules and source facts remain Python 3.8 compatible.
+Tests include the explicit CI-only six-project Docker coexistence proof; ordinary local tests contact no daemon.
+
 The existing backend action accepts `operation: identity-diagnostics` with a UTC `diagnostic-since`
 from the last24hours and exact `diagnostic-service` (default`api`). It performs no deploy, rsync,
 Compose mutation or environment read. `identity_diagnostics.py` uses the existing CI SSH binding,

package/README.md

@@ -156,6 +156,10 @@ in App Store Connect; see [First-time app setup](#first-time-app-setup).
 
 ## Backend deploy (Python + Postgres, Docker)
 
+New ordinary Compose projects receive small isolated networks inside Docker's verified existing pools.
+Existing/custom/external networks and authored IPAM retain their contracts. Read-only
+`network-diagnostics` uses the same deployment identity; see [capacity and diagnosis](docs/BACKEND_NETWORKS.md).
+
 When a repo carries a Dockerized backend, the installer also vendors a backend deploy path:
 `.github/actions/backend-app/` and `.github/workflows/deploy-backend.yml`. A
 mobile-only repo is unaffected (the backend path is not installed).

package/action/.daemux-version

@@ -1 +1 @@
-1.0.150
+1.0.152

package/android-action/.daemux-version

@@ -1 +1 @@
-1.0.150
+1.0.152

package/backend-action/.daemux-version

@@ -1 +1 @@
-1.0.150
+1.0.152

package/backend-action/action.yml

@@ -7,7 +7,7 @@ description: >
 
 inputs:
   operation:
-    description: deploy (default) or identity-diagnostics (read-only fixed Firebase refusal labels).
+    description: deploy (default), identity-diagnostics, or read-only network-diagnostics.
     required: false
     default: deploy
   diagnostic-service:
@@ -93,7 +93,7 @@ runs:
       env:
         OPERATION: ${{ inputs.operation }}
       run: |
-        case "$OPERATION" in deploy|identity-diagnostics) ;; *) exit 1;; esac
+        case "$OPERATION" in deploy|identity-diagnostics|network-diagnostics) ;; *) exit 1;; esac
 
     - name: Validate inputs
       if: inputs.operation == 'deploy'
@@ -186,6 +186,14 @@ runs:
           "${{ github.action_path }}/edge_inputs.py" \
           "${{ github.action_path }}/edge_vhost.py" \
           "${{ github.action_path }}/edge_health.py" \
+          "${{ github.action_path }}/identity_diagnostics.py" \
+          "${{ github.action_path }}/network_runtime.py" \
+          "${{ github.action_path }}/network_contract.py" \
+          "${{ github.action_path }}/network_inventory.py" \
+          "${{ github.action_path }}/network_owned_inventory.py" \
+          "${{ github.action_path }}/network_readback.py" \
+          "${{ github.action_path }}/network_pools.py" \
+          "${{ github.action_path }}/network_prepare.py" \
           "${{ github.action_path }}/deploy_evidence.sh" \
           "${{ inputs.ssh-user }}@${{ inputs.host }}:$DEST/"
 
@@ -248,6 +256,31 @@ runs:
         path: ${{ steps.identity_diagnostics.outputs.result }}
         if-no-files-found: error
 
+    - name: Read backend network diagnostics
+      id: network_diagnostics
+      if: inputs.operation == 'network-diagnostics'
+      shell: bash
+      env:
+        DIAGNOSTIC_APP: ${{ inputs.app-name }}
+        DIAGNOSTIC_HOST: ${{ inputs.host }}
+        DIAGNOSTIC_USER: ${{ inputs.ssh-user }}
+      run: |
+        RESULT_DIR="$(mktemp -d "$RUNNER_TEMP/backend-network-diagnostics.XXXXXX")"
+        echo "result=$RESULT_DIR/result.json" >> "$GITHUB_OUTPUT"
+        python3 "${{ github.action_path }}/network_diagnostics.py" \
+          --app "$DIAGNOSTIC_APP" --host "$DIAGNOSTIC_HOST" --user "$DIAGNOSTIC_USER" \
+          --output "$RESULT_DIR/result.json"
+
+    - name: Retain backend network diagnostics
+      if: always() && inputs.operation == 'network-diagnostics'
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+      env:
+        NODE_OPTIONS: --require "${{ github.action_path }}/scripts/artifact_env.cjs"
+      with:
+        name: backend-network-diagnostics-${{ github.job }}-${{ github.run_attempt }}
+        path: ${{ steps.network_diagnostics.outputs.result }}
+        if-no-files-found: error
+
     - name: Cleanup key
       if: always()
       shell: bash

package/backend-action/network_contract.py

@@ -0,0 +1,119 @@
+"""Select only ordinary, automatically named Compose networks; never rewrite authored IPAM."""
+import hashlib
+import ipaddress
+import json
+import re
+
+OWNER = 'com.gowalk.cicd.network-contract'
+SCHEMA = 'com.gowalk.cicd.network-schema'
+PROJECT = 'com.docker.compose.project'
+NETWORK = 'com.docker.compose.network'
+
+
+class ContractFailure(Exception):
+    def __init__(self, code):
+        self.code = code
+        super().__init__(code)
+
+
+def identity(value, pattern):
+    if not isinstance(value, str) or not re.fullmatch(pattern, value):
+        raise ContractFailure('invalid_project_contract')
+    return value
+
+
+def disposition(key, value, project, services):
+    if value.get('external') is True:
+        return 'external'
+    if value.get('name') != project + '_' + key:
+        return 'custom_name'
+    if value.get('ipam'):
+        return 'authored_ipam'
+    allowed = {'name', 'driver', 'internal', 'attachable', 'enable_ipv4', 'enable_ipv6', 'labels', 'ipam'}
+    if set(value) - allowed or value.get('driver', 'bridge') not in ('', 'bridge'):
+        return 'custom_settings'
+    if value.get('enable_ipv6') or value.get('enable_ipv4') is False:
+        return 'address_family'
+    for service in services.values():
+        options = (service.get('networks') or {}).get(key) or {}
+        if options.get('ipv4_address') or options.get('ipv6_address'):
+            return 'static_address'
+    return 'eligible'
+
+
+def plans(config, project):
+    identity(project, r'[a-z0-9][a-z0-9-]{0,79}')
+    if not isinstance(config, dict) or config.get('name') != project:
+        raise ContractFailure('invalid_project_contract')
+    services, networks = config.get('services', {}), config.get('networks', {})
+    if not isinstance(services, dict) or not isinstance(networks, dict) or len(networks) > 64:
+        raise ContractFailure('invalid_project_contract')
+    result = []
+    for key, value in sorted(networks.items()):
+        identity(key, r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}')
+        if not isinstance(value, dict) or not isinstance(value.get('name'), str):
+            raise ContractFailure('invalid_project_contract')
+        selected = disposition(key, value, project, services)
+        labels = value.get('labels', {})
+        if selected == 'eligible':
+            if not isinstance(labels, dict) or any(not isinstance(v, str) for v in labels.values()):
+                raise ContractFailure('invalid_project_contract')
+            if any(k.startswith('com.docker.compose.') or k.startswith('com.gowalk.cicd.') for k in labels):
+                raise ContractFailure('reserved_network_label')
+        canonical = json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=True)
+        result.append({'key': key, 'name': value['name'], 'project': project, 'disposition': selected,
+                       'contract': hashlib.sha256(canonical.encode()).hexdigest(), 'settings': value})
+    return result
+
+
+def existing(plan, networks):
+    matches = [item for item in networks if item['Name'] == plan['name']]
+    if len(matches) > 1:
+        raise ContractFailure('network_name_ambiguous')
+    if not matches:
+        return None
+    network = matches[0]
+    labels = network.get('Labels') or {}
+    if plan['disposition'] in ('external', 'custom_name') and not labels.get(OWNER):
+        return network
+    if labels.get(PROJECT) != plan['project'] or labels.get(NETWORK) != plan['key']:
+        raise ContractFailure('network_ownership_mismatch')
+    if labels.get(OWNER) and (labels[OWNER] != plan['contract'] or labels.get(SCHEMA) != '1'):
+        raise ContractFailure('network_contract_changed')
+    return network
+
+
+def create_arguments(plan, subnet, compose_version):
+    value = plan['settings']
+    labels = dict(value.get('labels') or {})
+    labels.update({PROJECT: plan['project'], NETWORK: plan['key'], 'com.docker.compose.version': compose_version,
+                   OWNER: plan['contract'], SCHEMA: '1'})
+    gateway = str(ipaddress.IPv4Network(subnet).network_address + 1)
+    args = ['docker', 'network', 'create', '--driver', 'bridge', '--subnet', subnet, '--gateway', gateway]
+    for flag in ('internal', 'attachable'):
+        if value.get(flag):
+            args.append('--' + flag)
+    for key, value in sorted(labels.items()):
+        args.extend(['--label', key + '=' + value])
+    return args + [plan['name']]
+
+
+def verify_created(plan, network, subnet):
+    value, labels = plan['settings'], network.get('Labels') or {}
+    if (network['Name'] != plan['name'] or labels.get(OWNER) != plan['contract']
+            or labels.get(SCHEMA) != '1' or labels.get(PROJECT) != plan['project']
+            or labels.get(NETWORK) != plan['key'] or network.get('Driver') != 'bridge'
+            or network.get('EnableIPv6') or network.get('Scope') != 'local'
+            or labels.get('com.docker.compose.config-hash')):
+        raise ContractFailure('created_network_unverified')
+    if any(bool(network.get(k.title())) != bool(value.get(k)) for k in ('internal', 'attachable')):
+        raise ContractFailure('created_network_unverified')
+    pools = (network.get('IPAM') or {}).get('Config') or []
+    if len(pools) != 1 or pools[0].get('Subnet') != subnet:
+        raise ContractFailure('created_network_unverified')
+    if (network['IPAM'].get('Driver') != 'default' or network['IPAM'].get('Options')
+            or set(pools[0]) - {'Subnet', 'Gateway'}
+            or pools[0].get('Gateway') != str(ipaddress.IPv4Network(subnet).network_address + 1)):
+        raise ContractFailure('created_network_unverified')
+    if any(labels.get(k) != v for k, v in (value.get('labels') or {}).items()):
+        raise ContractFailure('created_network_unverified')

package/backend-action/network_diagnostics.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Read bounded deployment-host network evidence without syncing files or changing a network."""
+import argparse
+import ipaddress
+import json
+from pathlib import Path
+import re
+import shlex
+
+from identity_diagnostics import ReaderFailure, bounded, retain_result
+from network_pools import FAILURES as INVENTORY_FAILURES
+
+SCHEMA = 'gowalk-cicd/backend-network-diagnostics.v1'
+MODULES = ('identity_diagnostics', 'network_runtime', 'network_pools', 'network_inventory')
+FAILURES = INVENTORY_FAILURES | frozenset({'network_inventory_unverified', 'network_command_unavailable', ''})
+
+
+def remote_source(app):
+    """Send only package-owned Python sources; no environment, source checkout or private inputs."""
+    sources = {name: Path(__file__).with_name(name + '.py').read_text() for name in MODULES}
+    program = '''import json, sys, types
+sources = SOURCES
+for name, source in sources.items():
+    module = types.ModuleType(name)
+    sys.modules[name] = module
+    exec(compile(source, name + '.py', 'exec'), module.__dict__)
+from network_inventory import collect, InventoryFailure
+from network_runtime import run, NetworkFailure
+result = {'schema': SCHEMA, 'ok': False, 'project': APP, 'failure': ''}
+try:
+    inventory = collect(run, require_pools=False)
+    own = [item for item in inventory['networks']
+           if item['Labels'].get('com.docker.compose.project') == APP]
+    result.update({key: inventory[key] for key in
+                   ('docker_version', 'compose_version', 'python_version', 'pool_source',
+                    'pool_failure', 'pools', 'observed_at')})
+    result.update(ok=True, complete=True, network_count=len(inventory['networks']),
+                  excluded_subnets=inventory['excluded'],
+                  networks=[{'id': n['Id'], 'name': n['Name'], 'driver': n['Driver'],
+                             'key': n['Labels'].get('com.docker.compose.network', ''),
+                             'subnets': [p['Subnet'] for p in n['IPAM']['Config']],
+                             'endpoints': len(n['Containers'])} for n in own])
+except (InventoryFailure, NetworkFailure) as error:
+    result['failure'] = error.code
+    result.update(getattr(error, 'details', {}))
+except Exception:
+    result['failure'] = 'network_inventory_unverified'
+print(json.dumps(result, separators=(',', ':')))
+sys.exit(0 if result['ok'] else 1)
+'''
+    return program.replace('SCHEMA', repr(SCHEMA)).replace('APP', repr(app)).replace('SOURCES', repr(sources)).encode()
+
+
+def decode(status, raw, app):
+    try:
+        result = json.loads(raw)
+    except (ValueError, TypeError):
+        raise ReaderFailure('remote_invalid') from None
+    allowed = {'schema', 'ok', 'project', 'failure', 'docker_version', 'compose_version', 'python_version',
+               'pool_source',
+               'pool_failure', 'pools', 'observed_at', 'complete', 'network_count', 'excluded_subnets', 'networks'}
+    if (not isinstance(result, dict) or set(result) - allowed or result.get('schema') != SCHEMA
+            or result.get('project') != app or type(result.get('ok')) is not bool
+            or status != (0 if result['ok'] else 1)):
+        raise ReaderFailure('remote_invalid')
+    if result.get('failure') not in FAILURES:
+        raise ReaderFailure('remote_invalid')
+    if result['ok']:
+        validate_inventory(result)
+    elif set(result) != {'schema', 'ok', 'project', 'failure'}:
+        partial = {'schema', 'ok', 'project', 'failure', 'docker_version', 'compose_version', 'python_version', 'pools',
+                   'pool_source', 'pool_failure', 'observed_at', 'complete'}
+        if set(result) != partial or result['complete'] is not False:
+            raise ReaderFailure('remote_invalid')
+        validate_metadata(result)
+    return result
+
+
+def validate_metadata(result):
+    for key in ('docker_version', 'compose_version', 'python_version'):
+        pattern = r'\d+\.\d+\.\d+(?:[-+][A-Za-z0-9._-]{1,64})?'
+        if not isinstance(result.get(key), str) or not re.fullmatch(pattern, result[key]):
+            raise ReaderFailure('remote_invalid')
+    if result.get('pool_source') not in ('engine_info', 'versioned_moby_builtin', 'unverified'):
+        raise ReaderFailure('remote_invalid')
+    if (result.get('pool_failure') not in INVENTORY_FAILURES | {''}
+            or not isinstance(result.get('observed_at'), str)
+            or not re.fullmatch(r'[0-9T:+.\-Z]{20,40}', result['observed_at'])):
+        raise ReaderFailure('remote_invalid')
+    if not isinstance(result.get('pools'), list) or len(result['pools']) > 64:
+        raise ReaderFailure('remote_invalid')
+    try:
+        for pool in result['pools']:
+            if set(pool) != {'base', 'size'} or type(pool['size']) is not int or not 0 <= pool['size'] <= 32:
+                raise ValueError()
+            ipaddress.IPv4Network(pool['base'], strict=True)
+    except (ValueError, TypeError, KeyError):
+        raise ReaderFailure('remote_invalid') from None
+
+
+def validate_inventory(result):
+    validate_metadata(result)
+    if (result.get('complete') is not True or type(result.get('network_count')) is not int
+            or not 0 <= result['network_count'] <= 1024 or result['failure']):
+        raise ReaderFailure('remote_invalid')
+    for field, limit in (('excluded_subnets', 16384), ('networks', 1024)):
+        if not isinstance(result.get(field), list) or len(result[field]) > limit:
+            raise ReaderFailure('remote_invalid')
+    try:
+        for value in result['excluded_subnets']:
+            ipaddress.IPv4Network(value, strict=True)
+        for network in result['networks']:
+            validate_network(network, result['project'])
+    except (ValueError, TypeError, KeyError):
+        raise ReaderFailure('remote_invalid') from None
+
+
+def validate_network(network, project):
+    if (not isinstance(network, dict) or set(network) != {'id', 'name', 'driver', 'key', 'subnets', 'endpoints'}
+            or not isinstance(network['id'], str) or not re.fullmatch('[0-9a-f]{64}', network['id'])
+            or not isinstance(network['name'], str) or not re.fullmatch('[A-Za-z0-9_.-]{1,256}', network['name'])
+            or not isinstance(network['key'], str) or not re.fullmatch('[A-Za-z0-9_.-]{0,128}', network['key'])
+            or network['driver'] not in ('bridge', 'host', 'null', 'overlay', 'macvlan', 'ipvlan')
+            or type(network['endpoints']) is not int or not 0 <= network['endpoints'] <= 100000
+            or not isinstance(network['subnets'], list) or len(network['subnets']) > 64):
+        raise ValueError()
+    for value in network['subnets']:
+        ipaddress.ip_network(value, strict=True)
+
+
+def diagnose(app, host, user):
+    if (not re.fullmatch(r'[a-z0-9][a-z0-9-]{0,79}', app)
+            or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9.-]{0,252}', host)
+            or not re.fullmatch(r'[a-z_][a-z0-9_-]{0,31}', user)):
+        raise ReaderFailure('invalid_destination')
+    remote = shlex.join(['python3', '-'])
+    argv = ['ssh', '-i', str(Path.home() / '.ssh/backend_deploy'), '-o', 'IdentitiesOnly=yes',
+            '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=5',
+            '-o', 'ServerAliveCountMax=2', user + '@' + host, remote]
+    status, raw = bounded(argv, payload=remote_source(app), seconds=60, with_status=True)
+    return decode(status, raw, app)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--app', required=True)
+    parser.add_argument('--host', required=True)
+    parser.add_argument('--user', default='root')
+    parser.add_argument('--output', required=True)
+    args = parser.parse_args()
+    try:
+        result = diagnose(args.app, args.host, args.user)
+    except Exception as error:
+        code = error.code if isinstance(error, ReaderFailure) else 'network_diagnostic_unverified'
+        result = {'schema': SCHEMA, 'ok': False, 'project': args.app, 'failure': code}
+    try:
+        retain_result(args.output, result)
+    except ReaderFailure:
+        return 1
+    print(json.dumps(result, separators=(',', ':')))
+    return 0 if result['ok'] else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/backend-action/network_inventory.py

@@ -0,0 +1,235 @@
+"""Bounded private Docker/host inventory for allocation and scoped diagnostics (Python 3.8)."""
+import datetime
+import os
+import re
+import sys
+import time
+
+from network_pools import (InventoryFailure, address_exclusions, decode, effective_pools, prefix,
+                           resolver_exclusions, route_exclusions, validate_rules)
+
+LIMIT = 1024 * 1024
+INFO_FORMAT = ('{"version":{{json .ServerVersion}},"os":{{json .OSType}},'
+               '"security":{{json .SecurityOptions}},"pools":{{json .DefaultAddressPools}}}')
+HOST_PROBE = '''import json, os, socket, stat, struct, sys
+path = sys.argv[1]
+with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+    connection.settimeout(3)
+    connection.connect(path)
+    peer, uid, gid = struct.unpack('3i', connection.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, 12))
+record = os.lstat('/run/docker.pid')
+with open('/run/docker.pid', encoding='ascii') as source:
+    value = source.read(32).strip()
+if not value.isdigit() or not 1 < int(value) < 4194304:
+    raise SystemExit(1)
+pid = int(value)
+with open('/proc/%d/comm' % pid, encoding='ascii') as source:
+    command = source.read(32).strip()
+own = os.stat('/proc/self/ns/net').st_ino
+daemon = os.stat('/proc/%d/ns/net' % pid).st_ino
+init = os.stat('/proc/1/ns/net').st_ino
+rootful = uid == 0 and os.stat('/proc/%d' % pid).st_uid == 0 and peer in (1, pid)
+pidfile = stat.S_ISREG(record.st_mode) and record.st_uid == 0 and not record.st_mode & 0o022
+print(json.dumps({'local_rootful': rootful and pidfile and command == 'dockerd',
+                  'same_namespace': own == daemon == init}))
+'''
+
+
+class Reader:
+    def __init__(self, run):
+        self.run, self.deadline, self.total = run, time.monotonic() + 45, 0
+
+    def __call__(self, argv, *, parsed=True):
+        remaining = self.deadline - time.monotonic()
+        if remaining <= 0:
+            raise InventoryFailure('inventory_timeout')
+        try:
+            raw = self.run(argv, seconds=min(10, remaining))
+        except Exception as error:
+            code = {'command_timeout': 'inventory_timeout', 'output_limit': 'inventory_output_limit'}
+            raise InventoryFailure(code.get(getattr(error, 'code', ''), 'inventory_command_failed')) from None
+        if not isinstance(raw, bytes) or len(raw) > LIMIT:
+            raise InventoryFailure('inventory_output_limit')
+        self.total += len(raw)
+        if self.total > 8 * LIMIT:
+            raise InventoryFailure('inventory_output_limit')
+        return decode(raw) if parsed else raw
+
+
+def host_proof(read):
+    if (os.environ.get('DOCKER_HOST', '') not in ('', 'unix:///var/run/docker.sock', 'unix:///run/docker.sock')
+            or os.environ.get('DOCKER_CONTEXT', '') not in ('', 'default')
+            or any(os.environ.get(key) for key in
+                   ('DOCKER_TLS_VERIFY', 'DOCKER_CERT_PATH', 'DOCKER_API_VERSION', 'DOCKER_CONFIG'))):
+        raise InventoryFailure('docker_endpoint_unsupported')
+    endpoint = read(['docker', 'context', 'inspect', '--format', '{{json .Endpoints.docker.Host}}'])
+    if endpoint not in ('unix:///var/run/docker.sock', 'unix:///run/docker.sock'):
+        raise InventoryFailure('docker_endpoint_unsupported')
+    try:
+        proof = read([sys.executable, '-c', HOST_PROBE, endpoint[len('unix://'):]])
+    except InventoryFailure:
+        raise InventoryFailure('host_namespace_unverified') from None
+    if (not isinstance(proof, dict) or set(proof) != {'local_rootful', 'same_namespace'}
+            or any(value is not True for value in proof.values())):
+        raise InventoryFailure('host_namespace_unverified')
+
+
+def engine_info(read, require_pools):
+    info = read(['docker', 'info', '--format', INFO_FORMAT])
+    compose = read(['docker', 'compose', 'version', '--short'], parsed=False)
+    try:
+        compose = compose.decode('ascii').strip()
+        if compose.startswith('v'):
+            compose = compose[1:]
+    except UnicodeError:
+        raise InventoryFailure('docker_engine_unsupported') from None
+    if (not isinstance(info, dict) or set(info) != {'version', 'os', 'security', 'pools'}
+            or not isinstance(info['version'], str)
+            or not re.fullmatch(r'\d+\.\d+\.\d+(?:[-+][A-Za-z0-9._-]{1,64})?', info['version'])
+            or not re.fullmatch(r'\d+\.\d+\.\d+(?:[-+][A-Za-z0-9._-]{1,64})?', compose) or info['os'] != 'linux'
+            or not isinstance(info['security'], list)
+            or any(not isinstance(value, str) or 'rootless' in value for value in info['security'])):
+        raise InventoryFailure('docker_engine_unsupported')
+    result = {'docker_version': info['version'], 'compose_version': compose,
+              'python_version': '.'.join(str(value) for value in sys.version_info[:3]),
+              'pools': [], 'pool_source': 'unverified', 'pool_failure': ''}
+    try:
+        result['pools'], result['pool_source'] = effective_pools(info['pools'], info['version'])
+    except InventoryFailure as error:
+        if require_pools:
+            raise
+        result['pool_failure'] = error.code
+    return result
+
+
+def network_ipam(value):
+    if (not isinstance(value, dict) or set(value) - {'Driver', 'Options', 'Config'}
+            or value.get('Driver') not in ('default', 'null') or not isinstance(value.get('Config'), list)):
+        raise InventoryFailure('network_ipam_unsupported')
+    options = value.get('Options')
+    if options is not None and (not isinstance(options, dict) or options):
+        raise InventoryFailure('network_ipam_unsupported')
+    result, excluded = [], set()
+    for row in value['Config']:
+        if not isinstance(row, dict) or set(row) - {'Subnet', 'Gateway', 'IPRange', 'AuxiliaryAddresses'}:
+            raise InventoryFailure('network_ipam_unsupported')
+        subnet = prefix(row.get('Subnet'), strict=True)
+        if subnet.version == 4:
+            excluded.add(str(subnet))
+        for key in ('Gateway', 'IPRange'):
+            if row.get(key):
+                address = prefix(row[key])
+                if address.version != subnet.version or not address.subnet_of(subnet):
+                    raise InventoryFailure('network_ipam_unsupported')
+        auxiliary = row.get('AuxiliaryAddresses') or {}
+        if not isinstance(auxiliary, dict):
+            raise InventoryFailure('network_ipam_unsupported')
+        for address in auxiliary.values():
+            if not prefix(address).subnet_of(subnet):
+                raise InventoryFailure('network_ipam_unsupported')
+        result.append(dict(row))
+    return {'Driver': value['Driver'], 'Options': options or {}, 'Config': result}, excluded
+
+
+def network_record(row):
+    if not isinstance(row, dict):
+        raise InventoryFailure('inventory_invalid')
+    result = {key: row.get(key) for key in ('Id', 'Name', 'Driver', 'Scope', 'Internal', 'Attachable', 'EnableIPv6')}
+    if (not isinstance(result['Id'], str) or not re.fullmatch(r'[a-f0-9]{64}', result['Id'])
+            or not isinstance(result['Name'], str) or not 1 <= len(result['Name']) <= 256
+            or result['Driver'] not in ('bridge', 'host', 'null', 'overlay', 'macvlan', 'ipvlan')
+            or result['Scope'] not in ('local', 'swarm', 'global')
+            or any(type(result[key]) is not bool for key in ('Internal', 'Attachable', 'EnableIPv6'))):
+        raise InventoryFailure('inventory_invalid')
+    for key in ('Labels', 'Options'):
+        value = row.get(key)
+        if value is not None and (not isinstance(value, dict) or any(
+                not isinstance(k, str) or not isinstance(v, str) for k, v in value.items())):
+            raise InventoryFailure('inventory_invalid')
+        result[key] = value or {}
+    containers = row.get('Containers')
+    if not isinstance(containers, dict) or any(not isinstance(item, dict) for item in containers.values()):
+        raise InventoryFailure('inventory_invalid')
+    result['Containers'] = {key: {} for key in containers}
+    ipam = row.get('IPAM')
+    if result['Driver'] in ('host', 'null') and isinstance(ipam, dict) and ipam.get('Config', []) is None:
+        ipam = dict(ipam, Config=[])
+    result['IPAM'], excluded = network_ipam(ipam)
+    return result, excluded
+
+
+def network_ids(raw):
+    try:
+        ids = raw.decode('ascii').splitlines()
+    except UnicodeError:
+        raise InventoryFailure('inventory_invalid') from None
+    if (not ids or len(ids) > 1024 or len(set(ids)) != len(ids)
+            or any(not re.fullmatch(r'[a-f0-9]{64}', value) for value in ids)):
+        raise InventoryFailure('inventory_invalid')
+    return ids
+
+
+def network_scan(read):
+    listing = ['docker', 'network', 'ls', '--no-trunc', '--format', '{{.ID}}']
+    ids = network_ids(read(listing, parsed=False))
+    networks, excluded = [], set()
+    for offset in range(0, len(ids), 32):
+        batch = ids[offset:offset + 32]
+        rows = read(['docker', 'network', 'inspect', *batch])
+        if not isinstance(rows, list) or len(rows) != len(batch):
+            raise InventoryFailure('inventory_invalid')
+        observed = []
+        for row in rows:
+            network, prefixes = network_record(row)
+            networks.append(network)
+            observed.append(network['Id'])
+            excluded.update(prefixes)
+        if sorted(observed) != sorted(batch):
+            raise InventoryFailure('inventory_invalid')
+    if sorted(network_ids(read(listing, parsed=False))) != sorted(ids):
+        raise InventoryFailure('network_inventory_changed')
+    return networks, excluded
+
+
+def host_networks(read):
+    routes = read(['ip', '-j', '-4', 'route', 'show', 'table', 'all'])
+    rules = read(['ip', '-j', '-4', 'rule', 'show'])
+    addresses = read(['ip', '-j', '-4', 'address', 'show'])
+    resolver = read(['cat', '/etc/resolv.conf'], parsed=False)
+    validate_rules(rules)
+    records = []
+    excluded = route_exclusions(routes, records) | address_exclusions(addresses, records)
+    dns, stub = resolver_exclusions(resolver, records=records)
+    if stub:
+        try:
+            upstream = read(['resolvectl', 'dns'], parsed=False)
+        except InventoryFailure:
+            raise InventoryFailure('resolver_upstream_unknown') from None
+        dns.update(resolver_exclusions(upstream, resolved=True, records=records)[0])
+    return excluded | dns, sorted(records, key=lambda row: (row['subnet'], row['kind'], row['device']))
+
+
+def collect(run, *, require_pools=True):
+    """Return private fields only; callers must project their own closed public receipt."""
+    read = Reader(run)
+    host_proof(read)
+    result = engine_info(read, False)
+    try:
+        if require_pools and result['pool_failure']:
+            raise InventoryFailure(result['pool_failure'])
+        before = host_networks(read)
+        networks, occupied = network_scan(read)
+        after = host_networks(read)
+        if before != after:
+            raise InventoryFailure('host_inventory_changed')
+        host_proof(read)
+        if engine_info(read, False) != result:
+            raise InventoryFailure('host_inventory_changed')
+    except InventoryFailure as error:
+        error.details = dict(result, complete=False,
+                             observed_at=datetime.datetime.now(datetime.timezone.utc).isoformat())
+        raise
+    result.update({'networks': networks, 'excluded': sorted(occupied | after[0]), 'host_excluded': sorted(after[0]),
+                   'host_records': after[1],
+                   'complete': True, 'observed_at': datetime.datetime.now(datetime.timezone.utc).isoformat()})
+    return result