TraceAtom

TraceAtom v0.1 is a deterministic atomic event-trace format and offline verifier for AI agents that interact with Solana. It makes action identity, ordering, conditions, revisions, tool calls, input/output digests, evidence references, and Solana references explicit, then binds every atom into a canonical SHA-256 hash chain.

Status: local v0.1 milestone. This package is intentionally private and has not been published.

Why

Agent logs are often prose, mutable JSON, or transaction-only receipts. They do not reliably answer: what revision acted, under which condition, using which tool invocation, against which snapshot, and whether the claimed evidence existed first. TraceAtom provides a small interoperable contract and stable offline checks for those questions.

What v0.1 proves

• strict structure and bounded cardinality;
• contiguous sequence and nondecreasing timestamps;
• trace/condition/revision consistency;
• canonical atom hashes, predecessor continuity, and root self-consistency for the supplied document;
• duplicate atom/hash/evidence identity, duplicate action-kind invocation, invocation-independent semantic replay, and replayed result-signature detection;
• call-before-result tool lifecycle and exact call/result linkage;
• a same-revision, same-agent snapshot before every claim;
• evidence links for claims and complete offline Solana references for Solana-scoped actions.

It does not prove authorship, historical capture, that a snapshot really existed, that a Solana transaction landed, that a URI is available, that a statement is true in the world, or that an agent performed well. Anyone who can rewrite the whole document can inject or alter atoms and recompute the complete chain; a self-authored foreign trace can also be valid. TraceAtom detects inconsistent or partial mutation, not a consistent full rechain without a trusted signature or externally anchored root. It never calls RPC and never dereferences evidence.

Quickstart

Requirements: Node.js >=20.19.0 and pnpm 10.34.5.

corepack pnpm install --frozen-lockfile
corepack pnpm build
mkdir -p .traceatom-output
node dist/cli.js chain fixtures/baseline.draft.json --output .traceatom-output/baseline.trace.json --json
node dist/cli.js validate .traceatom-output/baseline.trace.json --json
node dist/cli.js verify .traceatom-output/baseline.trace.json --json
node dist/cli.js compare fixtures/baseline.trace.json fixtures/candidate.trace.json --json

The output directory is ignored by Git and is created as a real directory. Do not write directly to /tmp/file.json on macOS: /tmp is a symlink, and TraceAtom intentionally rejects a symlink as the final output parent. /private/tmp/<real-directory>/file.json is an alternative after explicitly creating the real subdirectory.

Expected policy failures return exit code 2; unexpected failures return 1; success returns 0.

Trace shape

A trace header declares schemaVersion, traceId, a cross-condition runId, condition, revision, deterministic createdAt, and provenance. Each atom includes:

• atomId, sequence, observedAt, condition, and revision;
• agent and session identity;
• tool name/version and action kind/scope/name/invocationId;
• lowercase sha256: input/output digests;
• bounded evidence links, each with its own digest and media type;
• Solana cluster, nullable signature and slot, plus program/account references;
• previousHash and hash after chaining.

The authoritative runtime contract is src/schemas.ts. Generated Draft 2020-12 schemas are in schemas/; they encode the representable claim/discriminator and signature/slot cross-field rules and are contract-tested with Ajv. Runtime parsing and semantic verification remain authoritative for operational policy.

See docs/SPEC.md for normative rules and docs/SECURITY-MODEL.md for trust boundaries.

Canonicalization and chaining

TraceAtom recursively sorts object keys, preserves dense array order, uses JSON primitive serialization, normalizes negative zero, and rejects undefined, non-finite, non-plain, sparse-array, and non-index array-property values. An atom hash is:

sha256(UTF-8(canonical-json(atom-with-previousHash-without-hash)))

The first previousHash is null; each subsequent value equals the prior atom hash; rootHash equals the final atom hash. Canonicalization is intended for schema-valid TraceAtom data and follows the RFC 8785 ordering/JSON-number approach.

Replay identity and tool lifecycle

Exact (invocationId, action.kind) reuse is one replay signal. A separate semantic fingerprint deliberately omits invocationId, atom identity, sequence/timestamps, and chain hashes, while retaining revision, agent, tool, logical action fields, input/output digests, evidence, and Solana references. Changing only a transport invocation ID therefore cannot disguise the same logical operation; changing an operation-bearing field produces a different fingerprint.

A tool_result must follow an earlier tool_call with the same invocationId. Their action name/scope, agent/session, and tool name/version must match, and the call's outputDigest must equal the result's inputDigest. Evidence IDs must be unique within each atom.

CLI

traceatom validate <trace.json> [--json]
traceatom chain <draft.json> [--output <file.json>] [--json]
traceatom verify <trace.json> [--json]
traceatom compare <baseline.json> <candidate.json> [--json]

compare requires valid traces, a shared runId, baseline on the left, and candidate on the right. A valid comparison with differences still exits 0.

Deterministic synthetic demo

node scripts/generate-fixtures.mjs
corepack pnpm build
corepack pnpm demo

The fixtures are synthetic, use localnet, are marked provenance.source: "fixture/demo" and benchmark: false, and use fixed timestamps. Signatures, slots, accounts, and evidence URLs are inert test data. They are not model-performance or chain-finality evidence.

Security posture

• JSON input is limited to 2 MiB, 32 nesting levels, 1,000 atoms, and bounded nested arrays/strings.
• Duplicate keys, comments, trailing commas, prototype-sensitive keys, non-files, and input symlinks are rejected.
• Evidence and Solana references are never fetched or executed.
• Atomic JSON output rejects input overwrite, non-.json paths, symlinked output parents/targets, non-files, and hardlinked targets.
• Validation never signs or sends transactions and does not use network state as truth.
• Hash-chain validity is not authentication: foreign/self-authored traces, fabricated snapshots, and modified documents followed by a complete consistent rechain can validate.

See SECURITY.md for reporting and supported versions.

Development

corepack pnpm format:check
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
corepack pnpm schemas:check
corepack pnpm audit --audit-level high
corepack pnpm pack:check

pack:check runs npm pack --dry-run --json --ignore-scripts because pnpm 10 does not support a no-write pack --dry-run; it then enforces the package file allowlist. It neither creates a tarball nor invokes publication.

Architecture

• src/schemas.ts: strict runtime contract and inferred types.
• src/canonical.ts, src/chain.ts: deterministic bytes and chain construction.
• src/verifier.ts: pure integrity/policy verifier with stable issue codes.
• src/compare.ts: baseline/candidate comparison.
• src/io.ts, src/cli.ts: hardened JSON I/O and thin CLI.
• scripts/: deterministic schema and fixture generation.
• test/: unit, integration, process, and path-hardening tests.

Non-goals for v0.1

RPC confirmation, transaction signing/submission, evidence retrieval, cryptographic agent signatures, streaming traces, binary encodings, automatic migration, and performance scoring are out of scope.

Contributing and roadmap

See CONTRIBUTING.md, GOVERNANCE.md, and ROADMAP.md. By participating, follow the Code of Conduct.