UTTORI ASM · IN DEVELOPMENT

Conflict-safe analysis editing

Use conflict-safe analysis editing when creating or verifying a ROM analysis project.

Tracked research under .uttori/research/ is the authority for human names, comments, classification and analysis choices in a Git source project. SQLite indexes these declarations alongside retained capture evidence. Edit ordinary JSON/source files, use native Undo and Git diffs, and integrate new generations through prepare, preview and merge.

Research declarations

A version-1 uttori-research document names the project ID, original ROM content SHA-256 and decisions. Each decision has collection, stable id and value. Supported collections are labels, comments, annotations, regions, analysis and evidence. A non-null value keeps the same ID as its decision. value: null suppresses an imported record; removing that decision restores the imported observation. Suppressing a symbol's presentation with suppressed: true is a separate label choice.

Human evidence uses source: "manual", a nonempty sourceId, an explicit confidence and optional detail. Records refer to evidence IDs. Retain original qualified addresses and IDs when changing names or relocating source. The research loader validates duplicate decisions, symbol names and evidence references before synchronization.

readResearchInputs() loads a validated snapshot. renameResearchSymbol() prepares a content-checked rename declaration, preserving identity, provenance and seeding policy. changeResearchSymbol() prepares aliases, suppression or entry-point changes. They do not write files or publish SQLite changes. Aliases are unique, distinct from the current name and bounded to 64 per symbol. synchronizeSourceResearch() indexes current Git decisions. Source analyze performs synchronization before conservative analysis.

In VS Code, F2 combines supported source uses with the symbol research edit. Edit Symbol Research and Edit Analysis Research open normal JSON documents. Coverage classification/state/target actions also propose research edits. Save and review them before analyzing evidence. A new presentation name does not automatically seed additional code.

SQLite transaction APIs

Standalone evidence hosts can use revision-checked publication directly. loadAnalysisProjectSnapshot() reads validated records and revision in one read transaction. commitAnalysisProjectTransaction() acquires BEGIN IMMEDIATE, checks that revision under the writer lock, and commits rows, provenance, manifest and revision together. prepareAnalysisProjectTransaction() validates an in-memory replacement without creating files or reserving the writer. Commit revalidates it.

Validation failures, stale revisions and errors before commit preserve the previous publication. On AnalysisProjectStaleError, reload and reapply intent; never attach a fresh revision token to stale replacement data. Every complete publication advances the revision, including semantically unchanged writes. Low-level transaction callbacks must be synchronous and roll back when they throw. Synchronous commit APIs cannot be interrupted by a same-event-loop timer.

loadAnalysisProjectViewSnapshot() loads metadata by default. An explicit reducer streams and validates runtime rows in the same snapshot. commitAnalysisProjectViewUpdate() replaces only supplied metadata tables and preserves runtime history. Complete-project writers replace runtime too. An omitted table is preserved; an empty supplied array clears it. These APIs do not replace tracked Git research as the authority for a source project.

Durability and recovery

The store uses WAL with synchronous=NORMAL. A process interruption during a transaction exposes either the prior or committed publication; an OS crash can lose recent commits while preserving SQLite consistency. SQLite documents the durability contract.

The watcher pointer is refreshed after commit. A valid stale pointer can reopen the authoritative database; a missing pointer is reconstructed from an existing validated current-format database without changing records or revision. A malformed/unreadable existing pointer fails explicitly and is preserved. A pointer-refresh warning does not undo a successful commit. Filesystem writes outside SQLite have their own recovery boundaries. See backup and recovery.

compactAnalysisProject() and project-compact checkpoint and VACUUM during explicit maintenance with a temporary-space check. Exact no-op imports do not run VACUUM. explainProjectEvidence() resolves persisted records, direct provenance, reverse references and conflicts without inventing mapper translations or stronger conclusions than the evidence supports.