@celilo/cli 0.23.0 → 0.24.0

package/src/services/cadence.ts

@@ -0,0 +1,165 @@
+/**
+ * How often celilo does something to a module, in one type.
+ *
+ * celilo has three per-module cadences — how often to back a module up, how
+ * often to health-check it, and (in the same family) how long to keep the
+ * backups. They were three spellings of the same idea: an enum of four words
+ * for backups, a `15m`-style duration for health checks, nothing shared. One
+ * namespace holding two unrelated formats is not one concept, so an operator
+ * setting `6h` on a backup had no way to be right.
+ *
+ * A cadence is therefore a word OR a duration, both normalised to minutes, plus
+ * `manual` for "the operator opted out". Every existing manifest keeps working:
+ * the words are the same words.
+ *
+ * The FLOOR is derived from the tick of the sweep that would act on the
+ * cadence, never stated independently. A cadence finer than its sweep's tick
+ * cannot be served, and accepting one leaves the operator believing they
+ * configured something that silently never happens. Deriving it means a changed
+ * tick moves the floor with it rather than waiting for someone to remember.
+ *
+ * Pure: no database, no clock. See
+ * openspec/changes/operator-cadence-overrides/design.md D3, D4.
+ */
+
+import { z } from 'zod';
+
+/** Minutes between runs, or `manual` — the operator opted out entirely. */
+export type Cadence = { minutes: number } | 'manual';
+
+/** The words a cadence may be spelled with, and what each means in minutes. */
+const NAMED_PERIODS: Record<string, number> = {
+  hourly: 60,
+  daily: 24 * 60,
+  weekly: 7 * 24 * 60,
+  // 30 days, matching what the backup schedule has always meant by `monthly`.
+  // No calendar-month semantics are introduced here, and none are lost.
+  monthly: 30 * 24 * 60,
+};
+
+export const DURATION_PATTERN = /^(\d+)(m|h|d)$/;
+
+/**
+ * Everything a cadence may be spelled as, for the JSON Schema export.
+ *
+ * Editors validate `modules/*​/manifest.yml` against the exported JSON Schema,
+ * which cannot carry a Zod refinement — so well-formedness is duplicated as a
+ * regex the same way `health_check.interval` already does it. The floor is not
+ * expressible here and stays a refinement.
+ */
+export const CADENCE_PATTERN = /^(hourly|daily|weekly|monthly|manual|\d+(m|h|d))$/;
+
+/**
+ * Parse a duration string (`15m`, `1h`, `1d`) to whole minutes.
+ * Returns null when the string is not a well-formed duration.
+ */
+export function parseIntervalMinutes(value: string): number | null {
+  const match = DURATION_PATTERN.exec(value);
+  if (!match) return null;
+  const amount = Number.parseInt(match[1], 10);
+  if (!Number.isFinite(amount) || amount <= 0) return null;
+  const unit = match[2];
+  if (unit === 'm') return amount;
+  if (unit === 'h') return amount * 60;
+  return amount * 60 * 24;
+}
+
+/** Parse a cadence in any accepted spelling. Returns null when malformed. */
+export function parseCadence(value: string): Cadence | null {
+  if (value === 'manual') return 'manual';
+  const named = NAMED_PERIODS[value];
+  if (named !== undefined) return { minutes: named };
+  const minutes = parseIntervalMinutes(value);
+  return minutes === null ? null : { minutes };
+}
+
+/**
+ * Spell a cadence back the way an operator would write it, preferring the word
+ * when one exists — a resolved `1440` reads as `daily`, not `24h`.
+ */
+export function formatCadence(cadence: Cadence): string {
+  if (cadence === 'manual') return 'manual';
+  for (const [word, minutes] of Object.entries(NAMED_PERIODS)) {
+    if (minutes === cadence.minutes) return word;
+  }
+  if (cadence.minutes % (24 * 60) === 0) return `${cadence.minutes / (24 * 60)}d`;
+  if (cadence.minutes % 60 === 0) return `${cadence.minutes / 60}h`;
+  return `${cadence.minutes}m`;
+}
+
+/** Milliseconds between runs. `manual` is infinite — never due, never stale. */
+export function cadenceMs(cadence: Cadence): number {
+  return cadence === 'manual' ? Number.POSITIVE_INFINITY : cadence.minutes * 60_000;
+}
+
+/**
+ * Minutes between ticks of a bus timer pattern (`timer.tick.5m` → 5).
+ *
+ * The floors below are derived through this rather than written down, so
+ * changing which tick a sweep rides changes what it can serve in the same edit.
+ */
+export function tickIntervalMinutes(pattern: string): number {
+  const suffix = pattern.replace(/^timer\.tick\./, '');
+  const minutes = parseIntervalMinutes(suffix);
+  if (minutes === null) throw new Error(`Not a timer tick pattern: ${pattern}`);
+  return minutes;
+}
+
+/**
+ * The bus tick each sweep rides.
+ *
+ * They live here, with the floors that derive from them, rather than beside
+ * each sweep's subscriber registration — a floor stated in one file and a tick
+ * chosen in another is exactly the pair that drifts. The sweeps import their
+ * pattern from here.
+ */
+export const BACKUP_SWEEP_PATTERN = 'timer.tick.1h';
+export const ALERTING_SWEEP_PATTERN = 'timer.tick.5m';
+
+/** Finest backup cadence the hourly backup sweep can serve. */
+export const BACKUP_CADENCE_FLOOR_MINUTES = tickIntervalMinutes(BACKUP_SWEEP_PATTERN);
+
+/** Finest health-check cadence the five-minute alerting sweep can serve. */
+export const MONITOR_INTERVAL_FLOOR_MINUTES = tickIntervalMinutes(ALERTING_SWEEP_PATTERN);
+
+/** Human list of accepted spellings, naming the finest cadence this sweep serves. */
+export function describeCadenceForm(floorMinutes: number): string {
+  return `Allowed: a named period (hourly, daily, weekly, monthly), a duration like "6h", "90m" or "3d" no finer than ${formatCadence({ minutes: floorMinutes })}, or "manual" to opt out.`;
+}
+
+/**
+ * A cadence value that the named sweep can actually serve.
+ *
+ * Validates the string form (what an operator types and what a manifest
+ * carries); the caller parses it with `parseCadence` once it is known good.
+ *
+ * The well-formedness check is a `.regex` on the inner string rather than part
+ * of the refinement because only the regex survives the export to JSON Schema,
+ * and that export is what validates `modules/*​/manifest.yml` in an editor. The
+ * floor cannot be expressed in JSON Schema at all, so it stays a refinement.
+ */
+export function cadenceSchema({
+  floorMinutes,
+  description,
+}: {
+  floorMinutes: number;
+  description?: string;
+}): z.ZodType<string> {
+  const form = describeCadenceForm(floorMinutes);
+  let base = z.string().regex(CADENCE_PATTERN, { message: form });
+  if (description) base = base.describe(description);
+  return base.superRefine((value, ctx) => {
+    const cadence = parseCadence(value);
+    if (cadence === null) {
+      // `0h` matches the pattern and is not a cadence.
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: form });
+      return;
+    }
+    if (cadence !== 'manual' && cadence.minutes < floorMinutes) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `"${value}" is finer than the sweep that would serve it can run (every ${formatCadence({ minutes: floorMinutes })}). ${form}`,
+      });
+    }
+  });
+}

package/src/services/machine-detector.ts

@@ -298,7 +298,15 @@ async function detectNetworkInterfacesWith(
     interfaces.push({ name: iface.name, ipAddress: iface.ipAddress, zone });
   }
 
-  // Classify: router if interfaces span multiple distinct zones
+  // Classify: router if interfaces span multiple distinct zones.
+  //
+  // The `!== 'unknown'` filter was dead code until now — `detectZoneFromIp`
+  // could not produce `'unknown'`, it claimed `external` instead, so every
+  // unmatched leg counted as a distinct zone and inflated this set. On the e2e
+  // firewall that meant four legs reported as `external`, collapsing to ONE
+  // zone here rather than the three real ones. The filter is live now, and it
+  // is the right rule: an interface celilo cannot attribute is not evidence of
+  // spanning anything.
   const uniqueZones = new Set(interfaces.map((i) => i.zone).filter((z) => z !== 'unknown'));
   const role: MachineRole = uniqueZones.size > 1 ? 'router' : 'host';
 
@@ -404,3 +412,17 @@ export async function testSshConnection(
     return false;
   }
 }
+
+/**
+ * How an interface's zone reads to an operator.
+ *
+ * `machine add` used to print the raw zone for every leg, which meant a firewall
+ * with five RFC1918 interfaces printed four of them as `(external)` — because
+ * `detectZoneFromIp` answered `external` when it meant "no idea". The vocabulary
+ * now distinguishes the two: a zone name when celilo matched one, and
+ * `unaccounted for` when it did not, which is the honest answer and the one that
+ * tells an operator there is something to declare.
+ */
+export function describeInterfaceZone(iface: NetworkInterface): string {
+  return iface.zone === 'unknown' ? 'unaccounted for — no declared subnet contains it' : iface.zone;
+}

package/src/services/module-config.ts

@@ -151,6 +151,39 @@ export function parseStoredConfigValue(
   }
 }
 
+/**
+ * A module's whole operator config as a plain key → typed-value map — the shape
+ * every policy resolver takes.
+ */
+export function loadModuleConfigs(db: DbClient, moduleId: string): Record<string, unknown> {
+  const configs: Record<string, unknown> = {};
+  for (const row of db
+    .select()
+    .from(moduleConfigs)
+    .where(eq(moduleConfigs.moduleId, moduleId))
+    .all()) {
+    configs[row.key] = parseStoredConfigValue(row);
+  }
+  return configs;
+}
+
+/**
+ * The raw string form of an operator override from an already-loaded config
+ * map, or undefined when the key is unset.
+ *
+ * Framework policy keys (cadences, retention, upgrade controls) are stored
+ * through the same typed path as any other config, so a cadence arrives as a
+ * string and a retention count as a number. Every resolver takes the string
+ * form and parses it itself, so this is the one place that flattening happens.
+ */
+export function configOverride(
+  configs: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const raw = configs?.[key];
+  return raw === undefined || raw === null ? undefined : String(raw);
+}
+
 /**
  * Get module configuration value
  * Returns parsed value (primitive or complex type)

package/src/services/storage-providers/s3.test.ts

@@ -1,17 +1,26 @@
 /**
- * Recurrence gate for ISS-0016: the S3 provider's upload() must send a
- * self-describing, replayable Buffer body — NOT a one-shot Node read stream.
+ * Recurrence gates for the two ways this provider's upload has been wrong.
  *
- * The original bug passed `createReadStream(localPath)` as PutObject Body with
- * no ContentLength; AWS SDK v3 fell back to aws-chunked streaming and failed
- * with "The request body terminated unexpectedly" (and couldn't replay the
- * stream across S3's retries/redirects). The verify path used a string body
- * (length known) and so never exercised the broken path — every real S3 backup
- * silently failed. These tests upload a REAL on-disk file and assert the body
- * is a Buffer, so a regression back to a stream is caught here.
+ * ISS-0016 — a one-shot `createReadStream` passed straight to PutObject as
+ * `Body` with no ContentLength. AWS SDK v3 fell back to aws-chunked streaming
+ * and failed with "The request body terminated unexpectedly", and could not
+ * replay the stream across S3's retries and redirects. The verify path used a
+ * string body (length known) and so never exercised the broken path, which is
+ * why every real S3 backup silently failed.
+ *
+ * celilo#685 — the fix for ISS-0016 was `readFileSync` into one Buffer, which
+ * is replayable and was fine for the system envelopes this provider carried at
+ * the time. Module backups then started using the same provider at a thousand
+ * times the size, and a ~1.9 GB Buffer on a 3784 MB management server was
+ * OOM-killed every hour for a day.
+ *
+ * The two constrain opposite things — replayable versus not resident — so
+ * neither test is meaningful alone, and satisfying one by breaking the other is
+ * exactly the history here. `Upload` (multipart) satisfies both: each PART is a
+ * replayable buffer, and only a bounded number of parts exist at once.
  *
  * No live S3 / MinIO harness exists, so we intercept S3Client.prototype.send
- * and inspect the command the provider builds.
+ * and inspect the commands the provider builds.
  */
 
 import { type Mock, afterEach, describe, expect, it, spyOn } from 'bun:test';
@@ -19,8 +28,20 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { Readable } from 'node:stream';
-import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
-import { type S3StorageConfig, createS3StorageProvider } from './s3';
+import {
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  UploadPartCommand,
+} from '@aws-sdk/client-s3';
+import {
+  type S3StorageConfig,
+  UPLOAD_PART_SIZE,
+  UPLOAD_QUEUE_SIZE,
+  createS3StorageProvider,
+} from './s3';
 
 const CONFIG: S3StorageConfig = {
   bucket: 'test-bucket',
@@ -44,7 +65,7 @@ describe('s3 storage provider (ISS-0016)', () => {
     }
   });
 
-  it('uploads a real on-disk file as a self-describing Buffer body, not a stream', async () => {
+  it('uploads a small file as a self-describing Buffer body, not a stream (ISS-0016)', async () => {
     dir = mkdtempSync(join(tmpdir(), 's3-upload-'));
     const file = join(dir, 'envelope.tar.gz');
     // A multi-KB real file — the case that broke against live S3.
@@ -61,6 +82,8 @@ describe('s3 storage provider (ISS-0016)', () => {
     const provider = createS3StorageProvider(CONFIG);
     await provider.upload(file, 'celilo-mgmt/2026/envelope.tar.gz');
 
+    // Under one part, so no multipart ceremony — a single PutObject, exactly
+    // as before. The bound below is what changed, not the small-file path.
     expect(sent).toHaveLength(1);
     const command = sent[0];
     expect(command).toBeInstanceOf(PutObjectCommand);
@@ -78,6 +101,66 @@ describe('s3 storage provider (ISS-0016)', () => {
     expect(command.input.Bucket).toBe('test-bucket');
   });
 
+  it('never holds more than one part per queue slot, however large the file (celilo#685)', async () => {
+    dir = mkdtempSync(join(tmpdir(), 's3-upload-large-'));
+    const file = join(dir, 'backup.tar.enc');
+
+    // Deliberately larger than one part, so the multipart path runs for real.
+    // It does not need to approach forgejo's 1.87 GB: the property under test
+    // is that peak residency is set by the part size rather than by the file,
+    // and a file that spans several parts demonstrates that at any scale. A
+    // test that had to allocate the failing size to prove the fix would be
+    // reproducing the bug rather than gating it.
+    const parts = 3;
+    const fileSize = UPLOAD_PART_SIZE * parts;
+    writeFileSync(file, Buffer.alloc(fileSize, 0x7a));
+
+    // Deliberately NOT a running total. Parts are uploaded concurrently and can
+    // arrive in any order, so the only way to show the artifact survives is to
+    // keep each part against its number and reassemble.
+    const received = new Map<number, Buffer>();
+    let inFlight = 0;
+    let peakInFlight = 0;
+    sendSpy = spyOn(S3Client.prototype, 'send').mockImplementation(async (command: unknown) => {
+      if (command instanceof CreateMultipartUploadCommand) return { UploadId: 'upload-1' };
+      if (command instanceof CompleteMultipartUploadCommand) return {};
+
+      expect(command).toBeInstanceOf(UploadPartCommand);
+      const part = command as UploadPartCommand;
+      const body = part.input.Body as Buffer;
+      const partNumber = part.input.PartNumber as number;
+
+      // Each part is still a replayable Buffer — ISS-0016 holds per part.
+      expect(Buffer.isBuffer(body)).toBe(true);
+      // A part number reused would silently lose data on reassembly.
+      expect(received.has(partNumber)).toBe(false);
+      received.set(partNumber, Buffer.from(body));
+
+      inFlight += 1;
+      peakInFlight = Math.max(peakInFlight, inFlight);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      inFlight -= 1;
+      return { ETag: `"etag-${partNumber}"` };
+    });
+
+    const provider = createS3StorageProvider(CONFIG);
+    await provider.upload(file, 'forgejo/2026-08-13/backup.tar.enc');
+
+    // The bound. No single request ever carries the whole artifact, and no more
+    // than the queue depth are resident at once, so peak bytes is
+    // UPLOAD_PART_SIZE * UPLOAD_QUEUE_SIZE no matter how big the file gets.
+    expect(received.size).toBe(parts);
+    for (const body of received.values()) expect(body.length).toBeLessThanOrEqual(UPLOAD_PART_SIZE);
+    expect(peakInFlight).toBeLessThanOrEqual(UPLOAD_QUEUE_SIZE);
+
+    // A bound is only worth having if the artifact still arrives. Reassembled
+    // in part order, the bytes must be the file — sizes summing correctly would
+    // not catch a swapped or duplicated part, and a backup that restores to
+    // scrambled bytes is worse than one that fails loudly.
+    const ordered = [...received.entries()].sort(([a], [b]) => a - b).map(([, body]) => body);
+    expect(Buffer.concat(ordered).equals(readFileSync(file))).toBe(true);
+  });
+
   it('downloads a multi-chunk response body to disk intact (short-read safe)', async () => {
     dir = mkdtempSync(join(tmpdir(), 's3-download-'));
     const out = join(dir, 'restored.bin');

package/src/services/storage-providers/s3.ts

@@ -3,7 +3,7 @@
  * Works with AWS S3, MinIO, Backblaze B2, Wasabi, and any S3-compatible service.
  */
 
-import { createWriteStream, readFileSync } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { Readable } from 'node:stream';
@@ -15,10 +15,47 @@ import {
   PutObjectCommand,
   S3Client,
 } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
 import type { StorageProvider, StorageVerifyResult } from './types';
 
 const BACKUP_PREFIX = 'celilo-backups';
 
+/**
+ * Multipart upload sizing. Peak resident bytes for an upload is
+ * `UPLOAD_PART_SIZE * UPLOAD_QUEUE_SIZE` — 64 MB — and does NOT grow with the
+ * artifact. That bound is the whole point of these two constants.
+ *
+ * `upload` used to `readFileSync` the artifact into one Buffer and hand it to
+ * PutObject. The comment justifying that read:
+ *
+ *   > Upload a Buffer, NOT a read stream (ISS-0016). A streamed Body fails with
+ *   > "The request body terminated unexpectedly" [...] Backup envelopes are
+ *   > small (state + key, not provider binaries — ISS-0015), so buffering is
+ *   > fine.
+ *
+ * The first half is true and still is: a one-shot Node stream as a PutObject
+ * `Body` cannot be replayed across the retries and redirects S3 issues, and
+ * with no ContentLength the SDK falls back to aws-chunked encoding on top.
+ * Passing `createReadStream` straight to PutObject would reintroduce exactly
+ * that bug.
+ *
+ * The second half stopped being true without anyone revisiting it. It was
+ * written when this provider only carried SYSTEM backups (celilo state plus a
+ * key, a few MB). MODULE backups now use the same provider and are three orders
+ * of magnitude larger — forgejo's envelope reached 1.87 GB — so "buffering is
+ * fine" became a ~1.9 GB Buffer on a 3784 MB management server, and the OOM
+ * killer took the backup every hour for a day while the on_backup hook itself
+ * reported success (celilo#685).
+ *
+ * `Upload` resolves the two halves rather than trading one for the other: it
+ * reads the stream a part at a time and each PART is a replayable buffer, so
+ * retries work without the whole object ever being resident. 16 MB parts keep
+ * a 1.87 GB artifact at ~117 requests, well inside S3's 10,000-part limit,
+ * which leaves headroom to ~160 GB.
+ */
+export const UPLOAD_PART_SIZE = 16 * 1024 * 1024;
+export const UPLOAD_QUEUE_SIZE = 4;
+
 export interface S3StorageConfig {
   bucket: string;
   region: string;
@@ -49,22 +86,18 @@ export function createS3StorageProvider(config: S3StorageConfig): StorageProvide
 
   return {
     async upload(localPath: string, remotePath: string): Promise<void> {
-      // Upload a Buffer, NOT a read stream (ISS-0016). A streamed Body fails
-      // with "The request body terminated unexpectedly": the SDK can't replay a
-      // one-shot Node stream across the retries/redirects S3 issues (e.g. a
-      // region 301), and with no ContentLength it falls back to aws-chunked
-      // encoding on top. A Buffer is replayable and self-describing — the same
-      // reason the string-bodied verify write succeeds where the stream upload
-      // did not. Backup envelopes are small (state + key, not provider
-      // binaries — ISS-0015), so buffering is fine.
-      const body = readFileSync(localPath);
-      await client.send(
-        new PutObjectCommand({
+      // Multipart, so peak memory is UPLOAD_PART_SIZE * UPLOAD_QUEUE_SIZE
+      // regardless of how large the artifact is.
+      await new Upload({
+        client,
+        partSize: UPLOAD_PART_SIZE,
+        queueSize: UPLOAD_QUEUE_SIZE,
+        params: {
           Bucket: bucket,
           Key: prefixedKey(remotePath),
-          Body: body,
-        }),
-      );
+          Body: createReadStream(localPath),
+        },
+      }).done();
     },
 
     async download(remotePath: string, localPath: string): Promise<void> {

package/src/services/zone-detector.test.ts

@@ -70,9 +70,14 @@ describe('zone-detector', () => {
       expect(zone).toBe('secure');
     });
 
-    it('returns external for non-matching IP', async () => {
+    it("returns 'unknown' for a PUBLIC address in no declared subnet", async () => {
+      // This asserted `external` before. It is now `'unknown'` because that is
+      // the question this function answers: containment. Whether 167.99.123.45
+      // is an external EDGE is `isPubliclyRoutable`'s question, and the caller
+      // resolves the two — see machine-add. Conflating them is the defect this
+      // change exists to remove (design D1).
       const zone = await detectZoneFromIp('167.99.123.45');
-      expect(zone).toBe('external');
+      expect(zone).toBe('unknown');
     });
 
     it('matches first IP in subnet', async () => {
@@ -87,7 +92,33 @@ describe('zone-detector', () => {
 
     it('does not match IP outside subnet', async () => {
       const zone = await detectZoneFromIp('192.168.1.100');
-      expect(zone).toBe('external');
+      expect(zone).toBe('unknown');
+    });
+
+    it("a PRIVATE address in no declared subnet is 'unknown', never 'external'", async () => {
+      // The heart of it. 172.16.5.5 is RFC 1918 — the internet cannot route to
+      // it under any circumstances — and it matched no declared subnet. Calling
+      // that `external` is the claim that broke `machine add`.
+      const zone = await detectZoneFromIp('172.16.5.5');
+      expect(zone).toBe('unknown');
+    });
+
+    /**
+     * §5.7 — PROOF THE OLD BEHAVIOUR IS GONE.
+     *
+     * The proposal's opening example, against the real subnet declarations in
+     * this fixture. Three RFC1918 gateway legs that no declared subnet contains.
+     * Pre-change, `detectZoneFromIp` returned `'external'` for every one of
+     * them, so `machine add` printed three private addresses as facing the
+     * internet. This test fails against that code and passes against this.
+     */
+    it('§5.7: three RFC1918 legs in no declared subnet are NOT external', async () => {
+      const undeclaredPrivateLegs = ['172.16.5.1', '10.99.0.1', '192.168.77.1'];
+      const zones = await Promise.all(undeclaredPrivateLegs.map((ip) => detectZoneFromIp(ip)));
+
+      expect(zones).toEqual(['unknown', 'unknown', 'unknown']);
+      // Stated separately so a failure says WHICH property broke.
+      expect(zones.filter((z) => z === 'external')).toEqual([]);
     });
   });
 

package/src/services/zone-detector.ts

@@ -6,7 +6,24 @@
 import { subnetContains } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../db/client';
-import { type NetworkZone, systemConfig } from '../db/schema';
+import { NETWORK_ZONES, type NetworkZone, systemConfig } from '../db/schema';
+
+/**
+ * The zones a subnet can be declared for — every `NetworkZone` except
+ * `external`.
+ *
+ * `external` is deliberately absent and must stay absent: it has no
+ * `network.external.subnet` and must never be given one. It is not a segment
+ * celilo manages, it is whatever the ISP handed you, so it is the RESIDUAL —
+ * decided by `isPubliclyRoutable`, not by containment (design D1, amended).
+ *
+ * Derived from NETWORK_ZONES rather than listed by hand. The hand-written list
+ * that used to be here had already dropped `control-plane-vpn`, which is the
+ * third instance of that bug class in this repo.
+ */
+const SUBNET_BACKED_ZONES: readonly NetworkZone[] = NETWORK_ZONES.filter(
+  (zone) => zone !== 'external',
+);
 
 /**
  * Get system network configuration for a zone
@@ -28,25 +45,28 @@ async function getZoneSubnet(zone: NetworkZone): Promise<string | null> {
 }
 
 /**
- * Detect network zone from IP address
- * Matches IP against system network configuration
+ * Which zone an address belongs to, or `'unknown'` when celilo cannot say.
+ *
+ * **`'unknown'` is the honest answer, and it used to be unreachable.** This
+ * returned `'external'` on no-match — so on a firewall with five RFC1918 legs
+ * and three declared zones, private gateway addresses were each reported as
+ * facing the internet. `NetworkInterface.zone` was already typed
+ * `NetworkZone | 'unknown'` and nothing could produce it, because this claimed
+ * `external` instead. The slot for the honest answer existed and was
+ * unreachable.
  *
- * @param ip - IP address to check
- * @returns Detected network zone, or 'external' if no match
+ * This answers ONLY the containment question. Whether an unmatched address is
+ * an external edge is a different question, answered by `isPubliclyRoutable` —
+ * see design D1 on why conflating the two was the defect.
  */
-export async function detectZoneFromIp(ip: string): Promise<NetworkZone> {
-  // Check each zone's subnet
-  const zones: NetworkZone[] = ['internal', 'dmz', 'app', 'secure', 'secure-mgmt'];
-
-  for (const zone of zones) {
+export async function detectZoneFromIp(ip: string): Promise<NetworkZone | 'unknown'> {
+  for (const zone of SUBNET_BACKED_ZONES) {
     const subnet = await getZoneSubnet(zone);
     if (subnet && subnetContains(subnet, ip)) {
       return zone;
     }
   }
-
-  // No match found - must be external
-  return 'external';
+  return 'unknown';
 }
 
 /**