result

package
v0.27.1 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	OutputVersion = "2"
	CLIName       = "jpack"
)

OutputVersion is the machine-output protocol version of every payload this runtime writes. VERSIONING.md makes it a protocol version and not the CLI release version, and requires a change that breaks machine-output compatibility to increment it deliberately. It became "2" when the experimental-evaluation payloads replaced their conformanceClaim member with the conformanceClaimReference member of this file (ADR-0011): a consumer that read the old member name finds no member of that name, which is a break and not an added field. The CHANGELOG entry for that change carries the migration.

View Source 
const (
	ExitSuccess     = 0
	ExitInvalid     = 1
	ExitUnsupported = 2
	ExitInvocation  = 3
	ExitIO          = 4
	ExitInternal    = 5
)
View Source 
const (
	NoHandoffTarget          = "null"
	HandoffTargetUnavailable = "unavailable"
)

NoHandoffTarget is the rendering of "no target at all" — the JSON literal a row writes to assert it, and what Canonical returns for an evaluation that reported none.

HandoffTargetUnavailable is the third state a *reported* target can be in, and it is deliberately not null: it says the report cannot state a target, where null says an evaluation reported none. Substituting null would report a §8.3 statement no evaluation made.

It has three causes, and a consumer tells the first from the others by whether the row carries an §8.4 class. The evaluation was **refused**, so it produced no answer at all. Or the evaluation produced one and **no rendering was computed** for the pack — a state no surface of this runtime reaches, since the caller that owns a row loop renders once for the pack before the loop. Or a rendering was supplied that was minted from **different pack bytes**, which is refused rather than repeated: the report declines to name a destination rather than risk naming the wrong one (ADR-0025). That last refusal is by the bytes and not by the target, so a rendering of a *different* pack that happens to declare the *same* destination degrades too — honest rather than pedantic, because what such a handle proves is only where it came from, and it did not come from here.

View Source 
const (
	HandoffTargetBudget    = 256
	HandoffTargetDigestHex = 16
)

The rendering budget of a reported handoff target, on ADR-0023's own footing and for its own reason. A target's kind and name are authored strings §2.1 bounds only at a megabyte each, and a matrix may declare MaxMatrixCases rows; a report retaining an uncapped rendering per row is gigabytes built out of inputs every carrier limit admits, which crosses the MCP response bound and turns a call that used to succeed into a refusal.

So the rendering is bounded here, at the one writer, rather than guarded at each of its readers. Within the budget a target renders exactly as it canonicalizes; beyond it the rendering is the prefix, an ellipsis, and the first HandoffTargetDigestHex hex digits of the SHA-256 of the full canonical bytes.

A capped rendering is a **display value and never an equality key.** The digest tail makes an accidental collision between two authored targets unlikely, and unlikely is not the standard a comparison is held to: sixty-four bits of digest deciding whether a suite passes would be a probabilistic answer to a question with an exact one. Whatever compares two targets compares the decoded values — presence, then each member in full — and reads these renderings only to say what it saw.

View Source 
const (
	ClassPackNotConformant            = "pack-not-conformant"
	ClassMalformedInput               = "malformed-input"
	ClassUnsupportedRequiredExtension = "unsupported-required-extension"
	ClassResourceExhaustion           = "resource-exhaustion"
)

Evaluation-error classes of JPS Core §8.4, in the fixed precedence order that section requires: the first class that applies to one evaluation's inputs is the class reported. An evaluation error is never a disposition.

View Source 
const (
	PhasePreflight  = "preflight"
	PhaseEvaluation = "evaluation"
)

Evaluation-error phases of JPS Core §8.4: a limit reached while admitting an input (§8.2) belongs to the preflight, and one reached while evaluating an admitted input belongs to the evaluation.

View Source 
const (
	MatrixProbeCovered = "covered"
	MatrixProbeMissing = "missing"
)

The status of one derived coverage probe in a packs test report. A probe is covered when some row witnesses it — by its expectation for a disposition probe, by its authored facts for a boundary probe — and missing when no row does. There is no third status: a probe the pack's own declarations make unreachable is not derived at all, because listing it as skipped would state a reachability claim in a status field.

View Source 
const (
	PackCheckPassed  = "passed"
	PackCheckFailed  = "failed"
	PackCheckSkipped = "skipped"
)

The status of one check in a packs validate report. A skipped check is one the configuration did not ask for — an absent expectedVersion, an absent matrix, absent hints, a filename outside the optional convention — or one an earlier failure left nothing to run, and it is reported rather than silently omitted, so a reader can tell "this passed" from "this was never checked".

View Source 
const (
	PackVersionUnset   = "unset"
	PackVersionMatches = "matches"
	PackVersionDiffers = "differs"
	PackVersionUnknown = "unknown"
)

The expectedVersion outcomes of one inventory row. "unset" means the entry pins no version, "matches" and "differs" compare the pin against the pack document's own version member, and "unknown" means the document could not be read to compare against — which is not a match and is never reported as one.

View Source 
const CheckpointVersion = "1"

CheckpointVersion is the shape of an audit checkpoint (ADR-0047 §1, §2a), a single integer as a string on the outputVersion precedent.

View Source 
const ComparisonLabel = "" /* 221-byte string literal not displayed */

ComparisonLabel labels every comparison of two pack versions (ADR-0045). A difference says the two documents decide an input differently and nothing about which of them is right, so the label says so wherever the payload goes.

View Source 
const EvaluationClaimReference = "CONFORMANCE.md"

EvaluationClaimReference is carried by every experimental-evaluation payload, and it is a locator rather than a claim: the conformance claim is stated, in full and only, in CONFORMANCE.md, and this member says where to read it (ADR-0011).

It is deliberately not a restatement. §3.4.1 fixes the entire form a claim may take — the class, one exact specVersion, the corpus version, the results obtained, and in the claim's own words that every row of that corpus version passed — so a payload member naming only a class and a version would carry part of that form and omit the rest, which is the partial claim §3.4.1 forbids. The payload therefore points at the one document that carries all of it and asserts nothing about conformance itself. The version scope a consumer needs in band is EvaluatorSpecVersion, which is a fact about the contract this evaluator applied and not a claim about conformance to it.

The member was "none" under ADR-0007 and ADR-0010, when denying a claim was accurate; it is now a reference, and its member name changed with its meaning (conformanceClaimReference, OutputVersion "2").

View Source 
const EvaluationCorpusLabel = "corpus results, the required evidence for the claim in CONFORMANCE.md"

EvaluationCorpusLabel labels every evaluation-corpus run this runtime reports. A run is results, and the claim those results are evidence for is one document with one scope: §3.4.1 makes corpus results required evidence for the claim and not exhaustive evidence of it, so a passing run neither is the claim nor exhausts it. The label points at the claim rather than denying one, which is what it did before ADR-0011.

View Source 
const EvaluatorSpecVersion = "0.2.0-draft"

EvaluatorSpecVersion names the exact JPS Core version whose evaluator contract this runtime's experimental evaluator applies: the §8.2 input preflight, the §8.3 portable disposition, and the §8.4 error classes and their precedence.

It is reported independently of the pack's own specVersion, and every evaluation payload carries both, because they are two different facts even though this evaluator now requires them to be equal: §11 makes the declared value exact, so a pack must declare this version to be evaluated at all, and a pack declaring any other is refused as pack-not-conformant in the preflight phase (evaluation.declaredSpecVersion). Keeping both members means a consumer reads the contract that was applied from the payload rather than inferring it from the pack, and it survives a later version that admits more than one.

It is also the exact version the claim in CONFORMANCE.md is made against, and therefore the version scope of that claim: nothing is claimed under 0.1.0-draft, which defines no evaluator class and under which §3.4.1 forbids such a claim outright.

View Source 
const ExampleKind = "version-pinned-conformance-fixture"

ExampleKind labels the example payloads: the bundled examples are the runtime's digest-locked conformance fixtures surfaced read-only, not authored templates. It appears in-band so a consumer never mistakes one for a template.

View Source 
const GraphCompositeLabel = "" /* 289-byte string literal not displayed */

GraphCompositeLabel labels every graph evaluation this runtime reports. The composite is an envelope of per-node results, not a specification artifact: no JPS version defines a composition, and the one thing the label may say about the evaluator that produced the node dispositions is where its conformance claim is stated.

View Source 
const GraphMatrixLabel = "" /* 309-byte string literal not displayed */

GraphMatrixLabel labels every graph matrix run. Like the pack matrix label it points at the one claim document and says nothing of its own about it, and like the composite label it says what no specification defines.

View Source 
const PackMatrixLabel = "" /* 187-byte string literal not displayed */

PackMatrixLabel labels every project matrix run. A project's matrix is the project's own rows about the project's own packs; it is not the specification's evaluation corpus, and running it reports what those rows did. The evaluator that ran them is the experimental one, whose conformance claim is stated, in full and only, in CONFORMANCE.md; this label points there and says nothing of its own about it.

View Source 
const PackSuggestionLabel = "" /* 193-byte string literal not displayed */

PackSuggestionLabel labels every packs suggest report with what the run produced and what it did not. It is the corpus label's discipline applied to a generator: the one thing a reader must not take from a candidate document is that anything in it has been decided.

View Source 
const ProjectKind = "non-normative-runtime-convention"

ProjectKind labels every payload of the project convention, in band, as what it is: a convention of this runtime and not part of the specification. A consumer that meets one of these payloads without reading ADR-0012 still learns from the payload itself that nothing here is normative, and that no other JPS implementation is obliged to understand a jpack.json.

View Source 
const ReasonExceptionEscalation = "exception-escalation"

ReasonExceptionEscalation is the one reason of §8.3 that is a direct handoff request rather than a trigger-selected one (§8, §8.1). It is named here because the disposition's own validity depends on it, and not only the engine's accounting of what it produced.

Variables

View Source 
var CLIVersion = "0.0.0-dev"

CLIVersion may be replaced at build time with -ldflags once releases are approved.

Functions

func OutcomeValueName added in v0.24.0 

func OutcomeValueName(name string) bool

OutcomeValueName reports whether name is a value name of draft RFC 0016: one lowercase ASCII letter, then ASCII letters and digits. The whole name is held to that, so a name that ends in a line feed is refused. It is written as a loop over the bytes and not as a pattern, because the RFC warns that a pattern's end anchor may admit what the rule refuses, and a loop has no anchor to get wrong. The evaluator's admission gate reads the same function, so the gate and the disposition cannot disagree about a name.

Types

type Artifact 

type Artifact struct {
	SpecVersion  string `json:"specVersion"`
	BundleDigest string `json:"bundleDigest"`
	Provenance   string `json:"provenance"`
}

type AuditChain added in v0.26.0 

type AuditChain struct {
	Status          string               `json:"status"`
	Scope           string               `json:"scope"`
	Lines           int64                `json:"lines"`
	Bytes           int64                `json:"bytes"`
	Trail           string               `json:"trail,omitempty"`
	Head            *AuditCheckpoint     `json:"head,omitempty"`
	Coverage        AuditCoverage        `json:"coverage"`
	Segments        []AuditSegment       `json:"segments"`
	SegmentsTotal   int64                `json:"segmentsTotal"`
	Discontinuities []AuditDiscontinuity `json:"discontinuities"`
	// DiscontinuitiesTotal counts every discontinuity; Discontinuities and
	// Segments list the first hundred of each, as Findings does.
	DiscontinuitiesTotal int64             `json:"discontinuitiesTotal"`
	Held                 *AuditHeld        `json:"held,omitempty"`
	Required             *AuditRequirement `json:"required,omitempty"`
	// Signatures is the sidecar as read, present when a public key was
	// supplied, and RequiredSigned a signed coverage the verification was
	// told to require: every record up to Through covered by a valid
	// signature.
	Signatures     *AuditSignatures  `json:"signatures,omitempty"`
	RequiredSigned *AuditRequirement `json:"requiredSigned,omitempty"`
	// Stamps is the stamps file as read, present when time-stamping roots
	// were supplied, and RequiredStamped a stamped coverage the verification
	// was told to require.
	Stamps           *AuditStamps      `json:"stamps,omitempty"`
	RequiredStamped  *AuditRequirement `json:"requiredStamped,omitempty"`
	Findings         []AuditFinding    `json:"findings"`
	FindingsTotal    int               `json:"findingsTotal"`
	Establishes      []string          `json:"establishes"`
	DoesNotEstablish []string          `json:"doesNotEstablish"`
}

AuditChain is what reading a trail found: its status, the scope of what was checked, its coverage and segments, and every finding, with the statements of what the result establishes and what it does not. Status is "valid" when every check passed and the trail has no discontinuity, "segmented" when every check passed and it has at least one, and "invalid" when any check failed.

type AuditCheckpoint added in v0.26.0 

type AuditCheckpoint struct {
	CheckpointVersion string `json:"checkpointVersion"`
	RecordDigest      string `json:"recordDigest"`
	Sequence          int64  `json:"sequence"`
	Trail             string `json:"trail"`
}

AuditCheckpoint names one record of a chained audit trail by what a holder needs to check it later: the trail's identity, the record's sequence, and the SHA-256 of the record's exact line bytes, without its newline. That digest is the one the next record's previous holds and the one a gateway action receipt's decision.recordDigest names for the same record, and because a chained line carries its own trail and sequence, it commits to both as well as to everything the chain links before it.

The members are declared in code-point order and hold only lowercase-hex strings and an integer under 2^53, so the compact encoding of this value is its own RFC 8785 canonical form: a checkpoint's exact bytes are what a later time stamp (#208) can be taken over.

type AuditCheckpointList added in v0.26.0 

type AuditCheckpointList struct {
	OutputVersion string            `json:"outputVersion"`
	Tool          Tool              `json:"tool"`
	Command       string            `json:"command"`
	Status        string            `json:"status"`
	TrailPath     string            `json:"trailPath"`
	After         int64             `json:"after"`
	Checkpoints   []AuditCheckpoint `json:"checkpoints"`
	More          bool              `json:"more"`
}

AuditCheckpointList is jpack audit checkpoint --since's payload: the checkpoints of the chained records after After, in sequence order, as many as were asked for, and whether more follow. A deliverer that hands each to a holder asks again after the last sequence it received.

type AuditCheckpointReport added in v0.26.0 

type AuditCheckpointReport struct {
	OutputVersion  string          `json:"outputVersion"`
	Tool           Tool            `json:"tool"`
	Command        string          `json:"command"`
	Status         string          `json:"status"`
	TrailPath      string          `json:"trailPath"`
	Checkpoint     AuditCheckpoint `json:"checkpoint"`
	UncoveredLines int64           `json:"uncoveredLines"`
}

AuditCheckpointReport is jpack audit checkpoint's payload: the checkpoint of the trail's last chained line, and how many lines after it it does not cover.

type AuditCoverage added in v0.26.0 

type AuditCoverage struct {
	// LegacyPrefix is the lines before the first chained line, which its
	// previous commits to as one block.
	LegacyPrefix int64 `json:"legacyPrefix"`
	// Chained is the chained lines.
	Chained int64 `json:"chained"`
	// Unchained is the unchained lines after the first chained line that a
	// later chained line commits to, as part of the whole file before it.
	Unchained int64 `json:"unchained"`
	// Uncovered is the lines no chained line commits to: the unchained lines
	// after the last chained line, or every line when none is chained.
	Uncovered int64 `json:"uncovered"`
	// Damaged is the lines a discontinuity names as damaged.
	Damaged int64 `json:"damaged"`
	// Signed is "not-checked" when no public key was supplied, so no
	// signature was checked (ADR-0047 §2b); otherwise "through" the highest
	// sequence whose own record carries a valid signature with no failed
	// check of the chain at or before it, which then covers every line up to
	// it, or "none" when no valid signature covers any.
	Signed AuditCoverageState `json:"signed"`
	// SignedRecords is the chained records with a valid signature of their
	// own, and UnsignedRecords the chained records without one; together
	// they are Chained. Both are zero when no signature was checked.
	SignedRecords   int64 `json:"signedRecords"`
	UnsignedRecords int64 `json:"unsignedRecords"`
	// Checkpointed is "not-supplied" without a held checkpoint, "through" the
	// sequence the held checkpoints cover, and "failed" when they cover none.
	Checkpointed AuditCoverageState `json:"checkpointed"`
	// Witnessed is the chained records a held checkpoint covers, and
	// Unwitnessed the chained records none does: every one after the
	// sequence Checkpointed is through, or every one when it is through none.
	Witnessed   int64 `json:"witnessed"`
	Unwitnessed int64 `json:"unwitnessed"`
	// Stamped is "not-checked" when no time-stamping roots were supplied, so
	// no stamp was checked (ADR-0047 §2a, C2); otherwise "through" the
	// highest sequence a trusted stamp's checkpoint names, with no failed
	// check of the trail at or before it, or "none".
	Stamped AuditCoverageState `json:"stamped"`
}

AuditCoverage says how much of a trail each kind of protection reaches. The line counts partition the trail's complete lines.

type AuditCoverageState added in v0.26.0 

type AuditCoverageState struct {
	Status  string `json:"status"`
	Through int64  `json:"through,omitempty"`
	Detail  string `json:"detail,omitempty"`
}

AuditCoverageState is one protection's reach.

type AuditDiscontinuity added in v0.26.0 

type AuditDiscontinuity struct {
	Line        int64  `json:"line"`
	Reason      string `json:"reason"`
	DamagedLine int64  `json:"damagedLine"`
	Bytes       int64  `json:"bytes"`
	Digest      string `json:"digest"`
}

AuditDiscontinuity is one discontinuity record a repair appended: the line it is on, why, and the damaged line it names, kept in place, with that line's length and digest as the record states them.

type AuditFinding added in v0.26.0 

type AuditFinding struct {
	Name   string `json:"name"`
	Line   int64  `json:"line"`
	Detail string `json:"detail"`
}

AuditFinding is one check a trail failed: a stable name, the line it is about, and what was found, never a record's contents.

type AuditHeld added in v0.26.0 

type AuditHeld struct {
	Supplied int64            `json:"supplied"`
	Matched  int64            `json:"matched"`
	Failed   int64            `json:"failed"`
	Latest   *AuditCheckpoint `json:"latest,omitempty"`
	Status   string           `json:"status"`
}

AuditHeld is what the trail was held to: the checkpoints a holder kept and supplied. Every one must match. Latest is the highest that matched with no failed check up to it, which is how far the coverage reaches; Status is "matched" when every one matched and the coverage reaches the highest supplied, and "failed" otherwise.

type AuditKey added in v0.26.0 

type AuditKey struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	PublicKey     string `json:"publicKey"`
	KeyID         string `json:"keyId"`
}

AuditKey is jpack audit key generate's and jpack audit key public's payload: a signing key's public key and keyId (ADR-0047 §2b), never anything of its private half.

type AuditRepair added in v0.26.0 

type AuditRepair struct {
	OutputVersion string             `json:"outputVersion"`
	Tool          Tool               `json:"tool"`
	Command       string             `json:"command"`
	Status        string             `json:"status"`
	TrailPath     string             `json:"trailPath"`
	Discontinuity AuditDiscontinuity `json:"discontinuity"`
}

AuditRepair is jpack audit repair's payload: the discontinuity record it appended.

type AuditRequirement added in v0.26.0 

type AuditRequirement struct {
	Through int64  `json:"through"`
	Status  string `json:"status"`
}

AuditRequirement is a coverage the verification was told to require: every record up to Through covered by a held checkpoint. Status is "met" or "unmet".

type AuditRotation added in v0.26.0 

type AuditRotation struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	TrailPath     string `json:"trailPath"`
	At            int64  `json:"at"`
	Trail         string `json:"trail"`
	From          string `json:"from"`
	Next          string `json:"next"`
	NextPublicKey string `json:"nextPublicKey"`
}

AuditRotation is jpack audit key rotate's payload: the key-rotation line it appended to the signature sidecar, by the trail line it follows, the trail, and the two keys by keyId, with the next key's public key.

type AuditSegment added in v0.26.0 

type AuditSegment struct {
	FirstLine int64 `json:"firstLine"`
	LastLine  int64 `json:"lastLine"`
}

AuditSegment is a run of lines between discontinuities, by line number.

type AuditSignatures added in v0.26.0 

type AuditSignatures struct {
	Lines        int64  `json:"lines"`
	Unreadable   int64  `json:"unreadable"`
	Rotations    int64  `json:"rotations"`
	KeysSupplied int64  `json:"keysSupplied"`
	Revocations  int64  `json:"revocations"`
	FirstKey     string `json:"firstKey"`
	KeyInForce   string `json:"keyInForce"`
}

AuditSignatures is the signature sidecar as a verification read it (ADR-0047 §2b): its lines, those of no shape it reads (a write that did not complete among them), the rotations followed, how many public keys and revocations were supplied, and the first key and the key in force at the end, by keyId.

type AuditStamp added in v0.26.0 

type AuditStamp struct {
	OutputVersion string          `json:"outputVersion"`
	Tool          Tool            `json:"tool"`
	Command       string          `json:"command"`
	Status        string          `json:"status"`
	TrailPath     string          `json:"trailPath"`
	Checkpoint    AuditCheckpoint `json:"checkpoint"`
	StampedAt     string          `json:"stampedAt,omitempty"`
	ExistedBy     string          `json:"existedBy,omitempty"`
	Policy        string          `json:"policy,omitempty"`
}

AuditStamp is jpack audit stamp's payload: the checkpoint stamped, whether this run stamped it or found it stamped already, and, for a stamp this run kept, the time the authority states, the time the checkpoint existed by (that time plus its stated accuracy) and the policy it stamped under.

type AuditStampLag added in v0.26.0 

type AuditStampLag struct {
	Records      int64   `json:"records"`
	MaxSeconds   float64 `json:"maxSeconds"`
	MaxSequence  int64   `json:"maxSequence,omitempty"`
	MinSeconds   float64 `json:"minSeconds"`
	MinSequence  int64   `json:"minSequence,omitempty"`
	AtAfterStamp bool    `json:"atAfterStamp"`
	AtUnreadable int64   `json:"atUnreadable"`
}

AuditStampLag is the lag between each covered record's at, the operator's word, and the time the first trusted stamp covering it attests the record existed by: over Records records, the longest (and its record's sequence) and the shortest (and its). AtAfterStamp says some record's at is later than that time, which the operator's word cannot be if the authority's is right. AtUnreadable counts covered records whose at could not be read.

type AuditStamps added in v0.26.0 

type AuditStamps struct {
	Lines                int64          `json:"lines"`
	Unreadable           int64          `json:"unreadable"`
	Trusted              int64          `json:"trusted"`
	RevocationChecked    int64          `json:"revocationChecked"`
	RevocationNotChecked int64          `json:"revocationNotChecked"`
	CoveredBy            string         `json:"coveredBy,omitempty"`
	Lag                  *AuditStampLag `json:"lag"`
}

AuditStamps is the stamps file as a verification read it: its lines, those of no shape it reads, the trusted stamps (their token holds under the roots supplied and their checkpoint matches the trail), how many of those had their certificates' revocation status checked against a supplied list and how many did not, the time the stamped coverage's records existed by, and the lag between records' at and the first trusted stamp covering them.

type AuditVerification added in v0.26.0 

type AuditVerification struct {
	OutputVersion         string `json:"outputVersion"`
	Tool                  Tool   `json:"tool"`
	Command               string `json:"command"`
	TrailPath             string `json:"trailPath"`
	SnapshotBetweenWrites bool   `json:"snapshotBetweenWrites"`
	AuditChain
}

AuditVerification is jpack audit verify's payload: the chain as read, which trail was read, and whether the snapshot was taken between writes.

type Case 

type Case struct {
	ID                   string              `json:"id"`
	ExpectedStatus       string              `json:"expectedStatus"`
	ActualStatus         string              `json:"actualStatus"`
	Status               string              `json:"status"`
	ExpectedDiagnostic   *ExpectedDiagnostic `json:"expectedDiagnostic"`
	ActualDiagnostics    []Diagnostic        `json:"actualDiagnostics"`
	DiagnosticsTruncated bool                `json:"diagnosticsTruncated"`
}

type Citation added in v0.21.0 

type Citation struct {
	SessionID string `json:"sessionId"`
	CallIndex int64  `json:"callIndex"`
	Signature string `json:"signature"`
}

Citation names one gateway receipt by session, index and signature -- the shape an action receipt's citations have and a decision record's (ADR-0033) -- as a matrix row declared it. The runtime resolves none.

type ComparedInputs added in v0.24.0 

type ComparedInputs struct {
	Kind                string `json:"kind"`
	Count               int    `json:"count"`
	Same                int    `json:"same"`
	Different           int    `json:"different"`
	UnresolvedUnderBoth int    `json:"unresolvedUnderBoth"`
}

ComparedInputs says what the inputs were and how they compared: kind is "matrix" (admitted under its own rules, its expectations playing no part) or "candidates" (a packs suggest document).

UnresolvedUnderBoth counts the inputs whose disposition was unresolved under both versions, whether or not they differ in reasons or handoff: no outcome was reached for them under either version, so a change in which outcome an input gets could not show on them. It is a part of count, not a third part beside same and different. An input refused on either side, or unresolved under one version only, is not counted.

type ComparedPack added in v0.24.0 

type ComparedPack struct {
	Path        string `json:"path"`
	PackID      string `json:"packId,omitempty"`
	PackVersion string `json:"packVersion,omitempty"`
	Digest      string `json:"digest,omitempty"`
}

ComparedPack names one of the two documents: the path it was read from, its own id and version as an evaluation read them (empty when every evaluation of it was refused before its identity could be read), and the digest of its exact bytes, absent when the read stopped at the byte limit and the whole document was never in hand.

type ComparedRefusal added in v0.24.0 

type ComparedRefusal struct {
	Class string `json:"class,omitempty"`
	Phase string `json:"phase,omitempty"`
	Code  string `json:"code"`
}

ComparedRefusal is a refused evaluation's class, phase and this runtime's code. Two refusals are the same when all three are.

type ComparedSide added in v0.24.0 

type ComparedSide struct {
	Disposition     *Disposition     `json:"disposition,omitempty"`
	HandoffTarget   *HandoffTarget   `json:"handoffTarget,omitempty"`
	EvaluationError *ComparedRefusal `json:"evaluationError,omitempty"`
}

ComparedSide is one pack's result for one input: a disposition, with the handoff target when one was requested, or the §8.4 refusal.

type ConfigSchema added in v0.4.0 

type ConfigSchema struct {
	OutputVersion           string   `json:"outputVersion"`
	Tool                    Tool     `json:"tool"`
	Command                 string   `json:"command"`
	Status                  string   `json:"status"`
	Kind                    string   `json:"kind"`
	ConfigVersion           string   `json:"configVersion"`
	SupportedConfigVersions []string `json:"supportedConfigVersions"`
	SchemaID                string   `json:"schemaId"`
	Bytes                   int      `json:"bytes"`
	SHA256                  string   `json:"sha256"`
	WrittenTo               string   `json:"writtenTo,omitempty"`
}

ConfigSchema describes the exact embedded jpack.json schema bytes, on the same shape spec schema reports for a bundled JPS schema. It names no specification version, because the configuration format is this runtime's and has a version of its own. ConfigVersion is the newest shape the schema describes; SupportedConfigVersions lists every one the runtime reads, so this payload cannot imply that an older shape stopped being read. The list is an added member, so outputVersion is unchanged under VERSIONING.md's machine-output rules.

type Diagnostic 

type Diagnostic struct {
	Code          string `json:"code"`
	CodeStability string `json:"codeStability"`
	Layer         string `json:"layer"`
	Severity      string `json:"severity"`
	InstancePath  string `json:"instancePath"`
	Message       string `json:"message"`
}

func ErrorDiagnostic 

func ErrorDiagnostic(code, layer, instancePath, message string) Diagnostic

type Disposition added in v0.2.0 

type Disposition struct {
	Kind      string         `json:"kind"`
	OutcomeID string         `json:"outcomeId,omitempty"`
	Reasons   []string       `json:"reasons"`
	Handoff   Handoff        `json:"handoff"`
	Value     map[string]any `json:"value,omitempty"`
}

Disposition is the portable disposition of JPS Core §8.3: kind ("outcome", "not-applicable", or "unresolved"), the outcome id exactly when kind is "outcome", the retained reason set as a sorted duplicate-free array (empty exactly when kind is "outcome"), and the handoff object. Under JPS Core 0.2.0-draft it carries these members and no others.

Value is the one member that is not Core's. The specification's RFC 0016 (Draft) proposes it, and the evaluator sets it under that RFC's opt-in and nowhere else (ADR-0039): the values the produced outcome declares, each a string or a Boolean. It is nil for every disposition made without the opt-in, and the canonical form then has no such member, so those bytes are what they were before the member existed. A reader of expected dispositions refuses the member (evaluation.DecodeDisposition), because an expectation is held to §8.3 as published.

It serializes as its own RFC 8785 canonical form, so the disposition member of any JSON payload this runtime writes without --pretty is the byte sequence §8.3 requires two implementations to agree on, with no second serializer to drift from. Under --pretty the member order and both sets are still canonical, but the payload's indentation reaches inside this member too, so those exact bytes are not present: §8.3 requires canonicalization "where a byte comparison is required", and a byte comparison must recanonicalize either side it did not itself produce.

func (Disposition) Canonical added in v0.4.0 

func (d Disposition) Canonical() ([]byte, error)

Canonical returns the disposition's RFC 8785 canonicalization: members ordered by name, both sets serialized as sorted duplicate-free arrays, an absent outcomeId or triggeredBy omitted rather than written as null, and no whitespace. Sorting happens here as well as at the source of the sets, so a caller cannot produce a non-canonical byte sequence by assembling a disposition itself.

It refuses a value that is not a legal §8.3 disposition rather than serializing one, enforcing every invariant that section states about the disposition alone: the three enumerated vocabularies (kind, handoff.state, and the reason set's members), the three iff rules a Go struct cannot express — outcomeId is present iff kind is "outcome", reasons is empty iff kind is "outcome", and triggeredBy is present iff the handoff state is "requested" — the exact reason set of a not-applicable result, triggeredBy being a subset of reasons, and the direct request a retained exception-escalation reason is. The one place canonicalization lives is therefore also the place that holds a caller to them. The engine builds no illegal value; an exported type can be handed one.

The one §8.3 requirement it cannot enforce is the one that is not about the disposition alone: that outcomeId "MUST name a declared outcome of the pack evaluated" is a fact about a pack this type never sees, so it stays where the pack is — the engine names only ids it read from the pack, and semantic validation has already refused a pack whose rules name an undeclared outcome. Whether the handoff state agrees with the pack's escalation object (§8.1) is pack-dependent in the same way and is likewise the engine's.

func (Disposition) MarshalJSON added in v0.4.0 

func (d Disposition) MarshalJSON() ([]byte, error)

MarshalJSON writes the canonical form of §8.3.

type DraftPrototype added in v0.3.0 

type DraftPrototype struct {
	RFC                       string   `json:"rfc"`
	Status                    string   `json:"status"`
	Operators                 []string `json:"operators"`
	Outcomes                  []string `json:"outcomes,omitempty"`
	PackValidUnderSpecVersion bool     `json:"packValidUnderSpecVersion"`
	Note                      string   `json:"note"`
}

DraftPrototype marks an evaluation that ran under a draft-RFC grammar extension rather than a published JPS version. It is present exactly when the caller opted into such a grammar, and it says in band what the operators are and that the pack carrying them is not valid under the specification the rest of the payload names. A consumer that ignores it is reading a disposition produced by operators no JPS version defines.

One evaluation runs under at most one draft RFC, so RFC names one (ADR-0039). Operators lists the draft condition operators the pack uses, which only RFC 0008 adds; under any other draft it is the empty array and not absent, because the member was always present and a consumer may read it without asking first. Outcomes lists the ids of the outcomes that carry a value declaration of RFC 0016, sorted. It is absent under RFC 0008, so the marker of that draft is byte for byte what it was before this member existed, and absent under RFC 0016 for a pack that declares no value.

type Evaluation added in v0.2.0 

type Evaluation struct {
	OutputVersion             string          `json:"outputVersion"`
	Tool                      Tool            `json:"tool"`
	Command                   string          `json:"command"`
	Status                    string          `json:"status"`
	Experimental              bool            `json:"experimental"`
	Rehearsal                 bool            `json:"rehearsal,omitempty"`
	Reviewed                  *bool           `json:"reviewed,omitempty"`
	ReviewedSet               *ReviewedSet    `json:"reviewedSet,omitempty"`
	ConformanceClaimReference string          `json:"conformanceClaimReference"`
	SpecVersion               string          `json:"specVersion"`
	EvaluatorSpecVersion      string          `json:"evaluatorSpecVersion"`
	PackID                    string          `json:"packId"`
	PackVersion               string          `json:"packVersion"`
	DraftPrototype            *DraftPrototype `json:"draftPrototype,omitempty"`
	Disposition               Disposition     `json:"disposition"`
	HandoffTarget             *HandoffTarget  `json:"handoffTarget,omitempty"`
	UnmetEvidence             []UnmetEvidence `json:"unmetEvidence,omitempty"`
	Trace                     []TraceEntry    `json:"trace"`
	Artifact                  *Artifact       `json:"artifact,omitempty"`
}

Evaluation is the experimental-evaluation envelope. Experimental is always true so no consumer can read the payload as a standard: this surface may change or be removed without compatibility promise (ADR-0007). ConformanceClaimReference is always set and always the same locator; it makes no claim, and the claim it locates is CONFORMANCE.md's alone. SpecVersion is the version the evaluated pack declares; EvaluatorSpecVersion is the version of the evaluator contract applied to it (§8.2–§8.4). Both are always present, and this evaluator requires them to agree: §11 makes the declared value exact, so a pack declaring another version is refused rather than evaluated.

Rehearsal is present exactly when the caller declared the run a rehearsal (ADR-0028): the evaluation ran identically, no audit record was appended and no reviewed set was consulted, and the payload states in band that this was not a decision — a consumer that reads the member cannot mistake a rehearsal for one. It is never inferred; absence means the caller made no such declaration, not that one was recorded.

Reviewed says which law the decision was judged under, as the audit record says it (ADR-0019, ADR-0044). It is present exactly when the project declares a reviewed-set lock and the run was not a declared rehearsal: true when every document the run applied was named as declared law and matched the lock, with ReviewedSet naming the lock's revision, and false when any was a draft -- a pack named by path or passed as text, or a graph document the configuration does not declare. It is absent, not false, for a project with no lock and for a rehearsal, which consults none: neither was judged against a reviewed set.

PackID and PackVersion echo the evaluated pack's own id and version members. They are additive members and not a new fact: they are read off the document that was evaluated, so a payload cannot name a pack the evaluation did not read. That is what makes them safe to echo — a project configuration's pinned version, a filename, and this echo are all validated references to the one statement of identity the pack document carries, never independent truths beside it (ADR-0012). Adding them does not move OutputVersion, on two VERSIONING.md rules read together: its compatibility-dimensions clause makes a break in machine-output compatibility the thing that increments the protocol version, and its MINOR bullet classes an added output field as a backward-compatible change. A consumer that never read these members reads the same payload it read before, so nothing broke.

type EvaluationCorpus added in v0.4.0 

type EvaluationCorpus struct {
	OutputVersion             string                 `json:"outputVersion"`
	Tool                      Tool                   `json:"tool"`
	Command                   string                 `json:"command"`
	Status                    string                 `json:"status"`
	Experimental              bool                   `json:"experimental"`
	ConformanceClaimReference string                 `json:"conformanceClaimReference"`
	Label                     string                 `json:"label"`
	SpecVersion               string                 `json:"specVersion"`
	SuiteVersion              string                 `json:"suiteVersion"`
	CorpusStatus              string                 `json:"corpusStatus"`
	CorpusLabel               string                 `json:"corpusLabel"`
	Provenance                string                 `json:"provenance"`
	Summary                   SuiteSummary           `json:"summary"`
	Cases                     []EvaluationCorpusCase `json:"cases"`
}

EvaluationCorpus is one run of the evaluation corpus bundled for an exact specification version. Like every experimental-evaluation payload it carries Experimental and ConformanceClaimReference, and it additionally carries Label so no reader can take a passing run for the claim of §3.4.1.

type EvaluationCorpusCase added in v0.4.0 

type EvaluationCorpusCase struct {
	ID                    string `json:"id"`
	Origin                string `json:"origin"`
	SpecSection           string `json:"specSection"`
	PackID                string `json:"packId,omitempty"`
	PackVersion           string `json:"packVersion,omitempty"`
	Status                string `json:"status"`
	Expected              string `json:"expected"`
	Actual                string `json:"actual"`
	ExpectedErrorClass    string `json:"expectedErrorClass,omitempty"`
	ActualErrorClass      string `json:"actualErrorClass,omitempty"`
	ExpectedErrorPhase    string `json:"expectedErrorPhase,omitempty"`
	ActualErrorPhase      string `json:"actualErrorPhase,omitempty"`
	ExpectedHandoffTarget string `json:"expectedHandoffTarget,omitempty"`
	ActualHandoffTarget   string `json:"actualHandoffTarget,omitempty"`
	// Cites is the row's own citations, when a project row declares them
	// (ADR-0034): the receipts the row's facts were transcribed under, in the
	// gateway's shape, carried as the values the row declared -- session,
	// index and signature, held to their grammar when the matrix loaded --
	// and verified by nothing here. Omitted when the row cites nothing.
	Cites  []Citation `json:"cites,omitempty"`
	Detail string     `json:"detail,omitempty"`
}

EvaluationCorpusCase is one evaluation-corpus row's result. Expected and actual are the RFC 8785 canonical dispositions compared byte for byte — both produced by the same canonicalizer, so the comparison is disposition equality as §8.3 defines it and not raw equality of what the manifest stores — or the §8.4 class and phase for a row that expects an error instead of a disposition.

PackID and PackVersion echo the identity members of the pack this row ran against, exactly as an evaluation payload does, and are absent for a row that produced no disposition — whether the refusal came before the pack was admitted or after, as a reached §10 limit does. The echo is read off the evaluation that produced it, and inventing one from the row's carrier would be the independent truth this echo is deliberately not.

ExpectedHandoffTarget and ActualHandoffTarget are the second comparison, and they appear **together**, exactly when the row asked for one (ADR-0025). Each carries one of three values: a target's rendering under the budget above, the literal null for no target, or HandoffTargetUnavailable. So the pair says which of the two sides names a destination as well as which destination it names, and it never quietly loses one half.

"unavailable" is the honest third state and the reason the pair is a triple rather than a pair of renderings: it says this report cannot state a target, where null says an evaluation reported none. Its causes are enumerated at HandoffTargetUnavailable — a refused evaluation, no rendering computed for the pack, or a supplied rendering minted from different pack bytes — and the first is told from the rest by ActualErrorClass being set. None of them moves a verdict: the comparison reads the decoded targets, so a degraded report is a report that says less, never a row that decides differently. A row that declares no expectedHandoffTarget carries neither member, and its result is byte for byte what it was before that member existed.

type EvaluationError added in v0.4.0 

type EvaluationError struct {
	Class                string `json:"class"`
	Phase                string `json:"phase"`
	EvaluatorSpecVersion string `json:"evaluatorSpecVersion"`
}

EvaluationError names the §8.4 class of an evaluation error and the phase it was reached in. It is the coarse, portable identity of the failure; the diagnostic beside it keeps this runtime's finer JPS-* code, which is the detail and not the class. EvaluatorSpecVersion names the Core version whose §8.4 contract assigned the class, which is a fact about this evaluator and not about the pack that was refused.

type Example added in v0.1.0 

type Example struct {
	OutputVersion        string `json:"outputVersion"`
	Tool                 Tool   `json:"tool"`
	Command              string `json:"command"`
	Status               string `json:"status"`
	SpecVersion          string `json:"specVersion"`
	EvaluatorSpecVersion string `json:"evaluatorSpecVersion"`
	Name                 string `json:"name"`
	Focus                string `json:"focus"`
	SpecSection          string `json:"specSection"`
	Bytes                int    `json:"bytes"`
	SHA256               string `json:"sha256"`
	Provenance           string `json:"provenance"`
	Kind                 string `json:"kind"`
	WrittenTo            string `json:"writtenTo,omitempty"`
}

type ExampleSummary added in v0.1.0 

type ExampleSummary struct {
	Name        string `json:"name"`
	Focus       string `json:"focus"`
	SpecSection string `json:"specSection"`
}

type Examples added in v0.1.0 

type Examples struct {
	OutputVersion        string           `json:"outputVersion"`
	Tool                 Tool             `json:"tool"`
	Command              string           `json:"command"`
	Status               string           `json:"status"`
	SpecVersion          string           `json:"specVersion"`
	EvaluatorSpecVersion string           `json:"evaluatorSpecVersion"`
	Provenance           string           `json:"provenance"`
	Kind                 string           `json:"kind"`
	Examples             []ExampleSummary `json:"examples"`
}

Examples lists one bundled version's valid examples. SpecVersion is the version the listed documents declare; EvaluatorSpecVersion is the only version the evaluator admits (§11). The two differ for the default set, and a reader needs both to know whether a document made from an example can be evaluated without re-declaring it.

type ExpectationFinding added in v0.22.0 

type ExpectationFinding struct {
	Index     int    `json:"index"`
	Status    string `json:"status"`
	Canonical string `json:"canonical,omitempty"`
	Code      string `json:"code,omitempty"`
	Message   string `json:"message,omitempty"`
}

ExpectationFinding is one proposed expectation's admission finding (ADR-0035). A valid finding carries the canonical §8.3 text the runtime would compare against; an invalid one carries the code and the message that says which rule refused it. Neither carries the other's members, so a reader can tell the two apart without consulting the aggregate.

type ExpectationReport added in v0.22.0 

type ExpectationReport struct {
	OutputVersion string               `json:"outputVersion"`
	Tool          Tool                 `json:"tool"`
	Command       string               `json:"command"`
	Status        string               `json:"status"`
	Experimental  bool                 `json:"experimental"`
	SpecVersion   string               `json:"specVersion"`
	Results       []ExpectationFinding `json:"results"`
}

ExpectationReport is one admission check of proposed exact expectations (ADR-0035): one finding per input, in the order they were given, and an aggregate that is valid only when every finding is. It carries the same versioned envelope as every other payload this runtime writes, so a later change that breaks machine-output compatibility has an OutputVersion to move (VERSIONING.md), and it carries Experimental like every other payload on this runtime's experimental surface.

Status is about admission, and reachability enters it only where reachability is a fact about the disposition alone: a valid finding says the text is a legal §8.3 disposition that §8's step order and §5's identifier grammar do not put beyond every conforming pack (ADR-0037). It does not say that any particular pack can produce it — pack-dependent reachability, an outcome this pack declares or a handoff it configures, is still not checked here.

func NewExpectationReport added in v0.22.0 

func NewExpectationReport(command, specVersion string, findings []ExpectationFinding) ExpectationReport

type ExpectedDiagnostic 

type ExpectedDiagnostic struct {
	Code string `json:"code"`
	Path string `json:"path"`
}

type Extensions 

type Extensions struct {
	Required    []string `json:"required"`
	Supported   []string `json:"supported"`
	Unsupported []string `json:"unsupported"`
}

type GraphDocument added in v0.19.0 

type GraphDocument struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	Experimental  bool   `json:"experimental"`
	Kind          string `json:"kind"`
	ConfigPath    string `json:"configPath"`
	ID            string `json:"id"`
	GraphID       string `json:"graphId"`
	GraphVersion  string `json:"graphVersion"`
	FormatVersion string `json:"formatVersion"`
	ResultNode    string `json:"resultNode,omitempty"`
	Path          string `json:"path"`
	RowsPath      string `json:"rowsPath,omitempty"`
	Description   string `json:"description,omitempty"`
	Bytes         int    `json:"bytes"`
	SHA256        string `json:"sha256"`
	Detail        string `json:"detail,omitempty"`
}

GraphDocument is the metadata beside one graph document served by configured id; the bytes travel separately, exactly as a served pack's do. Status is "valid" when the served bytes decoded and the identity members were read off them, and "undecodable" when they did not, in which case Detail says why and those members are empty rather than guessed. Neither value is a verdict on the document against the graph schema: serving a graph does not validate it, and experimental graph validate is what reports that. FormatVersion here is the version the document itself declares, read off the served bytes the way a PackDocument's specVersion is — not the format version a walk applied, which is what the member means on an evaluation payload.

type GraphEvaluation added in v0.8.0 

type GraphEvaluation struct {
	OutputVersion             string                `json:"outputVersion"`
	Tool                      Tool                  `json:"tool"`
	Command                   string                `json:"command"`
	Status                    string                `json:"status"`
	Experimental              bool                  `json:"experimental"`
	Rehearsal                 bool                  `json:"rehearsal,omitempty"`
	Reviewed                  *bool                 `json:"reviewed,omitempty"`
	ReviewedSet               *ReviewedSet          `json:"reviewedSet,omitempty"`
	ConformanceClaimReference string                `json:"conformanceClaimReference"`
	Label                     string                `json:"label"`
	Kind                      string                `json:"kind"`
	EvaluatorSpecVersion      string                `json:"evaluatorSpecVersion"`
	FormatVersion             string                `json:"formatVersion"`
	ConfigPath                string                `json:"configPath"`
	GraphPath                 string                `json:"graphPath"`
	GraphID                   string                `json:"graphId"`
	GraphVersion              string                `json:"graphVersion"`
	ResultNode                string                `json:"resultNode"`
	Disposition               Disposition           `json:"disposition"`
	HandoffTarget             *HandoffTarget        `json:"handoffTarget,omitempty"`
	Handoffs                  []GraphHandoff        `json:"handoffs"`
	Nodes                     []GraphNodeEvaluation `json:"nodes"`
	Artifact                  *Artifact             `json:"artifact,omitempty"`
}

GraphEvaluation is the composite envelope of one graph run. Disposition and HandoffTarget echo the declared result node's own members, exactly as they appear in Nodes — a validated echo on the ADR-0012 pattern, never a second truth — and Handoffs aggregates every requested handoff so an escalation upstream of the result is as visible as the result itself. Like every payload the experimental evaluator produces, it asserts nothing about the wisdom of acting on any disposition it carries. Reviewed and ReviewedSet are the run's, as Evaluation's are (ADR-0044): one invocation consults the lock once, for the configuration, the graph document and every node's pack.

type GraphEvidenceFeed added in v0.8.0 

type GraphEvidenceFeed struct {
	From        string `json:"from"`
	Requirement string `json:"requirement"`
	State       string `json:"state"`
}

GraphEvidenceFeed records one outcome-as-evidence edge as it applied to one node's evidence-availability document: the upstream node, the downstream requirement id, and the tri-state value the edge contributed. An upstream outcome contributes "present"; anything else contributes the edge's declared onUnresolved value, "unknown" unless the edge says "absent".

type GraphFactFeed added in v0.8.0 

type GraphFactFeed struct {
	From     string `json:"from"`
	Pointer  string `json:"pointer"`
	Injected bool   `json:"injected"`
	Value    string `json:"value,omitempty"`
}

GraphFactFeed records one outcome-as-fact edge as it applied to one node's facts document. Injected says whether a value was actually written: an upstream node that produced no outcome — an unresolved or not-applicable disposition — injects nothing, and the pointer is simply absent from the downstream facts document, which is how §7 already treats a fact nobody established. Value carries the injected outcome id exactly when Injected is true.

type GraphHandoff added in v0.8.0 

type GraphHandoff struct {
	Node        string         `json:"node"`
	TriggeredBy []string       `json:"triggeredBy"`
	Target      *HandoffTarget `json:"target,omitempty"`
}

GraphHandoff is one node's requested handoff, aggregated so a reader of the composite cannot miss an escalation a non-result node requested. It is an aggregation of what the node dispositions already say, never a new fact.

type GraphInventory added in v0.19.0 

type GraphInventory struct {
	OutputVersion string         `json:"outputVersion"`
	Tool          Tool           `json:"tool"`
	Command       string         `json:"command"`
	Status        string         `json:"status"`
	Experimental  bool           `json:"experimental"`
	Kind          string         `json:"kind"`
	ConfigPath    string         `json:"configPath"`
	ConfigVersion string         `json:"configVersion,omitempty"`
	Note          string         `json:"note,omitempty"`
	Graphs        []GraphSummary `json:"graphs"`
}

GraphInventory is the resolved graph inventory of one project, the graph sibling of PackInventory and deliberately not a member of it: the pack inventory is a stable command's payload, and this surface is experimental, so folding one into the other would put a removable member inside a payload that must not shrink (the separation ADR-0015 drew and ADR-0017 kept). Status is "none" when no configuration was found, which is an answer and not a failure, and Note says where the runtime looked.

type GraphNodeEvaluation added in v0.8.0 

type GraphNodeEvaluation struct {
	Node          string              `json:"node"`
	Pack          string              `json:"pack"`
	PackID        string              `json:"packId"`
	PackVersion   string              `json:"packVersion"`
	SpecVersion   string              `json:"specVersion"`
	FactFeeds     []GraphFactFeed     `json:"factFeeds"`
	EvidenceFeeds []GraphEvidenceFeed `json:"evidenceFeeds"`
	Disposition   Disposition         `json:"disposition"`
	HandoffTarget *HandoffTarget      `json:"handoffTarget,omitempty"`
	UnmetEvidence []UnmetEvidence     `json:"unmetEvidence,omitempty"`
	Trace         []TraceEntry        `json:"trace"`
}

GraphNodeEvaluation is one node's evaluation inside a graph run: the graph's node id, the project decision id it names, the evaluated pack's own identity echoes, the feeds that arrived over in-edges, and the same disposition, handoff target, and trace a standalone evaluation reports. Nothing is summarized away: the composite is these results side by side, not a replacement for them.

type GraphPlan added in v0.8.0 

type GraphPlan struct {
	OutputVersion string          `json:"outputVersion"`
	Tool          Tool            `json:"tool"`
	Command       string          `json:"command"`
	Status        string          `json:"status"`
	Kind          string          `json:"kind"`
	FormatVersion string          `json:"formatVersion"`
	ConfigPath    string          `json:"configPath"`
	GraphPath     string          `json:"graphPath"`
	GraphID       string          `json:"graphId"`
	GraphVersion  string          `json:"graphVersion"`
	ResultNode    string          `json:"resultNode"`
	Steps         []GraphPlanStep `json:"steps"`
}

GraphPlan is the evaluation plan of one graph, stated without evaluating anything: the deterministic node order, and per node the feeds it would receive. It reads pack documents only to echo their identity; no condition is interpreted, no disposition is produced, and the plan authorizes nothing.

type GraphPlanFeed added in v0.8.0 

type GraphPlanFeed struct {
	From         string `json:"from"`
	Fact         string `json:"fact,omitempty"`
	Evidence     string `json:"evidence,omitempty"`
	OnUnresolved string `json:"onUnresolved,omitempty"`
}

GraphPlanFeed is one edge as the plan states it, before any evaluation: which upstream node feeds which fact pointer or evidence requirement, and — for an evidence feed — the tri-state an unresolved upstream would contribute. OnUnresolved is stated explicitly, default included, because a plan whose reader must know the default has not explained anything.

type GraphPlanStep added in v0.8.0 

type GraphPlanStep struct {
	Order       int             `json:"order"`
	Node        string          `json:"node"`
	Pack        string          `json:"pack"`
	Path        string          `json:"path"`
	PackID      string          `json:"packId"`
	PackVersion string          `json:"packVersion"`
	Detail      string          `json:"detail,omitempty"`
	Feeds       []GraphPlanFeed `json:"feeds"`
}

GraphPlanStep is one node in evaluation order: its position, the project decision id it names, the declared path, the pack document's own identity when it could be read — empty with Detail set when it could not, never guessed — and every feed that will arrive before it runs.

type GraphSchema added in v0.8.0 

type GraphSchema struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	Kind          string `json:"kind"`
	FormatVersion string `json:"formatVersion"`
	SchemaID      string `json:"schemaId"`
	Bytes         int    `json:"bytes"`
	SHA256        string `json:"sha256"`
	WrittenTo     string `json:"writtenTo,omitempty"`
}

GraphSchema describes the exact embedded graph schema bytes, on the shape packs schema reports for the configuration schema. It names no specification version, because the graph format is this runtime's and has a formatVersion of its own — which is what FormatVersion carries, never the version member of any graph document: a payload in which "graphVersion" could mean either fact would be a payload nobody could read safely, so the format version is "formatVersion" in every graph payload and the document identity echo is graphId with graphVersion, exactly parallel to packId with packVersion.

type GraphSuite added in v0.10.0 

type GraphSuite struct {
	OutputVersion             string            `json:"outputVersion"`
	Tool                      Tool              `json:"tool"`
	Command                   string            `json:"command"`
	Status                    string            `json:"status"`
	Experimental              bool              `json:"experimental"`
	ConformanceClaimReference string            `json:"conformanceClaimReference"`
	Label                     string            `json:"label"`
	Kind                      string            `json:"kind"`
	FormatVersion             string            `json:"formatVersion"`
	EvaluatorSpecVersion      string            `json:"evaluatorSpecVersion"`
	ConfigPath                string            `json:"configPath"`
	ConfigVersion             string            `json:"configVersion"`
	Summary                   SuiteSummary      `json:"summary"`
	Graphs                    []GraphSuiteEntry `json:"graphs"`
}

GraphSuite is the project graph-matrix walk: every configured graph's rows, or the one graph --id selected, each entry exactly one graph test. It carries the same labels the single-graph payload carries, because the same two surfaces made every entry. A walk over a configuration that declares no graphs reports status "skipped" over zero entries — an answer, not a clean pass: nothing was tested, and the exit code says so.

type GraphSuiteEntry added in v0.10.0 

type GraphSuiteEntry struct {
	ID           string `json:"id"`
	Path         string `json:"path"`
	RowsPath     string `json:"rowsPath,omitempty"`
	GraphID      string `json:"graphId,omitempty"`
	GraphVersion string `json:"graphVersion,omitempty"`
	// GraphSHA256 is the bare-hex digest of the exact bytes this entry's run
	// loaded (ADR-0030), read off the one load: a consumer holding the served
	// document from another call binds these rows to that revision by equality
	// rather than by hope. Absent exactly when the document did not load,
	// beside the detail that says why.
	GraphSHA256 string         `json:"graphSha256,omitempty"`
	Status      string         `json:"status"`
	Summary     SuiteSummary   `json:"summary"`
	Rows        []GraphTestRow `json:"rows,omitempty"`
	Coverage    []MatrixProbe  `json:"coverage,omitempty"`
	Detail      string         `json:"detail,omitempty"`
}

GraphSuiteEntry is one configured graph's matrix run inside the project walk (ADR-0017), on PackTestEntry's shape: the project's graph id beside the graph document's own identity echoes, the run's rows and coverage exactly as the single-graph payload carries them, and Detail set when the graph did not run — an unreadable or invalid document, a missing rows declaration — in which case the identity echoes are empty rather than guessed and Rows and Coverage are absent.

type GraphSummary added in v0.19.0 

type GraphSummary struct {
	ID            string `json:"id"`
	GraphID       string `json:"graphId"`
	GraphVersion  string `json:"graphVersion"`
	FormatVersion string `json:"formatVersion"`
	ResultNode    string `json:"resultNode,omitempty"`
	Path          string `json:"path"`
	RowsPath      string `json:"rowsPath,omitempty"`
	RowsDeclared  bool   `json:"rowsDeclared"`
	Description   string `json:"description,omitempty"`
	// NodeCount and EdgeCount exist exactly when identity decoding succeeded
	// and the member has its declared shape — nodes a JSON object, edges a
	// JSON array — and are absent, not zero, otherwise, so a malformed
	// document can never look like an honest empty one. The names avoid nodes
	// and rows, which every walk payload uses for arrays.
	NodeCount *int   `json:"nodeCount,omitempty"`
	EdgeCount *int   `json:"edgeCount,omitempty"`
	Detail    string `json:"detail,omitempty"`
}

GraphSummary is one configured graph's inventory row: the project's configured id beside the document's own identity, two different names reported as two members exactly as a PackSummary does. Detail is present when the document could not be read or decoded, in which case the identity members are empty rather than guessed — listing is not validating, and experimental graph validate is where a broken graph is an error. ResultNode echoes the document's declared result member, the one node whose disposition is the composite headline.

type GraphTest added in v0.9.0 

type GraphTest struct {
	OutputVersion             string `json:"outputVersion"`
	Tool                      Tool   `json:"tool"`
	Command                   string `json:"command"`
	Status                    string `json:"status"`
	Experimental              bool   `json:"experimental"`
	ConformanceClaimReference string `json:"conformanceClaimReference"`
	Label                     string `json:"label"`
	Kind                      string `json:"kind"`
	FormatVersion             string `json:"formatVersion"`
	EvaluatorSpecVersion      string `json:"evaluatorSpecVersion"`
	ConfigPath                string `json:"configPath"`
	GraphPath                 string `json:"graphPath"`
	RowsPath                  string `json:"rowsPath"`
	GraphID                   string `json:"graphId"`
	GraphVersion              string `json:"graphVersion"`
	// GraphSHA256 binds this run to the exact document bytes it loaded
	// (ADR-0030), bare hex per the payload convention.
	GraphSHA256 string         `json:"graphSha256"`
	Summary     SuiteSummary   `json:"summary"`
	Rows        []GraphTestRow `json:"rows"`
	Coverage    []MatrixProbe  `json:"coverage,omitempty"`
}

GraphTest is one graph matrix run. It carries Experimental and ConformanceClaimReference like every payload the evaluator produces, and the graph labels beside them, because both surfaces made it: the rows ran through the experimental composition, and each node's disposition through the experimental evaluator.

Coverage reuses MatrixProbe unchanged, under a graph-owned probe grammar (MatrixProbe itself stays surface-agnostic): "node:<nodeId>:<packProbe>" is one node's pack-level probe — witnessed by a row's expectedNodes entry for that node, and for the declared result node also by the row's headline expectation, which is that node's disposition echoed — and "edge:<index>:resolved" / "edge:<index>:unresolved" are one edge's two branches, witnessed by the upstream node's expected disposition kind. Node ids are lowercase-kebab per the graph schema, so the colon namespacing is unambiguous. The member is present when some node's pack derived a probe, and absent when no node's pack could be read or the evaluator admitted none — never a statement that the rows did not load, which is a refusal carrying no payload at all. Mismatched rows still witness, because coverage reads expectations, which exist whether or not they held. It moves no status and no exit code (ADR-0014's invariant, inherited by ADR-0016), and it is additive, so outputVersion is unchanged by the VERSIONING.md machine-output rules.

type GraphTestNode added in v0.9.0 

type GraphTestNode struct {
	Node                  string        `json:"node"`
	Status                string        `json:"status"`
	Expected              string        `json:"expected"`
	Actual                string        `json:"actual"`
	ExpectedHandoffTarget string        `json:"expectedHandoffTarget,omitempty"`
	ActualHandoffTarget   string        `json:"actualHandoffTarget,omitempty"`
	Trace                 *[]TraceEntry `json:"trace,omitempty"`
}

GraphTestNode is one named node's comparison inside one graph matrix row: the RFC 8785 canonical §8.3 dispositions, expected and actual, compared byte for byte by the same canonicalizer every other comparison uses. Only the nodes a row names are compared; an unnamed node is unchecked, and saying so is the row author's choice made visible.

Trace is the node evaluation's own trace under ADR-0027's pinned contract, carried only when the run was asked (ADR-0031). A pointer so presence tracks the request exactly: asked and evaluated is present, [] at minimum, mirroring the contract's never-omitted rule; not asked is absent. A node the graph does not declare was never evaluated and has no trace even when asked. The comparison list is lexicographic by node name; each trace stays walk-ordered internally — two different orders, deliberately.

ExpectedHandoffTarget and ActualHandoffTarget appear together, exactly when the row's well-formed assertion named a node this run evaluated (ADR-0032): each is a rendering under the pack matrix's budget or the literal null, and the comparison that decides reads the decoded values, never these renderings. A row-defect mismatch — an undecodable expectation, a node the graph does not declare — reports the defect in the row's detail and no pair. The pack triple's third state, "unavailable", is unreachable here — a target rides only beside a disposition expectation, and a comparison exists only for a node this run evaluated — so these members never carry it.

type GraphTestRow added in v0.9.0 

type GraphTestRow struct {
	ID                    string          `json:"id"`
	Status                string          `json:"status"`
	Expected              string          `json:"expected"`
	Actual                string          `json:"actual"`
	ExpectedErrorClass    string          `json:"expectedErrorClass,omitempty"`
	ActualErrorClass      string          `json:"actualErrorClass,omitempty"`
	ExpectedErrorPhase    string          `json:"expectedErrorPhase,omitempty"`
	ActualErrorPhase      string          `json:"actualErrorPhase,omitempty"`
	ExpectedHandoffTarget string          `json:"expectedHandoffTarget,omitempty"`
	ActualHandoffTarget   string          `json:"actualHandoffTarget,omitempty"`
	Nodes                 []GraphTestNode `json:"nodes,omitempty"`
	Detail                string          `json:"detail,omitempty"`
}

GraphTestRow is one graph matrix row's result: the composite headline compared canonically, the §8.4 class and phase for a row that expects a refusal instead, and the per-node comparisons the row asked for.

ExpectedHandoffTarget and ActualHandoffTarget appear together, exactly when the row's well-formed assertion rode a run this walk performed (ADR-0032) — the composite's reported target is the result node's own, the value a target-only pack edit reaches while every disposition byte stays identical; a row-defect mismatch reports the defect in the detail and no pair. The actual side is the rendering or the literal null, or "unavailable" exactly where a run was refused under an expected composite: a §8.4-classed refusal sets ActualErrorClass beside it, and a graph-layer refusal that carries no class is told by the detail naming the refusal.

type GraphValidation added in v0.8.0 

type GraphValidation struct {
	OutputVersion string       `json:"outputVersion"`
	Tool          Tool         `json:"tool"`
	Command       string       `json:"command"`
	Status        string       `json:"status"`
	Kind          string       `json:"kind"`
	FormatVersion string       `json:"formatVersion"`
	ConfigPath    string       `json:"configPath"`
	GraphPath     string       `json:"graphPath"`
	GraphID       string       `json:"graphId,omitempty"`
	GraphVersion  string       `json:"graphVersion,omitempty"`
	GraphSHA256   string       `json:"graphSha256"`
	Diagnostics   []Diagnostic `json:"diagnostics"`
}

GraphValidation is one graph document's validation report: the document against the embedded schema and the graph's own semantic rules, and its references against the project — every node resolves through the configuration, every evidence feed names a requirement its target pack declares. Diagnostics carry every finding rather than the first one. GraphSHA256 is the bare-hex digest of the exact bytes this validation decoded (ADR-0030); the payload exists only after the document loaded, so unlike the walk entries the member is required.

type GraphValidationEntry added in v0.10.0 

type GraphValidationEntry struct {
	ID           string `json:"id"`
	Path         string `json:"path"`
	RowsPath     string `json:"rowsPath,omitempty"`
	GraphID      string `json:"graphId,omitempty"`
	GraphVersion string `json:"graphVersion,omitempty"`
	// GraphSHA256 is the bare-hex digest of the exact bytes this walk loaded
	// (ADR-0030): the member that lets a consumer holding the document from
	// another call know these results are about the same revision, read off
	// the one load rather than a second one. Absent exactly when the document
	// did not load, beside the diagnostics that say why.
	GraphSHA256 string       `json:"graphSha256,omitempty"`
	Status      string       `json:"status"`
	Diagnostics []Diagnostic `json:"diagnostics"`
}

GraphValidationEntry is one configured graph's validation inside the project walk: the document against the embedded schema, the graph's own rules, and its references against the project — the same checks the single-graph verb applies — plus the declared rows document's containment when one is declared. Diagnostics carry every finding rather than the first one.

type GraphValidationSuite added in v0.10.0 

type GraphValidationSuite struct {
	OutputVersion string                 `json:"outputVersion"`
	Tool          Tool                   `json:"tool"`
	Command       string                 `json:"command"`
	Status        string                 `json:"status"`
	Kind          string                 `json:"kind"`
	FormatVersion string                 `json:"formatVersion"`
	ConfigPath    string                 `json:"configPath"`
	ConfigVersion string                 `json:"configVersion"`
	Summary       PackCounts             `json:"summary"`
	Graphs        []GraphValidationEntry `json:"graphs"`
}

GraphValidationSuite is the project graph-validation walk, on PackValidation's shape: every configured graph held to the same checks, and a summary a CI gate can read at a glance. Like every graph payload it is a non-normative runtime convention, and says so in Kind.

type Handoff added in v0.2.0 

type Handoff struct {
	State       string   `json:"state"`
	TriggeredBy []string `json:"triggeredBy,omitempty"`
}

Handoff is the disposition's handoff object (§8.3): the state, and — exactly when the state is "requested" — the non-empty subset of the retained reasons that triggered the request. A direct exception escalation on a pack with no escalation object is a requested handoff with no Core-defined destination.

type HandoffTarget added in v0.2.0 

type HandoffTarget struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

HandoffTarget echoes the pack's declared escalation target when a handoff is requested. It is reported beside the disposition and never inside it: §8.3 keeps the configured target out of the disposition object, so a disposition can never disagree with the pack it came from.

func (*HandoffTarget) Canonical added in v0.17.0 

func (h *HandoffTarget) Canonical() ([]byte, error)

Canonical renders one escalation target as the value a row asserts it with: the RFC 8785 form of the {kind, name} object, and the JSON literal null for no target at all. The nil receiver is the "no target" case and is answered rather than refused, because a target's absence is a statement about an evaluation exactly as its presence is (ADR-0025).

It is not a disposition and never becomes one: §8.3 keeps the configured target outside the disposition object, so this is a second value reported beside that one. Both sides of the report are produced here, so a row's expectation and an evaluation's report are rendered by one writer and never by two — but what those two sides are *compared* by is the decoded values, not this rendering (see the budget above).

Like Disposition.Canonical it refuses a value that is not a legal target rather than serializing one: §8.1 states both members of an escalation target, and a pack declaring an empty kind or name is refused long before an evaluation could report one. The engine builds no such value; an exported type can be handed one, and serializing it would put a target no pack can declare on both sides of a comparison.

func (*HandoffTarget) Rendered added in v0.17.0 

func (h *HandoffTarget) Rendered() (string, error)

Rendered is Canonical under the budget above: the value a row result carries, and only that. Every reader that *reports* a target goes through it, so nothing retains an unbounded rendering — and no reader that *decides* anything goes through it at all.

type InputDifference added in v0.24.0 

type InputDifference struct {
	ID      string       `json:"id"`
	Changed []string     `json:"changed"`
	Old     ComparedSide `json:"old"`
	New     ComparedSide `json:"new"`
}

InputDifference is one input the two packs decide differently. Changed names what differs, in a fixed order: kind, outcomeId, reasons, handoff, value, handoffTarget, or refusal. The names describe the difference; what decides that there is one is the §8.3 canonical bytes, the handoff target, and the refusal.

type Layer 

type Layer struct {
	Name   string `json:"name"`
	Status string `json:"status"`
}

type LintCounts added in v0.15.0 

type LintCounts struct {
	Total   int `json:"total"`
	Passed  int `json:"passed"`
	Failed  int `json:"failed"`
	Skipped int `json:"skipped"`
}

LintCounts is one packs lint summary. Unlike PackCounts it carries a skipped member, because a lint entry has three outcomes and a summary that folded skipped packs into neither number would misdescribe its own total.

type LockFinding added in v0.13.0 

type LockFinding struct {
	Name   string `json:"name"`
	Kind   string `json:"kind,omitempty"`
	ID     string `json:"id,omitempty"`
	Path   string `json:"path,omitempty"`
	Detail string `json:"detail,omitempty"`
}

LockFinding is one named difference between a document and the reviewed set. Kind is "pack", "graph", or absent for the configuration itself: a pack and a graph may share an id, so the pair is the finding's identity.

type LockedID added in v0.13.0 

type LockedID struct {
	Kind   string `json:"kind"`
	ID     string `json:"id"`
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

LockedID is one declared document in the reviewed set, reported in the sorted order every project payload uses.

type MatrixProbe added in v0.9.0 

type MatrixProbe struct {
	Probe  string `json:"probe"`
	Status string `json:"status"`
	Detail string `json:"detail,omitempty"`
}

MatrixProbe is one derived coverage probe: a behavior or a comparison boundary the pack's own declarations make reachable, and whether any matrix row witnesses it. Coverage reads what the rows document — a disposition probe is witnessed by what a row expects, a boundary probe by what a row's authored facts state — and never what an evaluation produced. A covered probe says "a row states this", never that the row is right, and a matrix with every probe covered has stated something about every derivable behavior, which is not a statement that the pack decides well or that its rows expect the right things.

type MatrixProfile added in v0.21.0 

type MatrixProfile struct {
	Agreement  []OriginAgreement  `json:"agreement"`
	Coverage   []OriginCoverage   `json:"coverage,omitempty"`
	Thresholds []ThresholdProfile `json:"thresholds,omitempty"`
}

MatrixProfile reads one pack's matrix against the history its rows came from (ADR-0034): the statuses the run assigned, grouped by the origin each row declares; the derived coverage restricted to each origin's rows; and, for each comparison boundary the pack draws, where each origin's rows place the compared fact and how many of those disagree. It is present only when some row declares an origin, it is derived from the run already made, and it moves no status: a disagreement is one of a pack defect, a past inconsistency and a policy change, and which is the policy owner's to say.

type OperationalError 

type OperationalError struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	// EvaluationError is present exactly when the failure is an evaluation error
	// of JPS Core §8.4, naming its class and phase. Its absence means the failure
	// is an ordinary operational refusal — a bad invocation, an unreadable input,
	// an internal fault — which §8.4 does not classify.
	EvaluationError *EvaluationError `json:"evaluationError,omitempty"`
	Diagnostics     []Diagnostic     `json:"diagnostics"`
}

func NewEvaluationError added in v0.4.0 

func NewEvaluationError(command, status, class, phase, code, message string) OperationalError

NewEvaluationError reports one JPS Core §8.4 evaluation error: the class and phase in band, and this runtime's finer diagnostic code beside them. No disposition accompanies it, ever.

func NewOperationalError 

func NewOperationalError(command, code, message string) OperationalError

func NewOperationalResult 

func NewOperationalResult(command, status, code, message string) OperationalError

type OriginAgreement added in v0.21.0 

type OriginAgreement struct {
	Origin     string `json:"origin"`
	Rows       int    `json:"rows"`
	Passed     int    `json:"passed"`
	Mismatched int    `json:"mismatched"`
}

OriginAgreement is how one origin's rows fared: the rows that declare it, how many passed and how many did not, in the run's own terms.

type OriginCount added in v0.17.0 

type OriginCount struct {
	Origin string `json:"origin"`
	Rows   int    `json:"rows"`
}

OriginCount is how many of one pack's matrix rows declare one origin, in sorted order of the origin. Only rows that declare one are counted, so a suite in which nothing declares an origin carries no member rather than a zero: the absence of the marker is not a claim that every row was hand written, and a count of "" would read like one.

type OriginCoverage added in v0.21.0 

type OriginCoverage struct {
	Origin  string `json:"origin"`
	Covered int    `json:"covered"`
	Probes  int    `json:"probes"`
}

OriginCoverage is how many of the derived probes some row of one origin witnesses, out of the probes there are: which of the pack's reachable behaviors that history ever exercised.

type PackCheck added in v0.4.0 

type PackCheck struct {
	Name   string `json:"name"`
	Status string `json:"status"`
	Detail string `json:"detail,omitempty"`
}

PackCheck is one named check applied to one configured pack.

type PackComparison added in v0.24.0 

type PackComparison struct {
	OutputVersion             string            `json:"outputVersion"`
	Tool                      Tool              `json:"tool"`
	Command                   string            `json:"command"`
	Status                    string            `json:"status"`
	Experimental              bool              `json:"experimental"`
	Rehearsal                 bool              `json:"rehearsal"`
	ConformanceClaimReference string            `json:"conformanceClaimReference"`
	Label                     string            `json:"label"`
	EvaluatorSpecVersion      string            `json:"evaluatorSpecVersion"`
	Old                       ComparedPack      `json:"old"`
	New                       ComparedPack      `json:"new"`
	DifferentDecisions        bool              `json:"differentDecisions,omitempty"`
	Inputs                    ComparedInputs    `json:"inputs"`
	Differences               []InputDifference `json:"differences"`
}

PackComparison is one experimental compare run (ADR-0045): every input evaluated under both packs, and the inputs whose results differ.

Rehearsal is always true. The command opens no project, so it appends no audit record and consults no reviewed set, and the payload says so in the member ADR-0028 gave that statement. Inputs that are the same are counted and not listed; every difference is listed, in input order.

DifferentDecisions is true when both packs' ids were read and they differ: the two documents are two decisions rather than two versions of one. The comparison still runs, because comparing two decisions may be deliberate, and the member is omitted otherwise, both when the ids are the same and when either was never read.

type PackCounts added in v0.4.0 

type PackCounts struct {
	Total  int `json:"total"`
	Passed int `json:"passed"`
	Failed int `json:"failed"`
}

PackCounts summarizes a per-pack report: one count per pack checked, and one pack is either passed or failed. A check the configuration never asked for is skipped per check rather than per pack, which is where PackCheckSkipped reports it — a pack with four passed checks and one skipped has passed.

type PackDocument added in v0.4.0 

type PackDocument struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	Kind          string `json:"kind"`
	ConfigPath    string `json:"configPath"`
	ID            string `json:"id"`
	PackID        string `json:"packId"`
	PackVersion   string `json:"packVersion"`
	SpecVersion   string `json:"specVersion"`
	Path          string `json:"path"`
	Description   string `json:"description,omitempty"`
	Bytes         int    `json:"bytes"`
	SHA256        string `json:"sha256"`
	Detail        string `json:"detail,omitempty"`
}

PackDocument is the metadata beside one pack document served by decision id. The bytes travel separately, exactly as a bundled example's do.

Status is "valid" when the served bytes decoded and the identity members below were read off them, and "undecodable" when they did not, in which case Detail says why and those members are empty rather than guessed. Neither value is a verdict on the document's conformance: serving a pack does not validate it, and spec validate is what reports that.

type PackInventory added in v0.4.0 

type PackInventory struct {
	OutputVersion string        `json:"outputVersion"`
	Tool          Tool          `json:"tool"`
	Command       string        `json:"command"`
	Status        string        `json:"status"`
	Kind          string        `json:"kind"`
	ConfigPath    string        `json:"configPath"`
	ConfigVersion string        `json:"configVersion,omitempty"`
	Note          string        `json:"note,omitempty"`
	Packs         []PackSummary `json:"packs"`
}

PackInventory is the resolved project inventory. Status is "none" when no configuration was found at the resolved location, which is an answer and not a failure: a project may simply not use the convention, and Note says where the runtime looked.

type PackLock added in v0.13.0 

type PackLock struct {
	OutputVersion string     `json:"outputVersion"`
	Tool          Tool       `json:"tool"`
	Command       string     `json:"command"`
	Status        string     `json:"status"`
	Kind          string     `json:"kind"`
	ConfigPath    string     `json:"configPath"`
	LockPath      string     `json:"lockPath"`
	LockVersion   string     `json:"lockVersion"`
	ConfigDigest  string     `json:"configDigest"`
	Summary       PackCounts `json:"summary"`
	Entries       []LockedID `json:"entries"`
	WrittenTo     string     `json:"writtenTo,omitempty"`
}

PackLock is one packs lock report: the reviewed set this run declared (ADR-0019). It is its own payload rather than a member of an existing one, on ADR-0017's precedent — a surface this new should be removable without taking a member out of a payload consumers already read.

type PackLockVerification added in v0.13.0 

type PackLockVerification struct {
	OutputVersion string        `json:"outputVersion"`
	Tool          Tool          `json:"tool"`
	Command       string        `json:"command"`
	Status        string        `json:"status"`
	Kind          string        `json:"kind"`
	ConfigPath    string        `json:"configPath"`
	LockPath      string        `json:"lockPath"`
	LockVersion   string        `json:"lockVersion"`
	Summary       PackCounts    `json:"summary"`
	StaleEntries  int           `json:"staleEntries"`
	Checks        []PackCheck   `json:"checks,omitempty"`
	Findings      []LockFinding `json:"findings"`
}

PackLockVerification is one packs verify report: every difference between a project's current documents and the reviewed set its lock declares.

Summary counts the documents the configuration declares, and nothing else, so Passed plus Failed is always Total. Two findings are therefore outside it and each is reported in its own place: the configuration's own drift, which is a configuration-level check exactly as it is in PackValidation, and an entry the reviewed set names that the configuration no longer declares, which is counted by StaleEntries because it is not one of the documents Total is about. Every finding of every kind is in Findings regardless.

type PackProducersLint added in v0.15.0 

type PackProducersLint struct {
	OutputVersion   string                   `json:"outputVersion"`
	Tool            Tool                     `json:"tool"`
	Command         string                   `json:"command"`
	Status          string                   `json:"status"`
	Kind            string                   `json:"kind"`
	ConfigPath      string                   `json:"configPath"`
	ConfigVersion   string                   `json:"configVersion"`
	ProducersSource string                   `json:"producersSource"`
	Summary         LintCounts               `json:"summary"`
	Checks          []PackCheck              `json:"checks,omitempty"`
	Packs           []PackProducersLintEntry `json:"packs"`
}

PackProducersLint is one packs lint report (ADR-0022). It is its own payload rather than a member of an existing one, on the same reasoning PackLock records: a surface this new should be removable without taking a member out of a payload consumers already read. ProducersSource says which producer declaration the run was held to — the configuration's own hints, or an explicit manifest.

type PackProducersLintEntry added in v0.15.0 

type PackProducersLintEntry struct {
	ID          string      `json:"id"`
	PackID      string      `json:"packId"`
	PackVersion string      `json:"packVersion"`
	Path        string      `json:"path"`
	Status      string      `json:"status"`
	Checks      []PackCheck `json:"checks"`
}

PackProducersLintEntry is one pack's producer lint: whether every pointer its conditions consult has a producer, and whether declared and supplied evidence agree. Status follows the packs test discipline — "skipped" when nothing was checkable, never "passed".

type PackSuggestion added in v0.17.0 

type PackSuggestion struct {
	OutputVersion     string                `json:"outputVersion"`
	Tool              Tool                  `json:"tool"`
	Command           string                `json:"command"`
	Status            string                `json:"status"`
	Kind              string                `json:"kind"`
	Label             string                `json:"label"`
	ConfigPath        string                `json:"configPath"`
	ConfigVersion     string                `json:"configVersion"`
	CandidatesVersion string                `json:"candidatesVersion"`
	Summary           SuggestionCounts      `json:"summary"`
	Packs             []PackSuggestionEntry `json:"packs"`
	WrittenTo         string                `json:"writtenTo,omitempty"`
}

PackSuggestion is one packs suggest report (ADR-0024): the report *about* a derivation, which is a different artifact from the candidate document the derivation emits. The document goes to --write or to stdout and carries candidatesVersion and candidates; this payload carries the counts, the pack identities the candidates came from, and every skipped dimension. Keeping them apart is what lets the document stay inputs-only — a provenance member inside it would be a member of a file whose whole purpose is to be edited into a matrix — while a reader still learns which pack version a run read.

It is its own payload rather than a member of an existing one, on the reasoning PackLock and PackProducersLint record: a surface this new should be removable without taking a member out of a payload consumers already read.

type PackSuggestionEntry added in v0.17.0 

type PackSuggestionEntry struct {
	ID          string           `json:"id"`
	PackID      string           `json:"packId"`
	PackVersion string           `json:"packVersion"`
	Path        string           `json:"path"`
	Status      string           `json:"status"`
	Unreadable  bool             `json:"unreadable,omitempty"`
	Candidates  int              `json:"candidates"`
	Skipped     []SuggestionSkip `json:"skipped,omitempty"`
	Detail      string           `json:"detail,omitempty"`
}

PackSuggestionEntry is one pack's derivation: how many candidate inputs it produced and every dimension it did not. Status is "suggested" when the pack derived at least one candidate and "skipped" when it derived none — never "passed", because nothing here was checked.

Unreadable separates the two ways of deriving nothing, which are different facts and must not be reported as one. A pack this runtime read and found no derivable comparison in states no such comparison; a pack it could not read states nothing knowable at all, and a report that said "no comparison" of it would be asserting something about a document nobody parsed.

type PackSummary added in v0.4.0 

type PackSummary struct {
	ID                    string        `json:"id"`
	PackID                string        `json:"packId"`
	PackVersion           string        `json:"packVersion"`
	Path                  string        `json:"path"`
	MatrixPath            string        `json:"matrixPath,omitempty"`
	Matrix                bool          `json:"matrix"`
	Description           string        `json:"description,omitempty"`
	ExpectedVersion       string        `json:"expectedVersion,omitempty"`
	ExpectedVersionStatus string        `json:"expectedVersionStatus"`
	EvidenceRequirements  []string      `json:"evidenceRequirements"`
	ConsultedFactPaths    []string      `json:"consultedFactPaths"`
	Facts                 []ProjectHint `json:"facts"`
	Evidence              []ProjectHint `json:"evidence"`
	Detail                string        `json:"detail,omitempty"`
}

PackSummary is one resolved inventory row: the project's decision id beside the pack document's own identity, which are two different names and are reported as two members for that reason. Detail is present when the document could not be read or decoded, in which case the identity members are empty rather than guessed.

ConsultedFactPaths is the pointers the document's conditions carry, sorted and deduplicated (ADR-0020); the empty string is the root pointer. It reports what the document says, not a verdict on it: listing is not validating, a string that is not a legal pointer is reported verbatim, and a document that could not be read carries [] beside its Detail exactly as evidenceRequirements does. The list over-approximates by design — an object shaped like a condition but carried as data is collected too — so a consumer treats it as candidate pointers from an untrusted document, never as instructions or as proof of a read. An additive member, so outputVersion stays "2" by the same two VERSIONING.md rules ADR-0012 cites.

type PackTest added in v0.4.0 

type PackTest struct {
	OutputVersion             string `json:"outputVersion"`
	Tool                      Tool   `json:"tool"`
	Command                   string `json:"command"`
	Status                    string `json:"status"`
	Experimental              bool   `json:"experimental"`
	EvaluatorSpecVersion      string `json:"evaluatorSpecVersion"`
	ConformanceClaimReference string `json:"conformanceClaimReference"`
	Label                     string `json:"label"`
	Kind                      string `json:"kind"`
	ConfigPath                string `json:"configPath"`
	ConfigVersion             string `json:"configVersion"`
	// RequireMatrix is true exactly when the caller asked that a declared pack
	// with no matrix fail the run rather than be skipped (ADR-0042). Absent
	// otherwise, so a run that did not ask reads as it did before.
	RequireMatrix bool            `json:"requireMatrix,omitempty"`
	Summary       SuiteSummary    `json:"summary"`
	Packs         []PackTestEntry `json:"packs"`
}

PackTest is one packs test run. It carries Experimental, ConformanceClaimReference, and EvaluatorSpecVersion like every other payload the evaluator produces, because the evaluator that produced its rows is that surface — the applied contract version stays in band (ADR-0011) even for a run whose every pack was skipped and carries no row to infer it from. An additive member, so outputVersion stays "2" by the same two VERSIONING.md rules ADR-0012 cites.

type PackTestEntry added in v0.4.0 

type PackTestEntry struct {
	ID          string                 `json:"id"`
	PackID      string                 `json:"packId"`
	PackVersion string                 `json:"packVersion"`
	Path        string                 `json:"path"`
	MatrixPath  string                 `json:"matrixPath,omitempty"`
	Status      string                 `json:"status"`
	Summary     SuiteSummary           `json:"summary"`
	Rows        []EvaluationCorpusCase `json:"rows"`
	Coverage    []MatrixProbe          `json:"coverage,omitempty"`
	Origins     []OriginCount          `json:"origins,omitempty"`
	Profile     *MatrixProfile         `json:"profile,omitempty"`
	Detail      string                 `json:"detail,omitempty"`
}

PackTestEntry is one pack's matrix run. Rows reuse the corpus row type, because a project matrix row is compared exactly as a corpus row is: the RFC 8785 canonical disposition byte for byte, or the expected §8.4 error class and phase.

Coverage is present when the matrix loaded as rows, the evaluator admits the pack — one the preflight refuses never reaches §8, so no derivation describes it — and the pack's declarations derive at least one probe. Mismatched rows are included, because it reads what the rows document — their expectations, and their authored facts — which exist whether or not they held. It never moves Status — a missing probe is a fact about what the rows state, not a failed row (ADR-0014, ADR-0023). An additive member, so outputVersion stays "2" by the same two VERSIONING.md rules ADR-0012 cites. Origins counts the rows by the origin each declares, so a suite whose rows were mostly machine-supplied inputs says so where a reviewer and a CI log both read it (ADR-0024). It counts and never gates: an origin moves no status, no summary, and no exit code, because the member that decides anything about a row is its expectation and an expectation is always authored. Gating on it would be worse than useless — the marker is deletable in one edit, and a gate would teach exactly that deletion, destroying the one signal that measures how much of a suite a generator supplied. An additive member, so outputVersion stays "2" by the same two VERSIONING.md rules ADR-0012 cites.

type PackValidation added in v0.4.0 

type PackValidation struct {
	OutputVersion string                `json:"outputVersion"`
	Tool          Tool                  `json:"tool"`
	Command       string                `json:"command"`
	Status        string                `json:"status"`
	Kind          string                `json:"kind"`
	ConfigPath    string                `json:"configPath"`
	ConfigVersion string                `json:"configVersion"`
	Summary       PackCounts            `json:"summary"`
	Checks        []PackCheck           `json:"checks,omitempty"`
	Packs         []PackValidationEntry `json:"packs"`
}

PackValidation is one packs validate report.

Checks are the checks about the configuration itself rather than about any one pack — today the containment of the audit directory, which no pack entry owns. They are a separate list because the summary counts packs: a configuration-level failure moves Status without moving a pack count, and folding it into a pack's checks would report it against a pack that is fine. An additive member, so outputVersion stays "2" by the same two VERSIONING.md rules ADR-0012 cites.

type PackValidationEntry added in v0.4.0 

type PackValidationEntry struct {
	ID     string      `json:"id"`
	Path   string      `json:"path"`
	Status string      `json:"status"`
	Checks []PackCheck `json:"checks"`
}

PackValidationEntry is every check applied to one configured pack, in the order they were applied. A failed check that makes a later one meaningless — a path that escapes the project root — leaves the rest skipped rather than reporting checks that never ran.

type ProjectHint added in v0.4.0 

type ProjectHint struct {
	Key    string `json:"key"`
	Source string `json:"source,omitempty"`
	Hint   string `json:"hint,omitempty"`
}

ProjectHint is one non-normative agent hint declared in a jpack.json entry: where a fact or a piece of evidence is held, and how to obtain it. The runtime carries it and never acts on it — it holds no credential, opens no connection, and reads no source (ADR-0004, ADR-0006, ADR-0012). Key is the RFC 6901 JSON Pointer for a fact hint and the declared evidence-requirement id for an evidence hint.

type ReviewedSet added in v0.24.0 

type ReviewedSet struct {
	LockDigest   string `json:"lockDigest"`
	LockVersion  string `json:"lockVersion"`
	ConfigDigest string `json:"configDigest"`
}

ReviewedSet names the revision of a project's reviewed set (ADR-0019) that made a run's Reviewed true: the digest of the exact lock bytes the checks used, the shape those bytes declared, and the configuration digest that was compared.

It is named because the lock is replaced in place. Without it a reader holding a record or a payload and a lock file cannot tell whether that lock is the one the decision was judged under, and the Boolean would be a claim nothing outside the run can re-derive. It is present exactly when Reviewed is true: a draft was judged under no reviewed set, and a project with no lock has none to name. The audit record carries the same shape (ADR-0044).

type Schema 

type Schema struct {
	OutputVersion string `json:"outputVersion"`
	Tool          Tool   `json:"tool"`
	Command       string `json:"command"`
	Status        string `json:"status"`
	SpecVersion   string `json:"specVersion"`
	SchemaID      string `json:"schemaId"`
	Bytes         int    `json:"bytes"`
	SHA256        string `json:"sha256"`
	Provenance    string `json:"provenance"`
	WrittenTo     string `json:"writtenTo,omitempty"`
}

type SuggestionCounts added in v0.17.0 

type SuggestionCounts struct {
	Total      int `json:"total"`
	Suggested  int `json:"suggested"`
	Skipped    int `json:"skipped"`
	Candidates int `json:"candidates"`
}

SuggestionCounts summarizes one packs suggest run. Total counts the packs selected; Candidates counts the candidate inputs derived across all of them, which is the number a reviewer is about to read.

type SuggestionSkip added in v0.17.0 

type SuggestionSkip struct {
	Name   string `json:"name"`
	Detail string `json:"detail"`
}

SuggestionSkip is one derivation this run did not perform, and why. A dimension the generator cannot address is reported rather than silently omitted, on ADR-0022's skipped-not-passed precedent: a candidate set that quietly left out a pack's collection quantifiers would read as the whole derivable set when it is not.

type Suite 

type Suite struct {
	OutputVersion         string       `json:"outputVersion"`
	Tool                  Tool         `json:"tool"`
	Command               string       `json:"command"`
	Status                string       `json:"status"`
	SpecVersion           string       `json:"specVersion"`
	SuiteVersion          string       `json:"suiteVersion"`
	CorpusDigest          string       `json:"corpusDigest"`
	CorpusDigestAlgorithm string       `json:"corpusDigestAlgorithm"`
	Provenance            string       `json:"provenance"`
	Summary               SuiteSummary `json:"summary"`
	Cases                 []Case       `json:"cases"`
	Diagnostics           []Diagnostic `json:"diagnostics"`
	DiagnosticsTruncated  bool         `json:"diagnosticsTruncated"`
}

type SuiteSummary 

type SuiteSummary struct {
	Total      int `json:"total"`
	Passed     int `json:"passed"`
	Mismatched int `json:"mismatched"`
}

type ThresholdOrigin added in v0.21.0 

type ThresholdOrigin struct {
	Origin string        `json:"origin"`
	Below  ThresholdSide `json:"below"`
	At     ThresholdSide `json:"at"`
	Above  ThresholdSide `json:"above"`
}

ThresholdOrigin is one origin's rows against one boundary: below, at and above the literal, by the evaluator's own comparison (§7.4); a row whose fact is absent or not comparable there is counted on no side.

type ThresholdProfile added in v0.21.0 

type ThresholdProfile struct {
	Pointer string            `json:"pointer"`
	Literal string            `json:"literal"`
	Origins []ThresholdOrigin `json:"origins"`
}

ThresholdProfile is one comparison boundary the pack draws -- a fact pointer against a decimal literal -- and, per origin, where that origin's rows place the fact against it.

type ThresholdSide added in v0.21.0 

type ThresholdSide struct {
	Rows               int    `json:"rows"`
	Disagreeing        int    `json:"disagreeing"`
	Nearest            string `json:"nearest,omitempty"`
	NearestDisagreeing string `json:"nearestDisagreeing,omitempty"`
}

ThresholdSide counts the rows on one side of a boundary and how many of them disagree, and names the value nearest the literal on that side and the nearest disagreeing one, spelled as the row wrote them: the cases a policy owner asks about before moving a line. Nothing is a window; nearest is nearest.

type Tool 

type Tool struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

func CurrentTool 

func CurrentTool() Tool

type TraceEntry added in v0.2.0 

type TraceEntry struct {
	Stage          string         `json:"stage"`
	ID             string         `json:"id,omitempty"`
	Condition      string         `json:"condition"`
	Effect         string         `json:"effect,omitempty"`
	Outcome        string         `json:"outcome,omitempty"`
	Suppressed     bool           `json:"suppressed,omitempty"`
	OnUnknown      string         `json:"onUnknown,omitempty"`
	Skipped        bool           `json:"skipped,omitempty"`
	UnknownCauses  []UnknownCause `json:"unknownCauses,omitempty"`
	TypeMismatches []TypeMismatch `json:"typeMismatches,omitempty"`
}

TraceEntry records one stage of the §8 walk — the applicability, an exception, or a rule — including rules the walk never evaluated, which appear as not-evaluated with the skipped or suppressed label that says why. The trace is informative: §8 requires an unknown that resolution ignored to remain visible, and permits recording contributing ids. A pack's applicability is one unnamed condition rather than an authored declaration, so its entry carries no id at all rather than an empty one. ADR-0027 states the record's contract — walk order, exactly-once rule completeness and the precedence between its not-evaluated shapes, no stage for the step-2 evidence inspection, and no leaked in-progress record on a refused evaluation — and the byte-goldens that pin it.

ADR-0040 adds two members that say why an entry came out as it did. Each is omitted when it has nothing to say, so an entry that carries neither is byte for byte what ADR-0027 pinned. UnknownCauses is present only on an entry whose condition is unknown, and names every leaf the unknown came from — and only those: a leaf whose unknown a sibling's verdict overrode is not a cause. TypeMismatches names every equality comparison the entry's condition evaluated whose fact value and operand differ in JSON type, whatever the verdict, because the two values could not have been equal and the verdict does not say so. Neither member changes a verdict or a disposition.

type TypeMismatch added in v0.24.0 

type TypeMismatch struct {
	Path         string   `json:"path"`
	Within       *string  `json:"within,omitempty"`
	Operator     string   `json:"operator"`
	FactType     string   `json:"factType"`
	OperandTypes []string `json:"operandTypes"`
}

TypeMismatch is one equality comparison (equals, not-equals or in) whose fact value has a different JSON type from its operand, or for in from every member of its operand (ADR-0040). §7.4 makes equality type-preserving, so the two values are unequal whatever they are: equals and in are false, not-equals is true. This records that they could not have been equal, which the verdict alone does not say. OperandTypes lists the operand's JSON types in first-appearance order: one for equals and not-equals, the distinct member types for in. Path is always present, "" included; Within is as for UnknownCause. One entry lists a mismatch once however many times its condition compared it, in the order the walk first met it.

type UnknownCause added in v0.24.0 

type UnknownCause struct {
	Path                *string `json:"path,omitempty"`
	EvidenceRequirement string  `json:"evidenceRequirement,omitempty"`
	Within              *string `json:"within,omitempty"`
	Cause               string  `json:"cause"`
	FactType            string  `json:"factType,omitempty"`
}

UnknownCause is one leaf of a condition that evaluated unknown and left its entry unknown (ADR-0040). Path names a fact pointer, or EvidenceRequirement an evidence-present condition's requirement; one of the two is set, except for the cause "unsupported" on a node that states neither, which sets neither. Path and Within are pointers to strings because "" is a JSON Pointer of its own, selecting the whole document it is resolved against, and must survive serialization as "" rather than vanish as an unset member would. Within is the collection pointer of the draft RFC 0008 aggregate whose elements Path was resolved against, the innermost one when aggregates nest, and is absent for a pointer resolved against the facts document itself. An evidence-present condition inside an aggregate still reads the evaluation's evidence, not an element, so its cause carries no Within.

Cause is one of:

  • "absent": the pointer selects nothing in the document it was resolved in;
  • "not-comparable": an ordered comparison selected a value that is not a §2.2 decimal string, and FactType names the JSON type it has;
  • "not-an-array": a quantifier's collection pointer selected something that is not an array, whose type FactType names;
  • "unknown": an evidence-present condition read a requirement whose presence is unknown, stated or omitted;
  • "unsupported": a condition shape this evaluator does not decide, which a conformant pack cannot state and is reported rather than hidden.

type UnmetEvidence added in v0.24.0 

type UnmetEvidence struct {
	Requirement string `json:"requirement"`
	State       string `json:"state"`
}

UnmetEvidence is one required evidence requirement whose presence stopped an evaluation at §8 step 2 (ADR-0040): "absent" or "unknown", in the order the pack declares its requirements. It is reported beside the trace and never inside it, because step 2 evaluates no condition and ADR-0027 gives it no trace stage; the disposition's reasons are unchanged by it.

type Validation 

type Validation struct {
	OutputVersion        string          `json:"outputVersion"`
	Tool                 Tool            `json:"tool"`
	Command              string          `json:"command"`
	Status               string          `json:"status"`
	SpecVersion          string          `json:"specVersion,omitempty"`
	ValidationScope      ValidationScope `json:"validationScope"`
	Layers               []Layer         `json:"layers"`
	Extensions           Extensions      `json:"extensions"`
	Diagnostics          []Diagnostic    `json:"diagnostics"`
	DiagnosticsTruncated bool            `json:"diagnosticsTruncated"`
	Artifact             *Artifact       `json:"artifact,omitempty"`
}

func NewValidation 

func NewValidation(through string) Validation

type ValidationScope 

type ValidationScope struct {
	RequestedThrough        string `json:"requestedThrough"`
	FullDocumentConformance bool   `json:"fullDocumentConformance"`
}

type Version 

type Version struct {
	OutputVersion      string   `json:"outputVersion"`
	Tool               Tool     `json:"tool"`
	Command            string   `json:"command"`
	Status             string   `json:"status"`
	SupportedSpecs     []string `json:"supportedSpecVersions"`
	ArtifactProvenance string   `json:"artifactProvenance"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

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