UTTORI ASM · IN DEVELOPMENT

Instruction trace import

Import bounded runtime traces and keep evidence tied to the correct ROM.

Install @uttori/asm-disassembler and run this as import-trace.mjs with Node 26 or newer:

import {
  importRuntimeTraceIntoProject,
  loadAnalysisProjectViewSnapshot,
} from "@uttori/asm-disassembler";

const [directory, file] = process.argv.slice(2);
const { manifest } = loadAnalysisProjectViewSnapshot(directory);
const controller = new AbortController();
const cancel = () => controller.abort(new Error("Import cancelled"));
process.once("SIGINT", cancel);
try {
  const result = await importRuntimeTraceIntoProject(
    file,
    directory,
    {
      projectRomContentSha256: manifest.rom.contentSha256,
      sourceName: file,
      indexMode: "full",
    },
    {
      signal: controller.signal,
      maxBytes: 2 * 1024 ** 3,
      onStage: (message) => console.error(message),
    },
  );
  console.log(JSON.stringify(result, null, 2));
} finally {
  process.removeListener("SIGINT", cancel);
}

Run node import-trace.mjs /path/to/analysis /path/to/trace.json. The input is an uttori-asm-instruction-trace JSON artifact with schema version 1. Its ROM hash must match the project's headerless content hash. Architecture and address-space names must already match the project. The importer does not translate recorder addresses.

For decoded capture streams, use importRuntimeTraceSourceIntoProject(source, directory, context, options). The source supplies validated metadata and read(accept), calls accept synchronously for each ordered chunk, and resolves only after terminal integrity checks. A late producer error rejects the import. The importer owns and closes its database connection. It does not dispose the source or retain its chunks.

Records are derived facts, not input instructions: each distinct PC counts once, each joint PC/bytes/state variant counts twice (instruction and CPU-state records), and each distinct bus observation counts once. Repeated observations increment counts without consuming more records. Full register snapshots can therefore produce millions of records even at a small set of PCs. File size and invalid budget values are checked before reading the body. An explicit record budget can only be enforced as distinct facts are discovered; exceeding it aborts the import without publishing partial evidence. Raising the input-byte limit does not raise an explicit record budget.

A custom source must enforce its own input-byte budget. Chunk validation, sequence ordering, cumulative loss counts, ROM identity, and index limits still apply. Progress callbacks run synchronously and should return quickly.

full is the only supported instruction index profile. It retains all supplied registers, instruction bytes, exact execution counts and bus observations. It does not normalize CPU aliases or omit general-register history. Source identity hashes canonical validated metadata and chunks, so JSON whitespace does not create a new capture. Reimporting the same source preserves counts. Historical reduced-index receipts remain readable; reimporting them reuses retained facts with a warning rather than restoring previously omitted registers. Keep the original chronological capture for ordered history, replay and context companions.

Storage policy controls disposable projections and the live SQLite page ceiling independently of parser input and index limits. Imports preserve prior evidence. Exact no-op imports do not run VACUUM. See project storage and backup and recovery.

Cancellation is cooperative at read, chunk, record, and publication boundaries. It cannot preempt a synchronous SQLite operation or callback. Before publication, cancellation, malformed input, stale revisions, and conflicting records leave runtime facts and the semantic revision unchanged. Instruction import saves an explicit storage-policy change before indexing. That change can remain if the import fails. Bus import saves its policy with publication.

After the database commits, updating analysis.json can still fail. Reopen the project to inspect its saved revision and evidence before retrying. Successful repeat imports preserve counts and the semantic revision but refresh the import receipt. Post-commit maintenance failures are returned as warnings. An error is not a promise that every file and setting stayed unchanged.