docs: define v0.1 product and architecture contract

This commit is contained in:
hermes 2026-07-28 18:21:19 +00:00
commit c4fb0c6a01
12 changed files with 2130 additions and 64 deletions

View file

@ -12,32 +12,88 @@ names or locations.
_Avoid_: Binary, file, target
**Analysis Profile**:
The declared analysis inputs other than the Sample, including the Ghidra
version, analyzer configuration, language selection, and tool protocol version.
The canonical analysis inputs other than the Sample, including Ghidra and Java
versions, Target Specification, fully resolved loader and analyzer options,
analysis-adapter version, and maximum CPU count.
_Avoid_: Configuration, settings
**Target Specification**:
The loader, executable format, processor language, and compiler specification
used by Ghidra to interpret a Sample.
_Avoid_: Architecture, target
**Analysis**:
The reusable body of facts Ghidra derives from one Sample under one Analysis
Profile.
_Avoid_: Project, database, workspace
**Quarantined Analysis**:
Analysis data that failed integrity validation and is retained for diagnosis
but can never satisfy a Query.
_Avoid_: Analysis, cache miss
**Query**:
A read-only question evaluated against an Analysis. A Query cannot change the
Sample or Analysis.
_Avoid_: Command, job, operation
**Function**:
A Ghidra-discovered unit of executable behavior identified within an Analysis
by its entry Address.
_Avoid_: Symbol, method
**Function Selector**:
An unambiguous reference used to choose a function by address or resolved
symbol name.
_Avoid_: Function name, function ID
**Call Edge**:
A directed relationship from a caller Function through a callsite Address to
a resolved or unresolved callee, produced by a future targeted Query.
_Avoid_: Call, dependency
**Reference**:
A Ghidra-derived relationship from one Address to another Address or external
symbol, produced by a future targeted Query.
_Avoid_: Pointer, cross-reference result
**Address**:
A location within an Analysis identified by an explicit Ghidra address space
and an offset whose width is defined by that space.
_Avoid_: Integer, offset, pointer
**Artifact**:
A durable, schema-versioned representation of a Query result tied to its
Analysis.
_Avoid_: Output, report, result file
**Analysis Store**:
The tool-owned collection of reusable Analyses and Artifacts. It is disposable
and never contains the authoritative Sample.
_Avoid_: Project directory, cache directory, workspace
**Diagnostic Log**:
A tool-owned record of execution diagnostics that may explain an Analysis or
Query failure but is not part of the Query result.
_Avoid_: Artifact, output
**Invocation**:
One synchronous attempt by the Rust harness to run a bounded Ghidra/Java
operation and validate its response.
_Avoid_: Job, session, worker
**Worker Sandbox**:
The capability-limited environment containing only the untrusted Ghidra/JVM
child for one Invocation; the trusted Rust harness remains outside it.
_Avoid_: Analysis Store, containerized CLI
**Cleanup Transaction**:
Tool-owned staged data that has been removed from active store visibility and
is awaiting complete deletion or a recoverable retry.
_Avoid_: Analysis, quarantine
**Target Verification**:
The declared relationship between a Target Specification and the project's
integration-test matrix: either verified or unverified.
_Avoid_: Ghidra confidence, supported Sample
**Analysis Store**:
The tool-owned collection of reusable Analyses, Quarantined Analyses, Artifacts,
and Diagnostic Logs. It is disposable and never contains the authoritative
Sample.
_Avoid_: Project directory, cache directory, workspace