Storage

The Storage port: an atomic persistence boundary for Session records. It is the only source of durability; every backend (memory, SQL, files) implements this one service and is selected by layer.

Storage trusts its single owning Session to supply semantically valid records and transitions. A backend enforces atomicity, the global ID namespace, immutability of conversations and entries, document record consistency, and detached values (callers never share mutable state with storage).

Since v0.0.0

---

utils

Storage (class)

The storage service. Its layer owns the backend’s lifetime: closing the layer’s scope releases the backend.

Signature

declare class Storage

Source

Since v0.0.0

StorageShape (interface)

Signature

export interface StorageShape {
  /**
   * Atomically persist one batch and return its sequence; later reads observe it. `StorageRejected` guarantees that
   * nothing was applied. Any other failure leaves the outcome uncertain.
   */
  readonly commit: (writes: ReadonlyArray<StorageWrite>) => Effect.Effect<Seq, StorageRejected | StorageFailure>
  /** A fresh candidate from the global ID namespace. Only committed IDs are protected from reuse. */
  readonly mintId: Effect.Effect<number, StorageFailure>

  readonly conversation: (id: ConversationId) => Effect.Effect<Option.Option<ConversationRecord>, StorageFailure>
  /** Ascending by ID. */
  readonly scanConversations: (
    query: ConversationQuery,
    limit: number,
    cursor?: Cursor
  ) => Effect.Effect<Page<ConversationRecord>, StorageFailure>

  /** One entry by global ID. */
  readonly entry: (id: EntryId) => Effect.Effect<Option.Option<StoredEntry>, StorageFailure>
  /** One entry, only when it is visible through the conversation's fork ancestry. */
  readonly visibleEntry: (
    conversationId: ConversationId,
    id: EntryId
  ) => Effect.Effect<Option.Option<StoredEntry>, StorageFailure>
  /** The newest visible entry that carries a `head`, at or below the optional inclusive cutoff. */
  readonly findLatestHeadMarker: (
    conversationId: ConversationId,
    atOrBefore?: EntryId
  ) => Effect.Effect<Option.Option<EntryRecord & { readonly head: EntryId }>, StorageFailure>
  /** The inclusive visible range, newest-first. */
  readonly scanEntries: (
    query: EntryQuery,
    limit: number,
    cursor?: Cursor
  ) => Effect.Effect<Page<EntryRecord>, StorageFailure>

  readonly task: (id: TaskId) => Effect.Effect<Option.Option<TaskRecord>, StorageFailure>
  /** Ascending by ID, matching every supplied filter. */
  readonly scanTasks: (
    query: TaskQuery,
    limit: number,
    cursor?: Cursor
  ) => Effect.Effect<Page<TaskRecord>, StorageFailure>

  readonly submission: (id: SubmissionId) => Effect.Effect<Option.Option<SubmissionRecord>, StorageFailure>
  /** Ascending by ID, matching every supplied filter. */
  readonly scanSubmissions: (
    query: SubmissionQuery,
    limit: number,
    cursor?: Cursor
  ) => Effect.Effect<Page<SubmissionRecord>, StorageFailure>
  /** The submission with a conversation-scoped request ID. */
  readonly submissionByRequest: (
    conversationId: ConversationId,
    requestId: string
  ) => Effect.Effect<Option.Option<SubmissionRecord>, StorageFailure>

  /** The incarnation occupying one logical address at a point. */
  readonly findDocument: (
    address: DocumentAddress,
    at: DocumentPoint
  ) => Effect.Effect<Option.Option<DocumentRecord>, StorageFailure>
  /** Materialize one incarnation by ID at a point, without following a replacement at its address. */
  readonly document: (id: DocumentId, at: DocumentPoint) => Effect.Effect<Option.Option<StoredDocument>, StorageFailure>
  /** Ascending by ID: incarnations alive in one exact scope at a point. */
  readonly scanDocuments: (
    query: DocumentQuery,
    limit: number,
    cursor?: Cursor
  ) => Effect.Effect<Page<DocumentRecord>, StorageFailure>
}

Source

Since v0.0.0

StoredEntry (interface)

An entry and the sequence of the commit that persisted it.

Signature

export interface StoredEntry {
  readonly entry: EntryRecord
  readonly commitSeq: Seq
}

Source

Since v0.0.0