Skip to content

Commit 185da6d

Browse files
committed
refactor(apple): give snapshot and fold one native-build owner
Move the shared native-build cache, toolchain identity, and build host out of snapshot-source into a domain-neutral packages/platform-apple/src /native-build module group, so the fold helper no longer imports the snapshot bridge's deadlines, errors, host construction, or host types to compile a binary that needs none of them. - native-build/{cache,deadline,host,toolchain-identity,errors}.ts carry the one cache implementation, one lock implementation, and one toolchain-identity read every runtime clang build in this package shares (#2796, #2712); NativeBuildHost exposes only file access, command execution, locking, and process identity, with no bridge socket start/connect and no target-process inspection. - NativeBuildError is domain-neutral (cancelled/timeout/unsupported); no shared build module imports SnapshotSourceError or emits bridge-specific error fields. snapshot-source/errors.ts and deadline.ts map it onto SnapshotSourceError at the boundary, and foldable/fold-helper-cache.ts maps it onto its own fold-helper-build-failed AppError, preserving both public error shapes byte for byte (see the moved and updated test suites). - fold-helper-cache.ts drops its whole-snapshot-host construction (building a full SnapshotSourceHost and overriding `run`) for createNativeBuildHost(runAppleToolCommand), the narrow host the compile actually needs. - snapshot-source/host.ts drops its own copy of the lock-acquisition implementation in favor of the shared one. - cache-identity.ts keeps only the bridge's simulatorRuntime addition; the toolchain retry/probe/cancellation logic it used to own moved to native-build/toolchain-identity.ts with its test coverage. Net production lines grow (+132 across the touched files, per `git diff --numstat -M`) because achieving actual decoupling needs a second, narrow error/deadline type and a translation boundary, not because anything was merely relocated: the whole-snapshot-host construction, the duplicate lock implementation, and the fold helper's dependency on the bridge's deadline/error/host types are all deleted, and NativeBuildHost's type now statically forbids a future build/cache change from reaching back into bridge-only capabilities. Live-validated on this Darwin host with the production code: a cache miss then a cache-key-stable cache hit for both the snapshot bridge (779ms build -> 127ms reuse) and the fold helper (2.9s build -> 2.2s reuse, dominated by the unchanged per-call toolchain probe) via ensureSnapshotBridgeBinary/ensureFoldHelperBinary directly. No Swift changes.
1 parent c58fe85 commit 185da6d

14 files changed

Lines changed: 858 additions & 651 deletions

File tree

‎packages/platform-apple/src/foldable/fold-helper-cache.ts‎

Lines changed: 26 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,19 @@
11
import path from 'node:path';
22
import { AppError } from '@agent-device/kernel/errors';
33
import { execFailureDetails } from '@agent-device/host-kit/command';
4+
import { hostHomeDirectory } from '@agent-device/host-kit/host-file';
5+
import { findProjectRoot } from '@agent-device/host-kit/version';
46
import { runAppleToolCommand } from '../core/tool-provider.ts';
57
import { COLD_TOOLCHAIN_PROBE_TIMEOUT_MS } from '../runner/apple-runner-platform.ts';
6-
import { readHostToolchainIdentity } from '../snapshot-source/cache-identity.ts';
7-
import {
8-
createSnapshotSourceDeadline,
9-
type SnapshotSourceDeadline,
10-
} from '../snapshot-source/deadline.ts';
11-
import { SnapshotSourceError } from '../snapshot-source/errors.ts';
12-
import { createSnapshotSourceHost } from '../snapshot-source/host.ts';
8+
import { createNativeBuildDeadline, type NativeBuildDeadline } from '../native-build/deadline.ts';
9+
import { NativeBuildError } from '../native-build/errors.ts';
10+
import { createNativeBuildHost, type NativeBuildHost } from '../native-build/host.ts';
11+
import { readHostToolchainIdentity } from '../native-build/toolchain-identity.ts';
1312
import {
1413
ensureNativeBuildCacheEntry,
1514
execNativeBuildClang,
1615
fingerprintNativeBuildSource,
17-
} from '../snapshot-source/native-build-cache.ts';
18-
import type { SnapshotSourceHost } from '../snapshot-source/types.ts';
16+
} from '../native-build/cache.ts';
1917

2018
const FOLD_HELPER_SOURCE_FILENAME = 'Fold.m';
2119
const FOLD_HELPER_BINARY_FILENAME = 'fold-helper';
@@ -33,9 +31,9 @@ const FOLD_HELPER_PREPARATION_DEADLINE_MS =
3331

3432
/**
3533
* The fold helper binary for the host's active toolchain, building and caching it if needed. Shares
36-
* the snapshot bridge's content+toolchain-keyed build cache (`native-build-cache.ts`), so a fold
34+
* the snapshot bridge's content+toolchain-keyed build cache (`native-build/cache.ts`), so a fold
3735
* call after the first serves a cached binary instead of recompiling `Fold.m`, and a `DEVELOPER_DIR`
38-
* switch busts the cache instead of serving a binary built against a different SDK (#2796).
36+
* switch busts the cache instead of serving a binary built against a different SDK (#2796, #2970).
3937
*
4038
* Build and cache failures surface as `AppError('COMMAND_FAILED', ..., {reason:
4139
* 'fold-helper-build-failed'})`, the error shape `sendSimulatorFoldPose` reported before this cache
@@ -44,15 +42,15 @@ const FOLD_HELPER_PREPARATION_DEADLINE_MS =
4442
export async function ensureFoldHelperBinary(
4543
input: Readonly<{
4644
signal?: AbortSignal;
47-
host?: SnapshotSourceHost;
45+
host?: NativeBuildHost;
4846
cacheRoot?: string;
4947
sourceRoot?: string;
5048
}> = {},
5149
): Promise<Readonly<{ path: string }>> {
5250
const host = input.host ?? createFoldHelperCacheHost();
53-
const deadline = createSnapshotSourceDeadline(FOLD_HELPER_PREPARATION_DEADLINE_MS, input.signal);
51+
const deadline = createNativeBuildDeadline(FOLD_HELPER_PREPARATION_DEADLINE_MS, input.signal);
5452
try {
55-
const sourceRoot = input.sourceRoot ?? path.join(host.projectRoot(), 'apple', 'fold-helper');
53+
const sourceRoot = input.sourceRoot ?? path.join(findProjectRoot(), 'apple', 'fold-helper');
5654
const sourceHash = await fingerprintNativeBuildSource(
5755
host,
5856
sourceRoot,
@@ -61,7 +59,7 @@ export async function ensureFoldHelperBinary(
6159
);
6260
const toolchain = await readHostToolchainIdentity(host, deadline);
6361
const cacheRoot =
64-
input.cacheRoot ?? path.join(host.homeDirectory(), '.agent-device', 'fold-helper');
62+
input.cacheRoot ?? path.join(hostHomeDirectory(), '.agent-device', 'fold-helper');
6563
return await ensureNativeBuildCacheEntry({
6664
host,
6765
deadline,
@@ -82,14 +80,12 @@ export async function ensureFoldHelperBinary(
8280
}
8381
}
8482

85-
function createFoldHelperCacheHost(): SnapshotSourceHost {
86-
const real = createSnapshotSourceHost();
87-
return {
88-
...real,
89-
// Routed through the Apple tool-provider scope, not `run`'s default `runCmd`, so a fold test
90-
// can fake every exec this cache makes the same way it fakes the simctl dispatch (#2796).
91-
run: (command, args, options) => runAppleToolCommand(command, args, options),
92-
};
83+
function createFoldHelperCacheHost(): NativeBuildHost {
84+
// Routed through the Apple tool-provider scope, not `run`'s default `runCmd`, so a fold test can
85+
// fake every exec this cache makes the same way it fakes the simctl dispatch (#2796). A narrow
86+
// build host, not the full snapshot-bridge host: compilation needs no bridge socket and no
87+
// target-process inspection (#2970).
88+
return createNativeBuildHost(runAppleToolCommand);
9389
}
9490

9591
/**
@@ -119,8 +115,8 @@ export function buildFoldHelperCompileArgv(
119115
}
120116

121117
async function compileFoldHelper(
122-
host: SnapshotSourceHost,
123-
deadline: SnapshotSourceDeadline,
118+
host: NativeBuildHost,
119+
deadline: NativeBuildDeadline,
124120
sourceRoot: string,
125121
outputPath: string,
126122
): Promise<void> {
@@ -137,13 +133,13 @@ async function compileFoldHelper(
137133
}
138134

139135
/**
140-
* Rewraps a cache failure as the fold helper's build error, keeping its hint and typed details; a
141-
* cancellation, and any error that is not a snapshot-source failure, passes through unchanged.
136+
* Rewraps a native-build cache failure as the fold helper's build error, keeping its hint and typed
137+
* details; a cancellation, and any error that is not a native-build failure (including the fold
138+
* helper's own `foldHelperBuildFailed`, already in its public shape), passes through unchanged.
142139
*/
143140
function asFoldHelperCacheError(error: unknown): unknown {
144-
if (!(error instanceof SnapshotSourceError) || error.failureKind === 'cancelled') return error;
145-
const { bridgeFailure: _kind, bridgeFailureCode: cause, ...details } = error.details ?? {};
146-
return foldHelperBuildFailed({ ...details, cause }, error);
141+
if (!(error instanceof NativeBuildError) || error.buildFailureKind === 'cancelled') return error;
142+
return foldHelperBuildFailed({ ...error.buildDetails, cause: error.buildFailureCode }, error);
147143
}
148144

149145
function foldHelperBuildFailed(details: Readonly<Record<string, unknown>>, cause?: unknown) {

packages/platform-apple/src/snapshot-source/native-build-cache.test.ts renamed to packages/platform-apple/src/native-build/cache.test.ts

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,26 @@ import assert from 'node:assert/strict';
22
import { readdir, readFile, writeFile } from 'node:fs/promises';
33
import path from 'node:path';
44
import { test } from 'vitest';
5+
import { runCmd } from '@agent-device/host-kit/command';
56
import { mkdtempForTest } from '../__tests__/tmp-dir.ts';
6-
import { createSnapshotSourceDeadline } from './deadline.ts';
7-
import { createSnapshotSourceHost } from './host.ts';
8-
import { ensureNativeBuildCacheEntry, fingerprintNativeBuildSource } from './native-build-cache.ts';
9-
import type { SnapshotSourceHost } from './types.ts';
7+
import { createNativeBuildDeadline } from './deadline.ts';
8+
import { createNativeBuildHost, type NativeBuildHost } from './host.ts';
9+
import { ensureNativeBuildCacheEntry, fingerprintNativeBuildSource } from './cache.ts';
1010

1111
function testDeadline() {
12-
return createSnapshotSourceDeadline(30_000, undefined);
12+
return createNativeBuildDeadline(30_000, undefined);
13+
}
14+
15+
function testHost(): NativeBuildHost {
16+
return createNativeBuildHost(
17+
async (command, args, options) => await runCmd(command, args, options),
18+
);
1319
}
1420

1521
test('a cache hit skips the build, and a key-input or binary change rebuilds', async () => {
1622
const root = await mkdtempForTest('agent-device-native-build-cache-');
1723
const cacheRoot = path.join(root, 'cache');
18-
const host = createSnapshotSourceHost();
24+
const host = testHost();
1925
let builds = 0;
2026

2127
const ensure = (keyInputs: Readonly<Record<string, unknown>> = { sourceHash: 'abc' }) =>
@@ -57,7 +63,7 @@ test('a cache hit skips the build, and a key-input or binary change rebuilds', a
5763
test('a failed build leaves no cache entry, and a later call can retry', async () => {
5864
const root = await mkdtempForTest('agent-device-native-build-cache-failure-');
5965
const cacheRoot = path.join(root, 'cache');
60-
const host = createSnapshotSourceHost();
66+
const host = testHost();
6167
let attempts = 0;
6268

6369
const ensure = () =>
@@ -89,7 +95,7 @@ test('a failed build leaves no cache entry, and a later call can retry', async (
8995

9096
test('fingerprintNativeBuildSource keys on filename as well as content, so a rename busts the cache', async () => {
9197
const root = await mkdtempForTest('agent-device-native-fingerprint-');
92-
const host: SnapshotSourceHost = createSnapshotSourceHost();
98+
const host = testHost();
9399
await (await import('@agent-device/host-kit/host-file')).ensureHostDirectory(root);
94100
await writeFile(path.join(root, 'A.m'), 'same content');
95101
await writeFile(path.join(root, 'B.m'), 'same content');

packages/platform-apple/src/snapshot-source/native-build-cache.ts renamed to packages/platform-apple/src/native-build/cache.ts

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ import { createHash } from 'node:crypto';
22
import path from 'node:path';
33
import { withProcessLock } from '@agent-device/host-kit/file';
44
import { isCommandTimeoutError, type ExecResult } from '@agent-device/host-kit/command';
5-
import { remainingSnapshotSourceMs, type SnapshotSourceDeadline } from './deadline.ts';
6-
import { SnapshotSourceError, snapshotSourceError } from './errors.ts';
7-
import type { SnapshotSourceHost } from './types.ts';
5+
import { remainingNativeBuildMs, type NativeBuildDeadline } from './deadline.ts';
6+
import { NativeBuildError, nativeBuildError } from './errors.ts';
7+
import type { NativeBuildHost } from './host.ts';
88

99
const MANIFEST_FILENAME = 'manifest.json';
1010

@@ -15,12 +15,12 @@ export type NativeBuildCacheEntry = Readonly<{ path: string; cacheKey: string }>
1515
* against its manifest's key and binary hash, a miss builds into a temp directory and publishes it
1616
* with an atomic rename, and a build that fails leaves no partial entry behind. Every runtime clang
1717
* build in this package shares this mechanism so a stale entry, a corrupt cache, or a
18-
* `DEVELOPER_DIR` switch is handled once (#2796).
18+
* `DEVELOPER_DIR` switch is handled once (#2796, #2970).
1919
*/
2020
export async function ensureNativeBuildCacheEntry(
2121
input: Readonly<{
22-
host: SnapshotSourceHost;
23-
deadline: SnapshotSourceDeadline;
22+
host: NativeBuildHost;
23+
deadline: NativeBuildDeadline;
2424
cacheRoot: string;
2525
binaryFilename: string;
2626
/** Names the contended resource in a lock-stall diagnostic; every caller states its own. */
@@ -46,27 +46,27 @@ export async function ensureNativeBuildCacheEntry(
4646
task: async () => {
4747
const cached = await readValidCacheEntry(host, entryPath, binaryFilename, cacheKey, deadline);
4848
if (cached) return { path: cached, cacheKey };
49-
remainingSnapshotSourceMs(deadline, 'native-build-deadline');
49+
remainingNativeBuildMs(deadline, 'native-build-deadline');
5050
if (host.exists(entryPath)) await host.remove(entryPath);
51-
remainingSnapshotSourceMs(deadline, 'native-build-deadline');
51+
remainingNativeBuildMs(deadline, 'native-build-deadline');
5252
await host.ensureDirectory(cacheRoot);
5353
const temporaryPath = path.join(cacheRoot, `.${cacheKey}.${host.processId()}.tmp`);
54-
remainingSnapshotSourceMs(deadline, 'native-build-deadline');
54+
remainingNativeBuildMs(deadline, 'native-build-deadline');
5555
await host.remove(temporaryPath);
5656
try {
57-
remainingSnapshotSourceMs(deadline, 'native-build-deadline');
57+
remainingNativeBuildMs(deadline, 'native-build-deadline');
5858
await host.ensureDirectory(temporaryPath);
5959
const outputPath = path.join(temporaryPath, binaryFilename);
6060
await input.build(outputPath);
61-
remainingSnapshotSourceMs(deadline, 'native-build-deadline');
61+
remainingNativeBuildMs(deadline, 'native-build-deadline');
6262
await host.chmod(outputPath, 0o755);
6363
const binarySha256 = await sha256File(host, outputPath);
6464
const manifest = { ...input.keyInputs, cacheKey, binarySha256 };
6565
await host.writeText(
6666
path.join(temporaryPath, MANIFEST_FILENAME),
6767
`${JSON.stringify(manifest, null, 2)}\n`,
6868
);
69-
remainingSnapshotSourceMs(deadline, 'native-build-deadline');
69+
remainingNativeBuildMs(deadline, 'native-build-deadline');
7070
await host.rename(temporaryPath, entryPath);
7171
return { path: path.join(entryPath, binaryFilename), cacheKey };
7272
} catch (error) {
@@ -78,11 +78,11 @@ export async function ensureNativeBuildCacheEntry(
7878
}
7979

8080
async function readValidCacheEntry(
81-
host: SnapshotSourceHost,
81+
host: NativeBuildHost,
8282
entryPath: string,
8383
binaryFilename: string,
8484
cacheKey: string,
85-
deadline: SnapshotSourceDeadline,
85+
deadline: NativeBuildDeadline,
8686
): Promise<string | undefined> {
8787
const binaryPath = path.join(entryPath, binaryFilename);
8888
const manifestPath = path.join(entryPath, MANIFEST_FILENAME);
@@ -92,7 +92,7 @@ async function readValidCacheEntry(
9292
if (manifest.cacheKey !== cacheKey || typeof manifest.binarySha256 !== 'string') {
9393
return undefined;
9494
}
95-
remainingSnapshotSourceMs(deadline, 'native-cache-hash-deadline');
95+
remainingNativeBuildMs(deadline, 'native-cache-hash-deadline');
9696
const matchesBinary = (await sha256File(host, binaryPath)) === manifest.binarySha256;
9797
return matchesBinary ? binaryPath : undefined;
9898
} catch (error) {
@@ -104,12 +104,12 @@ async function readValidCacheEntry(
104104
/** Distinguishes a real cache-read failure (corrupt entry, stale manifest) from a caller cancellation or deadline. */
105105
function isCacheReadCancellationOrTimeout(error: unknown): boolean {
106106
return (
107-
error instanceof SnapshotSourceError &&
108-
(error.failureKind === 'cancelled' || error.failureKind === 'timeout')
107+
error instanceof NativeBuildError &&
108+
(error.buildFailureKind === 'cancelled' || error.buildFailureKind === 'timeout')
109109
);
110110
}
111111

112-
async function sha256File(host: SnapshotSourceHost, filePath: string): Promise<string> {
112+
async function sha256File(host: NativeBuildHost, filePath: string): Promise<string> {
113113
return createHash('sha256')
114114
.update(await host.readBinary(filePath))
115115
.digest('hex');
@@ -121,17 +121,17 @@ async function sha256File(host: SnapshotSourceHost, filePath: string): Promise<s
121121
* way, over its own filename list (#2796).
122122
*/
123123
export async function fingerprintNativeBuildSource(
124-
host: SnapshotSourceHost,
124+
host: NativeBuildHost,
125125
root: string,
126126
sourceFilenames: readonly string[],
127-
deadline: SnapshotSourceDeadline,
127+
deadline: NativeBuildDeadline,
128128
): Promise<string> {
129129
const hash = createHash('sha256');
130130
for (const sourceFile of sourceFilenames) {
131131
const filePath = path.join(root, sourceFile);
132-
remainingSnapshotSourceMs(deadline, 'native-source-fingerprint-deadline');
132+
remainingNativeBuildMs(deadline, 'native-source-fingerprint-deadline');
133133
if (!host.exists(filePath)) {
134-
throw snapshotSourceError('unsupported', 'native-source-missing', { filePath });
134+
throw nativeBuildError('unsupported', 'native-source-missing', { filePath });
135135
}
136136
hash.update(sourceFile);
137137
hash.update('\0');
@@ -148,8 +148,8 @@ export async function fingerprintNativeBuildSource(
148148
*/
149149
export async function execNativeBuildClang(
150150
input: Readonly<{
151-
host: SnapshotSourceHost;
152-
deadline: SnapshotSourceDeadline;
151+
host: NativeBuildHost;
152+
deadline: NativeBuildDeadline;
153153
argv: readonly string[];
154154
budgetMs: number;
155155
/** Names the build in the stall hint, e.g. "bridge" or "fold helper". */
@@ -158,7 +158,7 @@ export async function execNativeBuildClang(
158158
): Promise<ExecResult> {
159159
const timeoutMs = Math.min(
160160
input.budgetMs,
161-
remainingSnapshotSourceMs(input.deadline, 'native-build-deadline'),
161+
remainingNativeBuildMs(input.deadline, 'native-build-deadline'),
162162
);
163163
try {
164164
return await input.host.run('xcrun', [...input.argv], {
@@ -168,7 +168,7 @@ export async function execNativeBuildClang(
168168
});
169169
} catch (error) {
170170
if (!isCommandTimeoutError(error)) throw error;
171-
throw snapshotSourceError(
171+
throw nativeBuildError(
172172
'timeout',
173173
'native-build-stalled',
174174
{
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import { Deadline } from '@agent-device/host-kit/retry';
2+
import { nativeBuildError } from './errors.ts';
3+
4+
export type NativeBuildDeadline = Readonly<{
5+
clock: Deadline;
6+
/** The clock the deadline is read against; injected so a test can move time. */
7+
now: () => number;
8+
signal: AbortSignal | undefined;
9+
}>;
10+
11+
export function createNativeBuildDeadline(
12+
timeoutMs: number,
13+
signal: AbortSignal | undefined,
14+
now: () => number = Date.now,
15+
): NativeBuildDeadline {
16+
if (signal?.aborted) throw nativeBuildError('cancelled', 'abort-signal');
17+
return { clock: Deadline.fromTimeoutMs(timeoutMs, now()), now, signal };
18+
}
19+
20+
export function remainingNativeBuildMs(deadline: NativeBuildDeadline, code: string): number {
21+
if (deadline.signal?.aborted) throw nativeBuildError('cancelled', 'abort-signal');
22+
const remainingMs = deadline.clock.remainingMs(deadline.now());
23+
if (remainingMs <= 0) throw nativeBuildError('timeout', code);
24+
return Math.max(1, Math.floor(remainingMs));
25+
}
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { AppError } from '@agent-device/kernel/errors';
2+
3+
export type NativeBuildFailureKind = 'cancelled' | 'timeout' | 'unsupported';
4+
5+
/**
6+
* Domain-neutral: carries a build/cache fact (cancellation, timeout, unsupported host) with no
7+
* knowledge of the snapshot bridge protocol or the fold helper's public error shape. Every consumer
8+
* maps this to its own error type instead of this module knowing either one (#2970).
9+
*/
10+
export class NativeBuildError extends AppError {
11+
readonly buildFailureKind: NativeBuildFailureKind;
12+
readonly buildFailureCode: string;
13+
/** The details this error was constructed with, before this class's own kind/code stamps. */
14+
readonly buildDetails: Readonly<Record<string, unknown>>;
15+
16+
constructor(
17+
kind: NativeBuildFailureKind,
18+
code: string,
19+
message = `native build ${kind}: ${code}`,
20+
details: Readonly<Record<string, unknown>> = {},
21+
cause?: unknown,
22+
) {
23+
super(
24+
'COMMAND_FAILED',
25+
message,
26+
{ ...details, nativeBuildFailure: kind, nativeBuildFailureCode: code },
27+
cause,
28+
);
29+
this.name = 'NativeBuildError';
30+
this.buildFailureKind = kind;
31+
this.buildFailureCode = code;
32+
this.buildDetails = details;
33+
}
34+
}
35+
36+
export function nativeBuildError(
37+
kind: NativeBuildFailureKind,
38+
code: string,
39+
details: Readonly<Record<string, unknown>> = {},
40+
cause?: unknown,
41+
): NativeBuildError {
42+
return new NativeBuildError(kind, code, undefined, details, cause);
43+
}

0 commit comments

Comments
 (0)