closure

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package closure stores and verifies the evidence graph used to assess PiG's correspondence with the pinned Pi source.

Index

Constants

View Source
const (
	FamilyCoverageDataset  = "family-coverage"
	ScenarioQualityDataset = "scenario-quality"
)
View Source
const (
	PortMapDataset            = "port-map"
	CoverageDataset           = "coverage-row"
	SemanticMappingDataset    = "semantic-mapping"
	SemanticDeltaDataset      = "semantic-delta"
	InputRenderMappingDataset = "behavior-input-mapping"
	AsyncContractDataset      = "async-contract"
	ChangedSourceDataset      = "upstream-sync"
	BehaviorContractDataset   = "behavior-contract"
	FormatOwnershipDataset    = "format-version"
)
View Source
const (
	ScenarioOutcomePass = "pass"
	ScenarioOutcomeFail = "fail"
)

ScenarioOutcomePass and ScenarioOutcomeFail are the only recognized outcomes of a canonical parity scenario run.

View Source
const DivergenceDashboardDataset = "divergence"
View Source
const FoundationDashboardDataset = "foundation"

Variables

This section is empty.

Functions

func AssertionAudit

func AssertionAudit(ctx context.Context, databasePath, root string) ([]byte, error)

func ConfineFactDiffToUnit

func ConfineFactDiffToUnit(graph *Graph, unit WorkUnit, changedPaths []string) error

ConfineFactDiffToUnit rejects an applied patch whose semantic footprint exceeds the leased work unit. The footprint of a changed path is the set of semantic boundaries owned by every behavior whose mapped production target hosts a pin at that path; each such boundary must belong to the unit's own boundary set. A patch that stays inside its declared write paths can still change a file that also hosts another behavior's mapped target, and this guard catches that escape where the purely textual path confinement cannot.

func ConfinePatchToLease

func ConfinePatchToLease(lease Lease, unit WorkUnit, bundle *correspondence.TranslatorBundle) error

ConfinePatchToLease rejects a Translator patch that writes outside the exact paths its leased work unit owns. Production edits must land in the unit write set and test edits in its test or fixture set, so a worker holding a lease can never touch another unit's files even when those files are valid targets elsewhere.

func ContentHash

func ContentHash(record Record) (string, error)

func CurrentEnvironmentHash

func CurrentEnvironmentHash(configured []string) (string, error)

func CurrentToolchainHash

func CurrentToolchainHash(ctx context.Context) (string, error)

func EvidenceReadiness

func EvidenceReadiness(ctx context.Context, path string) ([]byte, error)

func ExpectedGoTestFailureHash

func ExpectedGoTestFailureHash(expectedTest string, outputs []string) (string, error)

ExpectedGoTestFailureHash derives the exact structured failure identity used by automatic Go mutants from the bound test's expected output events.

func Explain

func Explain(ctx context.Context, path, obligationID string) ([]byte, error)

func Frontier

func Frontier(ctx context.Context, path, recordID string) ([]byte, error)

func GrantLeaseInStore

func GrantLeaseInStore(ctx context.Context, path, workUnitID, holder string) ([]byte, error)

GrantLeaseInStore grants one derived work unit to a holder and persists the resulting lease record. It reads the current active set from the graph, so the overlap-admission gate rejects a grant that would collide with a lease already held. The operation assumes serialized invocation: the campaign controller serializes production/evidence writes, so no two grants race the active set.

func HashBytes

func HashBytes(value []byte) string

func ImportCurrentDenominators

func ImportCurrentDenominators(root string, snapshot *Snapshot) ([]Record, DenominatorImportReport, error)

func IntegrateLease

func IntegrateLease(current *Graph, lease Lease, units map[string]WorkUnit) error

IntegrateLease admits a lease into canonical integration only if its recorded base still matches the current graph. Canonical integration is serial, so a lease granted before an earlier integration advanced shared support is detected as stale here and must rebase rather than integrate on a stale base.

func IntegrateLeaseInStore

func IntegrateLeaseInStore(ctx context.Context, path, leaseID string) ([]byte, error)

IntegrateLeaseInStore lands one active lease: it rejects a stale base (whose support moved since the grant), flips the lease active→integrated so it stops contending, and recomputes delta briefs for the leases that remain active. The briefs are empty until an integration also changes obligation support; landing proven evidence is a separate operation, so nothing here mutates a verdict.

func MappingReview

func MappingReview(ctx context.Context, path string) ([]byte, error)

func MutationReadiness

func MutationReadiness(ctx context.Context, path string) ([]byte, error)

func PlanUnits

func PlanUnits(ctx context.Context, path string) ([]byte, error)

PlanUnits returns the deterministic parallel work units derived from the closure graph in the disposable store. It is read-only: it exposes the planner's output for a campaign controller to lease, and it neither grants leases nor mutates the graph.

func ReadEvidenceRequest

func ReadEvidenceRequest(ctx context.Context, path, requestID string) ([]byte, error)

ReadEvidenceRequest returns one canonical evidence request from the disposable store. The record is revalidated with the complete graph before it is exposed, so a malformed or dangling request cannot cross the Porter process boundary.

func ReadMutationRequest

func ReadMutationRequest(ctx context.Context, path, requestID string) ([]byte, error)

func ReadReport

func ReadReport(ctx context.Context, path, dataset string) ([]byte, error)

ReadReport renders one dataset as a graph projection. Source fields remain intact; state fields keep imported non-authoritative status explicit without allowing it to count as proof.

func ReadStatus

func ReadStatus(ctx context.Context, path string) ([]byte, error)

func RebuildStore

func RebuildStore(ctx context.Context, path string, graph *Graph) error

func RenderCoverageAudit

func RenderCoverageAudit(audit CoverageAudit) []byte

func RenderReport

func RenderReport(graph *Graph, dataset string) ([]byte, error)

func RenderStatus

func RenderStatus(verdicts []Verdict, provisionalClaims ...ProvisionalClaim) ([]byte, error)

RenderStatus retains the source count and provisional-claim sections. The status-row projection is the generated per-obligation view; its state columns are derived from the rows, so imported claims cannot add credit to proven or waived totals.

func ReportDatasets

func ReportDatasets() []string

ReportDatasets returns the closed dataset set accepted by the report engine and every Porter adapter.

func SafeStorePath

func SafeStorePath(root, configured string) (string, error)

func ValidHash

func ValidHash(value string) bool

func VerdictDrift

func VerdictDrift(before, after *Graph) []string

VerdictDrift reports the obligations whose effective verdict differs between two graphs, in deterministic obligation order. It is the reconciliation primitive: run it between a campaign's incrementally accumulated graph and a from-scratch rebuild of the same records, and a non-empty result means the incremental path diverged from a full re-derivation. A state or reason change, or an obligation present in one graph but not the other, is drift.

func VerifyRequestIntoStore

func VerifyRequestIntoStore(ctx context.Context, root, storePath, requestID, evidenceDir, message string) (*EvidenceRun, []Verdict, error)

VerifyRequestIntoStore autonomously produces attested evidence for a verification-only obligation set and folds it into the store, returning the evidence run and the re-derived verdict of every obligation the request covers.

It runs the bound EvidenceRequest against the canonical tree, commits and attests the resulting evidence, appends the attestation records to the store, and rebuilds it so the derived verdicts reflect the new proof. This is the non-authoring path: no translator patch is proposed, so it applies only to behaviors pig already matches. It cannot fabricate proof: the returned verdicts are re-derived from the attested records, so a failing run yields a contradicted or open verdict, never proven.

func VerifyStore

func VerifyStore(ctx context.Context, path string) error

func WhyOpen

func WhyOpen(ctx context.Context, path string) ([]byte, error)

func WorkUnitBaseFingerprint

func WorkUnitBaseFingerprint(graph *Graph, unit WorkUnit) (string, error)

WorkUnitBaseFingerprint hashes the unit's snapshot and the current support of its open obligations. It changes whenever any support the unit depends on changes, so a lease granted against one fingerprint is detectably stale after integration of overlapping or prerequisite work.

Types

type AffectedTests

type AffectedTests struct {
	TestIDs      []string
	Conservative bool
}

AffectedTests is the result of selecting which tests a set of changed behaviors requires. TestIDs is the deterministic set to re-run; Conservative is set when an edge gap (a changed behavior with no bound test) forced the full suite rather than a scoped selection.

func SelectAffectedTests

func SelectAffectedTests(graph *Graph, changedBehaviorIDs []string) (AffectedTests, error)

SelectAffectedTests chooses the tests to re-run for a set of changed behaviors from the assertion edges that bind tests to behaviors. It is conservative by construction: if any changed behavior has no bound test, the edge is missing and the full test suite is returned rather than a scoped subset, so a reconciliation run can never silently skip a test whose coverage the graph does not yet record. An empty change set selects nothing.

type AgentWorkScope

type AgentWorkScope struct {
	EvidenceIDs  []string
	FixturePaths []string
	TestPaths    []string
}

func ReadAgentWorkScope

func ReadAgentWorkScope(ctx context.Context, path, snapshotID string, obligationIDs []string) (AgentWorkScope, error)

type AppliedPatch

type AppliedPatch struct {
	CheckoutDir  string
	ChangedPaths []string
	ResultHashes map[string]string
}

AppliedPatch records the disposable candidate checkout a confined Translator patch was applied to, plus the exact changed paths and their resulting content hashes. The caller runs evidence against CheckoutDir and owns discarding it; the canonical tree is never modified.

func ApplyTranslatorPatch

func ApplyTranslatorPatch(ctx context.Context, root, canonicalCommit string, current *Graph, lease Lease, units map[string]WorkUnit, bundle *correspondence.TranslatorBundle) (*AppliedPatch, error)

ApplyTranslatorPatch integrates a Translator patch one serial step: it rejects a stale lease base, confines the patch to the leased work unit, clones the canonical commit into a disposable checkout, and applies each full-file replacement guarded by its original-content hash. It fails closed if the patch touches any path outside the declared edits.

type Assertion

type Assertion struct {
	Kind       Kind   `json:"kind"`
	ID         string `json:"id"`
	TestID     string `json:"testId"`
	Class      string `json:"class"`
	BehaviorID string `json:"behaviorId"`
	FacetID    string `json:"facetId"`
	Oracle     string `json:"oracle"`
}

func (*Assertion) RecordID

func (r *Assertion) RecordID() string

func (*Assertion) RecordKind

func (r *Assertion) RecordKind() Kind

type AssertionAuditRow

type AssertionAuditRow struct {
	TestID     string
	Path       string
	Bound      int
	Candidates int
	Status     string
}

type AssertionCandidate

type AssertionCandidate struct {
	ID        string
	TestID    string
	Path      string
	Line      int
	Kind      string
	Callee    string
	TextHash  string
	Enforcing bool
}

func ExtractAssertionCandidates

func ExtractAssertionCandidates(root string, test *Test, pin *Pin) ([]AssertionCandidate, error)

type Behavior

type Behavior struct {
	Kind         Kind     `json:"kind"`
	ID           string   `json:"id"`
	Name         string   `json:"name"`
	OriginPinIDs []string `json:"originPinIds"`
	FactIDs      []string `json:"factIds,omitempty"`
	Profile      string   `json:"profile"`
}

func (*Behavior) RecordID

func (r *Behavior) RecordID() string

func (*Behavior) RecordKind

func (r *Behavior) RecordKind() Kind

type BranchOutcome

type BranchOutcome struct {
	ID        string
	Path      string
	Kind      string
	Outcome   string
	StartLine int
	EndLine   int
	Status    string
}

type CampaignAuditEntry

type CampaignAuditEntry struct {
	UpstreamVersion string   `json:"upstreamVersion"`
	TargetCommit    string   `json:"targetCommit"`
	Holder          string   `json:"holder"`
	Grantable       int      `json:"grantable"`
	Parked          int      `json:"parked"`
	Blocked         int      `json:"blocked"`
	Deferred        int      `json:"deferred"`
	Held            int      `json:"held"`
	BudgetHalted    bool     `json:"budgetHalted"`
	GrantedLeaseIDs []string `json:"grantedLeaseIds"`
}

CampaignAuditEntry is one appended line of the campaign audit trail. It records the manifest identity, the plan partition counts, and the leases granted this step. It carries no wall clock: the append order is the temporal record and keeps the entry deterministic and testable.

type CampaignBudget

type CampaignBudget struct {
	MaxActiveLeases int
	MaxGrants       int
}

CampaignBudget bounds one scheduling step. A zero field means unbounded. The budget caps how much work the controller admits; it never removes a ready unit from the frontier, so exhausting the budget halts intake without shrinking the campaign.

type CampaignManifest

type CampaignManifest struct {
	UpstreamVersion string         `json:"upstreamVersion"`
	TargetCommit    string         `json:"targetCommit"`
	Holder          string         `json:"holder"`
	Budget          CampaignBudget `json:"budget"`
}

CampaignManifest is the replayable definition of a headless campaign. It pins the upstream authority and target commit so a resumed run drives the same frontier, and carries the budget the controller enforces each step.

type CampaignStepResult

type CampaignStepResult struct {
	Plan          GrantPlan
	GrantedLeases []Lease
	Audit         CampaignAuditEntry
}

CampaignStepResult reports one controller step: the derived plan, the leases it granted, and the audit entry it appended.

func CampaignStep

func CampaignStep(ctx context.Context, path string, manifest CampaignManifest) (CampaignStepResult, error)

CampaignStep drives one headless controller step against the store: it loads the current graph, plans the grantable frontier against the persisted active leases and the manifest budget, and grants each grantable unit through the serialized store mutation. The scheduler guarantees the grantable set is mutually compatible, so the sequential grants cannot contend. The step is resumable: it reads active leases from the store, so a killed campaign resumes without re-granting held work. It appends one audit line per step next to the store.

type CandidatePatchProof

type CandidatePatchProof struct {
	BoundTest string
	Command   EvidenceCommand
	Baseline  EvidenceCommandResult
	Patched   EvidenceCommandResult
}

CandidatePatchProof is the red→green evidence that a Translator patch is load-bearing: the bound test fails on the unpatched canonical checkout and passes on the patched candidate. It is the pre-integration gate that turns an applied patch into a proven one before serial integration runs the attested canonical evidence.

func ProveCandidatePatch

func ProveCandidatePatch(ctx context.Context, root, canonicalCommit string, applied *AppliedPatch, command EvidenceCommand, boundTest string, timeoutSeconds int) (*CandidatePatchProof, error)

ProveCandidatePatch runs the bound test command on a clean checkout of the canonical commit and on the patched candidate, and requires that the test fails on canonical and passes on the candidate. A patch whose bound test already passes on canonical is rejected as not load-bearing, and a patch that does not turn the test green is rejected. A harness error, timeout, or overflow on either run fails closed.

type CoverageAudit

type CoverageAudit struct {
	Blocks   []CoverageBlock
	Branches []BranchOutcome
}

func AuditGoCoverage

func AuditGoCoverage(root string, profile io.Reader, paths []string) (CoverageAudit, error)

func AuditGoCoverageScopes

func AuditGoCoverageScopes(root string, profile io.Reader, scopes []CoverageScope) (CoverageAudit, error)

type CoverageBlock

type CoverageBlock struct {
	Path        string
	StartLine   int
	StartColumn int
	EndLine     int
	EndColumn   int
	Statements  int
	Count       int
}

func ParseGoCoverage

func ParseGoCoverage(root string, profile io.Reader) ([]CoverageBlock, error)

type CoverageScope

type CoverageScope struct {
	Path      string
	StartLine int
	EndLine   int
}

func MappingCoverageScopes

func MappingCoverageScopes(ctx context.Context, path string) ([]CoverageScope, error)

type Decision

type Decision struct {
	Kind               Kind     `json:"kind"`
	ID                 string   `json:"id"`
	DecisionType       string   `json:"decisionType"`
	ScopeIDs           []string `json:"scopeIds"`
	Rationale          string   `json:"rationale"`
	Authority          string   `json:"authority"`
	ReviewWhen         string   `json:"reviewWhen,omitempty"`
	ValidThroughCommit string   `json:"validThroughCommit,omitempty"`
	FailureHashes      []string `json:"failureHashes,omitempty"`
}

func (*Decision) RecordID

func (r *Decision) RecordID() string

func (*Decision) RecordKind

func (r *Decision) RecordKind() Kind

type DeltaBrief

type DeltaBrief struct {
	LeaseID        string
	WorkUnitID     string
	OldFingerprint string
	NewFingerprint string
}

DeltaBrief tells an active lease holder that support their work unit depends on moved during serial integration of another lease, so their base is stale and their patch must be rebased and re-verified before it can integrate.

func DeltaBriefs

func DeltaBriefs(before, after *Graph, active []Lease, units map[string]WorkUnit) ([]DeltaBrief, error)

DeltaBriefs returns, in deterministic lease order, a brief for every active lease whose work-unit base fingerprint changed between the pre- and post-integration graphs. It is how serial integration recomputes support and notifies exactly the affected workers, and no others.

type DenominatorImportReport

type DenominatorImportReport struct {
	Counts            map[string]int
	ProvisionalClaims int
	SourceFiles       []string
}

type EvidenceArtifact

type EvidenceArtifact struct {
	Path string `json:"path"`
	Hash string `json:"hash"`
}

type EvidenceAttestation

type EvidenceAttestation struct {
	Kind             Kind               `json:"kind"`
	ID               string             `json:"id"`
	EvidenceID       string             `json:"evidenceId"`
	WitnessIDs       []string           `json:"witnessIds"`
	RepositoryCommit string             `json:"repositoryCommit"`
	Path             string             `json:"path"`
	Artifacts        []EvidenceArtifact `json:"artifacts"`
}

func (*EvidenceAttestation) RecordID

func (r *EvidenceAttestation) RecordID() string

func (*EvidenceAttestation) RecordKind

func (r *EvidenceAttestation) RecordKind() Kind

type EvidenceBinding

type EvidenceBinding struct {
	RecordID    string `json:"recordId"`
	ContentHash string `json:"contentHash"`
}

type EvidenceCommand

type EvidenceCommand struct {
	Name string   `json:"name"`
	Args []string `json:"args"`
}

type EvidenceCommandResult

type EvidenceCommandResult struct {
	Run         int    `json:"run"`
	Index       int    `json:"index"`
	CommandHash string `json:"commandHash"`
	StdoutHash  string `json:"stdoutHash"`
	StderrHash  string `json:"stderrHash"`
	ExitCode    int    `json:"exitCode"`
	Error       string `json:"error,omitempty"`
	Overflow    bool   `json:"overflow,omitempty"`
}

type EvidenceCoveredRange

type EvidenceCoveredRange struct {
	TargetID  string `json:"targetId"`
	PinID     string `json:"pinId"`
	Path      string `json:"path"`
	StartLine int    `json:"startLine"`
	EndLine   int    `json:"endLine"`
	Count     int    `json:"count"`
}

type EvidenceObligationBindings

type EvidenceObligationBindings struct {
	ObligationID string            `json:"obligationId"`
	Support      []EvidenceBinding `json:"support"`
}

type EvidenceProviderCapture

type EvidenceProviderCapture struct {
	TargetID           string `json:"targetId"`
	OracleArtifactHash string `json:"oracleArtifactHash"`
	TargetArtifactHash string `json:"targetArtifactHash"`
}

type EvidenceRequest

type EvidenceRequest struct {
	Kind           Kind                     `json:"kind"`
	ID             string                   `json:"id"`
	SnapshotID     string                   `json:"snapshotId"`
	ObligationIDs  []string                 `json:"obligationIds"`
	AssertionIDs   []string                 `json:"assertionIds"`
	Commands       []EvidenceCommand        `json:"commands"`
	Environment    []string                 `json:"environment"`
	Witnesses      []EvidenceWitnessRequest `json:"witnesses"`
	Durability     int                      `json:"durability"`
	Comparator     string                   `json:"comparator"`
	TimeoutSeconds int                      `json:"timeoutSeconds"`
}

func SynthesizeEvidenceRequest

func SynthesizeEvidenceRequest(graph *Graph, obligationID string) (*EvidenceRequest, error)

SynthesizeEvidenceRequest derives an EvidenceRequest for a verification-only obligation from the graph: the obligation's accepted mapping supplies the production targets, and the bound test's Execution recipe supplies the runnable command. It is the general, non-authoring counterpart to provider-wire's hardcoded request table. A synthesized request is only produced when the graph carries everything needed to run and witness the test mechanically; otherwise the function fails closed (no recipe, no accepted mapping, no admissible assertion) rather than guessing a command.

The recipe covers the common Go case: run one test function in a package with a coverage profile, witnessed by the executed production ranges. Obligations whose test carries no Execution (differentials, multi-command traces, authored recipes) are left to their authored EvidenceRequests and return an error here.

func (*EvidenceRequest) RecordID

func (r *EvidenceRequest) RecordID() string

func (*EvidenceRequest) RecordKind

func (r *EvidenceRequest) RecordKind() Kind

type EvidenceRun

type EvidenceRun struct {
	Kind            Kind                         `json:"kind"`
	ID              string                       `json:"id"`
	RequestID       string                       `json:"requestId"`
	SnapshotID      string                       `json:"snapshotId"`
	Result          string                       `json:"result"`
	AssertionIDs    []string                     `json:"assertionIds"`
	WitnessIDs      []string                     `json:"witnessIds"`
	SubjectPinIDs   []string                     `json:"subjectPinIds"`
	Executor        string                       `json:"executor"`
	ExecutorHash    string                       `json:"executorHash"`
	Environment     []string                     `json:"environment"`
	Commands        []EvidenceCommandResult      `json:"commands"`
	Artifacts       []EvidenceArtifact           `json:"artifacts"`
	Bindings        []EvidenceObligationBindings `json:"bindings"`
	ToolchainHash   string                       `json:"toolchainHash"`
	EnvironmentHash string                       `json:"environmentHash"`
	Durability      int                          `json:"durability"`
	TranscriptHash  string                       `json:"transcriptHash"`
}

func ExecuteRequest

func ExecuteRequest(ctx context.Context, databasePath, root, requestID, outputPath string) (*EvidenceRun, error)

func (*EvidenceRun) RecordID

func (r *EvidenceRun) RecordID() string

func (*EvidenceRun) RecordKind

func (r *EvidenceRun) RecordKind() Kind

type EvidenceTraceArtifact

type EvidenceTraceArtifact struct {
	WitnessType string                         `json:"witnessType"`
	Captures    []EvidenceTraceArtifactCapture `json:"captures"`
}

type EvidenceTraceArtifactCapture

type EvidenceTraceArtifactCapture struct {
	TargetID string               `json:"targetId"`
	Events   []EvidenceTraceEvent `json:"events"`
}

type EvidenceTraceEvent

type EvidenceTraceEvent struct {
	Ordinal   int    `json:"ordinal"`
	Kind      string `json:"kind"`
	Subject   string `json:"subject"`
	ValueHash string `json:"valueHash"`
}

type EvidenceWitnessRequest

type EvidenceWitnessRequest struct {
	WitnessType    string   `json:"witnessType"`
	TargetIDs      []string `json:"targetIds"`
	SubjectPinIDs  []string `json:"subjectPinIds"`
	CommandIndexes []int    `json:"commandIndexes"`
	ArtifactPath   string   `json:"artifactPath,omitempty"`
}

type ExecutionWitness

type ExecutionWitness struct {
	Kind             Kind                      `json:"kind"`
	ID               string                    `json:"id"`
	SnapshotID       string                    `json:"snapshotId"`
	RequestID        string                    `json:"requestId"`
	WitnessType      string                    `json:"witnessType"`
	TargetIDs        []string                  `json:"targetIds"`
	SubjectPinIDs    []string                  `json:"subjectPinIds"`
	Artifacts        []EvidenceArtifact        `json:"artifacts"`
	CoveredRanges    []EvidenceCoveredRange    `json:"coveredRanges"`
	ProviderCaptures []EvidenceProviderCapture `json:"providerCaptures"`
}

func (*ExecutionWitness) RecordID

func (r *ExecutionWitness) RecordID() string

func (*ExecutionWitness) RecordKind

func (r *ExecutionWitness) RecordKind() Kind

type Facet

type Facet struct {
	Kind Kind   `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name"`
}

func (*Facet) RecordID

func (r *Facet) RecordID() string

func (*Facet) RecordKind

func (r *Facet) RecordKind() Kind

type Fact

type Fact struct {
	Kind       Kind            `json:"kind"`
	ID         string          `json:"id"`
	SnapshotID string          `json:"snapshotId"`
	FactType   string          `json:"factType"`
	SubjectID  string          `json:"subjectId"`
	Resolution string          `json:"resolution"`
	PinIDs     []string        `json:"pinIds"`
	Value      json.RawMessage `json:"value"`
}

func (*Fact) RecordID

func (r *Fact) RecordID() string

func (*Fact) RecordKind

func (r *Fact) RecordKind() Kind

type GrantPlan

type GrantPlan struct {
	Grantable    []WorkUnit
	Parked       []WorkUnit
	Blocked      []WorkUnit
	Deferred     []WorkUnit
	Held         []string
	BudgetHalted bool
}

GrantPlan is the deterministic outcome of one scheduling step. Every open work unit lands in exactly one bucket, so the controller can grant Grantable now, leave Parked for a human, and revisit Deferred and Blocked on a later step without losing, duplicating, or silently skipping any unit.

func PlanCampaignGrants

func PlanCampaignGrants(graph *Graph, manifest CampaignManifest, active []Lease) (GrantPlan, error)

PlanCampaignGrants selects the next units to lease from the current graph and active lease set. It is pure and resumable: a unit already covered by an active lease is Held and never re-granted, a unit whose behavior awaits a human decision is Parked while others proceed, a unit that would overlap an active lease is Blocked, and a ready unit beyond the budget is Deferred with BudgetHalted set. Re-running it after the granted leases become active yields the same partition minus the newly held units, so a killed campaign resumes without drift.

func (GrantPlan) String

func (p GrantPlan) String() string

type Graph

type Graph struct {
	Records      map[string]Record
	RecordHashes map[string]string
	Verdicts     map[string]Verdict
}

func Build

func Build(records []Record) (*Graph, error)

func (*Graph) EffectiveVerdicts

func (g *Graph) EffectiveVerdicts() []Verdict

type Hypothesis

type Hypothesis struct {
	Kind           Kind            `json:"kind"`
	ID             string          `json:"id"`
	SnapshotID     string          `json:"snapshotId"`
	HypothesisType string          `json:"hypothesisType"`
	SubjectID      string          `json:"subjectId"`
	PinIDs         []string        `json:"pinIds"`
	Value          json.RawMessage `json:"value"`
}

func (*Hypothesis) RecordID

func (r *Hypothesis) RecordID() string

func (*Hypothesis) RecordKind

func (r *Hypothesis) RecordKind() Kind

type Kind

type Kind string
const (
	KindSnapshot            Kind = "snapshot"
	KindPin                 Kind = "pin"
	KindFact                Kind = "fact"
	KindHypothesis          Kind = "hypothesis"
	KindProvisionalClaim    Kind = "provisional-claim"
	KindFacet               Kind = "facet"
	KindRule                Kind = "rule"
	KindBehavior            Kind = "behavior"
	KindObligation          Kind = "obligation"
	KindTarget              Kind = "target"
	KindMapping             Kind = "mapping"
	KindReachability        Kind = "reachability"
	KindTest                Kind = "test"
	KindAssertion           Kind = "assertion"
	KindExecutionWitness    Kind = "execution-witness"
	KindEvidenceRequest     Kind = "evidence-request"
	KindEvidenceRun         Kind = "evidence-run"
	KindEvidenceAttestation Kind = "evidence-attestation"
	KindMutant              Kind = "mutant"
	KindMutationRequest     Kind = "mutation-request"
	KindMutationRun         Kind = "mutation-run"
	KindMutationAttestation Kind = "mutation-attestation"
	KindDecision            Kind = "decision"
	KindLease               Kind = "lease"
	KindScenarioRun         Kind = "scenario-run"
)

type Lease

type Lease struct {
	Kind            Kind       `json:"kind"`
	ID              string     `json:"id"`
	WorkUnitID      string     `json:"workUnitId"`
	SnapshotID      string     `json:"snapshotId"`
	Holder          string     `json:"holder"`
	BaseFingerprint string     `json:"baseFingerprint"`
	State           LeaseState `json:"state"`
}

Lease grants one work unit to one holder against an exact base fingerprint. Integration rejects a lease whose base no longer matches the current graph, so a worker cannot integrate a patch built on stale support. A lease is a durable receipt of a derived grant: every field is derived at grant time, never authored.

func ActiveLeases

func ActiveLeases(graph *Graph) []Lease

ActiveLeases returns the persisted active leases in deterministic ID order. Integrated leases are excluded because they no longer contend for overlap.

func GrantLease

func GrantLease(graph *Graph, active []Lease, units map[string]WorkUnit, workUnitID, holder string) (Lease, error)

GrantLease atomically admits a new lease against the active set. It fails closed on an unknown unit, a stale base fingerprint, or any overlap with an active lease: textual write/test/fixture path intersection, or semantic boundary intersection across otherwise disjoint files.

func (*Lease) RecordID

func (r *Lease) RecordID() string

func (*Lease) RecordKind

func (r *Lease) RecordKind() Kind

type LeaseState

type LeaseState string

LeaseState is the persisted lifecycle of a lease. A lease is active while its holder works and integrated once its patch has landed on canonical; only active leases participate in the overlap-admission set.

const (
	LeaseActive     LeaseState = "active"
	LeaseIntegrated LeaseState = "integrated"
)

type Mapping

type Mapping struct {
	Kind       Kind     `json:"kind"`
	ID         string   `json:"id"`
	BehaviorID string   `json:"behaviorId"`
	TargetIDs  []string `json:"targetIds"`
	Status     string   `json:"status"`
	DecisionID string   `json:"decisionId,omitempty"`
	RuleID     string   `json:"ruleId,omitempty"`
	FactIDs    []string `json:"factIds,omitempty"`
}

func (*Mapping) RecordID

func (r *Mapping) RecordID() string

func (*Mapping) RecordKind

func (r *Mapping) RecordKind() Kind

type Mutant

type Mutant struct {
	Kind                Kind         `json:"kind"`
	ID                  string       `json:"id"`
	SnapshotID          string       `json:"snapshotId"`
	ObligationID        string       `json:"obligationId"`
	TestID              string       `json:"testId"`
	TargetID            string       `json:"targetId"`
	PinID               string       `json:"pinId"`
	Facet               string       `json:"facet"`
	Mode                string       `json:"mode"`
	Operator            string       `json:"operator"`
	Edit                MutationEdit `json:"edit"`
	ExpectedFailureTest string       `json:"expectedFailureTest,omitempty"`
	ExpectedFailureHash string       `json:"expectedFailureHash"`
}

func NewMutant

func NewMutant(snapshotID, obligationID, testID, targetID, pinID, facet, mode, operator string, edit MutationEdit, expectedFailureTest, expectedFailureHash string) (*Mutant, error)

func (*Mutant) RecordID

func (r *Mutant) RecordID() string

func (*Mutant) RecordKind

func (r *Mutant) RecordKind() Kind

type MutationAttestation

type MutationAttestation struct {
	Kind             Kind               `json:"kind"`
	ID               string             `json:"id"`
	RunID            string             `json:"runId"`
	RepositoryCommit string             `json:"repositoryCommit"`
	Path             string             `json:"path"`
	Artifacts        []EvidenceArtifact `json:"artifacts"`
}

func (*MutationAttestation) RecordID

func (r *MutationAttestation) RecordID() string

func (*MutationAttestation) RecordKind

func (r *MutationAttestation) RecordKind() Kind

type MutationEdit

type MutationEdit struct {
	Path         string `json:"path"`
	OriginalHash string `json:"originalHash"`
	Before       string `json:"before"`
	After        string `json:"after"`
	MutatedHash  string `json:"mutatedHash"`
}

type MutationRequest

type MutationRequest struct {
	Kind           Kind              `json:"kind"`
	ID             string            `json:"id"`
	SnapshotID     string            `json:"snapshotId"`
	ObligationID   string            `json:"obligationId"`
	TestID         string            `json:"testId"`
	MutantIDs      []string          `json:"mutantIds"`
	Commands       []EvidenceCommand `json:"commands"`
	Environment    []string          `json:"environment"`
	TimeoutSeconds int               `json:"timeoutSeconds"`
}

func NewMutationRequest

func NewMutationRequest(snapshotID, obligationID, testID string, mutants []*Mutant, commands []EvidenceCommand, environment []string, timeoutSeconds int) (*MutationRequest, error)

func (*MutationRequest) RecordID

func (r *MutationRequest) RecordID() string

func (*MutationRequest) RecordKind

func (r *MutationRequest) RecordKind() Kind

type MutationResult

type MutationResult struct {
	MutantID     string `json:"mutantId"`
	CommandIndex int    `json:"commandIndex,omitempty"`
	FailureHash  string `json:"failureHash"`
	BoundTest    string `json:"boundTest,omitempty"`
	FailureTest  string `json:"failureTest,omitempty"`
	MutatedPath  string `json:"mutatedPath"`
	MutatedHash  string `json:"mutatedHash"`
	DecisionID   string `json:"decisionId,omitempty"`
}

type MutationRun

type MutationRun struct {
	Kind             Kind                    `json:"kind"`
	ID               string                  `json:"id"`
	RequestID        string                  `json:"requestId"`
	SnapshotID       string                  `json:"snapshotId"`
	RepositoryCommit string                  `json:"repositoryCommit"`
	Executor         string                  `json:"executor"`
	ExecutorHash     string                  `json:"executorHash"`
	Environment      []string                `json:"environment"`
	Baselines        []EvidenceCommandResult `json:"baselines"`
	Commands         []EvidenceCommandResult `json:"commands"`
	Results          []MutationResult        `json:"results"`
	Artifacts        []EvidenceArtifact      `json:"artifacts"`
	Support          []EvidenceBinding       `json:"support"`
	ToolchainHash    string                  `json:"toolchainHash"`
	EnvironmentHash  string                  `json:"environmentHash"`
}

func ExecuteMutationRequest

func ExecuteMutationRequest(ctx context.Context, databasePath, root, requestID, outputPath string) (*MutationRun, error)

func (*MutationRun) RecordID

func (r *MutationRun) RecordID() string

func (*MutationRun) RecordKind

func (r *MutationRun) RecordKind() Kind

type Obligation

type Obligation struct {
	Kind         Kind     `json:"kind"`
	ID           string   `json:"id"`
	BehaviorID   string   `json:"behaviorId"`
	FacetID      string   `json:"facetId"`
	RuleID       string   `json:"ruleId"`
	OriginPinIDs []string `json:"originPinIds"`
}

func (*Obligation) RecordID

func (r *Obligation) RecordID() string

func (*Obligation) RecordKind

func (r *Obligation) RecordKind() Kind

type Pin

type Pin struct {
	Kind       Kind   `json:"kind"`
	ID         string `json:"id"`
	SnapshotID string `json:"snapshotId"`
	Repository string `json:"repository"`
	Commit     string `json:"commit"`
	Path       string `json:"path"`
	SemanticID string `json:"semanticId"`
	StartLine  int    `json:"startLine"`
	EndLine    int    `json:"endLine"`
	QuoteHash  string `json:"quoteHash"`
	APIHash    string `json:"apiHash,omitempty"`
	BodyHash   string `json:"bodyHash,omitempty"`
}

func (*Pin) RecordID

func (r *Pin) RecordID() string

func (*Pin) RecordKind

func (r *Pin) RecordKind() Kind

type ProvisionalClaim

type ProvisionalClaim struct {
	Kind        Kind   `json:"kind"`
	ID          string `json:"id"`
	SnapshotID  string `json:"snapshotId"`
	SubjectID   string `json:"subjectId"`
	SourcePinID string `json:"sourcePinId"`
	Status      string `json:"status"`
}

func (*ProvisionalClaim) RecordID

func (r *ProvisionalClaim) RecordID() string

func (*ProvisionalClaim) RecordKind

func (r *ProvisionalClaim) RecordKind() Kind

type Reachability

type Reachability struct {
	Kind        Kind     `json:"kind"`
	ID          string   `json:"id"`
	BehaviorID  string   `json:"behaviorId"`
	TargetID    string   `json:"targetId"`
	Class       string   `json:"class"`
	Method      string   `json:"method"`
	RootPinIDs  []string `json:"rootPinIds"`
	Uncertainty string   `json:"uncertainty,omitempty"`
}

func (*Reachability) RecordID

func (r *Reachability) RecordID() string

func (*Reachability) RecordKind

func (r *Reachability) RecordKind() Kind

type Record

type Record interface {
	RecordKind() Kind
	RecordID() string
}

func AddAgentBundleSubmission

func AddAgentBundleSubmission(records []Record, submission *correspondence.AgentBundleSubmission) ([]Record, error)

func AddAgentProposals

func AddAgentProposals(records []Record, proposals []correspondence.AgentProposal) ([]Record, error)

func AddCompactionSettingsAssertions

func AddCompactionSettingsAssertions(root string, snapshot *Snapshot, records []Record) ([]Record, error)

func AddCompactionSettingsBehaviors

func AddCompactionSettingsBehaviors(root string, snapshot *Snapshot, records []Record) ([]Record, error)

func AddCompactionSettingsEvidenceRequests

func AddCompactionSettingsEvidenceRequests(records []Record) ([]Record, error)

func AddCorrespondenceAssertions

func AddCorrespondenceAssertions(root string, snapshot *Snapshot, records []Record) ([]Record, error)

func AddCorrespondenceDenominator

func AddCorrespondenceDenominator(ctx context.Context, root string, snapshot *Snapshot, records []Record) ([]Record, error)

AddCorrespondenceDenominator compiles the normalized Pi/Pig correspondence inventories into deterministic facts and open closure obligations. Direct setting identities may derive mappings; function candidates remain hypotheses.

func AddCorrespondenceEvidenceRequests

func AddCorrespondenceEvidenceRequests(records []Record) ([]Record, error)

func AddProviderWireAssertions

func AddProviderWireAssertions(root string, snapshot *Snapshot, records []Record) ([]Record, error)

func AddProviderWireBehaviors

func AddProviderWireBehaviors(root string, snapshot *Snapshot, records []Record) ([]Record, error)

func AddProviderWireEvidenceRequests

func AddProviderWireEvidenceRequests(records []Record) ([]Record, error)

func AttestEvidenceRun

func AttestEvidenceRun(ctx context.Context, root, evidenceDir, message string) ([]Record, error)

AttestEvidenceRun commits the evidence output directory produced by ExecuteRequest and loads its attestation, returning the attestation records (evidence run, witnesses, attestation) ready to fold into a store. Committing is required and not incidental: LoadEvidenceAttestation only trusts evidence whose artifacts are tracked and unchanged in the repository, so attestation is exactly the act of committing the captured evidence.

func DecodeJSONL

func DecodeJSONL(input io.Reader) ([]Record, error)

func LoadEvidenceAttestation

func LoadEvidenceAttestation(ctx context.Context, root, configured string) ([]Record, error)

func LoadMutationRun

func LoadMutationRun(ctx context.Context, root, configured string) ([]Record, error)

type Rule

type Rule struct {
	Kind           Kind   `json:"kind"`
	ID             string `json:"id"`
	Name           string `json:"name"`
	DefinitionHash string `json:"definitionHash"`
}

func (*Rule) RecordID

func (r *Rule) RecordID() string

func (*Rule) RecordKind

func (r *Rule) RecordKind() Kind

type ScenarioRun

type ScenarioRun struct {
	Kind           Kind               `json:"kind"`
	ID             string             `json:"id"`
	SnapshotID     string             `json:"snapshotId"`
	ScenarioFactID string             `json:"scenarioFactId"`
	Outcome        string             `json:"outcome"`
	Runs           int                `json:"runs"`
	Comparator     string             `json:"comparator"`
	CommandHash    string             `json:"commandHash"`
	Artifacts      []EvidenceArtifact `json:"artifacts"`
}

ScenarioRun is a canonical, content-addressed record of one parity scenario execution. It binds the scenario denominator fact to an attested pass/fail outcome under an exact snapshot, comparator, command, and captured artifacts, so family and scenario reports can derive coverage from proof rather than asserting it. A pass credits the scenario; a fail contradicts it. The record carries no unverified narrative and fails Build if its ID is not the hash of its own content.

func (*ScenarioRun) RecordID

func (r *ScenarioRun) RecordID() string

func (*ScenarioRun) RecordKind

func (r *ScenarioRun) RecordKind() Kind

type Snapshot

type Snapshot struct {
	Kind            Kind     `json:"kind"`
	ID              string   `json:"id"`
	UpstreamCommit  string   `json:"upstreamCommit"`
	TargetCommit    string   `json:"targetCommit"`
	ToolchainHash   string   `json:"toolchainHash"`
	EnvironmentHash string   `json:"environmentHash"`
	ExtractorHashes []string `json:"extractorHashes,omitempty"`
	RulePackHashes  []string `json:"rulePackHashes,omitempty"`
}

func (*Snapshot) RecordID

func (r *Snapshot) RecordID() string

func (*Snapshot) RecordKind

func (r *Snapshot) RecordKind() Kind

type Target

type Target struct {
	Kind       Kind     `json:"kind"`
	ID         string   `json:"id"`
	SnapshotID string   `json:"snapshotId"`
	PinIDs     []string `json:"pinIds"`
	FactIDs    []string `json:"factIds,omitempty"`
	Language   string   `json:"language"`
	Symbol     string   `json:"symbol"`
}

func (*Target) RecordID

func (r *Target) RecordID() string

func (*Target) RecordKind

func (r *Target) RecordKind() Kind

type Test

type Test struct {
	Kind           Kind           `json:"kind"`
	ID             string         `json:"id"`
	SnapshotID     string         `json:"snapshotId"`
	PinID          string         `json:"pinId"`
	FixturePinIDs  []string       `json:"fixturePinIds"`
	DefinitionHash string         `json:"definitionHash"`
	MutationPolicy string         `json:"mutationPolicy,omitempty"`
	Execution      *TestExecution `json:"execution,omitempty"`
}

func (*Test) RecordID

func (r *Test) RecordID() string

func (*Test) RecordKind

func (r *Test) RecordKind() Kind

type TestExecution

type TestExecution struct {
	Package    string   `json:"package"`
	RunName    string   `json:"runName"`
	BuildTags  []string `json:"buildTags,omitempty"`
	Comparator string   `json:"comparator"`
}

TestExecution records how to run a test mechanically, so an autonomous verifier can synthesize an EvidenceRequest from the graph rather than from an authored command switch (provider-wire derives these today from a hardcoded table). The recipe is Go-specific for the common case: run one test function in a package with a coverage profile. Heterogeneous recipes (differentials, multi-command traces) stay authored and leave Execution empty; a synthesizer fails closed for them rather than guessing.

type Verdict

type Verdict struct {
	ObligationID  string       `json:"obligationId"`
	State         VerdictState `json:"state"`
	SupportHashes []string     `json:"supportHashes"`
	Reason        string       `json:"reason"`
}

type VerdictState

type VerdictState string
const (
	VerdictOpen         VerdictState = "open"
	VerdictProvisional  VerdictState = "provisional"
	VerdictProven       VerdictState = "proven"
	VerdictWaived       VerdictState = "waived"
	VerdictContradicted VerdictState = "contradicted"
)

type WorkUnit

type WorkUnit struct {
	ID                  string
	SnapshotID          string
	BehaviorID          string
	ObligationIDs       []string
	WritePaths          []string
	TestPaths           []string
	FixturePaths        []string
	SemanticBoundaryIDs []string
}

WorkUnit is a graph-derived parallel ownership unit rooted at one open behavior. It carries the exact repository paths a Translator may write and the upstream semantic boundaries the behavior depends on. Two units conflict when their write footprints overlap textually or their semantic boundaries intersect, even across disjoint files. Work units are derived, never authored.

func PlanWorkUnits

func PlanWorkUnits(graph *Graph) ([]WorkUnit, error)

PlanWorkUnits derives one work unit per open behavior root from the closure graph. The result is deterministic: units are sorted by ID and every path and boundary list is sorted and de-duplicated.

Jump to

Keyboard shortcuts

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