fix(evidence): derive default authority from subject binding (#10321)

* fix(evidence): derive default authority from subject binding

evidenceEnvelopeForAdmission defaulted a missing authority to shipped-artifact
for every observation, including ones with no artifact subject and ones
produced by a live debugger session. An unbound record therefore claimed
authority over an artifact it cannot name, and live GDB, Rizin and Cutter
observations could never qualify a live-observation contract because that
contract accepts only controlled-replay or external-service Evidence.

Default to analyst-inference when no subject is bound and keep
shipped-artifact when one is, so the default matches what the record can
actually support. Declare controlled-replay at the eight live debugger
observation sites (GDB 6, Rizin 1, Cutter 1) so those records describe the
controlled replay they performed and satisfy the documented contract.

* fix(gdb): label retained process-exit observations as controlled replay

The GDB command process-exit branch was the only unbound retention path that
named no authority, so this branch's new default derived it as
analyst-inference. That label cannot support the live-observation contract,
and every sibling path (timeout, cancellation, protocol failure, startup)
already states controlled-replay.

The authority and the unavailable-subject reason now live beside the
provider identity so the retention paths read them from one place instead
of repeating the literals and drifting apart.

* style(evidence): apply repository formatting

* fix(cutter): classify command observations as external-service

The bridge drives the documented already-running Cutter GUI, whose
document state REA neither owns nor resets, so its command
observations claim no controlled replay. Label them external-service
like the comparable IDA and Frida bridge evidence: live-observation
obligations still accept it, while controlled-replay-only verifier
contracts and bundle replay scenarios no longer include these
observations.

* fix(adb): keep device observations at external-service authority

The admission default now derives authority from the subject, so a subjectless ADB observation fell to analyst-inference. A device is a service REA attaches to rather than drives, so the observation supports external-service and must stay eligible for live-observation contracts.

Carry an explicit authority through AnalysisObservation so a producer that knows its own authority can name it, and set it for every ADB operation.

* fix(adb): keep retained observations at external-service authority

The admission default derives authority from the subject, and a subjectless
observation falls to analyst-inference. createAnalysisExecution never carried
an authority field, so every observation the ADB adapter built through it was
committed at the subject-derived default instead of the service's.

Name the authority once in the domain model, stamp it on every successful
execution at the adapter boundary, and route the cleanup-failure and
cancellation-retention sites through one helper. Open the execution options
field so other providers can name their own authority.

Verified: a push whose device digest does not match now retains its receipt at
external-service; removing the stamp fails that assertion. check:fast passes.

* fix(adb): keep the retained verification receipt at device authority

The verificationFailed branch built its retained receipt with createEvidence
directly, so the admission default derived the authority from a subjectless
target and labelled an observed push as analyst-inference. Pass the device
authority through the same way the neighbouring digest-mismatch partial does,
so the receipt can still support live-observation verification.

* style(adb): apply oxfmt formatting to the authority fix

The previous commit wrapped two expressions that oxfmt keeps on one line, so
npm run format:check failed on Static checks.
This commit is contained in:
2SinceJuly authored and GitHub committed 2026-11-18 13:06:25 -05:00
1 parent 204056f21a
commit b99e7737de
15 files changed
+196 -22

No files matched your search

+9 -1
View File
@@ -1703,6 +1703,9 @@ exit 1`,
const evidence = parseEvidence(result.error.partialObservation);
expect(evidence).toMatchObject({
operation: "push_adb_file",
// The retained receipt names the service authority, not the subject-derived
// default a partial observation would otherwise fall back to.
authority: "external-service",
normalized_result: {
local_path: localFile,
device_path: "/data/local/tmp/payload.bin",
@@ -2698,7 +2701,12 @@ exit 1`,
code: "resource_constraint",
details: { operation: "push_adb_file" },
});
expect(result.error.partialObservation).toBeDefined();
// The retained receipt names the service authority, not the subject-derived
// default a partial observation would otherwise fall back to.
expect(parseEvidence(result.error.partialObservation)).toMatchObject({
operation: "push_adb_file",
authority: "external-service",
});
});
it("attributes version capture failures to the public operation and retains the prerequisite", async () => {
+43 -13
View File
@@ -35,6 +35,7 @@ import {
type AnalysisExecution,
} from "../ports/AnalysisProvider.js";
import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";
import { ADB_DEVICE_OBSERVATION_AUTHORITY } from "../domain/adb/adbDeviceAnalysis.js";
import type {
AdbDisplayNumericIssues,
AdbDisplayPartialObservation,
@@ -187,6 +188,41 @@ const SCREEN_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
const BUGREPORT_TIMEOUT_MS = 600_000;
const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024;
/**
* Commit an ADB observation as Evidence that names the device's authority. Every
* retained receipt and partial travels through here so none can fall back to the
* subject-derived default for a target REA does not own.
*/
const createObservationEvidence = (
operation: string,
parameters: Record<string, JsonValue>,
execution: AnalysisExecution,
) =>
createAnalysisExecutionEvidence(
operation,
parameters,
{
...execution,
authority: execution.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY,
},
"observed",
);
/**
* Stamp the device's authority on every successful execution at the adapter
* boundary, so a caller-projected or retained observation cannot fall back to a
* subject-derived authority for a target REA does not own.
*/
const observedExecution = (
result: Result<AnalysisExecution, AnalysisError>,
): Result<AnalysisExecution, AnalysisError> =>
result.ok
? ok({
...result.value,
authority: result.value.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY,
})
: result;
/** Carry the exact digest owner through caller-specific partial-result mapping. */
class AdbDigestFailure extends Error {
constructor(
@@ -989,12 +1025,7 @@ export class AdbProvider {
const partialObservation =
execution === undefined
? undefined
: createAnalysisExecutionEvidence(
operation,
parameters,
execution,
"observed",
);
: createObservationEvidence(operation, parameters, execution);
return new ProviderCleanupError(
ADB_PROVIDER_IDENTITY.id,
resources,
@@ -1109,12 +1140,7 @@ export class AdbProvider {
throw cleanup;
},
partial: (completed) =>
createAnalysisExecutionEvidence(
operation,
parameters,
completed,
"observed",
),
createObservationEvidence(operation, parameters, completed),
},
),
);
@@ -1246,7 +1272,7 @@ export class AdbProvider {
jsonObjectSchema.parse(request.input),
);
if (!retried.ok) return retried;
return await this.#executeOperation(request, options);
return observedExecution(await this.#executeOperation(request, options));
} finally {
release();
}
@@ -2591,6 +2617,8 @@ export class AdbProvider {
limitations: completed.limitations,
locations: completed.locations,
confidence: "observed",
authority:
completed.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY,
},
),
);
@@ -2635,6 +2663,8 @@ export class AdbProvider {
limitations: completed.limitations,
locations: completed.locations,
confidence: "observed",
authority:
completed.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY,
},
),
},
@@ -127,6 +127,8 @@ it("composes observed Evidence with the caller parameters inline", async () => {
expect(evidence.operation).toBe("list_adb_devices");
expect(evidence.parameters).toEqual({});
expect(evidence.confidence).toBe("observed");
// A device REA attaches to is not one it owns, so the observation names the service rather than a replay.
expect(evidence.authority).toBe("external-service");
});
it("preserves cancellation before execution", async () => {
@@ -4,6 +4,7 @@ import type {
ExecutionOptions,
} from "../../ports/AnalysisProvider.js";
import {
ADB_DEVICE_OBSERVATION_AUTHORITY,
adbRequestSchema,
adbDeviceListObservationSchema,
type AdbOperation,
@@ -33,9 +34,17 @@ export class AdbDeviceAnalysisService {
{
execute: async (request, options) => {
const result = await this.provider.execute(request, options);
return result.ok && request.operation === "list_adb_devices"
? projectDeviceList(result.value)
: result;
if (!result.ok) return result;
// A device is a service REA attaches to and does not own, so what it
// reports is an external observation rather than a replay REA drives.
const observed = {
...result.value,
authority:
result.value.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY,
} as const;
return request.operation === "list_adb_devices"
? projectDeviceList(observed)
: ok(observed);
},
},
"observed",
+1
View File
@@ -193,6 +193,7 @@ export class CutterBridgeService {
identity_status: output.identityStatus,
},
rawResult: normalizedOutput,
authority: "external-service",
limitations: [
"Cutter exposes no verified stable identity for the active unsaved document or tab.",
"Document identity is partial: the bridge uses a plugin instance UUID and observed generation; a same-path tab switch or reload may not be distinguishable.",
+8
View File
@@ -6,6 +6,14 @@ import { z } from "zod";
import { knownCoverageStatusSchema } from "../coverage.js";
import { localPathStringSchema } from "../localPath.js";
import { IDENTIFIER_PATTERN } from "../stringPatterns.js";
import type { EvidenceAuthority } from "../evidence.js";
/**
* A device is a service REA attaches to and does not own, so what it reports is
* an external observation rather than one bound to a shipped artifact.
*/
export const ADB_DEVICE_OBSERVATION_AUTHORITY: EvidenceAuthority =
"external-service";
/**
* Device serials as adb prints them: emulator-5554, USB identifiers, and
+9
View File
@@ -3,6 +3,7 @@ import {
createEvidence,
evidenceEnvelopeForAdmission,
type Evidence,
type EvidenceAuthority,
type EvidenceCreationOptions,
type EvidenceLocation,
type EvidenceProvider,
@@ -29,6 +30,11 @@ export interface AnalysisObservation {
* its caller. Explicit null means the observation has no file subject.
*/
readonly subject?: EvidenceSubjectTarget | null;
/**
* The authority the observation itself supports. Missing derives it from the
* subject, which a service REA does not own cannot name.
*/
readonly authority?: EvidenceAuthority;
}
/** Build the single borrowed observation used for admission and commitment. */
@@ -49,6 +55,9 @@ const analysisExecutionEvidenceInput = (
...(execution.relationshipCoverage === undefined
? {}
: { relationshipCoverage: execution.relationshipCoverage }),
...(execution.authority === undefined
? {}
: { authority: execution.authority }),
locations: execution.locations,
confidence,
});
+23
View File
@@ -832,6 +832,29 @@ it("binds an explicit unknown-subject reason into the semantic Evidence identity
expect(parseEvidence(explicit)).toEqual(explicit);
});
it("derives the default authority from whether the subject names a target", () => {
const observation = { operation: "health", parameters: {}, result: true };
expect(createEvidence(TARGET, PROVIDER, observation).authority).toBe(
"shipped-artifact",
);
expect(
createEvidence(unknownTarget("not-observed"), PROVIDER, observation)
.authority,
).toBe("analyst-inference");
expect(
createEvidence(unknownTarget("not-observed"), PROVIDER, {
...observation,
authority: "controlled-replay",
}).authority,
).toBe("controlled-replay");
expect(
createEvidence(TARGET, PROVIDER, {
...observation,
authority: "external-service",
}).authority,
).toBe("external-service");
});
it("derives byte-stable bundle manifests independent of record order", () => {
const artifactEvidence = createEvidence(TARGET, PROVIDER, {
operation: "health",
+8 -2
View File
@@ -356,7 +356,7 @@ export const evidenceSubjectDisplay = (evidence: {
: undefined;
};
type EvidenceAuthority = z.infer<typeof evidenceAuthoritySchema>;
export type EvidenceAuthority = z.infer<typeof evidenceAuthoritySchema>;
type ExecutionEnvironment = z.infer<typeof executionEnvironmentSchema>;
export type EvidenceProvider = Readonly<z.output<typeof providerSchema>>;
@@ -608,7 +608,13 @@ export const evidenceEnvelopeForAdmission = (
raw_result: observation.rawResult ?? null,
normalized_result: observation.result,
confidence: observation.confidence ?? "observed",
authority: observation.authority ?? "shipped-artifact",
// Only a subject that names an identified target can support shipment
// authority; an unknown target names no artifact and claims none.
authority:
observation.authority ??
(subject.identity.kind === "unknown"
? "analyst-inference"
: "shipped-artifact"),
environment: observation.environment ?? null,
limitations: observation.limitations ?? [],
...(observation.relationshipCoverage === undefined
+6
View File
@@ -7,6 +7,12 @@ export const GDB_PROVIDER_IDENTITY = {
version: null,
} as const;
/**
* GDB observations come from a session REA runs and whose target it names, so
* every retention path claims the same controlled replay.
*/
export const GDB_OBSERVATION_AUTHORITY = "controlled-replay" as const;
/** Provider identity with the version this GDB reported, or null when unknown. */
export interface GdbProviderIdentity {
readonly id: typeof GDB_PROVIDER_IDENTITY.id;
+7 -2
View File
@@ -21,6 +21,7 @@ import {
type GdbMiValue,
} from "./GdbMiRecord.js";
import {
GDB_OBSERVATION_AUTHORITY,
GDB_PROVIDER_IDENTITY,
gdbReportedVersion,
type GdbProviderIdentity,
@@ -419,13 +420,17 @@ const createGdbSessionEvidence = (
},
): Evidence => {
const { provenance, unobservedReason } = session.launchFile;
const withAuthority = {
...observation,
authority: observation.authority ?? GDB_OBSERVATION_AUTHORITY,
};
return createEvidence(
gdbSessionSubject(session),
session.provider,
provenance === undefined
? observation
? withAuthority
: {
...observation,
...withAuthority,
parameters: {
...observation.parameters,
launch_provenance: { ...provenance },
+6 -1
View File
@@ -15,6 +15,7 @@ import type { JsonValue } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
import type {
Evidence,
EvidenceAuthority,
EvidenceLocation,
EvidenceSubjectTarget,
} from "../domain/evidence.js";
@@ -117,7 +118,7 @@ export interface AnalysisExecution extends AnalysisObservation {
readonly siblingUnavailability?: AnalysisCapabilityUnavailableError;
}
interface CreateAnalysisExecutionOptions {
export interface CreateAnalysisExecutionOptions {
readonly rawResult?: unknown;
readonly pseudocodeAbsence?: PseudocodeAbsence;
readonly sourceDescriptor?: AnalysisSourceDescriptor;
@@ -133,6 +134,7 @@ interface CreateAnalysisExecutionOptions {
readonly locations?: readonly EvidenceLocation[];
readonly sourceEvidence?: readonly Evidence[];
readonly subject?: EvidenceSubjectTarget | null;
readonly authority?: EvidenceAuthority;
}
/**
@@ -212,6 +214,9 @@ export function createAnalysisExecution(
? {}
: { sourceEvidence: Object.freeze([...options.sourceEvidence]) }),
...(options.subject === undefined ? {} : { subject: options.subject }),
...(options.authority === undefined
? {}
: { authority: options.authority }),
};
}
+1
View File
@@ -142,6 +142,7 @@ const createRizinCommandEvidence = ({
},
result: { ...result },
rawResult: { ...result },
authority: "controlled-replay",
limitations: [
RIZIN_SESSION_TARGET_LIMITATION,
...(launchTarget.unobservedReason === undefined
@@ -103,6 +103,48 @@ it.each(["descriptor-first", "command-first"] as const)(
},
);
it("classifies confirmed command observations as external-service, not controlled-replay", async () => {
const service = new CutterBridgeService({
listSessions: async () => ({
sessions: [],
bridge_directory: "/private/bridge",
discovery_status: "no_live_bridge_found",
bridge_directory_security: "private_verified",
}),
execute: async () => ({
requestId: "4b18ce4d-bf31-456e-ae31-e8c547b2f9db",
output: { sections: "4" },
currentFile: "/fixtures/sample.bin",
documentGeneration: 7,
identityStatus: "partial",
cutterVersion: "Cutter fixture version",
executionState: "complete",
error: null,
message: null,
outputTruncated: false,
}),
});
const result = await service.execute({
session_id: "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a",
expected_generation: 7,
command: "pd 4",
});
if (!result.ok) throw new Error("Expected confirmed dispatch to succeed");
expect(result.value).toMatchObject({
authority: "external-service",
normalized_result: {
command: "pd 4",
execution_state: "complete",
},
limitations: expect.arrayContaining([
"Document identity is partial: the bridge uses a plugin instance UUID and observed generation; a same-path tab switch or reload may not be distinguishable.",
]),
});
expect(result.value).not.toHaveProperty("authority", "controlled-replay");
});
it("retains uncertain command completion as Evidence without encouraging a retry", async () => {
const service = new CutterBridgeService({
listSessions: async () => ({
@@ -3398,6 +3398,25 @@ it("retains an exited GDB session when no inferior identity was captured", async
expect(manager.status(started.value.session_id)).toBeDefined();
});
it("labels the retained process-exit observation as controlled replay", async () => {
const manager = await managerFor(
responsiveProvider(`
if (match[2].includes('auto-load off')) process.stdout.write(match[1] + '^done\\n');
else process.exit(3);
`),
);
const started = await expectGdbSessionStarted(manager);
const executed = await manager.execute(started.value.session_id, "exit now");
expect(executed).toMatchObject({
ok: false,
error: {
cleanupIncomplete: true,
partialObservation: { authority: "controlled-replay" },
},
});
});
it("retains a session when closing cannot confirm the debugger process stopped", async () => {
let stopCalls = 0;
const provider = await createProvider(responsiveProvider());