Agent-System/internal/traceimpact/types.go

package traceimpact

// Coverage and impact statuses. Unknown, failed, and empty are different.
const (
	ImpactConfirmed           = "confirmed_impact"
	ImpactPossible            = "possible_impact"
	ImpactDependencyUnchanged = "dependency_unchanged"
	ImpactNoKnown             = "no_known_dependencies"
	ImpactIndexPending        = "index_pending"
	ImpactPartial             = "partial"
	ImpactFailed              = "failed"

	KindRequirement = "requirement"
	KindTest        = "test"

	ReviewConfirmed = "confirmed"
	ReviewCandidate = "candidate"
	ReviewRejected  = "rejected"

	ProvenanceExplicit = "explicit_reference"
	ProvenanceRule     = "rule"
	ProvenanceModel    = "model_candidate"

	RelationRefines   = "refines"
	RelationDependsOn = "depends_on"

	DecisionConfirm = "confirm"
	DecisionReject  = "reject"

	ReopenPending  = "pending"
	ReopenApproved = "approved"
	ReopenRejected = "rejected"

	MarkOpen    = "open"
	MarkCleared = "cleared"

	ClearNoChange = "no_change"
	ClearRevision = "revision_started"

	ExtractorVersion = "trace-keys-v1"
	MaxWalkDepth     = 3
	MaxWalkNodes     = 50
)

// ItemRevision is an immutable projection of one item at one snapshot.
type ItemRevision struct {
	ID          int64
	ItemID      int64
	RevisionNo  int
	SourceDocID string
	SnapshotID  int64
	ContentHash string
	Statement   string
	Extractor   string
	Tombstone   bool
}

// Item is a stable project entry.
type Item struct {
	ID          int64  `json:"id"`
	ProjectID   int64  `json:"project_id"`
	BusinessKey string `json:"business_key"`
	Kind        string `json:"kind"`
	Lifecycle   string `json:"lifecycle_state"`
	ReviewState string `json:"review_state"`
	Tombstone   bool   `json:"tombstone"`
	Statement   string `json:"statement,omitempty"`
	SourceDocID string `json:"source_doc_id,omitempty"`
}

// Edge is a directed relation. Reverse walk follows dependents of a changed item.
type Edge struct {
	ID           int64  `json:"id"`
	ProjectID    int64  `json:"project_id"`
	FromItemID   int64  `json:"from_item_id"`
	ToItemID     int64  `json:"to_item_id"`
	RelationType string `json:"relation_type"`
	Provenance   string `json:"provenance"`
	ReviewState  string `json:"review_state"`
	EvidenceDoc  string `json:"evidence_doc_id,omitempty"`
	FromKey      string `json:"from_key,omitempty"`
	ToKey        string `json:"to_key,omitempty"`
}

// Decision is the authority record for a candidate edge.
type Decision struct {
	ID        int64  `json:"id"`
	ProjectID int64  `json:"project_id"`
	EdgeID    int64  `json:"edge_id"`
	Decision  string `json:"decision"`
	Reason    string `json:"reason"`
	DecidedBy int64  `json:"decided_by"`
}

// IndexState is the coverage watermark for one document snapshot.
type IndexState struct {
	ProjectID  int64  `json:"project_id"`
	DocID      string `json:"doc_id"`
	SnapshotID int64  `json:"source_snapshot_id"`
	Status     string `json:"status"`
	Extractor  string `json:"extractor_version"`
	ItemCount  int    `json:"item_count"`
	Error      string `json:"error,omitempty"`
}

// DocRef binds a document to the stage the caller is asking about.
type DocRef struct {
	DocID       string `json:"doc_id"`
	StageKey    string `json:"stage_key,omitempty"`
	StageStatus string `json:"stage_status,omitempty"`
	AuthorID    int64  `json:"author_id,omitempty"`
	Visible     bool   `json:"visible"`
	Markdown    string `json:"markdown,omitempty"`
	SnapshotID  int64  `json:"snapshot_id,omitempty"`
}

// Suggestion is a clickable next step, not a free-text instruction.
type Suggestion struct {
	Action string `json:"action"`
	Reason string `json:"reason"`
}

// Impact is one affected document or item.
type Impact struct {
	DocID      string `json:"doc_id,omitempty"`
	ItemKey    string `json:"item_key,omitempty"`
	StageKey   string `json:"stage_key,omitempty"`
	ImpactType string `json:"impact_type"`
	Depth      int    `json:"depth"`
	Reason     string `json:"reason"`
}

// Report is the deterministic impact result.
type Report struct {
	ProjectID      int64        `json:"project_id"`
	SourceDocID    string       `json:"source_doc_id"`
	CoverageStatus string       `json:"coverage_status"`
	Impacts        []Impact     `json:"impacts"`
	Suggestions    []Suggestion `json:"suggestions"`
	Summary        string       `json:"summary"`
}

// ReopenRequest asks to unlock selected documents on a completed stage.
type ReopenRequest struct {
	ID          int64    `json:"id"`
	ProjectID   int64    `json:"project_id"`
	InstanceID  int64    `json:"instance_id"`
	StageKey    string   `json:"stage_key"`
	DocTasks    []string `json:"doc_task_keys"`
	Reason      string   `json:"reason"`
	RequestedBy int64    `json:"requested_by"`
	Status      string   `json:"status"`
}

// RecheckMark is a soft signal on a completed stage.
type RecheckMark struct {
	ID        int64  `json:"id"`
	ProjectID int64  `json:"project_id"`
	StageKey  string `json:"stage_key"`
	SourceDoc string `json:"source_doc_id"`
	Status    string `json:"status"`
	Reason    string `json:"reason"`
	AckedBy   int64  `json:"acked_by,omitempty"`
}