trajectories 0.0.0 → 0.1.1

package/docs/inspirations.md

@@ -0,0 +1,103 @@
+# Inspirations and provenance
+
+Trajectories inherits Ledger's implemented search and indexing engine and keeps
+the prior-art research that shaped it. This page is the current map: it separates
+adopted dependencies, independently implemented patterns, and ideas that remained
+research or plans. Resemblance to a reference is not evidence that its code or
+file format was adopted.
+
+The historical packet is preserved under the [Ledger research archive](research/ledger/README.md),
+frozen from `archeism/ledger` commit
+`43081aef54c23b4bd017b6c0e11fc42a9a1cb381`. Its [manifest](research/ledger/manifest.json)
+records every original and ported path, SHA-256 digest and link-only transformation.
+Those documents describe Ledger at the frozen commit; their commands, plans,
+measurements and open items are historical evidence rather than current package
+instructions.
+
+Read each claim at its recorded scope. Static source inspection, synthetic tests,
+live observations and proposed designs are different evidence classes in the
+archive. A later port preserves the finding and its limits; it does not turn an
+unrun upstream test or rejected experiment into current verification.
+
+## Current classification
+
+| Reference | Classification | What reached Trajectories |
+| --- | --- | --- |
+| [Letta Trajectory](https://github.com/letta-ai/trajectory) | Adopted dependency | Canonical normalization, validation, stable source identities and canonical records. Trajectories currently pins `@letta-ai/trajectory` `0.4.3`; its portable store, native discovery, relationships and access layers remain Trajectories responsibilities. |
+| [Obelisk](https://github.com/tommy0103/obelisk) | Behavioral research; independent implementation | Ledger studied writer ownership, commit ordering and explicit execution relationships. The port retains Ledger's writer lease and source-proved parentage. No Obelisk code, SQL, package or unpublished workspace dependency was copied. |
+| [Cass](https://github.com/dicklesworthstone/coding_agent_session_search) | Behavioral and format research; independent implementation | Ledger adapted machine-readable search, source-bound recovery and operational patterns, and used pinned native-reader findings when implementing Cursor and OpenCode discovery. Trajectories does not embed Cass or claim its engine or output format. |
+| [AgentsView](https://github.com/kenn-io/agentsview) | Behavioral and format research; independent implementation | Ledger learned from writable ownership, watch plus reconciliation, capture publication, and native Cursor/OpenCode readers. Its own reconciliation and native SQLite handling were implemented and tested in Ledger, then ported. |
+| [Vercel AI SDK Harnesses](https://github.com/vercel/ai/tree/main/packages/harness) | Historical live-capture research | Ledger treated the event stream as a possible live input seam, not a persistence layer. Its proposed live adapter and push path did not ship in Ledger. Current Trajectories codecs and transfer work need their own evidence; this archive does not establish that lineage by resemblance. |
+| [Letta Code](https://github.com/letta-ai/letta-code) | Historical service and reflection research | Ledger studied process ownership, scheduled-run outcomes and reflection completion. The planned Dream/curation worker did not ship. Reading `letta-code` transcript files is source-format support, not adoption of Letta Code's service lifecycle. |
+| [Wake](https://github.com/iAmCorey/Wake) | Implemented patterns with attribution; no dependency or code copy | Ledger independently implemented several pinned Wake mechanisms: locked-SQLite copy fallback, derive-rule counters, echo filtering, title and recency behavior, deletion tombstones, and remote truthfulness primitives. The trigram proposal was measured and rejected; no remote transport was shipped. These Ledger files were then ported to Trajectories. |
+
+## What was actually ported
+
+Trajectories' `legacy` engine came from Ledger at the frozen commit. The
+[retirement source audit](../evidence/ledger-retirement-source-audit.md) and
+[port inventory](../evidence/ledger-port-2026-10-06/source-inventory.json) distinguish
+byte-identical files from intentional package changes. The package-level
+[`legacy/NOTICE.md`](../legacy/NOTICE.md) records that direct source provenance.
+
+The inherited surface includes:
+
+- native history discovery and normalization through the adopted Trajectory
+  dependency;
+- lexical, semantic and hybrid retrieval with machine-readable output;
+- source identity, diagnostics, parentage and coverage;
+- bounded ingestion, reconciliation, durable progress and writer arbitration;
+- Wake-derived mechanisms whose source comments retain the upstream pin and
+  scope; and
+- operator utilities, installers and regression tests recorded by the migration
+  audit.
+
+Trajectories adds portable managed history, immutable snapshots, native
+reader/writer codecs and conversion/continuation boundaries. Those additions
+have their own tests and evidence; the Ledger archive does not retroactively
+attribute them to an older inspiration.
+
+## Research that did not become Ledger runtime behavior
+
+The frozen research also contains proposals and targets. The following were not
+missing code in the port:
+
+- Dream analysis, reflection, findings publication and memory or skill
+  promotion;
+- an AI SDK Harness live-event adapter and durable push buffer;
+- a cross-machine fleet service or remote mirror transport;
+- integrity-addressed retention of every native artifact generation ever
+  indexed; and
+- Wake's desktop UI, whole-session replacement, stats-only deduplication and
+  in-process-only scan locking.
+
+Trajectories' managed snapshots preserve histories explicitly imported into its
+store. That does not prove archival coverage for every transcript previously
+found by Ledger's native scanner.
+
+## Retained evidence
+
+Start with the archived [Ledger inspiration index](research/ledger/docs/inspirations.md).
+The most useful primary maps are:
+
+- [September 7 pinned comparison](research/ledger/docs/research/2026-09-07-confer-inspirations.md)
+  and [Letta Code service review](research/ledger/docs/research/2026-09-07-letta-continuous-service.md);
+- [September 9 refreshed comparison](research/ledger/docs/research/2026-09-09-other-inspirations.md),
+  [Trajectory and Letta Code review](research/ledger/docs/research/2026-09-09-trajectory-and-letta-code.md),
+  and [harness transcript contract](research/ledger/docs/research/2026-09-09-harness-transcript-contract.md);
+- [native history discovery](research/ledger/docs/research/2026-09-09-native-history-discovery.md),
+  [AgentsView native audit](research/ledger/docs/research/2026-09-09-agentsview-native-discovery.md),
+  and [native implementation verification](research/ledger/docs/research/2026-09-09-native-history-implementation.md);
+- [PR2/PR6 integration record](research/ledger/docs/pr2-pr6-integration.md)
+  and [daemon observation](research/ledger/docs/research/2026-09-09-daemon-observation.md); and
+- [Wake deep dive](research/ledger/confer/2026-09-14-wake/wake.md),
+  [port program](research/ledger/docs/research/2026-09-16-wake-port-program.md),
+  and its C1–C10 cycle notes. The [C5 note](research/ledger/docs/research/2026-09-16-c5-trigram.md)
+  preserves the rejected trigram result; the [C8 note](research/ledger/docs/research/2026-09-16-c8-remote-truth.md)
+  preserves the narrower primitives-only remote scope.
+
+For the current comparison against Huihua and OAR (Open Agent Runtime), see
+[Huihua and OAR assessment](research/2026-10-06-huihua-and-oar.md). That review is
+separate from this provenance record and must not imply dependency, ingestion,
+schema or format compatibility without direct evidence.
+The owner reaffirmed Trajectories' own format: borrow Voyage's observation
+patterns to improve it. Voyage ingestion is not part of the proposed ports.

package/docs/ledger-migration.md

@@ -0,0 +1,141 @@
+# Ledger retirement and Trajectories package boundary
+
+Trajectories now contains Ledger's implemented CLI engine and operational
+utilities. The conversion SDK and CLI ship in one `trajectories` package with
+separate entrypoints. `trajector` is not a runtime dependency or an additional
+required package.
+
+| Entry point | Purpose | Runtime and dependencies |
+| --- | --- | --- |
+| `import … from 'trajectories'` | Native codecs, per-session canonical logs, central identity and explicit continuation preparation | Node 22.13+; no Bun SQLite, AI SDK, WDK or harness executor |
+| `trajectories` | Discover/index/search/analyze native and managed history; conversion and operator utilities | Bun; retained Ledger SQLite/search engine; local semantic model is optional |
+
+Perpetual execution, provider credentials, worker recovery and execution leases
+belong to the caller. The CLI's writer lease protects the search DB; it does not
+claim ownership of an agent. Managed `index` is a derived lexical projection,
+not another execution journal. SDK consumers can omit it entirely.
+
+The [canonical-log replacement](../../../docs/adr/0011-trajectories-log-authority.md)
+changes the shared managed-session core used by the API and managed CLI commands.
+It also replaces full portable captures in caller receipts and Workflow results
+with retained delta references. Ordinary native scan/sync keeps Ledger's ingestion
+and search engine. Native harness files remain native. The version 2 managed
+API requires explicit migration of version 1 stores; it does not write both
+managed formats as competing authorities.
+
+For managed version 1 stores, freeze native and Workflow writers and run
+`trajectories migrate SOURCE --out NEW_DESTINATION --writers-stopped --robot`.
+The destination must be fresh. The migration locks each old session's publication,
+preserves its ID, imports accepted captures and retains each old prepared native
+baseline once. It never rewrites source session/snapshot bytes or reads mutable
+native paths. `NEW_DESTINATION/migration.json` is published only after successful
+reconstruction. Keep failed partial destinations and the original source.
+
+The manifest's `heads` map selects the migrated head after each old source head's
+prepared bindings. `captures` separately maps each old accepted snapshot to its
+exact capture head/reference; `bindings` maps old exported baselines to exact new
+head/binding IDs. Apply these mappings to caller and Workflow state before resuming
+writers against the destination; unmapped state still requires migration.
+
+## Port inventory
+
+Source oracle: `archeism/ledger` at
+`43081aef54c23b4bd017b6c0e11fc42a9a1cb381` (latest Ledger main verified 2026-10-06).
+The [source audit](../evidence/ledger-retirement-source-audit.md) records the
+distinction between implemented behavior and aspirations in the old README.
+
+| Ledger capability | Trajectories location or command |
+| --- | --- |
+| 18 native history readers, source discovery and scan outcomes | `legacy/src/scanner.ts`, `native/`; `scan`, `sync` |
+| Lexical/semantic/hybrid search, metadata, filters, aliases and robot v1/v2 | `search/query`, `recent/last`, `status`, `models pull` |
+| Queue, resumable append ingestion, checkpoints, diagnostics and budgets | Retained `legacy/src` engine; `sync`, `build`, foreground `watch` |
+| SQLite schema/migrations, read-only gates, writer arbitration and tombstones | Retained schema/reader/writer; `delete` and serving/admission guards |
+| Proven native parent/subagent/workflow relationships | Retained normalization and parentage fields; search/recent metadata |
+| Worktree wrapper and SHA-pinned source installation | `ops/install-cli.sh`, `ops/install-release.sh` |
+| Bounded Linux/macOS periodic lexical ingestion | `ops/linux/install-systemd-user.sh`, `ops/macos/install-launchd.sh` |
+| Agent-facing CLI utilities | `skills/trajectories`, search/recent shell wrappers |
+| Claude prompt-only history recovery with original-byte provenance | `import-claude-history`; `legacy/scripts/import-claude-history.ts` |
+| Bounded native SQLite diagnostic and old title recovery recipe | `legacy/scripts/native-history-smoke.ts`, `retitle-sessions.md` |
+| Read-only resource/ingestion observer and frozen rollout validation | `legacy/scripts/observe-daemon.ts`, `verify-runtime-rollout.ts` |
+| Pinned source inspirations, native-format research and Wake cycle decisions | [Inspiration index](./inspirations.md), [historical research packet](./research/ledger/README.md) |
+
+Added on top of the port: 11 native reader/writer codecs, managed canonical
+log history, stable central identity across prepared harness changes,
+`show` for full conversation inspection, and `index --store` to make completed
+central histories searchable under `managed:<id>`. This source coverage is
+different from proving all runtime/model routes live; keep the
+[compatibility limits](../README.md#fidelity-and-supported-boundaries).
+
+Ledger never shipped the planned Dream/memory-curation system, a fleet server,
+or raw archival retention for every historically indexed native transcript.
+They are not missing ports. Managed log references retain captured native evidence
+for histories explicitly imported through its SDK/CLI; ordinary native sync
+retains the old provenance/path contract. Preserve native stores and evidence archives.
+
+The historical research packet now travels with Trajectories. Its manifest pins
+the Ledger source and hashes both original and ported documents; relative links
+to excluded evidence point at the original immutable commit. Historical commands
+are not current operator instructions. Large raw transcripts, databases and
+experiment archives remain in their original evidence locations. The separate
+[Huihua/OAR assessment](./research/2026-10-06-huihua-and-oar.md) records new port
+candidates without changing the SDK's active-context or execution contracts.
+
+## Deliberate cutover
+
+1. Build and verify this package. Run the packed-consumer test to prove the SDK,
+   CLI, skills and operator files work outside both source repositories.
+2. Select the existing Ledger DB explicitly. Compare `status`, `recent` and known
+   search queries with the old CLI before replacing a machine's entrypoint.
+3. Back up that DB with SQLite's backup mechanism and stop its old writer. Keep
+   the original DB path and native harness histories. Installation does not move
+   them. Existing WAL files require a consistent SQLite backup, not an arbitrary
+   copy of the primary file while a writer is active.
+4. Install the new CLI and inspect a manual bounded `sync`. Enable the replacement
+   periodic unit on the target host; the installer does not stop Ledger's unit.
+   The [ops guide](../ops/README.md) contains commands, limits and OS behavior.
+5. Freeze Ledger's source/history after that cutover is verified. Keep the old
+   commit and its research/evidence as historical records. Trajectories requires
+   no Ledger checkout at runtime.
+
+DB precedence remains `--db` > `TRAJECTORIES_DB` > `LEDGER_DB` > the old XDG
+`ledger/ledger.sqlite` default. Central storage separately uses `--store` >
+`TRAJECTORIES_HOME` > XDG `trajectories`. Scheduled `sync` indexes native stores;
+`index --store` explicitly projects a selected managed store. Repeat after a
+new accepted head. Only accepted history enters this projection; staged captures
+do not become search results. Index deletion suppresses the derived search row
+without deleting the session's canonical log or retained evidence.
+
+Managed index rows use the dedicated `managed` source (`--source managed` in
+search/recent), while their records keep original native `source_type`,
+`native_session_id` and `binding_id` where known. This isolates
+native admission tombstones from central IDs. Indexed `show` explicitly returns
+the full `ledger-db` record projection; `managed_log_path` points to the session
+log. Use `show CENTRAL_ID --store STORE` for accepted records with central ids,
+payloads and per-record origin, pinned to the displayed head. The SQLite
+projection is not another conversation authority. Its optional provenance
+columns remain null for old records whose origin was not captured; read-only
+commands continue serving older compatible databases without migrating them.
+
+The source release installer retains the full reviewed monorepo archive and
+frozen dependency patch, filters the dependency install to Trajectories, skips
+root lifecycle scripts and builds only this package. The packed npm consumer
+does not need the monorepo; install it with `bun add --global trajectories@0.1.0`. The subsequent
+[Mac cutover](../evidence/mac-cutover-2026-10-07/README.md) verified the clean
+command and scheduler replacement against the retained database; its receipt
+records the rollback and remaining ingestion limits.
+
+## Acceptance evidence
+
+Verify with `bun run verify` in `packages/trajectories`. The retained Ledger
+suite exercises the original index/search contracts; added tests cover managed
+identity across Claude Code → Codex history preparation, unchanged re-indexing,
+full-length tools, accepted-history preservation, suppression, corrupt/missing store
+refusal, writer contention, standalone packaging and wrappers/installers.
+Operational tests use temporary homes and fake service supervisors. Linux units
+also pass the real systemd definition parser when available. These local tests
+are separate from the later Mac cutover and the live transfer cohorts.
+
+The [acceptance record](../evidence/ledger-port-2026-10-06/README.md) preserves the
+812-pass local gate, 12 explicit skips, raw logs, resources, source hashes and
+independent review. House operating skills remain unchanged; the product skill
+was migrated without claiming measured skill improvement.

package/docs/pi-compaction-context.md

@@ -0,0 +1,75 @@
+# Pi compacted provider context
+
+Verified locally on 2026-10-05 with `@ai-sdk/harness-pi@1.0.104`, native
+`@earendil-works/pi-coding-agent@0.84.4`, and OMP 17.3.4. This is native Pi's
+compacted history transported to another harness, not a shared native runtime or
+a new summarization policy. The SDK still has no harness runtime dependency.
+
+## Archive and live context
+
+`snapshot.raw` retains the exact complete native transcript. For supported Pi
+compaction, `snapshot.canonical` becomes the native active view: the latest
+summary as a user message, its retained range, then subsequent entries. Older
+summary entries selected by that range become additional wrapped user messages,
+matching native ordering. Surviving canonical identities and hashes are kept;
+derived summaries use their native compaction entry ID and disclose the
+`trajectories/pi-compaction-context-v1` diagnostic. The existing failed-draft
+filter follows this projection.
+
+Pi's summary wrapper is copied exactly. Export rederives the active view from
+raw bytes, so clearing an archive's `portabilityIssues` or rehashing stale
+canonical history cannot bypass that contract. Old snapshots need recapture.
+Original snapshots stay immutable.
+
+Same-native Pi compaction can change the live prefix. Central append therefore
+requires the same identified native session and exact append-only source bytes,
+then checks the full archive conversation with failed drafts excluded. A summary
+alone does not count as new conversation progress. Other harnesses and imported
+native sessions retain the normal prepared-prefix check.
+
+This follows Raven's useful distinction between lossless archive and lossy live
+compaction, documented in its [pinned vocabulary](https://github.com/EverMind-AI/Raven/blob/3632e6040c7038a60ec418ce39ccae185c72c19f/CONTEXT.md).
+No Raven code or execution loop was introduced.
+
+## Bounded acceptance
+
+Accept identified Pi v3 files with one complete linear entry chain, unique IDs,
+ancestral retention anchors, ordinary user/assistant/tool-result content, and
+recognized bookkeeping. Every selected non-failed message must have canonical
+coverage. Tool results require native call ID and name; pending/orphan tool
+guards still apply after projection.
+
+Branches, disconnected or duplicate metadata, resets, custom messages, extension
+summaries, images, unsupported roles/content and malformed summaries stay blocked.
+Unsupported histories remain archivable with `portabilityIssues`; conversion
+rejects them. OMP-origin compaction stays unsupported because its remote history,
+reset, retry and snapcompact rules differ. This does not change that reader.
+Native extensions that transform provider messages are outside this proof.
+
+## Source contract and verification
+
+| Installed source | SHA-256 |
+| --- | --- |
+| Pi 0.84.4 `dist/core/session-manager.js` | `f0912a8b585263cc9793b38d97f01d19b0617c67b56d7f790bbb81a27d916a3c` |
+| Pi 0.84.4 `dist/core/messages.js` | `a4e4865e343bf87f8078f75ff179a2a77cd7c2700cf8473476bd4dc5ed36adb6` |
+| OMP 17.3.4 `src/session/session-context.ts` | `752c20f846be937422fadcbb632710376c7b829fd7ba520d02e92d21ce3012ea` |
+
+Pi's `buildContextEntries` selects the latest compaction, retained entries starting
+at `firstKeptEntryId`, and subsequent entries. `convertToLlm` adds the summary's
+exact user wrapper. Installed runtime source supplies the oracle; core code uses
+pure data. Recheck this contract when upgrading the native runtime or normalizer.
+
+`test/pi-compaction.test.ts` protects identities/raw preservation, repeated
+summaries, central continuity/progress, malformed topology, export revalidation,
+and unfinished or silently dropped tool results. An independent GPT-6-astra
+review reproduced a missing-call-ID result that normalization silently removed;
+its failing regression preceded the guard correction.
+
+The [native trial](../../trajectories-workflow/experiments/pi-compaction/README.md)
+uses ordinary public HarnessAgent sessions. Baseline Pi continued after compaction
+while both exports rejected it. After projection, central append, direct Pi
+resume, Pi export and OMP handoff passed with exact logical provider role/text
+order and the complete original transcript preserved. Localhost responses do not
+prove semantic summary quality, native state transfer, or perpetual availability.
+The retained [transfer receipt](../evidence/pi-compaction-transfer.json) includes
+the provider conversations, native hashes, diagnostics and resource measurements.

package/docs/pi-provider-context.md

@@ -0,0 +1,76 @@
+# Pi interrupted assistant drafts
+
+Verified 2026-10-03 against installed Pi dependencies and a real Workflow Harness
+discovery transcript. This is a source-specific projection, not a general rule
+for other harnesses or a complete implementation of native context reconstruction.
+
+## Native behavior
+
+Pi's `transformMessages` removes an entire assistant message when its
+`stopReason` is `aborted` or `error`, including text, reasoning, and incomplete
+tool calls. Provider translators call this transformer before making a model
+request. Native session JSONL still contains those messages.
+
+Verified upstream files:
+
+| Package | Installed source | Relevant lines | SHA-256 |
+| --- | --- | --- | --- |
+| `@earendil-works/pi-ai@0.84.4` | `dist/api/transform-messages.js` | 153–160 omit drafts; 170–173 preserve tool results | `e51975857b2fefa7e9cc108850ddab5a2fd1753a399f3cde00d76cd700ce6d10` |
+| `@earendil-works/pi-ai@0.74.2` | `dist/providers/transform-messages.js` | 150–157 omit drafts; 167–170 preserve tool results | `2601ac1c657643dc4f2f1cb55785a3ef435077345457d973fb0a018dfcefa469` |
+
+The source repositories are [Pi](https://github.com/earendil-works/pi/tree/main/packages/ai)
+and its earlier [pi-mono location](https://github.com/earendil-works/pi-mono/tree/main/packages/ai).
+The installed package version and file digest above are the verified inputs;
+moving default-branch documentation is not a version pin.
+
+Pi does **not** remove a real tool result paired with an omitted assistant draft.
+It also synthesizes a result for some dangling non-failed calls. Trajectories
+preserves actual tool results and does not copy the synthetic-result behavior:
+orphan results and unfinished non-failed tool batches continue to fail closed.
+OMP has a different native transformation; the Pi projection is never applied to
+OMP input. Installed OMP 17.3.4 drops aborted/error drafts and paired results,
+except some interrupted-thinking continuity pairs, and has additional reset,
+retry and remote-compaction behavior. Our unchanged OMP archive path is not a
+claim that all its archived records are visible to its provider.
+
+The separate [Pi compaction projection](pi-compaction-context.md) adds a verified
+summary-and-tail view for a bounded native subset, before this draft filter.
+
+## Portable projection and provenance
+
+`readSnapshot` first normalizes the original bytes through the pinned Letta
+normalizer. It rejects invalid native JSON before projection. For Pi only,
+`projectPiProviderContext` removes canonical components attributable to an
+aborted/error assistant entry. Every surviving record keeps its original ID,
+hash, order, and content. All original diagnostics are retained. Each omitted
+entry adds a `noise_record_dropped` diagnostic with its original line and the
+explicit `trajectories/pi-provider-context-v1` marker.
+
+Original bytes, including every omitted draft, remain unchanged in `snapshot.raw`.
+The snapshot identity hashes those bytes and the resulting canonical view. The
+projection does not rewrite an existing saved snapshot. Re-reading its original
+bytes produces a new snapshot when this projection changes its canonical view.
+
+Native wrapper IDs identify canonical components. Legacy rows without IDs use
+Letta's pinned byte-anchor identity, including UTF-8 bytes and CRLF characters:
+`sha256(sourceGroupId + '|byte|' + byteOffset)`. This identity mapping was verified
+against `@letta-ai/trajectory@0.4.3`, `dist/canonical.js`, SHA-256
+`b1441714396dfb85a01feaae2c0624b27739a517807c8f86815d15fae0364244`.
+Tests protect that dependency contract; recheck it when upgrading the normalizer.
+
+## Evidence
+
+The real discovery snapshot originally contained an aborted partial
+`checkpoint_probe` call with ID `call_d184b675b83c46e0885c8270`. Pi's installed
+transformer reduced 14 native messages to 13 provider messages; there was no
+associated tool result. Without projection, all six native writers rejected the
+unfinished batch. Re-reading the identical bytes with projection made all six
+format conversions succeed and disclose the omitted draft. This check used zero
+model calls and establishes format compatibility, not resumed model behavior.
+
+The before/after snapshot IDs, source digest, conversion results, and diagnostic
+are recorded in `evidence/pi-provider-context-discovery.json` in the repository.
+`test/pi-context.test.ts` covers string/array error drafts, every destination,
+legacy Unicode/CRLF identities, original diagnostics, preserved tool results,
+pending successful calls, unchanged OMP handling, stable continuation prefixes,
+and malformed source rejection.

package/docs/research/2026-10-06-huihua-and-oar.md

@@ -0,0 +1,176 @@
+# Huihua and OAR: evidence formats for Trajectories
+
+Source inspection, 2026-10-06. This assessment adds research and port candidates;
+it does not add a codec, execution adapter, dependency, or live compatibility claim.
+The preserved [Ledger inspiration packet](../inspirations.md) distinguishes
+implemented patterns from proposals and rejected experiments.
+
+## Frozen sources
+
+| Project | Inspected revision | Purpose |
+| --- | --- | --- |
+| [Huihua](https://github.com/wibus-wee/huihua/tree/a596eb1dbcec1e2928dfd7865dedf5188e08a62a) | `a596eb1dbcec1e2928dfd7865dedf5188e08a62a`, v0.3.0 | Read and normalize native stores and recorded streams |
+| [OAR](https://github.com/botiverse/oar/tree/a3b43f94059ff40a38536a76b541011a48ed8686) | `a3b43f94059ff40a38536a76b541011a48ed8686` | Runtime observations, controls, projections and Voyage recording |
+| [Ledger](https://github.com/archeism/ledger/tree/43081aef54c23b4bd017b6c0e11fc42a9a1cb381) | `43081aef54c23b4bd017b6c0e11fc42a9a1cb381` | Original research, implemented CLI patterns and experiment evidence |
+| [Trajectories baseline](https://github.com/archeism/oh-my-ai/tree/b2555516b77ce0508f0c02b94c0ac4346125b490/packages/trajectories) | `b2555516b77ce0508f0c02b94c0ac4346125b490` | Existing SDK, managed sessions and Ledger CLI port |
+
+These are separate source pins. Huihua's provider research can reference older
+OAR or runtime revisions; inspecting current OAR does not refresh those fixtures.
+The observations below are source/test inspection, not a new performance trial.
+
+## What Voyage unifies
+
+Yes: OAR unifies heterogeneous runtime observations into one ordered record
+stream. Voyage is the JSONL serialization of that stream. Normalization happens
+in OAR's adapters; the [Voyage writer](https://github.com/botiverse/oar/blob/a3b43f94059ff40a38536a76b541011a48ed8686/packages/oar/src/voyage.ts)
+wraps each existing record without translating it again.
+
+The [record contract](https://github.com/botiverse/oar/blob/a3b43f94059ff40a38536a76b541011a48ed8686/docs/spec/record-stream.md)
+uses three kinds sharing a sequence and attribution envelope:
+
+| Kind | Evidence retained | Meaning |
+| --- | --- | --- |
+| `frame` | Native payload plus zero or more normalized facts | What the runtime actually reported |
+| `request` | Direction, request identity and control/native request body | What the host or runtime asked for |
+| `response` | Observed control acceptance, rejection, answer or exit | What outcome OAR observed for that control |
+
+`seq` orders records within the stream; `sessionId` and `agentPath` identify the
+session and agent. Optional `spanId` is native, rather than a fabricated turn id.
+`receivedAt` is the adapter's observation time, not proof of vendor execution
+time. Multiple facts from one native frame share its sequence; the payload stays
+in one record. An uninterpreted frame remains present with an empty fact list.
+
+A control being accepted does not prove that execution completed. Native
+completion is a separate frame. Unobserved outcomes remain absent, and late
+runtime frames are retained after an abort/dispose request or a settled span.
+An unsolicited process exit can have an empty `requestId`; an importer must not
+invent a matching control. Child-session completion and usage must not settle
+the root session. Requested model/effort in a header differs from values the
+runtime actually reports.
+
+Voyage v3 starts with `format: "oar-voyage/3"` and a header, then record wrappers,
+then an `end` line. A missing end marks a truncated capture. An end line does not
+prove successful task execution. Synchronous writes retain already-written data
+across a process crash, but the inspected writer does not call `fsync`; this is
+not evidence of power-loss durability or recovery of unobserved events.
+
+### What to borrow
+
+1. Keep host intent, control acknowledgement and runtime fact separately
+   attributable. This directly helps investigate the previously observed gap
+   between a slice checkpoint and later native effects.
+2. OAR traces facts back to a shared native frame, preserving unknown records
+   without copying a large payload once per interpreted fact. The owner has
+   skipped adding an evidence-reference API to Trajectories; retain this as
+   comparative research, not an implementation task.
+3. Make usage, status and conversation views recomputable from records, with a
+   scoped cursor. Preserve late events and child attribution in the evidence.
+
+This is a useful acquisition/analysis contract. It does not establish portable
+active context, native caches, permissions, exactly-once effects, or durable
+workflow recovery. The lessons concern source retention, ordering and attribution
+inside our own managed-session format. Voyage is a
+comparison source, not a proposed ingestion format. The earlier OAR lab imported
+the underlying Pi native transcript.
+
+## Huihua port assessment
+
+Huihua's [architecture and coverage](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/docs/architecture.md)
+describe 20 provider labels, including ACP and OAR recordings. That is a count
+of readable input families, not 20 executable harnesses or writable resume
+formats. Trajectories currently has 18 CLI history sources and 11 SDK codecs.
+
+| Candidate | Existing overlap | Smallest useful port and acceptance gate |
+| --- | --- | --- |
+| **Native evidence references — skipped by owner** | Canonical Letta records, raw transcript, hashes and diagnostics already survive snapshots | Use the retained native transcript for conversion debugging. No separate observation projection or evidence inspection API is an active task. |
+| **Incremental SDK acquisition — unmeasured** | CLI ingestion is already bounded and resumable; SDK `readSnapshot` generally collects the transcript | Measure import time and peak memory before changing internals. Preserve canonical records, diagnostics, snapshot identities and publication integrity; a failed or cancelled import must not advance a managed head. Keep the public API until a measured benefit justifies a change. |
+
+The [skipped evidence API design](../evidence-api.md) is retained as history.
+Type-checking and contract review proved properties of the proposal, not that a
+new interface was needed. Streaming first needs a measured baseline; there is
+no new exported streaming or evidence API in this checkpoint.
+
+The [event contract](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/src/contracts/event.ts)
+links normalized events by sequence and record index. Its
+[source contract](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/src/contracts/source.ts)
+keeps native record evidence independently. Tool, file-change and subagent
+selectors return views of existing events; they do not establish implicit
+tool pairing or native resume semantics. This can supplement our canonical
+conversation without promoting every observed event into model context.
+
+Huihua accepts acquired byte streams separately from discovery. Its
+[streaming tests](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/tests/parse.test.ts)
+check producer consumption and early cancellation. JSONL parsing is incremental;
+some SQLite paths buffer selected rows, and a collected snapshot still retains
+history. Early termination does not validate an unread suffix. Streaming is
+therefore not a fixed-memory or complete-snapshot guarantee.
+
+Malformed JSON can remain unknown evidence with a diagnostic in Huihua; that
+differs from a fatal stream, checksum or size failure. Managed snapshot
+publication still needs our own explicit completeness and integrity policy.
+
+Two lower-priority ideas need comparison against the retained Ledger engine:
+
+- Provider scans can yield a failed store separately from prior discoveries.
+  Borrow that SDK seam only where our existing scan outcomes do not already
+  provide isolation; retain cancellation and explicit provider selection.
+- A pure TypeScript read-only SQLite/WAL decoder could help inspect frozen
+  archives without adding a native SQLite dependency to the SDK. Huihua rejects
+  unsupported/changed stores; its bounded schema coverage and custom-parser
+  maintenance cost require separate evaluation. It is not a replacement for
+  the CLI's live-store snapshot/retry reader.
+
+## Preserve the protections we already proved
+
+Huihua's [Pi research](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/src/providers/pi/RESEARCH.md)
+retains branches in physical order and does not select native active context.
+Our [Pi compaction](../pi-compaction-context.md),
+[provider-context projection](../pi-provider-context.md), and incomplete-tool
+guards must remain. An archive reader accepting a file does not authorize
+replaying every message into another harness.
+
+Neither representation automatically preserves an entire original store image.
+Huihua's [JSONL reader](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/src/shared/jsonl.ts)
+skips blank lines; selected SQLite rows are not a database backup, and compressed
+source bytes need separate retention. Trajectories' normal UTF-8 text reads also
+do not prove fidelity for arbitrary invalid UTF-8. Keep source evidence and
+diagnostics specific to the actual capture method.
+
+Huihua's [compatibility manifest](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/fixtures/compatibility/sources.json)
+provides useful fixture provenance. Evidence strength varies: several provider
+research pages pin producer sources, while some link moving branches;
+[Antigravity research](https://github.com/wibus-wee/huihua/blob/a596eb1dbcec1e2928dfd7865dedf5188e08a62a/src/providers/antigravity/RESEARCH.md)
+explicitly relies on a partial observed schema and synthetic fixtures.
+Do not turn provider registration into an unbounded compatibility claim.
+
+## What remains worth measuring
+
+The current SDK [reader](../../src/convert.ts) collects and normalizes complete
+native history. Large imports may therefore incur temporary-memory and parsing
+costs. Internal incremental parsing is a candidate only after profiling; chunked
+reading followed by the same full-buffer parser does not prove a saving, and the
+final snapshot still retains complete history.
+
+The managed [store](../../src/store.ts) writes each new snapshot id as a complete
+JSON bundle, retaining raw text, canonical records and sidecars. Identical ids
+reuse an immutable file, but changed generations retain complete bundles again.
+The owner has explicitly rejected this per-capture full-bundle architecture.
+[ADR 0011](../../../../docs/adr/0011-trajectories-log-authority.md) specifies one
+canonical append-only log, shared native evidence/artifacts, and restrained
+derived checkpoints. The store and Workflow migration is pending. Measure
+allocated bytes across the full replacement and its evidence/cache overhead;
+do not use a smaller copy of the same snapshot system as the new source of truth.
+
+The import-memory candidate is a source-based hypothesis; no measured performance
+improvement is claimed. The retained Ledger CLI already has bounded/resumable
+ingestion and must not be rewritten merely to copy Huihua's interface. Provider
+scan isolation and a custom SQLite decoder have no demonstrated additional need.
+
+The current decision is to preserve this research, skip the evidence API, and
+move managed persistence to one canonical log while keeping SDK ingestion costs
+unmeasured. The owner asked
+what we can learn from Voyage, not to add its format as an input. The earlier
+Voyage/ACP recording-reader proposal was removed after that correction.
+Keep Letta-backed conversation conversion and our central session identity.
+Keep native execution in HarnessAgent and durability in the optional Workflow
+integration. No new reader, schema or runtime behavior ships with this checkpoint.