@defrex/autobuild 0.8.0

package/packages/core/src/store/remote/token.ts

@@ -0,0 +1,137 @@
+/**
+ * HMAC-scoped store tokens (SPEC §8.1 [D8]): "the token is scoped to this
+ * build and session — an agent physically cannot append to another build's
+ * log or read another build's artifacts". Least privilege comes from the
+ * runner minting a narrow token, not from prompt instructions.
+ *
+ * A token is `base64url(JSON scope) + '.' + base64url(hmac-sha256(secret,
+ * payload))`. The scope IS the token — the server keeps no session state;
+ * it verifies the signature (timing-safe) and the expiry, then trusts the
+ * embedded scope.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { z } from 'zod'
+import { viaSchema, type Via } from '../../events/envelope'
+
+export interface LegacyBuildTokenScope {
+  /** Retained wire compatibility for all existing build-scoped tokens. */
+  build: string
+  session: string
+  exp: number
+}
+
+export interface ResourceTokenScope {
+  resource: {
+    kind: 'build' | 'repo' | 'session'
+    id: string
+  }
+  session: string
+  exp: number
+  /** Delegated-write attribution (§15.1): when present, the hosted service
+   * stamps this via onto human-actor event writes and rejects writes claiming
+   * a via the token does not carry. A session resource token's authority is
+   * exactly its one session. */
+  via?: Via
+}
+
+/** Human operator authority is deliberately disjoint from raw store authority.
+ * The signed nonblank user claim attributes every operator API event. An
+ * unscoped operator token carries no via claim, so any write claiming a via
+ * under it is rejected. */
+export interface OperatorTokenScope {
+  operator: { user: string }
+  exp: number
+  via?: Via
+}
+
+/** Deployment authority used by dispatchers for raw store and hosted ticket
+ * routes. It intentionally does not grant access to attributed operator APIs. */
+export interface DeploymentTokenScope {
+  operator: true
+  session: string
+  exp: number
+}
+
+/** Legacy scopes remain valid on their existing routes. */
+export type TokenScope =
+  | LegacyBuildTokenScope
+  | ResourceTokenScope
+  | OperatorTokenScope
+  | DeploymentTokenScope
+
+const commonScope = {
+  session: z.string().min(1),
+  exp: z.number().int(),
+}
+const tokenScopeSchema = z.union([
+  z.strictObject({ build: z.string().min(1), ...commonScope }),
+  z.strictObject({
+    resource: z.strictObject({
+      kind: z.enum(['build', 'repo', 'session']),
+      id: z.string().min(1),
+    }),
+    ...commonScope,
+    via: viaSchema.optional(),
+  }),
+  z.strictObject({
+    operator: z.strictObject({ user: z.string().trim().min(1) }),
+    exp: z.number().int(),
+    via: viaSchema.optional(),
+  }),
+  z.strictObject({ operator: z.literal(true), ...commonScope }),
+])
+
+export function tokenResource(scope: TokenScope): {
+  kind: 'build' | 'repo' | 'session' | 'admin' | 'operator' | 'deployment'
+  id: string
+} {
+  if ('operator' in scope) {
+    return scope.operator === true
+      ? { kind: 'deployment', id: '*' }
+      : { kind: 'operator', id: scope.operator.user }
+  }
+  if ('build' in scope) {
+    return scope.build === '*' ? { kind: 'admin', id: '*' } : { kind: 'build', id: scope.build }
+  }
+  return scope.resource
+}
+
+function sign(secret: string, payload: string): Buffer {
+  return createHmac('sha256', secret).update(payload).digest()
+}
+
+export function mintToken(secret: string, scope: TokenScope): string {
+  const payload = Buffer.from(JSON.stringify(scope), 'utf8').toString('base64url')
+  return `${payload}.${sign(secret, payload).toString('base64url')}`
+}
+
+/**
+ * Bad signature, malformed token, unparseable scope, or expired → null —
+ * verification never explains itself to the caller (the server maps null to
+ * 401). The signature compare is timing-safe via `crypto.timingSafeEqual`.
+ */
+export function verifyToken(secret: string, token: string, now: Date): TokenScope | null {
+  const parts = token.split('.')
+  if (parts.length !== 2) return null
+  const [payload, signature] = parts as [string, string]
+  const expected = sign(secret, payload)
+  let provided: Buffer
+  try {
+    provided = Buffer.from(signature, 'base64url')
+  } catch {
+    return null
+  }
+  if (provided.length !== expected.length || !timingSafeEqual(provided, expected)) {
+    return null
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))
+  } catch {
+    return null
+  }
+  const scope = tokenScopeSchema.safeParse(raw)
+  if (!scope.success) return null
+  if (scope.data.exp <= now.getTime()) return null
+  return scope.data
+}

package/packages/core/src/store/remote/version.ts

@@ -0,0 +1,10 @@
+import manifest from '../../../../../package.json'
+
+/** Release-synchronized identity sent by every remote-store client. */
+export const AUTOBUILD_VERSION = manifest.version
+
+/** Wire compatibility version for the remote BuildStore protocol. */
+export const REMOTE_STORE_PROTOCOL_VERSION = '2'
+
+export const AUTOBUILD_VERSION_HEADER = 'x-autobuild-version'
+export const REMOTE_STORE_PROTOCOL_VERSION_HEADER = 'x-autobuild-protocol-version'

package/packages/core/src/store/retention.ts

@@ -0,0 +1,91 @@
+/**
+ * Artifact retention policy for the dispatcher run/config artifact family.
+ *
+ * Every dispatcher run start and config reload deposits a
+ * `dispatcher-effective-config` (and on reload a `dispatcher-config`)
+ * repository artifact; each build launch deposits a
+ * `build-runner-effective-config` build artifact. Without a bound these rows
+ * grow without limit (~1440/day/repo for a per-minute hosted dispatcher cron).
+ *
+ * The store contract (`store/types.ts`) has no delete, and the remote-store
+ * protocol deliberately exposes no deletion endpoint — the artifact-store
+ * schema and transport are out of bounds for retention. The policy is
+ * therefore enforced **inside each store adapter at the deposit path**: when a
+ * new revision of a retention-managed kind is deposited, the adapter keeps the
+ * latest `maxRevisions` revisions of that `(scope, kind)` and deletes the
+ * older ones in the same transaction, under the same serialization as the
+ * deposit itself.
+ *
+ * The rule is count-based, not age-based: revision sequences already order by
+ * deposit recency, so recency is preserved without a clock in the decision,
+ * the boundary is deterministic, and an age rule would still only ever fire on
+ * a deposit (there is no sweeper). Events and journal entries are never
+ * pruned — historical payloads may reference a revision that no longer
+ * resolves; the current run's snapshot is always among the newest deposits.
+ */
+
+/**
+ * Operator notes artifact kind (`operator/registry.ts`). The agent-facing
+ * notes tools read and write this repository artifact kind; it is
+ * retention-managed so an operator agent that revises its notes on every
+ * round cannot grow the repository artifact table without limit. The bound
+ * is the store's configured `maxRevisions` — the same deposit-time prune
+ * the dispatcher config family uses — whose default is
+ * `DEFAULT_ARTIFACT_RETENTION_MAX_REVISIONS` (the newest 200 revisions
+ * survive). Defined here rather than in the registry module for the same
+ * reason the dispatcher kinds are: store adapters must not import from the
+ * operator surface (store → operator would be an import cycle).
+ */
+export const OPERATOR_NOTES_REPO_KIND = 'operator-notes'
+
+/**
+ * Repository-scoped artifact kinds subject to retention. Values mirror the
+ * kind constants in `cli/dispatch.ts` (DISPATCHER_EFFECTIVE_CONFIG_ARTIFACT)
+ * and `config/live.ts` (DISPATCHER_CONFIG_ARTIFACT); they are restated as
+ * literals here because the store adapters must not import from the CLI
+ * (store → cli would be an import cycle).
+ */
+export const DISPATCHER_RETENTION_REPO_KINDS = [
+  'dispatcher-effective-config',
+  'dispatcher-config',
+] as const
+
+/** Repository-scoped kinds retained for the operator surface (see above). */
+export const OPERATOR_RETENTION_REPO_KINDS = [OPERATOR_NOTES_REPO_KIND] as const
+
+/**
+ * Build-scoped artifact kinds subject to retention. Value mirrors
+ * `BUILD_EFFECTIVE_CONFIG_ARTIFACT` in `processes/build-execution-state.ts`.
+ */
+export const DISPATCHER_RETENTION_BUILD_KINDS = ['build-runner-effective-config'] as const
+
+/** Default bound: the newest 200 revisions of each retention-managed kind survive. */
+export const DEFAULT_ARTIFACT_RETENTION_MAX_REVISIONS = 200
+
+/** True when deposits of `kind` are retention-managed (pruned past the bound). */
+export function isRetentionManagedKind(kind: string): boolean {
+  return (
+    (DISPATCHER_RETENTION_REPO_KINDS as readonly string[]).includes(kind) ||
+    (OPERATOR_RETENTION_REPO_KINDS as readonly string[]).includes(kind) ||
+    (DISPATCHER_RETENTION_BUILD_KINDS as readonly string[]).includes(kind)
+  )
+}
+
+/**
+ * The pure pruning decision every adapter (and every test) shares: given the
+ * revision numbers that currently exist for one `(scope, kind)`, return the
+ * ones beyond the newest `maxRevisions` — exactly the revisions to delete.
+ * Pure and side-effect-free; returns [] when nothing is past the bound.
+ */
+export function revisionsToPrune(revisions: readonly number[], maxRevisions: number): number[] {
+  if (!Number.isInteger(maxRevisions) || maxRevisions < 1) {
+    throw new Error(`maxRevisions must be a positive integer, got ${maxRevisions}`)
+  }
+  for (const revision of revisions) {
+    if (!Number.isInteger(revision) || revision < 0) {
+      throw new Error(`revisions must be nonnegative integers, got ${revision}`)
+    }
+  }
+  const newestFirst = [...revisions].sort((a, b) => b - a)
+  return newestFirst.slice(maxRevisions).sort((a, b) => a - b)
+}

package/packages/core/src/store/session-handle.ts

@@ -0,0 +1,265 @@
+import type { EventType } from '../events/payloads'
+import type { EventWrite } from '../events/catalog'
+import type { RepositoryEventType, RepositoryEventWrite } from '../events/repository'
+import type { AbEvent, EventEnvelope } from '../events/catalog'
+import type { RepositoryEvent, RepositoryEventEnvelope } from '../events/repository'
+import type {
+  SessionEvent,
+  SessionEventEnvelope,
+  SessionEventType,
+  SessionEventWrite,
+} from '../events/sessions'
+import type {
+  Artifact,
+  ArtifactInput,
+  ArtifactMeta,
+  BuildRecord,
+  BuildStore,
+  NewBuildInput,
+  RepositoryArtifact,
+  RepositoryArtifactMeta,
+  RepositoryRecord,
+  SessionArtifact,
+  SessionArtifactMeta,
+  SessionRecord,
+  SessionScopedStore,
+  SubscribeOptions,
+  Unsubscribe,
+} from './types'
+import type {
+  StreamChunk,
+  StreamOutcome,
+  StreamPart,
+  StreamRead,
+  StreamRecord,
+  StreamScope,
+} from './streams/types'
+
+/** Interface-level authority failure for a session-scoped handle — the
+ * session counterpart of `BuildScopeError`. */
+export class SessionScopeError extends Error {
+  constructor(
+    readonly scope: string,
+    readonly operation: string,
+    readonly target?: string,
+  ) {
+    super(
+      target === undefined
+        ? `session-scoped store for ${JSON.stringify(scope)} forbids ${operation}`
+        : `session-scoped store for ${JSON.stringify(scope)} forbids ${operation} targeting ${JSON.stringify(target)}`,
+    )
+    this.name = 'SessionScopeError'
+  }
+}
+
+/** Wrap a full store with one-session authority. The wrapper keeps the
+ * complete BuildStore shape so accidental session create/list, collection,
+ * build, or repository calls fail loudly instead of disappearing behind a
+ * type assertion. A session-scoped handle may touch only its own session's
+ * record, events, artifacts, and session-scoped streams. */
+export function createSessionScopedStore(store: BuildStore, scope: string): SessionScopedStore {
+  const own = (operation: string, id: string): void => {
+    if (id !== scope) throw new SessionScopeError(scope, operation, id)
+  }
+  const ownStreamScope = (record: StreamRecord): void => {
+    if (record.scope.kind !== 'session' || record.scope.session !== scope) {
+      throw new SessionScopeError(scope, 'stream', record.id)
+    }
+  }
+  const ownStream = async (streamId: string): Promise<void> => {
+    const record = await store.getStream(streamId)
+    if (record) ownStreamScope(record)
+  }
+  const sessionScope = (operation: string, candidate: StreamScope): void => {
+    if (candidate.kind !== 'session' || candidate.session !== scope) {
+      throw new SessionScopeError(scope, operation, JSON.stringify(candidate))
+    }
+  }
+  return {
+    sessionScope: scope,
+    scopeSession(id: string): SessionScopedStore {
+      own('scopeSession', id)
+      return this
+    },
+    scopeBuild(_slug: string): never {
+      throw new SessionScopeError(scope, 'scopeBuild')
+    },
+    createBuild(_input: NewBuildInput): Promise<BuildRecord> {
+      return Promise.reject(new SessionScopeError(scope, 'createBuild'))
+    },
+    getBuild(slug: string): Promise<BuildRecord | null> {
+      return Promise.reject(new SessionScopeError(scope, 'getBuild', slug))
+    },
+    listBuilds(): Promise<BuildRecord[]> {
+      return Promise.reject(new SessionScopeError(scope, 'listBuilds'))
+    },
+    append<T extends EventType>(slug: string, _event: EventWrite<T>): Promise<EventEnvelope<T>> {
+      return Promise.reject(new SessionScopeError(scope, 'append', slug))
+    },
+    appendIfCurrent<T extends EventType>(
+      slug: string,
+      _expectedSeq: number,
+      _event: EventWrite<T>,
+    ): Promise<EventEnvelope<T> | null> {
+      return Promise.reject(new SessionScopeError(scope, 'appendIfCurrent', slug))
+    },
+    appendWithArtifacts<T extends EventType>(
+      slug: string,
+      _artifacts: ArtifactInput[],
+      _makeEvent: (deposited: ArtifactMeta[]) => EventWrite<T>,
+    ): Promise<{ event: EventEnvelope<T>; artifacts: ArtifactMeta[] }> {
+      return Promise.reject(new SessionScopeError(scope, 'appendWithArtifacts', slug))
+    },
+    getEvents(slug: string, _sinceSeq?: number): Promise<AbEvent[]> {
+      return Promise.reject(new SessionScopeError(scope, 'getEvents', slug))
+    },
+    putArtifact(slug: string, _artifact: ArtifactInput): Promise<ArtifactMeta> {
+      return Promise.reject(new SessionScopeError(scope, 'putArtifact', slug))
+    },
+    getArtifact(slug: string, _kind: string, _rev?: number): Promise<Artifact | null> {
+      return Promise.reject(new SessionScopeError(scope, 'getArtifact', slug))
+    },
+    listArtifacts(slug: string, _kind?: string): Promise<ArtifactMeta[]> {
+      return Promise.reject(new SessionScopeError(scope, 'listArtifacts', slug))
+    },
+    claimLease(slug: string, _holder: string, _ttlMs: number): Promise<boolean> {
+      return Promise.reject(new SessionScopeError(scope, 'claimLease', slug))
+    },
+    heartbeat(slug: string, _holder: string): Promise<boolean> {
+      return Promise.reject(new SessionScopeError(scope, 'heartbeat', slug))
+    },
+    releaseLease(slug: string, _holder: string): Promise<void> {
+      return Promise.reject(new SessionScopeError(scope, 'releaseLease', slug))
+    },
+    subscribe(
+      slug: string,
+      _opts: SubscribeOptions,
+      _onEvent: (event: AbEvent) => void,
+    ): Unsubscribe {
+      throw new SessionScopeError(scope, 'subscribe', slug)
+    },
+    ensureRepo(repo: string): Promise<RepositoryRecord> {
+      return Promise.reject(new SessionScopeError(scope, 'ensureRepo', repo))
+    },
+    getRepo(repo: string): Promise<RepositoryRecord | null> {
+      return Promise.reject(new SessionScopeError(scope, 'getRepo', repo))
+    },
+    appendRepo<T extends RepositoryEventType>(
+      repo: string,
+      _event: RepositoryEventWrite<T>,
+    ): Promise<RepositoryEventEnvelope<T>> {
+      return Promise.reject(new SessionScopeError(scope, 'appendRepo', repo))
+    },
+    appendRepoWithArtifacts<T extends RepositoryEventType>(
+      repo: string,
+      _artifacts: ArtifactInput[],
+      _makeEvent: (deposited: RepositoryArtifactMeta[]) => RepositoryEventWrite<T>,
+    ): Promise<{ event: RepositoryEventEnvelope<T>; artifacts: RepositoryArtifactMeta[] }> {
+      return Promise.reject(new SessionScopeError(scope, 'appendRepoWithArtifacts', repo))
+    },
+    getRepoEvents(repo: string, _sinceSeq?: number): Promise<RepositoryEvent[]> {
+      return Promise.reject(new SessionScopeError(scope, 'getRepoEvents', repo))
+    },
+    putRepoArtifact(repo: string, _artifact: ArtifactInput): Promise<RepositoryArtifactMeta> {
+      return Promise.reject(new SessionScopeError(scope, 'putRepoArtifact', repo))
+    },
+    getRepoArtifact(
+      repo: string,
+      _kind: string,
+      _rev?: number,
+    ): Promise<RepositoryArtifact | null> {
+      return Promise.reject(new SessionScopeError(scope, 'getRepoArtifact', repo))
+    },
+    listRepoArtifacts(repo: string, _kind?: string): Promise<RepositoryArtifactMeta[]> {
+      return Promise.reject(new SessionScopeError(scope, 'listRepoArtifacts', repo))
+    },
+    claimRepoLease(repo: string, _holder: string, _ttlMs: number): Promise<boolean> {
+      return Promise.reject(new SessionScopeError(scope, 'claimRepoLease', repo))
+    },
+    heartbeatRepo(repo: string, _holder: string): Promise<boolean> {
+      return Promise.reject(new SessionScopeError(scope, 'heartbeatRepo', repo))
+    },
+    releaseRepoLease(repo: string, _holder: string): Promise<void> {
+      return Promise.reject(new SessionScopeError(scope, 'releaseRepoLease', repo))
+    },
+    async createSession(input): Promise<SessionRecord> {
+      throw new SessionScopeError(scope, 'createSession', input.repo)
+    },
+    async getSession(id: string): Promise<SessionRecord | null> {
+      own('getSession', id)
+      return store.getSession(id)
+    },
+    listSessions(repo: string): Promise<SessionRecord[]> {
+      return Promise.reject(new SessionScopeError(scope, 'listSessions', repo))
+    },
+    async appendSessionEvent<T extends SessionEventType>(
+      id: string,
+      event: SessionEventWrite<T>,
+    ): Promise<SessionEventEnvelope<T>> {
+      own('appendSessionEvent', id)
+      return store.appendSessionEvent(id, event)
+    },
+    async getSessionEvents(
+      id: string,
+      sinceSeq?: number,
+      opts?: { waitSeconds?: number; signal?: AbortSignal },
+    ): Promise<SessionEvent[]> {
+      own('getSessionEvents', id)
+      return store.getSessionEvents(id, sinceSeq, opts)
+    },
+    async appendSessionWithArtifacts<T extends SessionEventType>(
+      id: string,
+      artifacts: ArtifactInput[],
+      makeEvent: (deposited: SessionArtifactMeta[]) => SessionEventWrite<T>,
+    ): Promise<{ event: SessionEventEnvelope<T>; artifacts: SessionArtifactMeta[] }> {
+      own('appendSessionWithArtifacts', id)
+      return store.appendSessionWithArtifacts(id, artifacts, makeEvent)
+    },
+    async putSessionArtifact(id: string, artifact: ArtifactInput): Promise<SessionArtifactMeta> {
+      own('putSessionArtifact', id)
+      return store.putSessionArtifact(id, artifact)
+    },
+    async getSessionArtifact(
+      id: string,
+      kind: string,
+      rev?: number,
+    ): Promise<SessionArtifact | null> {
+      own('getSessionArtifact', id)
+      return store.getSessionArtifact(id, kind, rev)
+    },
+    async listSessionArtifacts(id: string, kind?: string): Promise<SessionArtifactMeta[]> {
+      own('listSessionArtifacts', id)
+      return store.listSessionArtifacts(id, kind)
+    },
+    async createStream(candidate: StreamScope, label: string): Promise<StreamRecord> {
+      sessionScope('createStream', candidate)
+      return store.createStream(candidate, label)
+    },
+    async appendStreamParts(streamId: string, parts: StreamPart[]): Promise<StreamChunk> {
+      await ownStream(streamId)
+      return store.appendStreamParts(streamId, parts)
+    },
+    async readStream(
+      streamId: string,
+      opts?: { since?: number; waitSeconds?: number; signal?: AbortSignal },
+    ): Promise<StreamRead> {
+      await ownStream(streamId)
+      return store.readStream(streamId, opts)
+    },
+    async closeStream(streamId: string, outcome: StreamOutcome): Promise<StreamRecord> {
+      await ownStream(streamId)
+      return store.closeStream(streamId, outcome)
+    },
+    async getStream(streamId: string): Promise<StreamRecord | null> {
+      await ownStream(streamId)
+      return store.getStream(streamId)
+    },
+    async listStreams(candidate: StreamScope): Promise<StreamRecord[]> {
+      sessionScope('listStreams', candidate)
+      return store.listStreams(candidate)
+    },
+    close(): Promise<void> {
+      return Promise.reject(new SessionScopeError(scope, 'close'))
+    },
+  }
+}

package/packages/core/src/store/streams/assemble.ts

@@ -0,0 +1,79 @@
+/**
+ * Close-time assembly (SPEC §7.6): the one piece of shared core code every
+ * adapter uses to turn a stream's part sequence into the protocol's
+ * `UIMessage[]` document.
+ *
+ * The SDK's own processor is the protocol: classification reuses
+ * `uiMessageChunkSchema` (the executable definition of "defined part type")
+ * and assembly reuses `readUIMessageStream`. Parts of undefined types — and
+ * malformed defined-type parts — are dropped and counted, never fatal.
+ *
+ * The SDK's stream state machine models exactly one message per stream (a
+ * `start` chunk updates the message id/metadata without resetting accumulated
+ * parts), while a stream here is a whole session. The part sequence is
+ * therefore split into segments at each `start` chunk, and one `UIMessage`
+ * per segment is collected, in order. Verified against ai@7 behavior by
+ * `assemble.test.ts`, which is the tripwire if an SDK upgrade changes it.
+ */
+import { readUIMessageStream, uiMessageChunkSchema } from 'ai'
+import type { UIMessage } from 'ai'
+import type { StreamPart } from './types'
+
+const chunkSchema = uiMessageChunkSchema() as unknown as {
+  validate: (value: unknown) => Promise<{ success: boolean }>
+}
+
+/** Classify one part against the protocol's defined chunk union. */
+async function isDefinedPart(part: StreamPart): Promise<boolean> {
+  return (await chunkSchema.validate(part)).success
+}
+
+/**
+ * Assemble the ordered part sequence of a whole stream into the document.
+ * Returns the `UIMessage[]` (empty when nothing assembled, e.g. zero chunks)
+ * and the count of dropped parts (undefined types and malformed defined-type
+ * parts). Per-chunk protocol errors surface through the SDK's `onError` and
+ * are swallowed — an `error` chunk is content, not an assembly failure.
+ */
+export async function assembleUIMessageDocument(
+  parts: StreamPart[],
+): Promise<{ document: UIMessage[]; droppedPartCount: number }> {
+  const defined: StreamPart[] = []
+  let droppedPartCount = 0
+  for (const part of parts) {
+    if (await isDefinedPart(part)) {
+      defined.push(part)
+    } else {
+      droppedPartCount++
+    }
+  }
+
+  // Split into segments at each `start` chunk (a segment begins with its
+  // `start`); parts before the first `start` form a leading segment.
+  const segments: StreamPart[][] = []
+  let current: StreamPart[] = []
+  for (const part of defined) {
+    if (part.type === 'start' && current.length > 0) {
+      segments.push(current)
+      current = []
+    }
+    current.push(part)
+  }
+  if (current.length > 0) segments.push(current)
+
+  const document: UIMessage[] = []
+  for (const segment of segments) {
+    const stream = new ReadableStream<StreamPart>({
+      start(controller) {
+        for (const part of segment) controller.enqueue(part)
+        controller.close()
+      },
+    })
+    let last: UIMessage | undefined
+    for await (const message of readUIMessageStream({ stream: stream as never })) {
+      last = message
+    }
+    if (last) document.push(last)
+  }
+  return { document, droppedPartCount }
+}

package/packages/core/src/store/streams/lock.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-stream, in-process async mutex (AUT-348): a promise-chain per key that
+ * serializes a store's close against its appends inside one process, so an
+ * append issued while a close is in flight either lands before the close's
+ * prepare snapshot or blocks until the close commits and then fails the
+ * closed re-check with an explicit error — never a silently omitted chunk.
+ *
+ * This is coordination *within one process only*. Cross-process and
+ * cross-connection writers are invisible to it; serializing those remains the
+ * store adapter's transaction discipline (BEGIN IMMEDIATE re-verification in
+ * SQLite, the `FOR UPDATE` row lock in Postgres).
+ */
+export class StreamLocks {
+  /** Queue tail per key: settles only when the current holder finishes. */
+  private readonly tails = new Map<string, Promise<unknown>>()
+
+  /** Run `fn` while holding the lock for `key`. Holders run in FIFO launch
+   * order; a holder that throws releases the key and propagates its error to
+   * its own caller without rejecting (poisoning) later holders. */
+  run<T>(key: string, fn: () => T | Promise<T>): Promise<T> {
+    const tail = this.tails.get(key) ?? Promise.resolve()
+    // A failed holder must release the key, so the wait chain never rejects.
+    const turn = tail.then(
+      () => undefined,
+      () => undefined,
+    )
+    const run = turn.then(fn)
+    // Keep the chain alive regardless of this holder's fate, and drop the
+    // entry once this holder is the last one (the tail) so idle keys do not
+    // accumulate. A caller that already chained onto `tail` re-sets the entry
+    // with its own, which makes the equality check a no-op for it.
+    const released = run.then(
+      () => undefined,
+      () => undefined,
+    )
+    this.tails.set(key, released)
+    released.then(() => {
+      if (this.tails.get(key) === released) this.tails.delete(key)
+    })
+    return run
+  }
+}