UTTORI ASM · IN DEVELOPMENT
Analysis coordinates
Use analysis coordinates when creating or verifying a ROM analysis project.
Addresses and lengths are bytes. Every address is qualified by a named space. Equal numbers in two
spaces are not interchangeable. File-space addresses are offsets into headerless ROM content.
CPU addresses require the target plugin's mapper to become file offsets. Ranges are half-open
[start, end): length is end - start, and the final byte is end - 1. Project validation enforces
the declared addressBits (1–53). Research validation constrains qualified addresses and ranges to their declared space. RomImage copies input bytes
and returns copies from reads. Its full-file hash includes a copier header and its content hash does not.
Snapshot/load helpers own and close their connections before returning decoded objects. Their
readonly types do not freeze objects at runtime. Prefer replacement arrays and keep the original
snapshot unchanged for revision-checked publication. Research proposals persist nothing; apply them
as ordinary file edits with native Undo and Git review.
openAnalysisProjectStore() returns a caller-owned connection. Close it exactly once in finally.
Use a single store.transaction(callback, false) for related reads and consume iterators inside
that transaction. The callback must be synchronous. Async/thenable returns are rejected and rolled
back. Prepare asynchronous inputs first. Calls cannot nest transactions or outlive close().
false selects a deferred read snapshot, not an enforced read-only connection. Long-lived readers
can retain WAL pages. Lock contention waits up to five seconds before SQLite reports failure.
Advanced SqliteAnalysisStore exports remain public for bounded queries and host integrations.
Opening validates the physical format, not all records. Raw table replacement requires an active
transaction but does not perform semantic validation or publish a revision/pointer automatically.
Prefer the validated APIs below for application edits.
| API | Replacement and preservation contract |
|---|---|
loadAnalysisProjectSnapshot |
Complete validated records, including all runtime history in memory. |
loadAnalysisProjectViewSnapshot |
Metadata plus optional runtime projection. Omitted runtime is not an empty backing store. |
commitAnalysisProjectTransaction / commitPreparedAnalysisProjectTransaction |
Complete replacement, including runtime. Require the caller's revision for existing projects. |
commitAnalysisProjectViewUpdate |
Each supplied metadata array replaces that entire table. Omitted tables and all runtime remain. [] clears a supplied table. |
publishAnalysisProject |
Create or replace everything, including runtime. Samples the revision at call time and cannot detect a replacement based on an old caller snapshot. Editing clients use the revision-checked commit APIs. View updates preserve history. |
Git source projects keep human decisions in tracked research files. SQLite publication APIs serve evidence/index hosts and do not replace those Git inputs. See research editing.