Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions packages/ad-replay/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,6 @@
".": {
"types": "./src/index.ts",
"default": "./src/index.ts"
},
"./divergence": {
"types": "./src/replay-divergence.ts",
"default": "./src/replay-divergence.ts"
}
}
}
103 changes: 1 addition & 102 deletions packages/ad-replay/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,104 +1,3 @@
/**
* The `ad-replay` package façade (#1478 P5 stage D — narrowed; report-action/
* suggestion-ranking/vars/identity-vocabulary further narrowed by the P5
* review pass; plan-digest/resume and `classifyTargetBindingMatch` further
* narrowed by the #1555 review pass, "complete the binding façade instead of
* documenting deviations"; the target-verification policy functions further
* narrowed by the #1555 review's R3 pass, "target verification must happen
* INSIDE the engine"). `scripts/layering/package-boundaries.test.ts` asserts
* this file's exact export list — see "the real tree parses, declares, and
* passes R11" — so a stray export (including one this parser cannot
* enumerate a name for, like `export *`) fails that gate, not just a comment
* mismatch.
*
* The binding design (issue comment 5156017698) is two value entrypoints —
* `inspectAdReplay` + `runAdReplay` — plus the neutral vocabulary their
* signatures are built from, exported by name (#1555 structural-quality
* review, "typed façade replaces the zero-type rule"): a package a root
* consumer must integrate against through hand-derived `Parameters<...>`/
* `ReturnType<...>` gymnastics in a SINGLE allowed root module
* (`src/daemon/ad-replay-facade-types.ts`, since deleted) is a shim tax, not
* an isolation win — every derived name still had to be re-exported from that
* one file for every other root module to use, and every daemon-side type
* that shadowed an engine type by hand (`TargetVerificationEntry`,
* `TargetClassificationOutcome`, `TargetBindingFailureEvidence`,
* `ReplayVerifiedTargetGuard`, plus a `toDaemonEvidence` copy translator
* between mutable and readonly array shapes) was a duplicate definition that
* could silently drift from the type it mirrored. `packages/maestro`'s
* façade (`facade-execution.ts`/`facade-runtime-port.ts`/…) is the precedent:
* a package boundary is enforced by an exact, gate-pinned export LIST, not by
* exporting zero types. The gate below now pins values AND types together,
* so a stray widening — a type accidentally exported, or one accidentally
* dropped that a root file was still deriving by hand — fails loudly either
* way.
*
* `inspectAdReplay` is the read-only `.ad` manifest reader — the plan-digest
* hash (`plan-digest.ts`, `computeReplayPlanDigest`) and the `--from`/
* `--plan-digest` resume-point math (`resume.ts`, `resolveReplayEntryIndex`)
* are internal-only; the manifest carries the digest as `planDigest` and the
* resume math as a `resolveEntryIndex` closure instead, so
* `session-replay-runtime-plan.ts`'s `prepareReplayPlan` and
* `request-router-repair-expired.test.ts` read them off the manifest rather
* than importing the underlying functions. `AdReplayManifest` is its return
* type and `AdReplayVarSources` is `runAdReplay`'s `${VAR}` scope-input
* shape — both named here since `session-replay-runtime-plan.ts` threads them
* by name across its own helper signatures.
*
* `runAdReplay` is the `.ad` step loop; `AdReplayStepRuntime` is the runtime
* capability bag the daemon adapter
* (`session-replay-runtime-engine-adapter.ts`) implements to thread it,
* including selector resolution through the direct `@agent-device/selectors`
* package engine. Selector parsing and matching stay behind that package's
* string-only façade; no adapter value crosses this boundary.
*
* `./internal/target-verification.ts`'s four policy functions
* (`planPostResolutionTargetVerification`, `planPreDispatchTargetVerification`,
* `deriveReplayTargetGuardMismatchEvidence`, `deriveWaitLandmarkMismatchEvidence`)
* stay engine-private — they are called only from `./internal/verify-dispatch.ts`'s
* `verifyAndDispatchStep`, never the daemon — but the TYPED evidence shapes
* they consume (`AdReplayGuardMismatchEvidence`, `AdReplayLandmarkMismatchEvidence`)
* and the classification/guard/binding-evidence/verification-routing shapes
* `verifyAndDispatchStep` exchanges with the daemon's `AdReplayStepRuntime`
* implementation (`AdReplayVerificationEntry`, `AdReplayTargetClassification`,
* `AdReplayTargetObservation`, `AdReplayTargetBindingEvidence`, `AdReplayDispatchGuard`,
* `AdReplayDispatchOutcome`) ARE named here: the
* daemon builds/reads real values of these shapes directly now (routing in
* `session-replay-target-verification.ts`, wire-narrowing in
* `session-replay-runtime-engine-adapter.ts`) rather than re-declaring a
* structurally-identical twin per module.
*
* `${VAR}` scope/planning: the engine builds the `${VAR}` scope (via
* `@agent-device/ad-script`) from the request's `varSources` and resolves
* each action exactly once per step, handing the daemon's `dispatchStep`/
* `beginTargetVerification` capabilities the RESOLVED action — never a raw
* action plus a scope for the daemon to interpolate itself (#1555 review P1,
* "move variable semantics/planning behind the replay entrypoint"). The
* `${VAR}`-scrub values a divergence report redacts (`AdReplayScrubValue`)
* are threaded the same direction, as an explicit argument on each
* build*Failure/handleActionFailure capability, computed ONCE per run from
* the engine's own live scope — never recomputed daemon-side from a second
* scope object, and never re-collected per call site.
*/

/** Native inspection and execution implement the shared contracts-owned ports. */
export { inspectAdReplay } from './internal/inspect.ts';
export type { AdReplayManifest } from './internal/inspect.ts';

export { runAdReplay } from './internal/step-loop.ts';

export type {
AdReplayDispatchGuard,
AdReplayDispatchOutcome,
AdReplayScrubValue,
AdReplayStepFailure,
AdReplayStepRuntime,
AdReplayTargetBindingEvidence,
AdReplayTargetClassification,
AdReplayTargetObservation,
AdReplayVarSources,
AdReplayVerificationEntry,
} from './internal/runtime-port-types.ts';

export type {
AdReplayGuardMismatchEvidence,
AdReplayLandmarkMismatchEvidence,
} from './internal/target-verification.ts';
10 changes: 5 additions & 5 deletions packages/ad-replay/src/internal/__tests__/resume.test.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
import type {
AdReplayEntryIndexParams,
PendingRecordAndHeal,
} from '@agent-device/contracts/ad-replay-execution';
import assert from 'node:assert/strict';
import { test } from 'vitest';
import {
resolveReplayEntryIndex,
type AdReplayEntryIndexParams,
type PendingRecordAndHeal,
} from '../resume.ts';
import { resolveReplayEntryIndex } from '../resume.ts';

/**
* #1555 structural-quality review ("package-local tests... resume.ts and
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'vitest';
import { runAdReplay } from '../step-loop.ts';
import type { AdReplayStepRuntime } from '../runtime-port-types.ts';
import type { AdReplayStepRuntime } from '@agent-device/contracts/ad-replay-execution';
import type { SessionAction } from '@agent-device/contracts/session';
import type { TargetAnnotationV1 } from '@agent-device/contracts/replay';

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
import type {
AdReplayGuardMismatchEvidence,
AdReplayLandmarkMismatchEvidence,
} from '@agent-device/contracts/ad-replay-execution';
import assert from 'node:assert/strict';
import { test } from 'vitest';
import type { TargetAnnotationV1 } from '@agent-device/contracts/replay';
Expand All @@ -6,8 +10,6 @@ import {
deriveWaitLandmarkMismatchEvidence,
planPostResolutionTargetVerification,
planPreDispatchTargetVerification,
type AdReplayGuardMismatchEvidence,
type AdReplayLandmarkMismatchEvidence,
} from '../target-verification.ts';

/**
Expand Down
25 changes: 5 additions & 20 deletions packages/ad-replay/src/internal/inspect.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
import { AppError } from '@agent-device/kernel/errors';
import type { SessionAction } from '@agent-device/contracts/session';
import {
parseReplayScriptDetailed,
readReplayScriptMetadata,
resolveDeclaredScriptPlatform,
type ReplayScriptMetadata,
} from '@agent-device/ad-script';
import { computeReplayPlanDigest } from './plan-digest.ts';
import { resolveReplayEntryIndex, type PendingRecordAndHeal } from './resume.ts';
import { resolveReplayEntryIndex } from './resume.ts';

/**
* #1478 P5 stage C2b: the read-only `.ad` inspection façade. Moved out of
Expand All @@ -29,23 +27,10 @@ import { resolveReplayEntryIndex, type PendingRecordAndHeal } from './resume.ts'
* new top-level façade export — they are plain data/a closure hanging off
* the manifest object `inspectAdReplay` already returns.
*/
export type AdReplayManifest = Readonly<{
actions: SessionAction[];
actionLines: number[];
metadata: ReplayScriptMetadata;
/** SHA-256 digest of the canonical plan (`digestFlags` binds the same platform/target the replay invokes with). */
planDigest: string;
/** The `--from`/`--plan-digest` resume-point math, closed over this manifest's own `actions`/`planDigest`. */
resolveEntryIndex(params: {
from: number | undefined;
digest: string | undefined;
pendingRecordAndHeal: PendingRecordAndHeal | undefined;
sessionActionsLength: number;
}): { ok: true; value: number } | { ok: false; message: string };
}>;

/** The request-level `--platform`/`--target` override the plan digest binds (raw flags, before any metadata merge). */
export type AdReplayDigestFlags = Readonly<{ platform?: string; target?: string }>;
import type {
AdReplayManifest,
AdReplayDigestFlags,
} from '@agent-device/contracts/ad-replay-execution';

/**
* Parses one `.ad` script's TEXT and returns its actions/line table, header
Expand Down
26 changes: 5 additions & 21 deletions packages/ad-replay/src/internal/resume.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,27 +17,11 @@
* notes for why that reordering was judged out of scope here.
*/

/**
* The session-side state that gates an EMPTY-TAIL resume (`--from actionCount
* + 1`). Stamped for `record-and-heal`, and per #1262 also for
* `caution`/`manual`'s record-and-heal-shaped alternate repair (their own
* unshifted `resume.from` is unaffected by this watermark).
*/
export type PendingRecordAndHeal = Readonly<{
expectedFrom: number;
actionsCountAtDivergence: number;
}>;

export type AdReplayEntryIndexParams = Readonly<{
from: number | undefined;
digest: string | undefined;
pendingRecordAndHeal: PendingRecordAndHeal | undefined;
sessionActionsLength: number;
}>;

export type AdReplayEntryIndexResult =
| Readonly<{ readonly ok: true; readonly value: number }>
| Readonly<{ readonly ok: false; readonly message: string }>;
import type {
PendingRecordAndHeal,
AdReplayEntryIndexParams,
AdReplayEntryIndexResult,
} from '@agent-device/contracts/ad-replay-execution';

/**
* Resolves `--from`/`--plan-digest` into a 0-based loop entry index before
Expand Down
6 changes: 3 additions & 3 deletions packages/ad-replay/src/internal/step-loop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ import type {
AdReplayRunOutcome,
AdReplayRunRequest,
AdReplayStepRuntime,
} from './runtime-port-types.ts';
} from '@agent-device/contracts/ad-replay-execution';
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved

/**
* #1478 P5 stage C2b: the `.ad` step-loop ENGINE policy, split out of
* `packages/replay-port/src/daemon-port/native-command.ts`'s replay orchestration /
* `resolveReplayStepResponse` / `buildReplayActionFailure`. Everything that
* touches a real device, a snapshot, `SessionStore`, or the P4b repair
* coordinator is daemon authority and stays behind the narrow
* `AdReplayStepRuntime` capabilities (`./runtime-port-types.ts`) — this
* `AdReplayStepRuntime` capabilities (`@agent-device/contracts/ad-replay-execution`) — this
* module only decides which action to run next, when to skip one, and when
* to stop.
*
Expand All @@ -28,7 +28,7 @@ import type {
* vocabulary and the verify-then-dispatch orchestrator — both extracted out,
* following `packages/maestro`'s own three-way split
* (`runtime-port-types.ts` for the vocabulary, its engine files for the
* orchestration logic). `./runtime-port-types.ts` now owns every
* orchestration logic). `@agent-device/contracts/ad-replay-execution` now owns every
* `AdReplayStepRuntime`-adjacent type; `./verify-dispatch.ts` owns
* `verifyAndDispatchStep` and its two dispatch helpers. This file is left
* with exactly the loop (`runAdReplay`) and the terminal-close/executable-
Expand Down
38 changes: 6 additions & 32 deletions packages/ad-replay/src/internal/target-verification.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,45 +44,19 @@
* not engine policy. This module now only reads already-typed values.
*/

import type { TargetAncestryEntry, TargetAnnotationV1 } from '@agent-device/contracts/replay';
import type { TargetAnnotationV1 } from '@agent-device/contracts/replay';
import {
firstAncestryMismatch,
identityFieldMismatches,
type LocalIdentity,
} from '@agent-device/ad-script';
import { readSelectorExpression } from '@agent-device/selectors';

/**
* The verified/observed member's structural position within its capture
* (document order + sibling) — moved here (from `./step-loop.ts`, which
* still uses it for `AdReplayVerifiedTargetGuard`) so both this module's
* typed evidence shapes and the step loop can reference ONE definition
* without a cycle: this module has no dependency on `./step-loop.ts`, but
* `./step-loop.ts` already depends on this one.
*/
export type AdReplayTargetStructuralDenotation = Readonly<{
documentOrder: number;
sibling: number;
}>;

/**
* The guard-mismatch refusal's typed evidence, already narrowed by the
* daemon adapter from the wire response's `details` bag — the engine never
* sees the untyped bag itself.
*/
export type AdReplayGuardMismatchEvidence = Readonly<{
targetRole?: 'source' | 'destination';
observed: LocalIdentity | undefined;
expectedStructural: AdReplayTargetStructuralDenotation | undefined;
observedStructural: AdReplayTargetStructuralDenotation | undefined;
}>;

/** The wait-landmark-mismatch refusal's typed evidence — same translate-before-crossing rule. */
export type AdReplayLandmarkMismatchEvidence = Readonly<{
matchCount: number | undefined;
observed: LocalIdentity | undefined;
observedAncestry: readonly TargetAncestryEntry[];
}>;
import type {
AdReplayTargetStructuralDenotation,
AdReplayGuardMismatchEvidence,
AdReplayLandmarkMismatchEvidence,
} from '@agent-device/contracts/ad-replay-execution';

// ---------------------------------------------------------------------------
// Pre-capture verification gating (`verifyReplayActionTarget`'s two branches).
Expand Down
2 changes: 1 addition & 1 deletion packages/ad-replay/src/internal/verify-dispatch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import type {
AdReplayStepRuntime,
AdReplayTargetObservation,
AdReplayVerifiedTargetGuard,
} from './runtime-port-types.ts';
} from '@agent-device/contracts/ad-replay-execution';

/**
* #1478 P5 stage C2b (split out of `step-loop.ts` by the #1555 structural-
Expand Down
2 changes: 1 addition & 1 deletion packages/ad-script/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
export { parseReplayScriptDetailed, readReplayScriptMetadata } from './internal/script.ts';
export type { ReplayScriptMetadata } from './internal/script.ts';
export type { ReplayScriptMetadata } from '@agent-device/contracts/replay-script-data';

export { resolveDeclaredScriptPlatform } from './internal/open-script.ts';

Expand Down
2 changes: 1 addition & 1 deletion packages/ad-script/src/internal/replay-input.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
import type { ReplayScriptMetadata } from '@agent-device/contracts/replay-script-data';
import type { CommandFlags } from '@agent-device/contracts/command';
import { AppError } from '@agent-device/kernel/errors';
import { isReplayBackendId, unsupportedReplayBackendMessage } from './format.ts';
import {
parseReplayScriptDetailed,
readReplayScriptMetadata,
type ParsedReplayScript,
type ReplayScriptMetadata,
} from './script.ts';

export type ParsedReplayInput = ParsedReplayScript & {
Expand Down
9 changes: 1 addition & 8 deletions packages/ad-script/src/internal/script.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { ReplayScriptMetadata } from '@agent-device/contracts/replay-script-data';
import { AppError } from '@agent-device/kernel/errors';
import { recordingQualityInputToExportQuality } from '@agent-device/contracts/recording';
import {
Expand Down Expand Up @@ -45,14 +46,6 @@ export const REPLAY_METADATA_PLATFORMS = new Set<ReplayScriptPlatform>(
);
const REPLAY_METADATA_TARGETS = new Set<DeviceTarget>(['mobile', 'tv', 'desktop']);

export type ReplayScriptMetadata = {
platform?: ReplayScriptPlatform;
target?: DeviceTarget;
timeoutMs?: number;
retries?: number;
env?: Record<string, string>;
};

export type ParsedReplayScript = {
actions: SessionAction[];
actionLines: number[];
Expand Down
7 changes: 1 addition & 6 deletions packages/ad-script/src/internal/vars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,7 @@ export type ReplayVarScope = {
expandedBuiltinNames?: Set<string>;
};

export type ReplayVarSources = {
builtins?: Record<string, string>;
fileEnv?: Record<string, string>;
shellEnv?: Record<string, string>;
cliEnv?: Record<string, string>;
};
import type { ReplayVarSources } from '@agent-device/contracts/replay-script-data';

const SHELL_PREFIX = 'AD_VAR_';

Expand Down
1 change: 0 additions & 1 deletion packages/command-output/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
"type": "module",
"description": "Shared CLI and MCP command presentation: per-family output formatters, warning routing, color, human error lines, and result serialization. Takes terminal facts as explicit input and performs no process I/O.",
"dependencies": {
"@agent-device/ad-replay": "workspace:*",
"@agent-device/capture-kit": "workspace:*",
"@agent-device/command-registry": "workspace:*",
"@agent-device/command-surface": "workspace:*",
Expand Down
2 changes: 1 addition & 1 deletion packages/command-output/src/output/error.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import {
type NormalizedError,
} from '@agent-device/kernel/errors';
import { readResponseWarnings } from '@agent-device/kernel/success-text';
import { formatReplayDivergenceReport } from '@agent-device/ad-replay/divergence';
import { formatReplayDivergenceReport } from '@agent-device/contracts/replay-divergence-data';
import { collapseWarningText } from '../output-common.ts';

/**
Expand Down
Loading
Loading