sessionstore

type AcquireReconciliationClaimRequest ¶

type AcquireReconciliationClaimRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	HolderID  string
	ExpiresAt time.Time
}

AcquireReconciliationClaimRequest takes or extends the claim on one session.

HolderID is the calling replica's own identity. ExpiresAt is that replica's promise about when it will be done, and it must lie in the store's future and within MaxReconciliationClaimTTL of it.

There is no claim instant and no expected revision. The claim instant is the store's, for the reason ReconciliationClaim states; the revision is not the caller's business because a claim is not a decision about a record the caller has read — it is "am I the one doing this?", and the answer is decided by the holder and the clock, closed by a compare-and-swap this store reads for itself.

There is deliberately no lease epoch. Requiring one would say that holding a session's lease is relevant to doing scaling work for it, which is exactly backwards: reconciliation runs when NO Host owns the session.

type AcquireResidencyRequest ¶ added in v0.4.0

type AcquireResidencyRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

AcquireResidencyRequest names an existing disposition-mode catalog session.

type AdmitCommandRequest ¶

type AdmitCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ProposedRuntimeCommandID RuntimeCommandID
	Kind                     CommandKind

	Payload    []byte
	PayloadRef sessionwire.ObjectReference

	AcceptedAt    time.Time
	ApplyDeadline time.Time
}

AdmitCommandRequest accepts one client command into a session's inbox. It is idempotent by (TenantID, SessionID, CommandID): a repeat returns the stored record unchanged with created false.

ProposedRuntimeCommandID is a PROPOSAL. Racing replicas may propose different runtime identities for one public CommandID; only the one in the winning record is stored, returned, and used, and a losing replica receives the winner's rather than its own. A caller must therefore use the returned mapping and never the value it sent.

AcceptedAt and ApplyDeadline are the caller's clock readings, as every other timestamp this package stores is. They belong to the WINNER: a duplicate returns the accepted instant and deadline that were durably committed, not the ones it just sent, and they take no part in deciding whether a duplicate mismatches — see AdmitCommand.

type AdmitDispositionCommandRequest ¶ added in v0.5.0

type AdmitDispositionCommandRequest struct {
	TenantID                 sessionwire.TenantID
	SessionID                sessionwire.SessionID
	CommandID                sessionwire.CommandID
	Binding                  SessionBinding
	ProposedRuntimeCommandID RuntimeCommandID
	Kind                     CommandKind
	Payload                  []byte
	PayloadObject            *sessionwire.ObjectMetadata
	AcceptedAt               time.Time
	ApplyDeadline            time.Time
}

AdmitDispositionCommandRequest proposes a pending command for an existing disposition catalog session. Binding must equal its actual immutable pin. A retry compares binding/kind/content and returns the winning runtime ID, metadata or inline representation, timestamps, deadline and acceptance order. This is not public-create reservation: uniqueness is scoped to one session.

type AdmitPublicCreateRequest ¶ added in v0.5.0

type AdmitPublicCreateRequest struct {
	Identity      PublicCreateIdentity
	Payload       []byte
	PayloadObject *sessionwire.ObjectMetadata
}

AdmitPublicCreateRequest completes prepared admission with verified content. Inline and independently uploaded object representations compare by content; retries return the exact winning inbox representation and acceptance order.

type BeginApplyingCommandRequest ¶

type BeginApplyingCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	LeaseEpoch       uint64
	ClaimExpiresAt   time.Time
}

BeginApplyingCommandRequest moves a claimed command into applying. Its members mean what ClaimCommandRequest's mean; ClaimExpiresAt replaces the claim's expiry, because the bound that mattered while the claimer was preparing is not the bound that matters while it is applying.

It is the machine's ONE IRREVERSIBLE expiry choice, and a caller should size it for the whole application rather than for the next step. Applying is a fortress: it cannot be re-claimed at any epoch and it cannot be renewed, so once this expiry lapses the command can be completed only by this same lease epoch and settled by nobody else until a later task's recovery reads the journal correlation. A value chosen too small does not fail the application — it parks the command.

type BeginDispositionAttemptRequest ¶ added in v0.6.0

type BeginDispositionAttemptRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	AttemptID        DispositionAttemptID
	JournalEpoch     JournalEpoch
	ResidencyEpoch   ResidencyEpoch
	StartedAt        time.Time
}

BeginDispositionAttemptRequest authorizes exactly one dispatch of one claimed command.

ExpectedRevision is the revision of the record the caller read and decided on, as every compare-and-swap in this package requires. JournalEpoch is the grant the runtime's own construction returned; ResidencyEpoch is the Host grant the caller holds, and it must be the claim's own — a lower one has been superseded permanently, and a higher one has not claimed this command.

StartedAt is the caller's own clock reading of when the attempt began. It is recorded, not used as a guard. Within THIS PROTOCOL the settlement path is the only exception: a settlement caller supplies no instant at all, and DispositionOutcome.SettledAt is the store's own reading — see there for why. The scope is not decoration. Package-wide the store's clock is stored in several places (gates, pointers and host targets all record one), so a sentence that claimed settlement was the only such instant anywhere would be false.

type BodyReference ¶

type BodyReference struct {
	Reference sessionwire.ObjectReference
	SizeBytes uint64
	SHA256    [32]byte
}

BodyReference is the fixed-integrity representation stored in an envelope. Reference is a logical Core identity, never a provider key or signed URL.

func BodyReferenceFromObjectMetadata(metadata sessionwire.ObjectMetadata) (BodyReference, error)

func (r BodyReference) ObjectMetadata() (sessionwire.ObjectMetadata, error)

type BodySlot ¶

type BodySlot struct {
	Inline    []byte
	Reference *BodyReference
}

BodySlot is one independent inline or object-backed body. A nil Inline is absent; a non-nil, zero-length Inline is present. Inline and Reference are mutually exclusive.

type CatalogEntry ¶

type CatalogEntry struct {
	Record   CatalogRecord
	Revision uint64
}

CatalogEntry is a catalog record together with the revision a caller passes to a subsequent Factory-owned compare-and-swap. The provider's immutable order is deliberately not exposed: it is sparse and scope-relative, so no caller can correctly infer a position or a count from it.

type CatalogError ¶

type CatalogError struct {
	Code     CatalogErrorCode
	Field    string
	Epoch    uint64
	Revision uint64
	Cause    error
}

CatalogError is a typed, redacted catalog failure. Field names the offending input or stage and never carries a provider name, key, or record payload. Epoch is populated only for CatalogErrorEpoch, where the committed high-water epoch is itself the answer, and Revision only for CatalogErrorConflict, where a backend that can safely disclose the current revision did so.

func (e *CatalogError) Error() string

func (e *CatalogError) Unwrap() error

type CatalogErrorCode ¶

type CatalogErrorCode string

CatalogErrorCode classifies a session catalog record failure.

Cursor is separate from Invalid because the two name different owners. An invalid limit is a caller mistake in the request this package validates; Cursor means a continuation token was not one this store issued for this query, whether the envelope or the provider token inside it failed, and a caller's only recovery is to restart the walk from the first page.

Epoch and Conflict are deliberately distinct, and the distinction is the whole point of the catalog's two ownership mechanisms. Epoch means a Host-owned write named a lease epoch below the record's committed high-water mark: that writer has provably been superseded and must not retry with the same epoch. Conflict means a compare-and-swap lost a race on the record's revision without any statement about ownership; the caller may re-read and retry. Unknown means the mutation's outcome could not be resolved at all.

const (
	CatalogErrorInvalid   CatalogErrorCode = "invalid"
	CatalogErrorCursor    CatalogErrorCode = "cursor"
	CatalogErrorNotFound  CatalogErrorCode = "not_found"
	CatalogErrorDeleted   CatalogErrorCode = "deleted"
	CatalogErrorIdentity  CatalogErrorCode = "identity"
	CatalogErrorEpoch     CatalogErrorCode = "epoch"
	CatalogErrorSequence  CatalogErrorCode = "sequence"
	CatalogErrorTooSoon   CatalogErrorCode = "too_soon"
	CatalogErrorConflict  CatalogErrorCode = "conflict"
	CatalogErrorUnknown   CatalogErrorCode = "unknown"
	CatalogErrorBackend   CatalogErrorCode = "backend"
	CatalogErrorMalformed CatalogErrorCode = "malformed"
	CatalogErrorVersion   CatalogErrorCode = "version"
	CatalogErrorTooLarge  CatalogErrorCode = "too_large"
)

type CatalogRecord ¶

type CatalogRecord struct {
	// PublicCreate is immutable provenance, present only in version 3 catalogs.
	// Desired placement and idempotency changes never rewrite this identity.
	PublicCreate *PublicCreateReservation
	// Binding is immutable after creation. Zero preserves the legacy v1 record.
	Binding                SessionBinding
	TenantID               sessionwire.TenantID
	SessionID              sessionwire.SessionID
	AgentID                sessionwire.AgentID
	RuntimeCompatibilityID string

	CreatedAt    time.Time
	LastActiveAt time.Time

	State            sessionwire.SessionState
	Residency        sessionwire.SessionResidency
	DesiredPlacement sessionwire.HostPlacement

	LastJournalSeq uint64
	LastEventID    sessionwire.EventID
	Checkpoint     CheckpointSummary
	OpenGates      []sessionwire.GateProjection

	LeaseEpoch            uint64
	DesiredIdempotencyKey string
	DesiredGeneration     uint64
	DesiredWorkload       DesiredWorkload
}

CatalogRecord is the neutral, replay-free durable projection of one session.

Its fields have two different owners, and the difference is enforced rather than documented. LeaseEpoch, State, Residency, LastActiveAt, the journal summary, the checkpoint summary, and the open-gate projections are written by the Host that holds the session's lease, and a write naming an epoch below the committed high-water mark is refused. DesiredPlacement, RuntimeCompatibilityID, and DesiredIdempotencyKey are Factory-authored desired state, guarded by revision compare-and-swap and an idempotency key; Factory never names a lease epoch, so it cannot claim ownership it does not have.

func (r CatalogRecord) PlacementIntent() (PlacementIntent, error)

func (r CatalogRecord) Status() (sessionwire.SessionStatus, error)

func (r CatalogRecord) Summary() (sessionwire.SessionSummary, error)

type CheckpointSummary ¶

type CheckpointSummary struct {
	JournalSeq uint64
	Reference  sessionwire.ObjectReference
	CapturedAt time.Time
}

CheckpointSummary is the bounded durable description of the active workspace checkpoint. Its zero value means no checkpoint has been committed. It names a logical Core object reference, never a provider key or signed URL.

type ClaimCommandRequest ¶

type ClaimCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	LeaseEpoch       uint64
	ClaimExpiresAt   time.Time
}

ClaimCommandRequest takes a short-lived claim on one accepted command.

ExpectedRevision is the revision the caller decided on, which is the revision the compare-and-swap names. It is required: a transition is a decision about a record the caller has read, and a claim that named no revision would be a blind write dressed as a compare-and-swap.

LeaseEpoch is the session lease epoch the claimer is acting under, and ClaimExpiresAt is the caller's own reading of when the claim lapses. The claim's expiry may fall after the command's apply deadline — that is what lets an unexpired claim win the deadline race — but it may not fall in the past.

type ClaimDispositionCommandRequest ¶ added in v0.8.0

type ClaimDispositionCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	Residency        *ResidencyGrant
	ClaimExpiresAt   time.Time
}

ClaimDispositionCommandRequest takes a short-lived claim on one admitted disposition command, which is the state BeginDispositionAttempt starts from.

ExpectedRevision is the revision the caller read and decided on, as every compare-and-swap in this package requires. ClaimExpiresAt is the caller's own reading of when the claim lapses, evaluated against the STORE's clock, and it is held to MaxCommandClaimTTL for that constant's stated reason. The claim's expiry MAY fall after the command's apply deadline — that is what lets an unexpired claim win the deadline race — but it may not fall in the past.

Residency is a GRANT and not a number, and that is the load-bearing choice ¶

Every other residency-taking API in this package takes a bare ResidencyEpoch. This one takes the *ResidencyGrant that AcquireResidency returned, and the epoch is read off it. The caller cannot name an epoch at all.

The reason is that THIS EDGE IS THE ONLY PRODUCER OF THE RECORD'S HIGH-WATER MARK, and that mark only ever rises. Three call sites fence against it — this edge, BeginDispositionAttempt and RejectDispositionCommand — so a single stored claim at an epoch no provider ever issued permanently supersedes every real Host for that command: it can never be claimed, attempted or applied again, and its only remaining exit is a zero-residency reconciler rejection once the bogus claim lapses. The command is durably lost, silently, from one well-formed call.

A bare number could not be checked. `storage.Leaser` exposes only `Acquire(ctx, name) (Lease, error)`, so there is NO way to read a session's issued epoch without taking the lease away from whoever holds it — the store cannot validate a number a caller hands it, at any price short of a Storage contract change. A grant needs no validation: it is the store's own object, carrying a provider-issued epoch for a named session, so an unissued number is not expressible rather than merely refused.

Be exact about what that buys, because the module's own warnings apply here too. It is NOT proof of a live lease — nothing in this package reads one, and a grant whose lease has expired or been taken over still passes. It IS proof that the epoch came from this store's provider for this session, which is the whole of what a ratcheting mark needs: a stale grant names a LOWER epoch and the fence refuses it on its own terms, and it cannot name a higher one. See (*ResidencyGrant).residencyFor for each conjunct.

Why the other edges keep a bare epoch, which is not an inconsistency ¶

The rule, stated so that it actually sorts this package rather than sounding like it does:

A caller-asserted value is safe when it is BOUNDED, SELF-LIMITING, or
COMPARED AND DISCARDED. It must be store-issued when it becomes a MONOTONIC
BOUND ON FUTURE CALLERS that is UNBOUNDED ABOVE and OUTLIVES THE STATE THAT
CARRIED IT.

"The store decides from it" is NOT the rule, and the distinction matters because the shorter sentence is the one a reader will remember. Three caller-asserted values in this same file are decided from, two of them are written, and none is store-issued — and all three are fine:

• ExpectedRevision is compared and discarded. Every compare-and-swap here decides from it, and it never becomes state.
• ClaimExpiresAt is written AND decided from — liveness, the deadline race, replay identity — but it is BOUNDED (MaxCommandClaimTTL, and it must be in the future) and SELF-LIMITING: it lapses, and the record recovers.
• ApplyDeadline is written at admission and decides the deadline refusal, and it is bounded by the same rankable-time rule every stored instant is.

Claim.ResidencyEpoch is none of those. It is written, it is UNBOUNDED ABOVE, and — the property that actually does the work — it OUTLIVES THE CLAIM: dispositionRecordHighWater reads it with no liveness test, and the fence runs BEFORE the live check at both edges, so a lapsed claim still supersedes. That is what makes a bad value permanent rather than merely temporary, and it is the whole discriminator. TestClaimDispositionCommandRefusalOrder's "superseded residency before the deadline and a lapsed claim" is the case that proves it.

Applying that rule to this protocol's four residency-bearing APIs: SettlingResidencyEpoch is recorded and never read back. BeginDispositionAttempt's epoch is fenced to equal the claim's own, so it cannot raise the mark. RejectDispositionCommand writes no claim at all, so it cannot either — and it must accept a zero, because a reconciler holds no residency. Only this edge writes the mark, so only this edge is gated.

type ClearHostRegistrationRequest ¶

type ClearHostRegistrationRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch uint64
}

ClearHostRegistrationRequest releases one session's route, leaving the epoch-fenced tombstone behind.

It carries no timestamp, and that is deliberate rather than an omission. A tombstone's instants are not an observation of anything — they record that THIS STORE wrote the tombstone — and a caller-supplied instant could place a tombstone's expiry in the future, producing a record that reads as released by structure and as live by time. The store's own clock cannot.

type ClearSessionPointerRequest ¶

type ClearSessionPointerRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch uint64
}

ClearSessionPointerRequest gives up one role's object, leaving the epoch-fenced tombstone behind.

It names no sequence, and that is the shape of the operation rather than an omission: clearing does not publish a capture, so there is nothing for a sequence to describe, and the stored one is RETAINED rather than replaced. A request that could name one could lower it.

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock supplies wall time to storage decisions and permits deterministic tests.

type CommandApplication ¶

type CommandApplication struct {
	CommandID        sessionwire.CommandID
	RuntimeCommandID RuntimeCommandID

	Outcome CommandApplicationOutcome

	// PrefixSeq and PrefixEpoch locate the prefix the outcome is about, and are
	// zero when the outcome is Absent.
	PrefixSeq   uint64
	PrefixEpoch uint64

	// EffectSeq and EffectEventID name the public event that carried the
	// effect, and are zero unless the outcome is Committed.
	EffectSeq     uint64
	EffectEventID sessionwire.EventID

	// SupersedingEpoch is the highest opening-fence epoch THE WALK OBSERVED,
	// and a writer at or below it is provably fenced out of the stream.
	//
	// It is deliberately not described as the highest lease that ever owned the
	// session, which is what a walk from sequence one happens to find today.
	// The two come apart the moment the walk is bounded — the admission-tip
	// bound above is the obvious way, and it would leave every fence written
	// before the command was accepted unobserved — and the predicate this
	// member exists for stays correct under that, because a fence observed
	// LATER than some other fence is still a fence. Promising the maximum over
	// the whole journal would make a bound that is otherwise fine look like a
	// breaking change.
	SupersedingEpoch uint64

	CapturedTip uint64
}

CommandApplication is what one session's journal proves about one command.

Every member describes DURABLE STATE this store read, never a conclusion about a caller. The sequences are journal sequences in the session's own stream; the epochs are session lease epochs.

CapturedTip is the tip the correlation was taken at, and it exists to say how long the answer is good for. The answer is: FOUR OF THE FIVE OUTCOMES ARE NOT STABLE ACROSS TIPS, and the transitions are ordinary rather than exotic — absent becomes committed when the applier commits its prefix and effect a moment later, abandoned becomes committed when a later lease retries the application to completion, unresolved becomes either as soon as one more record lands, and committed becomes conflicted when a prefix breaking the mapping appears anywhere later in the stream. Two of those are what this package's own tests do on purpose.

Only CONFLICTED cannot be superseded, because nothing outranks a broken mapping in precedence, which is also why it is the one finding an operator can act on without re-reading.

What IS monotone is not an outcome but a pair of NEGATIVE facts, and they are exactly the two a settlement rests on:

• no effect for this command had committed by CapturedTip, and
• the writer at a given epoch was already fenced out by CapturedTip.

Both are properties of a PREFIX OF THE STREAM, and the journal only appends, so no later record undoes either. That is the whole of why the settlements are safe, and it is also why they RE-SCAN rather than accept a correlation a caller took earlier: a caller's older answer still carries true negative facts, but the store cannot tell from the value alone which tip they were true of relative to the record it is about to write.

A caller may therefore hold a correlation to decide WHAT TO DO — finish or settle — and must not hold one as a licence. Caching an ABSENT answer and rejecting on it later is precisely the overwrite this file exists to prevent: absence is the least stable finding there is, because every application starts from it.

type CommandApplicationOutcome ¶

type CommandApplicationOutcome string

CommandApplicationOutcome is what a session's journal proves about one command's application. It is a closed vocabulary because each value unlocks a different settlement, and a caller that met an unlisted one would have no safe default.

const (
	// CommandApplicationAbsent means no record in the journal names this
	// command. Nothing has been applied under it.
	CommandApplicationAbsent CommandApplicationOutcome = "absent"

	// CommandApplicationCommitted means a correlated prefix is immediately
	// followed by the public event that carried its effect. The command has
	// been applied, whichever lease did it.
	CommandApplicationCommitted CommandApplicationOutcome = "committed"

	// CommandApplicationAbandoned means a correlated prefix is immediately
	// followed by an opening fence above its own epoch: the application started
	// and its writer lost the stream before committing anything more.
	CommandApplicationAbandoned CommandApplicationOutcome = "abandoned"

	// CommandApplicationUnresolved means a correlated prefix exists whose
	// outcome cannot be read: it is still at the tip with its writer possibly
	// alive, or the record after it is neither its effect nor its writer's
	// fence. Both settlements refuse; the answer may become readable later.
	CommandApplicationUnresolved CommandApplicationOutcome = "unresolved"

	// CommandApplicationConflicted means a prefix names this command's public
	// identity with a different runtime identity or kind. The durable mapping
	// is broken, so no settlement is safe and an operator has to look.
	CommandApplicationConflicted CommandApplicationOutcome = "conflicted"
)

type CommandClaim ¶

type CommandClaim struct {
	LeaseEpoch uint64
	ExpiresAt  time.Time
}

CommandClaim is the current short-lived claim on a command. Its zero value means the command is unclaimed.

LeaseEpoch is the claiming Host's grant epoch. It is recorded here rather than fencing anything in this file: admission never writes a claim.

type CommandKind ¶

type CommandKind string

CommandKind names what the command asks the session to do.

The set is deliberately not enumerated here. Core accepts any non-empty state, residency, and gate kind so a later wire version can add one, and a closed set in this package would refuse a command Core itself considers valid. It is validated as a bounded opaque UTF-8 value.

type CommandResult ¶

type CommandResult struct {
	CompletedAt time.Time
	EventID     sessionwire.EventID
	JournalSeq  uint64
}

CommandResult is the terminal application result: the durable journal event that carried the command's effect. Its zero value means the command has not been applied.

type CompleteCommandRequest ¶

type CompleteCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	LeaseEpoch       uint64
	Result           CommandResult
}

CompleteCommandRequest records the terminal application of a command.

Result names the durable journal event that carried the command's effect. It is required, because "applied" with no event is a claim that something happened with nothing to point at.

type CreateCatalogEntryRequest ¶

type CreateCatalogEntryRequest struct {
	Binding                SessionBinding
	TenantID               sessionwire.TenantID
	SessionID              sessionwire.SessionID
	AgentID                sessionwire.AgentID
	RuntimeCompatibilityID string
	CreatedAt              time.Time
	LastActiveAt           time.Time
	State                  sessionwire.SessionState
	Residency              sessionwire.SessionResidency
	DesiredPlacement       sessionwire.HostPlacement
	DesiredWorkload        DesiredWorkload
	IdempotencyKey         string
}

CreateCatalogEntryRequest creates the authoritative record for one session. Legacy creation is idempotent by (TenantID, SessionID). A bound retry must also match the immutable Binding and AgentID; a mismatch is CatalogErrorConflict. A legacy request cannot adopt a bound row. Matching retries return the stored record unchanged with created false, even when mutable desired fields differ.

type DesiredWorkload ¶

type DesiredWorkload struct {
	PayloadVersion string
	Payload        []byte
}

DesiredWorkload is the platform workload a Factory wants reconciled for a dedicated session, carried opaquely.

Its zero value means no workload is desired, which is the ordinary case for a pooled session: pooled capacity is reconciled by scaling a Department's Hosts, not by creating anything per session.

The two members are present together or absent together, and canonicalization enforces that rather than documenting it. A payload with no version is a document no reconciler can interpret — it would have to guess a schema — and a version with no payload is a claim about nothing. Requiring both also gives "absent" exactly one spelling, which is what keeps a record's stored bytes independent of which writer produced them.

PayloadVersion is caller-owned text and is never interpreted here. It exists so that a reconciler reading a payload it does not understand can say so instead of misreading it.

A NOTE OWED TO WHOEVER ADDS A BYTES-IDENTITY CHECK TO THE CATALOG. This member makes the catalog record's stored bytes a normalizer's output rather than a fixed point of the caller's input: encoding/json decodes a []byte with non-strict base64, so a stored "AR==" decodes to one byte and re-encodes as "AQ==". The record still round-trips CANONICALLY — decode, encode, decode again is stable, which is what the codec fuzzer asserts — but a check comparing a provider's reply against the exact bytes handed to it, as verifyReconciliationClaimBytes and verifyRegistrationBytes do for records with no []byte member, would refuse a faithful reply to a value some other writer had stored non-canonically. Compare re-encoded forms there, not raw bytes.

type DispositionAttempt ¶ added in v0.6.0

type DispositionAttempt struct {
	AttemptID      DispositionAttemptID `json:"attempt_id"`
	JournalEpoch   JournalEpoch         `json:"journal_epoch"`
	ResidencyEpoch ResidencyEpoch       `json:"residency_epoch"`
	StartedAt      time.Time            `json:"started_at"`
}

DispositionAttempt is the complete record of one authorized dispatch, written before the dispatch and immutable afterwards.

JournalEpoch is the grant the runtime returned for the bound journal and ResidencyEpoch is the Host grant the dispatch was authorized under. They are stored as two members of two types on purpose: an attempt that kept one number could not tell a successor which authority had actually been held.

These struct tags are NOT the durable spelling; see dispositionAttemptWire.

type DispositionAttemptID ¶ added in v0.6.0

type DispositionAttemptID string

DispositionAttemptID is the immutable identity of one authorized dispatch. It is an opaque caller-chosen name, bounded like every other identity here, and it is what the runtime's durable disposition must name for the evidence to be about this attempt.

type DispositionClaim ¶ added in v0.6.0

type DispositionClaim struct {
	ResidencyEpoch ResidencyEpoch `json:"residency_epoch"`
	ExpiresAt      time.Time      `json:"expires_at"`
}

DispositionClaim is the residency-guarded claim a command is worked on under.

Nothing in THIS file moves a pending command into claimed: the claim edge is ClaimDispositionCommand in disposition_claim.go, and this type is declared here because the attempt below consumes such a record and must say precisely what it requires of one. ExpiresAt is the claimant's own reading of when the claim lapses, evaluated against the STORE's clock exactly as every other liveness guard in this package is.

type DispositionCommandCursor ¶ added in v0.7.0

type DispositionCommandCursor struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch    uint64
	ConsumedOrder uint64

	UpdatedAt time.Time
}

DispositionCommandCursor is the durable record of how far one session's disposition command consumer has got, and of the residency epoch that last said so.

WHAT IT IS. ConsumedOrder is an immutable acceptance order from THIS session's DISPOSITION inbox, and the record's meaning is exactly: SOME CONSUMER ASSERTED IT WAS DONE WITH EVERY COMMAND AT OR BELOW THIS POSITION. LeaseEpoch is the epoch of the grant that last wrote the record and is its fencing high-water mark; it never falls, which is why this record is never deleted.

WHAT IT IS NOT, and this half matters more, because the obvious reading of a durable cursor is far stronger than what this row can support. It follows the rule SettlingResidencyEpoch states for the settlement record: the stored epoch is CONTEXT, NOT AUTHORITY.

1. IT IS NOT PROOF THAT ANY COMMAND WAS APPLIED. It is not a summary of the inbox and it is not derived from one. A consumer that read ten commands, rejected three, failed at the eleventh and saved ten writes exactly the same row as one that applied all ten. The authoritative state of a command is its own record's State, reachable by name, and nothing here substitutes for reading it.

2. IT IS NOT PROOF THAT THE SAVER HELD A LIVE RESIDENCY. The fence establishes that LeaseEpoch is at or above the greatest epoch previously committed to this row; it does not establish that the grant was still held at the compare-and-swap, and NO PATH IN THIS PACKAGE READS A LIVE LEASE on this record. Read the field as "who asked, at or above the mark", never as "who validly consumed".

3. IT AUTHORIZES NOTHING. It licenses no claim, no dispatch, no settlement and no read. Every one of those goes through its own operation, with its own preconditions, and none of them consults this row.

4. IT SAYS NOTHING ABOUT COMMANDS ABOVE IT. In particular a command above the cursor may be applied, settled, or claimed by someone else; the cursor is a consumer's position, not a watermark the inbox respects.

5. ZERO IS NOT PROOF THAT NOTHING WAS CONSUMED. It is proof that nothing was RECORDED. A consumer that processed a hundred commands and crashed before its first save leaves this row absent, and a successor that trusted zero as history rather than as a starting position would re-present all hundred. Re-presentation is safe — command application is idempotent by identity — but a caller must know that is what it is relying on.

6. IT IS NOT COMPARABLE ACROSS SESSIONS OR PROTOCOLS, for the reason DispositionInboxEntry states about AcceptedOrder itself: the number is a position in one session's disposition stream and means nothing in any other.

UpdatedAt is the STORE's clock, read when the request is validated and before any provider call, exactly as SessionPointer's is and for the same reason: nothing decides on it, so it is an audit line rather than an input, and paying a round trip to make it truer would buy nothing.

The accumulation is one small permanent row per session that has ever had a consumer: never listed, never ranked, never due, never read except by name. The registry's carry-forward contract about retention applies word for word — the only safe reaper is one that removes the session's whole scope at once, because deleting this row alone destroys a fence while leaving the session writable.

type DispositionCommandCursorEntry ¶ added in v0.7.0

type DispositionCommandCursorEntry struct {
	Cursor   DispositionCommandCursor
	Revision uint64
}

DispositionCommandCursorEntry is a cursor together with the revision a later compare-and-swap names.

The ZERO ENTRY is the answer for a session that has never recorded one, and it is a whole-value answer rather than a found flag: ConsumedOrder is zero exactly when nothing is recorded, because a zero order is refused on the way in and no provider allocates one. A caller may therefore test the entry, the cursor, or the order and get the same answer from all three.

type DispositionCommandDescriptor ¶ added in v0.5.0

type DispositionCommandDescriptor struct {
	// PublicCreate is emitted only by AdmitPublicCreate. Its explicit presence
	// fails older strict canonical v2 decoders; Kind itself remains opaque.
	// Generic reads check catalog binding, not reservation proof. The marker
	// alone cannot authorize future public-create dispatch; only successful
	// AdmitPublicCreate verifies reservation, catalog and inbox for an ACK.
	PublicCreate     bool                        `json:"public_create,omitempty"`
	TenantID         sessionwire.TenantID        `json:"tenant_id"`
	SessionID        sessionwire.SessionID       `json:"session_id"`
	CommandID        sessionwire.CommandID       `json:"command_id"`
	Binding          SessionBinding              `json:"binding"`
	RuntimeCommandID RuntimeCommandID            `json:"runtime_command_id"`
	Kind             CommandKind                 `json:"kind"`
	PayloadDigest    string                      `json:"payload_digest"`
	PayloadSize      uint64                      `json:"payload_size"`
	Payload          []byte                      `json:"payload,omitempty"`
	PayloadObject    *sessionwire.ObjectMetadata `json:"payload_object,omitempty"`
}

DispositionCommandDescriptor is immutable command identity and its winning runtime mapping. PayloadDigest is lowercase SHA-256 hex. PayloadSize and digest identify content regardless of representation or independent upload generation. PayloadObject, when present, contains the exact winning canonical metadata. Payload bytes are private and bounded by MaxInboxPayloadBytes; nil means empty inline content when PayloadObject is nil. Binding is the actual catalog pin. These struct tags are NOT the durable spelling: stored member names are pinned separately by this package's private wire DTO and by golden byte literals, so renaming a field here cannot move a stored record.

type DispositionDueCommandPage ¶ added in v0.5.0

type DispositionDueCommandPage struct {
	Commands   []DispositionInboxEntry
	Examined   int
	Unreadable int
	Limit      int
	NextCursor sessionwire.Cursor
}

DispositionDueCommandPage is a weak deadline-ordered view, not an acceptance stream or evidence of nonexistence. Examined counts provider rows, including Unreadable rows skipped for malformed/misfiled descriptors or missing, deleted, corrupt, legacy-mode or mismatched catalogs. Such rows advance continuation. Provider unavailability, cancellation and scope-check failures fail the page. No command is returned without its actual immutable catalog binding checked.

type DispositionEvidence ¶ added in v0.6.0

type DispositionEvidence struct {
	AttemptID           DispositionAttemptID
	Kind                DispositionOutcomeKind
	AttemptJournalEpoch JournalEpoch
	AuthorJournalEpoch  JournalEpoch
	DispositionSeq      uint64
	AuthorFenceSeq      uint64
	EventID             sessionwire.EventID
	EventSeq            uint64
}

DispositionEvidence is one committed runtime disposition, as read from the bound journal by the configured reader. Every member describes a record that is already durable in that journal; nothing here is a conclusion about a caller and nothing here may be supplied by one.

AuthorJournalEpoch is the grant that AUTHORED the disposition, which is the attempt's own grant for an application or a refusal and a strictly later one for a recovery closure. AuthorFenceSeq names the verified opening fence of that later author grant and is set only for a closure.

EventID and EventSeq are retained members of the durable shape that are ALWAYS ZERO. They were written for an applied disposition that carried its public event in the same envelope, and no such record can exist: a journal append frames one envelope, so an effect is always a separate record. They are kept rather than removed because they are members of the durable wire DTO and removing one would change stored bytes; nothing derives anything from them, and a non-zero value here is refused.

type DispositionEvidenceReader ¶ added in v0.6.0

type DispositionEvidenceReader interface {
	ReadDispositionEvidence(ctx context.Context, req DispositionEvidenceRequest) (DispositionEvidence, error)
}

DispositionEvidenceReader is the narrow, trusted boundary over committed journal records. An implementation resolves ONLY the immutable binding in the request, reads committed dispositions from that journal, and returns what it found. It must not execute an agent, and this package neither imports nor knows anything about what does.

Returning an error is the correct answer for an unavailable, cancelled, incomplete or unreadable journal: the error propagates to the caller and the command is left unsettled. A reader must NEVER report a missing or unreadable record as an empty DispositionEvidence — absence is not a disposition, and the zero value is refused here precisely so that a reader which did so settles nothing.

type DispositionEvidenceRequest ¶ added in v0.6.0

type DispositionEvidenceRequest struct {
	TenantID         sessionwire.TenantID
	SessionID        sessionwire.SessionID
	CommandID        sessionwire.CommandID
	Kind             CommandKind
	RuntimeCommandID RuntimeCommandID
	Binding          SessionBinding
	Attempt          DispositionAttempt
}

DispositionEvidenceRequest is the question the store asks its reader. It is DERIVED from the store's current inbox record — the pinned binding, the durable runtime mapping and the immutable attempt — and never from a settlement caller, which is what makes the reader's scope the session's own bound journal rather than anywhere a caller could point it.

type DispositionInboxEntry ¶ added in v0.5.0

type DispositionInboxEntry struct {
	Record        DispositionInboxRecord
	Revision      uint64
	AcceptedOrder uint64
}

DispositionInboxEntry carries provider revision and opaque per-session order. AcceptedOrder is increasing, not contiguous, and not comparable across sessions or protocols. Due pages are deadline-ordered, not acceptance-ordered.

type DispositionInboxRecord ¶ added in v0.5.0

type DispositionInboxRecord struct {
	Descriptor    DispositionCommandDescriptor `json:"descriptor"`
	AcceptedAt    time.Time                    `json:"accepted_at"`
	ApplyDeadline time.Time                    `json:"apply_deadline"`
	State         InboxState                   `json:"state"`
	Claim         *DispositionClaim            `json:"claim,omitempty"`
	Attempt       *DispositionAttempt          `json:"attempt,omitempty"`
	Outcome       *DispositionOutcome          `json:"outcome,omitempty"`
}

DispositionInboxRecord is one disposition command's authoritative record. Timestamps, like the descriptor, remain exactly those chosen by the winning create; admission produces InboxStatePending and never anything else.

Claim, Attempt and Outcome are the states beyond admission, and each is absent until the state that requires it: what each state must and must not carry is validateDispositionState, because that is a property of the record rather than of whichever transition wrote it. Once written, the attempt and both of its grant identities are immutable — no transition may rewrite one to make a successor's epochs look current. A terminal REJECTION is the one state that may carry none of the three: the protocol allows a command to be rejected before any dispatch was authorized, and such a record has no attempt for an outcome to be keyed by.

These struct tags are NOT the durable spelling; see the private wire DTOs.

type DispositionOutcome ¶ added in v0.6.0

type DispositionOutcome struct {
	Kind                   DispositionOutcomeKind `json:"kind"`
	AttemptID              DispositionAttemptID   `json:"attempt_id"`
	AttemptJournalEpoch    JournalEpoch           `json:"attempt_journal_epoch"`
	AuthorJournalEpoch     JournalEpoch           `json:"author_journal_epoch"`
	DispositionSeq         uint64                 `json:"disposition_seq"`
	AuthorFenceSeq         uint64                 `json:"author_fence_seq"`
	EventID                sessionwire.EventID    `json:"event_id"`
	EventSeq               uint64                 `json:"event_seq"`
	SettlingResidencyEpoch ResidencyEpoch         `json:"settling_residency_epoch"`
	SettledAt              time.Time              `json:"settled_at"`
}

DispositionOutcome is the durable terminal result of one command, keyed by the attempt that produced it and by the journal record that proves it.

SettlingResidencyEpoch is the residency the SETTLEMENT was requested under, which is separate settlement context and may be a successor's: it is recorded beside the attempt rather than over it, so the record keeps naming the grants the dispatch was actually authorized under.

Be exact about how much it is worth, and about which LAYER holds it. It is settlement context recorded from the REQUEST, fenced only against the claim's high-water mark, so the invariant it carries is SettlingResidencyEpoch >= Claim.ResidencyEpoch and nothing more — and that is a TRANSITION-time invariant, not a stored one. SettleDispositionCommand enforces it; the record validators check only that the epoch is non-zero, so a decoded record violating the inequality is accepted. It is true of every record this package WRITES and not of every record the codec ADMITS.

It is not proof of live residency at settlement either: no lease is read on this path, so a Host whose residency merely equals the claim's may have lost that lease since, and one naming a higher epoch is taken at its word. Read it as "who asked, and that they were not already superseded" — never as "who validly held the session when this settled".

SettledAt is a DELIBERATE DEVIATION from this package's convention that a stored instant is the caller's own clock reading, and the deviation is the point rather than an oversight. Every other member of this struct is derived from verified evidence or from the store's own immutable record, and the whole of SettleDispositionCommandRequest is that a caller supplies nothing an outcome is built from; accepting a caller's timestamp would have been the one caller-authored value in a record whose entire purpose is that it has none. It is the store's clock at the moment the outcome was constructed, taken before the terminal compare-and-swap, so it is when the store DECIDED and not when the runtime acted — the journal sequences are what order the runtime's side. It is not comparable with a caller's clock and must not be used as one.

EventID and EventSeq are members of the durable shape that are always zero; see DispositionEvidence for why they are retained rather than removed.

These struct tags are NOT the durable spelling; see dispositionOutcomeWire.

type DispositionOutcomeKind ¶ added in v0.6.0

type DispositionOutcomeKind string

DispositionOutcomeKind is the closed vocabulary of terminal runtime dispositions. Each value is a different durable statement and each carries different evidence, so a value outside this set is refused rather than given a default.

const (
	// DispositionApplied means that, under the ATTEMPT's journal grant, the
	// runtime durably recorded that it accepted this command into its
	// execution path. That is the whole of it, and the narrowness is the
	// point.
	//
	// It does NOT mean the effect is in the same journal envelope — an earlier
	// spelling of this comment said so and it was FALSE.
	// SessionJournal.Append takes exactly one record, encodes one body, frames
	// one envelope and does one AppendDefinite; there is no batch, so a runtime
	// cannot put any effect in the same frame as its disposition. The
	// disposition is a separate, private, bodiless frame, and a CONFORMING
	// runtime writes it after the synchronously-observable effect.
	//
	// That ordering is an obligation on the writer, not a property this package
	// establishes: the bodiless shape is enforced by validateEnvelope, but
	// nothing here observes when the effect was written, so a caller must not
	// read this as a checked guarantee.
	//
	// Four things it therefore does not prove: that a turn started, that a turn
	// folded, that no later TurnRejected can follow, and that a queued input
	// survives a crash. It says the acceptance was recorded, and a caller that
	// needs any of the four must read the journal for it.
	DispositionApplied DispositionOutcomeKind = "applied"

	// DispositionNoOp is an explicit successful application with no effect —
	// an interrupt of an idle session. It is a success, and it fabricates no
	// public event: reject-before-dispatch and an applied no-op are different
	// outcomes and are never merged.
	DispositionNoOp DispositionOutcomeKind = "no_op"

	// DispositionRefused is the runtime's own durable statement, authored under
	// the ATTEMPT's own grant, that it did NOT accept this command into its
	// execution path. It settles the command as rejected.
	//
	// It exists for liveness, not for symmetry. A runtime has post-prefix
	// failure paths it can take under a LIVE lease, and the only other
	// rejecting kind — DispositionNotApplied — is authored by a STRICTLY LATER
	// journal grant. Without this arm a command failing that way would sit
	// applying until the lease turned over, which a healthy Host never does.
	//
	// It is not a recovery closure and is never a substitute for one: a
	// refusal is a live runtime's own answer, while a closure is a successor's
	// conclusion about a runtime that is gone. Nothing may derive one from the
	// other.
	DispositionRefused DispositionOutcomeKind = "refused"

	// DispositionNotApplied is a successor runtime's recovery closure: it
	// proves, under a strictly later journal grant whose opening fence it
	// names, that no accepted transition occurred for this attempt. It is the
	// tombstone late dispatch must consult. An empty read is not one.
	DispositionNotApplied DispositionOutcomeKind = "not_applied"
)

type DrainHostTargetRequest ¶

type DrainHostTargetRequest struct {
	Key HostTargetKey

	HostID         sessionwire.HostID
	HostGeneration uint64
}

DrainHostTargetRequest withdraws one Host's advertisement for one target, gracefully and immediately.

It carries no timestamp, and that is deliberate rather than an omission. A withdrawal's instant is not an observation of anything — it records that THIS STORE wrote the withdrawal — and a caller-supplied instant would let a Host place its own withdrawal in the future or the distant past, in a record that nothing afterwards re-derives an expiry from. The store's own clock cannot.

type DueCommand ¶

type DueCommand struct {
	Entry InboxEntry
}

DueCommand is one outstanding command. The identities are read from the RECORD rather than restated beside it — a sweep learns them from the row — and Entry is the same value a named read of that command returns, held to the same filing checks.

It wraps a single member rather than being one, for the reason DueGatePage is a type rather than a second return value: what a reconciler needs BESIDE the record is not settled yet, and adding a field is a smaller change to make than changing the element type of a public slice.

type DueCommandPage ¶

type DueCommandPage struct {
	Commands   []DueCommand
	Examined   int
	Unreadable int
	Limit      int
	NextCursor sessionwire.Cursor
}

DueCommandPage is one bounded page of outstanding commands together with what producing it cost. It is where the three cost members both sweeps carry are defined; DueGatePage refers here rather than restating them.

EXAMINED is the number of rows the provider returned, and LIMIT is the EFFECTIVE limit after a zero request limit has been resolved to the store's page size, so the comparison is available to a caller that named no limit. Together they answer a question the results alone cannot: Examined == Limit with nothing reported means this page was full and none of it said anything, which is a different state from "nothing is due".

UNREADABLE counts rows this reader could not decode, that disagreed with the filing they were found under, or that belong in a different shard. Each is SKIPPED rather than failing the page, and that is the strongest rule here rather than leniency: this view is ascending by an instant that never moves and nothing rewrites such a row, so a reader that failed on one would switch reconciliation off for every tenant in the shard until someone repaired the row by hand.

LOCATING AN UNREADABLE ROW IS OUT OF BAND, and that is a real limitation rather than an oversight to be discovered. Unreadable is a count; this package has no logger and no channel to report a row's identity through, and adding one is public surface a later task should design rather than something to bolt on here. What an operator has instead is the SHARD and the DUE BOUND the page was read at, which narrow the row to one namespace and one prefix of an ordered view. The row's stable key and ordering scope are in hand at both skip sites, so a reporting channel is cheap to add when something exists to receive it.

NEXTCURSOR is what keeps that skipping from becoming starvation. An unreadable row is stepped over by the provider's own continuation, which resumes from the tuple the page ended on, so a row left in place is passed rather than met again on the next page.

type DueGate ¶

type DueGate struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	Gate      sessionwire.GateProjection
}

DueGate is one gate whose deadline has passed, together with the session it belongs to. Gate is the projection read back from that session's durable catalog record, not from the intent: the intent is an index into the projection and never a second copy of it.

type DueGatePage ¶

type DueGatePage struct {
	Gates      []DueGate
	Remnants   []RemnantGateIntent
	Examined   int
	Unreadable int
	Limit      int

	// NextCursor resumes this shard's sweep after the position this page ended
	// at. It is empty when the view is exhausted.
	//
	// It is what turns the head-of-line hazard this reader used to have from
	// permanent into transient. A row that reports nothing — a remnant, or one
	// this reader could not read at all — is stepped over by the provider's own
	// continuation, which resumes from the frozen (due_at, stable_key,
	// ordering_scope) tuple the page ended on. So a blocking row is PASSED
	// rather than met again at the head of every page, and a gate behind it is
	// reached on the next page instead of never.
	//
	// A still-open gate past its deadline is deliberately NOT stepped over
	// permanently: it stays in the view, so every fresh pass reports it again,
	// because it is current due work that nothing has dealt with. It does not
	// block, because the continuation moves past it within a pass.
	NextCursor sessionwire.Cursor
}

DueGatePage is one bounded page of due gates together with what producing it cost.

Examined, Limit and Unreadable are defined on DueCommandPage, including why an unreadable row is skipped rather than failing the page and why locating one is out of band. They mean the same things here.

What is specific to this page is the distinction between the two ways a row can report no gate. A REMNANT was read and understood and can be retired, so it is reported in Remnants with the revision a retirement names; an UNREADABLE row is one nothing in this package can vouch for, so it is counted and left alone. Reporting the second as the first would aim a retirement at a row whose gate may well be open in a record nobody could decode.

type Envelope ¶

type Envelope struct {
	Kind EnvelopeKind

	EventID  sessionwire.EventID
	RecordID string

	Public  BodySlot
	Runtime BodySlot

	LeaseEpoch       uint64
	CommandID        sessionwire.CommandID
	RuntimeCommandID uuid.UUID
	CommandKind      string

	AttemptID           string
	AttemptJournalEpoch uint64
	DispositionKind     string
}

Envelope is one deterministic raw journal record. Public and Runtime remain separate so a public reader can select the public slot without inspecting or resolving private runtime bytes.

func DecodeEnvelope(frame []byte) (Envelope, error)

type EnvelopeError ¶

type EnvelopeError struct {
	Code  EnvelopeErrorCode
	Field string
	Cause error
}

EnvelopeError reports a bounded codec failure and preserves its cause without placing attacker-controlled cause text in Error().

func (e *EnvelopeError) Error() string

func (e *EnvelopeError) Unwrap() error

type EnvelopeErrorCode ¶

type EnvelopeErrorCode string

EnvelopeErrorCode is a stable machine-readable envelope failure reason.

const (
	EnvelopeErrorMalformed EnvelopeErrorCode = "malformed"
	EnvelopeErrorVersion   EnvelopeErrorCode = "version"
	EnvelopeErrorKind      EnvelopeErrorCode = "kind"
	EnvelopeErrorField     EnvelopeErrorCode = "field"
	EnvelopeErrorOrder     EnvelopeErrorCode = "order"
	EnvelopeErrorMissing   EnvelopeErrorCode = "missing"
	EnvelopeErrorInvalid   EnvelopeErrorCode = "invalid"
	EnvelopeErrorLength    EnvelopeErrorCode = "length"
	EnvelopeErrorTooLarge  EnvelopeErrorCode = "too-large"
	EnvelopeErrorDigest    EnvelopeErrorCode = "digest"
	EnvelopeErrorTrailing  EnvelopeErrorCode = "trailing"
)

type EnvelopeKind ¶

type EnvelopeKind uint8

EnvelopeKind identifies the closed set of raw journal record shapes.

const (
	EnvelopeKindPublicEvent       EnvelopeKind = 1
	EnvelopeKindRuntimeControl    EnvelopeKind = 2
	EnvelopeKindOpeningFence      EnvelopeKind = 3
	EnvelopeKindApplicationPrefix EnvelopeKind = 4
	// EnvelopeKindCommandDisposition is the runtime's own durable, bodiless
	// statement of what became of ONE authorized dispatch attempt.
	EnvelopeKindCommandDisposition EnvelopeKind = 5
)

type FindCommandApplicationRequest ¶

type FindCommandApplicationRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID
}

FindCommandApplicationRequest names one accepted command whose journal evidence a caller wants. It carries no positioning members: the correlation is a question about the whole of a session's history, and a caller that could bound the walk could bound away the evidence.

type GetCatalogEntryRequest ¶

type GetCatalogEntryRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

GetCatalogEntryRequest reads one session's authoritative catalog record.

type GetCommandRequest ¶

type GetCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID
}

GetCommandRequest reads one accepted command by its public identity.

type GetDispositionCommandRequest ¶ added in v0.5.0

type GetDispositionCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID
}

GetDispositionCommandRequest names one command in the disposition namespace.

type GetHostRegistrationRequest ¶

type GetHostRegistrationRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

GetHostRegistrationRequest reads one session's current route.

type GetObjectMetadataRequest ¶ added in v0.4.0

type GetObjectMetadataRequest struct {
	TenantID     sessionwire.TenantID
	SessionID    sessionwire.SessionID
	ExpectedKind ObjectKind
	Reference    sessionwire.ObjectReference
}

GetObjectMetadataRequest resolves one logical reference in a caller-authorized tenant/session scope and an explicit semantic kind.

type GetObjectRequest ¶

type GetObjectRequest struct {
	TenantID     sessionwire.TenantID
	SessionID    sessionwire.SessionID
	ExpectedKind ObjectKind
	Metadata     sessionwire.ObjectMetadata
}

GetObjectRequest names a verified object and the semantic kind the caller is authorized to consume.

type GetReconciliationClaimRequest ¶

type GetReconciliationClaimRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

GetReconciliationClaimRequest reads one session's current claim.

type GetSessionPointerRequest ¶

type GetSessionPointerRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

GetSessionPointerRequest reads one session's current pointer of one role.

type HostAdvertisement ¶

type HostAdvertisement struct {
	InternalEndpoint  sessionwire.InternalEndpoint
	IsolationClass    sessionwire.HostIsolationClass
	Accepting         bool
	AvailableCapacity uint64

	// ExpiresAt is the promise the Host makes about its next heartbeat, and it
	// is the row's due time. It lives on the advertisement rather than on the
	// record because a withdrawn row has no next heartbeat to promise: putting
	// it here is what makes "withdrawn implies not due" a statement about the
	// record's SHAPE instead of a rule someone has to remember.
	ExpiresAt time.Time
}

HostAdvertisement is the offered half of a Host target row: everything a Factory needs to decide whether to place a NEW session on this Host, and nothing that would let it claim an existing one.

It is a separate pointer member rather than a group of optional fields, and that is what makes withdrawal correct BY CONSTRUCTION rather than by convention. A withdrawn row has no advertisement, and "no advertisement" is one nil rather than an enumeration of five zero values that a sixth member would silently escape — and, more importantly here, both derived views read that one nil, so a withdrawn row cannot be ranked and cannot be due.

type HostRegistration ¶

type HostRegistration struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch uint64

	ObservedAt time.Time
	ExpiresAt  time.Time

	// Route is nil exactly when this registration is a released tombstone.
	Route *HostRoute
}

HostRegistration is the authoritative durable record of where one session is currently running, and of the lease epoch that fact was observed under.

It is an EXPIRING ROUTING HINT over a PERMANENT FENCE, and those two halves have opposite lifetimes:

• The route expires. A reader past ExpiresAt must treat the registration as absent, because the Host that published it may have died at any instant after ObservedAt and nothing will tell this record about it.
• LeaseEpoch does not expire, ever. It is the high-water mark that refuses a superseded Host's write, and it is the reason an expired registration and a released one are RETAINED rather than deleted. Dropping the row would drop the fence, and the next write from a lease that has already lost the session would be admitted.

A nil Route is the released tombstone: the registration a graceful shutdown leaves behind. It carries the fence and nothing else, so no reader can route to it however its timestamps read.

The accumulation that follows is intentional and affordable: one small, permanent row per session that has ever been registered, never listed, never ranked, never due, and never read except by name. The reader cost is nil, which is what makes permanence the right answer rather than a debt.

CARRY-FORWARD CONTRACT for whoever adds retention: THE ONLY SAFE REAPER IS ONE THAT REMOVES THE SESSION'S WHOLE SCOPE AT ONCE — this row, its catalog record, its journal, its commands, and its collision witnesses — because deleting this row ALONE destroys the fence while leaving the session registrable, which is precisely the state the retention exists to prevent. A sweep that walks record kinds independently and reclaims the cheapest one first will reach this one first, and it must not.

WHAT THIS RECORD OWNS, AND WHAT THE CATALOG OWNS. Three members appear in both records, and in every case the catalog's is Factory-authored DESIRED state or a durable status projection while this one's is the Host's OBSERVED answer:

• Placement. CatalogRecord.DesiredPlacement is what a Factory ASKED for under its own revision/idempotency CAS. HostRoute.Placement is the admission model the session is actually running under. The two disagree for the whole interval between a desired change and its reconciliation, and a router that used the desired value during that interval would bind to a Host that is not serving the session.
• Residency. CatalogRecord.Residency is the session's last known status, which is what a picker renders and which must survive this record's expiry. HostRoute.Residency is the ROUTABLE residency: it is only ever read together with the route it qualifies, and it disappears with it. A session whose registration has expired is cold no matter what the catalog's projection last said, which is exactly the statement the catalog cannot make because it does not expire.
• RuntimeCompatibilityID and AgentID. The catalog's are what the session was created for and what a Factory later desired; the route's are what the running Host actually loaded. A Factory reusing a route must check the observed one, because a Host that has been restarted onto a newer runtime is not compatible with a session pinned to the older one.

LeaseEpoch appears in both too, and there the duplication is real and deliberate: each record carries the epoch ITS OWN writes are fenced at. Neither is derived from the other, neither is read to decide the other, and the two advance independently — a Host that updates its catalog projection without refreshing its registration leaves this record at the older epoch, which is correct, because the fence protects the record it lives on.

func (r HostRegistration) Observation() (sessionwire.HostLinkRegistryObservation, error)

type HostRegistrationEntry ¶

type HostRegistrationEntry struct {
	Registration HostRegistration
	Revision     uint64
}

HostRegistrationEntry is a registration together with the revision a later compare-and-swap names.

The provider's immutable acceptance order is deliberately NOT exposed, for the reason CatalogEntry's is not: a session's position in a stream of registrations is not a fact any caller acts on. Commands expose theirs because arrival order is the thing consumers sort by.

type HostRoute ¶

type HostRoute struct {
	HostID         sessionwire.HostID
	HostGeneration uint64

	AgentID                sessionwire.AgentID
	RuntimeCompatibilityID string

	Placement        sessionwire.HostPlacement
	InternalEndpoint sessionwire.InternalEndpoint
	Residency        sessionwire.SessionResidency
	Accepting        bool
}

HostRoute is the routable half of a Host registration: everything a Factory needs to establish a HostLink to the process currently holding the session.

It is a separate pointer member rather than a group of optional fields on the record, and that is what makes the tombstone below correct BY CONSTRUCTION. A released registration has no route, and "no route" is one nil rather than an enumeration of eight zero values that a ninth member would silently escape.

Every member is OBSERVED — what the Host reports it is actually doing — which is the whole difference from the catalog record. See HostRegistration.

type HostTarget ¶

type HostTarget struct {
	Key HostTargetKey

	HostID         sessionwire.HostID
	HostGeneration uint64

	ObservedAt time.Time

	// Advertisement is nil exactly when this row is withdrawn.
	Advertisement *HostAdvertisement
}

HostTarget is one Host's current advertisement for one target: the durable row behind a placement decision.

IT IS CAPACITY, NOT AUTHORITY, AND THAT BOUNDARY IS STRUCTURAL. This record names no tenant, no session, and no lease epoch — there is nowhere in it to spell one — and the projection it publishes to a reader, core's HostLinkCapacityReport, has no such member either. A Factory that has read this row knows a Host said it could take work; it knows nothing whatsoever about who owns any session. The record that answers THAT question is HostRegistration, whose LeaseEpoch is the fence, and no code path leads from this file to it. TestHostTargetsCannotSpellSessionOwnership pins the structural half of that claim so it cannot decay into prose.

HostGeneration is on the record rather than on the advertisement because a withdrawn row keeps it. It is a WRITE-ORDERING high-water mark over one row, and the distinction from the registry's epoch is worth stating precisely, because the two would otherwise look like the same mechanism:

• HostID is part of this row's identity, so the only writers of this row are incarnations of ONE Host. The generation orders that Host's own writes against each other and against nothing else.
• What it prevents is a liveness fault, not a safety one. A restarted Host publishes at a higher generation; a heartbeat or a drain still in flight from the dead incarnation would otherwise overwrite live capacity with a dead process's view of it, and the target would flap.
• It confers NO right over any session. A Host holding the highest generation on a capacity row has proven only that it is the newest incarnation of itself.

The rows are removable, which is the other half of the difference from the registry. See hostTargetDue for what removes one and why nothing here is retained forever.

func (t HostTarget) Report() (sessionwire.HostLinkCapacityReport, error)

type HostTargetEntry ¶

type HostTargetEntry struct {
	Target   HostTarget
	Revision uint64
}

HostTargetEntry is one advertisement together with the revision a later compare-and-swap names.

It is returned to the HOST that owns the row — from a publish, a drain, and the reconciler's own bookkeeping — and deliberately not to a placement reader, which receives projections instead. See HostTargetPage.

The provider's immutable acceptance order is not exposed, for the reason CatalogEntry's is not: a row's position in a stream of advertisements is not a fact any caller acts on.

type HostTargetError ¶

type HostTargetError struct {
	Code       HostTargetErrorCode
	Field      string
	Generation uint64
	Revision   uint64
	Cause      error
}

HostTargetError is a typed, redacted Host target directory failure. Field names the offending input or stage and never carries a provider name, a key, or a record payload.

Revision is populated only for HostTargetErrorConflict, carrying the value that is itself the answer, as the other record kinds do for that code.

Generation is populated only for HostTargetErrorGeneration, carrying the high-water mark that refused the write so a superseded incarnation learns it has been superseded rather than retrying forever.

There is deliberately no epoch member of any kind. A caller cannot obtain a lease epoch from this type because there is no lease epoch in this record to obtain.

func (e *HostTargetError) Error() string

func (e *HostTargetError) Unwrap() error

type HostTargetErrorCode ¶

type HostTargetErrorCode string

HostTargetErrorCode classifies a Host target directory failure.

It is its own vocabulary rather than the registry's, and the reason is not merely that they are separate aggregates. It is that a caller MUST NOT be able to write one handler for both. A RegistryError is the public account of who is running a session; a HostTargetError is the public account of who might be able to take one. Sharing a type would let a caller branch on "expired" without knowing which of those two questions it had just asked, and the whole discipline of this record is that capacity is never authority.

The codes are the ones the ordinary vocabulary supplies, with three that need their reasons stated:

• Withdrawn — the row exists and offers no capacity. It is what a drain leaves and what the reconciler writes; it is not an error in a caller and it is not a claim about any session.
• Generation — the caller named a Host generation BELOW the row's committed high-water mark, so the write comes from a superseded incarnation of that same Host. It is deliberately NOT called Epoch: RegistryErrorEpoch means a lease has provably lost a SESSION, and a code sharing that name would invite a reader to believe this record fences ownership. It does not. See HostTarget.
• Cursor — a page token this store did not issue for this exact target. The walk restarts from the first page; nothing is wrong with the store.

Conflict means a lost revision compare-and-swap and nothing else — re-read and retry — which is the meaning it has for every other record kind here.

TWO ERROR TYPES REACH A CALLER OF THIS RECORD, and a consumer must handle both. Validating a target reports *InvalidIdentityError for AgentID, because that is what every identity derivation in this package reports for a sessionwire identity, while the opaque runtime id and the placement enum report *HostTargetError — so one malformed request surfaces as either type depending on which member is wrong. That is the package's convention rather than this record's choice, and it is written down here because this record is the first one a Host or a Factory calls.

const (
	HostTargetErrorInvalid    HostTargetErrorCode = "invalid"
	HostTargetErrorNotFound   HostTargetErrorCode = "not_found"
	HostTargetErrorWithdrawn  HostTargetErrorCode = "withdrawn"
	HostTargetErrorDeleted    HostTargetErrorCode = "deleted"
	HostTargetErrorIdentity   HostTargetErrorCode = "identity"
	HostTargetErrorGeneration HostTargetErrorCode = "generation"
	HostTargetErrorConflict   HostTargetErrorCode = "conflict"
	HostTargetErrorCursor     HostTargetErrorCode = "cursor"
	HostTargetErrorUnknown    HostTargetErrorCode = "unknown"
	HostTargetErrorBackend    HostTargetErrorCode = "backend"
	HostTargetErrorMalformed  HostTargetErrorCode = "malformed"
	HostTargetErrorVersion    HostTargetErrorCode = "version"
	HostTargetErrorTooLarge   HostTargetErrorCode = "too_large"
)

type HostTargetKey ¶

type HostTargetKey struct {
	AgentID                sessionwire.AgentID
	RuntimeCompatibilityID string
	Placement              sessionwire.HostPlacement
}

HostTargetKey is the target half of an advertisement's identity: the (agent, runtime, placement) triple a Host offers capacity FOR.

It is a struct rather than three parameters because it is threaded through the derivation, the request types, and the page, and because the whole triple is what selects a provider scope. A caller that dropped one member would otherwise be selecting a different target while looking correct.

This is derived capacity, not a definition catalogue. Nothing here says an agent or a runtime EXISTS; it says a Host is currently willing to serve one.

type HostTargetPage ¶

type HostTargetPage struct {
	Hosts             []sessionwire.HostLinkCapacityReport
	LapsedSkipped     int
	UnreadableSkipped int
	NextCursor        sessionwire.Cursor
}

HostTargetPage is one bounded page of live capacity for one target.

Hosts carries core's capacity reports rather than this package's entries, and that is the capacity/authority boundary made structural on the read side. A HostLinkCapacityReport has no tenant member, no session member, and no epoch member, so a Factory holding one cannot mistake it for a claim on anything — there is nothing in it to mistake. The revision a compare-and-swap needs goes to the HOST that owns the row, through publish and drain, and a placement reader has no business rewriting another process's advertisement.

TWO COUNTS say why a page is shorter than its limit, and neither is a diagnostic afterthought. A page that silently returned fewer entries would leave a caller unable to tell "this target has little capacity" from "this target is full of rows I passed over", and the two causes want different responses:

• LapsedSkipped counts rows whose heartbeat promise had already lapsed at the store's clock. Such a row is still RANKED, so it still occupies a position in every later page; a nonzero count means the directory is owed a ReconcileHostTargets pass, which is the only thing that clears it.
• UnreadableSkipped counts rows this build could not decode, or that disagreed with the filing they were found under.

THE RULE FOR AN UNREADABLE ROW IS STATED HERE AND NOWHERE ELSE, because a rule restated in five places is a rule that drifts in four of them. Such a row is skipped rather than FAILING THE PAGE, and that is load-bearing rather than lenient: nothing in this package ever rewrites a row it cannot read — a newer writer may have produced it — so the row is permanent, and a reader that failed the page on one would take every Host serving that target out of service for as long as it existed, with no recovery path anywhere in the system. Skipping keeps the newer writer's row untouched and starts publishing it the instant a reader that understands it asks; the count keeps the condition visible; and README.md records that a genuinely corrupt row has no in-band repair at all. ListDueGates and ListSessions obey the same rule for the same reason.

A page may therefore contain fewer than Limit entries while still issuing a continuation. A caller that wants a specific number of candidates pages until NextCursor is empty; it must not treat a short page as the end of the target.

type HostTargetReconcileResult ¶

type HostTargetReconcileResult struct {
	Scanned    int
	Withdrawn  int
	StillLive  int
	Contended  int
	Unreadable int
	Unverified int

	Exhausted  bool
	NextCursor sessionwire.Cursor
}

HostTargetReconcileResult accounts for every row one sweep scanned. The five outcomes sum to Scanned, which is asserted rather than assumed: a sweep that silently dropped a row would otherwise look like a sweep that had nothing to do.

• Withdrawn — the row's stored expiry had genuinely lapsed and the sweep removed it from both views.
• StillLive — the row named by the due page had not actually lapsed when the sweep revalidated its stored expiry. The due view is weakly consistent and a Host may have heartbeated since; this is the count of rows the revalidation SAVED.
• Contended — the compare-and-swap lost to a concurrent write, or the row moved out from under it. Nothing was decided and a later sweep will see the row again if it is still lapsed.
• Unreadable — the row could not be decoded, or disagreed with the filing it was found under. The sweep steps over it and does NOT rewrite it, for the reason HostTargetPage gives. A nonzero count is an operator's signal, not a transient: nothing retires such a row.
• Unverified — the compare-and-swap COMMITTED and the provider's reply then failed this package's checks on it. The withdrawal is durable, so the row is handled and no later sweep will revisit it, but this sweep cannot say that it is: the reply it was given does not describe what it wrote. It is its own outcome rather than folded into Contended, which means the opposite — that nothing was decided.

Exhausted reports whether the sweep reached the end of the due view within its page budget. NextCursor is nonempty exactly when it did not, and a caller that wants the whole view hands it back — see ReconcileHostTargetsRequest for why that is a correctness property rather than a convenience.

type InboxEntry ¶

type InboxEntry struct {
	Record        InboxRecord
	Revision      uint64
	AcceptedOrder uint64
}

InboxEntry is a command record together with the provider state a caller needs: the revision a later compare-and-swap names, and the immutable acceptance order.

AcceptedOrder is exposed, and CatalogEntry's order deliberately is not. The difference is that a catalog record's order means nothing to anyone — a session's position in a creation stream is not a fact any caller acts on — while a command's acceptance order is the durable arrival order of commands within a session, which consumers sort a bounded ListOrdered page by and which a retry must receive unchanged as evidence that it is the same acceptance.

It is an OPAQUE COMPARISON KEY and nothing else:

• It is strictly increasing within one session's order scope: once a command has order 12, no command in that session becomes newly observable at 11.
• It is NOT contiguous and NOT one-based. A provider may allocate from a JetStream stream sequence or a shared SQL sequence, so a session's first command can have order 5000 and its second 9000. Nothing may derive a count, a position, or "the next" order from it.
• It is not comparable across sessions or tenants. Two sessions' orders come from different scopes and may interleave arbitrarily.

func (e InboxEntry) CommandStatus() (sessionwire.CommandStatus, error)

type InboxError ¶

type InboxError struct {
	Code     InboxErrorCode
	Field    string
	Epoch    uint64
	Order    uint64
	Revision uint64
	Cause    error
}

InboxError is a typed, redacted command failure. Field names the offending input or stage and never carries a provider name, a key, or any part of the command's private payload.

Revision is populated only for InboxErrorConflict, carrying the value that is itself the answer, as CatalogError does for that code.

Epoch and Order are the two consumption-cursor high-water marks, and BOTH are populated for BOTH of the two fence codes — InboxErrorEpoch and InboxErrorOrder — rather than one each. That is deliberate and is the rule PointerError already follows: a caller that has to raise its epoch will have to satisfy the position too, and one round trip is enough to learn both. Epoch is additionally populated for InboxErrorEpoch on every other path that fences an epoch. Neither member means anything for any other code.

func (e *InboxError) Error() string

func (e *InboxError) Unwrap() error

type InboxErrorCode ¶

type InboxErrorCode string

InboxErrorCode classifies a durable command record failure.

It is the inbox's own vocabulary rather than the catalog's, and the reason is ownership. Gates reuse CatalogError because a gate IS catalog state: the projection lives in the catalog record and the deadline intent is an index into it, so a gate failure is a statement about that record. A command is a separate aggregate — its own namespace, its own record, its own identity, its own lifecycle — and admission never reads or writes a session's catalog record. A caller branching on an inbox failure should not have to match the catalog's type to learn that its command was not stored, and the command lifecycle's later states need failures the catalog has no business naming.

CommandMismatch is definite and caller-caused: one command id was reused for a DIFFERENT command, and the stored command is untouched. No retry helps — the caller must mint a new id or send the command it originally sent.

It is deliberately NOT called "conflict", and the omission is the point. This file already spells "conflict" two ways. CatalogErrorConflict means a lost revision compare-and-swap: recoverable, provider-caused, carrying the actual revision, and explicitly inviting a re-read and a retry. ObjectErrorConflict means a key already holding DIFFERENT CONTENT, which is the near-twin of what a reused command id is — so a reader who met that one first would reasonably expect "conflict" here and get the catalog's recovery advice instead.

The tie goes to the catalog's meaning because of what this record IS: an OrderedIndex row has a Revision, so the command transition machine will compare-and-swap it and will need a name for losing that race. The object aggregate never will. InboxErrorConflict therefore carries the catalog's meaning exactly — a lost revision compare-and-swap, recoverable, reporting the actual revision, inviting a re-read and a retry — and the caller-caused content case takes a name that cannot be mistaken for either neighbour.

Unknown means the mutation's outcome could not be resolved at all, so the caller learns nothing about what is stored and must retry the same identity to find out.

Identity means a stored record disagreed with the identity it was filed under or asked for. It is not a caller error and not a conflict: it means the provider's answer cannot be trusted, and no retry of the caller's fixes it.

The transition machine adds the rest, and each one names a DIFFERENT recovery so that a caller can branch without reading prose:

• NotFound — no command has ever been admitted under that identity. The caller is asking about something it never accepted.
• Conflict — the record moved under the caller. Re-read and decide again. Revision carries what the record is at now when the store could see it.
• Epoch — the caller named a lease epoch BELOW the epoch the record's claim was taken under. That lease has provably been superseded and must not retry under the same epoch; Epoch carries the committed high-water mark, as CatalogErrorEpoch does.
• ClaimHeld — a LIVE claim is held on this command and is not provably the caller's. It cannot say "someone else": a claim records the lease epoch it was taken under and no claimant identity, so two writers under one epoch are indistinguishable to it. That matters for the likeliest recipient, which is not a rival but a claimer meeting its OWN live claim: a claim cannot be renewed, so a caller that wants more time must enter applying before its claim lapses, and waiting for the claim to expire — the advice that fits a rival — is the one thing that caller must not do.
• ClaimLost — the caller does not hold the live claim the transition requires, and Field says which of the two situations it is. "lease_epoch" means the claim is held under another epoch, so the caller never held this command; "claim" means the caller's own claim lapsed. Both are answered by claiming again, which the apply deadline may no longer permit, but they read very differently to an operator: the first is a writer working on a command that is not its own, the second is a writer that was too slow.

ClaimHeld and ClaimLost are the pair the journal already spells for lease ownership, and they mean the corresponding two things here.

• Deadline — a NEW claim was attempted at or after the command's apply deadline. No retry helps: the command is now the deadline reconciler's, and the caller learns its answer by reading the terminal record.
• State — the record is in a state this transition has no edge out of, and the caller had a current revision when it asked. It is a caller mistake about the machine rather than a race.
• Evidence — the journal does not support the settlement asked for, and Field says which question it failed. "application" means the correlation did not establish that no effect committed — either one did, or the evidence is not readable — so the command must be finished or left alone rather than rejected. "result" means a recovering successor named a terminal result that is not the effect its prefix is correlated with. "applying_lease" means the lease holding the record's claim is not yet provably fenced out of the journal, so it could still commit the effect this settlement would orphan. None of the three is a race and none is answered by retrying the same call unchanged: the first two are permanent for the journal as it stands, and the third becomes settleable only once a later lease has opened the stream.
• Terminal — the command's outcome is already settled. It is separate from State because it is the one state failure that is PERMANENT and that carries an answer: a caller meeting it should read the record and report the outcome rather than re-deciding anything.

const (
	InboxErrorInvalid         InboxErrorCode = "invalid"
	InboxErrorCursor          InboxErrorCode = "cursor"
	InboxErrorCommandMismatch InboxErrorCode = "command_mismatch"
	InboxErrorNotFound        InboxErrorCode = "not_found"
	InboxErrorDeleted         InboxErrorCode = "deleted"
	InboxErrorIdentity        InboxErrorCode = "identity"
	InboxErrorConflict        InboxErrorCode = "conflict"
	InboxErrorEpoch           InboxErrorCode = "epoch"
	InboxErrorOrder           InboxErrorCode = "order"
	InboxErrorClaimHeld       InboxErrorCode = "claim_held"
	InboxErrorClaimLost       InboxErrorCode = "claim_lost"
	InboxErrorDeadline        InboxErrorCode = "deadline"
	InboxErrorState           InboxErrorCode = "state"
	InboxErrorEvidence        InboxErrorCode = "evidence"
	InboxErrorTerminal        InboxErrorCode = "terminal"
	InboxErrorUnknown         InboxErrorCode = "unknown"
	InboxErrorBackend         InboxErrorCode = "backend"
	InboxErrorMalformed       InboxErrorCode = "malformed"
	InboxErrorVersion         InboxErrorCode = "version"
	InboxErrorTooLarge        InboxErrorCode = "too_large"
)

type InboxRecord ¶

type InboxRecord struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	RuntimeCommandID RuntimeCommandID
	Kind             CommandKind

	Payload    []byte
	PayloadRef sessionwire.ObjectReference

	AcceptedAt    time.Time
	ApplyDeadline time.Time

	State     InboxState
	Claim     CommandClaim
	Result    CommandResult
	Rejection *sessionwire.ErrorDetail
}

InboxRecord is the authoritative durable record of one accepted command.

Payload and PayloadRef are PRIVATE: they are the command's body, they are never part of a public projection, and no failure this package returns carries either of them. At most one of the two is set — an inline body up to MaxInboxPayloadBytes, or a reference to an object persisted first — and neither is set for a command that has no body. They are also IMMUTABLE for the life of the record, as Kind is: emptying or rewriting one turns every later retry of the command into a permanent mismatch — see sameCommandAs.

The acceptance order is deliberately NOT a member here. It is allocated by the provider at Create and is therefore not part of the bytes this record encodes; it is reported on InboxEntry, where its origin is unambiguous.

type InboxState ¶

type InboxState string

InboxState is the durable processing state of one accepted command.

The transitions between them — including which writer may make each one, what a claim epoch fences, and what a terminal CAS must set — are inbox_claim.go's. Admission produces InboxStatePending and never anything else. What each state must and must not carry is validateInboxState, below, because that is a property of the stored record rather than of the operation that wrote it.

const (
	InboxStatePending  InboxState = "pending"
	InboxStateClaimed  InboxState = "claimed"
	InboxStateApplying InboxState = "applying"
	InboxStateApplied  InboxState = "applied"
	InboxStateRejected InboxState = "rejected"
)

type InvalidBackendError ¶

type InvalidBackendError struct {
	Component string
}

InvalidBackendError reports a storage component or required capability that was not wired at Open. Component is one of Composite, Ledger, Leaser, KV, OrderedIndex, Blobs, or BlobReaderLifecycle.

func (e *InvalidBackendError) Error() string

type InvalidBackgroundWorkError ¶

type InvalidBackgroundWorkError struct{}

InvalidBackgroundWorkError reports a nil internal background work function.

func (*InvalidBackgroundWorkError) Error() string

type InvalidIdentityError ¶

type InvalidIdentityError struct {
	Field string
	Cause error
}

InvalidIdentityError identifies which opaque identity failed validation without retaining or rendering its value.

func (e *InvalidIdentityError) Error() string

func (e *InvalidIdentityError) Unwrap() error

type InvalidLimitError ¶

type InvalidLimitError struct {
	Field string
	Value int64
	Min   int64
	Max   int64
}

InvalidLimitError reports a limit outside its inclusive valid range.

func (e *InvalidLimitError) Error() string

type InvalidOptionError ¶

type InvalidOptionError struct {
	Field string
	Cause error
}

InvalidOptionError reports an invalid Open option. When Cause is non-nil it is preserved for errors.Is and errors.As.

func (e *InvalidOptionError) Error() string

func (e *InvalidOptionError) Unwrap() error

type JournalEpoch ¶ added in v0.6.0

type JournalEpoch uint64

JournalEpoch is a runtime grant in a session's bound agent journal. It is meaningful only with that journal's lease namespace and the session binding that resolves it, and it must never be compared with, or assigned from, a ResidencyEpoch: the two are different authorities over different stores. The runtime returns this value from its own journal ownership capability; a Host may not copy its residency epoch into it.

type JournalError ¶

type JournalError struct {
	Code  JournalErrorCode
	Field string
	Epoch uint64
	Cause error
}

JournalError is a typed, redacted journal failure. Field names the offending input or stage and never carries a provider name, key, or record payload. Epoch is populated only where a fencing epoch is itself the answer — the live holder's epoch for lease_held, this writer's epoch for lease_lost.

func (e *JournalError) Error() string

func (e *JournalError) Unwrap() error

type JournalErrorCode ¶

type JournalErrorCode string

JournalErrorCode classifies a journal ownership, append, or read failure.

Fenced and Unknown are deliberately distinct outcomes of one CAS append. Fenced is definite — a successor's record occupies the contested sequence, so this writer has provably lost the stream. Unknown means the outcome could not be resolved at all, so the writer's own tip is no longer trustworthy. Both end the writer permanently; only Fenced asserts that someone else won.

const (
	JournalErrorInvalid   JournalErrorCode = "invalid"
	JournalErrorLeaseHeld JournalErrorCode = "lease_held"
	JournalErrorLeaseLost JournalErrorCode = "lease_lost"
	JournalErrorFenced    JournalErrorCode = "fenced"
	JournalErrorUnknown   JournalErrorCode = "unknown"
	JournalErrorClosed    JournalErrorCode = "closed"
	JournalErrorBackend   JournalErrorCode = "backend"
	JournalErrorIntegrity JournalErrorCode = "integrity"
	JournalErrorTooLarge  JournalErrorCode = "too_large"
	JournalErrorCursor    JournalErrorCode = "cursor"
)

type JournalWriter ¶

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

JournalWriter is one epoch-fenced single-writer grant over a session's journal. It is safe for concurrent use; every append is serialized.

Ownership algorithm. OpenJournal acquires a lease grant, reads the tip exactly once, and appends an opening fence at precisely that tip stamped with the grant's epoch. If that CAS conflicts the grant is spent: OpenJournal releases the lease and returns a typed conflict, and the caller may acquire a fresh, strictly higher epoch and reopen. It deliberately does NOT refresh the tip and retry, because a retry loop lets a writer silently reorder itself behind records it never observed.

After a successful open the writer tracks only its own committed sequence and CASes every later append on it. It never re-reads the tip, so a successor's opening fence permanently fails this writer at its next append. An append whose outcome could not be resolved is equally terminal: rather than re-read and rebase onto whatever is now durable, the writer latches the failure and refuses every later append.

func (w *JournalWriter) Append(ctx context.Context, env Envelope) (uint64, error)

func (w *JournalWriter) Close(ctx context.Context) error

func (w *JournalWriter) Epoch() uint64

func (w *JournalWriter) Sequence() uint64

type KeyspaceError ¶

type KeyspaceError struct {
	Code  KeyspaceErrorCode
	Cause error
}

KeyspaceError reports a fail-closed layout or physical-key failure. Cause is available to errors.Is/As, while Error deliberately omits provider and raw ID details.

func (e *KeyspaceError) Error() string

func (e *KeyspaceError) Unwrap() error

type KeyspaceErrorCode ¶

type KeyspaceErrorCode string

KeyspaceErrorCode is a stable machine-readable keyspace failure class.

const (
	KeyspaceBackend          KeyspaceErrorCode = "backend"
	KeyspaceMarkerMalformed  KeyspaceErrorCode = "marker_malformed"
	KeyspaceLayoutMismatch   KeyspaceErrorCode = "layout_mismatch"
	KeyspaceMarkerAmbiguous  KeyspaceErrorCode = "marker_ambiguous"
	KeyspaceBindingNotFound  KeyspaceErrorCode = "binding_not_found"
	KeyspaceBindingAmbiguous KeyspaceErrorCode = "binding_ambiguous"
	KeyspaceScopeInvalid     KeyspaceErrorCode = "scope_invalid"
	KeyspaceHashCollision    KeyspaceErrorCode = "hash_collision"
	KeyspaceLegacyTenant     KeyspaceErrorCode = "legacy_tenant"
	KeyspaceLegacySession    KeyspaceErrorCode = "legacy_session"
)

type Limits ¶

type Limits struct {
	MaxPageSize int
}

Limits contains Store-wide ceilings. MaxPageSize bounds every provider page requested by SessionStore; individual operations may request a smaller page.

func DefaultLimits() Limits

type ListCompatibleHostsRequest ¶

type ListCompatibleHostsRequest struct {
	Key HostTargetKey

	// Cursor is a token a previous page of THIS target issued. It is opaque:
	// retain it and hand it back, but do not parse it or derive ordering,
	// identity, or authority from it. Possessing one authorizes nothing, and a
	// cursor this store did not issue for this target is refused with
	// HostTargetErrorCursor, which means the walk restarts from the first page
	// rather than that anything is wrong with the store.
	Cursor sessionwire.Cursor

	// Limit is the page's record ceiling. Zero means the store's configured
	// page size. It bounds the rows the PROVIDER returns, not the reports this
	// page publishes; see HostTargetPage.
	Limit int
}

ListCompatibleHostsRequest positions one bounded page of the Hosts currently offering capacity for one target, most free capacity first.

type ListDueCommandsRequest ¶

type ListDueCommandsRequest struct {
	Shard         int
	DueAtOrBefore time.Time
	Limit         int
	Cursor        sessionwire.Cursor
}

ListDueCommandsRequest positions one bounded page of one shard's outstanding commands.

Shard names the control shard to read and must be below the store's ControlShards. A caller sweeps by visiting every shard round-robin; the store deliberately does not do that for it, because a replica that swept every shard in one call would hold the whole deployment's reconciliation in one request's latency and one caller's failure.

DueAtOrBefore is the inclusive wall-clock bound and is the FIRST page's query. A continuation carries its own bound, so a resumed request must leave this zero: presenting both would be two answers to one question, and silently preferring either is how a resumed sweep starts querying a bound it was never bound to.

type ListDueDispositionCommandsRequest ¶ added in v0.5.0

type ListDueDispositionCommandsRequest struct {
	Shard         int
	DueAtOrBefore time.Time
	Limit         int
	Cursor        sessionwire.Cursor
}

ListDueDispositionCommandsRequest pages one disposition-only control shard. Supply DueAtOrBefore on the first request or Cursor on continuations, never both. The cursor retains the original bound and cannot cross protocol kinds.

type ListDueGatesRequest ¶

type ListDueGatesRequest struct {
	// Shard names the control shard to read and must be below the store's
	// ControlShards. A caller sweeps by visiting every shard round-robin.
	Shard int

	// DueAtOrBefore is the inclusive wall-clock bound and is the FIRST page's
	// query. A continuation carries its own bound, so a resumed request must
	// leave this zero; see dueGatePosition.
	DueAtOrBefore time.Time

	// Limit is the page's record ceiling. Zero means the store's configured
	// page size.
	Limit int

	// Cursor resumes a sweep of this shard from the position a previous page
	// ended at. It is opaque and is bound to this cursor kind and this shard.
	Cursor sessionwire.Cursor
}

ListDueGatesRequest positions one bounded page of one control shard's gates whose deadline has passed. It is cross-tenant rather than tenant-scoped, because the due view is: see gateNamespace, and see shards.go for what a shard is and for what "service-only" does and does not mean here.

type ListSessionDispositionCommandsRequest ¶ added in v0.7.0

type ListSessionDispositionCommandsRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	AfterOrder uint64
	Limit      int
}

ListSessionDispositionCommandsRequest positions one bounded page of ONE session's disposition inbox in immutable acceptance order.

AfterOrder is an EXCLUSIVE lower bound and is the caller's. Zero starts at the head of the session's stream, which is the provider's own spelling and is unambiguous because no provider allocates order zero. A caller resumes by passing the previous page's NextAfterOrder, or its own durable cursor.

THE BOUND IS THE CALLER'S AND THE ORDERING IS THE STORE'S. A consumer that sorted a page for itself would be inferring an order rather than reading one, and the order it inferred would be its own opinion about rows the provider had already ranked. Nothing in this request selects an order, a direction or a sort key, because there is exactly one and it is the provider's immutable acceptance order.

There is no Cursor member, deliberately. A page token would be a second way to say the one thing AfterOrder says, and the two would have to be reconciled on every continuation — which is the failure ListDueDispositionCommandsRequest documents at length for a query whose bound genuinely cannot be restated. This one's can: the bound IS a row's order, and a caller that has the row has the bound.

type ListSessionsRequest ¶

type ListSessionsRequest struct {
	TenantID sessionwire.TenantID

	// Cursor is a token a previous page of THIS tenant issued. It is opaque:
	// retain it and hand it back, but do not parse it or derive ordering,
	// tenancy, or authority from it. Possessing one authorizes nothing — a
	// caller must authorize TenantID on its own — and a cursor this store did
	// not issue for this tenant is refused with CatalogErrorCursor, which
	// means the walk restarts from the first page rather than that anything is
	// wrong with the store.
	Cursor sessionwire.Cursor

	// Limit is the page's record ceiling. Zero means the store's configured
	// page size.
	Limit int
}

ListSessionsRequest positions one bounded recent-first page of a tenant's sessions. Cursor is a token a previous page issued; Limit is that page's record ceiling, and zero means the store's configured page size.

type LoadDispositionCommandCursorRequest ¶ added in v0.7.0

type LoadDispositionCommandCursorRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

LoadDispositionCommandCursorRequest reads one session's consumption cursor.

type ObjectError ¶

type ObjectError struct {
	Code  ObjectErrorCode
	Field string
	Cause error
}

ObjectError is a typed, redacted object operation failure. Field names the offending input or stage and never carries a provider path, key, or payload.

Terminating an object stream can produce more than one failure at once — the cause that ended the stream, a read error observed by a racing reader, and a provider Close error — and those are reported as an errors.Join tree, so a returned error may contain several *ObjectError values. The FIRST one found by errors.As is the primary classification: it is the failure that caused termination, and later ones are subsidiary consequences of it. A caller that genuinely needs every code can walk the tree itself through the `Unwrap() []error` that errors.Join returns; the package deliberately does not export a set extractor, because classifying on the primary cause is the supported contract and an exported extractor would freeze the join shape.

func (e *ObjectError) Error() string

func (e *ObjectError) Unwrap() error

type ObjectErrorCode ¶

type ObjectErrorCode string

ObjectErrorCode classifies redacted object operation failures.

Digest and Integrity are deliberately distinct: Digest means the caller's own metadata is self-inconsistent (its Digest field disagrees with the digest inside its ObjectID), while Integrity means bytes or a stored key did not match what the object identity promised.

const (
	ObjectErrorInvalid   ObjectErrorCode = "invalid"
	ObjectErrorSize      ObjectErrorCode = "size"
	ObjectErrorDigest    ObjectErrorCode = "digest"
	ObjectErrorSource    ObjectErrorCode = "source"
	ObjectErrorBackend   ObjectErrorCode = "backend"
	ObjectErrorConflict  ObjectErrorCode = "conflict"
	ObjectErrorIntegrity ObjectErrorCode = "integrity"
	ObjectErrorCanceled  ObjectErrorCode = "canceled"
	// MetadataUnavailable means the scoped immutable index has no record. The
	// bytes may still exist (for example, objects written before the index).
	ObjectErrorMetadataUnavailable ObjectErrorCode = "metadata_unavailable"
)

type ObjectKind ¶

type ObjectKind string

ObjectKind is a closed semantic class for immutable session objects.

const (
	ObjectKindJournalPublic       ObjectKind = "journal-public"
	ObjectKindJournalRuntime      ObjectKind = "journal-runtime"
	ObjectKindCommandPayload      ObjectKind = "command-payload"
	ObjectKindToolResult          ObjectKind = "tool-result"
	ObjectKindWorkspaceCheckpoint ObjectKind = "workspace-checkpoint"
	ObjectKindRuntimeCheckpoint   ObjectKind = "runtime-checkpoint"
	ObjectKindArtifact            ObjectKind = "artifact"
	ObjectKindAttachment          ObjectKind = "attachment"
	ObjectKindContinuation        ObjectKind = "continuation"
	ObjectKindRuntimeObject       ObjectKind = "runtime-object"
)

type OpenGateRequest ¶

type OpenGateRequest struct {
	TenantID   sessionwire.TenantID
	SessionID  sessionwire.SessionID
	LeaseEpoch uint64
	Gate       sessionwire.GateProjection
}

OpenGateRequest projects one gate as publicly open and records its absolute deadline. LeaseEpoch is the writing Host's grant epoch, compared against the record's committed high-water mark exactly as UpdateCatalogHostState's is: open gates are Host-owned state.

Gate.OpenedJournalSeq must name an event at or below the record's durable journal tip. A gate whose opening event is not yet durable is refused rather than stored, because a reader would otherwise be handed a page claiming an event its own tip says does not exist.

type OpenJournalRequest ¶

type OpenJournalRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

OpenJournalRequest names the session whose stream a writer wants to own.

type Option ¶

type Option func(*config) error

Option configures Open.

func WithClock(clock Clock) Option

func WithControlShards(shards int) Option

func WithDispositionEvidence(reader DispositionEvidenceReader) Option

func WithIOProviderOwnership(closer io.Closer) Option

func WithJournalDispositionEvidence() Option

func WithLegacySingleTenant(defaultTenant sessionwire.TenantID) Option

func WithLimits(limits Limits) Option

func WithLogger(logger *slog.Logger) Option

func WithProviderOwnership(closer ProviderCloser) Option

func WithShutdownTimeout(timeout time.Duration) Option

type PlacementIntent ¶

type PlacementIntent struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	AgentID                sessionwire.AgentID
	RuntimeCompatibilityID string

	Placement  sessionwire.HostPlacement
	Workload   DesiredWorkload
	Generation uint64
}

PlacementIntent is the complete Factory-authored answer to "what should exist for this session", and nothing else.

COMPLETE AS TO AUTHORSHIP, NOT AS TO SUFFICIENCY, and the difference decides whether a controller acting on one alone is correct. This is the only one of the record's three projections that drops State — Summary and Status both carry it — so an intent cannot say whether the session it describes is still alive. A controller holding only this could create a dedicated workload for a session that has ended. Read CatalogRecord.State, or Status(), from the SAME entry: one read of one record answers both questions, and taking them from one entry is what makes the pair consistent.

Excluding the observation is nonetheless right, and is this type's whole discipline — an intent that carried liveness would be a request and a fact in one value, and the next reader would not know which half it was acting on.

It is what a placement controller reads, and its shape is the reason it exists as a type rather than as a handful of catalog members a caller picks out. Every member here is a REQUEST. There is no lease epoch, no HostID, no endpoint, no residency and no journal position, so a consumer cannot read an observation out of it and cannot be one refactor away from treating a request as a fact — the Host registry's tuple is where observed placement lives, and it is fenced by an epoch this intent structurally cannot name.

Generation is what a controller records against the workload it created. A controller that reconciled generation 7 and reads 7 again has nothing to do, however many times the record has been rewritten in between.

type PointerError ¶

type PointerError struct {
	Code     PointerErrorCode
	Field    string
	Epoch    uint64
	Sequence uint64
	Revision uint64
	Cause    error
}

PointerError is a typed, redacted object pointer failure. Field names the offending input or stage and never carries a provider name, a key, or a record payload.

Revision is populated only for PointerErrorConflict, carrying the value that is itself the answer, as the other record kinds do for that code.

Epoch and Sequence are the two high-water marks the record retains, and they are populated by exactly the three codes that refuse a write or withhold a target: Epoch, Sequence and Cleared. Disclosing them is not a courtesy. They are the only durable facts a caller's next attempt has to satisfy, nothing else in this package reads them out, and a cleared pointer in particular hands back no record at all — so withholding them would leave probing by rejected write as a caller's only way to learn what it must name. The registry discloses its epoch on its two no-route codes for the same reason.

A DELIBERATE ASYMMETRY WITH THE TARGET: neither the refusals nor the cleared report names the object that IS stored. A caller learns what it must beat, never what it lost to.

func (e *PointerError) Error() string

func (e *PointerError) Unwrap() error

type PointerErrorCode ¶

type PointerErrorCode string

PointerErrorCode classifies an object pointer failure.

It is its own vocabulary rather than the catalog's, and the reason is the one this whole record exists for: the catalog carries a checkpoint SUMMARY that a projection write replaces wholesale, and this record carries the authoritative name. A caller that could handle both with one code set would be one refactor away from treating a failure to write the copy as a failure to write the truth, or the reverse.

The codes that need their reasons stated:

• Cleared — the pointer exists and names nothing. It is not an error in the caller and not an absence: the record is there, it holds both high-water marks, and it is those marks the failure carries. Reporting it as NotFound would tell a caller that a session had never had this pointer, which licenses a first write at any epoch and any sequence.
• Epoch — the request names a strictly lower lease epoch than the record's committed high-water mark, so the caller has provably lost the session.
• Sequence — the epoch was accepted and the target is OLDER than the one already named. Distinct from Epoch because the caller's authority is not in question and retrying will not help: what it holds is stale.
• NotFound — no pointer record of this kind exists at all. Distinct from Cleared for the reason above, and the distinction is what stops a clear from being confused with a session that has never checkpointed.

Conflict means a lost revision compare-and-swap and nothing else — re-read and retry — which is the meaning it has for every other record kind here.

const (
	PointerErrorInvalid   PointerErrorCode = "invalid"
	PointerErrorNotFound  PointerErrorCode = "not_found"
	PointerErrorCleared   PointerErrorCode = "cleared"
	PointerErrorEpoch     PointerErrorCode = "epoch"
	PointerErrorSequence  PointerErrorCode = "sequence"
	PointerErrorDeleted   PointerErrorCode = "deleted"
	PointerErrorIdentity  PointerErrorCode = "identity"
	PointerErrorConflict  PointerErrorCode = "conflict"
	PointerErrorUnknown   PointerErrorCode = "unknown"
	PointerErrorBackend   PointerErrorCode = "backend"
	PointerErrorMalformed PointerErrorCode = "malformed"
	PointerErrorVersion   PointerErrorCode = "version"
	PointerErrorTooLarge  PointerErrorCode = "too_large"
)

type PreparePublicCreateRequest ¶ added in v0.5.0

type PreparePublicCreateRequest struct {
	Identity                 PublicCreateIdentity
	ProposedRuntimeCommandID RuntimeCommandID
	AcceptedAt               time.Time
	ApplyDeadline            time.Time
	InitialWorkload          DesiredWorkload
}

PreparePublicCreateRequest reserves identity before payload bytes need exist. An identical retry returns the original mapping, times and initial workload.

type ProtocolMode ¶ added in v0.4.0

type ProtocolMode string

ProtocolMode identifies a session's immutable dispatch protocol. Record upgrades do not convert this mode; conversion requires an offline migration.

const (
	// ProtocolModeLegacy uses the released single-store epoch protocol.
	ProtocolModeLegacy ProtocolMode = "legacy"
	// ProtocolModeDisposition reserves the independent ownership/settlement
	// protocol. Its execution APIs are not implemented by this prerequisite.
	ProtocolModeDisposition ProtocolMode = "disposition"
)

type ProviderCloser ¶

type ProviderCloser interface {
	Close(context.Context) error
}

ProviderCloser is the lifecycle boundary for a provider whose ownership is explicitly transferred to Store.

type PublicCreateIdentity ¶ added in v0.5.0

type PublicCreateIdentity struct {
	TenantID      sessionwire.TenantID  `json:"tenant_id"`
	SessionID     sessionwire.SessionID `json:"session_id"`
	CommandID     sessionwire.CommandID `json:"command_id"`
	Target        HostTargetKey         `json:"target"`
	Binding       SessionBinding        `json:"binding"`
	Kind          CommandKind           `json:"kind"`
	PayloadDigest string                `json:"payload_digest"`
	PayloadSize   uint64                `json:"payload_size"`
}

PublicCreateIdentity binds a public create command to one immutable launch. PayloadDigest is lowercase SHA-256 hex; size/digest identify content, not an upload generation. Kind remains opaque; the dedicated API marks public create.

type PublicCreatePreparation ¶ added in v0.5.0

type PublicCreatePreparation struct {
	Reservation PublicCreateReservation
	Catalog     CatalogEntry
}

PublicCreatePreparation proves matching reservation/catalog only. It is not an ACK, a terminal outcome, or execution authority. Upload oversized bytes with PutCommandPayload, then call AdmitPublicCreate. A crash may require resending bytes; there is no background recovery, body reconstruction or orphan reaping.

type PublicCreateReservation ¶ added in v0.5.0

type PublicCreateReservation struct {
	Identity         PublicCreateIdentity `json:"identity"`
	RuntimeCommandID RuntimeCommandID     `json:"runtime_command_id"`
	AcceptedAt       time.Time            `json:"accepted_at"`
	ApplyDeadline    time.Time            `json:"apply_deadline"`
	InitialWorkload  DesiredWorkload      `json:"initial_workload"`
}

PublicCreateReservation is a durable proposal winner, NOT an accepted command. It can outlive a lost catalog race or a missing payload. Runtime mapping, times and InitialWorkload are first-writer proposals, never retry comparisons.

type PublishHostTargetRequest ¶

type PublishHostTargetRequest struct {
	Key HostTargetKey

	HostID         sessionwire.HostID
	HostGeneration uint64

	ObservedAt    time.Time
	Advertisement HostAdvertisement
}

PublishHostTargetRequest advertises one Host's current capacity for one target. It is also the HEARTBEAT: a Host republishes on its own cadence and this one operation moves the stored value, the rank, and the due time in a single compare-and-swap.

It carries a HostAdvertisement by VALUE, which is what makes "publish" and "drain" two different operations rather than one operation with a nil argument. A caller cannot accidentally remove its own capacity from every placement page by forgetting to set a member, and the withdrawn row has exactly two writers: DrainHostTarget and ReconcileHostTargets.

ObservedAt and the advertisement's ExpiresAt are the Host's own clock readings, as every other timestamp this package stores is. ExpiresAt is the promise the Host makes about its next heartbeat, so it must lie in the store's future and within MaxHostTargetTTL of it.

There is no expected revision. An advertisement is not a decision a caller makes about a row it has read — it is the current truth about one process's spare capacity — and the write is closed against the revision this store reads for itself. The generation is what establishes the right to write at all, and it establishes nothing else; see HostTarget.

type PutCommandPayloadRequest ¶ added in v0.5.0

type PutCommandPayloadRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	SizeBytes uint64
	SHA256    [32]byte
	MediaType string
	Body      io.Reader
}

PutCommandPayloadRequest declares exact content for an orchestration inbox object. There is no caller-selectable kind: only command-payload is allowed.

type PutHostRegistrationRequest ¶

type PutHostRegistrationRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch uint64

	ObservedAt time.Time
	ExpiresAt  time.Time

	Route HostRoute
}

PutHostRegistrationRequest publishes the current observed route to one session, creating the registration if no Host has ever registered it.

It carries a HostRoute by VALUE, which is what makes "publish" and "release" two different operations rather than one operation with a nil argument. A caller cannot accidentally erase a session's route by forgetting to set a member, and the tombstone has exactly one writer: ClearHostRegistration.

ObservedAt and ExpiresAt are the Host's own clock readings, as every other timestamp this package stores is. ExpiresAt is the promise the Host makes about its next heartbeat, so it must lie in the store's future and within MaxHostRegistrationTTL of it.

There is no expected revision. A registration is not a decision a caller makes about a record it has read — it is the current truth about where the session is running — and the write is closed against the revision this store reads for itself, exactly as UpdateCatalogHostState is. The epoch is what establishes the right to write at all.

type PutObjectRequest ¶

type PutObjectRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	Kind      ObjectKind
	SizeBytes uint64
	SHA256    [32]byte
	MediaType string
	Body      io.Reader
}

PutObjectRequest declares an immutable object's exact content properties. MediaType is optional, bounded, validated descriptive metadata; it is untrusted and does not participate in object identity.

SizeBytes is the exact byte length of Body, not a hint: a body that ends early or runs long is rejected. SessionStore imposes no ceiling on it, by design — the effective bound is whatever the storage provider accepts. Verification streams through a fixed buffer and nothing here allocates in proportion to SizeBytes, so a large declared size costs a rejected write, not memory.

type ReadGatesRequest ¶

type ReadGatesRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
}

ReadGatesRequest reads one session's open public gates.

It has no cursor and no limit. The catalog holds at most MaxCatalogOpenGates gates for a session, so the whole answer is bounded by construction and is read from one record; a continuation would be a token that could never be issued. A future API that pages a larger open-gate set is what GatePage.OpenGateCount is reserved for.

type ReadPublicJournalRequest ¶

type ReadPublicJournalRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	FromSeq   uint64

	// Tail starts within the last Limit sequence positions at the tip captured
	// by this read. Limit zero uses the store's configured page size. Private
	// records occupy positions without returning events, so a tail may contain
	// fewer events than Limit. The byte budget can shorten the page further;
	// its continuation cursor remains pinned to the same captured tip.
	Tail bool

	// ScanLimit bounds examined journal records, including withheld private
	// records. Zero preserves the unbounded-by-records legacy scan; a positive
	// value must not exceed storage.MaxOrderedPageLimit. Exhaustion may return
	// an empty event page with advanced coverage and a continuation cursor.
	// Supply this budget again on each continuation; it is not part of the
	// cursor. Event and byte limits may stop earlier, deferring the next event
	// without counting it as covered. This bounds record work, not total bytes
	// fetched to resolve the public bodies of the examined records.
	ScanLimit int

	// Cursor is a token a previous page of THIS session issued. It is opaque:
	// retain it and hand it back, but do not parse it or derive position,
	// tenancy, or authority from it. Possessing one authorizes nothing — a
	// caller must authorize TenantID and SessionID on its own — and a cursor
	// this store did not issue for this session and this projection is refused
	// with JournalErrorCursor, which means the walk restarts rather than that
	// anything is wrong with the journal.
	Cursor sessionwire.Cursor

	Limit int
}

ReadPublicJournalRequest positions one bounded public journal page. FromSeq (inclusive, zero meaning the first record), Cursor and Tail are mutually exclusive. Continue a page with its returned Cursor and Tail false.

type ReadRuntimeJournalRequest ¶

type ReadRuntimeJournalRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	FromSeq   uint64

	// Cursor carries the same rules as ReadPublicJournalRequest.Cursor, and the
	// two are not interchangeable: a public token presented here, or a runtime
	// token presented to the public read, is refused.
	Cursor sessionwire.Cursor

	Limit int
}

ReadRuntimeJournalRequest positions one bounded privileged replay page. Its FromSeq and Cursor positioning rules match ReadPublicJournalRequest; runtime replay does not offer tail positioning.

type ReconcileError ¶

type ReconcileError struct {
	Code      ReconcileErrorCode
	Field     string
	ExpiresAt time.Time
	Revision  uint64
	Cause     error
}

ReconcileError is a typed, redacted reconciliation claim failure. Field names the offending input or stage and never carries a provider name, a key, or a record payload.

Revision is populated only for ReconcileErrorConflict, carrying the value that is itself the answer, as the other record kinds do for that code.

ExpiresAt is populated only for ReconcileErrorHeld, and it is the whole reason the code is useful: a replica told only "someone else has it" can do nothing but poll, while one told when the claim lapses can wait exactly that long. It deliberately does NOT disclose the holder — knowing which replica is working is not a fact any decision here turns on.

func (e *ReconcileError) Error() string

func (e *ReconcileError) Unwrap() error

type ReconcileErrorCode ¶

type ReconcileErrorCode string

ReconcileErrorCode classifies a reconciliation claim failure.

It is its own vocabulary rather than the registry's or the catalog's, and for the reason HostTargetErrorCode is: a caller must not be able to write one handler for both. A RegistryError is the public account of who OWNS a session; a ReconcileError is the public account of who is currently doing scaling work for one. Sharing a type would let a caller branch on "held" without knowing which of those two questions it had asked, and the whole discipline of this record is that a claim is not ownership.

The codes that need their reasons stated:

• Held — another holder's claim is LIVE. It is not a failure in the caller and says nothing about any session's lease; it means the work is already being done, so do it later or not at all. ExpiresAt carries the horizon.
• Lapsed — no live claim is present. GetReconciliationClaim reports it against expires_at, meaning the stored claim has run out; a release reports it against holder_id, meaning the claim on this session is not the caller's and has run out, so there is nothing of the caller's to release. Both say the same thing about the world and differ in which of the caller's assumptions was wrong, which is why the field distinguishes them rather than a fourth code.
• NotFound — no claim record exists at all. Distinct from Lapsed because a session nobody has ever reconciled and one whose reconciler crashed are different operational facts, and identical to a caller that only wants to know whether it may proceed.

Conflict means a lost revision compare-and-swap and nothing else — re-read and retry — which is the meaning it has for every other record kind here.

There is deliberately no epoch code and no epoch member. A caller cannot obtain a lease epoch from this vocabulary because there is no lease epoch in this record to obtain.

const (
	ReconcileErrorInvalid   ReconcileErrorCode = "invalid"
	ReconcileErrorNotFound  ReconcileErrorCode = "not_found"
	ReconcileErrorHeld      ReconcileErrorCode = "held"
	ReconcileErrorLapsed    ReconcileErrorCode = "lapsed"
	ReconcileErrorDeleted   ReconcileErrorCode = "deleted"
	ReconcileErrorIdentity  ReconcileErrorCode = "identity"
	ReconcileErrorConflict  ReconcileErrorCode = "conflict"
	ReconcileErrorUnknown   ReconcileErrorCode = "unknown"
	ReconcileErrorBackend   ReconcileErrorCode = "backend"
	ReconcileErrorMalformed ReconcileErrorCode = "malformed"
	ReconcileErrorVersion   ReconcileErrorCode = "version"
	ReconcileErrorTooLarge  ReconcileErrorCode = "too_large"
)

type ReconcileHostTargetsRequest ¶

type ReconcileHostTargetsRequest struct {
	Limit    int
	MaxPages int

	// Cursor resumes a sweep that ran out of page budget. It is opaque: retain
	// it and hand it back, but do not parse it. Possessing one authorizes
	// nothing — this operation is service-owned and a caller must establish
	// that on its own — and a token this store did not issue for a sweep is
	// refused with HostTargetErrorCursor.
	//
	// Resuming is not an optimization; see DefaultHostTargetReconcilePages for
	// why a page budget alone leaves this sweep able to make no progress at
	// all.
	Cursor sessionwire.Cursor
}

ReconcileHostTargetsRequest bounds one service-owned sweep of the directory's deadline view. Zero means the default in Limit and MaxPages.

type ReconciliationClaim ¶

type ReconciliationClaim struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	HolderID string

	ClaimedAt time.Time
	ExpiresAt time.Time
}

ReconciliationClaim is the durable record of which Factory replica is currently doing reconciliation work for one session, and until when.

HolderID names the replica, opaquely. It is the only thing a later write is compared against, and it is not authority: two replicas that chose the same holder string are indistinguishable here, which costs exactly the duplicate work this record exists to reduce and costs nothing else.

ClaimedAt is the store's own clock reading at the moment the claim was accepted; ExpiresAt is the holder's promise about when it will be finished. The two are stamped from different clocks on purpose. A caller-supplied claim instant could be placed after its own expiry, or before a takeover that has already happened, and nothing could tell; the horizon must be the caller's because only the caller knows how long its work takes, and it is bounded above for that reason.

WHICH CLOCK, AND WHAT THAT DOES NOT BUY. Taking the claim instant from the store rather than the request removes a degree of freedom from the REQUEST; it does not make the instant authoritative. The clock is caller-injected and unchecked (see WithClock), and a Factory replica embeds its own Store, so s.clock is that replica's clock one level down. Liveness is therefore evaluated against the READING replica's clock and is skew-relative in both directions: a slow replica sees another's claim live longer than its holder meant, and a fast one takes it over early. There is no shared time here and none is available.

That is affordable for the reason this file's header gives and for no other: the claim licenses nothing, so the worst either direction produces is duplicated or delayed work that was already safe to do concurrently. It would NOT be affordable for a record whose expiry decided who may write, which is why the Host lease is a lease and this is not one.

A claim whose expiry EQUALS its claim instant has lapsed on arrival, which is exactly what ReleaseReconciliationClaim writes. That is not a second state needing a marker of its own: "released" and "expired" are the same fact to every reader — no live claim — and giving them one spelling means no reader has to know which one it is looking at.

type ReconciliationClaimEntry ¶

type ReconciliationClaimEntry struct {
	Claim    ReconciliationClaim
	Revision uint64
}

ReconciliationClaimEntry is a claim together with the revision a later compare-and-swap names.

The provider's immutable acceptance order is deliberately not exposed, for the reason HostRegistrationEntry's is not: a session's position in a stream of claims is not a fact any caller acts on.

type RegistryError ¶

type RegistryError struct {
	Code     RegistryErrorCode
	Field    string
	Epoch    uint64
	Revision uint64
	Cause    error
}

RegistryError is a typed, redacted Host registration failure. Field names the offending input or stage and never carries a provider name, a key, or a record payload.

Revision is populated only for RegistryErrorConflict, carrying the value that is itself the answer, as CatalogError and InboxError do for that code.

Epoch is populated more widely than the catalog's and the inbox's, and the extra two codes are the point rather than an inconsistency. For RegistryErrorEpoch it is the high-water mark that refused the write, as it is there. For RegistryErrorExpired and RegistryErrorReleased it is the fence the retained record still carries — because those two codes are the whole public account of a session that has no route, they are what a retention sweep acts on, and this package offers no other way to observe a registration's epoch. Without it a caller's only route to the record's most consequential permanent state would be to attempt a write it expects to fail and read the refusal. RegistryErrorNotFound carries no epoch: there is no record and so no fence, and a zero there means exactly that.

func (e *RegistryError) Error() string

func (e *RegistryError) Unwrap() error

type RegistryErrorCode ¶

type RegistryErrorCode string

RegistryErrorCode classifies a Host registration failure.

It is the registry's own vocabulary rather than the catalog's, and the reason is the one InboxErrorCode gives. Gates reuse CatalogError because a gate IS catalog state. A registration is a separate aggregate: its own namespace, its own record, its own identity, its own fencing high-water mark, and — unlike every other record in this package — its own LIFETIME, because it expires while nothing else here does. Its writes never read or write a session's catalog record, and a caller branching on "there is no live route" should not have to match the type that reports "there is no such session".

The three ways a registration can fail to be a route are deliberately separate codes, and none of them is an error in the caller:

• NotFound — no registration has ever been written for this session. No Host has ever held it, or none has ever reported holding it.
• Expired — a registration exists and names a Host, but its expiry has passed. The Host may be alive and merely slow to heartbeat, or it may be gone; this record cannot tell the difference and neither may its reader.
• Released — a registration exists and is the tombstone a graceful shutdown left behind. The Host that held the session let it go on purpose.

A ROUTER MUST TREAT ALL THREE ALIKE: none of them is a route, and the difference between them is diagnostic. They are separate rather than collapsed into NotFound because of what an undifferentiated "absent" invites. A future writer that reads a registration, sees "not found", and creates a fresh record has just dropped the fencing high-water mark of whatever was really there — which is precisely the write the epoch fence exists to refuse. Nothing in this package reaches a write path through a reader that reports these codes, and the codes being distinct is what makes a future one that tries to look wrong rather than plausible.

The rest name the same failures the catalog's and the inbox's codes do:

• Invalid — a caller mistake in the request or a stored record that no longer satisfies its own rules.
• Deleted — the provider holds a TOMBSTONE for this identity. This package never deletes a registration, so it means the fencing high-water mark has been physically destroyed by something outside it; it is reported and never worked around, because the alternative is admitting a write from a lease that has already lost the session.
• Identity — a stored record disagreed with the identity it was filed under or asked for. It is not a caller error and no retry fixes it.
• Epoch — the caller named a lease epoch BELOW the record's committed high-water mark. That lease has provably been superseded and must not retry under the same epoch; Epoch carries the high-water mark, as CatalogErrorEpoch does.
• Conflict — a compare-and-swap lost a race on the record's revision, with no statement about ownership. Re-read and retry. Revision carries what the record is at now when the store could see it.
• Unknown — the mutation's outcome could not be resolved at all.

const (
	RegistryErrorInvalid   RegistryErrorCode = "invalid"
	RegistryErrorNotFound  RegistryErrorCode = "not_found"
	RegistryErrorExpired   RegistryErrorCode = "expired"
	RegistryErrorReleased  RegistryErrorCode = "released"
	RegistryErrorDeleted   RegistryErrorCode = "deleted"
	RegistryErrorIdentity  RegistryErrorCode = "identity"
	RegistryErrorEpoch     RegistryErrorCode = "epoch"
	RegistryErrorConflict  RegistryErrorCode = "conflict"
	RegistryErrorUnknown   RegistryErrorCode = "unknown"
	RegistryErrorBackend   RegistryErrorCode = "backend"
	RegistryErrorMalformed RegistryErrorCode = "malformed"
	RegistryErrorVersion   RegistryErrorCode = "version"
	RegistryErrorTooLarge  RegistryErrorCode = "too_large"
)

type RejectCommandRequest ¶

type RejectCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	LeaseEpoch       uint64
	Rejection        sessionwire.ErrorDetail
}

RejectCommandRequest records the terminal typed rejection of a command.

LeaseEpoch is OPTIONAL here and required everywhere else in this file, and the asymmetry is the deadline reconciler's. Claiming, applying, and completing are things a session's lease holder does; rejecting is also what a Factory replica does to a command that has run out of deadline, and such a replica may be reconciling a session that has never had a lease at all. A zero epoch is therefore the honest statement "I am not acting under a session lease", and it buys exactly the authority the state machine grants that caller: it may settle a command that nobody is working on, and nothing else.

A NONZERO epoch here is a consistency check on a view the caller asserts, not an authority boundary. Nothing forces a caller to name one — a superseded Host obtains the reconciler's authority simply by passing zero — so the fence cannot be what keeps a stale lease out. What keeps it out is the claim rule below it, which is a property of the RECORD and applies identically at every epoch: a live claim admits only its own, and an applying record admits nobody. The fence's job is narrower and still worth doing: a caller that volunteers an epoch below the record's high-water mark is telling the store its view of the session is stale, and is told so rather than acting on it.

Rejection is a value rather than a pointer because a rejection without a reason is not a state this record has. It is validated as a public projection, so it carries a stable typed cause rather than a provider or runtime message.

type RejectDispositionCommandRequest ¶ added in v0.8.0

type RejectDispositionCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	ResidencyEpoch   ResidencyEpoch
}

RejectDispositionCommandRequest refuses one command BEFORE any dispatch of it was durably authorized.

ExpectedRevision means what it means everywhere else here. ResidencyEpoch is OPTIONAL: see this file's header for why, and for what a zero buys.

There is no rejection reason, and its absence is a stated cost rather than an oversight — see the header's third divergence.

type ReleaseReconciliationClaimRequest ¶

type ReleaseReconciliationClaimRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	HolderID string
}

ReleaseReconciliationClaimRequest gives one session's claim back early.

It carries no timestamp, and that is deliberate rather than an omission, for the reason ClearHostRegistrationRequest carries none: a released claim's instants record that THIS STORE released it, and a caller-supplied one could place the release in the future, producing a record that reads as released by intent and as live by time.

type RemnantGateIntent ¶

type RemnantGateIntent struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	GateID    sessionwire.GateID
	Revision  uint64
}

RemnantGateIntent is one deadline intent whose gate the session's durable record does not project as open, together with the revision a retirement names.

It is reported rather than acted on, and rather than merely dropped, because this reader cannot decide the question a retirement has to answer: whether the open that wrote the intent crashed or is still in flight. Only elapsed time can, and the service that sweeps is the one holding the clock the retirement is evaluated against. See RetireGateDeadlineIntent.

The revision travels with it so the retirement is a compare-and-swap onto the row this page actually saw. Without it a sweeper would have to re-read, and a re-read is a second decision point at which a gate could have been reopened.

IT IS DELIBERATELY NOT RetireGateDeadlineIntentRequest, though the two spell the same four members today and staticcheck reports the conversion (S1016). One is a SWEEP RESULT and the other an OPERATION REQUEST, and collapsing them would make the request hostage to whatever a future page decides to report: a member added here for a caller's convenience would silently become a member the operation accepts. The conversion is used once, in the test that drives the whole sweeper path, which is the right place for it — it holds the two shapes together where they are meant to line up, and stops compiling if they ever diverge, which is the loud failure rather than a silent one.

type ResidencyAcquireCleanupError ¶ added in v0.4.0

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

ResidencyAcquireCleanupError means acquisition was canceled after a provider grant arrived and its release also failed. No ownership grant is returned. Use errors.As to retain this cleanup obligation and retry Release; until a release succeeds the Store admission remains held and Close may time out. Unwrap exposes both the acquisition refusal and provider cleanup failure.

func (e *ResidencyAcquireCleanupError) Error() string

func (e *ResidencyAcquireCleanupError) Release(ctx context.Context) error

func (e *ResidencyAcquireCleanupError) Unwrap() error

type ResidencyEpoch ¶ added in v0.4.0

type ResidencyEpoch uint64

ResidencyEpoch identifies a Host residency grant. It is meaningful only in that session's residency namespace and must never be compared with, or used as, a journal epoch. Residency alone authorizes no journal writes or command application; the disposition protocol is not activated by this API.

type ResidencyError ¶ added in v0.4.0

type ResidencyError struct {
	Operation string
	Cause     error
}

ResidencyError is a provider failure acquiring or releasing residency. Cause preserves provider errors, including storage.LeaseHeldError for contention. Catalog, scope and Store lifecycle refusals retain their existing typed errors.

func (e *ResidencyError) Error() string

func (e *ResidencyError) Unwrap() error

type ResidencyGrant ¶ added in v0.4.0

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

ResidencyGrant owns only an orchestration residency lease. Epoch and Lost come directly from Storage; Lost is the provider's actual notification, never inferred from journal events, release errors or caller cancellation.

Liveness is provider-dependent. In particular memstore provides neither TTL nor crash takeover. Residency loss does not fence a journal: a successor must independently acquire the journal grant before application.

The grant is safe for concurrent use and holds a Store admission until a successful Release. Store shutdown attempts bounded cleanup once; failed cleanup retains the admission for an explicit retry. Providers must honor Release context cancellation. There is no background retry loop.

func (g *ResidencyGrant) Epoch() ResidencyEpoch

func (g *ResidencyGrant) Lost() <-chan struct{}

func (g *ResidencyGrant) Release(ctx context.Context) error

type ResolveGateRequest ¶

type ResolveGateRequest struct {
	TenantID   sessionwire.TenantID
	SessionID  sessionwire.SessionID
	LeaseEpoch uint64
	GateID     sessionwire.GateID
}

ResolveGateRequest retires one open gate. It records only that the gate is no longer open and awaiting an answer: it carries no response, decides nothing about what the session does next, and starts no continuation.

It is idempotent, and it must be: a resolve interrupted between clearing the projection and retiring the intent is completed by repeating it.

type RetireGateDeadlineIntentRequest ¶

type RetireGateDeadlineIntentRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	GateID    sessionwire.GateID
	Revision  uint64
}

RetireGateDeadlineIntentRequest tombstones one gate's deadline intent.

Revision is the revision the caller observed on the row, in a RemnantGateIntent from ListDueGates. The write is a compare-and-swap onto it, so a row that moved between the page and this call is refused rather than retired on stale evidence.

It is the counterpart of RemnantGateIntent, which is what a sweep reports and what a caller builds this from; the two are deliberately separate types for the reason stated there.

It names a tenant and a session because it must: the intent is filed under the session's scope and there is no way to reach it without them. So this operation cannot carry the structural hint the sweeps carry — a request that names no tenant — and its service-only status is prose alone. What protects it is that there is nothing a tenant could aim it at productively: it refuses any gate the session's own durable record still projects as open.

type RuntimeCommandID ¶

type RuntimeCommandID string

RuntimeCommandID is the runtime-facing identity a Host forwards into the Harness API. It is a named type rather than a bare string because it travels beside the public CommandID in almost every signature, and two adjacent strings of one type are silently swappable.

This package does not impose a UUID grammar on it. Harness allocates UUIDs today, but the durable MAPPING is what this record exists to make authoritative; a grammar check here would be a second statement of a rule this package does not own, and it would refuse a future runtime identity without adding any safety. It is validated as a bounded opaque UTF-8 value, exactly as the catalog validates the identities it does not own.

type RuntimePage ¶

type RuntimePage struct {
	Records        []RuntimeRecord
	CapturedTip    uint64
	CoveredThrough uint64
	NextCursor     sessionwire.Cursor
}

RuntimePage is a bounded privileged replay page captured at CapturedTip.

type RuntimeRecord ¶

type RuntimeRecord struct {
	Seq      uint64
	Envelope Envelope
}

RuntimeRecord is one raw journal record as it is stored. Object-backed bodies stay unresolved: the caller decides which of them to fetch, through the ordinary object API, so a replay never pays for bytes it does not want.

type SaveDispositionCommandCursorRequest ¶ added in v0.7.0

type SaveDispositionCommandCursorRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch    uint64
	ConsumedOrder uint64
}

SaveDispositionCommandCursorRequest records one session's consumption cursor.

LeaseEpoch is the consumer's residency epoch and is compared against the record's committed high-water mark. ConsumedOrder is the acceptance order the consumer is done through and is compared against the record's committed order; both are high-water marks and neither ever falls.

There is no expected revision and no timestamp, for the reason SetSessionPointerRequest carries neither: a cursor is not a decision a caller makes about a record it has read — it is the current truth about how far a consumer has got — so the write is closed against the revision this store reads for itself.

type SessionBinding ¶ added in v0.4.0

type SessionBinding struct {
	StorageBindingID string       `json:"storage_binding_id"`
	BindingVersion   string       `json:"binding_version"`
	RuntimeSessionID string       `json:"runtime_session_id"`
	ProtocolMode     ProtocolMode `json:"protocol_mode"`
}

SessionBinding pins the storage configuration and runtime identity chosen at creation. IDs are bounded opaque configuration names, not provider keys or credentials. BindingVersion identifies immutable configuration, never the current agent default. The all-zero value denotes an unbound legacy record. A nonzero binding must contain all four members.

type SessionDispositionCommandPage ¶ added in v0.7.0

type SessionDispositionCommandPage struct {
	Commands       []DispositionInboxEntry
	Limit          int
	NextAfterOrder uint64
}

SessionDispositionCommandPage is one bounded ascending page of one session's disposition inbox.

Commands are in STRICTLY increasing AcceptedOrder, every one of them strictly above the request's bound. They are the SAME DispositionInboxEntry values a named read of each command returns, held to the same filing checks and to the same catalog binding — there is no weaker sweep-shaped variant, because a consumer acts on these rows and every write it then makes is a compare-and-swap against the revision reported here.

LIMIT is the EFFECTIVE limit after a zero request limit has been resolved to the store's page size, so a caller that named no limit can still tell a full page from a short one.

NEXTAFTERORDER is the last row's order, and is zero exactly when the page is empty. An empty page means the stream is exhausted at this bound: unlike a due page, nothing here is skipped, so there is no "empty but not finished" state to distinguish. A caller that receives one keeps the bound it asked with.

There is no Unreadable count, and its absence is the contract rather than an omission — see ListSessionDispositionCommands.

type SessionPage ¶

type SessionPage struct {
	sessionwire.SessionPage

	UnreadableSkipped int
}

SessionPage is one bounded page of a tenant's sessions together with what producing it cost, as DueGatePage is for the deadline view.

It embeds Core's page rather than replacing it, so a caller still reads Sessions and NextCursor directly and can hand the embedded value to anything that takes a sessionwire.SessionPage.

UnreadableSkipped counts rows this reader could not hold to their own identity and therefore did not publish. It is not a diagnostic afterthought: it is what makes skipping such a row safe to do at all, because it leaves the caller able to tell "this tenant has three sessions" from "this tenant has three sessions and one row I could not vouch for". A nonzero count is durable — nothing in this package rewrites such a row — so it means a build that understands the row is needed, not that a retry will help.

type SessionPointer ¶

type SessionPointer struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	Kind SessionPointerKind

	LeaseEpoch uint64
	Sequence   uint64

	UpdatedAt time.Time

	// Target is nil exactly when this pointer has been cleared.
	Target *sessionwire.ObjectReference
}

SessionPointer is the durable record of which immutable object currently fills one role for one session, and of the two high-water marks that decide whether a later write may replace it.

The two are different questions and both are permanent:

• LeaseEpoch answers MAY YOU WRITE. It is the epoch of the grant that last wrote this record, and a write naming a strictly lower one has provably lost the session. An equal one is admitted because one grant writes many times. It never falls, which is why this record is never deleted.
• Sequence answers IS THIS NEWER. It is the journal position the target was captured at, and a write naming a strictly lower one would republish an object that a later capture has already superseded. It never falls either, and it is the one thing the epoch cannot supply: two writes under ONE grant are ordered only by their revision compare-and-swap, so a losing writer that retried would otherwise reinstate its older checkpoint over the newer one and every restore afterwards would silently lose the work in between. The catalog refuses a regressing LastJournalSeq for exactly this reason.

A nil Target is the cleared tombstone. It is one nil rather than an enumeration of zero values, so a LIVE TOMBSTONE IS UNREPRESENTABLE rather than excluded by a check somebody has to remember, and a cleared pointer carries both high-waters and nothing else.

UpdatedAt is the STORE's clock, not a caller's, for the reason ClearHostRegistrationRequest carries no timestamp: nothing in this record has an expiry, so no decision turns on this instant, and a caller-supplied one could only be wrong. It is the record's audit line and the summary's capture instant.

It is read when the request is VALIDATED, before this store issues any provider call — not when the write was accepted. A set reads it before admission, the witness binding, the read and the compare-and-swap; a clear reads it after its read and before its one swap, so the two paths do not even stamp from the same point in their own sequences. That is precisely because nothing decides on it: validating before any provider work is the property worth having, and paying a round trip to make an audit line a few milliseconds truer is not.

The accumulation is one small permanent row per role per session that has ever had one: never listed, never ranked, never due, and never read except by name. The registry's carry-forward contract about retention applies here word for word — the only safe reaper is one that removes the session's whole scope at once, because deleting this row alone destroys a fence while leaving the session writable.

func (p SessionPointer) CheckpointSummary() (CheckpointSummary, error)

type SessionPointerEntry ¶

type SessionPointerEntry struct {
	Pointer  SessionPointer
	Revision uint64
}

SessionPointerEntry is a pointer together with the revision a later compare-and-swap names.

The provider's immutable acceptance order is deliberately not exposed, for the reason HostRegistrationEntry's is not: a session's position in a stream of pointer writes is not a fact any caller acts on.

type SessionPointerKind ¶

type SessionPointerKind string

SessionPointerKind is the closed set of roles a session's current object can fill. It is the vocabulary the generic kernel below is parameterized by, and each member has exactly one public triple of methods.

ActiveContinuation is declared here and stored here and is otherwise RESERVED for the gate suspension/resume plan. This file stores a NAME; it does not define what a continuation contains, does not resume one, and no operation in this package reads one — which TestNothingElseInThisPackageReadsAPointer keeps true.

const (
	SessionPointerActiveContinuation  SessionPointerKind = "active-continuation"
	SessionPointerWorkspaceCheckpoint SessionPointerKind = "workspace-checkpoint"
	SessionPointerRuntimeCheckpoint   SessionPointerKind = "runtime-checkpoint"
)

type SetSessionPointerRequest ¶

type SetSessionPointerRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID

	LeaseEpoch uint64
	Sequence   uint64

	Target sessionwire.ObjectReference
}

SetSessionPointerRequest names the object one role should now point at.

It carries a Target by VALUE, which is what makes "set" and "clear" two different operations rather than one operation with a nil argument: a caller cannot erase a session's checkpoint by forgetting to set a member, and the tombstone has exactly one writer.

It carries no KIND. The kind is spelled by the METHOD, so there is no way to name a role that has no method and no way to hand the wrong role a reference that the method's own object-kind rule would then have to catch by luck.

LeaseEpoch is the grant's epoch and is compared against the record's committed high-water mark. Sequence is the journal position the target was captured at and is compared against the record's committed sequence; both are high-water marks and neither ever falls.

There is no expected revision and no timestamp. A pointer is not a decision a caller makes about a record it has read — it is the current truth about which object fills a role — so the write is closed against the revision this store reads for itself, exactly as UpdateCatalogHostState and PutHostRegistration are, and the instant is the store's for the reason SessionPointer states.

type SettleDispositionCommandRequest ¶ added in v0.6.0

type SettleDispositionCommandRequest struct {
	TenantID  sessionwire.TenantID
	SessionID sessionwire.SessionID
	CommandID sessionwire.CommandID

	ExpectedRevision uint64
	ResidencyEpoch   ResidencyEpoch
}

SettleDispositionCommandRequest asks the store to settle one command from durable evidence.

It names a command, the revision the caller decided on, and the residency the claimant holds — and nothing else. It CANNOT supply an outcome, an absence, or any proof structure: the store derives what it expects from its own record and obtains the evidence itself, which is the whole of why a settlement cannot be talked into a state the journal does not support.

ResidencyEpoch is settlement context, recorded in the outcome. It is not compared with any journal epoch, and it does not authorize the settlement — the evidence does. It may be a successor's, which is what lets the original holder AND a successor settle the same command by the same route.

type Store ¶

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

Store is the durable session aggregate over one complete storage backend.

func Open(ctx context.Context, backend *storage.Composite, opts ...Option) (*Store, error)

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	sessionwire "github.com/looprig/core/sessionwire/v1"
	"github.com/looprig/sessionstore"
	"github.com/looprig/storage/memstore"
)

func main() {
	ctx := context.Background()

	store, err := sessionstore.Open(ctx, memstore.New())
	if err != nil {
		log.Fatal(err)
	}
	defer func() {
		if err := store.Close(ctx); err != nil {
			log.Fatal(err)
		}
	}()

	createdAt := time.Date(2026, 8, 30, 10, 0, 0, 0, time.UTC)
	if _, created, err := store.CreateCatalogEntry(ctx, sessionstore.CreateCatalogEntryRequest{
		TenantID:               "tenant-a",
		SessionID:              "session-a",
		AgentID:                "agent-a",
		RuntimeCompatibilityID: "runtime-v1",
		CreatedAt:              createdAt,
		LastActiveAt:           createdAt,
		State:                  sessionwire.SessionStateIdle,
		Residency:              sessionwire.SessionResidencyCold,
		DesiredPlacement:       sessionwire.HostPlacementPooled,
		IdempotencyKey:         "create-1",
	}); err != nil {
		log.Fatal(err)
	} else {
		fmt.Println("created:", created)
	}

	page, err := store.ListSessions(ctx, sessionstore.ListSessionsRequest{TenantID: "tenant-a", Limit: 10})
	if err != nil {
		log.Fatal(err)
	}
	for _, summary := range page.Sessions {
		fmt.Println("session:", summary.SessionID, summary.State)
	}
	fmt.Println("unreadable skipped:", page.UnreadableSkipped)

}

Output:
created: true
session: session-a idle
unreadable skipped: 0

func (s *Store) AcquireReconciliationClaim(
	ctx context.Context,
	req AcquireReconciliationClaimRequest,
) (ReconciliationClaimEntry, error)

func (s *Store) AcquireResidency(ctx context.Context, req AcquireResidencyRequest) (*ResidencyGrant, error)

func (s *Store) AdmitCommand(ctx context.Context, req AdmitCommandRequest) (InboxEntry, bool, error)

func (s *Store) AdmitDispositionCommand(ctx context.Context, req AdmitDispositionCommandRequest) (DispositionInboxEntry, bool, error)

func (s *Store) AdmitPublicCreate(ctx context.Context, req AdmitPublicCreateRequest) (DispositionInboxEntry, bool, error)

func (s *Store) BeginApplyingCommand(ctx context.Context, req BeginApplyingCommandRequest) (InboxEntry, error)

func (s *Store) BeginDispositionAttempt(ctx context.Context, req BeginDispositionAttemptRequest) (DispositionInboxEntry, error)

func (s *Store) ClaimCommand(ctx context.Context, req ClaimCommandRequest) (InboxEntry, error)

func (s *Store) ClaimDispositionCommand(ctx context.Context, req ClaimDispositionCommandRequest) (DispositionInboxEntry, bool, error)

func (s *Store) ClearActiveContinuationPointer(
	ctx context.Context, req ClearSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) ClearHostRegistration(ctx context.Context, req ClearHostRegistrationRequest) (HostRegistrationEntry, error)

func (s *Store) ClearRuntimeCheckpointPointer(
	ctx context.Context, req ClearSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) ClearWorkspaceCheckpointPointer(
	ctx context.Context, req ClearSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) Close(ctx context.Context) error

func (s *Store) CompleteCommand(ctx context.Context, req CompleteCommandRequest) (InboxEntry, error)

func (s *Store) ControlShards() int

func (s *Store) CreateCatalogEntry(ctx context.Context, req CreateCatalogEntryRequest) (CatalogEntry, bool, error)

func (s *Store) DrainHostTarget(ctx context.Context, req DrainHostTargetRequest) (HostTargetEntry, error)

func (s *Store) FindCommandApplication(ctx context.Context, req FindCommandApplicationRequest) (CommandApplication, error)

func (s *Store) GetActiveContinuationPointer(
	ctx context.Context, req GetSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) GetCatalogEntry(ctx context.Context, req GetCatalogEntryRequest) (CatalogEntry, error)

func (s *Store) GetCommand(ctx context.Context, req GetCommandRequest) (InboxEntry, error)

func (s *Store) GetDispositionCommand(ctx context.Context, req GetDispositionCommandRequest) (DispositionInboxEntry, error)

func (s *Store) GetHostRegistration(ctx context.Context, req GetHostRegistrationRequest) (HostRegistrationEntry, error)

func (s *Store) GetObject(ctx context.Context, req GetObjectRequest) (io.ReadCloser, error)

func (s *Store) GetObjectMetadata(ctx context.Context, req GetObjectMetadataRequest) (sessionwire.ObjectMetadata, error)

func (s *Store) GetReconciliationClaim(
	ctx context.Context,
	req GetReconciliationClaimRequest,
) (ReconciliationClaimEntry, error)

func (s *Store) GetRuntimeCheckpointPointer(
	ctx context.Context, req GetSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) GetWorkspaceCheckpointPointer(
	ctx context.Context, req GetSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) ListCompatibleHosts(ctx context.Context, req ListCompatibleHostsRequest) (HostTargetPage, error)

func (s *Store) ListDueCommands(ctx context.Context, req ListDueCommandsRequest) (DueCommandPage, error)

func (s *Store) ListDueDispositionCommands(ctx context.Context, req ListDueDispositionCommandsRequest) (DispositionDueCommandPage, error)

func (s *Store) ListDueGates(ctx context.Context, req ListDueGatesRequest) (DueGatePage, error)

func (s *Store) ListSessionDispositionCommands(
	ctx context.Context, req ListSessionDispositionCommandsRequest,
) (SessionDispositionCommandPage, error)

func (s *Store) ListSessions(ctx context.Context, req ListSessionsRequest) (SessionPage, error)

func (s *Store) LoadDispositionCommandCursor(
	ctx context.Context, req LoadDispositionCommandCursorRequest,
) (DispositionCommandCursorEntry, error)

func (s *Store) OpenGate(ctx context.Context, req OpenGateRequest) (CatalogEntry, error)

func (s *Store) OpenJournal(ctx context.Context, req OpenJournalRequest) (*JournalWriter, error)

func (s *Store) PreparePublicCreate(ctx context.Context, req PreparePublicCreateRequest) (PublicCreatePreparation, error)

func (s *Store) PublishHostTarget(ctx context.Context, req PublishHostTargetRequest) (HostTargetEntry, error)

func (s *Store) PutCommandPayload(ctx context.Context, req PutCommandPayloadRequest) (sessionwire.ObjectMetadata, error)

func (s *Store) PutHostRegistration(ctx context.Context, req PutHostRegistrationRequest) (HostRegistrationEntry, error)

func (s *Store) PutObject(ctx context.Context, req PutObjectRequest) (sessionwire.ObjectMetadata, error)

func (s *Store) ReadDispositionEvidence(ctx context.Context, req DispositionEvidenceRequest) (DispositionEvidence, error)

func (s *Store) ReadGates(ctx context.Context, req ReadGatesRequest) (sessionwire.GatePage, error)

func (s *Store) ReadPublicJournal(ctx context.Context, req ReadPublicJournalRequest) (sessionwire.JournalPage, error)

func (s *Store) ReadRuntimeJournal(ctx context.Context, req ReadRuntimeJournalRequest) (RuntimePage, error)

func (s *Store) ReconcileHostTargets(
	ctx context.Context,
	req ReconcileHostTargetsRequest,
) (HostTargetReconcileResult, error)

func (s *Store) RejectCommand(ctx context.Context, req RejectCommandRequest) (InboxEntry, error)

func (s *Store) RejectDispositionCommand(ctx context.Context, req RejectDispositionCommandRequest) (DispositionInboxEntry, bool, error)

func (s *Store) ReleaseReconciliationClaim(
	ctx context.Context,
	req ReleaseReconciliationClaimRequest,
) (ReconciliationClaimEntry, error)

func (s *Store) ResolveGate(ctx context.Context, req ResolveGateRequest) (CatalogEntry, error)

func (s *Store) RetireGateDeadlineIntent(ctx context.Context, req RetireGateDeadlineIntentRequest) error

func (s *Store) SaveDispositionCommandCursor(
	ctx context.Context, req SaveDispositionCommandCursorRequest,
) (DispositionCommandCursorEntry, error)

func (s *Store) SetActiveContinuationPointer(
	ctx context.Context, req SetSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) SetRuntimeCheckpointPointer(
	ctx context.Context, req SetSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) SetWorkspaceCheckpointPointer(
	ctx context.Context, req SetSessionPointerRequest) (SessionPointerEntry, error)

func (s *Store) SettleDispositionCommand(ctx context.Context, req SettleDispositionCommandRequest) (DispositionInboxEntry, bool, error)

func (s *Store) UpdateCatalogDesiredState(ctx context.Context, req UpdateCatalogDesiredStateRequest) (CatalogEntry, error)

func (s *Store) UpdateCatalogHostState(ctx context.Context, req UpdateCatalogHostStateRequest) (CatalogEntry, error)

type StoreClosedError ¶

type StoreClosedError struct{}

StoreClosedError reports an attempt to admit work after shutdown started.

func (*StoreClosedError) Error() string

type UpdateCatalogDesiredStateRequest ¶

type UpdateCatalogDesiredStateRequest struct {
	TenantID               sessionwire.TenantID
	SessionID              sessionwire.SessionID
	ExpectedRevision       uint64
	IdempotencyKey         string
	DesiredPlacement       sessionwire.HostPlacement
	RuntimeCompatibilityID string
	DesiredWorkload        DesiredWorkload
}

UpdateCatalogDesiredStateRequest writes Factory-authored desired state. It deliberately has no lease epoch member: desired state is guarded by revision compare-and-swap plus a retry-stable idempotency key, because Factory does not hold the Host's lease and must not be able to spell a claim on it.

IdempotencyKey names the INTENT, and exactly one key is retained. A request whose key equals the retained one is treated as a replay of that intent and returns the stored record unchanged with a nil error — including when the rest of the request differs. Reusing a key for a NEW intent therefore succeeds without applying anything, so a caller must mint a fresh key per distinct desired state rather than per retry batch.

type UpdateCatalogHostStateRequest ¶

type UpdateCatalogHostStateRequest struct {
	TenantID       sessionwire.TenantID
	SessionID      sessionwire.SessionID
	LeaseEpoch     uint64
	State          sessionwire.SessionState
	Residency      sessionwire.SessionResidency
	LastActiveAt   time.Time
	LastJournalSeq uint64
	LastEventID    sessionwire.EventID
	Checkpoint     CheckpointSummary
	OpenGates      []sessionwire.GateProjection
}

UpdateCatalogHostStateRequest writes the fields owned by the Host holding the session's journal lease. LeaseEpoch is that grant's epoch and is compared against the record's committed high-water mark.

Every field here REPLACES its stored counterpart; nothing is merged. A write that omits Checkpoint zeroes the stored checkpoint summary, and a write that omits OpenGates clears the stored gate projections. That is deliberate and is why the catalog holds a *summary*: the authoritative, retained high-water checkpoint pointer is a separate epoch-fenced record, so clearing a summary here loses no durable state. Callers therefore send the complete current projection on every write rather than a delta.

LastJournalSeq is the one exception, and its asymmetry is intentional: the journal is append-only and a successor fence commits above its predecessor's tip, so a durable sequence never moves backwards and a regressing one is refused rather than stored.