runtimecommand

type Admitted ¶

type Admitted struct {
	// CommandID is Host's opaque public identity for this command.
	CommandID CommandID
	// RuntimeCommandID is the once-allocated UUID this command's runtime headers
	// and events carry. Harness uses it verbatim.
	RuntimeCommandID uuid.UUID
	// Kind selects the runtime dispatch path.
	Kind Kind
	// LeaseEpoch is the session-lease epoch this command was admitted against. A
	// record admitted under a superseded epoch is refused.
	LeaseEpoch uint64
	// Blocks is the input payload, required for KindInput and forbidden for every
	// other kind (a payload a kind cannot carry would be silently dropped).
	Blocks []content.Block
}

Admitted is one command Host has ALREADY admitted, handed to Harness for application. Harness re-validates it — an admitted record it cannot durably correlate is refused rather than applied on trust — but it never re-derives an identity from it.

func (a Admitted) Application() Application

func (a Admitted) Validate() error

type Application ¶

type Application struct {
	CommandID        CommandID `json:"command_id"`
	RuntimeCommandID uuid.UUID `json:"runtime_command_id"`
	LeaseEpoch       uint64    `json:"lease_epoch"`
	// Kind is the admitted command's kind. It is part of the correlation because
	// the released SessionStore reader correlates on it: a prefix whose kind
	// disagrees with the inbox record's resolves CONFLICTED, not applied. Omitting
	// it would make every application unmatchable by the counterparty.
	Kind Kind `json:"command_kind"`
}

Application is the private durable correlation an applier writes BEFORE the effect: the public id, the one runtime id it maps to, and the lease epoch the application ran under. It is the whole content of the application prefix — no payload, no user content — because its only job is to answer "was this public command already applied, and under which runtime identity?".

Known gap, recorded so it is a decision rather than an oversight: it carries no loop id. KindInput dispatches to the session's ACTIVE loop, and which loop that was is not recoverable from this record — neither recovery nor an audit can say where an admitted command landed. Nothing in the current contract needs it (the runtime id correlates the events, and the events carry the loop), but a per-loop-addressed admitted command would need this field, and adding it later changes the persisted body and therefore every existing record's fingerprint.

func (a Application) Validate() error

type Applier ¶

type Applier interface {
	// ApplyRuntimeCommand durably records the application prefix and then applies
	// the command, returning the disposition. A duplicate delivery returns the
	// original disposition and applies nothing.
	//
	// A non-nil error does not license a retry. The prefix is written BEFORE the
	// effect, so an error raised by the effect leaves a durable prefix behind and
	// every later delivery deduplicates against it. Re-deliver and read
	// Disposition.Duplicate to learn what happened; do not assume an error means
	// nothing was recorded.
	//
	// A returned Disposition also does not mean the application will SETTLE. The
	// durable settlement correlation resolves an application by finding the public
	// event adjacent to its prefix, and adjacency is not guaranteed for any command
	// kind: another writer's record in that slot leaves the application unresolved
	// forever. Unresolved never licenses a rejection, so nothing is applied twice and
	// nothing is settled over — but a caller that BLOCKS on an application settling
	// blocks indefinitely. Treat the Disposition as the answer, not as a promise that
	// a later durable query will agree.
	ApplyRuntimeCommand(context.Context, Admitted) (Disposition, error)
}

Applier is the SEGREGATED runtime-command capability. It is deliberately not a method on session.Session: almost every Session implementation — every test double, every adapter, the TUI's view — will never apply an admitted command, and widening the base contract would force all of them to grow a method they cannot honor. A caller obtains one through Provider.

type CapabilityUnavailableError ¶

type CapabilityUnavailableError struct{ CommandID CommandID }

CapabilityUnavailableError reports that ApplyRuntimeCommand was called on a session that does not advertise the capability. A caller that went through Provider.RuntimeCommands never sees it; it exists so a caller that reached the method by a bare type assertion fails loudly instead of silently applying a command with no durable correlation.

func (e *CapabilityUnavailableError) Error() string

type CommandID ¶

type CommandID string

CommandID is the public, retry-stable command identity Host owns. It is opaque to Harness; see the package doc for why it is never parsed as a UUID.

func (id CommandID) Validate() error

type Disposition ¶

type Disposition struct {
	// CommandID echoes the public id this disposition answers for.
	CommandID CommandID
	// RuntimeCommandID is the durable runtime identity of the application.
	RuntimeCommandID uuid.UUID
	// PrefixSequence is the journal sequence of the application prefix. For a
	// duplicate it is the ORIGINAL append's sequence, never a new one.
	PrefixSequence uint64
	// Duplicate reports that this delivery applied nothing because the command was
	// already applied.
	Duplicate bool
	// Interrupted reports, for KindInterrupt, whether a running turn was cancelled.
	// It is the TRANSIENT outcome of an application, not part of the durable prefix,
	// so a duplicate delivery always reports false: the prefix records the
	// correlation, never the outcome. Read it only alongside Duplicate.
	Interrupted bool
}

Disposition is what an application resolved to. A duplicate delivery reports the ORIGINAL disposition — the same runtime id and the same prefix sequence the first delivery reported — with Duplicate set, so a caller can distinguish "applied by this call" from "already applied" without being able to confuse the two.

type Kind ¶

type Kind string

Kind is the bounded set of admitted commands Harness can apply through this seam. It is deliberately small: every kind here must have an existing runtime dispatch path, so a new kind is a new implementation, never a new default.

const (
	// KindInput applies admitted user input to the session's active loop.
	KindInput Kind = "input"
	// KindInterrupt applies a session-wide interrupt.
	KindInterrupt Kind = "interrupt"
)

func (k Kind) Valid() bool

type LeaseLostError ¶

type LeaseLostError struct {
	CommandID CommandID
	Epoch     uint64
}

LeaseLostError reports that the applier's session lease is no longer held, so no effect may be applied under it.

func (e *LeaseLostError) Error() string

type MappingConflictError ¶

type MappingConflictError struct {
	CommandID CommandID
	// RuntimeCommandID is the id the offered delivery carried.
	RuntimeCommandID uuid.UUID
	// DurableRuntimeID is the id the durable application prefix holds. It is zero
	// when the prefix could not be read; see Cause.
	DurableRuntimeID uuid.UUID
	// Kind is the kind the offered delivery carried, and DurableKind the kind the
	// durable prefix holds. They are compared because the RELEASED reader compares
	// them: a prefix whose kind disagrees with the inbox record's resolves
	// CONFLICTED. Ignoring the kind here would have Harness report already-applied
	// for a shape the counterparty refuses.
	Kind        Kind
	DurableKind Kind
	// Sequence is the journal sequence of the durable prefix.
	Sequence uint64
	Cause    error
}

MappingConflictError reports that the public CommandID is already durable under a mapping this delivery may not be applied against. It covers two situations that must both fail closed, and the two are distinguishable — do not collapse them.

A CONFLICT: the durable prefix was read and binds this public id to a DIFFERENT RuntimeCommandID. That is never a legitimate retry, because a retry of an admitted command carries the mapping Host allocated once. DurableRuntimeID is set.

An UNREADABLE prefix: the durable frame at Sequence could not be read at all, so the mapping is UNKNOWN. DurableRuntimeID is then zero and Cause is the read failure. Reporting this as a duplicate would tell Host "already applied" about a command that may never have been applied.

Error() distinguishes them. The unreadable arm must not name a mapping: printing an all-zero DurableRuntimeID as though it had been read is a message that contradicts its own Cause, and it sends a reader hunting for a runtime command that does not exist.

func (e *MappingConflictError) Error() string

func (e *MappingConflictError) Unwrap() error

type Provider ¶

type Provider interface {
	RuntimeCommands() (Applier, bool)
}

Provider is implemented by a session that MAY be able to apply admitted runtime commands. RuntimeCommands reports the capability: ok is false — with a nil Applier — for a session with no durable, deduplicating application-prefix log, which includes a headless/no-persistence session.

The two-result form is the point, exactly as it is for the committed-public-event capability: a single-result form would hand back an applier that fails only after Host has already acknowledged the command as accepted.

type StaleLeaseEpochError ¶

type StaleLeaseEpochError struct {
	CommandID CommandID
	Admitted  uint64
	Current   uint64
}

StaleLeaseEpochError reports an admitted record whose lease epoch is not the epoch the applier currently holds. Applying it would let a superseded owner's admission take effect under a lease it no longer holds.

func (e *StaleLeaseEpochError) Error() string

type ValidationError ¶

type ValidationError struct {
	Field  string
	Reason string
}

ValidationError reports a malformed admitted record or correlation.

func (e *ValidationError) Error() string