core

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package core is PiG's synchronous Durable core (docs/plan/durable-core, ADR-0001): one deterministic state machine per Session that takes an ABI 1 event and returns a step of commits, reads, notices and effects. The same source builds natively, as a Go wasip1 reactor and as a TinyGo wasip1 reactor (-scheduler=none); cmd/corewasm is the Wasm binding and sqlhost the native host.

Rules for every package under durable/core except cmd, host, contract and the abi/spec and abi/abitest tooling (purity_test.go enforces them): no reflection, no encoding/json, no fmt, no os, time, sync or net, no goroutines, no package-level mutable state (a package-level var must be documented as read-only), no I/O.

Layout and ownership (docs/plan/durable-core/LAYOUT.md):

abi       event, step, value types, codecs, Builder, abi_id         integrator
jv        ordered JSON values (ECMAScript property order)          dcore-session
delta     Chord document ops: tracker, apply                       dcore-session
rec       task, submission, conversation, document records        dcore-store
history   transcript arena, index, JSON scan/encode, context,      dcore-store, with dcore-loop
          forks, compaction ranges and summaries
store     SQL table, Pi rows, cold open, sidecar                   dcore-store
session   line, scheduler, tasks, documents, inbox, forks, ...     dcore-session
turn      generation and tool tasks                                dcore-loop
core      event routing and read deferral (this package)           integrator
cmd/corewasm, sqlhost, driver, host/cf, probe, budget (tooling)    dcore-host

Imports only point down this list (abi at the bottom, core at the top).

Index

Constants

View Source
const ABIID = abi.ID

ABIID is abi_id (ABI section 1).

Variables

View Source
var ErrNotImplemented = errors.New("session: not implemented")

ErrNotImplemented is returned for an event the handler does not serve yet; the core turns it into a rejected step. Read-only: assigned once at initialization.

Functions

func SQLTable

func SQLTable() []string

SQLTable returns the sql_table export.

Types

type Handler

type Handler interface {
	Handle(ev *abi.Event) error
}

Handler applies one ABI event (ABI section 5) to the Session kernel, emitting commits, reads, notices and effects into the builder it was made with. A store.ErrPending result means the event needs rows; the core re-delivers it after them.

type Reader

type Reader = func(sql uint16, params []abi.Value) ([][]abi.Value, error)

Reader runs one read statement of the SQL table at once and returns its rows (ABI section 4.2, import pig.read). The rows' text and blob values must not alias host memory the next call reuses.

type Rejection

type Rejection struct{ Name, Message string }

Rejection is an error the host sees as a rejected step: Pi's error name and message (ABI section 4.4).

func (*Rejection) Error

func (r *Rejection) Error() string

func (*Rejection) Text

func (r *Rejection) Text() string

Text is the message of the thrown host error (Error.message).

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is one ABI handle.

func NewSession

func NewSession(uuidv7 func() string) *Session

NewSession returns a handle. uuidv7 is the host's process-level pi-ai uuidv7() generator (ABI section 4.2).

func (*Session) MemStats

func (s *Session) MemStats() [8]uint64

MemStats reports the mem_stats export: arena, index, derived, documents, scratch, total live, heap in use, linear memory size. Total live is the documents plus the record text the mirror holds of what this handle wrote, so it stays constant across turns that leave no live work. The binding fills the last two from its runtime.

func (*Session) SetReader

func (s *Session) SetReader(read Reader)

SetReader gives the handle the host's synchronous read. With a reader, open loads the live state and the core reads settled records when a step needs them; without one it loads every record at open.

func (*Session) Step

func (s *Session) Step(ev abi.Event) *abi.Step

Step processes one event. The returned step is valid until the next Step call.

type ThrownError

type ThrownError struct{ Name, Message string }

ThrownError is what host code (a tool, a hook, a section) threw: its text is the error's message, as errorText in harness/tool.ts reads it, and its name survives for a caller that classifies.

func (*ThrownError) Error

func (e *ThrownError) Error() string

Directories

Path Synopsis
abi
Package abi is the Durable core host ABI 1 (docs/plan/durable-core/ABI.md): the event, step and value types, their wire codecs, the step builder every core package emits into, and ID, the abi_id every build exports.
Package abi is the Durable core host ABI 1 (docs/plan/durable-core/ABI.md): the event, step and value types, their wire codecs, the step builder every core package emits into, and ID, the abi_id every build exports.
abitest
Package abitest reads ABI event scripts and runs them through a native core.
Package abitest reads ABI event scripts and runs them through a native core.
payload
Package payload holds the JSON shapes of ABI 1 event and effect payloads as hosts send and read them (ABI sections 5-7).
Package payload holds the JSON shapes of ABI 1 event and effect payloads as hosts send and read them (ABI sections 5-7).
spec
Package spec holds the normative tables of ABI 1 (docs/plan/durable-core/ABI.md sections 4-8) and computes abi_id, the sha256 of their canonical rendering.
Package spec holds the normative tables of ABI 1 (docs/plan/durable-core/ABI.md sections 4-8) and computes abi_id, the sha256 of their canonical rendering.
spec/cmd/abigen command
Command abigen writes durable/core/abi/id.go (the abi_id constant the core exports) and durable/core/abi/abi.json (the tables and abi_id the JavaScript hosts read) from the tables in package spec.
Command abigen writes durable/core/abi/id.go (the abi_id constant the core exports) and durable/core/abi/abi.json (the tables and abi_id the JavaScript hosts read) from the tables in package spec.
budget
coldhints command
Command coldhints marks the functions that the first turn of a session runs in a core built by build-wasm.sh, as WebAssembly compilation hints, so that a host that enables hints compiles them with Liftoff when it compiles the module instead of one at a time on its first call.
Command coldhints marks the functions that the first turn of a session runs in a core built by build-wasm.sh, as WebAssembly compilation hints, so that a host that enables hints compiles them with Liftoff when it compiles the module instead of one at a time on its first call.
tinygo/patchdata command
Command patchdata writes the start address of .data, and the ranges of the globals that hold no heap pointers, into a TinyGo core built with the runtime fork in budget/tinygo.
Command patchdata writes the start address of .data, and the ranges of the globals that hold no heap pointers, into a TinyGo core built with the runtime fork in budget/tinygo.
cmd
corenative command
Command corenative serves the Durable core, built natively, to a host in another process over two FIFOs: the same exports as the WASI reactor (cmd/corewasm), one request and one response at a time.
Command corenative serves the Durable core, built natively, to a host in another process over two FIFOs: the same exports as the WASI reactor (cmd/corewasm), one request and one response at a time.
Package contracttest is the Go side of the Durable core conformance gate (docs/plan/durable-core/CONTRACT.md sections 5-7).
Package contracttest is the Go side of the Durable core conformance gate (docs/plan/durable-core/CONTRACT.md sections 5-7).
boundary
Package boundary checks that the production core links none of the reflection-driven standard-library packages TinyGo cannot build faithfully (go list -deps over the core packages, the Go and the Wasm configuration).
Package boundary checks that the production core links none of the reflection-driven standard-library packages TinyGo cannot build faithfully (go list -deps over the core packages, the Go and the Wasm configuration).
cmd/benchhost command
Command benchhost runs the durable-bench scenario (CONTRACT section 6: W1, W2, W4c, X1 and the H handoff rows) on the production Durable core packages as a native bench host.
Command benchhost runs the durable-bench scenario (CONTRACT section 6: W1, W2, W4c, X1 and the H handoff rows) on the production Durable core packages as a native bench host.
cmd/countgate command
Command countgate measures what the Durable core costs on a recorded workload (package counts): bytes allocated, mallocs, Wasm instructions on an instrumented module, native instructions under callgrind, and the growth of the live set per turn.
Command countgate measures what the Durable core costs on a recorded workload (package counts): bytes allocated, mallocs, Wasm instructions on an instrumented module, native instructions under callgrind, and the growth of the live set per turn.
cmd/replayhost command
Command replayhost is a script-driven stand-in for a native Durable core host: it applies the statements of a recorded trace to a SQLite store, one transaction per commit, and writes its own trace with contracttest.Writer.
Command replayhost is a script-driven stand-in for a native Durable core host: it applies the statements of a recorded trace to a SQLite store, one transaction per commit, and writes its own trace with contracttest.Writer.
cmd/scprovider command
Command scprovider serves the core's write encoder to the storage conformance suite (CONTRACT 3.10, the SC row): the suite's Storage is pi-durable's SqliteStorage for every read, and this process for commit and mintId.
Command scprovider serves the core's write encoder to the storage conformance suite (CONTRACT 3.10, the SC row): the suite's Storage is pi-durable's SqliteStorage for every read, and this process for commit and mintId.
counts
Package counts is the Durable core's deterministic count gate (Durable plan 2, item 9) and its flight recorder format.
Package counts is the Durable core's deterministic count gate (Durable plan 2, item 9) and its flight recorder format.
fuel
Package fuel meters a WebAssembly module: Instrument rewrites a module so that every basic block adds its own length to a counter, the Wasm instruction count the count gate ratchets (docs/plan/durable-core, Durable plan 2 item 9).
Package fuel meters a WebAssembly module: Instrument rewrites a module so that every basic block adds its own length to a counter, the Wasm instruction count the count gate ratchets (docs/plan/durable-core, Durable plan 2 item 9).
guard
Package guard bounds a native host process of the conformance gate: a request that runs too long, a heap that grows past a limit, or a parent that has gone.
Package guard bounds a native host process of the conformance gate: a request that runs too long, a heap that grows past a limit, or a parent that has gone.
storehost
Package storehost is the synchronous SQLite host of ABI section 3 for the store alone: tooling that drives store.Store (the benchmark engine, the storage-conformance provider) applies a step's commits and answers its reads with it.
Package storehost is the synchronous SQLite host of ABI section 3 for the store alone: tooling that drives store.Store (the benchmark engine, the storage-conformance provider) applies a step's commits and answers its reads with it.
Package docs holds the built-in conversation documents of src/harness/agent.ts and provider.ts that no machine owns: pi.agent and pi.provider, and the conversation-creation step for pi.agent.
Package docs holds the built-in conversation documents of src/harness/agent.ts and provider.ts that no machine owns: pi.agent and pi.provider, and the conversation-creation step for pi.agent.
Package driver holds the native Go effect executors of the Durable core (docs/plan/durable-core/ABI.md section 6, ADR-0001 D17).
Package driver holds the native Go effect executors of the Durable core (docs/plan/durable-core/ABI.md section 6, ADR-0001 D17).
Package history is the transcript half of the Durable core: entries, forks, head markers, context edits, compaction ranges and reset, and the context derivation that turns them into the model's messages.
Package history is the transcript half of the Durable core: entries, forks, head markers, context edits, compaction ranges and reset, and the context derivation that turns them into the model's messages.
internal/buildcheck command
Command buildcheck links the history package into a program so that TinyGo (-target=wasip1 -scheduler=none), Go wasip1 and native Go build the same source.
Command buildcheck links the history package into a program so that TinyGo (-target=wasip1 -scheduler=none), Go wasip1 and native Go build the same source.
Package inbox is the Session-side submission queue of src/harness/inbox.ts and submissions.ts: the built-in pi.inbox document, the boundaries that place queued items, and admission, abort and withdrawal of submissions.
Package inbox is the Session-side submission queue of src/harness/inbox.ts and submissions.ts: the built-in pi.inbox document, the boundaries that place queued items, and admission, abort and withdrawal of submissions.
internal
delta
Package delta ports Chord's immutable JSON deltas (@earendil-works/chord 1.0.4 `delta`: operations, the immutable applier and the overlay draft tracker) onto the ordered value model of package jv.
Package delta ports Chord's immutable JSON deltas (@earendil-works/chord 1.0.4 `delta`: operations, the immutable applier and the overlay draft tracker) onto the ordered value model of package jv.
Package jv is the ordered JSON value model of the Durable core's session layer.
Package jv is the ordered JSON value model of the Durable core's session layer.
Package probe is a small ABI 1 core that exists to test hosts.
Package probe is a small ABI 1 core that exists to test hosts.
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).
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).
Package session is the Durable core's Session layer: the Session line, the transaction that stages one atomic commit (conversations, entries, tasks, submissions and documents), the document cache, and the task scheduler.
Package session is the Durable core's Session layer: the Session line, the transaction that stages one atomic commit (conversations, entries, tasks, submissions and documents), the document cache, and the task scheduler.
cmd/tgprobe command
Command tgprobe links the session layer's packages so the TinyGo build can prove they compile without reflection.
Command tgprobe links the session layer's packages so the TinyGo build can prove they compile without reflection.
hopcost
Package hopcost derives, in microtask ticks, how long Pi's Storage adapters take, so the core can park a line job on a hops chain as long as Pi's job (ABI.md section 5.3).
Package hopcost derives, in microtask ticks, how long Pi's Storage adapters take, so the core can park a line job on a hops chain as long as Pi's job (ABI.md section 5.3).
sessiontest
Package sessiontest provides an in-memory session.Store that keeps all committed state, as pi-durable's MemoryStorage does.
Package sessiontest provides an in-memory session.Store that keeps all committed state, as pi-durable's MemoryStorage does.
Package sqlhost is the native Go host of the Durable core (docs/plan/durable-core/ABI.md section 11, ADR-0001 D17).
Package sqlhost is the native Go host of the Durable core (docs/plan/durable-core/ABI.md section 11, ADR-0001 D17).
cmd/bench command
Command bench is the native candidate of the Durable conformance gate (durable/contract/impls/native.mjs): the bench scenario (durable/contract/scenarios/bench.mjs) run through the native session on the core, with its statements written as a trace of statements only (contracttest.Writer), which the Node tools replay onto the starting store.
Command bench is the native candidate of the Durable conformance gate (durable/contract/impls/native.mjs): the bench scenario (durable/contract/scenarios/bench.mjs) run through the native session on the core, with its statements written as a trace of statements only (contracttest.Writer), which the Node tools replay onto the starting store.
Package store owns pi-durable's SQLite format inside the core: the SQL table, the rows every commit writes (CONTRACT section 3.1, row identity with pi-durable main), the single-writer guard, the in-memory metadata, cold open of the live state (ADR D5), loads of committed non-live records, and the pig_ sidecar (ADR D6).
Package store owns pi-durable's SQLite format inside the core: the SQL table, the rows every commit writes (CONTRACT section 3.1, row identity with pi-durable main), the single-writer guard, the in-memory metadata, cold open of the live state (ADR D5), loads of committed non-live records, and the pig_ sidecar (ADR D6).
Ports packages/ai/src/utils/overflow.ts (OVERFLOW_PATTERNS, NON_OVERFLOW_PATTERNS) Ports packages/ai/src/utils/retry.ts (RETRYABLE_PROVIDER_ERROR_PATTERN, NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN)
Ports packages/ai/src/utils/overflow.ts (OVERFLOW_PATTERNS, NON_OVERFLOW_PATTERNS) Ports packages/ai/src/utils/retry.ts (RETRYABLE_PROVIDER_ERROR_PATTERN, NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN)

Jump to

Keyboard shortcuts

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