Skip to content

docs: define trajectory architecture and implementation plan - #27

Merged
minixalpha merged 6 commits into
mainfrom
codex/trajectory
Aug 23, 2026
Merged

docs: define trajectory architecture and implementation plan#27
minixalpha merged 6 commits into
mainfrom
codex/trajectory

Conversation

@minixalpha

@minixalpha minixalpha commented Aug 23, 2026

Copy link
Copy Markdown
Owner

Summary

  • Define Source Record, Native Event, Journal Entry, Event Journal, and ATIF Trajectory as distinct layers in the project vocabulary.
  • Add bilingual research comparing Pi, Claude Code, Codex, OpenCode, and Grok event surfaces, including reproducible local captures and schema-faithful ATIF mappings.
  • Document OpenRouter actual-cost accounting, generation-based reconciliation, the unified Chat Completions transport, and the provider-neutral boundary nano will need.
  • Replace the earlier public native-trajectory proposal with an internal append-only Event Journal and public ATIF-v1.7 output.
  • Add the 0.8.x implementation sequence for events, journal persistence, cost enrichment, ATIF projection, CLI integration, Harbor collection, and layered validation.
  • Explicitly defer --output-format and stream-json to a later PR while preserving the shared runtime-fact model.

Architecture decisions

  • Core emits agent-independent Native Events; the journal writer adds run identity, strict sequence, and record time to form durable Journal Entries.
  • --trajectory PATH exposes only an ATIF-v1.7 snapshot. The internal Event Journal remains replayable implementation state rather than a second public trajectory format.
  • Cost retains provenance. Provider-reported OpenRouter values may populate standard ATIF cost fields, while calculated, partial, or unknown values remain explicitly labeled.
  • A future OpenRouter transport should default to Chat Completions; the existing Anthropic Messages compatibility path can reconcile missing cost through generation IDs.
  • Harbor passes a trajectory path and reads ATIF instead of translating a native trajectory itself.

Validation

  • Confirmed all three new English research notes match the heading structure and line count of their Chinese sources.
  • Regenerated the complete English 0.8.x development notes from the Chinese source.
  • Checked the new English documents for Chinese-text residue, balanced code fences, and existing relative-link targets.
  • Ran git diff --check successfully.

Documentation only; no runtime behavior changes.

@minixalpha minixalpha changed the title codex/trajectory docs: define trajectory architecture and implementation plan Aug 23, 2026
@minixalpha
minixalpha merged commit c1d847a into main Aug 23, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant