pigeonhole-db 1.1.0

data/sig/pigeonhole.rbs

@@ -0,0 +1,1484 @@
+# The Ruby API's snapshot (ICR 0111): every public class and method of the `pigeonhole-db` gem.
+# test/test_signatures.rb fails if a class's public methods and these declarations differ,
+# and the suite runs under `rbs test`'s runtime checking.
+module Pigeonhole
+  VERSION: String
+  NATIVE_VERSION: String
+
+  # `:none`, `:buffered`, `:group_sync` or `:sync`.
+  type durability = :none | :buffered | :group_sync | :sync
+
+  # A family, table or kind name.
+  type name = String | Symbol
+
+  # A cell value: a String is bytes, an Integer an i64, a Float an f64.
+  type value = String | Integer | Float
+
+  type path = String | ::_ToPath
+
+  # One cell of a row: its family, qualifier and version.
+  type entry = [String, String, Cell]
+
+  # A vector as written, by the family's element type: an Array of Numerics (`:f32`, `:f16`,
+  # `:bf16`), an Array of Integers (`:i8`), or the packed bits as a String (`:bit`).
+  type vector_in = Array[Numeric] | String
+
+  # A vector as read: an Array of Floats (`:f32`, and `:f16`/`:bf16` widened), an Array of
+  # Integers (`:i8`), or the packed bits as a String (`:bit`).
+  type vector_out = Array[Float] | Array[Integer] | String
+
+  # Keys or seeds: an Array of Strings, or another Enumerable of them (a Set).
+  type keys = Array[String] | Enumerable[String]
+
+  def self.open: (path path, ?create: bool, ?shards: Integer?, ?durability: durability?,
+                  ?block_cache: Integer?, ?row_cache: Integer?, ?memtable_budget: Integer?,
+                  ?shm_dir: path?, ?read_only_fallback: bool?, ?change_feed: Integer?,
+                  ?change_feed_off: bool, ?feed_age: Numeric?, ?feed_tables: Array[name]?) -> Database
+               | [T] (path path, ?create: bool, ?shards: Integer?, ?durability: durability?,
+                      ?block_cache: Integer?, ?row_cache: Integer?, ?memtable_budget: Integer?,
+                      ?shm_dir: path?, ?read_only_fallback: bool?, ?change_feed: Integer?,
+                      ?change_feed_off: bool, ?feed_age: Numeric?,
+                      ?feed_tables: Array[name]?) { (Database) -> T } -> T
+
+  def self.open_reader: (path path, ?shm_dir: path?, ?block_cache: Integer?, ?row_cache: Integer?) -> Reader
+                      | [T] (path path, ?shm_dir: path?, ?block_cache: Integer?, ?row_cache: Integer?) { (Reader) -> T } -> T
+
+  # A Pigeonhole error. A code's subclass carries the code's name and number; `SpentError`
+  # (no code) is a mutation, batch or transaction used after it was spent.
+  class Error < StandardError
+    attr_reader code: String?
+    attr_reader code_num: Integer?
+
+    def initialize: (?String? message, ?String? code, ?Integer? code_num) -> void
+  end
+
+  # A mutation, batch or transaction used after its commit, discard or rollback (no code).
+  class SpentError < Error
+  end
+
+  # A counter's value couldn't be read after its commit applied: the commit succeeded.
+  class ReturnedValueError < Error
+    attr_reader seqno: Integer?
+
+    def initialize: (?String? message, ?String? code, ?Integer? code_num, ?Integer? seqno) -> void
+  end
+
+  class Io < Error
+  end
+
+  class Corruption < Error
+  end
+
+  class WriterLocked < Error
+  end
+
+  class ShmVersionMismatch < Error
+  end
+
+  class ShmUnavailable < Error
+  end
+
+  class UnsupportedFormat < Error
+  end
+
+  class NetworkFilesystem < Error
+  end
+
+  class TableNotFound < Error
+  end
+
+  class TableExists < Error
+  end
+
+  class FamilyNotFound < Error
+  end
+
+  class FamilyExists < Error
+  end
+
+  class UnknownMergeOperator < Error
+  end
+
+  class MergeFailed < Error
+  end
+
+  class Conflict < Error
+  end
+
+  class ReadOnly < Error
+  end
+
+  class KeyTooLarge < Error
+  end
+
+  class ValueTooLarge < Error
+  end
+
+  class NoSpace < Error
+  end
+
+  class InvalidArgument < Error
+  end
+
+  class Unsupported < Error
+  end
+
+  class Closed < Error
+  end
+
+  class NoReaderSlot < Error
+  end
+
+  class RecordTooLarge < Error
+  end
+
+  class Busy < Error
+  end
+
+  class SnapshotExpired < Error
+  end
+
+  class WouldDeadlock < Error
+  end
+
+  class BatchTooLarge < Error
+  end
+
+  class OutcomeUnknown < Error
+  end
+
+  class NoWriter < Error
+  end
+
+  class UnsupportedFeature < Error
+  end
+
+  class FeedExpired < Error
+  end
+
+  # The open database, as the writer process.
+  class Database
+    def table: (name name) -> TableBuilder
+    def tables: () -> Array[String]
+    def drop_table: (name name) -> nil
+    def snapshot: (?durable: bool) -> Snapshot
+                | [T] (?durable: bool) { (Snapshot) -> T } -> T
+    def write_batch: () -> WriteBatch
+                   | [T] () { (WriteBatch) -> T } -> T
+    def transaction: () -> Transaction
+                   | [T] () { (Transaction) -> T } -> T
+    def transact: [T] (?max_attempts: Integer?, ?deadline: Numeric?, ?durability: durability?) { (Transaction) -> T } -> T
+    def flush: () -> nil
+    def compact: () -> nil
+    def close: () -> nil
+    def closed?: () -> bool
+  end
+
+  # A database opened as a reader process.
+  class Reader
+    def table: (name name) -> Table
+    def tables: () -> Array[String]
+    def snapshot: (?durable: bool) -> Snapshot
+                | [T] (?durable: bool) { (Snapshot) -> T } -> T
+    def close: () -> nil
+    def closed?: () -> bool
+  end
+
+  class TableBuilder
+    def family: (name name, ?Family? options) -> self
+    def create: () -> Table
+    def create_if_missing: () -> Table
+    def open: () -> Table
+  end
+
+  class Table
+    def name: () -> String
+    def families: () -> Array[String]
+    def family_info: (name family) -> FamilyInfo?
+    def get: (String row, name family, String qualifier, ?snapshot: Snapshot?) -> Cell?
+    def row: (String row, ?families: Array[name]?, ?qualifier_prefix: String?, ?versions: Integer,
+              ?column_limit: Integer?, ?snapshot: Snapshot?) -> Row?
+    def scan: (?String? prefix, ?start: String?, ?end: String?, ?families: Array[name]?,
+               ?qualifier_prefix: String?, ?versions: Integer, ?limit: Integer?,
+               ?column_limit: Integer?, ?snapshot: Snapshot?, ?chunk: Integer) -> Enumerator[Row, void]
+    def mutate: (String row) -> Mutation
+    def put: (String row, name family, String qualifier, value value, ?ts: Integer?,
+              ?durability: durability?) -> Integer
+    def incr: (String row, name family, String qualifier, Integer delta, ?ts: Integer?,
+               ?durability: durability?) -> Integer
+    def incr_returning: (String row, name family, String qualifier, Integer delta, ?ts: Integer?,
+                         ?durability: durability?) -> Integer?
+    def delete: (String row, ?name? family, ?String? qualifier, ?ts: Integer?,
+                 ?durability: durability?) -> Integer
+    def multi_get: (keys keys, ?families: Array[name]?, ?qualifier_prefix: String?, ?versions: Integer,
+                    ?column_limit: Integer?, ?snapshot: Snapshot?) -> Array[Row?]
+    def multi_get_within: (keys keys, bytes: Integer, ?families: Array[name]?, ?qualifier_prefix: String?,
+                           ?versions: Integer, ?column_limit: Integer?, ?snapshot: Snapshot?,
+                           ?after: KeysPosition?) -> KeysPage
+    def scan_within: (?String? prefix, bytes: Integer, ?start: String?, ?end: String?,
+                      ?families: Array[name]?, ?qualifier_prefix: String?, ?versions: Integer,
+                      ?limit: Integer?, ?column_limit: Integer?, ?snapshot: Snapshot?,
+                      ?after: ScanPosition?) -> ScanPage
+    def traverse: (keys seeds, name family, ?hops: Integer, ?per_node_limit: Integer?, ?hop_limit: Integer?,
+                   ?max_nodes: Integer?, ?byte_budget: Integer?, ?parents: bool, ?qualifier_prefix: String?,
+                   ?snapshot: Snapshot?, ?parallel: Integer?) -> Traversal
+    def pages: (String row, Integer size, ?families: Array[name]?, ?qualifier_prefix: String?,
+                ?versions: Integer, ?snapshot: Snapshot?, ?after: RowPosition?) -> Pages
+    def nearest: (name family, vector_in query, Integer k, ?prefix: String?, ?start: String?, ?end: String?,
+                  ?keys: keys?, ?qualifier_prefix: String?, ?snapshot: Snapshot?,
+                  ?parallel: Integer?) -> Array[Neighbour]
+    def nearest_within: (name family, vector_in query, Integer k, bytes: Integer, ?prefix: String?,
+                         ?start: String?, ?end: String?, ?keys: keys?, ?qualifier_prefix: String?,
+                         ?snapshot: Snapshot?, ?parallel: Integer?) -> NearestPage
+    def feed: (?tables: Array[Table]?, ?prefix: String?, ?visible: bool, ?from_snapshot: Snapshot?,
+               ?from_oldest: bool, ?resume: String?) -> Feed
+            | [T] (?tables: Array[Table]?, ?prefix: String?, ?visible: bool, ?from_snapshot: Snapshot?,
+                   ?from_oldest: bool, ?resume: String?) { (Feed) -> T } -> T
+    def inspect: () -> String
+  end
+
+  # Writes to one row, committed atomically.
+  class Mutation
+    def put: (name family, String qualifier, value value, ?ts: Integer?) -> self
+    def put_u64: (name family, String qualifier, Integer value, ?ts: Integer?) -> self
+    def incr: (name family, String qualifier, Integer delta, ?ts: Integer?) -> self
+    def aggregate: (name family, String qualifier, Integer | Float | String value, ?ts: Integer?) -> self
+    def put_vector: (name family, String qualifier, vector_in vector, ?ts: Integer?) -> self
+    def delete: (?name? family, ?String? qualifier, ?ts: Integer?) -> self
+    def durability: (durability durability) -> self
+    def commit: () -> Integer
+    def commit_if: (Condition condition) -> Integer?
+    def commit_returning: () -> Incremented
+  end
+
+  # The counter cells a Mutation#commit_returning wrote, after its commit.
+  class Incremented
+    def seqno: () -> Integer
+    def value: (name family, String qualifier, ?ts: Integer?) -> Integer?
+    def to_h: () -> Hash[[String, String, Integer], Integer?]
+    def size: () -> Integer
+    def inspect: () -> String
+  end
+
+  # Writes to any rows and tables, committed atomically.
+  class WriteBatch
+    def put: (Table table, String row, name family, String qualifier, value value, ?ts: Integer?) -> self
+    def put_u64: (Table table, String row, name family, String qualifier, Integer value, ?ts: Integer?) -> self
+    def incr: (Table table, String row, name family, String qualifier, Integer delta, ?ts: Integer?) -> self
+    def aggregate: (Table table, String row, name family, String qualifier, Integer | Float | String value,
+                    ?ts: Integer?) -> self
+    def put_vector: (Table table, String row, name family, String qualifier, vector_in vector,
+                     ?ts: Integer?) -> self
+    def delete: (Table table, String row, ?name? family, ?String? qualifier, ?ts: Integer?) -> self
+    def commit: (?durability: durability?) -> Integer
+    def size: () -> Integer
+    def length: () -> Integer
+  end
+
+  # An optimistic transaction.
+  class Transaction
+    def put: (Table table, String row, name family, String qualifier, value value, ?ts: Integer?) -> self
+    def put_u64: (Table table, String row, name family, String qualifier, Integer value, ?ts: Integer?) -> self
+    def incr: (Table table, String row, name family, String qualifier, Integer delta, ?ts: Integer?) -> self
+    def aggregate: (Table table, String row, name family, String qualifier, Integer | Float | String value,
+                    ?ts: Integer?) -> self
+    def put_vector: (Table table, String row, name family, String qualifier, vector_in vector,
+                     ?ts: Integer?) -> self
+    def delete: (Table table, String row, ?name? family, ?String? qualifier, ?ts: Integer?) -> self
+    def get: (Table table, String row, name family, String qualifier) -> Cell?
+    def get_row: (Table table, String row, Array[name] families) -> Row?
+    def commit: (?durability: durability?) -> Integer
+    def rollback: () -> nil
+  end
+
+  class Snapshot
+    def seqno: () -> Integer
+    def release: () -> nil
+  end
+
+  # One version of a cell.
+  class Cell
+    def value: () -> String
+    def ts: () -> Integer
+    def typed: () -> (String | Integer | Float | Array[Float] | Array[Integer] | nil)
+    def as_vector: () -> vector_out?
+    def as_int: () -> Integer?
+    def as_u64: () -> Integer?
+    def as_float: () -> Float?
+    def hll_estimate: () -> Integer?
+    def sum_f64: () -> Float?
+    def mean_var: () -> [Integer, Float, Float]?
+    def histogram_counts: () -> Array[Integer]?
+    def quantile: (Numeric q) -> Float?
+    def bloom_contains: (Integer | String element) -> bool?
+    def ==: (untyped other) -> bool
+    def inspect: () -> String
+  end
+
+  # A row's key and cells; Enumerable over `[family, qualifier, cell]`.
+  class Row
+    include Enumerable[entry]
+
+    def key: () -> String
+    def get: (name family, String qualifier) -> Cell?
+    def cells: () -> Array[entry]
+    def size: () -> Integer
+    def length: () -> Integer
+    def each: () { (entry) -> void } -> self
+            | () -> Enumerator[entry, self]
+    def inspect: () -> String
+  end
+
+  # A column family's options.
+  class Family
+    def self.new: (?max_versions: Integer?, ?ttl: Numeric?, ?bloom_bits: Integer?, ?block_size: Integer?,
+                   ?blob_threshold: Integer?, ?compression: name?, ?zstd_level: Integer?) -> Family
+    def self.counter: (?max_versions: Integer?, ?ttl: Numeric?) -> Family
+    def self.vector: (Integer dim, name element, name metric, ?max_versions: Integer?, ?ttl: Numeric?) -> Family
+    def self.aggregate: (name kind, ?bounds: Array[Numeric]?, ?mantissa_bits: Integer?, ?max_buckets: Integer?,
+                         ?bits: Integer?, ?hashes: Integer?, ?max_versions: Integer?, ?ttl: Numeric?) -> Family
+  end
+
+  # A family's stored options.
+  class FamilyInfo
+    def name: () -> String
+    def counter?: () -> bool
+    def aggregation: () -> Symbol?
+    def max_versions: () -> Integer
+    def ttl: () -> Float?
+    def bloom_bits: () -> Integer
+    def blob_threshold: () -> Integer
+    def block_size: () -> Integer
+    def compression: () -> Symbol
+    def zstd_level: () -> Integer?
+    def merge_operator: () -> String?
+    def cache_priority: () -> Symbol
+    def compaction: () -> Symbol
+    def vector: () -> VectorSpec?
+    def family: () -> Family
+    def inspect: () -> String
+  end
+
+  # A vector family's dimension, element type and metric.
+  class VectorSpec
+    def self.new: (Integer dim, name element, name metric) -> VectorSpec
+    def dim: () -> Integer
+    def element: () -> Symbol
+    def metric: () -> Symbol
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+    def inspect: () -> String
+  end
+
+  # Where a walk of a row's pages stopped: stable bytes, naming no row.
+  class RowPosition
+    def self.from_bytes: (String bytes) -> RowPosition
+    def to_bytes: () -> String
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+
+  # Where a `scan_within` page stopped; it names its table.
+  class ScanPosition
+    def self.from_bytes: (String bytes) -> ScanPosition
+    def to_bytes: () -> String
+    def row: () -> String
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+
+  # Where a `multi_get_within` page stopped; it names its table.
+  class KeysPosition
+    def self.from_bytes: (String bytes) -> KeysPosition
+    def to_bytes: () -> String
+    def key: () -> String
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+
+  # A change feed subscription. A cursor, like Pages: every Enumerable method consumes the
+  # commits it reads. A live feed has no end: `to_a`, `map` and `count` wait for ever, and
+  # `each(timeout: s).to_a` drains what's there.
+  class Feed
+    include Enumerable[Commit]
+
+    def next: (?timeout: Numeric?) -> Commit?
+    def try_next: () -> Commit?
+    def each: (?timeout: Numeric?) { (Commit) -> void } -> self
+            | (?timeout: Numeric?) -> Enumerator[Commit, self]
+    def token: () -> String
+    def oldest_retained: () -> Integer?
+    def close: () -> nil
+    def closed?: () -> bool
+  end
+
+  # One whole commit from a change feed.
+  class Commit < Data
+    attr_reader seqno: Integer
+    attr_reader timestamp: Integer
+    attr_reader changes: Array[Change]
+
+    def self.new: (Integer seqno, Integer timestamp, Array[Change] changes) -> instance
+                | (seqno: Integer, timestamp: Integer, changes: Array[Change]) -> instance
+    def self.[]: (Integer seqno, Integer timestamp, Array[Change] changes) -> instance
+               | (seqno: Integer, timestamp: Integer, changes: Array[Change]) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (seqno: Integer, timestamp: Integer, changes: Array[Change]) -> void
+    def size: () -> Integer
+  end
+
+  # One mutation of a commit. A kind a later engine adds arrives as :unknown.
+  class Change < Data
+    type kind = :put | :merge | :delete_cell | :delete_column | :delete_family | :unknown
+    type typed = String | Integer | Float | Array[Float] | Array[Integer] | nil
+
+    attr_reader table: String
+    attr_reader family: String
+    attr_reader kind: kind
+    attr_reader row: String
+    attr_reader qualifier: String
+    attr_reader timestamp: Integer
+    attr_reader value: typed
+
+    def self.new: (String table, String family, kind kind, String row, String qualifier, Integer timestamp,
+                   typed value) -> instance
+                | (table: String, family: String, kind: kind, row: String, qualifier: String, timestamp: Integer,
+                   value: typed) -> instance
+    def self.[]: (String table, String family, kind kind, String row, String qualifier, Integer timestamp,
+                  typed value) -> instance
+               | (table: String, family: String, kind: kind, row: String, qualifier: String, timestamp: Integer,
+                  value: typed) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (table: String, family: String, kind: kind, row: String, qualifier: String,
+                     timestamp: Integer, value: typed) -> void
+  end
+
+  # A wide row's pages, each read when it is asked for. A cursor: every Enumerable method
+  # consumes the pages it reads (`first` then `to_a` loses the first page).
+  class Pages
+    include Enumerable[Row]
+
+    def each: () { (Row) -> void } -> self
+            | () -> Enumerator[Row, self]
+    def position: () -> RowPosition?
+  end
+
+  # One of a nearest-neighbour search's results.
+  class Neighbour < Data
+    attr_reader row: String
+    attr_reader qualifier: String
+    attr_reader distance: Float
+    attr_reader ts: Integer
+
+    def self.new: (String row, String qualifier, Float distance, Integer ts) -> instance
+                | (row: String, qualifier: String, distance: Float, ts: Integer) -> instance
+    def self.[]: (String row, String qualifier, Float distance, Integer ts) -> instance
+               | (row: String, qualifier: String, distance: Float, ts: Integer) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (row: String, qualifier: String, distance: Float, ts: Integer) -> void
+  end
+
+  # A `nearest_within` page.
+  class NearestPage < Data
+    attr_reader neighbours: Array[Neighbour]
+    attr_reader bytes: Integer
+    attr_reader next_bytes: Integer?
+
+    def self.new: (Array[Neighbour] neighbours, Integer bytes, Integer? next_bytes) -> instance
+                | (neighbours: Array[Neighbour], bytes: Integer, next_bytes: Integer?) -> instance
+    def self.[]: (Array[Neighbour] neighbours, Integer bytes, Integer? next_bytes) -> instance
+               | (neighbours: Array[Neighbour], bytes: Integer, next_bytes: Integer?) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (neighbours: Array[Neighbour], bytes: Integer, next_bytes: Integer?) -> void
+    def cut_by_budget: () -> bool
+    def size: () -> Integer
+  end
+
+  # One hop of a traversal.
+  class Hop < Data
+    attr_reader nodes: Array[String]
+    attr_reader parents: Array[Integer]?
+
+    def self.new: (Array[String] nodes, Array[Integer]? parents) -> instance
+                | (nodes: Array[String], parents: Array[Integer]?) -> instance
+    def self.[]: (Array[String] nodes, Array[Integer]? parents) -> instance
+               | (nodes: Array[String], parents: Array[Integer]?) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (nodes: Array[String], parents: Array[Integer]?) -> void
+    def size: () -> Integer
+  end
+
+  # A traversal's result.
+  class Traversal < Data
+    attr_reader seeds: Array[String]
+    attr_reader hops: Array[Hop]
+    attr_reader rows: Integer
+    attr_reader edges: Integer
+    attr_reader hops_cut: Integer
+    attr_reader cut_by_max_nodes: bool
+    attr_reader cut_by_budget: bool
+
+    def self.new: (Array[String] seeds, Array[Hop] hops, Integer rows, Integer edges, Integer hops_cut,
+                   bool cut_by_max_nodes, bool cut_by_budget) -> instance
+                | (seeds: Array[String], hops: Array[Hop], rows: Integer, edges: Integer, hops_cut: Integer,
+                   cut_by_max_nodes: bool, cut_by_budget: bool) -> instance
+    def self.[]: (Array[String] seeds, Array[Hop] hops, Integer rows, Integer edges, Integer hops_cut,
+                  bool cut_by_max_nodes, bool cut_by_budget) -> instance
+               | (seeds: Array[String], hops: Array[Hop], rows: Integer, edges: Integer, hops_cut: Integer,
+                  cut_by_max_nodes: bool, cut_by_budget: bool) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (seeds: Array[String], hops: Array[Hop], rows: Integer, edges: Integer, hops_cut: Integer,
+                     cut_by_max_nodes: bool, cut_by_budget: bool) -> void
+  end
+
+  # A `scan_within` page.
+  class ScanPage < Data
+    attr_reader rows: Array[Row]
+    attr_reader bytes: Integer
+    attr_reader cut_by_budget: bool
+    attr_reader next_bytes: Integer?
+    attr_reader resume: ScanPosition?
+
+    def self.new: (Array[Row] rows, Integer bytes, bool cut_by_budget, Integer? next_bytes,
+                   ScanPosition? resume) -> instance
+                | (rows: Array[Row], bytes: Integer, cut_by_budget: bool, next_bytes: Integer?,
+                   resume: ScanPosition?) -> instance
+    def self.[]: (Array[Row] rows, Integer bytes, bool cut_by_budget, Integer? next_bytes,
+                  ScanPosition? resume) -> instance
+               | (rows: Array[Row], bytes: Integer, cut_by_budget: bool, next_bytes: Integer?,
+                  resume: ScanPosition?) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (rows: Array[Row], bytes: Integer, cut_by_budget: bool, next_bytes: Integer?,
+                     resume: ScanPosition?) -> void
+    def size: () -> Integer
+  end
+
+  # A `multi_get_within` page.
+  class KeysPage < Data
+    attr_reader rows: Array[Row]
+    attr_reader bytes: Integer
+    attr_reader cut_by_budget: bool
+    attr_reader next_bytes: Integer?
+    attr_reader resume: KeysPosition?
+
+    def self.new: (Array[Row] rows, Integer bytes, bool cut_by_budget, Integer? next_bytes,
+                   KeysPosition? resume) -> instance
+                | (rows: Array[Row], bytes: Integer, cut_by_budget: bool, next_bytes: Integer?,
+                   resume: KeysPosition?) -> instance
+    def self.[]: (Array[Row] rows, Integer bytes, bool cut_by_budget, Integer? next_bytes,
+                  KeysPosition? resume) -> instance
+               | (rows: Array[Row], bytes: Integer, cut_by_budget: bool, next_bytes: Integer?,
+                  resume: KeysPosition?) -> instance
+    def self.members: () -> Array[Symbol]
+    def self.inspect: () -> String
+    def initialize: (rows: Array[Row], bytes: Integer, cut_by_budget: bool, next_bytes: Integer?,
+                     resume: KeysPosition?) -> void
+    def size: () -> Integer
+  end
+
+  # A condition a row must meet for `Mutation#commit_if` to apply.
+  class Condition
+    def self.absent: (name family, String qualifier) -> Condition
+    def self.exists: (name family, String qualifier) -> Condition
+    def self.equals: (name family, String qualifier, String value) -> Condition
+  end
+
+  # Agent memory (D311, ICR 0107; #697 PR 3a).
+  module Memory
+    # A memory's kind.
+    type kind = :episodic | :semantic | :procedural | :unknown
+
+    # A memory id, or its text form.
+    type id = MemoryId | String
+
+    # A link to write: `[to, link type, weight]`.
+    type link_spec = [id, Integer, Numeric]
+
+    # The store is pinned to another embedding model than the one named.
+    class ModelMismatch < InvalidArgument
+    end
+
+    # The consolidator block raised, which stopped the pass.
+    class ConsolidateError < MergeFailed
+      attr_reader consolidated: ConsolidatePass?
+
+      def initialize: (?String? message, ?String? code, ?Integer? code_num, ?consolidated: ConsolidatePass?) -> void
+    end
+
+    module LinkType
+      DERIVED_FROM: Integer
+      SUPERSEDES: Integer
+      SIMILAR_TO: Integer
+      FIRST_CUSTOM: Integer
+    end
+
+    # A memory's id.
+    class MemoryId
+      include Comparable
+
+      def self.new: (String text) -> MemoryId
+      def self.from_bytes: (String bytes) -> MemoryId
+      def to_bytes: () -> String
+      def namespace: () -> String
+      def created_us: () -> Integer
+      def to_s: () -> String
+      def inspect: () -> String
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+      def <=>: (untyped other) -> Integer?
+    end
+
+    # The embedding model a store is pinned to.
+    class EmbeddingModel
+      def self.new: (String id, Integer dim, name element) -> EmbeddingModel
+      def id: () -> String
+      def dim: () -> Integer
+      def element: () -> Symbol
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
+    # Recall's signal weights.
+    class Weights
+      FIELDS: Array[Symbol]
+
+      def self.new: (?vector: Numeric?, ?keyword: Numeric?, ?recency: Numeric?, ?importance: Numeric?,
+                     ?uses: Numeric?, ?graph: Numeric?, ?consolidated: Numeric?) -> Weights
+      def to_a: () -> [Float, Float, Float, Float, Float, Float, Float]
+      def to_h: () -> Hash[Symbol, Float]
+      def vector: () -> Float
+      def keyword: () -> Float
+      def recency: () -> Float
+      def importance: () -> Float
+      def uses: () -> Float
+      def graph: () -> Float
+      def consolidated: () -> Float
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
+    # A recall's graph expansion.
+    class Expand
+      MAX_HOPS: Integer
+
+      def self.new: (?Integer hops, ?max: Integer?) -> Expand
+      def hops: () -> Integer
+      def max: () -> Integer
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
+    # A store's forget policy.
+    class ForgetPolicy
+      def self.new: (?min_retention: Numeric?, ?max_age: Hash[name, Numeric]?, ?half_life: Numeric?,
+                     ?use_weight: Numeric?, ?max_per_pass: Integer?, ?interval: Numeric?) -> ForgetPolicy
+      def min_retention: () -> Float?
+      def max_age: () -> Hash[Symbol, Float]
+      def half_life: () -> Float
+      def use_weight: () -> Float
+      def max_per_pass: () -> Integer
+      def interval: () -> Float
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+    end
+
+    # How `consolidate` picks and folds groups.
+    class ConsolidatePolicy
+      def self.new: (?min_age: Numeric?, ?group_similarity: Numeric?, ?min_group: Integer?,
+                     ?max_group: Integer?, ?max_groups: Integer?, ?sources: name?) -> ConsolidatePolicy
+      def min_age: () -> Float
+      def group_similarity: () -> Float
+      def min_group: () -> Integer
+      def max_group: () -> Integer
+      def max_groups: () -> Integer
+      def sources: () -> Symbol
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+    end
+
+    # A store's near-duplicate dedup.
+    class NearDedup
+      def self.new: (Numeric similarity, ?policy: name) -> NearDedup
+      def similarity: () -> Float
+      def policy: () -> Symbol
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+    end
+
+    # A store's IVF index options.
+    class IvfOptions
+      def self.new: (?min_namespace_len: Integer?, ?nprobe: Integer?, ?target_list_len: Integer?) -> IvfOptions
+      def min_namespace_len: () -> Integer
+      def nprobe: () -> Integer?
+      def target_list_len: () -> Integer?
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+    end
+
+    # A memory to write.
+    class Memory
+      def self.new: (String text, ?embedding: Array[Numeric]?, ?kind: name?, ?importance: Numeric?,
+                     ?source: String?, ?session: String?, ?links: Array[link_spec]?, ?pinned: bool) -> Memory
+      def text: () -> String
+      def inspect: () -> String
+    end
+
+    # What `remember` did.
+    class Remembered < Data
+      attr_reader id: MemoryId
+      attr_reader outcome: Symbol
+
+      def self.new: (MemoryId id, Symbol outcome) -> instance
+                  | (id: MemoryId, outcome: Symbol) -> instance
+      def self.[]: (MemoryId id, Symbol outcome) -> instance
+                 | (id: MemoryId, outcome: Symbol) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (id: MemoryId, outcome: Symbol) -> void
+    end
+
+    # What `mark_used` did.
+    class Marked < Data
+      attr_reader marked: Integer
+      attr_reader missing: Array[MemoryId]
+
+      def self.new: (Integer marked, Array[MemoryId] missing) -> instance
+                  | (marked: Integer, missing: Array[MemoryId]) -> instance
+      def self.[]: (Integer marked, Array[MemoryId] missing) -> instance
+                 | (marked: Integer, missing: Array[MemoryId]) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (marked: Integer, missing: Array[MemoryId]) -> void
+    end
+
+    # A link.
+    class Link < Data
+      attr_reader id: MemoryId
+      attr_reader type: Integer
+      attr_reader weight: Float
+
+      def self.new: (MemoryId id, Integer type, Float weight) -> instance
+                  | (id: MemoryId, type: Integer, weight: Float) -> instance
+      def self.[]: (MemoryId id, Integer type, Float weight) -> instance
+                 | (id: MemoryId, type: Integer, weight: Float) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (id: MemoryId, type: Integer, weight: Float) -> void
+    end
+
+    # Where a memory came from.
+    class Source < Data
+      attr_reader name: String
+      attr_reader at_us: Integer
+
+      def self.new: (String name, Integer at_us) -> instance
+                  | (name: String, at_us: Integer) -> instance
+      def self.[]: (String name, Integer at_us) -> instance
+                 | (name: String, at_us: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (name: String, at_us: Integer) -> void
+    end
+
+    # A stored memory, as `get` reads it.
+    class StoredMemory < Data
+      attr_reader id: MemoryId
+      attr_reader text: String
+      attr_reader kind: kind
+      attr_reader importance: Float
+      attr_reader uses: Integer
+      attr_reader last_used_us: Integer?
+      attr_reader session: String?
+      attr_reader pinned: bool
+      attr_reader consolidated: bool
+      attr_reader superseded_by: MemoryId?
+      attr_reader sources: Array[Source]
+      attr_reader links: Array[Link]
+      attr_reader backlinks: Array[Link]
+      attr_reader embedding: Array[Float]?
+      attr_reader summary: bool
+
+      def self.new: (MemoryId id, String text, kind kind, Float importance, Integer uses,
+                     Integer? last_used_us, String? session, bool pinned, bool consolidated,
+                     MemoryId? superseded_by, Array[Source] sources, Array[Link] links,
+                     Array[Link] backlinks, Array[Float]? embedding, bool summary) -> instance
+                  | (id: MemoryId, text: String, kind: kind, importance: Float, uses: Integer,
+                     last_used_us: Integer?, session: String?, pinned: bool, consolidated: bool,
+                     superseded_by: MemoryId?, sources: Array[Source], links: Array[Link],
+                     backlinks: Array[Link], embedding: Array[Float]?, summary: bool) -> instance
+      def self.[]: (MemoryId id, String text, kind kind, Float importance, Integer uses,
+                    Integer? last_used_us, String? session, bool pinned, bool consolidated,
+                    MemoryId? superseded_by, Array[Source] sources, Array[Link] links,
+                    Array[Link] backlinks, Array[Float]? embedding, bool summary) -> instance
+                 | (id: MemoryId, text: String, kind: kind, importance: Float, uses: Integer,
+                    last_used_us: Integer?, session: String?, pinned: bool, consolidated: bool,
+                    superseded_by: MemoryId?, sources: Array[Source], links: Array[Link],
+                    backlinks: Array[Link], embedding: Array[Float]?, summary: bool) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (id: MemoryId, text: String, kind: kind, importance: Float, uses: Integer,
+                       last_used_us: Integer?, session: String?, pinned: bool, consolidated: bool,
+                       superseded_by: MemoryId?, sources: Array[Source], links: Array[Link],
+                       backlinks: Array[Link], embedding: Array[Float]?, summary: bool) -> void
+      def pinned?: () -> bool
+      def consolidated?: () -> bool
+      def summary?: () -> bool
+    end
+
+    # `verify`'s counts.
+    class StoreStats < Data
+      attr_reader memories: Integer
+      attr_reader no_content: Integer
+      attr_reader stale_dedup: Integer
+      attr_reader broken_links: Integer
+      attr_reader missing_embeddings: Integer
+      attr_reader dangling_superseded: Integer
+      attr_reader text_index_inconsistent: bool
+      attr_reader ivf_mismatched: Integer
+      attr_reader ivf_counter_drift: Integer
+
+      def self.new: (Integer memories, Integer no_content, Integer stale_dedup,
+                     Integer broken_links, Integer missing_embeddings, Integer dangling_superseded,
+                     bool text_index_inconsistent, Integer ivf_mismatched, Integer ivf_counter_drift) -> instance
+                  | (memories: Integer, no_content: Integer, stale_dedup: Integer,
+                     broken_links: Integer, missing_embeddings: Integer,
+                     dangling_superseded: Integer, text_index_inconsistent: bool,
+                     ivf_mismatched: Integer, ivf_counter_drift: Integer) -> instance
+      def self.[]: (Integer memories, Integer no_content, Integer stale_dedup,
+                    Integer broken_links, Integer missing_embeddings, Integer dangling_superseded,
+                    bool text_index_inconsistent, Integer ivf_mismatched, Integer ivf_counter_drift) -> instance
+                 | (memories: Integer, no_content: Integer, stale_dedup: Integer,
+                    broken_links: Integer, missing_embeddings: Integer,
+                    dangling_superseded: Integer, text_index_inconsistent: bool,
+                    ivf_mismatched: Integer, ivf_counter_drift: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (memories: Integer, no_content: Integer, stale_dedup: Integer,
+                       broken_links: Integer, missing_embeddings: Integer,
+                       dangling_superseded: Integer, text_index_inconsistent: bool,
+                       ivf_mismatched: Integer, ivf_counter_drift: Integer) -> void
+      def consistent?: () -> bool
+    end
+
+    # One signal of a hit.
+    class Signal < Data
+      attr_reader rank: Integer
+      attr_reader value: Float
+
+      def self.new: (Integer rank, Float value) -> instance
+                  | (rank: Integer, value: Float) -> instance
+      def self.[]: (Integer rank, Float value) -> instance
+                 | (rank: Integer, value: Float) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (rank: Integer, value: Float) -> void
+    end
+
+    # A hit's signals.
+    class Signals < Data
+      attr_reader vector: Signal?
+      attr_reader keyword: Signal?
+      attr_reader recency: Signal?
+      attr_reader importance: Signal?
+      attr_reader uses: Signal?
+      attr_reader graph: Signal?
+
+      def self.new: (Signal? vector, Signal? keyword, Signal? recency, Signal? importance,
+                     Signal? uses, Signal? graph) -> instance
+                  | (vector: Signal?, keyword: Signal?, recency: Signal?, importance: Signal?,
+                     uses: Signal?, graph: Signal?) -> instance
+      def self.[]: (Signal? vector, Signal? keyword, Signal? recency, Signal? importance,
+                    Signal? uses, Signal? graph) -> instance
+                 | (vector: Signal?, keyword: Signal?, recency: Signal?, importance: Signal?,
+                    uses: Signal?, graph: Signal?) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (vector: Signal?, keyword: Signal?, recency: Signal?, importance: Signal?,
+                       uses: Signal?, graph: Signal?) -> void
+    end
+
+    # One recalled memory.
+    class RecallHit < Data
+      attr_reader id: MemoryId
+      attr_reader text: String
+      attr_reader kind: kind
+      attr_reader importance: Float
+      attr_reader created_us: Integer
+      attr_reader superseded_by: MemoryId?
+      attr_reader score: Float
+      attr_reader signals: Signals?
+      attr_reader embedding: Array[Float]?
+
+      def self.new: (MemoryId id, String text, kind kind, Float importance, Integer created_us,
+                     MemoryId? superseded_by, Float score, Signals? signals, Array[Float]? embedding) -> instance
+                  | (id: MemoryId, text: String, kind: kind, importance: Float,
+                     created_us: Integer, superseded_by: MemoryId?, score: Float,
+                     signals: Signals?, embedding: Array[Float]?) -> instance
+      def self.[]: (MemoryId id, String text, kind kind, Float importance, Integer created_us,
+                    MemoryId? superseded_by, Float score, Signals? signals, Array[Float]? embedding) -> instance
+                 | (id: MemoryId, text: String, kind: kind, importance: Float, created_us: Integer,
+                    superseded_by: MemoryId?, score: Float, signals: Signals?,
+                    embedding: Array[Float]?) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (id: MemoryId, text: String, kind: kind, importance: Float,
+                       created_us: Integer, superseded_by: MemoryId?, score: Float,
+                       signals: Signals?, embedding: Array[Float]?) -> void
+    end
+
+    # What a recall did.
+    class RecallStats < Data
+      attr_reader candidates: Integer
+      attr_reader truncated: bool
+      attr_reader expanded: Integer
+      attr_reader expansion_truncated: bool
+      attr_reader ivf_namespaces: Integer
+      attr_reader ivf_fallbacks: Integer
+
+      def self.new: (Integer candidates, bool truncated, Integer expanded,
+                     bool expansion_truncated, Integer ivf_namespaces, Integer ivf_fallbacks) -> instance
+                  | (candidates: Integer, truncated: bool, expanded: Integer,
+                     expansion_truncated: bool, ivf_namespaces: Integer, ivf_fallbacks: Integer) -> instance
+      def self.[]: (Integer candidates, bool truncated, Integer expanded, bool expansion_truncated,
+                    Integer ivf_namespaces, Integer ivf_fallbacks) -> instance
+                 | (candidates: Integer, truncated: bool, expanded: Integer,
+                    expansion_truncated: bool, ivf_namespaces: Integer, ivf_fallbacks: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (candidates: Integer, truncated: bool, expanded: Integer,
+                       expansion_truncated: bool, ivf_namespaces: Integer, ivf_fallbacks: Integer) -> void
+    end
+
+    # A forget pass's counts.
+    class ForgetPass < Data
+      attr_reader examined: Integer
+      attr_reader deleted: Integer
+      attr_reader protected: Integer
+      attr_reader resume: MemoryId?
+
+      def self.new: (Integer examined, Integer deleted, Integer protected, MemoryId? resume) -> instance
+                  | (examined: Integer, deleted: Integer, protected: Integer, resume: MemoryId?) -> instance
+      def self.[]: (Integer examined, Integer deleted, Integer protected, MemoryId? resume) -> instance
+                 | (examined: Integer, deleted: Integer, protected: Integer, resume: MemoryId?) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (examined: Integer, deleted: Integer, protected: Integer, resume: MemoryId?) -> void
+    end
+
+    # A consolidation pass's counts.
+    class ConsolidatePass < Data
+      attr_reader groups: Integer
+      attr_reader committed: Integer
+      attr_reader skipped: Integer
+      attr_reader created: Integer
+      attr_reader merged: Integer
+      attr_reader sources: Integer
+      attr_reader resume: MemoryId?
+
+      def self.new: (Integer groups, Integer committed, Integer skipped, Integer created,
+                     Integer merged, Integer sources, MemoryId? resume) -> instance
+                  | (groups: Integer, committed: Integer, skipped: Integer, created: Integer,
+                     merged: Integer, sources: Integer, resume: MemoryId?) -> instance
+      def self.[]: (Integer groups, Integer committed, Integer skipped, Integer created,
+                    Integer merged, Integer sources, MemoryId? resume) -> instance
+                 | (groups: Integer, committed: Integer, skipped: Integer, created: Integer,
+                    merged: Integer, sources: Integer, resume: MemoryId?) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (groups: Integer, committed: Integer, skipped: Integer, created: Integer,
+                       merged: Integer, sources: Integer, resume: MemoryId?) -> void
+    end
+
+    # One memory event of a commit.
+    class MemoryEvent < Data
+      attr_reader kind: Symbol
+      attr_reader id: MemoryId
+      attr_reader by: MemoryId?
+
+      def self.new: (Symbol kind, MemoryId id, MemoryId? by) -> instance
+                  | (kind: Symbol, id: MemoryId, by: MemoryId?) -> instance
+      def self.[]: (Symbol kind, MemoryId id, MemoryId? by) -> instance
+                 | (kind: Symbol, id: MemoryId, by: MemoryId?) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (kind: Symbol, id: MemoryId, by: MemoryId?) -> void
+    end
+
+    # One commit's memory events.
+    class MemoryCommit < Data
+      attr_reader seqno: Integer
+      attr_reader timestamp_us: Integer
+      attr_reader events: Array[MemoryEvent]
+
+      def self.new: (Integer seqno, Integer timestamp_us, Array[MemoryEvent] events) -> instance
+                  | (seqno: Integer, timestamp_us: Integer, events: Array[MemoryEvent]) -> instance
+      def self.[]: (Integer seqno, Integer timestamp_us, Array[MemoryEvent] events) -> instance
+                 | (seqno: Integer, timestamp_us: Integer, events: Array[MemoryEvent]) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (seqno: Integer, timestamp_us: Integer, events: Array[MemoryEvent]) -> void
+      def size: () -> Integer
+    end
+
+    # One step of a ConsolidateLoop.
+    class LoopStep < Data
+      attr_reader events: Integer
+      attr_reader passes: Array[[String, ConsolidatePass]]
+      attr_reader failed: Array[[String, Exception]]
+      attr_reader stopped: Array[[String, ConsolidatePass]]
+      attr_reader interrupted: bool
+      attr_reader next_due: Integer?
+      attr_reader token: String
+
+      def self.new: (Integer events, Array[[String, ConsolidatePass]] passes,
+                     Array[[String, Exception]] failed, Array[[String, ConsolidatePass]] stopped,
+                     bool interrupted, Integer? next_due, String token) -> instance
+                  | (events: Integer, passes: Array[[String, ConsolidatePass]],
+                     failed: Array[[String, Exception]], stopped: Array[[String, ConsolidatePass]],
+                     interrupted: bool, next_due: Integer?, token: String) -> instance
+      def self.[]: (Integer events, Array[[String, ConsolidatePass]] passes,
+                    Array[[String, Exception]] failed, Array[[String, ConsolidatePass]] stopped,
+                    bool interrupted, Integer? next_due, String token) -> instance
+                 | (events: Integer, passes: Array[[String, ConsolidatePass]],
+                    failed: Array[[String, Exception]], stopped: Array[[String, ConsolidatePass]],
+                    interrupted: bool, next_due: Integer?, token: String) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (events: Integer, passes: Array[[String, ConsolidatePass]],
+                       failed: Array[[String, Exception]],
+                       stopped: Array[[String, ConsolidatePass]], interrupted: bool,
+                       next_due: Integer?, token: String) -> void
+      def interrupted?: () -> bool
+    end
+
+    # Another consolidation loop of the same name took over.
+    class LoopTakenOver < Conflict
+    end
+
+    # The watch method Store and ReadStore share.
+    module Watches
+      def watch: (?(String | Array[String]) namespaces, ?from_snapshot: Snapshot?, ?resume: String?, ?visible: bool) -> Watch
+               | [T] (?(String | Array[String]) namespaces, ?from_snapshot: Snapshot?, ?resume: String?,
+                      ?visible: bool) { (Watch) -> T } -> T
+    end
+
+    # A store's memory events.
+    class Watch
+      include Enumerable[MemoryCommit]
+
+      def next: (?timeout: Numeric?) -> MemoryCommit?
+      def try_next: () -> MemoryCommit?
+      def each: (?timeout: Numeric?) { (MemoryCommit) -> void } -> self
+              | (?timeout: Numeric?) -> Enumerator[MemoryCommit, self]
+      def token: () -> String
+      def oldest_retained: () -> Integer?
+      def close: () -> nil
+      def closed?: () -> bool
+    end
+
+    # Feed-driven consolidation.
+    class ConsolidateLoop
+      def run_once: (?Numeric timeout) -> LoopStep
+      def next_due: () -> Integer?
+      def close: () -> nil
+    end
+
+    # The recall methods Store and ReadStore share.
+    module Recalls
+      def recall: (String | Array[String] namespaces, ?text: String?, ?embedding: Array[Numeric]?, ?k: Integer?,
+                   ?candidates: Integer?, ?byte_budget: Integer?, ?snapshot: Snapshot?, ?now_us: Integer?,
+                   ?half_life: Numeric?, ?fusion: name, ?weights: Weights?, ?include_superseded: bool,
+                   ?session: String?, ?with_signals: bool, ?with_embeddings: bool,
+                   ?expand: Expand?, ?exact: bool, ?nprobe: Integer?) -> Array[RecallHit]
+      def recall_with_stats: (String | Array[String] namespaces, ?text: String?, ?embedding: Array[Numeric]?,
+                              ?k: Integer?, ?candidates: Integer?, ?byte_budget: Integer?, ?snapshot: Snapshot?,
+                              ?now_us: Integer?, ?half_life: Numeric?, ?fusion: name, ?weights: Weights?,
+                              ?include_superseded: bool, ?session: String?, ?with_signals: bool,
+                              ?with_embeddings: bool, ?expand: Expand?, ?exact: bool,
+                              ?nprobe: Integer?) -> [Array[RecallHit], RecallStats]
+      def get: (id id) -> StoredMemory?
+      def verify: () -> StoreStats
+    end
+
+    # A memory store in the writer process.
+    class Store
+      include Recalls
+      include Watches
+
+      def consolidate_loop: (String name, ?policy: ConsolidatePolicy?, ?namespaces: Array[String]?, ?clock_offset: Numeric?) { (Array[StoredMemory]) -> Array[Memory] } -> ConsolidateLoop
+
+      def self.create: (Database db, String name, ?embedding: EmbeddingModel?, ?forget: ForgetPolicy?,
+                        ?episodic_ttl: Numeric?, ?near_dedup: NearDedup?, ?normalization: name?,
+                        ?ivf: IvfOptions?) -> Store
+                     | [T] (Database db, String name, ?embedding: EmbeddingModel?, ?forget: ForgetPolicy?,
+                            ?episodic_ttl: Numeric?, ?near_dedup: NearDedup?, ?normalization: name?,
+                        ?ivf: IvfOptions?) { (Store) -> T } -> T
+      def self.open: (Database db, String name, model: String?) -> Store
+                   | [T] (Database db, String name, model: String?) { (Store) -> T } -> T
+      def self.open_reader: (Reader reader, String name, model: String?) -> ReadStore
+                          | [T] (Reader reader, String name, model: String?) { (ReadStore) -> T } -> T
+      def close: () -> nil
+      def closed?: () -> bool
+      def embedding_model: () -> EmbeddingModel?
+      def normalization: () -> Symbol
+      def ivf: () -> IvfOptions?
+      def remember: (String ns, String text, ?embedding: Array[Numeric]?, ?kind: name?, ?importance: Numeric?,
+                     ?source: String?, ?session: String?, ?links: Array[link_spec]?, ?pinned: bool) -> Remembered
+      def remember_in: (Transaction txn, String ns, String text, ?embedding: Array[Numeric]?, ?kind: name?,
+                        ?importance: Numeric?, ?source: String?, ?session: String?, ?links: Array[link_spec]?,
+                        ?pinned: bool) -> Remembered
+      def delete: (id id) -> bool
+      def delete_in: (Transaction txn, id id) -> bool
+      def link: (id from, id to, Integer link_type, ?Numeric weight) -> nil
+      def supersede: (id old, id new) -> nil
+      def mark_used: (Array[id] ids) -> Marked
+      def forget: (?policy: ForgetPolicy?, ?after: id?, ?now_us: Integer?) -> ForgetPass
+      def forget_in: (Transaction txn, id id, Integer now_us) -> Symbol
+      def forget_policy: () -> ForgetPolicy?
+      def forget_policy=: (ForgetPolicy? policy) -> ForgetPolicy?
+      def near_dedup: () -> NearDedup?
+      def near_dedup=: (NearDedup? near) -> NearDedup?
+      def near_duplicate: (String ns, String text, ?embedding: Array[Numeric]?) -> [MemoryId, Float]?
+      def consolidate: (String ns, ?policy: ConsolidatePolicy?, ?after: id?, ?now_us: Integer?) { (Array[StoredMemory]) -> Array[Memory] } -> ConsolidatePass
+    end
+
+    # A memory store in a reader process.
+    class ReadStore
+      include Recalls
+      include Watches
+
+      def close: () -> nil
+      def closed?: () -> bool
+      def embedding_model: () -> EmbeddingModel?
+      def normalization: () -> Symbol
+      def ivf: () -> IvfOptions?
+    end
+  end
+
+  # Full-text search (D309, ICR 0105; #697 PR 3b).
+  module Text
+    # A query: a Query, or a String in the query syntax.
+    type query = Query | String
+
+    # A search hit.
+    class Hit < Data
+      attr_reader id: String
+      attr_reader score: Float
+      attr_reader text: String?
+      attr_reader matches: Array[Match]
+
+      def self.new: (String id, Float score, String? text, Array[Match] matches) -> instance
+                  | (id: String, score: Float, text: String?, matches: Array[Match]) -> instance
+      def self.[]: (String id, Float score, String? text, Array[Match] matches) -> instance
+                 | (id: String, score: Float, text: String?, matches: Array[Match]) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (id: String, score: Float, text: String?, matches: Array[Match]) -> void
+    end
+
+    # Where a clause matched: a byte range of the hit's text.
+    class Match < Data
+      attr_reader clause: Integer
+      attr_reader occurrence: Integer
+      attr_reader range: Range[Integer]
+
+      def self.new: (Integer clause, Integer occurrence, Range[Integer] range) -> instance
+                  | (clause: Integer, occurrence: Integer, range: Range[Integer]) -> instance
+      def self.[]: (Integer clause, Integer occurrence, Range[Integer] range) -> instance
+                 | (clause: Integer, occurrence: Integer, range: Range[Integer]) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (clause: Integer, occurrence: Integer, range: Range[Integer]) -> void
+    end
+
+    # How a fuzzy clause expanded.
+    class FuzzyStats < Data
+      attr_reader clause: Integer
+      attr_reader term: String
+      attr_reader expansions: Integer
+      attr_reader cut: bool
+
+      def self.new: (Integer clause, String term, Integer expansions, bool cut) -> instance
+                  | (clause: Integer, term: String, expansions: Integer, cut: bool) -> instance
+      def self.[]: (Integer clause, String term, Integer expansions, bool cut) -> instance
+                 | (clause: Integer, term: String, expansions: Integer, cut: bool) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (clause: Integer, term: String, expansions: Integer, cut: bool) -> void
+    end
+
+    # What a search read.
+    class SearchStats < Data
+      attr_reader fuzzy: Array[FuzzyStats]
+      attr_reader stale: Integer
+
+      def self.new: (Array[FuzzyStats] fuzzy, Integer stale) -> instance
+                  | (fuzzy: Array[FuzzyStats], stale: Integer) -> instance
+      def self.[]: (Array[FuzzyStats] fuzzy, Integer stale) -> instance
+                 | (fuzzy: Array[FuzzyStats], stale: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (fuzzy: Array[FuzzyStats], stale: Integer) -> void
+    end
+
+    # An index's options.
+    class IndexOptions < Data
+      attr_reader k1: Float
+      attr_reader b: Float
+      attr_reader positions: bool
+      attr_reader stop_words: bool
+      attr_reader normalization: Symbol
+      attr_reader max_terms: Integer
+      attr_reader max_term_bytes: Integer
+
+      def self.new: (Float k1, Float b, bool positions, bool stop_words, Symbol normalization,
+                     Integer max_terms, Integer max_term_bytes) -> instance
+                  | (k1: Float, b: Float, positions: bool, stop_words: bool, normalization: Symbol,
+                     max_terms: Integer, max_term_bytes: Integer) -> instance
+      def self.[]: (Float k1, Float b, bool positions, bool stop_words, Symbol normalization,
+                    Integer max_terms, Integer max_term_bytes) -> instance
+                 | (k1: Float, b: Float, positions: bool, stop_words: bool, normalization: Symbol,
+                    max_terms: Integer, max_term_bytes: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (k1: Float, b: Float, positions: bool, stop_words: bool,
+                       normalization: Symbol, max_terms: Integer, max_term_bytes: Integer) -> void
+    end
+
+    # The cell an index covers.
+    class Source < Data
+      attr_reader table: String
+      attr_reader family: String
+      attr_reader qualifier: String
+
+      def self.new: (String table, String family, String qualifier) -> instance
+                  | (table: String, family: String, qualifier: String) -> instance
+      def self.[]: (String table, String family, String qualifier) -> instance
+                 | (table: String, family: String, qualifier: String) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (table: String, family: String, qualifier: String) -> void
+    end
+
+    # `verify`'s counts.
+    class IndexStats < Data
+      attr_reader documents: Integer
+      attr_reader terms: Integer
+      attr_reader postings: Integer
+      attr_reader forward_mismatch: Integer
+      attr_reader source_mismatch: Integer
+      attr_reader counter_drift: Integer
+      attr_reader invalid_utf8: Integer
+      attr_reader consistent: bool
+
+      def self.new: (Integer documents, Integer terms, Integer postings, Integer forward_mismatch,
+                     Integer source_mismatch, Integer counter_drift, Integer invalid_utf8,
+                     bool consistent) -> instance
+                  | (documents: Integer, terms: Integer, postings: Integer,
+                     forward_mismatch: Integer, source_mismatch: Integer, counter_drift: Integer,
+                     invalid_utf8: Integer, consistent: bool) -> instance
+      def self.[]: (Integer documents, Integer terms, Integer postings, Integer forward_mismatch,
+                    Integer source_mismatch, Integer counter_drift, Integer invalid_utf8,
+                    bool consistent) -> instance
+                 | (documents: Integer, terms: Integer, postings: Integer,
+                    forward_mismatch: Integer, source_mismatch: Integer, counter_drift: Integer,
+                    invalid_utf8: Integer, consistent: bool) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (documents: Integer, terms: Integer, postings: Integer,
+                       forward_mismatch: Integer, source_mismatch: Integer, counter_drift: Integer,
+                       invalid_utf8: Integer, consistent: bool) -> void
+      def consistent?: () -> bool
+    end
+
+    # What `rebuild` or `repair` did.
+    class RebuildStats < Data
+      attr_reader documents: Integer
+      attr_reader changed: Integer
+      attr_reader invalid_utf8: Integer
+
+      def self.new: (Integer documents, Integer changed, Integer invalid_utf8) -> instance
+                  | (documents: Integer, changed: Integer, invalid_utf8: Integer) -> instance
+      def self.[]: (Integer documents, Integer changed, Integer invalid_utf8) -> instance
+                 | (documents: Integer, changed: Integer, invalid_utf8: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (documents: Integer, changed: Integer, invalid_utf8: Integer) -> void
+    end
+
+    # A full-text query.
+    class Query
+      def self.new: () -> Query
+      def self.parse: (String text) -> Query
+      def term: (String term) -> Query
+      def text: (String text) -> Query
+      def phrase: (Array[String] words, ?slop: Integer) -> Query
+      def fuzzy: (String term, ?(Symbol | Integer) fuzziness) -> Query
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+    end
+
+    # The search methods Index and ReadIndex share.
+    module Searches
+      def search: (query query, Integer k, ?id_prefix: String?, ?snapshot: Snapshot?, ?highlight: bool,
+                   ?prefix_length: Integer?, ?max_expansions: Integer?) -> Array[Hit]
+      def search_with_stats: (query query, Integer k, ?id_prefix: String?, ?snapshot: Snapshot?, ?highlight: bool,
+                              ?prefix_length: Integer?, ?max_expansions: Integer?) -> [Array[Hit], SearchStats]
+      def verify: () -> IndexStats
+      def options: () -> IndexOptions
+      def source: () -> Source
+    end
+
+    # A full-text index in the writer process.
+    class Index
+      include Searches
+
+      def self.create: (Database db, String name, table: Table, family: name, qualifier: String, ?k1: Numeric?,
+                        ?b: Numeric?, ?positions: bool?, ?stop_words: bool?, ?normalization: name?,
+                        ?max_terms: Integer?, ?max_term_bytes: Integer?) -> Index
+      def self.open: (Database db, String name) -> Index
+      def self.open_reader: (Reader reader, String name) -> ReadIndex
+      def put: (String id, String text) -> nil
+      def put_in: (Transaction txn, String id, String text) -> nil
+      def delete: (String id) -> bool
+      def delete_in: (Transaction txn, String id) -> bool
+      def rebuild: () -> RebuildStats
+      def repair: () -> RebuildStats
+    end
+
+    # A full-text index in a reader process.
+    class ReadIndex
+      include Searches
+    end
+  end
+
+  # The vector index (D306, ICR 0100; #697 PR 3b).
+  module Vector
+    # A search hit.
+    class Hit < Data
+      attr_reader id: String
+      attr_reader distance: Float
+
+      def self.new: (String id, Float distance) -> instance
+                  | (id: String, distance: Float) -> instance
+      def self.[]: (String id, Float distance) -> instance
+                 | (id: String, distance: Float) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (id: String, distance: Float) -> void
+    end
+
+    # What a search read.
+    class SearchStats < Data
+      attr_reader lists_probed: Integer
+      attr_reader lists: Integer
+
+      def self.new: (Integer lists_probed, Integer lists) -> instance
+                  | (lists_probed: Integer, lists: Integer) -> instance
+      def self.[]: (Integer lists_probed, Integer lists) -> instance
+                 | (lists_probed: Integer, lists: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (lists_probed: Integer, lists: Integer) -> void
+    end
+
+    # `verify`'s counts.
+    class IndexStats < Data
+      attr_reader vectors: Integer
+      attr_reader list_lens: Array[Integer]
+
+      def self.new: (Integer vectors, Array[Integer] list_lens) -> instance
+                  | (vectors: Integer, list_lens: Array[Integer]) -> instance
+      def self.[]: (Integer vectors, Array[Integer] list_lens) -> instance
+                 | (vectors: Integer, list_lens: Array[Integer]) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (vectors: Integer, list_lens: Array[Integer]) -> void
+    end
+
+    # What a bulk load did.
+    class BulkStats < Data
+      attr_reader vectors: Integer
+      attr_reader lists: Integer
+
+      def self.new: (Integer vectors, Integer lists) -> instance
+                  | (vectors: Integer, lists: Integer) -> instance
+      def self.[]: (Integer vectors, Integer lists) -> instance
+                 | (vectors: Integer, lists: Integer) -> instance
+      def self.members: () -> Array[Symbol]
+      def self.inspect: () -> String
+      def initialize: (vectors: Integer, lists: Integer) -> void
+    end
+
+    # The search methods Index and ReadIndex share.
+    module Searches
+      def search: (vector_in query, Integer k, ?nprobe: Integer?, ?parallel: Integer?, ?snapshot: Snapshot?,
+                   ?id_prefix: String?, ?max_probe: Integer?) -> Array[Hit]
+      def search_with_stats: (vector_in query, Integer k, ?nprobe: Integer?, ?parallel: Integer?,
+                              ?snapshot: Snapshot?, ?id_prefix: String?, ?max_probe: Integer?) -> [Array[Hit], SearchStats]
+    end
+
+    # A vector index in the writer process.
+    class Index
+      include Searches
+
+      def self.create: (Database db, String name, VectorSpec spec, ?nprobe: Integer?, ?target_list_len: Integer?,
+                        ?reassign_neighbours: Integer?, ?rebalance: name?, ?rebalancer: bool) -> (Index | [Index, Rebalancer])
+      def self.open: (Database db, String name, ?rebalancer: bool) -> (Index | [Index, Rebalancer])
+      def self.open_reader: (Reader reader, String name) -> ReadIndex
+      def spec: () -> VectorSpec
+      def rebalance: () -> Symbol
+      def max_list_len: () -> Integer
+      def min_list_len: () -> Integer
+      def insert: (String id, vector_in vector) -> nil
+      def delete: (String id) -> bool
+      def insert_in: (Transaction txn, Placed placed, String id, vector_in vector) -> nil
+      def delete_in: (Transaction txn, Placed placed, String id) -> bool
+      def after_commit: (Placed placed) -> nil
+      def verify: () -> IndexStats
+      def bulk_load: (Enumerable[[String, vector_in]] pairs, expected: Integer, ?batch: Integer) -> BulkStats
+    end
+
+    # A vector index in a reader process.
+    class ReadIndex
+      include Searches
+
+      def spec: () -> VectorSpec
+    end
+
+    # One transaction's writes to one index.
+    class Placed
+      def self.new: () -> Placed
+    end
+
+    # A background-mode index's rebalancing, driven by a Ruby thread.
+    class Rebalancer
+      def run_once: (Numeric budget) -> bool
+      def wait: (Numeric timeout) -> nil
+      def closed?: () -> bool
+    end
+
+    # A bulk load in progress (Index#bulk_load's).
+    class BulkLoad
+      def push: (Array[[String, vector_in]] pairs) -> nil
+    end
+  end
+end