chore(gates): pin the moved daemon HTTP wire surface and teach the released-baseline check file moves

Exports map + snapshot gain the daemon-http subpath. The wire ledger
re-keys the eight moved declarations (buildDaemonHealthPayload moves with
its new caller-supplied version parameter, acked additive). The
released-baseline comparison now classifies a baseline declaration that
re-appears unchanged at exactly one new path as a move instead of a
removal: a file move is not wire surface a released peer stopped sending.
A move that changes shape is a change acked at the destination path, and a
name still owned by the baseline stays a removal.

Author: thymikee

packages/contracts/package.json

@@ -163,6 +163,10 @@
       "types": "./src/command-platform-execution.ts",
       "default": "./src/command-platform-execution.ts"
     },
+    "./daemon-http": {
+      "types": "./src/daemon-http.ts",
+      "default": "./src/daemon-http.ts"
+    },
     "./daemon-owner-cleanup": {
       "types": "./src/daemon-owner-cleanup.ts",
       "default": "./src/daemon-owner-cleanup.ts"

scripts/layering/contracts-exports.snapshot.json

@@ -37,6 +37,7 @@
   "@agent-device/contracts/clipboard-runtime",
   "@agent-device/contracts/command",
   "@agent-device/contracts/command-platform-execution",
+  "@agent-device/contracts/daemon-http",
   "@agent-device/contracts/daemon-owner-cleanup",
   "@agent-device/contracts/device",
   "@agent-device/contracts/device-readiness-runtime",

scripts/wire-compat/model.test.ts

@@ -112,6 +112,131 @@ test('a removed wire declaration passes with a bump', () => {
   assert.deepEqual(result.failures, []);
 });
 
+// #2318 moved the daemon HTTP wire contract from src/daemon to
+// packages/contracts. A declaration that left its path but was re-declared
+// unchanged is a file move, not a removal: a released peer still parses it,
+// so it must not force a protocol bump.
+test('a declaration moved to a new file unchanged is a move, not a removal', () => {
+  const movedFrom = 'src/daemon/http-contract.ts#buildDaemonHttpUrl';
+  const movedTo = 'packages/contracts/src/daemon-http.ts#buildDaemonHttpUrl';
+  const released = ledger({
+    declarations: { [movedFrom]: 'sha256:ddd', [META]: 'sha256:bbb' },
+  });
+  const current = ledger({ declarations: { [movedTo]: 'sha256:ddd', [META]: 'sha256:bbb' } });
+  const result = compareWireLedgers({
+    baselineTag: 'v0.20.6',
+    released,
+    current,
+    digests: new Map(Object.entries({ [movedTo]: 'sha256:ddd', [META]: 'sha256:bbb' })),
+  });
+  assert.deepEqual(result.moved, [movedFrom]);
+  assert.deepEqual(result.removed, []);
+  assert.deepEqual(result.added, []);
+  assert.deepEqual(result.failures, []);
+});
+
+// A baseline key that leaves and a same-named key that arrives with a moved
+// digest are textually indistinguishable, so the gate reads the pair as a
+// CHANGE at the destination (ackable at the new digest) rather than the
+// bump-only removal the key-pair alone would suggest.
+test('a move that changes the shape is a change, acked at the path it moved to', () => {
+  const movedFrom = 'src/daemon/http-health.ts#buildDaemonHealthPayload';
+  const movedTo = 'packages/contracts/src/daemon-http.ts#buildDaemonHealthPayload';
+  const released = ledger({ declarations: { [movedFrom]: 'sha256:old' } });
+  const current = ledger({
+    declarations: { [movedTo]: 'sha256:new' },
+    compatibleChanges: [
+      {
+        declaration: movedTo,
+        digest: 'sha256:new',
+        rationale: 'The added parameter is caller-local; the wire payload is unchanged.',
+      },
+    ],
+  });
+  const digests = new Map(Object.entries({ [movedTo]: 'sha256:new' }));
+  const withoutAck = compareWireLedgers({
+    baselineTag: 'v0.20.6',
+    released,
+    current: ledger({ declarations: { [movedTo]: 'sha256:new' } }),
+    digests,
+  });
+  assert.deepEqual(withoutAck.changed, [movedTo]);
+  assert.deepEqual(withoutAck.removed, []);
+  assert.equal(withoutAck.failures.length, 1);
+  const withAck = compareWireLedgers({ baselineTag: 'v0.20.6', released, current, digests });
+  assert.deepEqual(withAck.failures, []);
+});
+
+// Names are not unique across files: while a baseline declaration still owns
+// the name at its own path, a same-named declaration elsewhere cannot be
+// identified as a move of this one, so the baseline key stays a removal.
+test('a name still owned by the baseline is not a move, so it remains a removal', () => {
+  const serverSendJson = 'src/daemon/server/http-server.ts#sendJson';
+  const uploadSendJson = 'src/daemon/upload-http.ts#sendJson';
+  const released = ledger({
+    declarations: { [serverSendJson]: 'sha256:old', [uploadSendJson]: 'sha256:eee' },
+  });
+  const current = ledger({ declarations: { [uploadSendJson]: 'sha256:eee' } });
+  const result = compareWireLedgers({
+    baselineTag: 'v0.20.6',
+    released,
+    current,
+    digests: new Map(Object.entries({ [uploadSendJson]: 'sha256:eee' })),
+  });
+  assert.deepEqual(result.removed, [serverSendJson]);
+  assert.deepEqual(result.moved, []);
+  assert.equal(result.failures.length, 1);
+});
+
+// One destination cannot be two declarations' move. When two same-name
+// baseline declarations leave their paths and one same-name path arrives, one
+// of them is a real removal, and a removal is bump-only.
+test('two same-name removals cannot share one move destination, so both stay removals', () => {
+  const first = 'src/a.ts#sendJson';
+  const second = 'src/b.ts#sendJson';
+  const destination = 'src/c.ts#sendJson';
+  const released = ledger({ declarations: { [first]: 'sha256:ddd', [second]: 'sha256:ddd' } });
+  const current = ledger({ declarations: { [destination]: 'sha256:ddd' } });
+  const result = compareWireLedgers({
+    baselineTag: 'v0.20.6',
+    released,
+    current,
+    digests: new Map(Object.entries({ [destination]: 'sha256:ddd' })),
+  });
+  assert.deepEqual(result.removed, [first, second]);
+  assert.deepEqual(result.moved, []);
+  // The destination is a key the baseline never had, so it is still reported
+  // as added alongside the removal that fails the gate.
+  assert.deepEqual(result.added, [destination]);
+  assert.equal(result.failures.length, 1);
+});
+
+// The contested-destination rule holds even when the arriving digest matches
+// one of the sources and an ack sits at the destination: the other source's
+// removal still cannot be covered.
+test('a contested destination fails even when acked at the destination', () => {
+  const first = 'src/a.ts#sendJson';
+  const second = 'src/b.ts#sendJson';
+  const destination = 'src/c.ts#sendJson';
+  const released = ledger({ declarations: { [first]: 'sha256:aaa', [second]: 'sha256:old' } });
+  const current = ledger({
+    declarations: { [destination]: 'sha256:new' },
+    compatibleChanges: [
+      { declaration: destination, digest: 'sha256:new', rationale: 'One of them moved here.' },
+    ],
+  });
+  const result = compareWireLedgers({
+    baselineTag: 'v0.20.6',
+    released,
+    current,
+    digests: new Map(Object.entries({ [destination]: 'sha256:new' })),
+  });
+  assert.deepEqual(result.removed, [first, second]);
+  assert.deepEqual(result.moved, []);
+  assert.equal(result.failures.length, 1);
+  assert.match(result.failures[0]!, /an ack cannot cover it/);
+});
+
 test('a newly added wire declaration is additive and needs nothing', () => {
   const added = 'packages/kernel/src/contracts.ts#NewEnvelope';
   const current = ledger({

scripts/wire-compat/model.ts

@@ -29,7 +29,16 @@ export type WireComparison = {
   changed: readonly string[];
   /** Declarations the baseline had and the current wire surface does not. */
   removed: readonly string[];
-  /** Declarations added since the baseline; additive, so never a failure. */
+  /**
+   * Baseline declarations that left their path but were re-declared unchanged
+   * (same name, same digest) at a single new path that no other left
+   * declaration also claims: a file move, never a failure.
+   */
+  moved: readonly string[];
+  /**
+   * Current keys the baseline never had (pure-move destinations excepted —
+   * their source is reported in `moved` instead). Additive, so never a failure.
+   */
   added: readonly string[];
   /** Whether the protocol version advanced since the baseline. */
   bumped: boolean;
@@ -43,12 +52,20 @@ export function compareWireLedgers(input: WireComparisonInput): WireComparison {
 
   const changed: string[] = [];
   const removed: string[] = [];
+  const moved: string[] = [];
+  const movedDestinations = new Set<string>();
+  const moveDestination = soleMoveDestinations(released.declarations, digests);
   for (const [key, releasedDigest] of Object.entries(released.declarations)) {
-    const digest = digests.get(key);
-    if (digest === undefined) removed.push(key);
-    else if (digest !== releasedDigest) changed.push(key);
+    const fate = baselineKeyFate(key, releasedDigest, digests, moveDestination);
+    if (fate.kind === 'changed') changed.push(fate.reportKey);
+    else if (fate.kind === 'moved') {
+      moved.push(key);
+      movedDestinations.add(fate.destination);
+    } else if (fate.kind === 'removed') removed.push(key);
   }
-  const added = Object.keys(current.declarations).filter((key) => !(key in released.declarations));
+  const added = Object.keys(current.declarations).filter(
+    (key) => !(key in released.declarations) && !movedDestinations.has(key),
+  );
 
   const failures: string[] = [];
   const stillAt = `still ${current.protocolVersion}`;
@@ -85,5 +102,84 @@ export function compareWireLedgers(input: WireComparisonInput): WireComparison {
     }
   }
 
-  return { changed, removed, added, bumped, failures };
+  return { changed, removed, moved, added, bumped, failures };
+}
+
+type BaselineFate =
+  | { kind: 'unchanged' }
+  | { kind: 'changed'; reportKey: string }
+  | { kind: 'moved'; destination: string }
+  | { kind: 'removed' };
+
+/** What a baseline declaration became in the current surface. */
+function baselineKeyFate(
+  key: string,
+  releasedDigest: string,
+  digests: ReadonlyMap<string, string>,
+  moveDestination: ReadonlyMap<string, string>,
+): BaselineFate {
+  const digest = digests.get(key);
+  if (digest !== undefined) {
+    return digest === releasedDigest ? { kind: 'unchanged' } : { kind: 'changed', reportKey: key };
+  }
+  const destination = moveDestination.get(key);
+  if (destination === undefined) return { kind: 'removed' };
+  return digests.get(destination) === releasedDigest
+    ? { kind: 'moved', destination }
+    : { kind: 'changed', reportKey: destination };
+}
+
+/**
+ * Displaced baseline declarations mapped to the single new path they may have
+ * moved to — or nothing when the move cannot be identified.
+ *
+ * A same-name re-declaration at exactly one new path is a file move, which a
+ * released peer still parses. One destination cannot be two declarations'
+ * moves, though: when two same-name baseline declarations left their paths and
+ * only one same-name new path exists, the other declaration's loss is real and
+ * only a bump covers it, so the contested destination resolves to removals. A
+ * same-name re-declaration whose digest MOVED is a change at the destination,
+ * ackable (digest-pinned, rationale required) rather than bump-forcing:
+ * textually it is indistinguishable from a removal plus a new same-named
+ * declaration, and that reading gets the ack escape hatch. Candidate paths are
+ * limited to ones absent from the baseline: names are not unique across files
+ * (two files both declare `sendJson`), and a name a baseline declaration still
+ * owns at its own path cannot identify a move.
+ */
+function soleMoveDestinations(
+  releasedDeclarations: Record<string, string>,
+  digests: ReadonlyMap<string, string>,
+): ReadonlyMap<string, string> {
+  const releasedKeys = new Set(Object.keys(releasedDeclarations));
+  const candidates = new Map<string, readonly string[]>();
+  for (const key of releasedKeys) {
+    if (digests.has(key)) continue;
+    const name = declarationName(key);
+    candidates.set(
+      key,
+      [...digests.keys()].filter(
+        (candidate) => declarationName(candidate) === name && !releasedKeys.has(candidate),
+      ),
+    );
+  }
+  const claimCount = new Map<string, number>();
+  for (const matches of candidates.values()) {
+    if (matches.length === 1) {
+      const destination = matches[0]!;
+      claimCount.set(destination, (claimCount.get(destination) ?? 0) + 1);
+    }
+  }
+  const sole = new Map<string, string>();
+  for (const [key, matches] of candidates) {
+    if (matches.length === 1 && claimCount.get(matches[0]!) === 1) {
+      sole.set(key, matches[0]!);
+    }
+  }
+  return sole;
+}
+
+/** The declaration name in a `<file>#<name>` key. */
+function declarationName(key: string): string {
+  const separator = key.lastIndexOf('#');
+  return separator >= 0 ? key.slice(separator + 1) : key;
 }

scripts/wire-compat/run.ts

@@ -88,5 +88,5 @@ process.stdout.write(
   `Daemon RPC wire surface checked against ${baseline.tag} ` +
     `(protocol ${result.bumped ? 'bumped' : 'unchanged'}): ${WIRE_DECLARATIONS.length} ` +
     `declarations, ${result.changed.length} changed, ${result.removed.length} removed, ` +
-    `${result.added.length} added.\n`,
+    `${result.added.length} added, ${result.moved.length} moved.\n`,
 );

test/wire-compat/ledger.json

@@ -1,6 +1,14 @@
 {
   "protocolVersion": 2,
   "declarations": {
+    "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_BASE_PATH": "sha256:a1ada25c6f90d9c69c8c836538e8882547bf239559f7c1accacd0654355802dd",
+    "packages/contracts/src/daemon-http.ts#DAEMON_HTTP_TENANT_HEADER": "sha256:ed49119d232500885f014ac73f6123d298d404c6c176abdae59cf324825927e5",
+    "packages/contracts/src/daemon-http.ts#DaemonHealthPayload": "sha256:050650184ad3e61d9359bf5866e7fc1e15e13f14f736a8c92ca57cad6d388967",
+    "packages/contracts/src/daemon-http.ts#buildDaemonHealthPayload": "sha256:709899c02b2a5f6ec2a995350ac7b5791d67db12a631b109af5074427291edda",
+    "packages/contracts/src/daemon-http.ts#buildDaemonHttpAuthHeaders": "sha256:5548a44d6248ed858d19a0b2985ec4ae8a7181bae8294b85edf3c1b3b58e80d4",
+    "packages/contracts/src/daemon-http.ts#buildDaemonHttpBaseUrl": "sha256:f92697208d9f42ec0dcfb006b6f2dce761bd5307db27ce2e52927fd7742e3a9a",
+    "packages/contracts/src/daemon-http.ts#buildDaemonHttpTenantHeaders": "sha256:e38a5f0b5ab07ee3a5fe3db229d0de750888660c55bf31692e100002be96de1d",
+    "packages/contracts/src/daemon-http.ts#buildDaemonHttpUrl": "sha256:d38f1f8877588fbcb1fea8c52a5cb7dc205043e3fc698b3d78fdcf821fa80471",
     "packages/contracts/src/request-progress.ts#CommandProgressEvent": "sha256:2dc6ff7f3b619d9b917210d47ebf9eee8095563389c8956b4e9f2bd994e1942d",
     "packages/contracts/src/request-progress.ts#ReplayTestProgressEvent": "sha256:61df00308d0e21f2acfc4f73cb2c07cd0c251e827f1c87628e2d08338e1b5c84",
     "packages/contracts/src/request-progress.ts#ReplayTestSuiteProgressEvent": "sha256:2d6599bfcf1e94596c61f85a8a986874b59b8c05e82e5e00dd31e381a5b0fe84",
@@ -64,18 +72,10 @@
     "src/daemon/downloadable-artifact-http.ts#readArtifactId": "sha256:3472ee52d951fdf7ef00ee500298602c68f0e1e3b8c44ff51b09981efabf348c",
     "src/daemon/downloadable-artifact-http.ts#readRequestPathname": "sha256:6b3a49c72365cf7da4552abef59862c073461f746025e28d409048815dd586f2",
     "src/daemon/downloadable-artifact-http.ts#resolveDownloadableArtifactHttpRoute": "sha256:9fcdc9619e8d378e8f04ef7b3584863af446e855702ddce83a16ec194a6d98af",
-    "src/daemon/http-contract.ts#DAEMON_HTTP_BASE_PATH": "sha256:a1ada25c6f90d9c69c8c836538e8882547bf239559f7c1accacd0654355802dd",
-    "src/daemon/http-contract.ts#DAEMON_HTTP_TENANT_HEADER": "sha256:ed49119d232500885f014ac73f6123d298d404c6c176abdae59cf324825927e5",
-    "src/daemon/http-contract.ts#buildDaemonHttpAuthHeaders": "sha256:5548a44d6248ed858d19a0b2985ec4ae8a7181bae8294b85edf3c1b3b58e80d4",
-    "src/daemon/http-contract.ts#buildDaemonHttpBaseUrl": "sha256:f92697208d9f42ec0dcfb006b6f2dce761bd5307db27ce2e52927fd7742e3a9a",
-    "src/daemon/http-contract.ts#buildDaemonHttpTenantHeaders": "sha256:e38a5f0b5ab07ee3a5fe3db229d0de750888660c55bf31692e100002be96de1d",
-    "src/daemon/http-contract.ts#buildDaemonHttpUrl": "sha256:d38f1f8877588fbcb1fea8c52a5cb7dc205043e3fc698b3d78fdcf821fa80471",
     "src/daemon/http-errors.ts#NormalizedHttpError": "sha256:2c2111802fe5f193acbeacc454de9cfab82bc8e4274b896f485e19a14f5518cf",
     "src/daemon/http-errors.ts#failStreamedHttpResponse": "sha256:7199933eca7244bc801e0601b17cc1aed584bc2353879830fd0686e99f1200c4",
     "src/daemon/http-errors.ts#sendRestJsonError": "sha256:981abb859649419604d555601b5c4bd6616e78215327e055e5f8023c6c15f556",
     "src/daemon/http-errors.ts#statusCodeForNormalizedError": "sha256:20ad272162e28425920bd2dcb4da5ec104bd7e8be2028b902b05bfa4da3df966",
-    "src/daemon/http-health.ts#DaemonHealthPayload": "sha256:050650184ad3e61d9359bf5866e7fc1e15e13f14f736a8c92ca57cad6d388967",
-    "src/daemon/http-health.ts#buildDaemonHealthPayload": "sha256:5eebf35539d04e3693bb6d7081ffdfcb0d2d8b7d53066e30ca6b4017fa4a55a3",
     "src/daemon/http-request-target.ts#decodeUriSegment": "sha256:b37622771ea4e61d1a9820169dbdc5809b5c38889bfad79277d7b22f3c3f1ef1",
     "src/daemon/request-diagnostics-http.ts#REQUEST_DIAGNOSTICS_CONTENT_TYPE": "sha256:16bbd9ae7eaeaaa8c8cbd6e65c4ce786a6c5230c5351288228bbf1a6f11bdcdc",
     "src/daemon/request-diagnostics-http.ts#RequestDiagnosticsHttpAuthorizer": "sha256:20761c39f434c675bb3405838dded5640bb623737957257e0452ebd46035eef1",
@@ -175,6 +175,11 @@
     "src/remote/upload-stream.ts#streamFileToHttpRequestAttempt": "sha256:da39a79fa7c1f81e55caf613eedc347c0f3a9a9711b265a4db185677532d9552"
   },
   "compatibleChanges": [
+    {
+      "declaration": "packages/contracts/src/daemon-http.ts#buildDaemonHealthPayload",
+      "digest": "sha256:709899c02b2a5f6ec2a995350ac7b5791d67db12a631b109af5074427291edda",
+      "rationale": "#2318 moves the daemon HTTP wire contract into @agent-device/contracts and hands buildDaemonHealthPayload the version its caller advertises instead of reading the package version itself. The added parameter is caller-local \u2014 each side passes its own readVersion() \u2014 and the /health payload a released peer sends or parses is byte-identical."
+    },
     {
       "declaration": "packages/kernel/src/contracts.ts#DaemonArtifactKnownType",
       "digest": "sha256:21886407c3fbc30d8c0c544503b831c78db2408aeaef1b9b2c6a4139144aef28",
@@ -183,7 +188,7 @@
     {
       "declaration": "src/remote/daemon-artifacts.ts#DownloadRemoteArtifactParams",
       "digest": "sha256:3ec63be2dbdb542e30b19d1500bc16874607823afb7ae392e92b0b535865859e",
-      "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state — never serialized, never sent to the daemon — that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before."
+      "rationale": "#2246 adds the optional isDirectory field. It is pure client-local state \u2014 never serialized, never sent to the daemon \u2014 that tells the CLIENT'S OWN download logic to extract a tar body instead of writing it verbatim; the GET /artifacts/:id request and response framing are unchanged. Every existing call site (screenshot, recording) omits it and keeps writing a single file exactly as before."
     },
     {
       "declaration": "src/remote/daemon-artifacts.ts#downloadRemoteArtifact",