Documentation
¶
Overview ¶
Package tracecontext implements the versioned immutable work-item identity and signed trace-context envelope contract from ADR 0154.
The package is pure: it performs no network I/O, reads no configuration, and never grants dispatch permission. It must stay importable from pkg/behaviourtest, so it must not depend on internal/cli, internal/repos, internal/layers, or the nested mintcore module.
Index ¶
Constants ¶
const ( ReasonAbsent = "absent" ReasonMalformed = "malformed" ReasonOversized = "oversized" ReasonUnknownVersion = "unknown-version" ReasonUnknownKey = "unknown-key" ReasonBadSignature = "bad-signature" ReasonBindingMismatch = "binding-mismatch" ReasonConflictingCarrier = "conflicting-carrier" ReasonProvenance = "provenance" ReasonUnresolved = "unresolved" ReasonPending = "pending" )
Reason codes for non-admitted outcomes. They are redacted diagnostics: no key material, no raw bytes.
const MaxCarrierLen = 588
MaxCarrierLen is the maximum legal base64 carrier length in characters: base64.StdEncoding of MaxEnvelopeLen bytes without line breaks.
const MaxEnvelopeLen = 439
MaxEnvelopeLen is the maximum legal wire size in bytes: a bound envelope with scenario provenance and a 253-byte instance (439 bytes). Anything longer is definitionally invalid.
Variables ¶
This section is empty.
Functions ¶
func DecodeCarrier ¶
DecodeCarrier strictly decodes a base64 carrier string to raw envelope bytes. It rejects line breaks, non-canonical encodings, and carriers longer than MaxCarrierLen.
func KeyID ¶
KeyID returns the v1 key selector for a verification key: the first 8 bytes of SHA-256(public key). Envelopes carry only this selector; keys are resolved exclusively against trusted configuration.
func NormalizeInstance ¶
NormalizeInstance canonicalizes a forge web base URL to the D01 instance form: lowercase scheme://host with an escaped, case-sensitive deployment prefix and no trailing slashes, query, fragment, or user info. Only http and https are accepted. Ports lose leading zeros (an all-zero port stays :0) and must fit 16 bits; empty and default ports are then removed. Trailing DNS root dots are stripped, hosts must be ASCII (punycode for IDNs), and IPv6 hosts take their RFC 5952 section 4 form, with IPv4-mapped addresses in mixed notation, and no zone identifier. Path segments and escape spelling are preserved so distinct deployments cannot alias; a path mixing percent-escapes with characters that still need escaping rejects. All identity and envelope construction must use the normalized form so independent launches converge.
Types ¶
type Domain ¶
type Domain byte
Domain distinguishes the two v1 message domains. The domain byte is covered by the signature, so a pending marker cannot be replayed as a bound envelope.
type EntityKind ¶
type EntityKind byte
EntityKind distinguishes the entity kinds that can share a forge container. GitLab issue and merge-request database IDs come from independent spaces, so the kind is part of every identity.
const ( // KindWorkItem is an issue on GitHub, GitLab, or Jira. KindWorkItem EntityKind = 0x01 // KindChangeProposal is a GitHub pull request or a GitLab merge // request. Jira has no change-proposal entity in this contract. KindChangeProposal EntityKind = 0x02 )
func (EntityKind) Valid ¶
func (k EntityKind) Valid() bool
Valid reports whether k is a defined entity kind.
type Envelope ¶
type Envelope struct {
Domain Domain
KeyID [8]byte
Installation [16]byte
Instance string
Container int64
Kind EntityKind
// Entity is the immutable destination database ID. It must be 0 in
// pending markers; the destination does not exist yet.
Entity int64
TraceID trace.TraceID
ParentSpanID trace.SpanID
Provenance Provenance
Nonce [16]byte
Signature [64]byte
}
Envelope is a decoded v1 envelope or pending marker. Its fields are unauthenticated: Parse checks structure only, so TraceID, ParentSpanID, and Provenance must not be consumed unless Admit returns OutcomeAdmitted. The wire layout, exact sizes, and strict limits are specified in docs/normative/trace-context/v1/README.md, provisional until the first carrier-publishing PR merges; Marshal is its only legal encoder.
func Parse ¶
Parse strictly decodes and structurally validates wire bytes. It accepts only the exact structural length for the parsed domain and provenance kind; duplicate and unknown fields are structurally impossible in the fixed layout. Parse does not verify the signature or binding, so its result is unauthenticated: Admit is the only authenticated path and the only safe source of trace context. Provenance cross-field consistency is checked at admission, not here.
type Fallback ¶
Fallback is the deterministic entity-derived context: a stable TraceID and a synthetic anchor SpanID. By contract, the anchor exists only as a parent reference, is never exported as a span, and is never repointed.
func DeriveFallback ¶
DeriveFallback derives the v1 deterministic fallback context. The derivation covers the forge instance, container, kind, and entity — never the installation, per ADR 0154. It returns ok=false for an unresolved identity. The derivation is pure, so independent and concurrent first events converge on identical nonzero IDs.
type Identity ¶
type Identity struct {
// Installation is the 128-bit installation identifier provisioned
// with the signing key pair. It is authenticated in envelopes but
// deliberately excluded from fallback derivation, per ADR 0154.
Installation [16]byte
// Instance is the normalized forge web base URL: lowercase scheme://host
// with its escaped, case-sensitive deployment prefix and no trailing slash.
// Use NormalizeInstance to build it from trusted configuration.
Instance string
// Container is the immutable repository or project database ID.
Container int64
// Kind is the entity kind within the container.
Kind EntityKind
// Entity is the immutable entity database ID.
Entity int64
}
Identity is the immutable binding of a forge entity (ADR 0154, D01): installation, forge instance, container, entity kind, and entity database ID. Display names, entity URLs, GitHub numbers, GitLab IIDs, and Jira keys are not identity components; docs/normative/trace-context/v1/README.md holds the per-forge field mapping.
func (Identity) Resolved ¶
Resolved reports whether the forge-side identity components are present and valid: a canonical instance, a container ID >= 1, a valid kind, and an entity ID >= 1. Installation is local configuration rather than event identity, so it is not part of resolution; admission checks it against the envelope separately. An unresolved identity must postpone dispatch (FR-002); it never derives a fallback.
type Outcome ¶
type Outcome int
Outcome is the admission outcome. It never encodes dispatch permission.
const ( // OutcomeFallback means no decoded candidate was admissible; the // caller uses the deterministic entity-derived fallback, except for // ReasonUnresolved, where it must postpone dispatch. It is the zero // value. OutcomeFallback Outcome = iota // OutcomeAdmitted means a verified bound envelope matched the // expected binding; the admitted IDs are available. OutcomeAdmitted // OutcomePending means a verified pending marker matched the expected // scope. It grants neither context nor links; callers bound the reread // by a window from the entity's trusted creation metadata, then fall // back. OutcomePending )
type Provenance ¶
type Provenance struct {
Kind ProvenanceKind
// SourceTraceID and SourceSpanID identify the creating operation for
// ProvenanceSourceLink. Valid when Kind == ProvenanceSourceLink.
SourceTraceID trace.TraceID
SourceSpanID trace.SpanID
// ScenarioTraceID and ScenarioInvocationID identify the scenario for
// ProvenanceScenario. Valid when Kind == ProvenanceScenario.
ScenarioTraceID trace.TraceID
ScenarioInvocationID [16]byte
}
Provenance carries the authenticated creation provenance of an envelope. Only the fields selected by Kind are meaningful.
type ProvenanceKind ¶
type ProvenanceKind byte
ProvenanceKind selects the authenticated provenance section.
const ( // ProvenanceNone means the envelope carries no creation provenance. ProvenanceNone ProvenanceKind = 0x00 // ProvenanceSourceLink is an ordinary creation relationship: the // source operation's span context, recorded as a link only. The // destination keeps its own TraceID. ProvenanceSourceLink ProvenanceKind = 0x01 // ProvenanceScenario is behaviour-test scenario ownership: the entity // inherits the scenario TraceID. ProvenanceScenario ProvenanceKind = 0x02 )
func (ProvenanceKind) Valid ¶
func (k ProvenanceKind) Valid() bool
Valid reports whether k is a defined provenance kind.
type Result ¶
type Result struct {
Outcome Outcome
// Reason is a redacted reason code when the outcome is not admitted.
Reason string
// TraceID and ParentSpanID are the admitted context, valid when
// Outcome == OutcomeAdmitted.
TraceID trace.TraceID
ParentSpanID trace.SpanID
// Provenance is the authenticated provenance, valid when
// Outcome == OutcomeAdmitted.
Provenance Provenance
}
Result is the admission outcome. It carries admitted IDs and authenticated provenance only — never sampling flags, tracestate, baggage, or dispatch permission (FR-007, FR-008). Its zero value selects fallback and carries no admitted context or links.
func Admit ¶
Admit parses, verifies, and binds candidate envelope wire bytes, each decoded from its carrier with DecodeCarrier, against the expected identity and the configured eligible verification keys (active plus retained). Identical duplicate candidates are acceptable; any differing candidates reject. Keys are resolved only from the supplied trusted set. Admission is independent of dispatch authorization: this function never returns permission.
An unresolved expected identity reports ReasonUnresolved before any decoded candidate is inspected: the caller must postpone dispatch (FR-002) and must not read the candidate's own diagnostics as the cause.