trajectories 0.0.0 → 0.1.2

package/docs/research/ledger/docs/research/2026-09-09-daemon-observation.md

@@ -0,0 +1,231 @@
+# Integrated daemon observation
+
+Status: operational retest passed at source revision `6bd64b7`; the supervised
+daemon remains running. Failed attempts are retained. Corpus coverage and raw
+archival retention are not complete.
+
+## Question and acceptance
+
+Can the integrated Ledger watcher preserve the existing index, make new native
+records searchable under launchd, and continue bounded backfill without loading
+an entire large JSONL transcript?
+
+Acceptance requires a schema-6 migration with no missing existing record hashes,
+the recovered Claude prompt slice still searchable, a supervised foreground
+process, automatic import and append of a labeled synthetic canary, and continued
+cursor progress. A successful process start or populated database alone is not
+acceptance. This trial does not establish complete corpus coverage, raw archival
+retention, exactly-once effects, or steady-state fleet capacity.
+
+## Frozen protocol
+
+- Target: this Mac's stable Ledger checkout at merged revision
+  `56b51e2b76d8d37f749bb114f5b73f1e40164cf9`, Bun 1.4.0,
+  installed Trajectory 0.3.0. Both PRs are merged before launch.
+- Host: Apple Silicon macOS, 10 CPU cores, 24 GiB physical memory. Other desktop
+  work continues; this is an operational observation, not an isolated benchmark.
+- Database: create a SQLite backup of the existing checkout index, preserving the
+  original. Migrate only the candidate, verify identity-adjusted record hashes,
+  then install the candidate at the service's dedicated data path.
+- Workload: native-source discovery and bounded catch-up, plus a clearly labeled
+  synthetic Pi JSONL canary with three sequential append observations. No private
+  transcript bodies, titles, credentials, or environment dumps in reports.
+- Service settings: lexical ingestion, 60-second reconciliation, 25 candidate
+  sessions per source per tick, explicit discovery limit 1,000,000 per source,
+  1 MiB target normalization chunks, adaptive individual records up to 64 MiB.
+  The record-input ceiling is not a peak-RSS guarantee.
+- Observe the explicit process tree and read-only aggregate DB state at one-second
+  cadence for at least 180 seconds. Record baseline, sampled peak, and end RSS,
+  cumulative CPU and sampled CPU demand, wall time, query responsiveness, cursor
+  progress, failures, and supervision state. Keep unavailable I/O measurements
+  explicit rather than reporting zero. The service remains running afterward.
+- Repetition: one operational service run, three canary appends. Do not infer
+  stable percentiles or capacity from this sample.
+- Model/token accounting: no model or embedding generation in the daemon trial;
+  model tokens and cache counters are not applicable. Agent engineering work is
+  outside the sampled daemon process tree.
+- Preserve private raw observation artifacts and hashes locally; publish only a
+  compact verdict and sanitized evidence. Validate the trial record with the
+  personal evaluation-engineering checker and disclose missing measurements.
+
+## Exploratory metadata
+
+Before installation, the original schema-v3 index contains 190 sessions and
+68,301 canonical records: 2 Claude sessions and 188 Cursor sessions. One Claude
+session is the separately recovered prompt-history slice. These counts do not
+establish complete coverage.
+
+A paginated metadata-only discovery returned 14,493 candidate sessions:
+6,227 Claude, 3,406 Codex, 187 Pi, 1 Letta Code, 137 Droid, 2,705 Cursor,
+and 1,830 OpenCode. Files can change while discovery runs; these are candidate
+listings, not successfully normalized sessions or an immutable corpus manifest.
+An earlier over-limit probe was invalid because upstream page size is capped at
+1,000; the scanner now paginates instead of reporting those sources as empty.
+
+Byte framing of six large files, without decoding transcript values, found a
+roughly 750 MB Claude file and Codex files up to 419 MB. The largest observed
+individual JSONL row was 4,184,489 bytes. This motivated separating the 1 MiB
+batch target from the individual-record ceiling.
+
+## Results
+
+### Pre-observation startup attempt
+
+The schema-6 candidate retained all 190 sessions and all 68,301 original record
+hashes after source-prefix adjustment. The recovered prompt slice retains 78
+records and the scoped `benchflow` query returns its historical hit. Integrity
+and foreign-key checks pass. The original schema-3 database remains unchanged.
+
+The first launchd attempt used the checkout below `~/Documents/Codex/`. It
+stalled before opening SQLite: a one-second process sample remained in
+`getcwd -> open`, and the matching macOS TCC event requested
+`kTCCServiceSystemPolicyDocumentsFolder` for Bun. This is a failed startup, not
+an ingestion run. The service was unloaded; no OS security policy was changed.
+
+For the observation, the same merged revision was cloned to
+`~/workspace/personal/ledger`, dependencies installed from the frozen lockfile,
+and the service reinstalled from that stable checkout. The dedicated database
+and rollback copy are outside Documents. This path correction is fixed before
+the ingestion observation begins. Service logs were set to mode 0600; their
+parent directory is 0700. The installer's shell umask alone does not govern
+files created by launchd.
+
+### Ingestion observation
+
+The first full observation completed its 180.120-second collection window with
+175 samples, zero collection errors, and zero query timeouts. **Ingestion
+acceptance failed:** sessions remained 190, records 68,301, and persisted cursors
+zero. The synthetic import returned zero hits after 90.199 seconds (90 polls,
+zero query errors); subsequent appends were not attempted.
+
+Attach-time RSS was 69,058,560 bytes, sampled peak 82,165,760 bytes, and end RSS
+74,088,448 bytes. The observed process tree consumed at least 132.15 CPU-seconds;
+peak sampled demand was 1.0015 cores. This is wasted startup work, not measured
+ingestion throughput. Per-process I/O and post-teardown memory were not measured.
+
+The watcher recursively subscribes to each directory and also manually walks
+its descendants, including broad agent homes containing plugins and worktrees.
+All of this precedes the first reconcile. A process sample during the failed
+window shows deep repeated filesystem recursion. The process was unloaded and
+its exit verified after collection. The original DB and failed-run artifacts
+remain intact.
+
+### Revised-run protocol
+
+Retain the same migration, search, import, three-append, and cursor-progress
+acceptance criteria. Before another run, narrow automatic subscriptions to
+actual transcript stores, retain shallow parent watches for store creation,
+and use manual per-directory watches only as a platform fallback. Keep all
+sources and periodic reconciliation. Test those properties before deployment;
+record the committed revised source SHA before launch. Repeat the 180-second
+collection on the same dedicated DB and a new labeled canary. Preserve the
+failed attempt rather than replacing it with the retest. This is a single
+operational retest, not a controlled throughput or capacity comparison.
+
+The retest's watcher change is committed at `750f7b8`, with installer changes at
+`952f9078b3fe188d9e916915d9e772ae50fe0709`. Before deployment, the combined core
+suite passed 182 tests and 1,087 assertions across 19 files; the observer suite
+passed 10 tests and 79 assertions. Typecheck and whitespace checks passed.
+
+Independent review then found quadratic ancestor lookup in the unsupported
+recursive-watch fallback. A 512-directory fixture measured 131,842 candidate
+visits; the recursive-only registry reduces that counter to zero. The final
+deployment is `6bd64b717e646b0d62d31eb833f3dff0736e4456`, with 183 passing core
+tests, 1,097 assertions across 19 files, and passing typecheck. The same 10-test
+observer gate remains green. This final revision was captured before launch,
+along with source-tree, runtime binary, watcher, lockfile, and protocol hashes.
+
+### Retest results
+
+The 180.186-second run completed with 175 process samples and 33 read-only DB
+samples, zero collection errors, and zero query timeouts. The installed service
+started once and remained the same supervised process throughout.
+
+| Measurement | Observed result |
+| --- | --- |
+| Indexed sessions | 267 -> 752; increase 485 |
+| Canonical records / FTS rows | 71,745 -> 123,896; increase 52,151, equal at each endpoint |
+| Cursor bytes ingested | 32,656,746 -> 404,526,886; progress 371,870,140 bytes |
+| Synthetic initial import | Searchable after 10.024 seconds |
+| Three sequential appends | Searchable after 12.032, 9.021, and 3.007 seconds |
+| Attach / sampled peak / end RSS | 249,462,784 / 347,127,808 / 289,652,736 bytes |
+| Observed CPU-seconds / peak sampled cores | 130.26 / 1.0173 |
+| Aggregate DB subprocess elapsed range | 89.141-566.350 ms; includes process startup |
+| Failed cursors at window end | 61; not hidden as successful coverage |
+
+Canary visibility is polled at one-second intervals under ongoing native
+backfill; these are observed end-to-end latencies, not latency percentiles.
+Cursor byte totals are logical progress, not disk-I/O counters. The two native
+canary files are explicitly synthetic and remain labeled in the Pi store.
+The sampled RSS peak is about 331 MiB, not a hard memory bound.
+
+A later coherent read transaction found 1,523 sessions, 190,501 records and the
+same number of FTS rows, zero foreign-key violations, and two staged replacement
+sessions. All 78 recovered Claude prompts remained present; the scoped
+`benchflow` historical query still returned its hit (5.656 ms for that probe).
+This post-window snapshot demonstrates continued progress, not an extension of
+the frozen measurement window or complete archival preservation.
+
+The actual CLI was also checked after the window using `query benchflow` with
+`--source claude-code --limit 20 --robot --json` and the dedicated DB. Its
+structured response contained nine hits, including the recovered history slice,
+with exit zero and no stderr. The fully checked end-to-end invocation took
+4.645 seconds under continuing backfill; do not confuse that with the isolated
+SQL-query duration above or infer stable latency from this probe.
+
+The service uses the committed PR7 implementation from
+`~/workspace/personal/ledger` and `~/.local/share/ledger/ledger.sqlite`. It remains
+installed under user launchd label `com.archeism.ledger`. PR2 and PR6 are already
+merged; this operational follow-up is kept as its own PR.
+
+### Residual failures
+
+Observed failed receipts included 33 small Cursor `/projects/` JSONL files
+totaling 5,490 bytes, additional Cursor JSONL files, and 25 OpenCode JSON files
+totaling 958,856 bytes. No failed-file payloads were opened for this triage.
+Their metadata cannot establish whether they are malformed, metadata-only,
+configuration, or unsupported transcript exports. Zero checkpoint bytes does
+not mean zero file reads. The successful run observed ingestion from Claude,
+Codex, Cursor, Pi, Droid, and Letta Code; it does not establish all-source recall.
+
+Source inspection confirms two remaining issues. Custom discovery primarily
+filters by extension, while OpenCode normalization expects a whole
+`{info, messages}` export. Also, non-JSONL failures currently omit the cache
+receipt fields needed to skip an unchanged failure. A newest-first budget can
+therefore keep retrying the same 25 files before older valid exports. This is a
+confirmed scheduling mechanism, not proof that valid older OpenCode exports
+exist in this corpus. Cursor JSONL failures already have fingerprint-bound
+negative caching.
+
+Follow-up work: tighten export eligibility, retain controlled failure reasons,
+distinguish deterministic failures from transient retries, and separate fresh
+work from retry scheduling. A regression should place 25 newer invalid JSON
+fixtures ahead of one older valid export, then change a failed fixture into a
+valid export and require recovery. These changes are not claimed as implemented
+by this PR. See `scanner.ts:194`, `ingest.ts:122`, and `watch.ts:443` at the final
+deployment revision.
+
+## Remaining optimization
+
+The [bounded pagination probe](2026-09-09-discovery-pagination.md) confirms that
+Trajectory 0.3.0 inventories a source again for every page. Two pages over 1,002
+synthetic files caused 2,004 stat operations and four directory reads. This is
+not evidence that pagination caused the measured startup stall. There is no
+public single-inventory API in the installed package. Keep full discovery
+coverage and the published normalizer; request an upstream inventory boundary
+before replacing this with private imports or copied discovery code.
+
+Both failed-attempt evaluation records validate structurally and remain
+`complete: false`: per-process I/O and post-teardown memory were not collected,
+and the TCC startup attempt lacks a full resource trace. Original artifacts and
+checksums are private under `.local/integrate-7wV4FS/evaluation/` in the retained
+development checkout. No private transcript contents are published here.
+
+The third record, `evaluation/attempt-03-operational-retest/run.json`, also
+validates with no errors and `complete: false` for the same unmeasured I/O and
+teardown fields. Its operational rubric passes. Six negative controls reject
+changed hashes, fabricated zero teardown memory, absent record progress, a
+missing append, missing historical evidence, and a service restart. The frozen
+protocol is recovered from Git revision `6bd64b7` and matches its prelaunch
+hash; this document's subsequently appended results are not substituted for
+the trial input. All prior archive files remain unchanged.

package/docs/research/ledger/docs/research/2026-09-09-discovery-pagination.md

@@ -0,0 +1,114 @@
+# Discovery pagination: bounded enumeration evidence
+
+2026-09-09. **Measured future optimization, not an implemented change.** Retain
+published Trajectory normalization and complete discovery; do not replace its
+discovery layer or depend on private imports to optimize pagination.
+
+## Pin and public boundary
+
+- Installed and [lockfile-resolved](https://github.com/archeism/ledger/blob/43081aef54c23b4bd017b6c0e11fc42a9a1cb381/packages/core/bun.lock) package:
+  `@letta-ai/trajectory@0.3.0`. Inspected upstream pin:
+  [`21ae92d10579499b183d93929c85da0b91233167`](https://github.com/letta-ai/trajectory/tree/21ae92d10579499b183d93929c85da0b91233167).
+- The only public discovery function is `listTrajectories`. There is no
+  `listSourceSessions`, inventory snapshot API, or public adapter lister.
+  [Entrypoint](https://github.com/letta-ai/trajectory/blob/21ae92d10579499b183d93929c85da0b91233167/src/index.ts#L181-L186).
+- Package subpaths expose only `.`, `./schema`, `./schema/canonical`, and
+  `./package.json`. Resolving `dist/listing.js` or `dist/adapters/omp/list.js`
+  through the package name returned `ERR_PACKAGE_PATH_NOT_EXPORTED` in Node.
+  An internal function's `export` declaration is not a public package contract.
+  [Export map](https://github.com/letta-ai/trajectory/blob/21ae92d10579499b183d93929c85da0b91233167/package.json#L17-L25).
+- Every page calls the source lister again before pagination; page size is capped
+  at 1,000. The cursor retains identity/position, not an inventory snapshot.
+  [Dispatch and pagination](https://github.com/letta-ai/trajectory/blob/21ae92d10579499b183d93929c85da0b91233167/src/listing.ts#L74-L153).
+
+## Observation and limits
+
+Node `v24.18.1`, macOS arm64; 1,002 synthetic empty JSONL files in one temporary
+project, separately listed as Pi and OMP. Pass-through instrumentation counts
+filesystem API calls under the fixture root, not kernel syscalls or physical I/O.
+
+| Source (each independently) | Cumulative items | `statSync` | `readdirSync` | `readFileSync` |
+| --- | ---: | ---: | ---: | ---: |
+| Pi / OMP, page 1 | 1,000 | 1,002 | 2 | 0 |
+| Pi / OMP, pages 1 + 2 | 1,002 | 2,004 | 4 | 0 |
+
+Thus two pages repeat inventory metadata work. There were no fixture-content
+reads: these listers discover metadata without normalizing the empty files.
+Bun `1.4.0` did not expose named filesystem imports to this instrumentation;
+its zero counters were rejected, not treated as zero I/O. Counts above are from
+Node, not a Bun timing comparison.
+
+Ledger's audited `5d629ec3058485327a84c963f8c73997e46acbc1` scanner accumulated
+all pages before the watcher applied its import budget. This is a source-backed
+delay mechanism, **not a measured cause of the reported 90/130-second daemon
+observations, nor a throughput, memory, latency, or capacity result**. No native
+corpus, real database, model, embedding, or daemon was exercised by this probe.
+
+## Deferred public API proposal
+
+An upstream public full-inventory function, for example
+`listSourceSessions({ source, root }) -> Promise<TrajectoryListing[]>`, could
+reuse the existing listers once. This is a proposed name/contract, not an API
+available in `0.3.0`. Ledger could then enumerate children for **all OMP parents**
+before sorting and applying its final combined budget. No parser is copied and
+published canonical normalization remains unchanged. Until such a supported API
+exists, retain current complete pagination rather than lower coverage limits,
+deep-import internals, or add a large duplicate discovery implementation.
+No upstream issue or change has been submitted or authorized by this note.
+
+## Reproduce
+
+From the repository root with dependencies already installed and Node 24.18.1:
+the command imports only public package entrypoints, creates 1,002 temporary empty
+files, asserts counts/coverage, and removes the fixture in `finally`.
+
+```sh
+cd packages/core
+node --input-type=module <<'JS'
+import fs from "node:fs";
+import { createRequire, syncBuiltinESMExports } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+const require = createRequire(import.meta.url);
+assert.equal(require("@letta-ai/trajectory/package.json").version, "0.3.0");
+const root = fs.mkdtempSync(join(tmpdir(), "ledger-listing-count-"));
+const project = join(root, "sessions", "project");
+const original = { statSync: fs.statSync, readdirSync: fs.readdirSync,
+  readFileSync: fs.readFileSync };
+let counts = [0, 0, 0]; // stat, directory enumeration, content read
+try {
+  fs.mkdirSync(project, { recursive: true });
+  for (let i = 0; i < 1002; i++)
+    fs.writeFileSync(join(project, `session-${String(i).padStart(4, "0")}.jsonl`), "");
+  Object.keys(original).forEach((method, index) => {
+    fs[method] = function (...args) {
+      if (String(args[0]).startsWith(root + "/")) counts[index]++;
+      return Reflect.apply(original[method], fs, args);
+    };
+  });
+  syncBuiltinESMExports();
+  const api = await import("@letta-ai/trajectory");
+  assert.deepEqual(Object.keys(api).filter(k => /^list/.test(k)), ["listTrajectories"]);
+  for (const source of ["pi", "omp"]) {
+    counts = [0, 0, 0];
+    const first = await api.listTrajectories({ source, root, limit: 1000 });
+    assert.equal(first.items.length, 1000);
+    assert.ok(first.nextCursor);
+    assert.deepEqual(counts, [1002, 2, 0]);
+    console.log(JSON.stringify({ source, pages: 1, items: 1000, counts }));
+    const second = await api.listTrajectories({ source, root, limit: 1000,
+      cursor: first.nextCursor });
+    assert.equal(second.items.length, 2);
+    assert.equal(second.nextCursor, undefined);
+    assert.equal(new Set([...first.items, ...second.items].map(x => x.path)).size, 1002);
+    assert.deepEqual(counts, [2004, 4, 0]);
+    console.log(JSON.stringify({ source, pages: 2, items: 1002, counts }));
+  }
+} finally {
+  Object.assign(fs, original);
+  syncBuiltinESMExports();
+  fs.rmSync(root, { recursive: true, force: true });
+}
+JS
+```

package/docs/research/ledger/docs/research/2026-09-09-harness-transcript-contract.md

@@ -0,0 +1,145 @@
+# Trajectory discovery and AI SDK Harnesses transcript contracts
+
+## Answer
+
+**Trajectory parses Cursor and OpenCode exports but does not discover their local
+stores.** This was verified against installed and latest published `0.3.0`, current
+upstream source, and direct public-API probes below. Ledger's broad custom file
+scanner is not functionality inherited from Trajectory.
+
+**Vercel unifies live turn input/output and session lifecycle, not historical
+transcript ingestion or a canonical archive.** Applications can use common AI SDK
+messages and streams across harnesses, but each native runtime still owns its
+conversation history. Passing old messages to `HarnessAgent` does not import that
+history: it selects the latest user message, with separate handling for pending
+tool continuations. [History contract](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/content/docs/03-ai-sdk-harnesses/02-harness-agent.mdx#L188-L201),
+[implementation](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/harness-agent.ts#L833-L885).
+
+## Pins and scope
+
+- Refreshed GitHub `main` on 2026-09-09 at 01:41 UTC:
+  [`45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563`](https://github.com/vercel/ai/commit/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563).
+  This supersedes the earlier `46cea633cf7286386eb4e70f9c04413c57723d35` research pin.
+- Public npm metadata reported `@ai-sdk/harness` **1.0.104**, Claude Code
+  **1.0.108**, and Codex **1.0.106**. Their release tags all resolved to
+  [`db450a22f14c21fe734f0592bcde191a4515bc1c`](https://github.com/vercel/ai/commit/db450a22f14c21fe734f0592bcde191a4515bc1c).
+  The collected release-to-HEAD comparison showed no changes under those three
+  package directories. Thus the examined package contracts also exist in
+  release-tag source, not only unreleased main. Built tarballs were not audited.
+  [Harness metadata](https://registry.npmjs.org/@ai-sdk/harness/1.0.104),
+  [Claude metadata](https://registry.npmjs.org/@ai-sdk/harness-claude-code/1.0.108),
+  [Codex metadata](https://registry.npmjs.org/@ai-sdk/harness-codex/1.0.106).
+- Official source docs still label harness packages **experimental**, despite
+  published 1.0 versions. [Status](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/content/docs/03-ai-sdk-harnesses/01-overview.mdx#L25-L36).
+- Bounded inspection: public GitHub tree, exported core/session interfaces,
+  eleven adapter entrypoints, official source docs, and decisive Claude/Codex
+  implementation and test paths. Tests were read, not run. No local upstream
+  clone, installation, model execution, daemon, database, or personal transcript
+  access. Findings below describe these inspected surfaces, not every native
+  SDK capability or deployed documentation version.
+
+## Trajectory: parsing is separate from discovery
+
+On 2026-09-09, the installed package and npm's `latest` metadata both reported
+`@letta-ai/trajectory` **0.3.0**. The registry's `gitHead` and a live GitHub `main`
+lookup agreed on
+[`21ae92d10579499b183d93929c85da0b91233167`](https://github.com/letta-ai/trajectory/commit/21ae92d10579499b183d93929c85da0b91233167).
+[Published metadata](https://registry.npmjs.org/@letta-ai/trajectory/0.3.0).
+
+| Source | Supported normalization input | Local-store listing |
+| --- | --- | --- |
+| Cursor | Captured role/message content-block JSONL, documented from SWE-chat; callers supply the group identity for canonical normalization. | Intentionally unavailable: this capture is not a documented Cursor local-store format. [Adapter contract](https://github.com/letta-ai/trajectory/blob/21ae92d10579499b183d93929c85da0b91233167/src/adapters/cursor/README.md#L1-L25). |
+| OpenCode | An assembled whole-session JSON document with `info` and `messages`, whose entries contain message metadata and parts. | Intentionally unavailable: the caller provides the assembled export. [Adapter contract](https://github.com/letta-ai/trajectory/blob/21ae92d10579499b183d93929c85da0b91233167/src/adapters/opencode/README.md#L1-L34). |
+
+The public lister distinguishes known normalization-only sources from unknown
+sources, returning `listing_unavailable` for both Cursor and OpenCode.
+[Dispatch and classification](https://github.com/letta-ai/trajectory/blob/21ae92d10579499b183d93929c85da0b91233167/src/listing.ts#L56-L110).
+
+Bounded local verification used the installed package, no private inputs, and no
+database or model calls:
+
+| Probe | Cursor | OpenCode |
+| --- | --- | --- |
+| `listTrajectories({ source, limit: 1 })` | `NormalizationError`: `listing_unavailable` | `NormalizationError`: `listing_unavailable` |
+| `normalizeTranscript` on a synthetic user/assistant exchange in the documented format | Three records: meta, user, assistant; one `timestamps_synthesized` diagnostic | Three records: meta, user, assistant; zero diagnostics |
+
+Ledger therefore does need a caller-side discovery/export step for these sources.
+The current custom scanner selects by directory, depth and filename extension,
+not by a complete export-eligibility check. Its false candidates are a Ledger
+discovery issue; swapping the call to `listTrajectories()` would instead make
+both sources unavailable. [Ledger scanner](https://github.com/archeism/ledger/blob/43081aef54c23b4bd017b6c0e11fc42a9a1cb381/packages/core/src/scanner.ts).
+No ingestion behavior or dependency was changed by this research.
+
+## What Vercel makes common
+
+| Surface | Actual contract |
+| --- | --- |
+| Application history | `UIMessage` has `id`, role, optional metadata, and typed `parts`. This is an application/UI representation, not an assertion that all native execution evidence is included. [Shape](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/content/docs/07-reference/01-ai-sdk-core/31-ui-message.mdx#L50-L75). |
+| Turn input | AI SDK accepts `ModelMessage[]`, but the adapter receives only `string \| UserModelMessage` for a fresh turn. Prior history stays native. A regression explicitly verifies older user/assistant turns are discarded. [Adapter input](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/v1/harness-v1-prompt.ts#L1-L11), [test](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/harness-agent.test.ts#L3139-L3166). |
+| Adapter events | `HarnessV1StreamPart` standardizes text/reasoning, tool input/call/approval/result, step/turn finish, usage, errors, file changes, compaction, and a raw escape hatch. It reuses LanguageModelV4 primitives; it is not itself `UIMessage`. [Union](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/v1/harness-v1-stream-part.ts#L15-L137), [type-compatibility tests](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/v1/harness-v1-stream-part.test-d.ts#L25-L95). |
+| Consumer output | Adapter events become AI SDK `TextStreamPart`s; `harnessMetadata` becomes `providerMetadata`. The documented UI route uses `convertToModelMessages`, `agent.stream`, then `toUIMessageStream({ stream: result.stream })`. [Translation](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/internal/translate-stream-part.ts#L5-L27), [UI route](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/content/docs/03-ai-sdk-harnesses/07-ui.mdx#L153-L190). |
+| Result messages | `responseMessages` is constructed from the current result's accumulated content as assistant/tool model messages. It is not a session-history getter. [Construction](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/internal/harness-stream-text-result.ts#L397-L405), [conversion](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/internal/harness-stream-text-result.ts#L472-L482). |
+
+## Session continuity is not transcript access
+
+`createSession({ sessionId, resumeFrom })` restores a known session;
+`continueFrom` restores an unfinished turn. `detach()` and `stop()` return opaque
+resume state; `destroy()` ends without resumability. The envelope identifies
+`harnessId`, specification version, adapter-defined JSON `data`, and optional
+continuation/tool state. That is a common lifecycle envelope, not a portable
+cross-provider conversation. [Creation API](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/harness-agent.ts#L284-L340),
+[state types](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/v1/harness-v1-lifecycle-state.ts#L59-L119).
+
+The complete common `HarnessV1Session` interface exposes prompt/continue,
+compaction, suspend, detach, stop, and destroy. **It has no session listing,
+history retrieval, transcript export, or historical import method.** The inspected
+public adapter entrypoints likewise expose adapter factories/settings/types,
+not a cross-harness history service. This is a scoped API finding, not a claim
+that Claude's or Codex's own SDKs cannot inspect their native histories.
+[Session interface](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/v1/harness-v1-session.ts#L152-L258),
+[Claude exports](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-claude-code/src/index.ts#L1-L15),
+[Codex exports](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-codex/src/index.ts#L1-L14).
+
+Claude resumes the exact observed native conversation ID through the SDK's
+`resume` option, falling back to cwd-based continuation only without an exact
+ID. Codex retains a native `threadId` and calls `codex.resumeThread`.
+Neither path enumerates old host-local transcripts and converts them into a
+common historical dataset. [Claude resume](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-claude-code/src/bridge/index.ts#L511-L528),
+[Codex state](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-codex/src/codex-harness.ts#L175-L188),
+[Codex resume](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-codex/src/bridge/index.ts#L205-L218).
+
+Storage remains application-owned: the official session-store example keeps
+opaque resume state in a map and explicitly requires durable storage in
+production. It is not a retained-source archive or historical discovery/import
+service. This is a stronger distinction than merely observing that bridge event
+replay is not archival commitment. [Storage boundary](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/content/docs/03-ai-sdk-harnesses/07-ui.mdx#L97-L145).
+
+## Fidelity limits
+
+- **Claude:** messages with `parent_tool_use_id` are excluded from the parent
+  text/tool projection. The regression asserts no child-agent events leak into
+  that stream. A captured parent stream therefore cannot reconstruct the full
+  child execution. [Filter](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-claude-code/src/bridge/create-emit-stream-event.ts#L213-L218),
+  [test](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-claude-code/src/bridge/create-emit-stream-event.test.ts#L470-L522).
+- **Codex:** completed file changes become operation/path events; MCP results
+  prefer `structured_content` over `content` rather than preserving the native
+  result envelope. This is selective normalization, not a reversible native
+  transcript encoding. [Projection](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-codex/src/bridge/create-emit-stream-event.ts#L226-L271).
+- **Raw is not automatic preservation:** the common union permits
+  `{ type: 'raw', rawValue }` and the translator forwards it, but the inspected
+  Claude/Codex native loops feed their selective emitters without also emitting
+  each original native event as `raw`. The escape hatch does not recover events
+  those adapters never emit. [Raw forwarding](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/internal/translate-stream-part.ts#L252-L257),
+  [Claude loop](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-claude-code/src/bridge/index.ts#L582-L600),
+  [Codex loop](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness-codex/src/bridge/index.ts#L234-L264).
+- **SDK projection adds synthetic events:** file changes and compaction become
+  dynamic, provider-executed tool-call/result pairs with generated IDs. These
+  make UI rendering uniform; they are not original native tool calls or stable
+  source-record identities. [Translation](https://github.com/vercel/ai/blob/45f2b6a5bc06bdb40a847ea961f8d7ca7cd86563/packages/harness/src/agent/internal/translate-stream-part.ts#L165-L247).
+
+**Ledger implication (inference):** HarnessAgent is useful as a live integration
+boundary. Its normalized streams and opaque lifecycle state do not replace
+historical source discovery, native-source retention, provenance/identity, or a
+durable canonical archive. An application may persist UI messages for its own
+chat history, but that does not establish complete cross-harness execution
+evidence. No new implementation or adoption decision is made here.