Documentation
¶
Overview ¶
Package souls discovers principal-owned lesser souls and manages local incorporation bindings.
Index ¶
- Variables
- type BootstrapBeginInput
- type BootstrapBeginResult
- type BootstrapConversationCompleteInput
- type BootstrapConversationCompleteResult
- type BootstrapConversationMessageInput
- type BootstrapConversationMessageResult
- type BootstrapFinalizeInput
- type BootstrapFinalizePreflightInput
- type BootstrapFinalizePreflightResult
- type BootstrapFinalizeResult
- type BootstrapFinalizeSigningInput
- type BootstrapPrincipalPreflightInput
- type BootstrapPrincipalPreflightResult
- type BootstrapPrincipalVerifyInput
- type BootstrapPrincipalVerifyResult
- type BootstrapPromotionEvidence
- type BootstrapPublicationEvidence
- type BootstrapWalletChallenge
- type HostBootstrapError
- type Service
- func (s *Service) BeginBootstrapRegistration(ctx context.Context, input BootstrapBeginInput) (*BootstrapBeginResult, error)
- func (s *Service) CompleteBootstrapConversation(ctx context.Context, input BootstrapConversationCompleteInput) (*BootstrapConversationCompleteResult, error)
- func (s *Service) FinalizeBootstrap(ctx context.Context, input BootstrapFinalizeInput) (*BootstrapFinalizeResult, error)
- func (s *Service) Incorporate(ctx context.Context, principalUsername string, targetAgentUsername string, ...) (*Soul, error)
- func (s *Service) ListMine(ctx context.Context, username string) ([]Soul, error)
- func (s *Service) PrepareBootstrapFinalize(ctx context.Context, input BootstrapFinalizePreflightInput) (*BootstrapFinalizePreflightResult, error)
- func (s *Service) PrepareBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalPreflightInput) (*BootstrapPrincipalPreflightResult, error)
- func (s *Service) ResolveBoundAgent(ctx context.Context, agentUsername string) (*Soul, error)
- func (s *Service) SendBootstrapConversationMessage(ctx context.Context, input BootstrapConversationMessageInput) (*BootstrapConversationMessageResult, error)
- func (s *Service) VerifyBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalVerifyInput) (*BootstrapPrincipalVerifyResult, error)
- func (s *Service) WithHTTPClient(client *http.Client) *Service
- func (s *Service) WithHostInstanceKeyResolver(resolver func(context.Context, *config.Config, string) (string, error)) *Service
- type Soul
- type SoulAvatar
- type SoulAvatarStyle
Constants ¶
This section is empty.
Variables ¶
var ( // ErrHostTrustNotConfigured indicates the effective instance trust base URL is unavailable. ErrHostTrustNotConfigured = errors.New("host trust not configured") // ErrHostInstanceKeyMissing indicates no server-side Host instance key can be resolved. ErrHostInstanceKeyMissing = errors.New("host instance key missing") ErrHostInstanceKeyUnavailable = errors.New("host instance key unavailable") ErrHostUnavailable = errors.New("host unavailable") // ErrHostSigningPayloadUnsupported indicates Host returned signing metadata Lesser does not support. ErrHostSigningPayloadUnsupported = errors.New("host signing payload unsupported") )
var ( // ErrTrustNotConfigured indicates the instance trust base URL is unavailable. ErrTrustNotConfigured = errors.New("trust not configured") // ErrSoulNotAvailable indicates a soul is not available to the current authenticated principal. ErrSoulNotAvailable = errors.New("soul not available") // ErrSoulAlreadyBound indicates the target soul is already incorporated elsewhere. ErrSoulAlreadyBound = errors.New("soul already bound") // ErrTargetAgentRequired indicates the incorporation target agent identifier was omitted. ErrTargetAgentRequired = errors.New("target agent is required") // ErrTargetAgentNotFound indicates the requested local target agent does not exist. ErrTargetAgentNotFound = errors.New("target agent not found") // ErrTargetAgentMustBeAgent indicates the requested local target exists but is not an agent account. ErrTargetAgentMustBeAgent = errors.New("target account must be an agent") // ErrTargetAgentNotOwned indicates the requested local target agent is not owned by the authenticated principal. ErrTargetAgentNotOwned = errors.New("target agent not owned by authenticated principal") // ErrTargetAgentAlreadyHasSoul indicates the target local agent is already bound to another soul. ErrTargetAgentAlreadyHasSoul = errors.New("target agent already has soul") )
Functions ¶
This section is empty.
Types ¶
type BootstrapBeginInput ¶ added in v1.5.0
type BootstrapBeginInput struct {
// Username is the Lesser-local body handle Host receives as local_id.
Username string
BodyID string // Lesser-local state/UI identity; never serialized as Host local_id.
WalletAddress string
Capabilities []string
}
BootstrapBeginInput is the Lesser-local request for Host registration begin.
type BootstrapBeginResult ¶ added in v1.5.0
type BootstrapBeginResult struct {
RegistrationID string
HostSoulAgentID string
WalletAddress string
WalletChallenge BootstrapWalletChallenge
HostRequestID string
}
BootstrapBeginResult contains Host begin output needed by the GraphQL state.
type BootstrapConversationCompleteInput ¶ added in v1.5.0
BootstrapConversationCompleteInput is the Lesser-local request for completing a Host mint conversation.
type BootstrapConversationCompleteResult ¶ added in v1.5.0
type BootstrapConversationCompleteResult struct {
RegistrationID string
HostSoulAgentID string
ConversationID string
Status string
ProducedDeclarations string
CompletedAt *time.Time
HostRequestID string
}
BootstrapConversationCompleteResult contains Host completion state.
type BootstrapConversationMessageInput ¶ added in v1.5.0
type BootstrapConversationMessageInput struct {
RegistrationID string
ConversationID string
Message string
Model string
}
BootstrapConversationMessageInput is the Lesser-local request for sending a Host mint-conversation turn through the server-side instance-key route.
type BootstrapConversationMessageResult ¶ added in v1.5.0
type BootstrapConversationMessageResult struct {
RegistrationID string
ConversationID string
Model string
FullResponse string
HostRequestID string
}
BootstrapConversationMessageResult contains the Host conversation ids and terminal assistant response metadata collected from the SSE stream.
type BootstrapFinalizeInput ¶ added in v1.5.0
type BootstrapFinalizeInput struct {
RegistrationID string
ConversationID string
BoundarySignatures map[string]string
IssuedAt time.Time
ExpectedVersion int
SelfAttestation string
}
BootstrapFinalizeInput is the Lesser-local request for Host hosted/off-chain finalize and publication.
type BootstrapFinalizePreflightInput ¶ added in v1.5.0
type BootstrapFinalizePreflightInput struct {
RegistrationID string
ConversationID string
BoundarySignatures map[string]string
}
BootstrapFinalizePreflightInput is the Lesser-local request for Host finalize preflight/signing material.
type BootstrapFinalizePreflightResult ¶ added in v1.5.0
type BootstrapFinalizePreflightResult struct {
Version string
DigestHex string
IssuedAt *time.Time
ExpectedVersion int
NextVersion int
SelfAttestationSigning BootstrapFinalizeSigningInput
BoundaryRequirementsJSON string
FinalizeRequestTemplateJSON string
RegistrationPreviewJSON string
HostRequestID string
}
BootstrapFinalizePreflightResult contains Host-owned finalize signing material. Lesser relays these fields unchanged; it never reconstructs the signing payload locally.
type BootstrapFinalizeResult ¶ added in v1.5.0
type BootstrapFinalizeResult struct {
Version string
HostSoulAgentID string
PublishedVersion int
PrincipalAddress string
Publication BootstrapPublicationEvidence
Promotion BootstrapPromotionEvidence
HostRequestID string
}
BootstrapFinalizeResult contains Host finalize/publication output needed for Lesser local soul binding and workflow projection.
type BootstrapFinalizeSigningInput ¶ added in v1.5.0
type BootstrapFinalizeSigningInput struct {
SignerWallet string
SigningMethod string
MessageEncoding string
MessageHex string
DigestHex string
CanonicalJSON string
}
BootstrapFinalizeSigningInput contains the Host-owned self-attestation signing payload.
type BootstrapPrincipalPreflightInput ¶ added in v1.5.0
type BootstrapPrincipalPreflightInput struct {
RegistrationID string
PrincipalAddress string
PrincipalDeclaration string
DeclaredAt time.Time
}
BootstrapPrincipalPreflightInput is the Lesser-local request for Host principal declaration preflight.
type BootstrapPrincipalPreflightResult ¶ added in v1.5.0
type BootstrapPrincipalPreflightResult struct {
Version string
PrincipalAddress string
SignerAddress string
SigningMethod string
MessageEncoding string
MessageHex string
DigestHex string
CanonicalJSON string
DeclaredAt *time.Time
HostRequestID string
}
BootstrapPrincipalPreflightResult contains Host-owned signing material.
type BootstrapPrincipalVerifyInput ¶ added in v1.5.0
type BootstrapPrincipalVerifyInput struct {
RegistrationID string
WalletSignature string
PrincipalAddress string
PrincipalDeclaration string
PrincipalSignature string
DeclaredAt time.Time
}
BootstrapPrincipalVerifyInput is the Lesser-local request for Host proof verification.
type BootstrapPrincipalVerifyResult ¶ added in v1.5.0
type BootstrapPrincipalVerifyResult struct {
RegistrationID string
HostSoulAgentID string
WalletAddress string
PrincipalAddress string
OperationID string
PromotionStage string
HostRequestID string
}
BootstrapPrincipalVerifyResult contains Host verification output needed by the GraphQL state.
type BootstrapPromotionEvidence ¶ added in v1.5.0
type BootstrapPromotionEvidence struct {
AgentID string
RegistrationID string
Stage string
RequestStatus string
ReviewStatus string
ReadinessStatus string
AnchorState string
LatestConversationID string
LatestConversationStatus string
PublishedVersion int
GraduatedAt *time.Time
}
BootstrapPromotionEvidence contains Host promotion continuity fields.
type BootstrapPublicationEvidence ¶ added in v1.5.0
type BootstrapPublicationEvidence struct {
AgentID string
PublishedVersion int
RegistrationURI string
RegistrationS3Key string
VersionedRegistrationURI string
VersionedRegistrationS3Key string
AnchorState string
PublishedAt *time.Time
}
BootstrapPublicationEvidence contains Host publication evidence for the versioned hosted/off-chain registration artifact.
type BootstrapWalletChallenge ¶ added in v1.5.0
type BootstrapWalletChallenge struct {
ID string
Address string
ChainID int
Nonce string
Message string
IssuedAt *time.Time
ExpiresAt *time.Time
}
BootstrapWalletChallenge contains the Host-issued wallet signing message.
type HostBootstrapError ¶ added in v1.5.0
type HostBootstrapError struct {
Code string
Message string
Source string
StatusCode int
HostRequestID string
Err error
}
HostBootstrapError describes a bounded, client-safe failure returned while talking to Host's instance-key bootstrap API.
func (*HostBootstrapError) Error ¶ added in v1.5.0
func (e *HostBootstrapError) Error() string
func (*HostBootstrapError) Unwrap ¶ added in v1.5.0
func (e *HostBootstrapError) Unwrap() error
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service resolves principal-bound souls for a Lesser instance and manages explicit incorporation bindings.
func NewService ¶
func NewService(accountRepo accountRepository, instanceRepo instanceRepository, cfg *config.Config, logger *zap.Logger) *Service
NewService creates a new soul service.
func (*Service) BeginBootstrapRegistration ¶ added in v1.5.0
func (s *Service) BeginBootstrapRegistration(ctx context.Context, input BootstrapBeginInput) (*BootstrapBeginResult, error)
BeginBootstrapRegistration calls Host's instance-key registration begin route.
func (*Service) CompleteBootstrapConversation ¶ added in v1.5.0
func (s *Service) CompleteBootstrapConversation(ctx context.Context, input BootstrapConversationCompleteInput) (*BootstrapConversationCompleteResult, error)
CompleteBootstrapConversation completes a Host mint conversation and returns the Host-owned declaration output checkpoint.
func (*Service) FinalizeBootstrap ¶ added in v1.5.0
func (s *Service) FinalizeBootstrap(ctx context.Context, input BootstrapFinalizeInput) (*BootstrapFinalizeResult, error)
FinalizeBootstrap relays Host finalize and publication. Hosted/off-chain success does not require on-chain mint transaction fields.
func (*Service) Incorporate ¶
func (s *Service) Incorporate(ctx context.Context, principalUsername string, targetAgentUsername string, agentID string) (*Soul, error)
Incorporate explicitly binds a soul to a local agent chosen by the authenticated principal.
func (*Service) ListMine ¶
ListMine returns the current user's discoverable souls for this instance.
func (*Service) PrepareBootstrapFinalize ¶ added in v1.5.0
func (s *Service) PrepareBootstrapFinalize(ctx context.Context, input BootstrapFinalizePreflightInput) (*BootstrapFinalizePreflightResult, error)
PrepareBootstrapFinalize calls Host finalize preflight and fails closed on unsupported signing metadata.
func (*Service) PrepareBootstrapPrincipalDeclaration ¶ added in v1.5.0
func (s *Service) PrepareBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalPreflightInput) (*BootstrapPrincipalPreflightResult, error)
PrepareBootstrapPrincipalDeclaration calls Host's principal declaration preflight route and fails closed on unsupported signing metadata.
func (*Service) ResolveBoundAgent ¶ added in v1.1.41
ResolveBoundAgent returns the canonical bound soul identity for a local agent username. It returns (nil, nil) when the agent is not soul-bound.
func (*Service) SendBootstrapConversationMessage ¶ added in v1.5.0
func (s *Service) SendBootstrapConversationMessage(ctx context.Context, input BootstrapConversationMessageInput) (*BootstrapConversationMessageResult, error)
SendBootstrapConversationMessage relays one mint-conversation turn to Host's instance-key SSE route and consumes the terminal event so GraphQL receives a bounded same-origin mutation result.
func (*Service) VerifyBootstrapPrincipalDeclaration ¶ added in v1.5.0
func (s *Service) VerifyBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalVerifyInput) (*BootstrapPrincipalVerifyResult, error)
VerifyBootstrapPrincipalDeclaration calls Host's combined wallet/proof/ principal declaration verification route.
func (*Service) WithHTTPClient ¶
WithHTTPClient overrides the HTTP client used for lesser-host requests.
type Soul ¶
type Soul struct {
AgentID string
Domain string
LocalID string
ENSName *string
Wallet string
TokenID string
MetaURI string
Avatar *SoulAvatar
PrincipalAddress string
PrincipalSignature string
PrincipalDeclaration string
PrincipalDeclaredAt string
Status string
LifecycleStatus string
LifecycleReason string
SuccessorAgentID string
PredecessorAgentID string
SelfDescriptionVersion *int
Capabilities []string
MintTxHash string
MintedAt *time.Time
UpdatedAt *time.Time
Bound bool
BoundAgentUsername string
BoundPrincipalAddress string
BoundAt time.Time
BoundUpdatedAt time.Time
}
Soul represents a host-discovered soul plus local binding state.
type SoulAvatar ¶ added in v1.2.14
type SoulAvatar struct {
TokenURI string
Image string
CurrentStyleID *int
CurrentStyleName string
CurrentRendererAddress string
Styles []SoulAvatarStyle
}
SoulAvatar represents the current soul avatar plus all configured style variants.