UTTORI ASM · IN DEVELOPMENT

Runtime evidence API

Use runtime evidence api when creating or verifying a ROM analysis project.

Runtime records are emulator-neutral. Their discriminated records describe aggregated instruction execution, memory reads/writes, CPU state at an instruction address, half-open executed/operand/read/written coverage, and observed control targets. Emulator-specific formats stop at target-plugin importers.

Runtime EvidenceRecord entries can pin an artifact's format/version, SHA-256, ROM content SHA-256, and mapper. Project validation rejects malformed identities, foreign ROM hashes, foreign mappers, invalid counts or widths, and out-of-range addresses before publishing records.

mergeRuntimeEvidence() only adds stable-id facts. Exact reimport is a no-op. A reused id with different content is rejected. Runtime-derived indirect target overrides are the one compositional exception: later captures union their targets and provenance without discarding earlier observations. inspectRuntimeEvidence() reports differing CPU-state, opcode, and instruction-size observations and explains the runtime provenance behind derived annotations and target overrides.

uttori-asm-instruction-trace is the native versioned artifact for explicit live instruction recordings. It stores a ROM content identity, producer revision, architecture/address-space identity, and ordered bounded-pull chunks with cumulative loss metadata. importRuntimeInstructionTrace() verifies that identity and ordering, requires matching architecture and address-space names, aggregates addresses into stable execution records, and returns a RuntimeEvidenceBatch. Its source identity hashes canonical validated metadata and chunks and it never mutates or persists a project. Callers must separately invoke mergeRuntimeEvidence() as an explicit user action or configured recording workflow.

importRuntimeTraceSourceIntoProject(source, directory, context, options) accepts an in-memory producer or decoded archive stream. A RuntimeTraceSource provides metadata and read(accept), calls the consumer synchronously for each ordered chunk, and rejects if the stream or its terminal integrity check fails. Chunks are indexed incrementally in SQLite and published atomically only after the reader completes. createRuntimeTraceFileSource() adapts existing JSON files to this interface and avoids validating/copying every rich chunk twice. The source owns its input byte budget. Project import owns cancellation, index-record limits and revision checks.

For large native captures, importRuntimeTraceIntoProject() aggregates chunks in connection-local SQLite temporary counters, then writes columnar runtime rows into the project. Parsing and integrity checks finish before publication. Failures before commit leave runtime facts and the semantic revision unchanged. Instruction imports save an explicitly supplied storage policy separately, so that policy can survive a failed import. A pointer-file write can fail after the database commits. Reopen the project before deciding whether to retry. Exact reimport preserves counts and the semantic revision, while updating the import receipt. Missing facts can be repaired. The runtime requires built-in node:sqlite.

See Trace import for limits, cancellation, capture ownership, full indexing, and an installed-package example.

Pure rendering returns an in-memory source inventory with original-ROM identity and byte ranges. It does not assign filesystem ownership or prohibit editing. Git source projects retain immutable pure generation commits, verify their payload and original-ROM equality, and integrate them through native three-way merges. sourceContentHash() and byte-comparison helpers support verification; target plugins render native syntax and validate builds/layout. Working files remain editable.

The public source APIs include openSourceProject(), sourceProjectLocalInputs(), synchronizeSourceResearch(), verifySourceGeneration(), previewSourceGeneration(), applySourceGeneration(), finishSourceGeneration() and abortSourceGeneration(). Use executeSourceOperation() from @uttori/asm-cli/source for the shared SNES host workflow. See Git source projects and research editing for authority and lifecycle.