Documentation
¶
Overview ¶
Package closure stores and verifies the evidence graph used to assess PiG's correspondence with the pinned Pi source.
Index ¶
- Constants
- func AssertionAudit(ctx context.Context, databasePath, root string) ([]byte, error)
- func ConfineFactDiffToUnit(graph *Graph, unit WorkUnit, changedPaths []string) error
- func ConfinePatchToLease(lease Lease, unit WorkUnit, bundle *correspondence.TranslatorBundle) error
- func ContentHash(record Record) (string, error)
- func CurrentEnvironmentHash(configured []string) (string, error)
- func CurrentToolchainHash(ctx context.Context) (string, error)
- func EvidenceReadiness(ctx context.Context, path string) ([]byte, error)
- func ExpectedGoTestFailureHash(expectedTest string, outputs []string) (string, error)
- func Explain(ctx context.Context, path, obligationID string) ([]byte, error)
- func Frontier(ctx context.Context, path, recordID string) ([]byte, error)
- func GrantLeaseInStore(ctx context.Context, path, workUnitID, holder string) ([]byte, error)
- func HashBytes(value []byte) string
- func ImportCurrentDenominators(root string, snapshot *Snapshot) ([]Record, DenominatorImportReport, error)
- func IntegrateLease(current *Graph, lease Lease, units map[string]WorkUnit) error
- func IntegrateLeaseInStore(ctx context.Context, path, leaseID string) ([]byte, error)
- func MappingReview(ctx context.Context, path string) ([]byte, error)
- func MutationReadiness(ctx context.Context, path string) ([]byte, error)
- func PlanUnits(ctx context.Context, path string) ([]byte, error)
- func ReadEvidenceRequest(ctx context.Context, path, requestID string) ([]byte, error)
- func ReadMutationRequest(ctx context.Context, path, requestID string) ([]byte, error)
- func ReadReport(ctx context.Context, path, dataset string) ([]byte, error)
- func ReadStatus(ctx context.Context, path string) ([]byte, error)
- func RebuildStore(ctx context.Context, path string, graph *Graph) error
- func RenderCoverageAudit(audit CoverageAudit) []byte
- func RenderReport(graph *Graph, dataset string) ([]byte, error)
- func RenderStatus(verdicts []Verdict, provisionalClaims ...ProvisionalClaim) ([]byte, error)
- func ReportDatasets() []string
- func SafeStorePath(root, configured string) (string, error)
- func ValidHash(value string) bool
- func VerdictDrift(before, after *Graph) []string
- func VerifyRequestIntoStore(ctx context.Context, root, storePath, requestID, evidenceDir, message string) (*EvidenceRun, []Verdict, error)
- func VerifyStore(ctx context.Context, path string) error
- func WhyOpen(ctx context.Context, path string) ([]byte, error)
- func WorkUnitBaseFingerprint(graph *Graph, unit WorkUnit) (string, error)
- type AffectedTests
- type AgentWorkScope
- type AppliedPatch
- type Assertion
- type AssertionAuditRow
- type AssertionCandidate
- type Behavior
- type BranchOutcome
- type CampaignAuditEntry
- type CampaignBudget
- type CampaignManifest
- type CampaignStepResult
- type CandidatePatchProof
- type CoverageAudit
- type CoverageBlock
- type CoverageScope
- type Decision
- type DeltaBrief
- type DenominatorImportReport
- type EvidenceArtifact
- type EvidenceAttestation
- type EvidenceBinding
- type EvidenceCommand
- type EvidenceCommandResult
- type EvidenceCoveredRange
- type EvidenceObligationBindings
- type EvidenceProviderCapture
- type EvidenceRequest
- type EvidenceRun
- type EvidenceTraceArtifact
- type EvidenceTraceArtifactCapture
- type EvidenceTraceEvent
- type EvidenceWitnessRequest
- type ExecutionWitness
- type Facet
- type Fact
- type GrantPlan
- type Graph
- type Hypothesis
- type Kind
- type Lease
- type LeaseState
- type Mapping
- type Mutant
- type MutationAttestation
- type MutationEdit
- type MutationRequest
- type MutationResult
- type MutationRun
- type Obligation
- type Pin
- type ProvisionalClaim
- type Reachability
- type Record
- func AddAgentBundleSubmission(records []Record, submission *correspondence.AgentBundleSubmission) ([]Record, error)
- func AddAgentProposals(records []Record, proposals []correspondence.AgentProposal) ([]Record, error)
- func AddCompactionSettingsAssertions(root string, snapshot *Snapshot, records []Record) ([]Record, error)
- func AddCompactionSettingsBehaviors(root string, snapshot *Snapshot, records []Record) ([]Record, error)
- func AddCompactionSettingsEvidenceRequests(records []Record) ([]Record, error)
- func AddCorrespondenceAssertions(root string, snapshot *Snapshot, records []Record) ([]Record, error)
- func AddCorrespondenceDenominator(ctx context.Context, root string, snapshot *Snapshot, records []Record) ([]Record, error)
- func AddCorrespondenceEvidenceRequests(records []Record) ([]Record, error)
- func AddProviderWireAssertions(root string, snapshot *Snapshot, records []Record) ([]Record, error)
- func AddProviderWireBehaviors(root string, snapshot *Snapshot, records []Record) ([]Record, error)
- func AddProviderWireEvidenceRequests(records []Record) ([]Record, error)
- func AttestEvidenceRun(ctx context.Context, root, evidenceDir, message string) ([]Record, error)
- func DecodeJSONL(input io.Reader) ([]Record, error)
- func LoadEvidenceAttestation(ctx context.Context, root, configured string) ([]Record, error)
- func LoadMutationRun(ctx context.Context, root, configured string) ([]Record, error)
- type Rule
- type ScenarioRun
- type Snapshot
- type Target
- type Test
- type TestExecution
- type Verdict
- type VerdictState
- type WorkUnit
Constants ¶
const ( FamilyCoverageDataset = "family-coverage" ScenarioQualityDataset = "scenario-quality" )
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" )
const ( ScenarioOutcomePass = "pass" ScenarioOutcomeFail = "fail" )
ScenarioOutcomePass and ScenarioOutcomeFail are the only recognized outcomes of a canonical parity scenario run.
const DivergenceDashboardDataset = "divergence"
const FoundationDashboardDataset = "foundation"
Variables ¶
This section is empty.
Functions ¶
func AssertionAudit ¶
func ConfineFactDiffToUnit ¶
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 CurrentEnvironmentHash ¶
func ExpectedGoTestFailureHash ¶
ExpectedGoTestFailureHash derives the exact structured failure identity used by automatic Go mutants from the bound test's expected output events.
func GrantLeaseInStore ¶
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 ImportCurrentDenominators ¶
func ImportCurrentDenominators(root string, snapshot *Snapshot) ([]Record, DenominatorImportReport, error)
func IntegrateLease ¶
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 ¶
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 PlanUnits ¶
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 ¶
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 ReadReport ¶
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 RenderCoverageAudit ¶
func RenderCoverageAudit(audit CoverageAudit) []byte
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 VerdictDrift ¶
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 WorkUnitBaseFingerprint ¶
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 ¶
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 ¶
func ReadAgentWorkScope ¶
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) RecordKind ¶
type AssertionAuditRow ¶
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) RecordKind ¶
type BranchOutcome ¶
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 ¶
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 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 ¶
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) RecordKind ¶
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 EvidenceArtifact ¶
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 EvidenceCommand ¶
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 EvidenceObligationBindings ¶
type EvidenceObligationBindings struct {
ObligationID string `json:"obligationId"`
Support []EvidenceBinding `json:"support"`
}
type EvidenceProviderCapture ¶
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 EvidenceWitnessRequest ¶
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 ¶
func (*Facet) RecordKind ¶
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) RecordKind ¶
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.
type Graph ¶
type Graph struct {
Records map[string]Record
RecordHashes map[string]string
Verdicts map[string]Verdict
}
func (*Graph) EffectiveVerdicts ¶
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 ¶
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) RecordKind ¶
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) RecordKind ¶
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) RecordKind ¶
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 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) RecordKind ¶
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 ¶
func AddAgentBundleSubmission ¶
func AddAgentBundleSubmission(records []Record, submission *correspondence.AgentBundleSubmission) ([]Record, error)
func AddAgentProposals ¶
func AddAgentProposals(records []Record, proposals []correspondence.AgentProposal) ([]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 AttestEvidenceRun ¶
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 LoadEvidenceAttestation ¶
type Rule ¶
type Rule struct {
Kind Kind `json:"kind"`
ID string `json:"id"`
Name string `json:"name"`
DefinitionHash string `json:"definitionHash"`
}
func (*Rule) RecordKind ¶
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) RecordKind ¶
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) RecordKind ¶
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) RecordKind ¶
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 ¶
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.
Source Files
¶
- agent_proposals.go
- assertions.go
- attestation.go
- campaign.go
- campaign_controller.go
- commit_path.go
- compaction_settings.go
- compaction_settings_assertions.go
- correspondence.go
- correspondence_assertions.go
- coverage.go
- decode.go
- denominator_import.go
- derive.go
- divergence_report.go
- doc.go
- executor.go
- family_report.go
- foundation_report.go
- graph.go
- integrator.go
- lease.go
- mutation.go
- provider_wire.go
- provider_wire_assertions.go
- provider_wire_requests.go
- reconciliation.go
- replace_unix.go
- report.go
- report_projection.go
- scenario_run.go
- store.go
- synthesize.go
- types.go
- verify.go