report

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 1, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package report projects the four canonical read-only reports over local truth. It owns no truth of its own: state, readiness, approval, history, evidence, and policy each keep exactly one existing owner, and every model here is a bounded projection of those owners. Nothing in this package writes, transitions, executes, or reaches the network.

Index

Constants

View Source 
const (
	KindStatus  = "status"
	KindProof   = "proof"
	KindHistory = "history"
	KindReview  = "review"
)

The four report kinds are the whole surface. A fifth report needs a requirement, not a constant.

Variables

This section is empty.

Functions

This section is empty.

Types

type Artifact 

type Artifact struct {
	Name    string `json:"name"`
	Present bool   `json:"present"`
}

Artifact reports whether one authored planning artifact exists. A partially authored change is an explicit fact, never an error and never an omission.

type CapabilityEffect 

type CapabilityEffect struct {
	Capability   string `json:"capability"`
	AcceptedPath string `json:"acceptedPath"`
	BeforeHash   string `json:"beforeHash,omitempty"`
	AfterHash    string `json:"afterHash,omitempty"`
	Created      bool   `json:"created"`
	NoOp         bool   `json:"noOp"`
}

CapabilityEffect is the expected sync effect on one accepted spec: which document changes, from which bytes to which bytes, identified by hash.

type CapabilityReview 

type CapabilityReview struct {
	Capability   string   `json:"capability"`
	Added        int      `json:"added"`
	Modified     int      `json:"modified"`
	Removed      int      `json:"removed"`
	Renamed      int      `json:"renamed"`
	Requirements []string `json:"requirements"`
}

CapabilityReview counts delta operations without carrying authored bodies.

type DesignSection 

type DesignSection struct {
	Name      string `json:"name"`
	Excerpt   string `json:"excerpt,omitempty"`
	Truncated bool   `json:"truncated"`
	Present   bool   `json:"present"`
}

DesignSection is one bounded design contract. Content is sampled and redacted by the existing bounded-output owner, so an oversized or secret-shaped artifact can only ever produce a short, safe excerpt.

type DiffIdentity 

type DiffIdentity struct {
	HEAD        string     `json:"head,omitempty"`
	Tasks       []TaskDiff `json:"tasks"`
	Unattempted []string   `json:"unattempted"`
	Ambiguous   bool       `json:"ambiguous"`
}

DiffIdentity is the change-wide diff identity. HEAD is set only when every attempted task agrees on one baseline commit; disagreement is reported as ambiguity rather than resolved by picking one.

type Event 

type Event struct {
	Sequence  int    `json:"sequence"`
	From      uint64 `json:"revisionFrom"`
	Revision  uint64 `json:"revision"`
	Kind      string `json:"kind"`
	ID        string `json:"id"`
	Actor     string `json:"actor"`
	Timestamp string `json:"timestamp"`
}

Event is one ordered history fact. Sequence is the append position and Revision is the resulting state revision; together they decide order. Timestamp is carried as a fact and never orders anything.

type HistoryModel 

type HistoryModel struct {
	Change string  `json:"change"`
	Events []Event `json:"events"`
	// Observations are appended history facts that carry no lifecycle
	// transition — today only friction. They are ordered by append position
	// alone and are kept out of Events so they can never take part in revision
	// ordering or weaken its gap and ambiguity checks. Revision reports the
	// revision the observation was recorded against, as a fact.
	Observations  []Event        `json:"observations"`
	Empty         bool           `json:"empty"`
	Inconsistency *Inconsistency `json:"inconsistency,omitempty"`
}

HistoryModel is the ordered lifecycle, approval, completion, sync, and archive record of one change, plus the observations appended beside it.

func ProjectHistory 

func ProjectHistory(truth Truth) (HistoryModel, error)

ProjectHistory orders every event of one change by resulting revision and append sequence. Timestamps are reported and never consulted for order.

type Inconsistency 

type Inconsistency struct {
	Code     string `json:"code"`
	Subject  string `json:"subject"`
	Observed string `json:"observed"`
	Action   string `json:"action"`
}

Inconsistency is an explicit blocking disagreement between sources. It is exposed instead of guessed, and it always suppresses "current" proof.

type ProofModel 

type ProofModel struct {
	Change        string             `json:"change"`
	PolicyDigest  string             `json:"policyDigest"`
	Tasks         []TaskProof        `json:"tasks"`
	Requirements  []RequirementProof `json:"requirements"`
	ExtraEvidence []string           `json:"extraEvidence"`
	Empty         bool               `json:"empty"`
	Inconsistency *Inconsistency     `json:"inconsistency,omitempty"`
}

ProofModel is task, requirement, and check applicability with stale, missing, and extra evidence made explicit.

func ProjectProof 

func ProjectProof(truth Truth) (ProofModel, error)

ProjectProof maps requirements, tasks, and required checks to the evidence recorded against them. Applicability is decided by the evidence owner alone.

type ReconcileEffect 

type ReconcileEffect struct {
	Capabilities []CapabilityEffect `json:"capabilities"`
	Diagnostics  []string           `json:"diagnostics"`
	Applicable   bool               `json:"applicable"`
	NoOp         bool               `json:"noOp"`
}

ReconcileEffect is the expected sync/archive effect projected from the one reconciliation owner. Rebuilt documents are deliberately absent.

type RequirementProof 

type RequirementProof struct {
	Capability  string   `json:"capability"`
	Requirement string   `json:"requirement"`
	Tasks       []string `json:"tasks"`
	Covered     bool     `json:"covered"`
}

RequirementProof is the requirement side of the same trace, so a requirement with no task is as visible as a task with no proof.

type ReviewModel 

type ReviewModel struct {
	Change          string                  `json:"change"`
	Lifecycle       string                  `json:"lifecycle"`
	Revision        uint64                  `json:"revision"`
	Profile         string                  `json:"profile"`
	PolicyDigest    string                  `json:"policyDigest"`
	Assurance       string                  `json:"assurance"`
	Approver        string                  `json:"approver,omitempty"`
	ApprovalHash    string                  `json:"approvalHash,omitempty"`
	ApprovalCurrent bool                    `json:"approvalCurrent"`
	Artifacts       []core.ApprovalArtifact `json:"artifacts"`
	Capabilities    []CapabilityReview      `json:"capabilities"`
	Tasks           []TaskReview            `json:"tasks"`
	Proof           ProofModel              `json:"proof"`
	Synced          *Event                  `json:"synced,omitempty"`
	Archived        *Event                  `json:"archived,omitempty"`
	Blockers        []core.ReadinessBlocker `json:"blockers"`
	Empty           bool                    `json:"empty"`
	Inconsistency   *Inconsistency          `json:"inconsistency,omitempty"`
}

ReviewModel is the bounded review packet input: approved intent and deltas, declared scope, proof, and the sync/archive effect. Source bodies, command output, and unbounded logs are deliberately absent.

func ProjectReview 

func ProjectReview(truth Truth) (ReviewModel, error)

ProjectReview is the bounded review packet input. It carries identities, counts, declared scope, and proof; never authored bodies or command output.

type ReviewPacket 

type ReviewPacket struct {
	Change        string                  `json:"change"`
	PolicyDigest  string                  `json:"policyDigest"`
	Review        ReviewModel             `json:"review"`
	Design        []DesignSection         `json:"design"`
	Diff          DiffIdentity            `json:"diff"`
	Effect        ReconcileEffect         `json:"effect"`
	Blockers      []core.ReadinessBlocker `json:"blockers"`
	Approvable    bool                    `json:"approvable"`
	Empty         bool                    `json:"empty"`
	Inconsistency *Inconsistency          `json:"inconsistency,omitempty"`
}

ReviewPacket is the one bounded review packet: approved intent and deltas, design contracts, task DAG and declared scope, diff identity, proof coverage, and the expected reconciliation effect. It resolves nothing and authorizes nothing: Approvable means no blocker was found, never that a human may be skipped.

func ProjectReviewPacket 

func ProjectReviewPacket(truth Truth) (ReviewPacket, error)

ProjectReviewPacket assembles the packet from the canonical owners alone: the review, proof, and readiness projections above, the recorded attempts that own diff identity, and the reconciliation plan. It reads accepted specs and deltas through the reconciliation owner and writes, transitions, and executes nothing.

type StatusModel 

type StatusModel struct {
	Change          string                  `json:"change"`
	Lifecycle       string                  `json:"lifecycle"`
	Revision        uint64                  `json:"revision"`
	NextAction      string                  `json:"nextAction"`
	Profile         string                  `json:"profile"`
	PolicyDigest    string                  `json:"policyDigest"`
	Assurance       string                  `json:"assurance"`
	ApprovalCurrent bool                    `json:"approvalCurrent"`
	ApprovalReason  string                  `json:"approvalReason,omitempty"`
	Artifacts       []Artifact              `json:"artifacts"`
	Tasks           []core.TaskReadiness    `json:"tasks"`
	Frontier        []string                `json:"frontier"`
	Outcome         core.ReadinessOutcome   `json:"outcome"`
	Blockers        []core.ReadinessBlocker `json:"blockers"`
	Empty           bool                    `json:"empty"`
	Inconsistency   *Inconsistency          `json:"inconsistency,omitempty"`
}

StatusModel is current lifecycle, full frontier, blockers, policy, and assurance.

func ProjectStatus 

func ProjectStatus(truth Truth) (StatusModel, error)

ProjectStatus reports current lifecycle, the full frontier, blockers, policy, and assurance. An empty or partially authored change is explicit.

type TaskDiff 

type TaskDiff struct {
	TaskID       string   `json:"task"`
	HEAD         string   `json:"head,omitempty"`
	Files        []string `json:"files"`
	ContractHash string   `json:"contractHash,omitempty"`
	ApprovalHash string   `json:"approvalHash,omitempty"`
}

TaskDiff is one task's diff identity: the commit its recorded attempt was baselined at and the exact file scope that attempt declared. The packet carries identity only; no patch text, no source body.

type TaskProof 

type TaskProof struct {
	TaskID            string                   `json:"task"`
	Activity          core.TaskActivity        `json:"activity"`
	Requirements      []string                 `json:"requirements"`
	Verify            string                   `json:"verify"`
	VerifyParsable    bool                     `json:"verifyParsable"`
	AttemptID         string                   `json:"attempt,omitempty"`
	ConsumedEvidence  string                   `json:"consumedEvidence,omitempty"`
	Current           bool                     `json:"current"`
	StaleEvidence     []string                 `json:"staleEvidence"`
	MissingChecks     []evidence.RequiredCheck `json:"missingChecks"`
	PriorPolicyDigest string                   `json:"priorPolicyDigest,omitempty"`
	Missing           bool                     `json:"missing"`
}

TaskProof maps one task to its declared verification, its current attempt, and the applicability of every evidence record recorded against it.

type TaskReview 

type TaskReview struct {
	ID           string            `json:"id"`
	Wave         int               `json:"wave"`
	Activity     core.TaskActivity `json:"activity"`
	DependsOn    []string          `json:"dependsOn"`
	Files        []string          `json:"files"`
	Requirements []string          `json:"requirements"`
	Verify       string            `json:"verify"`
}

TaskReview is the declared task contract a reviewer checks the diff against.

type Truth 

type Truth struct {
	Snapshot core.ReadinessSnapshot
	History  []record.Record
	Evidence []record.Record
	Policy   core.Policy
}

Truth is the bounded canonical input every report projects from. Load gathers it once; a Truth built by hand is refused because its readiness snapshot can only come from the canonical loader.

func Load 

func Load(root, change string, policy core.Policy) (Truth, error)

Load gathers canonical local truth for one change. It reads through the existing owners only: readiness owns state, plan, and approval projection; the record ledgers own history and evidence.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.