Records

Durable records and the atomic write batch exchanged between the Session and a Storage backend. Records are plain JSON values, so every backend can persist them without a codec.

Since v0.0.0

---

utils

ContextEdit (type alias)

An immutable override of one visible entry’s contribution to model context.

Signature

type ContextEdit =
  | { readonly target: EntryId; readonly action: "omit" }
  | { readonly target: EntryId; readonly action: "replace"; readonly messages: ReadonlyArray<Json> }

Source

Since v0.0.0

ConversationOwnership (type alias)

Ownership selected explicitly whenever a conversation is created.

Signature

type ConversationOwnership = { readonly kind: "ownerless" } | { readonly kind: "task"; readonly taskId: TaskId }

Source

Since v0.0.0

ConversationQuery (interface)

Signature

export interface ConversationQuery {
  readonly ownerConversationId?: ConversationId
  readonly ownerTaskId?: TaskId
}

Source

Since v0.0.0

ConversationRecord (interface)

Immutable identity, history ancestry, and task ownership of a transcript.

Signature

export interface ConversationRecord {
  readonly id: ConversationId
  /** Fork source and inclusive parent entry through which history is inherited. */
  readonly parent?: { readonly conversationId: ConversationId; readonly at: EntryId }
  /** Creator edge used for attribution, subtree abort, and subtree idle waits. */
  readonly owner?: { readonly conversationId: ConversationId; readonly taskId: TaskId }
}

Source

Since v0.0.0

Cursor (type alias)

Backend-owned continuation state that callers only round-trip to the same scan.

Signature

type Cursor = { readonly [key: string]: Json }

Source

Since v0.0.0

DocumentAddress (interface)

Exact logical identity of a document.

Signature

export interface DocumentAddress {
  readonly kind: string
  readonly scope: DocumentScope
  readonly key?: string
}

Source

Since v0.0.0

DocumentContent (type alias)

Complete value or patch, stored at the definition version that produced it.

Signature

type DocumentContent =
  | { readonly kind: "base"; readonly version: number; readonly value: JsonObject }
  | { readonly kind: "delta"; readonly version: number; readonly patch: JsonPatch.JsonPatch }

Source

Since v0.0.0

DocumentCreate (type alias)

Fields supplied when storage creates and stamps a new incarnation.

Signature

type DocumentCreate = Omit<DocumentRecord, "createdAt" | "retiredAt">

Source

Since v0.0.0

DocumentForkPolicy (type alias)

What a fork of the owning conversation starts with.

Signature

type DocumentForkPolicy = "initial" | "current" | "asOf"

Source

Since v0.0.0

DocumentHistory (type alias)

How much history a conversation document retains.

Signature

type DocumentHistory = "latest" | "rewindable"

Source

Since v0.0.0

DocumentPoint (type alias)

Current state or one historical commit.

Signature

type DocumentPoint = Seq | "current"

Source

Since v0.0.0

DocumentQuery (interface)

Incarnations alive in one exact scope at one point.

Signature

export interface DocumentQuery {
  readonly scope: DocumentScope
  readonly at: DocumentPoint
  readonly kind?: string
}

Source

Since v0.0.0

DocumentRecord (interface)

Persisted lifecycle record of one create-to-retire document incarnation.

Signature

export interface DocumentRecord {
  /** Unique incarnation ID; never reused when the same logical document is recreated. */
  readonly id: DocumentId
  readonly kind: string
  /** Family member key; absent for singletons. */
  readonly key?: string
  readonly scope: DocumentScope
  /** Conversation documents only. */
  readonly history?: DocumentHistory
  /** Conversation documents only. */
  readonly fork?: DocumentForkPolicy
  /** Commit that created the incarnation, stamped by storage. */
  readonly createdAt: Seq
  /** Commit that retired the incarnation; absent while current. */
  readonly retiredAt?: Seq
}

Source

Since v0.0.0

DocumentScope (type alias)

Signature

type DocumentScope =
  | { readonly kind: "session" }
  | { readonly kind: "conversation"; readonly conversationId: ConversationId }
  | { readonly kind: "task"; readonly taskId: TaskId }

Source

Since v0.0.0

EntryDraft (interface)

Entry content before the Session assigns identity and attribution. head: "self" heads the new entry.

Signature

export interface EntryDraft {
  readonly kind: string
  readonly model?: ReadonlyArray<Json>
  readonly data?: Json
  readonly head?: EntryId | "self"
  readonly edits?: ReadonlyArray<ContextEdit>
}

Source

Since v0.0.0

EntryQuery (interface)

Inclusive ID bounds for a newest-first scan of one conversation’s fork-aware history.

Signature

export interface EntryQuery {
  readonly conversationId: ConversationId
  readonly minEntryId?: EntryId
  readonly maxEntryId?: EntryId
}

Source

Since v0.0.0

EntryRecord (interface)

Immutable transcript record with separate model-facing and application-facing payloads.

Signature

export interface EntryRecord {
  readonly id: EntryId
  readonly conversationId: ConversationId
  /** Application-defined discriminator. */
  readonly kind: string
  /** Messages contributed to model context; absent for display or bookkeeping entries. */
  readonly model?: ReadonlyArray<Json>
  /** Payload consumed by views, extensions, or bookkeeping. */
  readonly data?: Json
  /** First entry of the active context selected by this entry (resets and compactions). */
  readonly head?: EntryId
  /** Context-only overrides of earlier visible entries. */
  readonly edits?: ReadonlyArray<ContextEdit>
  /** Task that appended this entry. */
  readonly byTaskId?: TaskId
}

Source

Since v0.0.0

JoinPolicy (type alias)

Signature

type JoinPolicy = "failFast" | "allSettled"

Source

Since v0.0.0

Json (type alias)

Signature

type Json = Schema.Json

Source

Since v0.0.0

JsonObject (type alias)

Signature

type JsonObject = Schema.JsonObject

Source

Since v0.0.0

Page (interface)

One ordered scan result and its optional continuation.

Signature

export interface Page<A> {
  readonly items: ReadonlyArray<A>
  readonly next?: Cursor
}

Source

Since v0.0.0

StorageWrite (type alias)

One record or document mutation in an atomic storage commit.

Signature

type StorageWrite =
  | { readonly type: "conversation"; readonly value: ConversationRecord }
  | { readonly type: "entry"; readonly value: EntryRecord }
  | { readonly type: "task"; readonly value: TaskRecord }
  | { readonly type: "submission"; readonly value: SubmissionRecord }
  | {
      readonly type: "document.create"
      readonly record: DocumentCreate
      readonly content: Extract<DocumentContent, { readonly kind: "base" }>
    }
  | {
      readonly type: "document.copy"
      readonly record: DocumentCreate
      readonly source: { readonly id: DocumentId; readonly at: DocumentPoint }
    }
  | { readonly type: "document.change"; readonly id: DocumentId; readonly content: DocumentContent }
  | { readonly type: "document.retire"; readonly id: DocumentId }

Source

Since v0.0.0

StoredDocument (interface)

Materialized value and stored definition version at a selected point.

Signature

export interface StoredDocument {
  readonly record: DocumentRecord
  readonly version: number
  readonly value: JsonObject
  /** Deltas replayed after the selected base to materialize `value`. */
  readonly deltasSinceBase: number
}

Source

Since v0.0.0

SubmissionCreate (type alias)

A submission record before storage assigns its ID.

Signature

type SubmissionCreate = SubmissionRecord extends infer R ? (R extends SubmissionRecord ? Omit<R, "id"> : never) : never

Source

Since v0.0.0

SubmissionQuery (interface)

Signature

export interface SubmissionQuery {
  readonly conversationId?: ConversationId
  readonly status?: SubmissionRecord["status"]
}

Source

Since v0.0.0

SubmissionRecord (type alias)

Durable lifecycle of one admitted user input or passive entry write.

Signature

type SubmissionRecord =
  | (SubmissionBase & { readonly type: "input"; readonly status: "queued" })
  | (SubmissionBase & { readonly type: "input"; readonly status: "placed"; readonly entry: EntryId })
  | (SubmissionBase & {
      readonly type: "input"
      readonly status: "done"
      readonly entry: EntryId
      readonly answer: EntryId
    })
  | (SubmissionBase & {
      readonly type: "input"
      readonly status: "unanswered"
      readonly entry?: EntryId
      readonly reason: string
      readonly detail?: Json
    })
  | (SubmissionBase & { readonly type: "write"; readonly status: "queued" })
  | (SubmissionBase & { readonly type: "write"; readonly status: "done"; readonly entry: EntryId })
  | (SubmissionBase & {
      readonly type: "write"
      readonly status: "unanswered"
      readonly reason: string
      readonly detail?: Json
    })

Source

Since v0.0.0

SubmissionSettlement (type alias)

How a placed or queued submission settles.

Signature

type SubmissionSettlement =
  | { readonly status: "done"; readonly answer: EntryId }
  | { readonly status: "unanswered"; readonly reason: string; readonly detail?: Json }

Source

Since v0.0.0

TaskOutcome (type alias)

Durable reason and optional result recorded when a task settles.

Signature

type TaskOutcome =
  | { readonly status: "completed"; readonly result: Json }
  | { readonly status: "failed"; readonly error: TaskOutcomeError; readonly result?: Json }
  | { readonly status: "aborted"; readonly reason?: string; readonly result?: Json }
  | { readonly status: "orphaned"; readonly reason: string }
  | { readonly status: "faulted"; readonly error: TaskOutcomeError }

Source

Since v0.0.0

TaskOutcomeError (interface)

JSON-safe error snapshot persisted instead of a runtime error.

Signature

export interface TaskOutcomeError {
  readonly message: string
  readonly detail?: Json
}

Source

Since v0.0.0

TaskOwnership (type alias)

The owner a task names when it is created: its conversation (top level) or another task (a child).

Signature

type TaskOwnership =
  | { readonly kind: "conversation"; readonly conversationId: ConversationId }
  | { readonly kind: "task"; readonly taskId: TaskId }

Source

Since v0.0.0

TaskQuery (interface)

Signature

export interface TaskQuery {
  readonly conversationId?: ConversationId
  readonly kind?: string
  readonly status?: TaskStatus
  readonly abortRequested?: boolean
  readonly background?: boolean
}

Source

Since v0.0.0

TaskRecord (interface)

Complete replacement record of one durable task state machine.

Signature

export interface TaskRecord {
  readonly id: TaskId
  readonly conversationId: ConversationId
  /** Registered task definition name. */
  readonly kind: string
  /** Definition version used to migrate live input and checkpoints. */
  readonly version: number
  readonly input: Json
  /** Owning task of a child task; absent for a task its conversation owns. Immutable. */
  readonly owner?: TaskId
  /** Excluded from ordinary idle waits, conversation aborts, and cascades. */
  readonly background: boolean
  readonly abortRequested: boolean
  readonly state: TaskState
  /** First-writer-wins values retained while the task is live. */
  readonly memos?: { readonly [name: string]: Json }
}

Source

Since v0.0.0

TaskState (type alias)

Complete durable execution state of a task.

Signature

type TaskState =
  | { readonly status: "pending"; readonly checkpoint: Json }
  | { readonly status: "running"; readonly checkpoint: Json }
  | {
      readonly status: "waiting"
      readonly checkpoint: Json
      readonly on: ReadonlyArray<TaskId>
      readonly policy: JoinPolicy
    }
  | { readonly status: "completing"; readonly outcome: TaskOutcome }
  | { readonly status: "terminal"; readonly outcome: TaskOutcome }

Source

Since v0.0.0

TaskStatus (type alias)

Signature

type TaskStatus = TaskState["status"]

Source

Since v0.0.0

addressKey

Stable string key of a logical document address, for indexes and caches.

Signature

declare const addressKey: (address: DocumentAddress) => string

Source

Since v0.0.0

scopeKey

Stable string key of a document scope, for indexes.

Signature

declare const scopeKey: (scope: DocumentScope) => string

Source

Since v0.0.0