Trajectory interop spec: importer and exporter design - #19
Open
adewale wants to merge 2 commits into
Open
Conversation
Specify two-way interop with Letta's trajectory-v1 interchange format, read off the authoritative schema rather than the announcement post. The importer is a source adapter, so it inherits redaction, content addressing, manifests, and the read-only guarantee with no new command. The exporter is a projection package plus one Workspace transition, and may only read redacted corpus rows -- never Archive blobs. Six schema properties drive the design: a trajectory is a JSON array rather than JSONL; additionalProperties is false everywhere, so aha metadata goes in a sidecar; the assistant record is a closed two-way variant modelled as a sum type; tool results carry no error signal, so exit codes are lost on export and never inferred on import; timestamps are pattern-constrained, so untimestamped entries are dropped loudly; and meta is flat, with no tree or subagent structure. Nine named laws carry the verification, each with a Type A and a Type B test: schema closure, no invention, loss-table honesty, import idempotence as an exact byte-level fixed point, link integrity, order preservation, redaction fixed point, truncation honesty, read-only boundaries, and determinism. Schema conformance is gated with the jsonschema-go module already present indirectly, so no new direct dependency is required. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019bXCp1iJB7dU2cAxSzWKmY
Fold three mechanisms from the reference implementation's ecosystem into the interop spec. Validate every document through two independently written validators -- the vendored JSON Schema and a hand-written Go validator -- and assert they agree. A schema passes things that are semantically wrong (args decoding to an array satisfies "type": "string"), and a hand-written validator drifts the moment upstream revises the schema; each catches the other's blind spot. Cross-record properties no schema can express, such as tool-call resolution, live in the hand-written half. Disagreements outside a committed exception list are themselves failures. Exclude version constants from golden comparison and assert them by separate rule instead, so a release bump cannot rewrite every golden and drown the diffs a reviewer is meant to read. Replace AdapterCapabilities.HasStableEntryIDs with a closed EntryIdentityKind ladder, promoted from an open question to scoped work. The importer is the forcing function: it is the first adapter whose message identity is content-derived and whose session header is synthetic, and one boolean puts it in the same bucket as Pi. The boolean becomes a derived method so it cannot disagree with the kind; manifest marshalling stays additive per the compatibility policy; and legacy manifests read back as unknown rather than as an invented level. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019bXCp1iJB7dU2cAxSzWKmY
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add comprehensive specification for trajectory-v1 interchange format support, defining the contract for importing agent session data from external sources and exporting aha sessions to the trajectory format for consumption by other tools.
Key changes
docs/trajectory-interop-spec.md): Complete design for trajectory-v1 importer and exporter, including:ParsedEntryrepresentationNotable design decisions
SourceAdapterinterface, gaining redaction, content-addressed blobs, read-only guarantee, and conformance harnesses for freeaha workspace exportcommand (not a top-levelexportcommand, which was explicitly frozen in v0.2)internal/depot,internal/archive, orinternal/cas; constructed only from redacted corpus rowsHasStableEntryIDswith closed variant (native,location,content,synthetic,unknown) to distinguish materially different identity strategiesadditionalProperties: false) goes in a companion.aha.jsonfileTest strategy highlights
@letta-ai/trajectory)Definition of done
Specification is complete and ready for implementation phases. All nine laws are defined and testable. Type A/Type B inventory covers every invariant. Phased rollout plan provides clear sequencing from gates (Phase 0) through importer (Phase 1), exporter library (Phase 2), surfaces (Phase 3), and closing the loop (Phase 4).
https://claude.ai/code/session_019bXCp1iJB7dU2cAxSzWKmY