Concepts

Organization

The tenant. Every event, finding, policy and credential belongs to exactly one organization. The API resolves the organization on the server from your session or from the ingestion key — never from an ID supplied in a request body.

Agent and runtime

An agent is identified by the name its events carry (claude-code, research-agent). A runtime (collector) is one installation that sends events: a developer machine running the Claude Code collector, or a process using an SDK key.

Session

A related run of activity, identified by the source's session id. A session is live if it has not ended and reported an event in the last 15 minutes. If a session stops reporting without an end event (crash, lost network), it is marked stale after an hour rather than left looking live.

Event

One thing that happened. Events use a versioned, provider-neutral schema (Event schema). Two timestamps are always kept separate:

  • occurred_at — when it happened, according to the sender
  • ingested_at — when Tracemason received it

Event ids are generated by the sender, so re-sending an event never creates a duplicate.

Trace

A session viewed as a timeline: every event in order, with tool requests paired to their results, subagent activity nested, findings marked on the events that caused them, and Git activity attached.

Policy and finding

A policy is a deterministic rule over events. When an event matches, a finding is opened with a severity, an explanation, the evidence events and recommended next steps. Repeated matches of the same policy on the same subject in one session raise the finding's occurrence count instead of opening more findings.

Findings move through: Open → Investigating → Acknowledged → Resolved, or False positive.

Alert

Raised once for each new finding of medium severity or higher. Always shown in the app; optionally delivered by email or signed webhook.

Investigation

A shareable record that collects findings, sessions, commits, pull requests and notes while someone works out what happened.

Provenance

When Tracemason says a session is related to a commit, pull request or deployment, it says how it knows:

Label Meaning
Verified Both sides report the same identifier. The collector saw HEAD move to a commit during a tool call, and the Git provider reported that same SHA.
Explicitly linked A person or tool declared it: the commit message or PR description contains Tracemason-Session: <session id>.
Correlated No shared identifier, but independent signals agree: the commit was made during the session, on the same branch, and changes files the session modified.
Possible association Same repository and time window only. Someone else may have made the commit.
Unknown No supporting evidence.

A link derived through another record is never stronger than the hop it came through. For example, a deployment of a pull request's merge commit is at most Correlated, because a merge can include other people's work.

Editing files in a repository is never, by itself, treated as evidence that an agent authored a commit.

Environment

Senders may declare an environment name (production, staging). Declared names are untrusted. Production-specific policies apply only after an admin marks the environment verified under Security → Policies' environment list (API: PATCH /api/orgs/:org/environments/:id).

Topology

The Topology view draws agents, repositories, environments and external hosts, and the activity connecting them. Every edge is derived from stored records and states its evidence ("3 sessions in this repository"). The Operations tab shows the same data as tables.