v1

type AgentCapabilitySummary ¶

type AgentCapabilitySummary struct {
	AgentID                AgentID  `json:"agent_id"`
	RuntimeCompatibilityID string   `json:"runtime_compatibility_id"`
	Capabilities           []string `json:"capabilities,omitempty"`
	// contains filtered or unexported fields
}

AgentCapabilitySummary advertises one Department member's stable identity and explicit runtime compatibility boundary without exposing launch internals.

func (s AgentCapabilitySummary) AdditionalFields() map[string]json.RawMessage

func (s AgentCapabilitySummary) MarshalJSON() ([]byte, error)

func (s *AgentCapabilitySummary) UnmarshalJSON(data []byte) error

func (s AgentCapabilitySummary) Validate() error

type AgentID ¶

type AgentID string

AgentID identifies an agent participating in a session.

func (id AgentID) Validate() error

type CommandEnvelope ¶

type CommandEnvelope struct {
	Version   WireVersion `json:"version"`
	CommandID CommandID   `json:"command_id"`
}

CommandEnvelope is common to every state-changing V1 request. CommandID is client-generated and retry-stable; Version is the Looprig wire version, not a transport or broker version.

func (e CommandEnvelope) Validate() error

type CommandID ¶

type CommandID string

CommandID identifies a client command. It is an opaque, non-empty UTF-8 string of at most MaxIDBytes bytes; in particular, it is not a UUID.

func DeterministicCommandID(domain string, fields ...string) (CommandID, error)

func (id *CommandID) UnmarshalJSON(data []byte) error

func (id CommandID) Validate() error

type CommandIDFramingCode ¶

type CommandIDFramingCode string

CommandIDFramingCode is a stable machine-readable reason a deterministic command ID cannot be framed.

const (
	// CommandIDFramingCodeTooManyFields reports a field count larger than a
	// uint32 can represent.
	CommandIDFramingCodeTooManyFields CommandIDFramingCode = "too_many_fields"
	// CommandIDFramingCodeFieldTooLong reports a UTF-8 field larger than a
	// uint32 can represent.
	CommandIDFramingCodeFieldTooLong CommandIDFramingCode = "field_too_long"
)

type CommandIDFramingError ¶

type CommandIDFramingError struct {
	Code CommandIDFramingCode
}

CommandIDFramingError reports a deterministic command ID input that cannot be represented by the version 1 framing. Code is stable for callers that need to distinguish framing failures without matching Error.

func (e *CommandIDFramingError) Error() string

type CommandState ¶

type CommandState string

CommandState records the durable command-admission lifecycle visible to a caller. Accepted means the inbox commit succeeded; it does not promise that a Host has already applied the command.

const (
	CommandStateAccepted CommandState = "accepted"
	CommandStatePending  CommandState = "pending"
	CommandStateApplied  CommandState = "applied"
	CommandStateRejected CommandState = "rejected"
)

type CommandStatus ¶

type CommandStatus struct {
	CommandID     CommandID    `json:"command_id"`
	State         CommandState `json:"status"`
	AcceptedOrder uint64       `json:"accepted_order,omitempty"`
	Error         *ErrorDetail `json:"error,omitempty"`
	// contains filtered or unexported fields
}

CommandStatus is the forward-compatible public representation of an accepted command. Rejected commands carry a stable ErrorDetail rather than a provider or runtime cause.

func (s CommandStatus) AdditionalFields() map[string]json.RawMessage

func (s CommandStatus) MarshalJSON() ([]byte, error)

func (s *CommandStatus) UnmarshalJSON(data []byte) error

func (s CommandStatus) Validate() error

type CreateRequest ¶

type CreateRequest struct {
	CommandEnvelope
	SessionID SessionID       `json:"session_id"`
	AgentID   AgentID         `json:"agent_id"`
	Blocks    json.RawMessage `json:"blocks,omitempty"`
}

CreateRequest admits a new durable session. SessionID is supplied by the client so a retry after an unknown outcome can reuse the same (SessionID, CommandID) pair; it is intentionally not server-minted here.

func (r *CreateRequest) UnmarshalJSON(data []byte) error

func (r CreateRequest) Validate() error

type Cursor ¶

type Cursor string

Cursor is an opaque, server-issued page token. Clients may retain and return it but must not derive ordering, tenancy, or authority from its contents.

type DepartmentCapabilitySummary ¶

type DepartmentCapabilitySummary struct {
	Agents []AgentCapabilitySummary `json:"agents"`
	// contains filtered or unexported fields
}

DepartmentCapabilitySummary is the transport-neutral capability discovery response for a Host Department or a Factory projection of one.

func (s DepartmentCapabilitySummary) AdditionalFields() map[string]json.RawMessage

func (s DepartmentCapabilitySummary) MarshalJSON() ([]byte, error)

func (s *DepartmentCapabilitySummary) UnmarshalJSON(data []byte) error

func (s DepartmentCapabilitySummary) Validate() error

type EnduringPublication ¶

type EnduringPublication struct {
	TenantID       TenantID        `json:"tenant_id"`
	SessionID      SessionID       `json:"session_id"`
	EventID        EventID         `json:"event_id"`
	JournalSeq     uint64          `json:"journal_seq"`
	CoveredThrough uint64          `json:"covered_through"`
	Body           json.RawMessage `json:"body"`
	// contains filtered or unexported fields
}

EnduringPublication is a committed public journal event carried over a live link. Body is already canonical public JSON and remains opaque to Core. The durable identity and sequence let a consumer join this fast path with a bounded journal read after reconnect or overflow.

func (p EnduringPublication) AdditionalFields() map[string]json.RawMessage

func (p EnduringPublication) MarshalJSON() ([]byte, error)

func (p EnduringPublication) RecordType() SessionRecordType

func (p *EnduringPublication) UnmarshalJSON(data []byte) error

func (p EnduringPublication) Validate() error

type EphemeralPublication ¶

type EphemeralPublication struct {
	TenantID  TenantID        `json:"tenant_id"`
	SessionID SessionID       `json:"session_id"`
	Body      json.RawMessage `json:"body"`
	// contains filtered or unexported fields
}

EphemeralPublication is a best-effort public live delta. It is deliberately not a durable event: it has no EventID, journal sequence, or coverage watermark and may be coalesced or dropped by a bounded delivery path.

func (p EphemeralPublication) AdditionalFields() map[string]json.RawMessage

func (p EphemeralPublication) MarshalJSON() ([]byte, error)

func (p EphemeralPublication) RecordType() SessionRecordType

func (p *EphemeralPublication) UnmarshalJSON(data []byte) error

func (p EphemeralPublication) Validate() error

type ErrorCode ¶

type ErrorCode string

ErrorCode is a stable public error discriminator. Factory maps transport and domain failures into this vocabulary without exposing implementation causes.

const (
	ErrorCodeInvalidRequest      ErrorCode = "invalid_request"
	ErrorCodeUnsupportedVersion  ErrorCode = "unsupported_version"
	ErrorCodeSessionNotFound     ErrorCode = "session_not_found"
	ErrorCodeCommandRejected     ErrorCode = "command_rejected"
	ErrorCodeGateResolved        ErrorCode = "gate_resolved"
	ErrorCodeGateNotResumable    ErrorCode = "gate_not_resumable"
	ErrorCodeGateExpired         ErrorCode = "gate_expired"
	ErrorCodeGateResponseInvalid ErrorCode = "gate_response_invalid"
	ErrorCodeRuntimeUnavailable  ErrorCode = "runtime_unavailable"
)

type ErrorDetail ¶

type ErrorDetail struct {
	Code      ErrorCode `json:"code"`
	Message   string    `json:"message,omitempty"`
	Retryable bool      `json:"retryable"`
	// contains filtered or unexported fields
}

ErrorDetail is the client-safe body of a stable error envelope.

func (e ErrorDetail) AdditionalFields() map[string]json.RawMessage

func (e ErrorDetail) MarshalJSON() ([]byte, error)

func (e *ErrorDetail) UnmarshalJSON(data []byte) error

func (e ErrorDetail) Validate() error

type ErrorEnvelope ¶

type ErrorEnvelope struct {
	Error ErrorDetail `json:"error"`
	// contains filtered or unexported fields
}

ErrorEnvelope is a forward-compatible response envelope. Unknown additive top-level fields are retained so a Core consumer can proxy a newer response without silently dropping data it does not yet understand.

func (e ErrorEnvelope) AdditionalFields() map[string]json.RawMessage

func (e ErrorEnvelope) MarshalJSON() ([]byte, error)

func (e *ErrorEnvelope) UnmarshalJSON(data []byte) error

func (e ErrorEnvelope) Validate() error

type EventID ¶

type EventID string

EventID identifies a published session event.

func (id EventID) Validate() error

type GateAnswerability ¶

type GateAnswerability string

GateAnswerability is the durable answerability projection. It is independent from whether a historical prompt can be rendered: an open event alone does not prove that an answer can still be accepted.

const (
	GateAnswerabilityResident    GateAnswerability = "resident"
	GateAnswerabilitySuspended   GateAnswerability = "suspended"
	GateAnswerabilitySubmitted   GateAnswerability = "submitted"
	GateAnswerabilityUnavailable GateAnswerability = "unavailable"
	GateAnswerabilityExpired     GateAnswerability = "expired"
)

type GateControl ¶

type GateControl struct {
	Action string `json:"action"`
	Label  string `json:"label"`
	// contains filtered or unexported fields
}

GateControl is an exact action and display label supplied by the gate owner.

func (c GateControl) AdditionalFields() map[string]json.RawMessage

func (c GateControl) MarshalJSON() ([]byte, error)

func (c *GateControl) UnmarshalJSON(data []byte) error

type GateFieldKind ¶

type GateFieldKind string

GateFieldKind identifies the presentation-safe shape of a prompt field.

const (
	GateFieldKindText        GateFieldKind = "text"
	GateFieldKindSelect      GateFieldKind = "select"
	GateFieldKindMultiSelect GateFieldKind = "multi_select"
	GateFieldKindConfirm     GateFieldKind = "confirm"
)

type GateID ¶

type GateID string

GateID identifies a gate awaiting a response.

func (id GateID) Validate() error

type GatePage ¶

type GatePage struct {
	JournalTip     uint64           `json:"journal_tip"`
	OpenGateCount  uint64           `json:"open_gate_count"`
	Gates          []GateProjection `json:"gates"`
	NextCursor     Cursor           `json:"next_cursor,omitempty"`
	PreviousCursor Cursor           `json:"previous_cursor,omitempty"`
	// contains filtered or unexported fields
}

GatePage is the bounded durable read of open public gates. JournalTip is a captured tip for the projection, and OpenGateCount can exceed len(Gates) when a later API pages a larger open-gate set.

func (p GatePage) AdditionalFields() map[string]json.RawMessage

func (p GatePage) MarshalJSON() ([]byte, error)

func (p *GatePage) UnmarshalJSON(data []byte) error

func (p GatePage) Validate() error

type GateProjection ¶

type GateProjection struct {
	GateID           GateID            `json:"gate_id"`
	Kind             string            `json:"kind"`
	Prompt           GatePrompt        `json:"prompt"`
	OpenedEventID    EventID           `json:"opened_event_id"`
	OpenedJournalSeq uint64            `json:"opened_journal_seq"`
	Deadline         time.Time         `json:"deadline"`
	Answerability    GateAnswerability `json:"answerability"`
	// contains filtered or unexported fields
}

GateProjection is the complete public durable view of an open gate. It joins a presentation-safe prompt with its opening event, effective deadline, and current answerability; it contains no raw answer or private runtime data.

func (p GateProjection) AdditionalFields() map[string]json.RawMessage

func (p GateProjection) MarshalJSON() ([]byte, error)

func (p *GateProjection) UnmarshalJSON(data []byte) error

func (p GateProjection) Validate() error

type GatePrompt ¶

type GatePrompt struct {
	Title    string           `json:"title,omitempty"`
	Body     string           `json:"body,omitempty"`
	Origin   string           `json:"origin,omitempty"`
	Schema   GatePromptSchema `json:"schema"`
	Controls []GateControl    `json:"controls,omitempty"`
	// contains filtered or unexported fields
}

GatePrompt contains only presentation-safe data that a Factory can render. In particular, Origin is the trusted display origin when applicable—not an action URL—and no private payload or signed URL is present.

func (p GatePrompt) AdditionalFields() map[string]json.RawMessage

func (p GatePrompt) MarshalJSON() ([]byte, error)

func (p *GatePrompt) UnmarshalJSON(data []byte) error

func (p GatePrompt) Validate() error

type GatePromptField ¶

type GatePromptField struct {
	Name     string             `json:"name"`
	Label    string             `json:"label"`
	Kind     GateFieldKind      `json:"kind"`
	Required bool               `json:"required"`
	Options  []GatePromptOption `json:"options,omitempty"`
	Default  json.RawMessage    `json:"default,omitempty"`
	// contains filtered or unexported fields
}

GatePromptField is one public structured field. Default is JSON data intended for rendering, not a submitted response value.

func (f GatePromptField) AdditionalFields() map[string]json.RawMessage

func (f GatePromptField) MarshalJSON() ([]byte, error)

func (f *GatePromptField) UnmarshalJSON(data []byte) error

func (f GatePromptField) Validate() error

type GatePromptOption ¶

type GatePromptOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
	// contains filtered or unexported fields
}

GatePromptOption is one presentation-safe selectable option.

func (o GatePromptOption) AdditionalFields() map[string]json.RawMessage

func (o GatePromptOption) MarshalJSON() ([]byte, error)

func (o *GatePromptOption) UnmarshalJSON(data []byte) error

type GatePromptSchema ¶

type GatePromptSchema struct {
	Fields []GatePromptField `json:"fields,omitempty"`
	// contains filtered or unexported fields
}

GatePromptSchema groups the public prompt fields. It deliberately contains no private prepared payload or response data.

func (s GatePromptSchema) AdditionalFields() map[string]json.RawMessage

func (s GatePromptSchema) MarshalJSON() ([]byte, error)

func (s *GatePromptSchema) UnmarshalJSON(data []byte) error

func (s GatePromptSchema) Validate() error

type GateResponseRequest ¶

type GateResponseRequest struct {
	CommandEnvelope
	SessionID              SessionID                  `json:"session_id"`
	GateID                 GateID                     `json:"gate_id"`
	Action                 string                     `json:"action"`
	Values                 map[string]json.RawMessage `json:"values"`
	ExpectedOpenEventID    EventID                    `json:"expected_open_event_id,omitempty"`
	ExpectedOpenJournalSeq uint64                     `json:"expected_open_journal_seq,omitempty"`
	// contains filtered or unexported fields
}

GateResponseRequest admits a private response to one public gate projection. Values are intentionally raw JSON because Harness remains the semantic gate validator; Core only validates the safe structural boundary.

func (r *GateResponseRequest) UnmarshalJSON(data []byte) error

func (r GateResponseRequest) Validate() error

type HostID ¶

type HostID string

HostID identifies the host responsible for a session.

func (id HostID) Validate() error

type HostIsolationClass ¶

type HostIsolationClass string

HostIsolationClass describes whether a Host target advertisement may accept sessions from different tenants. Pooled placement alone does not establish this boundary; Factory uses the advertised class when choosing capacity.

const (
	HostIsolationClassCrossTenantIsolated HostIsolationClass = "cross_tenant_isolated"
	HostIsolationClassTenantExclusive     HostIsolationClass = "tenant_exclusive"
)

type HostLinkAttachMode ¶ added in v0.8.0

type HostLinkAttachMode string

HostLinkAttachMode says whether an attach creates a session or restores one over existing durable state. It is a closed set.

const (
	// HostLinkAttachModeCreate launches a new session.
	HostLinkAttachModeCreate HostLinkAttachMode = "create"
	// HostLinkAttachModeRestore relaunches a session over its durable state.
	HostLinkAttachModeRestore HostLinkAttachMode = "restore"
)

type HostLinkAttachRequest ¶ added in v0.8.0

type HostLinkAttachRequest struct {
	Version                WireVersion        `json:"version"`
	TenantID               TenantID           `json:"tenant_id"`
	SessionID              SessionID          `json:"session_id"`
	HostID                 HostID             `json:"host_id"`
	HostGeneration         uint64             `json:"host_generation"`
	AgentID                AgentID            `json:"agent_id"`
	RuntimeCompatibilityID string             `json:"runtime_compatibility_id"`
	Mode                   HostLinkAttachMode `json:"mode"`
	ActorID                string             `json:"actor_id"`
	TraceID                string             `json:"trace_id,omitempty"`
	IdempotencyKey         string             `json:"idempotency_key"`
}

HostLinkAttachRequest asks one Host incarnation to make one session resident, sent as RPC method HostLinkMethodAttach.

HostID and HostGeneration name the Host incarnation the caller placed the session on (from that Host's HostLinkCapacityReport) and fence the attach as they fence bind, unbind and drain. A Host that is not that incarnation, such as a replacement serving the same endpoint or the same Host restarted, must refuse the attach before it acquires any lease, answering runtime_unavailable as it does for a bind addressed to another Host or an earlier incarnation. Without the fence such a Host would take the session lease and return an observation the caller cannot bind to, stranding the session with no route.

It carries no lease epoch. An attach to a session that is not resident acquires the session lease, which produces a new epoch. An attach to a session this Host already has resident acquires nothing and returns the existing residency with its existing epoch.

Mode rides the wire as the caller's statement of intent. A Host may refuse an attach whose mode contradicts durable state; the one such refusal a Host makes is a restore of a session with no durable state, or with no checkpoint when its target requires one, refused runtime_unavailable. Mode is NOT a create-identity guard. An attach to an already-resident session never reads it, so a create against a live session succeeds idempotently and returns that residency; and a create that meets existing durable state proceeds when the runtime build agrees. Whether a create may meet existing state at all is the create identity's idempotency question, not something this record decides.

ActorID is the requesting SERVICE identity, not an end user. Placement may be driven by a sweeper or reconciler with no live user behind it, so the field names who asked for residency, never whose authority a later command carries. TraceID is optional correlation context and confers nothing.

A Host answers an accepted attach with a HostLinkRegistryObservation as the reply body. Its host_id, host_generation and lease_epoch are what a following HostLinkBindRequest needs, so the caller can bind immediately with the returned epoch. Attach is therefore, like the drain methods, an exception to the empty body that accepts a bind or unbind: a Host must return the observation, not an empty body. A refused attach is answered with the existing HostLinkError vocabulary; the codes an attach may answer are:

• epoch_mismatch: the session lease is held by another owner, so the registry the caller placed from was stale. Its current_lease_epoch is that OTHER holder's epoch, possibly on another Host, and never an epoch this attach produced: a caller must not bind with it.
• runtime_mismatch: the request disagrees with what is running or registered. The runtime build differs from the target's or the durable state's, the target does not support this Host's placement, the session is already resident as a different agent, a dedicated Host is fixed to a different session, or the launched runtime is bound to a different session or agent.
• no_capacity: the target's admission weight exceeds this Host's remaining capacity.
• not_admitting: the Host is draining, or its isolation class forbids admitting this tenant alongside the ones already resident.
• runtime_unavailable: the attach names another Host or an earlier incarnation of this one, the Host registers no usable target for the agent, a restore has no durable state or lacks a checkpoint its target requires, or the launched runtime had already stopped.

A failure that is not a placement outcome carries no HostLinkError code at all. That covers a store that failed, and a launch that fails outright (a runtime that refused to launch, produced nothing, or lacks a capability the Host requires): re-placing it onto another Host running the same build would be a stampede, not a recovery.

func (r HostLinkAttachRequest) MarshalJSON() ([]byte, error)

func (r *HostLinkAttachRequest) UnmarshalJSON(data []byte) error

func (r HostLinkAttachRequest) Validate() error

type HostLinkBindRequest ¶

type HostLinkBindRequest struct {
	Version                WireVersion `json:"version"`
	TenantID               TenantID    `json:"tenant_id"`
	SessionID              SessionID   `json:"session_id"`
	HostID                 HostID      `json:"host_id"`
	HostGeneration         uint64      `json:"host_generation"`
	LeaseEpoch             uint64      `json:"lease_epoch"`
	RuntimeCompatibilityID string      `json:"runtime_compatibility_id"`
	IdempotencyKey         string      `json:"idempotency_key"`
}

HostLinkBindRequest establishes one Factory-local route to a Host-owned session. It is a routing optimization, not proof of ownership: the Host validates the current tuple against its durable lease before accepting it.

func (r HostLinkBindRequest) MarshalJSON() ([]byte, error)

func (r *HostLinkBindRequest) UnmarshalJSON(data []byte) error

func (r HostLinkBindRequest) Validate() error

type HostLinkCapacityReport ¶

type HostLinkCapacityReport struct {
	Version                WireVersion        `json:"version"`
	HostID                 HostID             `json:"host_id"`
	HostGeneration         uint64             `json:"host_generation"`
	AgentID                AgentID            `json:"agent_id"`
	RuntimeCompatibilityID string             `json:"runtime_compatibility_id"`
	Placement              HostPlacement      `json:"placement"`
	InternalEndpoint       InternalEndpoint   `json:"internal_endpoint"`
	IsolationClass         HostIsolationClass `json:"isolation_class"`
	Accepting              bool               `json:"accepting"`
	AvailableCapacity      uint64             `json:"available_capacity"`
	ObservedAt             time.Time          `json:"observed_at"`
	ExpiresAt              time.Time          `json:"expires_at"`
}

HostLinkCapacityReport is a Host's current target-advertisement observation. AvailableCapacity may be zero; that is a valid observation a Factory uses to avoid new placement while still maintaining existing HostLinks.

func (r HostLinkCapacityReport) MarshalJSON() ([]byte, error)

func (r *HostLinkCapacityReport) UnmarshalJSON(data []byte) error

func (r HostLinkCapacityReport) Validate() error

type HostLinkCommandDelivery ¶

type HostLinkCommandDelivery struct {
	CommandID CommandID `json:"command_id"`
}

HostLinkCommandDelivery wakes consumption of an already accepted command on an existing binding. Its only body member is the public, retry-stable CommandID: runtime UUIDs, input blocks, gate answers, and other private payloads remain in the durable inbox and never cross this link.

func (d HostLinkCommandDelivery) MarshalJSON() ([]byte, error)

func (d *HostLinkCommandDelivery) UnmarshalJSON(data []byte) error

func (d HostLinkCommandDelivery) Validate() error

type HostLinkDrainObservation ¶

type HostLinkDrainObservation struct {
	HostID          HostID             `json:"host_id"`
	HostGeneration  uint64             `json:"host_generation"`
	DrainGeneration uint64             `json:"drain_generation"`
	State           HostLinkDrainState `json:"state"`
	TenantID        TenantID           `json:"tenant_id,omitempty"`
	SessionID       SessionID          `json:"session_id,omitempty"`
}

HostLinkDrainObservation acknowledges a drain initiation and exposes its stable generation/state for a Factory to observe without inferring release completion from a transport close.

func (o HostLinkDrainObservation) MarshalJSON() ([]byte, error)

func (o *HostLinkDrainObservation) UnmarshalJSON(data []byte) error

func (o HostLinkDrainObservation) Validate() error

type HostLinkDrainRequest ¶

type HostLinkDrainRequest struct {
	Version        WireVersion `json:"version"`
	HostID         HostID      `json:"host_id"`
	HostGeneration uint64      `json:"host_generation"`
	IdempotencyKey string      `json:"idempotency_key"`
	TenantID       TenantID    `json:"tenant_id,omitempty"`
	SessionID      SessionID   `json:"session_id,omitempty"`
}

HostLinkDrainRequest starts idempotent Host draining. A missing tenant/session scope means whole-Host drain; both present scopes identify the fixed session of a dedicated Host. This request does not contain user authority or a deadline.

func (r HostLinkDrainRequest) MarshalJSON() ([]byte, error)

func (r *HostLinkDrainRequest) UnmarshalJSON(data []byte) error

func (r HostLinkDrainRequest) Validate() error

type HostLinkDrainState ¶

type HostLinkDrainState string

HostLinkDrainState is the bounded public result of a drain observation.

const (
	// HostLinkDrainStateDraining means admission is stopped and durable release
	// work is in progress.
	HostLinkDrainStateDraining HostLinkDrainState = "draining"
	// HostLinkDrainStateDrained means the observed scope has finished release.
	HostLinkDrainStateDrained HostLinkDrainState = "drained"
)

type HostLinkError ¶

type HostLinkError struct {
	Code                   HostLinkErrorCode `json:"code"`
	CurrentLeaseEpoch      uint64            `json:"current_lease_epoch,omitempty"`
	RuntimeCompatibilityID string            `json:"runtime_compatibility_id,omitempty"`
}

HostLinkError is a safe typed HostLink refusal. CurrentLeaseEpoch is present only for an epoch mismatch; RuntimeCompatibilityID identifies the compatible boundary in a runtime mismatch, never credentials or a raw runtime payload.

func (e HostLinkError) MarshalJSON() ([]byte, error)

func (e *HostLinkError) UnmarshalJSON(data []byte) error

func (e HostLinkError) Validate() error

type HostLinkErrorCode ¶

type HostLinkErrorCode string

HostLinkErrorCode is a stable HostLink control-plane refusal class. It has no provider error string or runtime payload, so callers can act without parsing opaque internals.

const (
	HostLinkErrorNotAdmitting       HostLinkErrorCode = "not_admitting"
	HostLinkErrorReleasing          HostLinkErrorCode = "releasing"
	HostLinkErrorNoCapacity         HostLinkErrorCode = "no_capacity"
	HostLinkErrorEpochMismatch      HostLinkErrorCode = "epoch_mismatch"
	HostLinkErrorRuntimeUnavailable HostLinkErrorCode = "runtime_unavailable"
	HostLinkErrorRuntimeMismatch    HostLinkErrorCode = "runtime_mismatch"
)

type HostLinkRegistryObservation ¶

type HostLinkRegistryObservation struct {
	Version                WireVersion      `json:"version"`
	TenantID               TenantID         `json:"tenant_id"`
	SessionID              SessionID        `json:"session_id"`
	HostID                 HostID           `json:"host_id"`
	HostGeneration         uint64           `json:"host_generation"`
	AgentID                AgentID          `json:"agent_id"`
	RuntimeCompatibilityID string           `json:"runtime_compatibility_id"`
	Placement              HostPlacement    `json:"placement"`
	InternalEndpoint       InternalEndpoint `json:"internal_endpoint"`
	Residency              SessionResidency `json:"residency"`
	Accepting              bool             `json:"accepting"`
	LeaseEpoch             uint64           `json:"lease_epoch"`
	ObservedAt             time.Time        `json:"observed_at"`
	ExpiresAt              time.Time        `json:"expires_at"`
}

HostLinkRegistryObservation is a current Host-owned session location hint. It is not ownership proof: SessionStore's lease and epoch fence remain authoritative even while the observation is fresh.

func (r HostLinkRegistryObservation) MarshalJSON() ([]byte, error)

func (r *HostLinkRegistryObservation) UnmarshalJSON(data []byte) error

func (r HostLinkRegistryObservation) Validate() error

type HostLinkUnbindRequest ¶

type HostLinkUnbindRequest struct {
	Version        WireVersion `json:"version"`
	TenantID       TenantID    `json:"tenant_id"`
	SessionID      SessionID   `json:"session_id"`
	HostID         HostID      `json:"host_id"`
	HostGeneration uint64      `json:"host_generation"`
	LeaseEpoch     uint64      `json:"lease_epoch"`
	IdempotencyKey string      `json:"idempotency_key"`
}

HostLinkUnbindRequest removes one Factory-local route. Repeating the same tuple/key is safe; it never releases the Host's lease or durable session.

func (r HostLinkUnbindRequest) MarshalJSON() ([]byte, error)

func (r *HostLinkUnbindRequest) UnmarshalJSON(data []byte) error

func (r HostLinkUnbindRequest) Validate() error

type HostPlacement ¶

type HostPlacement string

HostPlacement identifies the admission model for one Host advertisement. It is a bounded routing label, not a request to create or attach a session.

const (
	HostPlacementPooled    HostPlacement = "pooled"
	HostPlacementDedicated HostPlacement = "dedicated"
)

type IDValidationCode ¶

type IDValidationCode string

IDValidationCode is a stable machine-readable reason an identity is invalid.

const (
	// IDValidationCodeEmpty reports an empty identity.
	IDValidationCodeEmpty IDValidationCode = "empty"
	// IDValidationCodeTooLong reports an identity larger than MaxIDBytes bytes.
	IDValidationCodeTooLong IDValidationCode = "too_long"
	// IDValidationCodeInvalidUTF8 reports an identity that is not valid UTF-8.
	IDValidationCodeInvalidUTF8 IDValidationCode = "invalid_utf8"
)

type IDValidationError ¶

type IDValidationError struct {
	Code IDValidationCode
}

IDValidationError reports a failed identity validation. Code is stable for callers that need to distinguish validation failures without matching Error.

func (e *IDValidationError) Error() string

type InputRequest ¶

type InputRequest struct {
	CommandEnvelope
	SessionID SessionID       `json:"session_id"`
	Blocks    json.RawMessage `json:"blocks"`
}

InputRequest admits input blocks for an existing durable session. The blocks retain their canonical JSON form so Core does not import Harness content types.

func (r *InputRequest) UnmarshalJSON(data []byte) error

func (r InputRequest) Validate() error

type InternalEndpoint ¶

type InternalEndpoint string

InternalEndpoint is a non-secret WebSocket address for an authenticated HostLink. Credentials, signed query parameters, and fragments are prohibited; service authentication is carried by the HostLink adapter rather than this durable routing observation.

func (endpoint InternalEndpoint) Validate() error

type InterruptRequest ¶

type InterruptRequest struct {
	CommandEnvelope
	SessionID SessionID `json:"session_id"`
}

InterruptRequest asks the durable command plane to interrupt the target session. Completion is observed through CommandStatus and public events.

func (r *InterruptRequest) UnmarshalJSON(data []byte) error

func (r InterruptRequest) Validate() error

type JournalEvent ¶

type JournalEvent struct {
	EventID    EventID         `json:"event_id"`
	JournalSeq uint64          `json:"journal_seq"`
	Body       json.RawMessage `json:"body"`
	// contains filtered or unexported fields
}

JournalEvent is a public durable event. Body is already canonical public JSON and remains opaque to Core: it is neither decoded from nor synthesized from a Harness runtime event.

func (e JournalEvent) AdditionalFields() map[string]json.RawMessage

func (e JournalEvent) MarshalJSON() ([]byte, error)

func (e *JournalEvent) UnmarshalJSON(data []byte) error

func (e JournalEvent) Validate() error

type JournalPage ¶

type JournalPage struct {
	Events         []JournalEvent `json:"events"`
	CapturedTip    uint64         `json:"journal_tip"`
	CoveredThrough uint64         `json:"covered_through"`
	NextCursor     Cursor         `json:"next_cursor,omitempty"`
	PreviousCursor Cursor         `json:"previous_cursor,omitempty"`
	// contains filtered or unexported fields
}

JournalPage is a bounded public journal response captured at CapturedTip. CoveredThrough can advance across private ledger records, but never reveals their kind or bytes; clients may only use this authenticated watermark to close a sequence gap.

func (p JournalPage) AdditionalFields() map[string]json.RawMessage

func (p JournalPage) MarshalJSON() ([]byte, error)

func (p *JournalPage) UnmarshalJSON(data []byte) error

func (p JournalPage) Validate() error

type JournalTip ¶

type JournalTip struct {
	TenantID  TenantID  `json:"tenant_id"`
	SessionID SessionID `json:"session_id"`
	Tip       uint64    `json:"journal_tip"`
	// contains filtered or unexported fields
}

JournalTip is a repeatable repair hint. It is not an acknowledgement or a browser cursor: a client compares Tip with its own covered sequence and reads any missing public pages through the durable query plane.

func (h JournalTip) AdditionalFields() map[string]json.RawMessage

func (h JournalTip) MarshalJSON() ([]byte, error)

func (h JournalTip) RecordType() SessionRecordType

func (h *JournalTip) UnmarshalJSON(data []byte) error

func (h JournalTip) Validate() error

type ObjectMetadata ¶

type ObjectMetadata struct {
	Reference ObjectReference `json:"reference"`
	SizeBytes uint64          `json:"size_bytes"`
	MediaType string          `json:"media_type,omitempty"`
	Digest    string          `json:"digest,omitempty"`
	CreatedAt time.Time       `json:"created_at,omitzero"`
}

ObjectMetadata describes an immutable logical object without exposing a provider URL, credential, backend path, or object bytes.

func (m *ObjectMetadata) UnmarshalJSON(data []byte) error

func (m ObjectMetadata) Validate() error

type ObjectReference ¶

type ObjectReference struct {
	ObjectID string `json:"object_id"`
}

ObjectReference is an opaque logical object identity. It is not a bucket key, signed URL, credential, or a byte payload.

Unlike forward-compatible public projection records, object records are a redaction boundary: unknown JSON members are intentionally not retained or re-emitted, so a provider URL, credential, or object bytes cannot be proxied.

func (r *ObjectReference) UnmarshalJSON(data []byte) error

func (r ObjectReference) Validate() error

type RequestValidationCode ¶

type RequestValidationCode string

RequestValidationCode is a stable, transport-neutral reason a request record could not be decoded or validated. It intentionally names fields, never values, so request payloads such as gate answers do not leak through an error string.

const (
	RequestValidationCodeInvalidJSON        RequestValidationCode = "invalid_json"
	RequestValidationCodeDuplicateField     RequestValidationCode = "duplicate_field"
	RequestValidationCodeUnknownField       RequestValidationCode = "unknown_field"
	RequestValidationCodeMissingField       RequestValidationCode = "missing_required_field"
	RequestValidationCodeInvalidField       RequestValidationCode = "invalid_field"
	RequestValidationCodeUnsupportedVersion RequestValidationCode = "unsupported_version"
)

type RequestValidationError ¶

type RequestValidationError struct {
	Code  RequestValidationCode
	Field string
}

RequestValidationError reports a structural V1 request failure. Field is a stable field name rather than a caller-provided value.

func (e *RequestValidationError) Error() string

type RestoreRequest ¶

type RestoreRequest struct {
	CommandEnvelope
	SessionID SessionID `json:"session_id"`
}

RestoreRequest is the explicit wire-compatibility request. New clients rely on normal durable command admission and placement; this record keeps the staged route explicit without making a read trigger restoration.

func (r *RestoreRequest) UnmarshalJSON(data []byte) error

func (r RestoreRequest) Validate() error

type SessionID ¶

type SessionID string

SessionID identifies one session within a tenant.

func (id SessionID) Validate() error

type SessionPage ¶

type SessionPage struct {
	Sessions       []SessionSummary `json:"sessions"`
	NextCursor     Cursor           `json:"next_cursor,omitempty"`
	PreviousCursor Cursor           `json:"previous_cursor,omitempty"`
	// contains filtered or unexported fields
}

SessionPage is a bounded recent-first page. It is a durable read and never restores a cold session as a side effect.

func (p SessionPage) AdditionalFields() map[string]json.RawMessage

func (p SessionPage) MarshalJSON() ([]byte, error)

func (p *SessionPage) UnmarshalJSON(data []byte) error

func (p SessionPage) Validate() error

type SessionRecordType ¶

type SessionRecordType string

SessionRecordType is the stable wire name of a record carried on the tenant-scoped session channel `session:{tid}:{sid}` (specification 8.1). One subscriber receives every publication, repair hint, and repair control on that single channel, so each record names its own kind in the `type` envelope member rather than leaving a consumer to infer a kind from which optional members happen to be present.

The two spec-named values are used verbatim: specification 17.3 and 21 name the `session.reset` repair control and the repeatable `journal_tip` hint. A dotted name follows the control/RPC namespace the specification already uses for `session.input`, `session.interrupt`, and `gate.respond`; the two publication records are data rather than controls and use the snake_case record names their schemas and fixtures are already published under.

The discriminator belongs to the envelope. It never enters the opaque relayed event body, so the canonical byte-identical relay contract is unchanged.

const (
	SessionRecordTypeEnduringPublication  SessionRecordType = "enduring_publication"
	SessionRecordTypeEphemeralPublication SessionRecordType = "ephemeral_publication"
	SessionRecordTypeJournalTip           SessionRecordType = "journal_tip"
	SessionRecordTypeSessionReset         SessionRecordType = "session.reset"
)

func SessionRecordTypeOf(data []byte) (SessionRecordType, error)

type SessionReset ¶

type SessionReset struct {
	TenantID       TenantID  `json:"tenant_id"`
	SessionID      SessionID `json:"session_id"`
	LastContiguous uint64    `json:"last_contiguous"`
	JournalTip     uint64    `json:"journal_tip"`
	// contains filtered or unexported fields
}

SessionReset is a repeatable repair control sent after a bounded delivery path loses an enduring frame. LastContiguous is the greatest sequence the sender knows it forwarded in order; JournalTip is one durable tip captured for the receiver's subsequent bounded repair reads.

func (r SessionReset) AdditionalFields() map[string]json.RawMessage

func (r SessionReset) MarshalJSON() ([]byte, error)

func (r SessionReset) RecordType() SessionRecordType

func (r *SessionReset) UnmarshalJSON(data []byte) error

func (r SessionReset) Validate() error

type SessionResidency ¶

type SessionResidency string

SessionResidency is independent from SessionState: an idle session can remain resident and a cold session remains readable.

const (
	SessionResidencyCold      SessionResidency = "cold"
	SessionResidencyAttaching SessionResidency = "attaching"
	SessionResidencyResident  SessionResidency = "resident"
	SessionResidencyReleasing SessionResidency = "releasing"
)

type SessionState ¶

type SessionState string

SessionState is the durable execution-state projection. Values may grow in a future wire version; a consumer must treat an unfamiliar non-empty value as a state it cannot actively control rather than as a missing session.

const (
	SessionStateRunning       SessionState = "running"
	SessionStateWaitingOnGate SessionState = "waiting_on_gate"
	SessionStateSuspended     SessionState = "suspended"
	SessionStateRestoring     SessionState = "restoring"
	SessionStateIdle          SessionState = "idle"
	SessionStateFailed        SessionState = "failed"
	SessionStateInterrupted   SessionState = "interrupted"
	SessionStateStopped       SessionState = "stopped"
)

type SessionStatus ¶

type SessionStatus struct {
	SessionID     SessionID        `json:"session_id"`
	AgentID       AgentID          `json:"agent_id"`
	State         SessionState     `json:"state"`
	Residency     SessionResidency `json:"residency"`
	JournalTip    uint64           `json:"journal_tip"`
	WaitingGateID GateID           `json:"waiting_gate_id,omitempty"`
	UpdatedAt     time.Time        `json:"updated_at,omitzero"`
	// contains filtered or unexported fields
}

SessionStatus is the replay-free durable state for one session. It reports only projections that remain available while every Host is stopped.

func (s SessionStatus) AdditionalFields() map[string]json.RawMessage

func (s SessionStatus) MarshalJSON() ([]byte, error)

func (s *SessionStatus) UnmarshalJSON(data []byte) error

func (s SessionStatus) Validate() error

type SessionSummary ¶

type SessionSummary struct {
	SessionID    SessionID    `json:"session_id"`
	AgentID      AgentID      `json:"agent_id"`
	State        SessionState `json:"state"`
	Title        string       `json:"title,omitempty"`
	CreatedAt    time.Time    `json:"created_at,omitzero"`
	LastActiveAt time.Time    `json:"last_active_at"`
	// contains filtered or unexported fields
}

SessionSummary is the bounded, picker-facing durable projection used in a recent-first SessionPage. It deliberately contains no live Host route.

func (s SessionSummary) AdditionalFields() map[string]json.RawMessage

func (s SessionSummary) MarshalJSON() ([]byte, error)

func (s *SessionSummary) UnmarshalJSON(data []byte) error

func (s SessionSummary) Validate() error

type TenantID ¶

type TenantID string

TenantID identifies the tenant that owns a session.

func (id TenantID) Validate() error

type VersionNegotiationRequest ¶

type VersionNegotiationRequest struct {
	SupportedVersions []WireVersion `json:"supported_versions"`
}

VersionNegotiationRequest advertises the sessionwire versions a peer can speak before any versioned HostLink control records are accepted.

func (r VersionNegotiationRequest) MarshalJSON() ([]byte, error)

func (r *VersionNegotiationRequest) UnmarshalJSON(data []byte) error

func (r VersionNegotiationRequest) Validate() error

type VersionNegotiationResponse ¶

type VersionNegotiationResponse struct {
	Version WireVersion `json:"version"`
	// contains filtered or unexported fields
}

VersionNegotiationResponse selects the one current sessionwire version both ends use. Unknown additive response fields are retained for public ClientLink negotiation proxies; HostLink control requests remain strict.

func NegotiateVersion(request VersionNegotiationRequest) (VersionNegotiationResponse, error)

func (r VersionNegotiationResponse) AdditionalFields() map[string]json.RawMessage

func (r VersionNegotiationResponse) MarshalJSON() ([]byte, error)

func (r *VersionNegotiationResponse) UnmarshalJSON(data []byte) error

func (r VersionNegotiationResponse) Validate() error

type WireVersion ¶

type WireVersion uint8

WireVersion identifies a Looprig session wire-contract version.

const CurrentWireVersion WireVersion = 1