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 ¶
const ABIID = abi.ID
ABIID is abi_id (ABI section 1).
Variables ¶
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 ¶
Types ¶
type Handler ¶
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 ¶
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).
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one ABI handle.
func NewSession ¶
NewSession returns a handle. uuidv7 is the host's process-level pi-ai uuidv7() generator (ABI section 4.2).
func (*Session) MemStats ¶
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.
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
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
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). |
|
Package turn is the agent turn: the built-in pi.generation and pi.tool tasks (spec §8.3-8.6) as session.TaskImpl definitions.
|
Package turn is the agent turn: the built-in pi.generation and pi.tool tasks (spec §8.3-8.6) as session.TaskImpl definitions. |