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 ¶
- Variables
- func IndexedString(s string) string
- type Address
- type Conversation
- type Document
- func (d *Document) Address() Address
- func (d *Document) AliveAt(current bool, at int64) bool
- func (d *Document) Append(dst []byte) []byte
- func (d *Document) CreatedAt() (int64, bool)
- func (d *Document) CurrentOnly() bool
- func (d *Document) Fork() string
- func (d *Document) History() string
- func (d *Document) ID() int64
- func (d *Document) Key() (string, bool)
- func (d *Document) Kind() string
- func (d *Document) Retired(seq int64) *Document
- func (d *Document) RetiredAt() (int64, bool)
- func (d *Document) Scope() (kind ScopeKind, owner int64)
- func (d *Document) Stamped(seq int64, retire bool) *Document
- type JSON
- type ScopeKind
- type Submission
- func (s *Submission) Answer() (int64, bool)
- func (s *Submission) Append(dst []byte) []byte
- func (s *Submission) ConversationID() int64
- func (s *Submission) Entry() (int64, bool)
- func (s *Submission) ID() int64
- func (s *Submission) Reason() (string, bool)
- func (s *Submission) RequestColumn() (string, bool)
- func (s *Submission) RequestID() (string, bool)
- func (s *Submission) Status() SubmissionStatus
- func (s *Submission) Type() string
- type SubmissionStatus
- type Task
- func (t *Task) AbortRequested() bool
- func (t *Task) Append(dst []byte) []byte
- func (t *Task) Background() bool
- func (t *Task) Checkpoint() JSON
- func (t *Task) ConversationID() int64
- func (t *Task) EndedAt() (float64, bool)
- func (t *Task) ID() int64
- func (t *Task) Input() JSON
- func (t *Task) Kind() string
- func (t *Task) Memos() *jv.Object
- func (t *Task) Owner() (int64, bool)
- func (t *Task) StampTimes(candidate *Task, now float64) *Task
- func (t *Task) StartedAt() (float64, bool)
- func (t *Task) State() *jv.Object
- func (t *Task) Status() TaskStatus
- func (t *Task) Terminal() bool
- func (t *Task) Version() int
- func (t *Task) WithAbortRequested() *Task
- func (t *Task) WithMemos(memos *jv.Object) *Task
- func (t *Task) WithState(state *jv.Object) *Task
- type TaskStatus
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
AddressKey identifies the logical address of a record (storage.ts addressKey).
type Conversation ¶
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) 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 ¶
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 ¶
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 ¶
ParseDocument reads a stored document record.
func (*Document) AliveAt ¶
AliveAt is storage.ts isAliveAt for a historical point; current is the current-incarnation test.
func (*Document) CreatedAt ¶
CreatedAt is the commit that created the incarnation; ok is false on a DocumentCreate.
func (*Document) CurrentOnly ¶
CurrentOnly is storage.ts isCurrentOnly: only the current content is retained (no as-of reads).
func (*Document) History ¶
History is "latest" or "rewindable" for a conversation-scoped document, "" otherwise.
func (*Document) RetiredAt ¶
RetiredAt is the commit that retired the incarnation; ok is false while current.
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).
Document scopes; the documents.scope_kind column holds the name.
type Submission ¶
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) 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.
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 ¶
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 ¶
ParseTask reads a stored task record. The fields the tasks table indexes must be present and well formed.
func TaskOf ¶
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 ¶
AbortRequested reports the durable abort mark.
func (*Task) Background ¶
Background reports a background task (the `background` column is 1 exactly when this is true).
func (*Task) Checkpoint ¶
Checkpoint is the state's checkpoint (pending, running, waiting); nil when absent.
func (*Task) ConversationID ¶
ConversationID is the conversation the task lives in.
func (*Task) EndedAt ¶
EndedAt is the wall-clock ms of the change to terminal; ok is false while live.
func (*Task) Owner ¶
Owner is the owning task of a child task; ok is false for a task its conversation owns.
func (*Task) StampTimes ¶
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 ¶
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) Status ¶
func (t *Task) Status() TaskStatus
Status is the persisted status; 0 when the record has none.
func (*Task) WithAbortRequested ¶
WithAbortRequested returns {...t, abortRequested: true}.
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.