spines

Documentation

Index

• Constants
• type DispatchPlanRef
• type IntentCandidateTarget
• type IntentClassification
• type IntentClassificationType
• type IntentEvent
• type IntentInboxItem
• type IntentInboxItemStatus
• type IntentReceipt
• type IntentSource
• type IntentToCandidateResult
• type ReceiptLink
• type SceneFlowRunRef
• type TransactionRef

Constants

const (
	IntentReceiptActionRouted       = "intent_routed"
	IntentReceiptActionPendingOwner = "intent_pending_owner"
	IntentReceiptActionSuppressed   = "intent_suppressed"
)

IntentReceipt actions (closed set, mirrors intent-receipt.schema.json).

Types

type DispatchPlanRef

type DispatchPlanRef struct {
	DispatchPlanRef string `json:"dispatch_plan_ref"`
	TaskRef         string `json:"task_ref"`
	TransactionRef  string `json:"transaction_ref"`
	DispatchType    string `json:"dispatch_type"`
	RequiresBase    bool   `json:"requires_base"`
	BaseDecisionRef string `json:"base_decision_ref,omitempty"`
	IdempotencyKey  string `json:"idempotency_key,omitempty"`
}

DispatchPlanRef is the handoff object from Task Governance to controlled gateways. It remains a candidate plan and never executes by itself.

type IntentCandidateTarget

type IntentCandidateTarget string

IntentCandidateTarget enumerates the EIGHT candidate types an IntentEvent may fan out into. No ninth type may be invented; formal outputs are not targets.

const (
	IntentTargetTaskCandidate                 IntentCandidateTarget = "TaskCandidate"
	IntentTargetMemoryRequestCandidate        IntentCandidateTarget = "MemoryRequestCandidate"
	IntentTargetCommunicationDraftCandidate   IntentCandidateTarget = "CommunicationDraftCandidate"
	IntentTargetExecutionIntentCandidate      IntentCandidateTarget = "ExecutionIntentCandidate"
	IntentTargetBusinessObjectCandidate       IntentCandidateTarget = "BusinessObjectCandidate"
	IntentTargetSceneFlowRunCandidate         IntentCandidateTarget = "SceneFlowRunCandidate"
	IntentTargetCapabilityInvocationCandidate IntentCandidateTarget = "CapabilityInvocationCandidate"
	IntentTargetPackCandidate                 IntentCandidateTarget = "PackCandidate"
)

type IntentClassification

type IntentClassification struct {
	IntentEventID       string                     `json:"intent_event_id"`
	TransactionRef      string                     `json:"transaction_ref"`
	ClassificationTypes []IntentClassificationType `json:"classification_types"`
	CandidateTargets    []IntentCandidateTarget    `json:"candidate_targets,omitempty"`
	CandidateOnly       bool                       `json:"candidate_only"`
	NonFormal           bool                       `json:"non_formal"`
	RequiresBaseGate    bool                       `json:"requires_base_gate"`
	ReceiptRequired     bool                       `json:"receipt_required"`
	RiskClass           string                     `json:"risk_class,omitempty"`
	ModelGatewayRef     string                     `json:"model_gateway_ref,omitempty"`
}

IntentClassification is the candidate-routing decision for one IntentEvent. It never grants execution; requires_base_gate and receipt_required stay true for every downstream formal action.

type IntentClassificationType

type IntentClassificationType string

IntentClassificationType is the closed classification vocabulary. unknown means the event could not be classified and must wait for Owner disposition.

const (
	IntentClassificationTaskRequest          IntentClassificationType = "task_request"
	IntentClassificationCommunicationRequest IntentClassificationType = "communication_request"
	IntentClassificationMemoryRequest        IntentClassificationType = "memory_request"
	IntentClassificationExecutionRequest     IntentClassificationType = "execution_request"
	IntentClassificationObjectUpdateRequest  IntentClassificationType = "object_update_request"
	IntentClassificationSceneFlowTrigger     IntentClassificationType = "scene_flow_trigger"
	IntentClassificationGoalReviewTrigger    IntentClassificationType = "goal_review_trigger"
	IntentClassificationUnknown              IntentClassificationType = "unknown"
)

type IntentEvent

type IntentEvent struct {
	IntentEventID     string       `json:"intent_event_id"`
	Source            IntentSource `json:"source"`
	SourceRef         string       `json:"source_ref,omitempty"`
	RawInputSummary   string       `json:"raw_input_summary"`
	TransactionRef    string       `json:"transaction_ref"`
	ObjectRef         string       `json:"object_ref,omitempty"`
	PersonRef         string       `json:"person_ref,omitempty"`
	RelatedPersonRefs []string     `json:"related_person_refs,omitempty"`
	RelatedObjectRefs []string     `json:"related_object_refs,omitempty"`
	ActorRef          string       `json:"actor_ref,omitempty"`
	RiskHint          string       `json:"risk_hint,omitempty"`
	DesiredOutcome    string       `json:"desired_outcome,omitempty"`
	PayloadHash       string       `json:"payload_hash,omitempty"`
	CandidateTargets  []string     `json:"candidate_targets,omitempty"`
	CandidateOnly     bool         `json:"candidate_only"`
	NonFormal         bool         `json:"non_formal"`
	CreatedAt         time.Time    `json:"created_at"`
}

IntentEvent is the normalized inbox event. It is non-formal until downstream candidates pass their module gates and receive receipts.

type IntentInboxItem

type IntentInboxItem struct {
	IntentInboxItemID   string                     `json:"intent_inbox_item_id"`
	IntentEventID       string                     `json:"intent_event_id"`
	TransactionRef      string                     `json:"transaction_ref"`
	Source              IntentSource               `json:"source"`
	Status              IntentInboxItemStatus      `json:"status"`
	StatusReason        string                     `json:"status_reason,omitempty"`
	ClassificationTypes []IntentClassificationType `json:"classification_types,omitempty"`
	CandidateRefs       []string                   `json:"candidate_refs,omitempty"`
	ReceiptCandidateRef string                     `json:"receipt_candidate_ref,omitempty"`
	CandidateOnly       bool                       `json:"candidate_only"`
	NonFormal           bool                       `json:"non_formal"`
	CreatedAt           time.Time                  `json:"created_at"`
	UpdatedAt           time.Time                  `json:"updated_at"`
}

IntentInboxItem is the per-event inbox row: every intake produces exactly one item keyed by intent_event_id (idempotent replays return the same item).

type IntentInboxItemStatus

type IntentInboxItemStatus string

IntentInboxItemStatus is the inbox disposition state for one IntentEvent.

• routed: classified and fanned out into candidates (refs recorded).
• pending_owner: could not be classified; waits for Owner disposition. It must never be silently dropped.
• suppressed: deliberately produced no candidate cards (e.g. secretary small talk); still recorded for traceability.

const (
	IntentInboxItemRouted       IntentInboxItemStatus = "routed"
	IntentInboxItemPendingOwner IntentInboxItemStatus = "pending_owner"
	IntentInboxItemSuppressed   IntentInboxItemStatus = "suppressed"
)

type IntentReceipt

type IntentReceipt struct {
	ReceiptCandidateRef string    `json:"receipt_candidate_ref"`
	IntentEventID       string    `json:"intent_event_id"`
	TransactionRef      string    `json:"transaction_ref"`
	Action              string    `json:"action"`
	Status              string    `json:"status"`
	CandidateRefs       []string  `json:"candidate_refs,omitempty"`
	EvidenceRefs        []string  `json:"evidence_refs,omitempty"`
	CandidateOnly       bool      `json:"candidate_only"`
	NonFormal           bool      `json:"non_formal"`
	CreatedAt           time.Time `json:"created_at"`
}

IntentReceipt is the candidate-domain receipt of one intake/route step. It is evidence material (ref-only); formal receipts are minted by Base Gate + Receipt Ledger when a candidate later formalizes.

type IntentSource

type IntentSource string

IntentSource classifies every user, external, agent, pack, time, or system input before it fans out into module-specific candidates.

const (
	IntentSourceAgentSuggestionInput IntentSource = "agent_suggestion_input"
	IntentSourceUserMessageInput     IntentSource = "user_message_input"
	IntentSourceExternalMessageInput IntentSource = "external_message_input"
	IntentSourceExternalFileInput    IntentSource = "external_file_input"
	IntentSourceTaskFailureInput     IntentSource = "task_failure_input"
	IntentSourceTimeTriggerInput     IntentSource = "time_trigger_input"
	IntentSourcePackRunEventInput    IntentSource = "pack_run_event_input"
	IntentSourceSceneFlowEventInput  IntentSource = "scene_flow_event_input"
	IntentSourceGoalReviewInput      IntentSource = "goal_review_input"

	IntentSourceUserInput           IntentSource = IntentSourceUserMessageInput
	IntentSourceExternalMessage     IntentSource = IntentSourceExternalMessageInput
	IntentSourceTaskFailure         IntentSource = IntentSourceTaskFailureInput
	IntentSourcePackNodeTrigger     IntentSource = IntentSourcePackRunEventInput
	IntentSourceGoalReview          IntentSource = IntentSourceGoalReviewInput
	IntentSourceAgentSuggestion     IntentSource = IntentSourceAgentSuggestionInput
	IntentSourceTimeTrigger         IntentSource = IntentSourceTimeTriggerInput
	IntentSourceExternalSystemEvent IntentSource = IntentSourceExternalMessageInput
)

type IntentToCandidateResult

type IntentToCandidateResult struct {
	IntentEventID        string                          `json:"intent_event_id"`
	TransactionRef       string                          `json:"transaction_ref"`
	CandidateRefs        []string                        `json:"candidate_refs,omitempty"`
	Candidates           []*candidates.CandidateEnvelope `json:"candidates,omitempty"`
	CandidateOnly        bool                            `json:"candidate_only"`
	NonFormal            bool                            `json:"non_formal"`
	BlockedFormalOutputs []string                        `json:"blocked_formal_outputs,omitempty"`
}

IntentToCandidateResult is the fan-out product: one of the eight candidate types per target, each envelope carrying intent_event_id (payload key "intent_event_id" + SourceEventID) so every candidate is traceable back to its IntentEvent.

type ReceiptLink

type ReceiptLink struct {
	ReceiptRef     string   `json:"receipt_ref"`
	TransactionRef string   `json:"transaction_ref"`
	CandidateRef   string   `json:"candidate_ref,omitempty"`
	DecisionRef    string   `json:"decision_ref,omitempty"`
	ActorRef       string   `json:"actor_ref,omitempty"`
	SourceModule   string   `json:"source_module,omitempty"`
	PayloadHash    string   `json:"payload_hash,omitempty"`
	EvidenceRefs   []string `json:"evidence_refs,omitempty"`
}

ReceiptLink is the evidence edge that makes candidate -> formal transitions replayable through Receipt Ledger.

type SceneFlowRunRef

type SceneFlowRunRef struct {
	SceneFlowRunRef string `json:"scene_flow_run_ref"`
	PackVersionRef  string `json:"pack_version_ref,omitempty"`
	TransactionRef  string `json:"transaction_ref"`
	StepRunRef      string `json:"step_run_ref,omitempty"`
	SourceEventID   string `json:"source_event_id,omitempty"`
	ReceiptRef      string `json:"receipt_ref,omitempty"`
}

SceneFlowRunRef binds a SceneFlowRun to the transaction, originating intent, pack version, current step, and any receipt evidence it emits.

type TransactionRef

type TransactionRef struct {
	TransactionRef  string `json:"transaction_ref"`
	ObjectRef       string `json:"object_ref,omitempty"`
	PersonRef       string `json:"person_ref,omitempty"`
	SourceAuthority string `json:"source_authority,omitempty"`
	IdempotencyKey  string `json:"idempotency_key,omitempty"`
}

TransactionRef is the cross-module anchor for one owner-visible "thing". It may point to a formal TransactionObject, or to a candidate transaction while the object is still under governance review.