TerminalRecordingEntry Entity

TerminalRecordingEntry is the Terminal-owned Entity for one ordered raw PTY recording entry. It stores replayable Terminal transport facts separately from the terminal record so input, output, resize, header, and exit facts can be appended, searched, and replayed without rewriting the Terminal record on every chunk.

TerminalRecordingEntry rows are raw transport evidence. They are not AgentExecution semantic journal records and do not decide AgentExecution lifecycle or owner workflow state.

Sources

• Class: packages/core/src/entities/TerminalRecordingEntry/TerminalRecordingEntry.ts
• Schema: packages/core/src/entities/TerminalRecordingEntry/TerminalRecordingEntrySchema.ts
• Contract: packages/core/src/entities/TerminalRecordingEntry/TerminalRecordingEntryContract.ts
• Owning Entity: terminal.md
• Storage model: docs/adr/0001.08-ogm-anchored-entity-storage-and-hydrated-view-model.md
• Entity events: docs/adr/0001.09-contract-declared-entity-events-and-sse-publication.md

Responsibilities

Area	TerminalRecordingEntry owns
Identity	Canonical terminal_recording_entry:<id> Entity id.
Terminal relation	terminalId reference to the owning terminal record with cascade delete metadata.
Ordering	One-based sequence scoped to terminalId, unique with the Terminal relation.
Entry kind	Raw terminal recording entry type: header, input, output, resize, or exit.
Replay payload	Entry-specific data such as raw text, literal flag, dimensions, or exit code.
Search	Full-text indexed data field for terminal input/output content.
Append serialization	In-process per-Terminal append queue that prevents local sequence races.

Non-Responsibilities

Neighbor	Boundary
Terminal	Owns the hydrated recordingEntries collection and live recording persistence wiring. TerminalRecordingEntry owns each row.
AgentExecution journal	Owns semantic AgentExecution records, not raw PTY replay facts.
TerminalRegistry	Emits live updates; it does not persist recording rows.
Owning Entity of Terminal	May inspect or replay Terminal data through Terminal reads, but does not write recording rows directly.

Contract Methods

Method	Kind	Payload schema	Result schema	Behavior	Likely callers	Side effects
append	mutation	TerminalRecordingEntryInputSchema	TerminalRecordingEntrySchema	Appends the next ordered raw PTY recording entry for a Terminal.	Terminal.create header append; Terminal recording persistence subscribers for input, output, resize, and exit.	Persists one terminal_recording_entry row with generated id and next sequence.
read	query	TerminalRecordingEntryLocatorSchema	TerminalRecordingEntrySchema	Reads one recording entry by canonical Entity id.	Daemon entity dispatcher, direct diagnostic reads.	None.
find	query	TerminalRecordingEntryFindSchema	TerminalRecordingEntryCollectionSchema	Lists ordered recording entries for a Terminal, optionally filtered by entry type.	Terminal.read hydration, replay readers, tests.	Waits for pending in-process appends for that Terminal before querying.

Events

Event	Payload schema	Publisher	Subscribers/callers	Meaning
data.changed	TerminalRecordingEntrySchema	TerminalRecordingEntry through the generic Entity event capability; daemon validates with TerminalRecordingEntryContract.	SSE and daemon IPC subscribers using channels such as terminal_recording_entry:<id>.data.changed or terminal_recording_entry:*.*.	One raw recording entry row is available or changed.

Property Groups

Group	Property	Schema role
Identity	id	Canonical recording entry Entity id.
Ownership	terminalId	Canonical Terminal id exposed to application code; zod-surreal compiles it as a record<terminal> reference with cascade delete.
Ordering	sequence	Terminal-scoped replay order; unique with terminalId.
Classification	type	Raw PTY recording entry kind.
Time	occurredAt	Timestamp of the recorded entry.
Text	data, literal	Input/output data and optional literal-input flag.
Size	cols, rows	Header or resize dimensions.
Exit	exitCode	Exit code for terminal exit entries.

Schema Map

Schema	Purpose
TerminalRecordingEntryTypeSchema	Closed recording-entry vocabulary: header, input, output, resize, exit.
TerminalRecordingEntryLocatorSchema	Class-scoped selector by canonical Entity id.
TerminalRecordingEntryFindSchema	Terminal-scoped ordered replay query with optional entry kind filter.
TerminalRecordingEntryInputSchema	Append input; the class creates id, assigns sequence, and validates entry-specific required fields.
TerminalRecordingEntryStorageSchema	Persisted terminal_recording_entry table record with reference/index/full-text metadata.
TerminalRecordingEntrySchema	Hydrated Entity data exposed across the Entity boundary.
TerminalRecordingEntryCollectionSchema	Ordered collection returned by find.

TerminalRecordingEntryInputSchema enforces entry-specific payload requirements: input and output require data; header and resize require both cols and rows; exit may carry a nullable exitCode.

ERD

erDiagram
  TERMINAL ||--o{ TERMINAL_RECORDING_ENTRY : owns

  TERMINAL_RECORDING_ENTRY {
    string id PK
    string terminalId FK
    int sequence
    string type
    string occurredAt
    string data
    bool literal
    int cols
    int rows
    int exitCode
  }

The terminalId field is a canonical string id at the Entity boundary. The Surreal adapter converts it to a typed record<terminal> reference when writing or querying storage.

Append Flow

flowchart TD
  A[TerminalRegistry update] --> B[Terminal recording persistence]
  B --> C[TerminalRecordingEntry.append]
  C --> D[Wait for per-Terminal append queue]
  D --> E[Read last sequence for terminalId]
  E --> F[Create next terminal_recording_entry row]
  F --> G[Publish data.changed]
  G --> H[Terminal.read hydrates ordered recordingEntries]

Replay Query Flow

flowchart TD
  A[Terminal.read or replay caller] --> B[TerminalRecordingEntry.find]
  B --> C[Parse TerminalRecordingEntryFindSchema]
  C --> D[Wait for pending appends for terminalId]
  D --> E[Query terminal_recording_entry by terminalId]
  E --> F[Optional type filter]
  F --> G[Order by sequence ASC]
  G --> H[Return TerminalRecordingEntryCollectionSchema]

Cross-Control Checklist

Boundary	Status
Class	TerminalRecordingEntry.ts owns append sequencing, read, and find.
Schema	TerminalRecordingEntrySchema.ts owns storage fields, Surreal reference metadata, indexes, full-text search metadata, and append/find payloads.
Contract	TerminalRecordingEntryContract.ts declares append/read/find and data.changed event metadata.
Storage	terminal_recording_entry.terminalId references terminal; terminalId + sequence is unique.
Reference metadata	terminalId is a zod-surreal reference to terminal with onDelete: cascade; adapter conversion keeps Entity code on canonical string ids.
Event publication	Appended recording rows publish through the generic Entity event capability and are validated against TerminalRecordingEntryContract.
Documentation finding	Append sequencing is serialized in-process per Terminal. Cross-daemon concurrent append would need a datastore transaction or sequence allocator.
Schema metadata finding	TerminalRecordingEntry has the strongest current metadata coverage of the three pages; nested enum/member wording should still be included in any repository-wide schema description audit.