provenance

type AgentInfo struct {
	// Name identifies the agent (e.g. "claude", "codex", "kimi").
	Name string `json:"name"`
	// Version is the agent/model version, if known.
	Version string `json:"version,omitempty"`
	// Tool identifies the host tool or SDK (e.g. "claude-code").
	Tool string `json:"tool,omitempty"`
	// ToolVersion is the host tool's version, if known.
	ToolVersion string `json:"tool_version,omitempty"`
	// CLIVersion is the version of the modulex agent CLI (or equivalent)
	// that generated this envelope, if any.
	CLIVersion string `json:"cli_version,omitempty"`
}

type Approval struct {
	// Action names what was approved (e.g. "push", "release").
	Action     string    `json:"action"`
	ApprovedBy string    `json:"approved_by"`
	ApprovedAt time.Time `json:"approved_at"`
	// Notes is free text. Redact before persisting; see Envelope.Redact.
	Notes string `json:"notes,omitempty"`
}

type ChangeType string

type CommandClass string

type CommandResult struct {
	// Name is the command or Make target invoked (e.g. "make test").
	Name           string       `json:"name"`
	Args           []string     `json:"args,omitempty"`
	Classification CommandClass `json:"classification"`
	Status         Status       `json:"status"`
	// ExitCode is the process exit code. It is meaningless (and should be
	// ignored by consumers) when Status is StatusSkipped,
	// StatusUnavailable, or StatusApprovalRequired, so it is a pointer:
	// nil means "no exit code", distinct from an explicit 0 (success).
	ExitCode *int `json:"exit_code,omitempty"`
	// Duration is wall-clock time the command took to run, encoded as a
	// nanosecond count (time.Duration's default JSON encoding). Zero for
	// commands that never ran.
	Duration time.Duration `json:"duration_ns,omitempty"`
	// EnvironmentNeeds lists tools, services, or credentials the command
	// required (e.g. "docker", "GITHUB_TOKEN"), without ever including
	// their values.
	EnvironmentNeeds []string `json:"environment_needs,omitempty"`
	// Output is a free-text capture of command output. Redact before
	// persisting; see Envelope.Redact.
	Output string `json:"output,omitempty"`
	// Reason explains a StatusSkipped/StatusUnavailable/
	// StatusApprovalRequired status. Required (non-empty) in those cases;
	// see Envelope.Validate.
	Reason string `json:"reason,omitempty"`
}

type Envelope struct {
	SchemaVersion string    `json:"schema_version"`
	Repository    RepoState `json:"repository"`
	Agent         AgentInfo `json:"agent"`
	// Changes lists every file the agent touched, in the order they were
	// changed.
	Changes []FileChange `json:"changes,omitempty"`
	// Commands lists every command the agent ran, in execution order.
	Commands []CommandResult `json:"commands,omitempty"`
	// Verification lists every verification step (focused, full, boundary,
	// compatibility, security, secret-scan, changelog, ...), in the order
	// they were run.
	Verification []VerificationResult `json:"verification,omitempty"`
	// Approvals lists human approvals granted for elevated actions, if any.
	Approvals []Approval `json:"approvals,omitempty"`
	// Rollback describes rollback availability/status for this change. Nil
	// means rollback was not assessed (distinct from an assessed-but-
	// unavailable RollbackStatus{Available: false}).
	Rollback *RollbackStatus `json:"rollback,omitempty"`
	// CreatedAt is when this envelope was produced.
	CreatedAt time.Time `json:"created_at"`
}

type FileChange struct {
	Path string `json:"path"`
	// OldPath is set for ChangeRenamed to record the file's previous path.
	OldPath string     `json:"old_path,omitempty"`
	Type    ChangeType `json:"type"`
	// Hash is a content hash of the file after the change, in
	// "<algorithm>:<hex>" form (e.g. "sha256:abc123..."). Empty if not
	// computed (e.g. for a deleted file).
	Hash string `json:"hash,omitempty"`
}

type RepoState struct {
	Path   string `json:"path"`
	Branch string `json:"branch,omitempty"`
	Commit string `json:"commit"`
	// Dirty is true if the worktree had uncommitted changes (staged or
	// unstaged) at the time this envelope was produced.
	Dirty bool `json:"dirty"`
}

type RollbackStatus struct {
	// Available is true if a rollback path (e.g. a git revert, a retained
	// patch) exists for this change.
	Available bool `json:"available"`
	// Applied is true if a rollback has actually been performed.
	Applied bool `json:"applied"`
	// Method describes the rollback mechanism (e.g. "git revert <sha>").
	Method string `json:"method,omitempty"`
	// Notes is free text. Redact before persisting; see Envelope.Redact.
	Notes string `json:"notes,omitempty"`
}

type Status string

type VerificationCategory string

type VerificationResult struct {
	Name     string               `json:"name"`
	Category VerificationCategory `json:"category"`
	Status   Status               `json:"status"`
	Duration time.Duration        `json:"duration_ns,omitempty"`
	// Message is free-text detail (e.g. a failure summary). Redact before
	// persisting; see Envelope.Redact.
	Message string `json:"message,omitempty"`
	// Reason explains a StatusSkipped/StatusUnavailable/
	// StatusApprovalRequired status. Required (non-empty) in those cases;
	// see Envelope.Validate.
	Reason string `json:"reason,omitempty"`
}