rec

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package rec is the record layer for the records the core rewrites: pi-durable's conversation, task, submission and document records (spec §2, §3.2, §5.1, §6), written in pi-durable main da866ada's shapes and read tolerantly from 1.0.4 and newer stores (CONTRACT section 2.3).

Entries are immutable bytes and belong to package history (history.AppendEntryRecord, history.EntryRow). The records the core rewrites (Conversation, Task, Submission, Document) wrap a jv object (package durable/core/jv): mutators return a shallow copy with the field set in place, so unknown fields survive where Pi's spread keeps them (`{...record, state}`), and a path where Pi builds a fresh object builds a fresh record with a New* constructor. Task records carry main's startedAt/endedAt (StampTimes is src/session/transaction.ts #stampTimes); records written by 1.0.4 lack them.

Every record also exposes the indexed columns pi-durable's SqliteStorage derives from it (kind, status, request ID and document address, with the `JSON.stringify` encoding of indexed text, storage.ts encodeIndexedString), so the store writes Pi's rows from one place.

Owner: dcore-store (encoders, decoders, key orders). Field semantics are spec-owned; dcore-session and dcore-loop call the constructors and mutators and never assemble record JSON themselves.

Index

Constants

This section is empty.

Variables

View Source
var ErrShape = errors.New("rec: record has an unexpected shape")

ErrShape reports a stored record that lacks a field the core indexes. Read-only.

Functions

func IndexedString

func IndexedString(s string) string

IndexedString is storage.ts encodeIndexedString: indexed text columns hold JSON.stringify(value), quotes included, because some SQLite bindings replace lone UTF-16 surrogates.

Types

type Address

type Address struct {
	Kind      string // documents.kind
	ScopeKind string // documents.scope_kind
	OwnerID   int64  // documents.owner_id: 0 for the session
	Family    int64  // documents.family: 1 when the record has a key
	KeyValue  string // documents.key_value
}

Address is the document address columns (storage.ts addressParts): kind and key hold JSON.stringify(value).

func (Address) AddressKey

func (a Address) AddressKey() string

AddressKey identifies the logical address of a record (storage.ts addressKey).

type Conversation

type Conversation struct{ V *jv.Object }

Conversation is a conversation record (spec §2 ConversationRecord): `{id, parent?: {conversationId, at}, owner?: {conversationId, taskId}}`. It is immutable once written.

func ConversationOf

func ConversationOf(o *jv.Object) (*Conversation, error)

ConversationOf reads a conversation record that is already a value: ParseConversation without the text, with the same checks.

func NewConversation

func NewConversation(convID, parentConv, parentAt, ownerConv, ownerTask int64) *Conversation

NewConversation builds the record in Pi's key order (src/session/transaction.ts #stageConversation). parent and owner are absent when their conversation ID is 0.

func ParseConversation

func ParseConversation(b []byte) (*Conversation, error)

ParseConversation reads a stored conversation record.

func (*Conversation) Append

func (c *Conversation) Append(dst []byte) []byte

Append appends the record's JSON.stringify.

func (*Conversation) ID

func (c *Conversation) ID() int64

ID is the conversation ID.

func (*Conversation) OwnerConversation

func (c *Conversation) OwnerConversation() (int64, bool)

OwnerConversation and OwnerTask are the owner_conversation_id and owner_task_id column values (`write.value.owner?.conversationId ?? null`): ok is false where Pi binds NULL.

func (*Conversation) OwnerTask

func (c *Conversation) OwnerTask() (int64, bool)

OwnerTask is the owner_task_id column value; see OwnerConversation.

func (*Conversation) Parent

func (c *Conversation) Parent() (conv, at int64, ok bool)

Parent returns the fork source and the inclusive parent entry; ok is false for a root.

type Document

type Document struct{ V *jv.Object }

Document is a document record (spec §3.2 DocumentRecord): `{id, kind, key?, scope, history?, fork?, createdAt, retiredAt?}`. A DocumentCreate is the same record without createdAt and retiredAt.

func DocumentOf

func DocumentOf(o *jv.Object) (*Document, error)

DocumentOf reads a document record that is already a value: ParseDocument without the text, with the same checks.

func NewDocumentCreate

func NewDocumentCreate(docID int64, kind string, key *string, scope ScopeKind, scopeOwner int64, history, fork string) *Document

NewDocumentCreate builds the DocumentCreate of src/session/transaction.ts documentCreate and forks.ts collectCopies: `{id, kind, key?, scope, history?, fork?}`. key is nil for a singleton; history and fork are empty for session and task scopes. scopeOwner is the conversation or task ID (0 for the session).

func ParseDocument

func ParseDocument(b []byte) (*Document, error)

ParseDocument reads a stored document record.

func (*Document) Address

func (d *Document) Address() Address

Address returns the record's address columns.

func (*Document) AliveAt

func (d *Document) AliveAt(current bool, at int64) bool

AliveAt is storage.ts isAliveAt for a historical point; current is the current-incarnation test.

func (*Document) Append

func (d *Document) Append(dst []byte) []byte

Append appends the record's JSON.stringify.

func (*Document) CreatedAt

func (d *Document) CreatedAt() (int64, bool)

CreatedAt is the commit that created the incarnation; ok is false on a DocumentCreate.

func (*Document) CurrentOnly

func (d *Document) CurrentOnly() bool

CurrentOnly is storage.ts isCurrentOnly: only the current content is retained (no as-of reads).

func (*Document) Fork

func (d *Document) Fork() string

Fork is the fork policy of a conversation-scoped document, "" otherwise.

func (*Document) History

func (d *Document) History() string

History is "latest" or "rewindable" for a conversation-scoped document, "" otherwise.

func (*Document) ID

func (d *Document) ID() int64

ID is the incarnation ID.

func (*Document) Key

func (d *Document) Key() (string, bool)

Key is the family member key; ok is false for a singleton.

func (*Document) Kind

func (d *Document) Kind() string

Kind is the definition kind.

func (*Document) Retired

func (d *Document) Retired(seq int64) *Document

Retired returns `{...record, retiredAt: seq}`.

func (*Document) RetiredAt

func (d *Document) RetiredAt() (int64, bool)

RetiredAt is the commit that retired the incarnation; ok is false while current.

func (*Document) Scope

func (d *Document) Scope() (kind ScopeKind, owner int64)

Scope returns the scope kind and its owner ID (the conversation or task; 0 for the session); kind is 0 when the scope is malformed.

func (*Document) Stamped

func (d *Document) Stamped(seq int64, retire bool) *Document

Stamped returns the stored record of a create commit: `{...create, createdAt: seq, ...(retire ? {retiredAt: seq})}`.

type JSON

type JSON = any

JSON is a value of package jv (nil, bool, float64, string, []any or *jv.Object; ECMAScript property order).

type ScopeKind

type ScopeKind uint8

ScopeKind is the owner kind of a document (spec §3.2).

const (
	ScopeSession ScopeKind = iota + 1
	ScopeConversation
	ScopeTask
)

Document scopes; the documents.scope_kind column holds the name.

func (ScopeKind) String

func (k ScopeKind) String() string

String returns the persisted scope name.

type Submission

type Submission struct{ V *jv.Object }

Submission is a submission record (spec §2 SubmissionRecord): `{id, conversationId, requestId?, type, status, entry?, answer?, reason?, detail?}` with the admission code's key order. Mutators return a modified shallow copy.

func ParseSubmission

func ParseSubmission(b []byte) (*Submission, error)

ParseSubmission reads a stored submission record.

func SubmissionOf

func SubmissionOf(o *jv.Object) (*Submission, error)

SubmissionOf reads a submission record that is already a value: ParseSubmission without the text, with the same checks.

func (*Submission) Answer

func (s *Submission) Answer() (int64, bool)

Answer is the answering entry of a done input; ok is false when absent.

func (*Submission) Append

func (s *Submission) Append(dst []byte) []byte

Append appends the record's JSON.stringify.

func (*Submission) ConversationID

func (s *Submission) ConversationID() int64

ConversationID is the conversation the submission was admitted to.

func (*Submission) Entry

func (s *Submission) Entry() (int64, bool)

Entry is the placed or answered-input entry; ok is false when absent.

func (*Submission) ID

func (s *Submission) ID() int64

ID is the submission ID.

func (*Submission) Reason

func (s *Submission) Reason() (string, bool)

Reason is the reason of an unanswered submission.

func (*Submission) RequestColumn

func (s *Submission) RequestColumn() (string, bool)

RequestColumn is the submissions.request_id column: JSON.stringify(requestId), ok false for NULL.

func (*Submission) RequestID

func (s *Submission) RequestID() (string, bool)

RequestID is the host deduplication key; ok is false when absent.

func (*Submission) Status

func (s *Submission) Status() SubmissionStatus

Status is the persisted status; 0 when the record has none.

func (*Submission) Type

func (s *Submission) Type() string

Type is "input" or "write".

type SubmissionStatus

type SubmissionStatus uint8

SubmissionStatus is the persisted submission status (spec §2), also the submissions.status column.

const (
	Queued SubmissionStatus = iota + 1
	Placed
	Done
	Unanswered
)

Submission statuses.

func ParseSubmissionStatus

func ParseSubmissionStatus(name string) (SubmissionStatus, bool)

ParseSubmissionStatus is the inverse of String; ok is false for an unknown name.

func (SubmissionStatus) String

func (s SubmissionStatus) String() string

String returns the persisted name ("queued", ...), or "" for an invalid status.

type Task

type Task struct{ V *jv.Object }

Task is a task record (spec §5.1 TaskRecord): `{id, conversationId, kind, version, input, owner?, background, abortRequested, startedAt?, endedAt?, state, memos?}` in the order a creation writes them (startedAt and endedAt are appended by StampTimes). Accessors read V; mutators return a modified shallow copy.

func NewTask

func NewTask(taskID, conv int64, kind string, version int, input JSON, owner int64, background bool, checkpoint JSON) *Task

NewTask builds a pending task in the key order of Tx.createTask (src/session/transaction.ts:411-423). owner is 0 for a task its conversation owns. checkpoint is the definition's initial checkpoint.

func ParseTask

func ParseTask(b []byte) (*Task, error)

ParseTask reads a stored task record. The fields the tasks table indexes must be present and well formed.

func TaskOf

func TaskOf(o *jv.Object) (*Task, error)

TaskOf reads a task record that is already a value: ParseTask without the text, with the same checks. The task keeps o; records are never changed in place (mutators return a copy), so it needs no copy of its own.

func (*Task) AbortRequested

func (t *Task) AbortRequested() bool

AbortRequested reports the durable abort mark.

func (*Task) Append

func (t *Task) Append(dst []byte) []byte

Append appends the record's JSON.stringify.

func (*Task) Background

func (t *Task) Background() bool

Background reports a background task (the `background` column is 1 exactly when this is true).

func (*Task) Checkpoint

func (t *Task) Checkpoint() JSON

Checkpoint is the state's checkpoint (pending, running, waiting); nil when absent.

func (*Task) ConversationID

func (t *Task) ConversationID() int64

ConversationID is the conversation the task lives in.

func (*Task) EndedAt

func (t *Task) EndedAt() (float64, bool)

EndedAt is the wall-clock ms of the change to terminal; ok is false while live.

func (*Task) ID

func (t *Task) ID() int64

ID is the task ID.

func (*Task) Input

func (t *Task) Input() JSON

Input is the original task input.

func (*Task) Kind

func (t *Task) Kind() string

Kind is the registered task definition name.

func (*Task) Memos

func (t *Task) Memos() *jv.Object

Memos returns the memo object kept while the task can run, or nil.

func (*Task) Owner

func (t *Task) Owner() (int64, bool)

Owner is the owning task of a child task; ok is false for a task its conversation owns.

func (*Task) StampTimes

func (t *Task) StampTimes(candidate *Task, now float64) *Task

StampTimes is Transaction.#stampTimes (src/session/transaction.ts:953-963): startedAt on the first change to running, endedAt on the change to terminal. A value already set on candidate (the transaction's latest candidate for the task) or on t carries over; now is the Harness clock of this commit. It returns t itself when nothing changes.

func (*Task) StartedAt

func (t *Task) StartedAt() (float64, bool)

StartedAt is the wall-clock ms of the first change to running (main da866ada); ok is false before the task first runs and on records written by 1.0.4.

func (*Task) State

func (t *Task) State() *jv.Object

State returns the state object (`{status, checkpoint | on... | outcome}`).

func (*Task) Status

func (t *Task) Status() TaskStatus

Status is the persisted status; 0 when the record has none.

func (*Task) Terminal

func (t *Task) Terminal() bool

Terminal reports a settled task.

func (*Task) Version

func (t *Task) Version() int

Version is the definition version of the live input and checkpoint.

func (*Task) WithAbortRequested

func (t *Task) WithAbortRequested() *Task

WithAbortRequested returns {...t, abortRequested: true}.

func (*Task) WithMemos

func (t *Task) WithMemos(memos *jv.Object) *Task

WithMemos returns {...t, memos}.

func (*Task) WithState

func (t *Task) WithState(state *jv.Object) *Task

WithState returns {...t, state} (scheduler.ts withState): entering completing or terminal drops the memos.

type TaskStatus

type TaskStatus uint8

TaskStatus is the persisted task status (spec §5.1), also the tasks.status column.

const (
	Pending TaskStatus = iota + 1
	Running
	Waiting
	Sleeping
	Completing
	Terminal
)

Task statuses.

func ParseTaskStatus

func ParseTaskStatus(name string) (TaskStatus, bool)

ParseTaskStatus is the inverse of String; ok is false for an unknown name.

func (TaskStatus) String

func (s TaskStatus) String() string

String returns the persisted name ("pending", ...), or "" for an invalid status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL