@celilo/cli 0.23.0 → 0.24.1

package/src/services/config-provenance.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Who owns a config value — the operator, or celilo.
+ *
+ * The load-bearing case here is the one that looks like a special case and is
+ * not: `derive_from` does NOT mean derived. Getting that backwards refuses an
+ * operator's edit to their own config, and a migration written on the same test
+ * would delete the row.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { VariableDeclare } from '../manifest/schema';
+import {
+  declaredVariables,
+  describeDerivedSource,
+  explainNotSettable,
+  isDerivedVariable,
+} from './config-provenance';
+
+function variable(overrides: Partial<VariableDeclare> & { name: string }): VariableDeclare {
+  return {
+    type: 'string',
+    required: false,
+    source: 'user',
+    ...overrides,
+  } as VariableDeclare;
+}
+
+describe('isDerivedVariable', () => {
+  test('a user-sourced variable is the operator’s', () => {
+    expect(isDerivedVariable(variable({ name: 'acme_email', source: 'user' }))).toBe(false);
+  });
+
+  test.each(['capability', 'system', 'infrastructure', 'terraform'] as const)(
+    'a %s-sourced variable is celilo’s',
+    (source) => {
+      expect(isDerivedVariable(variable({ name: 'x', source }))).toBe(true);
+    },
+  );
+
+  test('a variable with NO declared source reads as the operator’s', () => {
+    // The manifest schema requires `source`, so this only happens for a
+    // malformed or pre-schema manifest already sitting in `manifest_data`. The
+    // question is which way to be wrong: guessing "derived" refuses an
+    // operator's `set` with a message insisting celilo owns a value nothing
+    // computes, which they cannot act on.
+    const noSource = {
+      name: 'app_port',
+      type: 'integer',
+      required: false,
+    } as unknown as VariableDeclare;
+
+    expect(isDerivedVariable(noSource)).toBe(false);
+  });
+
+  test('a user-sourced variable WITH a derive_from is still the operator’s', () => {
+    // iptables: `firewall_ip`, `source: user`, `derive_from: $machine:ipAddress`.
+    // `$machine:` derives are answered by the config interview — they seed a
+    // default the operator confirms — so the row is operator config. Classing
+    // it as derived would refuse an operator correcting their own firewall
+    // address, and deleting it on the same test would blind the trusted-sources
+    // audit in services/firewall-reach.ts, which reads exactly this row.
+    const firewallIp = variable({
+      name: 'firewall_ip',
+      source: 'user',
+      required: true,
+      derive_from: '$machine:ipAddress',
+    });
+
+    expect(isDerivedVariable(firewallIp)).toBe(false);
+  });
+});
+
+describe('declaredVariables', () => {
+  test('indexes a manifest’s owned variables by name', () => {
+    const declared = declaredVariables({
+      variables: {
+        owns: [variable({ name: 'hostname' }), variable({ name: 'vpn_subnet', source: 'system' })],
+      },
+    } as never);
+
+    expect([...declared.keys()].sort()).toEqual(['hostname', 'vpn_subnet']);
+    expect(declared.get('vpn_subnet')?.source).toBe('system');
+  });
+
+  test('a manifest declaring nothing yields an empty index, not a throw', () => {
+    expect(declaredVariables({} as never).size).toBe(0);
+  });
+});
+
+describe('explainNotSettable', () => {
+  test('a capability-sourced value points at the provider, not at this module', () => {
+    // The live footgun: `celilo module config set authentik auth_url …`
+    // reported success, wrote the row, and was discarded on the next deploy.
+    const message = explainNotSettable(
+      'authentik',
+      variable({
+        name: 'auth_url',
+        source: 'capability',
+        derive_from: '$capability:authentication.url',
+      }),
+    );
+
+    expect(message).toContain('not operator-settable');
+    expect(message).toContain('source: capability');
+    // Actionable: the only way to change a derived value is to fix its source.
+    expect(message).toContain('provider');
+    expect(message).toContain('redeploy');
+  });
+
+  test('a system-sourced value names the system key to set', () => {
+    const message = explainNotSettable(
+      'technitium',
+      variable({
+        name: 'vpn_subnet',
+        source: 'system',
+        derive_from: '$system:network.control-plane-vpn.subnet',
+      }),
+    );
+
+    // The operator should be able to copy the fix out of the error. The
+    // `$system:` prefix is stripped so the key is the one `system config set`
+    // actually takes.
+    expect(message).toContain('celilo system config set network.control-plane-vpn.subnet');
+  });
+
+  test('an infrastructure-sourced value keeps the placement guidance', () => {
+    const message = explainNotSettable(
+      'caddy',
+      variable({ name: 'vmid', source: 'infrastructure' }),
+    );
+
+    expect(message).toContain('IPAM');
+    expect(message).toContain('celilo proxmox migrate');
+  });
+});
+
+describe('describeDerivedSource', () => {
+  test('names the upstream, and the template when there is one', () => {
+    expect(
+      describeDerivedSource(
+        variable({
+          name: 'dmz_subnet',
+          source: 'system',
+          derive_from: '$system:network.dmz.subnet',
+        }),
+      ),
+    ).toBe('from system config ($system:network.dmz.subnet)');
+  });
+
+  test('degrades to the upstream alone when no template is declared', () => {
+    expect(describeDerivedSource(variable({ name: 'vmid', source: 'infrastructure' }))).toContain(
+      'infrastructure celilo selected',
+    );
+  });
+});

package/src/services/config-provenance.ts

@@ -0,0 +1,104 @@
+/**
+ * Who owns a module-config value: the operator, or celilo.
+ *
+ * A module's manifest declares a `source` for every variable it owns. `user`
+ * means the operator supplies it. Every other source — `capability`, `system`,
+ * `infrastructure`, `terraform` — means celilo computes it from somewhere else:
+ * another module's published capability data, system config, the selected
+ * infrastructure, a Terraform output.
+ *
+ * That distinction has to be shared rather than re-derived per command, because
+ * it was previously spelled differently in each place and the disagreements were
+ * silent. `module config set` refused only `source: infrastructure`, so setting
+ * a `capability`- or `system`-sourced value REPORTED SUCCESS, wrote the row, and
+ * was then discarded on the next deploy —
+ * `celilo module config set authentik auth_url …` being the live example. And
+ * `module config get` printed every row flat, so a value celilo derived was
+ * indistinguishable from one the operator had chosen.
+ *
+ * ## `derive_from` does not mean derived
+ *
+ * The tempting shortcut is "it has a `derive_from` template, so celilo computes
+ * it". That is wrong, and expensively so. `iptables` declares:
+ *
+ *     - name: firewall_ip
+ *       source: user
+ *       derive_from: "$machine:ipAddress"
+ *
+ * `$machine:` derivations are answered by the config interview — they seed a
+ * default the operator confirms — not by template resolution. The row is
+ * operator config. Treating it as derived would refuse an operator's attempt to
+ * correct their own firewall address, and a migration that deleted rows on the
+ * same test would blind the trusted-sources audit that reads it.
+ *
+ * `source` is the authority. Nothing else is.
+ */
+import type { ModuleManifest, VariableDeclare } from '../manifest/schema';
+
+/**
+ * Does celilo compute this variable, rather than the operator supply it?
+ *
+ * An ABSENT source reads as the operator's. The manifest schema requires
+ * `source`, so absent means a malformed or pre-schema manifest sitting in
+ * `modules.manifest_data` — and for those the question is which way to be
+ * wrong. Guessing "derived" refuses an operator's attempt to set their own
+ * config with a message insisting celilo owns a value nothing computes, which
+ * is unanswerable. Guessing "user" preserves what celilo did before this
+ * predicate existed, when only `infrastructure` was refused.
+ */
+export function isDerivedVariable(variable: Pick<VariableDeclare, 'source'>): boolean {
+  return variable.source !== undefined && variable.source !== 'user';
+}
+
+/** Every variable a module's manifest declares, indexed by name. */
+export function declaredVariables(manifest: ModuleManifest): Map<string, VariableDeclare> {
+  return new Map((manifest.variables?.owns ?? []).map((variable) => [variable.name, variable]));
+}
+
+/**
+ * A one-line explanation of where a derived value comes from, for output an
+ * operator reads. Says which upstream to go fix, since fixing the source is the
+ * only way to change a derived value.
+ */
+export function describeDerivedSource(variable: VariableDeclare): string {
+  switch (variable.source) {
+    case 'capability':
+      return variable.derive_from
+        ? `from another module's capability data (${variable.derive_from})`
+        : "from another module's capability data";
+    case 'system':
+      return variable.derive_from
+        ? `from system config (${variable.derive_from})`
+        : 'from system config';
+    case 'infrastructure':
+      return 'from the infrastructure celilo selected for this module';
+    case 'terraform':
+      return 'from a Terraform output, at deploy time';
+    default:
+      return `computed by celilo (source: ${variable.source})`;
+  }
+}
+
+/**
+ * Why `module config set` refuses this variable, and what to do instead.
+ * Actionable per source: a derived value is only wrong because its upstream is
+ * wrong, and fixing the upstream fixes every consumer at once, where pinning one
+ * module hides the divergence.
+ */
+export function explainNotSettable(moduleId: string, variable: VariableDeclare): string {
+  const header = `'${variable.name}' is derived by celilo (source: ${variable.source}) — not operator-settable.`;
+  const origin = `It is computed ${describeDerivedSource(variable)}, so a value set here would be overwritten the next time ${moduleId} is generated.`;
+
+  switch (variable.source) {
+    case 'capability':
+      return `${header}\n${origin}\n  • Fix it at the provider: change the config of the module that publishes this capability, then redeploy it.\n  • 'celilo module config get ${moduleId}' shows the value celilo currently computes.`;
+    case 'system':
+      return `${header}\n${origin}\n  • Fix it at the source: 'celilo system config set ${variable.derive_from?.replace(/^\$\{?system:/, '').replace(/\}$/, '') ?? '<key>'} <value>'.\n  • That corrects every module deriving from it at once, rather than pinning this one.`;
+    case 'infrastructure':
+      return `${header}\n${origin}\n  • node placement: set the service default for NEW deploys (celilo service reconfigure); move an existing container with 'celilo proxmox migrate'.\n  • vmid / IP: auto-allocated by IPAM.`;
+    case 'terraform':
+      return `${header}\n${origin}\n  • It is read back from Terraform outputs after the deploy creates the resource.`;
+    default:
+      return `${header}\n${origin}`;
+  }
+}

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([]);
     });
   });