Skip to content

feat(storage): read durable Session context refs - #4182

Merged
likun666661 merged 5 commits into
mainfrom
refactor/session-context-ref-reader
Aug 29, 2026
Merged

feat(storage): read durable Session context refs#4182
likun666661 merged 5 commits into
mainfrom
refactor/session-context-ref-reader

Conversation

@likun666661

@likun666661likun666661 commented Aug 29, 2026

Copy link
Copy Markdown
Member

Summary

  • Recognize durable session_context references as canonical StorageRef values, including exact shape, bounded identity, equality, and Runtime Host protocol validation.
  • Compose the context-offload authority into Runtime Host and route provider image-byte reads by reference kind: session_context uses the Session-bound Read image snapshot store, while session_file keeps the legacy ArtifactStore path.
  • Keep this as a reader-first expand slice: the Read builtin still publishes session_file, production composition gives context offload zero Session/workspace write quotas, and no copy, retirement, migration, or writer cutover is activated here.
  • Publish only the storage subpaths consumed by Runtime Host and preserve the lazy SQLite import boundary.

Refs #4071

Verification

  • npm --workspace @maka/core run typecheck
  • npm --workspace @maka/storage run typecheck
  • npm --workspace @maka/runtime run typecheck
  • npm --workspace @maka/runtime-host run typecheck
  • Full test:dist suites for core, storage, runtime, and runtime-host
  • Post-rebase targeted contract, routing, protocol, execution-composition, and execution-model-composition suites
  • npx biome lint and npx biome format on all changed source files

Rollout

This PR only makes already-durable context references readable. It does not publish new session_context references, so the writer/lifecycle cutover and its compatibility boundary remain in the next contraction PR.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex implemented the reader-first storage and Runtime Host wiring, added tests, and ran verification.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

@github-actionsgithub-actionsBot added the effort/M Under 500 readable lines label Aug 29, 2026
readonly sandboxDiagnostics: SandboxDiagnosticsProvider;
readonly memoryExtraction?: HostMemoryExtractionCoordinator;
readonly artifacts: HostExecutionArtifactAuthority;
readonly contextOffload?: InteractiveContextOffloadWriter;

@zhiiwzhiiwAug 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] The reader-only slice receives InteractiveContextOffloadWriter, which also exposes put, releaseReference, retireSession, and collectGarbage. Zero quotas do not constrain those destructive operations and even permit zero-byte puts, so the read-only invariant is not enforced by the authority boundary. Please introduce an authenticated read-only authority that exposes only read.

@likun666661likun666661Aug 29, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 91817d6. Model hydration now receives an authenticated InteractiveContextOffloadReader whose public surface is exactly kind, access, and read; the writer remains confined to storage composition and lifecycle preflight.

// ============================================================================

export type StorageRef =
| SessionContextRef

@zhiiwzhiiwAug 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Adding session_context to the global StorageRef union makes it flow through conversation copy, but rewriteStorageRef only rewrites session_file. A copied message therefore retains the source sessionId, and the target Session later fails to hydrate it with session_mismatch; Session retirement also does not release these references. Please add lifecycle handling or fail these operations explicitly until that owner exists.

@likun666661likun666661Aug 29, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 91817d6 for the reader-only slice. Exact conversation copy now rejects source-owned session_context refs, and Session removal checks context usage under admission and fails before the tombstone if any refs exist or if the Store is unavailable. The stacked writer PR will replace these guards with copy and retire lifecycle handling.

throw invalidProtocolFrame('Invalid AttachmentRef bytes');
}
if (attachment.ref.kind === 'session_file') {
if (attachment.ref.kind === 'session_file' || attachment.ref.kind === 'session_context') {

@zhiiwzhiiwAug 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] This decoder is also used by turn.message.submit, so the reader-first widening lets a peer persist arbitrary or dangling session_context references before the claimed writer cutover. Please use a direction-specific decoder or admission rule, or validate the active capability and referenced record before accepting this durable input.

@likun666661likun666661Aug 29, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 91817d6. Client admission now uses a direction-specific decoder that rejects Host-owned session_context attachments for turn.start, turn.message.submit, and hosted execution, while snapshot and result decoding continues to accept the ref kind.

return async (ref) => {
if (ref.kind === 'session_context') {
if (ref.sessionId !== input.sessionId) return { ok: false, reason: 'session_mismatch' };
if (!input.readImageSnapshots) return { ok: false, reason: 'unsupported_ref_kind' };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] When context storage fails to open, readImageSnapshots is omitted and a valid session_context reference is reported as unsupported_ref_kind. The binary supports this kind; the authority is unavailable. Please preserve the existing unavailable failure semantics so callers receive the actionable cause.

@likun666661likun666661Aug 29, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 91817d6. The attachment reader now distinguishes an unavailable context authority from an unsupported ref kind and returns unavailable; Runtime Host wires that state explicitly when the optional Store cannot open.

@likun666661
likun666661force-pushed the refactor/session-context-ref-reader branch from 91817d6 to 407a687CompareAugust 29, 2026 14:58

@Astro-HanAstro-Han left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

@likun666661
likun666661 merged commit 6fca2f5 into mainAug 29, 2026
14 checks passed
@likun666661
likun666661 deleted the refactor/session-context-ref-reader branch August 29, 2026 15:16
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/MUnder 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@likun666661@zhiiw@Astro-Han