Skip to content

Commit f5da8d6

Browse files
committed
refactor(replay): lock the ad-replay façade to its real consumers (#1478 P5)
1 parent e159587 commit f5da8d6

6 files changed

Lines changed: 147 additions & 66 deletions

File tree

‎fallow-baselines/health.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,14 @@
1818
"count": 1
1919
}
2020
},
21+
"src/__tests__/test-utils/in-memory-replay-selector-port.ts": {
22+
"complexity_moderate": {
23+
"count": 2
24+
},
25+
"crap_moderate": {
26+
"count": 2
27+
}
28+
},
2129
"src/cli-schema/cli-config.ts": {
2230
"crap_moderate": {
2331
"count": 1

‎packages/ad-replay/package.json‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,6 @@
1414
".": {
1515
"types": "./src/index.ts",
1616
"default": "./src/index.ts"
17-
},
18-
"./testing": {
19-
"types": "./src/internal/testing/in-memory-selector-port.ts",
20-
"default": "./src/internal/testing/in-memory-selector-port.ts"
2117
}
2218
}
2319
}

‎packages/ad-replay/src/index.ts‎

Lines changed: 88 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,29 @@
11
/**
2-
* The `ad-replay` package façade (#1478 P5 stage A).
2+
* The `ad-replay` package façade (#1478 P5 stage D — narrowed).
33
*
4-
* STAGE-A WIDE FAÇADE — TEMPORARY. This re-exports every symbol carried over
5-
* by the mechanical move so root consumers keep working unchanged apart from
6-
* their import specifier. It is not the intended final shape: a later stage
7-
* narrows this façade to `inspectAdReplay`/`runAdReplay` once the daemon
8-
* handlers and runtime wiring move into this package too. Do not treat the
9-
* current export list as a design decision — it is scaffolding.
4+
* The binding design (issue comment 5156017698) is `inspectAdReplay` +
5+
* `runAdReplay` and nothing else. Staged reality is wider than that: the
6+
* daemon wire-builders and handlers call several engine POLICY functions
7+
* directly rather than only through the two entrypoints (var substitution,
8+
* plan-digest, target-identity/-verification, report shaping). Every export
9+
* below is a `façade-deviation` from the binding-design ideal EXCEPT
10+
* `inspectAdReplay`/`runAdReplay` themselves; each deviation names its real
11+
* root consumer(s) so the PR body's deviation table is generated straight
12+
* from this file. No selector AST, no engine IR, no prepared-plan type, and
13+
* no internal subpath is exported — everything here has a live import site
14+
* outside this package (see `packages/ad-replay/src/index.ts`'s sibling
15+
* consumer grep in the P5 stage D commit message for the full map).
1016
*/
1117

18+
// ---------------------------------------------------------------------------
19+
// vars.ts — `.ad` variable substitution surface.
20+
// façade-deviation: the daemon resolves an action's variables directly
21+
// (`session-replay-target-verification.ts`, `session-replay-action-runtime.ts`)
22+
// and builds/collects env-derived scopes outside the step loop
23+
// (`session-replay-runtime.ts`, `session-replay-maestro-runtime.ts`,
24+
// `session-replay-runtime-failure.ts`) instead of only receiving resolved
25+
// actions back from `runAdReplay`.
26+
// ---------------------------------------------------------------------------
1227
export {
1328
buildReplayVarScope,
1429
collectReplayScrubbableVarValues,
@@ -17,26 +32,44 @@ export {
1732
readReplayCliEnvEntries,
1833
readReplayShellEnvSource,
1934
resolveReplayAction,
20-
resolveReplayString,
2135
} from './internal/vars.ts';
22-
export type { ReplayVarScope, ReplayVarSources } from './internal/vars.ts';
36+
export type { ReplayVarScope } from './internal/vars.ts';
2337

38+
// ---------------------------------------------------------------------------
39+
// plan-digest.ts — the `--from`/`--plan-digest` resume and save-script digest.
40+
// façade-deviation: `session-replay-runtime-plan.ts`'s resume path and
41+
// `request-router-repair-expired.test.ts` compute/read the digest directly,
42+
// ahead of and independent from any `runAdReplay` call.
43+
// ---------------------------------------------------------------------------
2444
export { computeReplayPlanDigest } from './internal/plan-digest.ts';
2545
export type { ReplayPlanDigestMetadata } from './internal/plan-digest.ts';
2646

47+
// ---------------------------------------------------------------------------
48+
// inspect.ts — the read-only `.ad` manifest reader. On-design: this IS one
49+
// of the two binding-design entrypoints.
50+
// ---------------------------------------------------------------------------
2751
export { inspectAdReplay } from './internal/inspect.ts';
2852
export type { AdReplayManifest } from './internal/inspect.ts';
2953

54+
// ---------------------------------------------------------------------------
55+
// step-loop.ts — the `.ad` step loop. On-design: this IS the other binding-
56+
// design entrypoint; `AdReplayStepRuntime` is the runtime capability bag the
57+
// daemon adapter (`session-replay-runtime.ts`) implements to thread it.
58+
// ---------------------------------------------------------------------------
3059
export { formatReplaySuccessMessage, runAdReplay } from './internal/step-loop.ts';
31-
export type {
32-
AdReplayProgressSink,
33-
AdReplayProgressStep,
34-
AdReplayResponse,
35-
AdReplayRunOutcome,
36-
AdReplayRunRequest,
37-
AdReplayStepRuntime,
38-
} from './internal/step-loop.ts';
60+
export type { AdReplayStepRuntime } from './internal/step-loop.ts';
3961

62+
// ---------------------------------------------------------------------------
63+
// target-identity.ts — record/replay local-identity primitives (ADR 0012
64+
// decision 3).
65+
// façade-deviation: the record-time writer (`src/daemon/session-target-evidence.ts`)
66+
// and replay-time classification core (`session-replay-target-classification.ts`)
67+
// call these identity functions directly so both sides compute the SAME
68+
// ordinal by construction; `wait`'s landmark poll
69+
// (`src/commands/interaction/runtime/selector-wait.ts`) and the shared
70+
// replay-zone tree helpers (`src/replay/target-evidence-tree.ts`,
71+
// `src/replay/target-identity-node.ts`) also call in below `runAdReplay`.
72+
// ---------------------------------------------------------------------------
4073
export {
4174
annotationLocalIdentity,
4275
classifyTargetBindingMatch,
@@ -45,49 +78,57 @@ export {
4578
matchesAncestryPrefix,
4679
matchesLocalIdentity,
4780
} from './internal/target-identity.ts';
48-
export type {
49-
LocalIdentity,
50-
TargetBindingClassification,
51-
TargetBindingClassificationInput,
52-
} from './internal/target-identity.ts';
81+
export type { LocalIdentity } from './internal/target-identity.ts';
5382

54-
// #1478 P5 stage C2a: the target-verification ENGINE policy split out of
55-
// `session-replay-target-verification.ts` — pre-capture verification gating
56-
// and post-dispatch mismatch-evidence derivation. See
57-
// `./internal/target-verification.ts` for the daemon/engine ownership split.
83+
// ---------------------------------------------------------------------------
84+
// target-verification.ts — #1478 P5 stage C2a target-verification ENGINE
85+
// policy (pre-capture verification gating, post-dispatch mismatch-evidence
86+
// derivation), split out of `session-replay-target-verification.ts`.
87+
// façade-deviation: that same daemon wire-builder is the direct caller of
88+
// all four functions below — see `./internal/target-verification.ts` for the
89+
// daemon/engine ownership split.
90+
// ---------------------------------------------------------------------------
5891
export {
5992
deriveReplayTargetGuardMismatchEvidence,
6093
deriveWaitLandmarkMismatchEvidence,
61-
describeStructuralMismatch,
6294
planPostResolutionTargetVerification,
6395
planPreDispatchTargetVerification,
64-
readAncestryEntries,
65-
readGuardMismatchObservedIdentity,
66-
} from './internal/target-verification.ts';
67-
export type {
68-
ReplayPostDispatchMismatchEvidence,
69-
ReplayPostResolutionVerificationPlan,
70-
ReplayPreDispatchVerificationPlan,
7196
} from './internal/target-verification.ts';
97+
export type { ReplayPostDispatchMismatchEvidence } from './internal/target-verification.ts';
7298

99+
// ---------------------------------------------------------------------------
100+
// session-replay-report-action.ts / session-replay-suggestion-ranking.ts —
101+
// the divergence-report action shape and repair-suggestion ranking.
102+
// façade-deviation: `session-replay-maestro-failure.ts`, `session-replay-heal.ts`,
103+
// and `session-replay-divergence.ts` build/rank divergence reports directly;
104+
// none of this rides back through `runAdReplay`'s return value.
105+
// ---------------------------------------------------------------------------
73106
export type { ReplayReportAction } from './internal/session-replay-report-action.ts';
74-
75107
export { rankAndDedupeReplaySuggestions } from './internal/session-replay-suggestion-ranking.ts';
76108

77-
// #1478 P5 stage B: the port TYPE only — root's production adapter
78-
// (`src/daemon/replay-selector-port.ts`) implements it against
79-
// `ReplaySelectorPort`'s three operations. The type is what rides in via
80-
// `runAdReplay`'s runtime parameter once the daemon threads it (stage C); no
81-
// selector AST type is ever exported here.
109+
// ---------------------------------------------------------------------------
110+
// selector-port.ts — the `ReplaySelectorPort` port TYPE only (#1478 P5 stage
111+
// B, the amendment's explicit rejection of a "seven-function selector-AST
112+
// mirror"). Two adapters implement it: the production adapter
113+
// (`src/daemon/replay-selector-port.ts`) and the in-memory adapter for this
114+
// package's own contract suite, relocated to
115+
// `src/__tests__/test-utils/in-memory-replay-selector-port.ts` (#1478 P5
116+
// stage D — package-internal code may not "reach back into root `src/`",
117+
// R11, so the adapter could not stay inside `packages/ad-replay` once its
118+
// only remaining consumer was a root test).
119+
// façade-deviation: daemon handlers thread `ReplaySelectorPort` values
120+
// directly (`session-replay-target-token.ts`, `session-replay-heal.ts`,
121+
// `session-replay-target-classification.ts`, `session-replay-runtime-failure.ts`,
122+
// `session-replay-runtime.ts`, `session-replay-target-verification.ts`) —
123+
// the port rides in as `runAdReplay`'s runtime threads it, but the type
124+
// itself is named at every one of those call sites.
125+
// ---------------------------------------------------------------------------
82126
export type {
83-
ReplaySelectorPort,
84-
ReplaySelectorGrammar,
85-
ReplaySelectorExpressionOutcome,
86-
ReplayRecordedTargetPolicy,
87127
ReplayRecordedTargetDisambiguation,
88-
ReplayRecordedTargetResolved,
89-
ReplayRecordedTargetUnresolved,
128+
ReplayRecordedTargetPolicy,
90129
ReplayRecordedTargetResolution,
91-
ReplaySelectorCandidateAction,
92130
ReplaySelectorCandidateOptions,
131+
ReplaySelectorExpressionOutcome,
132+
ReplaySelectorGrammar,
133+
ReplaySelectorPort,
93134
} from './internal/selector-port.ts';

‎scripts/layering/package-boundaries.test.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,19 @@ test('the real tree parses, declares, and passes R11', () => {
228228
'@agent-device/contracts',
229229
'@agent-device/kernel',
230230
]);
231+
const adReplayPackage = packages.find((pkg) => pkg.name === '@agent-device/ad-replay');
232+
assert.ok(adReplayPackage, 'ad-replay package must exist');
233+
// Locks the "exports only `.`" boundary: the stage-A wide façade and the
234+
// `./testing` subpath (the in-memory selector-port adapter, relocated to
235+
// `src/__tests__/test-utils/`) are both gone as of P5 stage D — a future
236+
// `./testing` (or any other) subpath widens this key list and fails the
237+
// assertion.
238+
assert.deepEqual([...adReplayPackage.exportTargets.keys()], ['@agent-device/ad-replay']);
239+
assert.deepEqual([...adReplayPackage.workspaceDependencies].sort(), [
240+
'@agent-device/ad-script',
241+
'@agent-device/contracts',
242+
'@agent-device/kernel',
243+
]);
231244
const providerWebDriverPackage = packages.find(
232245
(pkg) => pkg.name === '@agent-device/provider-webdriver',
233246
);
@@ -283,6 +296,10 @@ test('the real tree parses, declares, and passes R11', () => {
283296
rootWorkspaceDependencyNames(repoRoot).has('@agent-device/ad-script'),
284297
'root must declare the ad-script workspace dependency',
285298
);
299+
assert.ok(
300+
rootWorkspaceDependencyNames(repoRoot).has('@agent-device/ad-replay'),
301+
'root must declare the ad-replay workspace dependency',
302+
);
286303
assert.ok(
287304
rootWorkspaceDependencyNames(repoRoot).has('@agent-device/provider-webdriver'),
288305
'root must declare the provider-webdriver workspace dependency',
@@ -320,6 +337,9 @@ test('Node resolution enforces the exports map at runtime', () => {
320337
'@agent-device/ad-script/codec',
321338
'@agent-device/ad-script/internal/script.ts',
322339
'@agent-device/ad-script/src/index.ts',
340+
'@agent-device/ad-replay/testing',
341+
'@agent-device/ad-replay/internal/target-verification.ts',
342+
'@agent-device/ad-replay/src/index.ts',
323343
]) {
324344
assert.throws(
325345
() => import.meta.resolve(deep),
@@ -347,4 +367,6 @@ test('Node resolution enforces the exports map at runtime', () => {
347367
assert.ok(xmlResolved.endsWith('packages/xml/src/index.ts'), xmlResolved);
348368
const adScriptResolved = import.meta.resolve('@agent-device/ad-script');
349369
assert.ok(adScriptResolved.endsWith('packages/ad-script/src/index.ts'), adScriptResolved);
370+
const adReplayResolved = import.meta.resolve('@agent-device/ad-replay');
371+
assert.ok(adReplayResolved.endsWith('packages/ad-replay/src/index.ts'), adReplayResolved);
350372
});

packages/ad-replay/src/internal/testing/in-memory-selector-port.ts renamed to src/__tests__/test-utils/in-memory-replay-selector-port.ts

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,30 @@ import type {
77
ReplaySelectorExpressionOutcome,
88
ReplaySelectorGrammar,
99
ReplaySelectorPort,
10-
} from '../selector-port.ts';
10+
} from '@agent-device/ad-replay';
1111

1212
/**
1313
* #1478 P5 stage B: a deterministic, dependency-free `ReplaySelectorPort`
1414
* adapter for `packages/ad-replay`'s own contract suite
15-
* (`selector-port-contract.test.ts`). It honors the SAME contract as the
16-
* production adapter (`src/daemon/replay-selector-port.ts`) — result shapes,
17-
* tagged reasons, and the same-alternative winner+domain invariant — over a
18-
* tiny in-memory matcher instead of the real `src/selectors` grammar and
19-
* resolution engine. Deliberately NOT reproduced: quoting edge cases beyond
20-
* `key="value"`, every selector key, and the #1269 shared-id demotion — the
21-
* contract is about shapes and invariants, not grammar richness.
15+
* (`replay-selector-port-contract.test.ts`). It honors the SAME contract as
16+
* the production adapter (`src/daemon/replay-selector-port.ts`) — result
17+
* shapes, tagged reasons, and the same-alternative winner+domain invariant —
18+
* over a tiny in-memory matcher instead of the real `src/selectors` grammar
19+
* and resolution engine. Deliberately NOT reproduced: quoting edge cases
20+
* beyond `key="value"`, every selector key, and the #1269 shared-id demotion
21+
* — the contract is about shapes and invariants, not grammar richness.
22+
*
23+
* #1478 P5 stage D: relocated here from
24+
* `packages/ad-replay/src/internal/testing/in-memory-selector-port.ts`. It
25+
* only ever needed the exported `ReplaySelectorPort` port type and kernel
26+
* snapshot types — never a package-internal module — so once its only
27+
* consumer (`src/daemon/__tests__/replay-selector-port-contract.test.ts`)
28+
* turned out to be a root test (R11: only root may import the production
29+
* adapter, since a workspace package may never reach back into root `src/`),
30+
* keeping the adapter itself inside `packages/ad-replay` bought nothing: it
31+
* moved alongside its only caller, following the same
32+
* `src/__tests__/test-utils/` convention as `store-factory.ts` and
33+
* `session-factories.ts`.
2234
*
2335
* Mini expression grammar: `key="value"` terms (space-separated, ANDed),
2436
* alternatives joined by ` || ` (first-match-wins, same as the real chain).

‎src/daemon/__tests__/replay-selector-port-contract.test.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,13 @@
22
* #1478 P5 stage B: the `ReplaySelectorPort` contract (issue comment
33
* 5156017698's amendment), run against BOTH adapters — the production
44
* adapter (`../replay-selector-port.ts`, delegating to `src/selectors`) and
5-
* the package's deterministic in-memory adapter
6-
* (`@agent-device/ad-replay/testing`). This suite lives in root, not in
7-
* `packages/ad-replay`, because only root can import the production adapter
8-
* (R11 package-boundaries: a workspace package may never reach back into
9-
* root `src/`).
5+
* the deterministic in-memory adapter
6+
* (`../../__tests__/test-utils/in-memory-replay-selector-port.ts`, relocated
7+
* there in P5 stage D). This suite lives in root, not in `packages/ad-replay`,
8+
* because only root can import the production adapter (R11 package-boundaries:
9+
* a workspace package may never reach back into root `src/`) — the same
10+
* reason the in-memory adapter itself had to move to root once this was its
11+
* only consumer.
1012
*
1113
* Every scenario below is expressed in the in-memory adapter's documented
1214
* mini expression grammar (`key="value"` terms, ` || ` alternatives, keys
@@ -21,12 +23,12 @@ import assert from 'node:assert/strict';
2123
import { describe, test } from 'vitest';
2224
import type { SnapshotNode } from '@agent-device/kernel/snapshot';
2325
import type { ReplaySelectorPort } from '@agent-device/ad-replay';
24-
import { createInMemoryReplaySelectorPort } from '@agent-device/ad-replay/testing';
26+
import { createInMemoryReplaySelectorPort } from '../../__tests__/test-utils/in-memory-replay-selector-port.ts';
2527
import { createDaemonReplaySelectorPort } from '../replay-selector-port.ts';
2628

2729
const ADAPTERS: readonly (readonly [string, () => ReplaySelectorPort])[] = [
2830
['production (src/selectors)', createDaemonReplaySelectorPort],
29-
['in-memory (packages/ad-replay testing)', createInMemoryReplaySelectorPort],
31+
['in-memory (test-utils)', createInMemoryReplaySelectorPort],
3032
];
3133

3234
const saveNode: SnapshotNode = {

0 commit comments

Comments
 (0)