extevidence

package

v0.8.1 Latest Latest Go to latest Published: Sep 24, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 23 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Beamfall/corvint

Links

Open Source Insights

Documentation ¶

Overview ¶

Package extevidence attaches external evidence provider records to the path-impact receipt as a separated section (docs/specs/external-evidence-provider-v0.md).

Index ¶

Constants
Variables
func Freshness(ctx context.Context, root, captured, provider string) string
func InlineSection(ctx context.Context, index *contextindex.Index, source string, data []byte, ...) map[string]any
func Obligations(cem, impact []byte, limit int) (map[string]any, error)
func ParseCommand(value string) (string, error)
func ParseMCP(value string) (string, error)
func ReadPinned(ctx context.Context, root, source string, pin Pin) ([]byte, error)
func Section(ctx context.Context, index *contextindex.Index, sources []string, ...) map[string]any
func Selection(ctx context.Context, dir, revision string, sources []string, ...) map[string]any
func ValidSelectionProfile(name string) bool
type Capabilities
type Checkout
- func ParseCheckout(value string) (Checkout, error)
type Endpoint1
type Entity
type Identity
type Pin
type Record
- func Decode(data []byte) (Record, error)
type Record1
- func Decode1(data []byte) (Record1, error)
type Relation
type Relation1
type Repository
type Repository1
type SelectionInput

Constants ¶

View Source

const (
	VerificationVerified    = "verified"
	VerificationStale       = "stale"
	VerificationMissing     = "missing"
	VerificationDeleted     = "deleted"
	VerificationUnsupported = "unsupported"
	VerificationNotVerified = "not-verified"
)

Verification states for a path endpoint (EEP-V0-010).

View Source

const (
	FreshnessEqual               = "equal"
	FreshnessRepositoryAhead     = "repository-ahead"
	FreshnessProviderAhead       = "provider-ahead"
	FreshnessUnrelatedHistory    = "unrelated-history"
	FreshnessRevisionUnavailable = "revision-unavailable"
)

Freshness states from EEP-V0-009.

View Source

const (
	ObligationsComplete = "complete"
	ObligationsPartial  = "partial"
	ObligationsUnknown  = "unknown"
)

Sidecar states (EFO-V0-006).

View Source

const (
	MaxProviders   = 4
	MaxRecordBytes = 1 << 20
)

Bounds from EEP-V0-012 and EEP-V0-013.

View Source

const (
	EvidenceDeclared  = "declared"
	EvidenceObserved  = "observed"
	EvidenceInferred  = "inferred"
	EvidenceGenerated = "generated"
)

Evidence kinds a relation may carry (EEP-V0-007). A generated relation was produced by a model or heuristic, not observed; it is listed with its kind so a consumer can exclude it, and it never qualifies a selection (EEP-V0-019).

View Source

const (
	MaxRepositories = 8
	MaxCheckouts    = 8
)

Bounds from EEP-V1-004 and EEP-V1-009.

View Source

const (
	IdentityResolved   = "resolved"
	IdentityUnresolved = "unresolved"
	IdentityAmbiguous  = "ambiguous"
)

Identity states for a declared repository (EEP-V1-002).

View Source

const (
	BindingRoot        = "root"
	BindingCheckout    = "checkout"
	BindingUnbound     = "unbound"
	BindingMismatch    = "mismatch"
	BindingUnavailable = "unavailable"
	BindingAmbiguous   = "ambiguous"
	BindingUnresolved  = "unresolved"
)

Binding states for a declared repository (EEP-V1-003).

View Source

const (
	FreshnessTreeMismatch       = "tree-mismatch"
	FreshnessIdentityUnresolved = "identity-unresolved"
	FreshnessIdentityAmbiguous  = "identity-ambiguous"
	FreshnessNotEvaluated       = "not-evaluated"
)

Freshness states V1 adds to the EEP-V0-009 set (EEP-V1-005).

View Source

const (
	RelationUnresolved  = "unresolved"
	RelationStale       = "stale"
	RelationNotVerified = "not-verified"
	RelationFresh       = "fresh"
)

Relation states (EEP-V1-008), in precedence order.

View Source

const (
	StateLoaded      = "loaded"
	StateUnavailable = "unavailable"
	StateInvalid     = "invalid"
	StateUnsupported = "unsupported"
)

Provider states (EEP-V0-005).

View Source

const (
	ProfileStrict   = "strict"
	ProfileCoverage = "coverage"
)

Selection profiles name which verification relation types may narrow a selection (ETS-V0-004). No profile admits a context type.

View Source

const (
	SelectionNarrow  = "narrow-selection-allowed"
	SelectionFull    = "full-relevant-suite-required"
	SelectionBlocked = "blocked"
	SelectionUnknown = "unknown"
)

Selection states (ETS-V0-003). The state is decided from obligations, never from how many tests were selected.

View Source

const (
	MaxObligationDepth    = 4
	MaxObligationEntities = 256
)

The obligation walk is bounded in hops and in entities per record; a walk either bound cuts is reported, never silently dropped (ETS-V1-001).

View Source

const (
	CommandTimeout      = 10 * time.Second
	MaxCommandArguments = 32
	MaxCommandArgvBytes = 4096
)

Command transport bounds (EEP-TR-004). One launch per selected command, zero retries, one record per launch.

View Source

const Authority = "external-provider"

Authority is the label Core assigns to every external item (EEP-V0-007).

View Source

const ObligationsSchema = "external-frontier-obligations/0"

ObligationsSchema names the Change Frontier sidecar this file composes (EFO-V0-003).

View Source

const Schema = "external-evidence-provider/0"

Schema is the only record schema V0 accepts (EEP-V0-001).

View Source

const Schema1 = "external-evidence-provider/1"

Schema1 is the multi-repository record schema (EEP-V1-001).

View Source

const Schema2 = "external-evidence-provider/2"

Schema2 is the V1 record shape with the path-relation profile opted in: it alone composes path-to-path relations (EEP-V2-001).

View Source

const SelectionSchema = "external-test-selection/0"

SelectionSchema versions the affected-plan test_selection member (ETS-V0-002).

Variables ¶

View Source

var UntrustedTextFields = []string{
	"external.results[].summary", "external.results[].relation.rule", "external.results[].relation.reference",
	"external.downstream[].summary", "external.downstream[].relation.rule", "external.downstream[].relation.reference",
	"external.verification[].summary", "external.verification[].relation.rule", "external.verification[].relation.reference",
}

UntrustedTextFields names the provider-authored free text in the section (EEP-V0-013).

Functions ¶

func Freshness ¶

func Freshness(ctx context.Context, root, captured, provider string) string

Freshness compares the provider's observed revision with the captured commit revision by Git ancestry alone (EEP-V0-009).

func InlineSection ¶ added in v0.8.0

func InlineSection(ctx context.Context, index *contextindex.Index, source string, data []byte, reason string, changedPaths []string, limit int) map[string]any

InlineSection composes the section from one record a Core-owned in-process provider produced (EEP-V0-023). The bytes take the same decode, freshness and verification as a file, command or MCP record; a nil record is an unavailable provider row carrying reason, so absence stays visible.

func Obligations ¶

func Obligations(cem, impact []byte, limit int) (map[string]any, error)

Obligations composes the external-frontier-obligations/0 sidecar from raw CEM bytes and a raw `corvint impact` receipt (EFO-V0-002..EFO-V0-006). It reads no repository and never verifies the CEM: it binds both inputs by digest so a frontier document over the same CEM can be joined to it.

func ParseCommand ¶

func ParseCommand(value string) (string, error)

ParseCommand reads a `--provider-command` value: a JSON array of 1 to MaxCommandArguments strings whose first element is an absolute, clean executable path. It returns the provider source that selects it (EEP-TR-002).

func ParseMCP ¶

func ParseMCP(value string) (string, error)

ParseMCP uses precisely the command argv admission; file paths cannot select it.

func ReadPinned ¶

func ReadPinned(ctx context.Context, root, source string, pin Pin) ([]byte, error)

ReadPinned reads one file or runs one contained command, then returns the original bytes only after strict decoding and exact pin agreement. Callers must keep the trusted local executable immutable between hashing and launch. This helper does not compose evidence or change the Core receipt contract.

func Section ¶

func Section(ctx context.Context, index *contextindex.Index, sources []string, checkouts []Checkout, changedPaths []string, limit int) map[string]any

Section reads every selected record and returns the `external` member of the impact receipt. It never fails: every problem is a structured entry. checkouts bind V1 repositories to local directories (EEP-V1-003).

func Selection ¶

func Selection(ctx context.Context, dir, revision string, sources []string, checkouts []Checkout, input SelectionInput) map[string]any

Selection compiles the test_selection advice for an affected plan at the root commit revision. It reads provider records and Git objects only, executes nothing, and never fails: every problem is a structured entry.

func ValidSelectionProfile ¶

func ValidSelectionProfile(name string) bool

ValidSelectionProfile reports whether name is an accepted profile.

Types ¶

type Capabilities ¶ added in v0.7.0

type Capabilities struct {
	Schemas       []string `json:"schemas,omitempty"`
	EvidenceKinds []string `json:"evidence_kinds,omitempty"`
}

Capabilities is the optional provider capability declaration (EEP-TR-012). A nil member is undeclared and changes nothing; a present list, even empty, is the complete set the provider supports, and Core refuses a record whose invocation needs something outside it (EEP-TR-013).

type Checkout ¶

type Checkout struct {
	ID, Source string
}

Checkout is one operator-supplied `--repository ID=DIR` binding.

func ParseCheckout ¶

func ParseCheckout(value string) (Checkout, error)

ParseCheckout splits one `ID=DIR` argument (EEP-V1-003).

type Endpoint1 ¶

type Endpoint1 struct {
	Repository string `json:"repository,omitempty"`
	Path       string `json:"path,omitempty"`
	Blob       string `json:"blob,omitempty"`
	Provider   string `json:"provider,omitempty"`
	Entity     string `json:"entity,omitempty"`
}

Endpoint1 is either a repository-qualified path or a provider-qualified entity.

type Entity ¶

type Entity struct {
	ID      string `json:"id"`
	Kind    string `json:"kind"`
	Summary string `json:"summary"`
}

Entity is one externally documented thing.

type Identity ¶

type Identity struct {
	ID       string `json:"id"`
	Revision string `json:"revision"`
}

Identity names a provider and its own revision.

type Pin ¶

type Pin struct {
	Schema, ProviderID, ProviderRevision     string
	RepositoryRevision, RepositoryID, Origin string
	ExecutableSHA256                         string
}

Pin is an exact authoring-kit consumer contract, not a Core authority claim. RepositoryID and Origin select the root repository in /1 and /2 records. ExecutableSHA256 is mandatory for command sources and forbidden for files.

type Record ¶

type Record struct {
	Schema       string        `json:"schema"`
	Provider     Identity      `json:"provider"`
	Repository   Repository    `json:"repository"`
	Entities     []Entity      `json:"entities"`
	Relations    []Relation    `json:"relations"`
	Capabilities *Capabilities `json:"capabilities,omitempty"`
}

Record is one decoded provider record.

func Decode ¶

func Decode(data []byte) (Record, error)

Decode parses one record strictly: unknown members, duplicate entity ids, and any field outside the V0 bounds make the whole record invalid (EEP-V0-001).

type Record1 ¶

type Record1 struct {
	Schema       string        `json:"schema"`
	Provider     Identity      `json:"provider"`
	Repositories []Repository1 `json:"repositories"`
	Entities     []Entity      `json:"entities"`
	Relations    []Relation1   `json:"relations"`
	Capabilities *Capabilities `json:"capabilities,omitempty"`
}

Record1 is one decoded multi-repository provider record.

func Decode1 ¶

func Decode1(data []byte) (Record1, error)

Decode1 parses one multi-repository record strictly (EEP-V1-001, EEP-V2-001).

type Relation ¶

type Relation struct {
	From      string `json:"from"`
	To        string `json:"to"`
	Type      string `json:"type"`
	Evidence  string `json:"evidence"`
	Rule      string `json:"rule"`
	Reference string `json:"reference"`
	Blob      string `json:"blob,omitempty"`
}

Relation is one typed, directed link between two endpoints.

type Relation1 ¶

type Relation1 struct {
	From      Endpoint1 `json:"from"`
	To        Endpoint1 `json:"to"`
	Type      string    `json:"type"`
	Evidence  string    `json:"evidence"`
	Rule      string    `json:"rule"`
	Reference string    `json:"reference"`
}

Relation1 is one typed, directed link between two structured endpoints.

type Repository ¶

type Repository struct {
	Revision string `json:"revision"`
}

Repository names the repository revision the provider observed.

type Repository1 ¶

type Repository1 struct {
	ID       string `json:"id"`
	Origin   string `json:"origin,omitempty"`
	Remote   string `json:"remote,omitempty"`
	Revision string `json:"revision"`
	Tree     string `json:"tree,omitempty"`
	Role     string `json:"role,omitempty"`
}

Repository1 declares one repository: `id` and `origin` are authoritative, `remote` and `role` are advisory and never bind (EEP-V1-002).

type SelectionInput ¶

type SelectionInput struct {
	Changed        []string
	Worktree       []string
	Incomplete     []string
	Mandatory      []any
	Profile        string
	Limit          int
	CheckoutStatus func(ctx context.Context, dir string) ([]string, error)
}

SelectionInput is what the affected plan contributes. Changed is every changed root path (plan.dirty); Worktree is its uncommitted subset, which no revision-bound record can describe; Incomplete names why the plan scope is not bounded; Mandatory is echoed unchanged (ETS-V0-009). CheckoutStatus lists a bound checkout's dirty paths; nil leaves every checkout uninspected (ETS-V1-005).

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL