detectiveknowledge

Documentation

Overview

Package detectiveknowledge owns the private, reviewable knowledge proposal contract shared by local and hosted Detective stores. Preparing a handoff never writes to MeaningGraph or ModelSpec.

Index

• Constants
• Variables
• func PrepareHandoff(old Proposal, ifMatch int64, target Target, actor, receipt string, ...) (Proposal, Handoff, error)
• func ValidateActionShape(a Action) error
• func ValidateDraft(p Proposal) error
• func ValidateReferences(p Proposal, facts EvidenceFacts) error
• func ValidateTarget(t *Target) error
• type Action
• type EvidenceFacts
• type FindingFact
• type Handoff
• type Page
• type Proposal
  • func Review(old Proposal, ifMatch int64, decision, note, actor string, at time.Time) (Proposal, error)
  • func SaveDraft(old *Proposal, draft Proposal, ifMatch int64, actor string, at time.Time) (Proposal, error)
• type Response
• type Target

Constants

const MaxHandoffs = 20

Variables

var (
	ErrInvalid  = errors.New("invalid detective knowledge proposal")
	ErrConflict = errors.New("detective knowledge version conflict")
	ErrCapacity = errors.New("detective knowledge handoff capacity reached")
)

Functions

func PrepareHandoff

func PrepareHandoff(old Proposal, ifMatch int64, target Target, actor, receipt string, at time.Time) (Proposal, Handoff, error)

PrepareHandoff records a bounded target-specific review receipt. The handoff cites the reviewed proposal version before this append increments it.

func ValidateActionShape

func ValidateActionShape(a Action) error

ValidateActionShape checks only portable payload shape. An adapter must authorize the server-issued scope, operation ID, evidence and target access.

func ValidateDraft

func ValidateDraft(p Proposal) error

ValidateDraft rejects client-supplied lifecycle and handoff fields. These are issued solely by the transactional adapter through pure transitions.

func ValidateReferences

func ValidateReferences(p Proposal, facts EvidenceFacts) error

ValidateReferences establishes that each proposal reference belongs to its Case. A confirmed claim also needs confirmed Findings supporting every selected evidence ID. The adapter must construct facts from an authorized snapshot, including verified durable Case-run links for old run evidence.

func ValidateTarget

func ValidateTarget(t *Target) error

Types

type Action

type Action struct {
	Storage     string    `json:"storage"`
	SpaceID     string    `json:"spaceID"`
	Project     string    `json:"project"`
	OperationID string    `json:"operationId"`
	IfMatch     int64     `json:"ifMatch,omitempty"`
	Type        string    `json:"type"`
	Proposal    *Proposal `json:"proposal,omitempty"`
	ProposalID  string    `json:"proposalId,omitempty"`
	ReviewNote  string    `json:"reviewNote,omitempty"`
	Target      *Target   `json:"target,omitempty"`
}

Action deliberately retains the hosted wire shape; the authenticated adapter supplies and checks storage, Space, project, actor and operation.

type EvidenceFacts

type EvidenceFacts struct {
	CaseID      string
	EvidenceIDs []string
	Findings    []FindingFact
}

EvidenceFacts is an authorized adapter projection of Case evidence. Older run evidence may be included only after the adapter verifies the completed run and its durable Case-run link inside the same transaction.

type FindingFact

type FindingFact struct {
	ID           string
	Status       string
	EvidenceRefs []string
}

type Handoff

type Handoff struct {
	Kind            string    `json:"kind"`
	Status          string    `json:"status"`
	Target          Target    `json:"target"`
	ProposalID      string    `json:"proposalId"`
	ProposalVersion int64     `json:"proposalVersion"`
	CaseID          string    `json:"caseId"`
	ClaimStatus     string    `json:"claimStatus"`
	Statement       string    `json:"statement"`
	EvidenceRefs    []string  `json:"evidenceRefs"`
	FindingRefs     []string  `json:"findingRefs,omitempty"`
	PreparedAt      time.Time `json:"preparedAt"`
	PreparedBy      string    `json:"preparedBy"`
	Receipt         string    `json:"receipt"`
}

Handoff is a private, target-specific review artifact, not proof of acceptance by the destination registry.

type Page

type Page struct {
	Proposals  []Proposal `json:"proposals"`
	NextCursor string     `json:"nextCursor,omitempty"`
	HasMore    bool       `json:"hasMore"`
}

type Proposal

type Proposal struct {
	ID           string    `json:"id"`
	CaseID       string    `json:"caseId"`
	Kind         string    `json:"kind"`
	Title        string    `json:"title"`
	Statement    string    `json:"statement"`
	EvidenceRefs []string  `json:"evidenceRefs"`
	FindingRefs  []string  `json:"findingRefs,omitempty"`
	ClaimStatus  string    `json:"claimStatus"`
	Status       string    `json:"status"`
	Version      int64     `json:"version"`
	CreatedAt    time.Time `json:"createdAt"`
	CreatedBy    string    `json:"createdBy"`
	ReviewedAt   time.Time `json:"reviewedAt,omitempty"`
	ReviewedBy   string    `json:"reviewedBy,omitempty"`
	ReviewNote   string    `json:"reviewNote,omitempty"`
	Handoffs     []Handoff `json:"handoffs,omitempty"`
}

func Review

func Review(old Proposal, ifMatch int64, decision, note, actor string, at time.Time) (Proposal, error)

Review is the only transition to a reviewed or rejected proposal. A rejected proposal cannot be exported or silently edited back into a draft.

func SaveDraft

func SaveDraft(old *Proposal, draft Proposal, ifMatch int64, actor string, at time.Time) (Proposal, error)

SaveDraft returns a new private projection. Its caller must validate Case references and commit the projection, audit and receipt atomically.

type Response

type Response struct {
	Proposal *Proposal `json:"proposal,omitempty"`
	Export   *Handoff  `json:"export,omitempty"`
	Receipt  string    `json:"receipt"`
}

type Target

type Target struct {
	System           string `json:"system"`
	Repository       string `json:"repository"`
	ResourceID       string `json:"resourceId"`
	ExpectedRevision string `json:"expectedRevision"`
}