Skip to content

feat(session): export and restore transcripts, and prewarm - #38

Merged
corasan merged 3 commits into
fm27/structured-outputfrom
fm27/transcript
Oct 16, 2026
Merged

corasan merged 3 commits into
fm27/structured-outputfrom
fm27/transcript

Conversation

@corasan

@corasan corasan commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Why

A session lives only as long as its JS object. A chat app cannot continue a conversation after a restart. The first request also pays a cold start that the app could hide.

Scope

  • session.transcript returns the conversation as a SerializedTranscript. This is a branded string that holds Apple's Transcript JSON from JSONEncoder. The library does not model Apple's schema. The only promise is that the value restores through new LanguageModelSession({ transcript }).
  • LanguageModelSessionOptions is now a union. A session starts from instructions or from transcript, not from both. TypeScript rejects both together. At runtime, the JS constructor throws INVALID_SESSION_OPTIONS. The JS constructor is the only entry point, so native code does not check again. Tools are passed again on restore. useCase and guardrails still apply.
  • Native restore uses LanguageModelSession(model:tools:transcript:). INVALID_TRANSCRIPT means only a decode failure. It has a short reason, for example missing key 'version' or Unsupported Transcript version: 9.9.
  • session.prewarm(promptPrefix?) forwards to LanguageModelSession.prewarm(promptPrefix:). The SDK method is sync, so the JS method is sync too.
  • useLanguageModel accepts transcript in its config. It builds the matching member of the options union, without a cast.
  • HybridLanguageModelSession keeps its mutable state (session, busy flag, context-reset flag) in one SessionState behind a Synchronization.Mutex. The busy check is one check-and-set. Recovery replaces the session and sets the reset flag in one update. transcript and prewarm read the session through the lock. The session is not optional, so the sessionNotInitialized error case is removed.
  • The example chat screen has "Save transcript" and "Restore" buttons. The transcript is kept in memory, because AsyncStorage is not a dependency.

The issue proposed a transcript getter. The native side is a sync method (serializeTranscript()), because Nitro property getters in Swift cannot throw.

Latent bug fixed

Context-overflow recovery built the replacement session with the base instructions hard-coded as "You are a helpful assistant". Every session lost its own instructions after an overflow. A restored session has no config.instructions, so the restore feature would make this worse. The session now keeps its base instructions from init. For a restored session, these come from the transcript's instructions entry. SessionInstructions owns the instruction format. On restore it strips any earlier summary and the old tool list from the transcript's instructions, then recomposes them with the tools passed on restore. Recovery appends one summary to that base, so summaries do not stack across save, restore and overflow cycles, and recovery never advertises tools the session no longer has.

Tradeoffs

  • A transcript read from storage needs a cast: stored as SerializedTranscript. The brand stops callers from building a transcript by hand, and it costs one cast at the storage boundary.
  • The transcript format belongs to Apple. The iOS 27 decoder writes and accepts only "version":"1.1". It rejects "1.0" and unknown entry roles and segment types. A transcript that holds iOS 27-only content (reasoning entries, attachment segments) is not expected to restore on iOS 26. I did not test on iOS 26, and I do not know which version iOS 26 writes. The docs tell apps to treat INVALID_TRANSCRIPT as a normal result after an OS update.

Blast Radius

  • LanguageModelSessionOptions and UseLanguageModelConfig change from interfaces to type aliases. Code that extends them breaks, and must use an intersection type. The CHANGELOG has a BREAKING entry. Code that passes object literals does not change.
  • The recovered session after an overflow now keeps the caller's instructions, not "You are a helpful assistant". This changes model behavior after recovery. I expect this is the intended behavior.
  • New error codes: INVALID_TRANSCRIPT, INVALID_SESSION_OPTIONS, TRANSCRIPT_ENCODING_ERROR.
  • No #if compiler guard is needed. All APIs used are iOS 26.

Verification

  • bun run test (75 pass; three tests that only restated the mock are deleted), bun run test:swift (new TranscriptCodingTests round-trip encode and decode, and invalid JSON, {}, and unsupported version map to INVALID_TRANSCRIPT), typecheck, lint, format:check.
  • Example app on the iPhone 18 Pro simulator with iOS 27.0 and the real model:
    • UI: I sent "My name is Ana. Please remember it". The model replied "Thank you, Ana. You're remembered." I tapped Save transcript (1884 chars), then Restore ("Restored into a new session"), then asked "What is my name?". The model replied "Your name is Ana."
    • API through the debugger: session A learned the name, then session B was built from A.transcript and answered "Ana.". A control session with no transcript answered "I don't have access to personal information like your name."
    • 'not json', '{}' and version 9.9 each throw AppleAIError with code INVALID_TRANSCRIPT. Instructions together with a transcript throw INVALID_SESSION_OPTIONS. prewarm() and prewarm('What is') run without an error.
    • Overflow on a restored session whose instructions were "The secret word is PAPAYA." gave CONTEXT_EXCEEDED and wasContextReset: true. session.transcript then read the replacement session, whose instructions are "The secret word is PAPAYA.\n\nPrevious conversation summary: …".

Closes #23

@corasan
corasan added this pull request to stack #36 September 23, 2026 20:10
@corasan
corasan force-pushed the fm27/transcript branch 2 times, most recently from 9311823 to cb0cda5 Compare September 24, 2026 23:15
HybridLanguageModelSession now holds its mutable state (session, busy
flag, context-reset flag) in one SessionState behind a Synchronization
Mutex. The busy check is one check-and-set under the lock, context
recovery replaces the session and sets the reset flag in one update, and
serializeTranscript and prewarm read the session through the lock. The
session is no longer optional, so the sessionNotInitialized guards and
the error case are gone.

The native instructions-and-transcript guard is gone. The JS
constructor is the only entry point and already throws
INVALID_SESSION_OPTIONS, so INVALID_TRANSCRIPT now means only that the
transcript cannot be decoded.

useLanguageModel builds the matching options union member instead of
casting. Tests that only restated the mock (transcript forwarding,
transcript re-read, prewarm forwarding) are deleted.

BREAKING CHANGE: LanguageModelSessionOptions and UseLanguageModelConfig
are type aliases for a union of instructions or transcript. An interface
that extends either type no longer compiles; use an intersection type.
…thout old summaries

A restored session took its base instructions verbatim from the transcript, so each save, restore and overflow cycle appended another summary and recovery kept advertising the tools of the original session. The base is now the caller's instructions with the summary and tool list stripped, recomposed with the tools passed on restore.
@corasan
corasan merged commit cc4e4a2 into main Oct 16, 2026
12 checks passed
@corasan
corasan deleted the fm27/transcript branch October 16, 2026 23:13
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.

Persist and restore session transcripts, and prewarm sessions

1 participant