# coder-s-og-s/trajectory-ir architecture

> Architecture diagram of the GitHub repository coder-s-og-s/trajectory-ir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coder-s-og-s/trajectory-ir
- Repository: https://github.com/coder-s-og-s/trajectory-ir

## Overview

Trajectory IR is a Go-primary, portable intermediate representation and safety layer for agent execution—not an agent framework or durable execution engine. Its main workflow records projected context, seals a model decision, executes effect-classified tools with sandbox and block-and-gate protections, commits the step, and can export or verify a portable .tir package. The graph emphasizes documented Go runtime paths; some internal wiring and the Python reference implementation are not represented because their source was not sampled.

Main entry points: [`go/trajir/client/client.go`](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/client/client.go) (Trajectory client), [`go/trajir/log/log.go`](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/log/log.go) (Node log), [`go/trajir/resume/step.go`](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/resume/step.go) (Step runner), [`go/trajir/tir/tir.go`](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/tir/tir.go) (TIR packages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Run execution"]
  node_projector["Context projector<br/>[projector.go]"]
  node_resume["Step runner<br/>[step.go]"]
  node_gate["Replay gate<br/>[gate.go]"]
  node_effects["Effect classifier<br/>[effects.go]"]
  node_sandbox["Sandbox policy<br/>[sandbox.go]"]
end

subgraph group_integrity["Trajectory integrity"]
  node_nodes["Node identity<br/>[nodes.go]"]
  node_redact["Redaction<br/>[redact.go]"]
  node_tir["TIR packages<br/>[tir.go]"]
  node_signature["Package signatures<br/>[signature.go]"]
end

subgraph group_persistence["Persistence and backends"]
  node_cas["Content store<br/>[cas.go]"]
  node_log["Node log<br/>[log.go]"]
  node_pglog["Postgres log<br/>[log.go]"]
  node_durable["Durable backend<br/>[backend.go]"]
  node_sqlite[("SQLite backend<br/>[sqlite.go]")]
  node_temporal["Temporal adapter<br/>[backend.go]"]
end

subgraph group_interfaces["Host interfaces"]
  node_client["Trajectory client<br/>[client.go]"]
  node_mcp["MCP adapter<br/>[server.go]"]
end

node_host(("Agent host"))
node_model(("Model"))
node_tool(("Host tools"))
node_engine(("Durable engine"))

node_host -->|"drives steps"| node_client
node_client -->|"records nodes"| node_log
node_client -->|"opens memo"| node_durable
node_client -->|"checks effects"| node_effects
node_client -->|"checks policy"| node_sandbox
node_client -->|"gates tool calls"| node_gate
node_client -->|"runs full step"| node_resume
node_resume -->|"requests plan"| node_model
node_resume -->|"projects context"| node_projector
node_resume -->|"records step"| node_log
node_resume -->|"executes calls"| node_tool
node_gate -->|"records claims"| node_log
node_gate -->|"memoizes calls"| node_durable
node_log -->|"derives identity"| node_nodes
node_pglog -->|"derives identity"| node_nodes
node_client -->|"exports packages"| node_tir
node_tir -->|"reads trajectory"| node_log
node_tir -->|"stores artifacts"| node_cas
node_tir -->|"verifies signatures"| node_signature
node_redact -->|"redacts records"| node_log
node_durable -->|"uses local store"| node_sqlite
node_durable -.->|"selects adapter"| node_temporal
node_temporal -.->|"dispatches workflows"| node_engine
node_mcp -->|"serves tools"| node_host
node_mcp -->|"calls client"| node_client
node_mcp -->|"imports exports"| node_tir

click node_client "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/client/client.go"
click node_mcp "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/mcp/server.go"
click node_projector "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/projector/projector.go"
click node_resume "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/resume/step.go"
click node_gate "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/resume/gate.go"
click node_effects "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/effects/effects.go"
click node_sandbox "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/sandbox/sandbox.go"
click node_nodes "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/nodes/nodes.go"
click node_redact "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/redact/redact.go"
click node_tir "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/tir/tir.go"
click node_signature "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/tir/signature.go"
click node_cas "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/cas/cas.go"
click node_log "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/log/log.go"
click node_pglog "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/postgres/log.go"
click node_durable "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/durable/backend.go"
click node_sqlite "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/durable/sqlite.go"
click node_temporal "https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/durable/temporal/backend.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_projector,node_resume,node_gate,node_effects,node_sandbox toneBlue
class node_nodes,node_redact,node_tir,node_signature toneAmber
class node_cas,node_log,node_pglog,node_durable,node_sqlite,node_temporal toneMint
class node_client,node_mcp toneRose
class node_host,node_model,node_tool,node_engine toneIndigo
```

## Components

### Run execution

- [Context projector](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/projector/projector.go): `go/trajir/projector/projector.go`
- [Step runner](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/resume/step.go): `go/trajir/resume/step.go`
- [Replay gate](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/resume/gate.go): `go/trajir/resume/gate.go`
- [Effect classifier](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/effects/effects.go): `go/trajir/effects/effects.go`
- [Sandbox policy](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/sandbox/sandbox.go): `go/trajir/sandbox/sandbox.go`

### Trajectory integrity

- [Node identity](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/nodes/nodes.go): `go/trajir/nodes/nodes.go`
- [Redaction](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/redact/redact.go): `go/trajir/redact/redact.go`
- [TIR packages](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/tir/tir.go): `go/trajir/tir/tir.go`
- [Package signatures](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/tir/signature.go): `go/trajir/tir/signature.go`

### Persistence and backends

- [Content store](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/cas/cas.go): `go/trajir/cas/cas.go`
- [Node log](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/log/log.go): `go/trajir/log/log.go`
- [Postgres log](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/postgres/log.go): `go/trajir/postgres/log.go`
- [Durable backend](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/durable/backend.go): `go/trajir/durable/backend.go`
- [SQLite backend](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/durable/sqlite.go): `go/trajir/durable/sqlite.go`
- [Temporal adapter](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/durable/temporal/backend.go): `go/trajir/durable/temporal/backend.go`

### Host interfaces

- [Trajectory client](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/client/client.go): `go/trajir/client/client.go`
- [MCP adapter](https://github.com/coder-s-og-s/trajectory-ir/blob/main/go/trajir/mcp/server.go): `go/trajir/mcp/server.go`

### Other components

- **Agent host**
- **Model**
- **Host tools**
- **Durable engine**

## Connections

- Agent host → Trajectory client: drives steps
- Trajectory client → Node log: records nodes
- Trajectory client → Durable backend: opens memo
- Trajectory client → Effect classifier: checks effects
- Trajectory client → Sandbox policy: checks policy
- Trajectory client → Replay gate: gates tool calls
- Trajectory client → Step runner: runs full step
- Step runner → Model: requests plan
- Step runner → Context projector: projects context
- Step runner → Node log: records step
- Step runner → Host tools: executes calls
- Replay gate → Node log: records claims
- Replay gate → Durable backend: memoizes calls
- Node log → Node identity: derives identity
- Postgres log → Node identity: derives identity
- Trajectory client → TIR packages: exports packages
- TIR packages → Node log: reads trajectory
- TIR packages → Content store: stores artifacts
- TIR packages → Package signatures: verifies signatures
- Redaction → Node log: redacts records
- Durable backend → SQLite backend: uses local store
- Durable backend → Temporal adapter: selects adapter
- Temporal adapter → Durable engine: dispatches workflows
- MCP adapter → Agent host: serves tools
- MCP adapter → Trajectory client: calls client
- MCP adapter → TIR packages: imports exports