Documentation
¶
Overview ¶
Package brand provides branded types to prevent mixing raw strings or bytes across package contracts, matching util/id-brand and util/bytes upstream.
Branded[T] uses empty tag types to distinguish SessionID, ToolCallID, and other identifiers at compile time. Concrete aliases inherit serialization, database, and comparison methods. Construct them with NewSessionID, ParseSessionID, and similar helpers; brand.New[brand.SessionID] would incorrectly nest wrappers. Cross-package contracts should use these concrete types instead of raw values.
Index ¶
- type ApprovalRequestID
- type AttachmentID
- type Branded
- func (b Branded[T]) Equal(other Branded[T]) bool
- func (b Branded[T]) IsZero() bool
- func (b Branded[T]) MarshalJSON() ([]byte, error)
- func (b Branded[T]) Raw() string
- func (b *Branded[T]) Scan(src any) error
- func (b Branded[T]) String() string
- func (b *Branded[T]) UnmarshalJSON(data []byte) error
- func (b Branded[T]) Value() (driver.Value, error)
- type Bytes
- type CredentialRef
- type JobID
- type ProjectionID
- type SessionID
- type SkillID
- type ToolCallID
- type WorkspaceID
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApprovalRequestID ¶
type ApprovalRequestID = Branded[approvalRequestIDTag]
ApprovalRequestID uniquely identifies an approval prompt.
func NewApprovalRequestID ¶
func NewApprovalRequestID(raw string) ApprovalRequestID
NewApprovalRequestID constructs an approval request ID.
func ParseApprovalRequestID ¶
func ParseApprovalRequestID(raw string) (ApprovalRequestID, error)
ParseApprovalRequestID parses and validates an approval request ID.
type AttachmentID ¶
type AttachmentID = Branded[attachmentIDTag]
AttachmentID identifies an image or file in attachment storage.
func NewAttachmentID ¶
func NewAttachmentID(raw string) AttachmentID
NewAttachmentID constructs an attachment ID.
func ParseAttachmentID ¶
func ParseAttachmentID(raw string) (AttachmentID, error)
ParseAttachmentID parses and validates an attachment ID.
type Branded ¶
type Branded[T comparable] struct { // contains filtered or unexported fields }
Branded carries a string with a compile-time tag T. Distinct tags produce incompatible ID types, preventing a SessionID from being used as a ToolCallID. The unexported value is initialized through constructors or UnmarshalJSON.
func (Branded[T]) Equal ¶
Equal compares IDs with the same brand; incompatible brands cannot be compared.
func (Branded[T]) MarshalJSON ¶
MarshalJSON encodes the ID as a JSON string.
func (Branded[T]) Raw ¶
Raw returns the underlying string for external boundaries such as logs and filesystem paths. Cross-package contracts should retain the branded type.
func (*Branded[T]) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON string into the branded ID.
type Bytes ¶
type Bytes[T comparable] struct { // contains filtered or unexported fields }
Bytes carries binary data such as attachments and large tool results. Empty tag types distinguish different byte semantics at compile time.
func NewBytes ¶
func NewBytes[T comparable](raw []byte) Bytes[T]
NewBytes wraps a byte slice; the caller must not mutate it afterward.
func ZeroBytes ¶
func ZeroBytes[T comparable]() Bytes[T]
ZeroBytes returns zero-value branded bytes.
func (Bytes[T]) MarshalJSON ¶
MarshalJSON encodes branded bytes as a base64 JSON string.
func (Bytes[T]) String ¶
String returns the UTF-8 string view, useful for text such as tool results.
func (*Bytes[T]) UnmarshalJSON ¶
UnmarshalJSON decodes a base64 JSON string into branded bytes.
type CredentialRef ¶
type CredentialRef = Branded[credentialRefTag]
CredentialRef brands a POSIX variable name, such as OPENAI_API_KEY.
func NewCredentialRef ¶
func NewCredentialRef(raw string) CredentialRef
NewCredentialRef constructs a credential reference.
func ParseCredentialRef ¶
func ParseCredentialRef(raw string) (CredentialRef, error)
ParseCredentialRef parses and validates a credential reference.
type JobID ¶
type JobID = Branded[jobIDTag]
JobID uniquely identifies a background runtime job.
func ParseJobID ¶
ParseJobID parses and validates a job ID.
type ProjectionID ¶
type ProjectionID = Branded[projectionIDTag]
ProjectionID identifies a registered session projection.
func NewProjectionID ¶
func NewProjectionID(raw string) ProjectionID
NewProjectionID constructs a projection ID.
func ParseProjectionID ¶
func ParseProjectionID(raw string) (ProjectionID, error)
ParseProjectionID parses and validates a projection ID.
type SessionID ¶
type SessionID = Branded[sessionIDTag]
SessionID uniquely identifies an event-sourced SessionLog.
func NewSessionID ¶
NewSessionID constructs a session ID from a raw string.
func ParseSessionID ¶
ParseSessionID validates a session ID, rejecting empty strings.
type SkillID ¶
type SkillID = Branded[skillIDTag]
SkillID identifies a skill in the six-layer registry.
func ParseSkillID ¶
ParseSkillID parses and validates a skill ID.
type ToolCallID ¶
type ToolCallID = Branded[toolCallIDTag]
ToolCallID pairs a tool/call event with its tool/result.
func NewToolCallID ¶
func NewToolCallID(raw string) ToolCallID
NewToolCallID constructs a tool call ID from a raw string.
func ParseToolCallID ¶
func ParseToolCallID(raw string) (ToolCallID, error)
ParseToolCallID parses and validates a tool call ID.
type WorkspaceID ¶
type WorkspaceID = Branded[workspaceIDTag]
WorkspaceID identifies a directory in the workspace registry.
func NewWorkspaceID ¶
func NewWorkspaceID(raw string) WorkspaceID
NewWorkspaceID constructs a workspace ID.
func ParseWorkspaceID ¶
func ParseWorkspaceID(raw string) (WorkspaceID, error)
ParseWorkspaceID parses and validates a workspace ID.