* feat(process)!: name process capture Evidence by its launched root process
The capture result now carries the launched root process in
`manifest.root_process`: its PID with the start identity that
`observeProcessStartIdentity` read for that PID at launch, bound to the
capture's run token. The harness reads that identity once and shares it
between finalization signalling and the manifest, so the read no longer
depends on a positive finalization interval.
Capture Evidence names the root as its subject,
`{ kind: "process", pid, start_time, executable_sha256 }`. A PID without
its start identity is not an identity, so an unread start identity leaves
the subject `unknown`/`not-observed`. When the caller selects PID
normalization, the raw PID and start identity are not recorded:
`root_process` is `withheld-by-caller` and the subject is
`unknown`/`withheld-by-caller`, a new unknown reason. Capture validation
requires the withheld state exactly when PID normalization is selected.
Refs #11417
BREAKING CHANGE: process capture Evidence IDs change: captures without PID
normalization name `{ kind: "process", pid, start_time, executable_sha256 }`
as their subject, and captures with PID normalization name
`{ kind: "unknown", reason: "withheld-by-caller" }`. Capture results
require `manifest.root_process`; captures without it are refused.
Recreate stored process capture Evidence.
* fix(process): join the launch identity read and let cancellation interrupt its wait
The root's launch identity read now runs for every capture and the
manifest awaits it. The read stays unsignalled, because finalization
signals after a cancellation still need the retained identity, so the
manifest's wait observes cancellation through `waitForAbortable` instead.
`finishProcessRun` and the startup-failure path join the read, so a
capture never returns while it is still running.
* feat(rizin)!: bind Rizin command Evidence to its session and launch file (#11570)
* feat(rizin)!: bind Rizin command Evidence to its session and launch file
Rizin command Evidence was subject-less (`unknown`/`not-observed`). A new
`session` target identity names the debugger session REA minted and the
target it launched: `{ kind: "session", session_kind, id, target }`, where
`target` is a file identity or an explicit unknown. The Evidence subject
validates the nested launch file with the format-owned subject
declaration.
`start_rizin_debug_session` hashes the launch file with the shared stable
file hasher before Rizin starts and binds the session to it (`format:
"file"`, no architecture or selection). Later debugger commands do not
rebind it. A descriptor whose close fails is retained in the startup
resource scope, like the inferior TTY lease, and fails the start, as does
cancellation; any other hash failure leaves the target
`unknown`/`not-observed` and records the reason as a limitation. The
"target identity is not established" limitation is replaced by the
binding's meaning.
Refs #11417
BREAKING CHANGE: `rizin_debug_command` Evidence IDs change: its subject is
`{ kind: "session", session_kind: "rizin", id: <session_id>, target }`
with `target` the launch file hashed at start (`{ kind: "file", sha256,
format: "file", architecture: null, selection: null }`) or
`{ kind: "unknown", reason: "not-observed" }`. Recreate stored Rizin
command Evidence.
* feat(gdb)!: name GDB command Evidence by its debugger session (#11572)
GDB startup and console Evidence was subject-less (`unknown`/`not-observed`).
It now names the session REA minted with the shared `session` identity:
`{ kind: "session", session_kind: "gdb", id, target }`. One projection,
`gdbSessionSubject`, replaces the six `unknownTarget("not-observed")` sites.
`start_gdb_session` launches no program file; programs are loaded or
attached by console commands that REA does not hash, so the session target
stays `unknown`/`not-observed`. REA does not infer a file from a PID or a
path. The existing limitation that the active inferior identity is not
established still applies.
Refs #11417
BREAKING CHANGE: `start_gdb_session` startup Evidence and `gdb_console`
Evidence IDs change: their subject is `{ kind: "session", session_kind:
"gdb", id: <session_id>, target: { kind: "unknown", reason: "not-observed" } }`.
Recreate stored GDB Evidence.
* fix(rizin): keep the launch file read failure when its close also fails
When hashing the launch file failed and closing its descriptor failed
too, the start error kept only the close failure; the retained lease
retries only the close, so the read failure was lost. The cleanup error
now carries it as `launch_file_hash_failure`.
The session-binding test now rewrites the launch file after spawn and
between two commands, and checks that both records keep the digest read
before launch.
* fix(process): keep the descriptor a failed launch identity read could not close
The launch identity read reduced every rejection to an unverified reason, so an inspection-owner failure carrying an unclosed descriptor was dropped and the capture could succeed without retaining it. The retained identity now keeps that owner's failure; startup cleanup and finishProcessRun pass it through the same secondary inspection-failure path as the sampler, which fails the capture and keeps the descriptor owned for cleanup retry.
* refactor(rizin): describe a launch-file hash failure through errorMessage
* test(rizin): create launch-file fixtures through createTestTempDirectory
* fix(process): keep the descriptor a finalization signal's identity check left open (#11603)
* fix(process): keep the descriptor a finalization signal's identity check left open
The root signaller now catches a delivery whose identity check fails through the inspection owner, records the attempt as unverified, and keeps the inspection failure. finishProcessRun joins every delivery (including one that outlasted the finalization grace) and retains those failures through the same secondary inspection-failure path as the launch identity read, so the capture fails with the descriptor still owned for a cleanup retry.
* test(process): release descriptor-retention captures when an assertion fails
Both descriptor-retention regressions register their resource-scope release before the capture starts and use the project deadline instead of a fixed 15 s timeout.
8.0 KiB
Evidence names its subject with one tagged target identity
Status
Accepted (2026-11-15). Implementation lands in slices: the first slice does not
change Evidence IDs, and the slice that does is breaking (marked !, with
recreate-observations migration notes) and ships with the next Evidence format
revision.
Context
"The target" is defined three ways, with different fields:
| Definition | Fields | Owner |
|---|---|---|
| Evidence subject identity | digest.sha256, format, architecture |
evidenceSubjectIdentity in src/domain/evidence.ts |
| Snapshot target | sha256, kind, architecture, format, plus entry_point (raw, DOL) or flash offsets (ESP) |
snapshotTarget in src/domain/analysisSnapshot.ts |
| Snapshot cache stage compare | JSON.stringify of the snapshot target (key-order sensitive) |
AnalysisSnapshotCache.stage |
The Evidence subject schema can only describe a hashed local file. Of 120
non-test createEvidence calls, 50 pass no subject and receive the generic
limitation "Artifact identity is unavailable for this observation." (measured
on main at c56fffcd75): application 29, contracts 7, gdb 6, server 3, domain 3,
rizin 1, cutter 1. Every gdb, rizin, live-browser and process-capture record is
subject-less, because a URL, a running process or a debugger session cannot be a
subject. Comparison and workflow records are subject-less because they derive
from several linked records.
Consequences today:
- Two raw-binary observations of the same bytes at different entry points share
an Evidence subject identity unless the operation echoes the entry point into
parameters. The snapshot target keeps them apart. - Debugger, browser and process Evidence cannot be bound to what it observed. A rebuilt binary under the same path, or a different page at the same tool input, is indistinguishable in the record.
- Consumers that compare targets each reimplement the comparison.
The Evidence format revision (src/domain/evidenceFormat.ts, #10861) gives
Evidence one place to evolve. Phase 5 deferred two items to this decision: the
target identity, and a per-record format marker. A standalone record (outside a
bundle) does not declare its format today.
Decision
-
One tagged identity.
src/domain/targetIdentity.tsownsTargetIdentity, discriminated bykind:file:sha256,format,architecture(nullable) andselection.selectionholds the facts that select what was analysed in the bytes: the raw or DOL entry point, ESP flash and partition-table offsets, and a universal-binary slice. It isnullwhen nothing is selected.url: the URL with userinfo removed and itsorigin. Userinfo is a transport credential and is never part of an identity.process:pid,start_time(the platform start identity thesrc/process/identity primitives read for that PID), andexecutable_sha256(nullable when the executable could not be read stably). A PID alone does not identify a process after exit or reuse, so the start time is required: a producer that did not read it names anunknown(not-observed) target rather than claiming an identity it does not have.session: thesession_kind(rizin,gdb; later kinds such asbrowser-scenarioare added when a producer needs them), the sessionidREA minted, and thetargetthe session was opened on: the launch file hashed when the session started, orunknown. Later debugger commands do not rebind the session.unknown: areasonfrom a closed set:derived-from-linked-evidence(comparisons and workflows; their sources are already committed throughevidence_links),not-observed,unsupported-subject, andwithheld-by-caller(REA observed the identity and the caller chose not to record it, for example process capture PID normalization).
Display facts (
name,local_path) stay beside the identity and are not committed, as today. -
One key.
targetIdentityKey(identity)is the RFC 8785 canonical digest of the identity. Evidence, analysis snapshots, caches and session binding compare targets only through it.evidenceSubjectIdentity,sameEvidenceSubjectTargetIdentity,snapshotTarget's field-by-fieldsnapshotMatchesTargetand theJSON.stringifycompare are deleted. -
Every record has a subject.
createEvidencetakes aTargetIdentity, notundefined. A producer that cannot name its subject passesunknownwith a reason, so "no identity" is an explicit, reasoned value.MISSING_EVIDENCE_SUBJECT_LIMITATIONis removed; the reason replaces it. -
Evidence format revision 2. The new subject changes the committed content of every Evidence ID, including file subjects (which gain
kindandselection). It therefore ships as one breaking revision:EVIDENCE_FORMAT_REVISIONbecomes 2 and its revision note names the subject change.- Every Evidence record carries
evidence_format: 2, so a standalone record declares its format too. The marker is not part of the ID's committed content; it selects the reader, andadmitEvidenceBundleFormatgains a per-record check with the same refusal. - Analysis snapshots embed Evidence and target identities, so snapshot files from revision 1 are refused at open.
-
No migration of stored Evidence. An Evidence ID is a content commitment. Rewriting a revision 1 record under a new subject would claim an observation REA did not make. Revision 1 bundles, records and snapshots are refused with
RECREATE_EVIDENCE_GUIDANCE(recreate the observations with the current release). The bundle reader already does this for pre-revision bundles.
Slices
- Introduce
TargetIdentityandtargetIdentityKey. Use them for snapshot and cache comparison (replacing theJSON.stringifycompare), and letBinaryTargetResolverproduce the file identity through the shared stable file hasher. No Evidence ID changes; not breaking. - Evidence format revision 2 (breaking,
!): the subject becomesTargetIdentityplus display facts; the per-record marker is added; the 50 subject-less sites pass an explicit identity:unknown(derived-from-linked-evidence) for comparisons and workflows, and the best identity each producer already holds for the rest. - Producers gain real identities where they have the facts: gdb and rizin
sessionidentities bound to the opened file, live browserurl, process captureprocess. Each is its own PR and changes only that producer's IDs, which is still within revision 2 if it lands before the release; otherwise it needs its own revision.
Consequences
- Every Evidence ID changes once, in the release that ships revision 2.
Callers that stored Evidence IDs or bundles must recreate them; the release
notes carry the
BREAKING CHANGEfooter and this migration. - Debugger, browser and process Evidence can be bound to what it observed, and two observations that differ only in their selection (entry point, slice, flash offset) no longer share a subject.
- Target comparison has one owner. Session registries can store the identity at open and revalidate it before each call (a follow-up, not part of this decision).
unknownkeeps "the identity was not observed" visible as a fact with a reason, instead of an absent field with a generic limitation.- Revision 2 also takes the remaining fields that are optional only because older Evidence may omit them. Those that every producer writes become required in the same revision.