Trace context v1

This normative specification defines the immutable identity, deterministic fallback, signed-envelope encoding, and admission contract adopted by ADR 0154. See the Trace Context Reference for Go API guidance and implementation scope. Carrier publication, key provisioning, and runtime integration are outside this contract.

Identity

Every forge entity is addressed by an immutable five-part tuple. Display names, entity URLs, GitHub numbers, GitLab IIDs, and Jira keys are not identity components.

Component	GitHub	GitLab	Jira
Installation	128-bit ID provisioned with the signing key pair	same	same
Forge instance	web base URL (https://github.com, or a GHES host)	web base URL (https://gitlab.com, or a self-hosted host)	site base URL
Container	repository id; for a PR, the base repository, never the fork	project id; for an MR, the target project, never the fork	project id
Entity kind	work_item (issue), change_proposal (PR)	work_item (issue), change_proposal (MR)	work_item (issue; Jira has no change proposal)
Entity	work_item: issue REST id; change_proposal: pull-request REST id = GraphQL fullDatabaseId (BigInt), never the issue-space ID	issue or MR database id (not the IID)	issue id

A GitHub PR has both a pull-request ID and a different issue-space ID. The change_proposal identity must use the pull-request ID from /repos/{owner}/{repo}/pulls/{number}, also exposed as GraphQL fullDatabaseId. A PR's /issues/{number} response and the issue object in an issue_comment event carry its issue-space ID, which must never be used for change_proposal identity. For a PR event carrying only that issue object, resolve the pull-request ID through a trusted forge-adapter /pulls/{number} read before declaring the identity resolved. Until that read succeeds, keep the identity unresolved rather than substituting the issue-space ID or display number.

The instance string is the normalized, trusted deployment base URL: lowercase scheme://host, using http or https, followed by the case-sensitive, URL-escaped deployment path prefix, with trailing slashes removed. For example, https://GitLab.example.com/gitlab/ becomes https://gitlab.example.com/gitlab; it is distinct from both the root installation and /GitLab. Path segments and existing escape spelling are preserved, never cleaned or decoded into separators. A path that mixes percent-escapes with characters that still need escaping, such as /a%2Fb/c d, rejects; write the fully escaped prefix (/a%2Fb/c%20d). Use the same configured deployment URL on every launch, rather than an entity or API URL.

Normalization fixes spelling only; it never resolves one name to another. An IP literal and its hostname, two DNS aliases of one host, and https://[::ffff:192.0.2.1] and https://192.0.2.1 are different instances.

Strip leading zeros from the port, keeping an all-zero port as :0 rather than treating it as the default, and reject ports above 65535. Then remove an empty port and the scheme's default port (443 for HTTPS, 80 for HTTP). For example, https://host: and https://host:0443 become https://host, and https://host:08443 becomes https://host:8443. Hosts must be ASCII: use the punycode form for internationalized domain names, and reject Unicode host spellings instead of converting them. For example, https://GitHub.com:443/ becomes https://github.com, and https://XN--BCHER-KVA.example becomes https://xn--bcher-kva.example. Bracketed IPv6 hosts follow the same port rules and take their RFC 5952 section 4 form, with IPv4-mapped addresses in mixed notation: https://[2001:DB8:0:0:0:0:0:1] becomes https://[2001:db8::1]. Zone identifiers reject (https://[FE80::1%25EN0]; use a routable address), so a normalized instance always re-normalizes to itself. Trailing DNS root dots are stripped: https://github.com. and https://github.com are one deployment with one fallback identity.

NormalizeInstance rejects queries, fragments, user info, missing hosts, invalid UTF-8 or NUL in the decoded path, and normalized URLs over 253 bytes (including the escaped prefix). Identity resolution, signing, and parsing require the already canonical value; they never silently rewrite an authenticated field. Prefixed deployments use the same v1 length-delimited instance field and fallback derivation with the full normalized instance bytes.

The installation ID is generated during key provisioning and identifies one install's key set. It is authenticated inside every envelope and must match the verifier's configured installation at admission. It is deliberately not part of fallback derivation, so entities keep stable traces regardless of key state.

Rename and move rules

• Renames (issue titles, repository names, Jira project keys) never change identity: the container and entity components are database IDs.
• A container transfer that keeps the container's database ID keeps identity; one that changes the database ID is a new binding.
• An entity moved between containers (a GitHub issue transfer, a Jira project move) has a new binding — a different container or entity ID — and therefore a new identity. A previously published envelope fails the binding check and the moved entity falls back. A move is never treated as a rename.
• Changing the configured deployment URL (a Jira site rename, a GHES hostname change, a GitLab external_url change) is also a new binding: published envelopes fail the binding check and entities fall back.

Fallback derivation (v1)

When the identity is resolved and no admissible stored context exists, the entity's context is derived deterministically. An unresolved identity gets no derived context; dispatch is postponed instead (see Admission). The derivation is:

• Input: the forge instance, container, kind, and entity — never the installation.
• SHA-256 over the exact concatenation below. Only strings are length-prefixed; all integers are big-endian: uint16(33) || "fullsend.tracecontext.identity.v1" || uint16(N) || instance[N] || uint64(container) || byte(kind) || uint64(entity). N counts UTF-8 bytes, container/entity are in [1, 2^63−1], and kind is 0x01 (work item) or 0x02 (change proposal).
• TraceID = the first 16 digest bytes; the anchor SpanID = the next 8.
• An all-zero result (probability 2⁻¹²⁸ for the trace, 2⁻⁶⁴ for the span) replaces only that ID's final byte with 0x01, so derived IDs are valid.

The derivation is pure, so independent launches and concurrent first events converge on identical nonzero IDs without shared state. The anchor SpanID is a synthetic parent reference by protocol choice: no exported span carries the anchor ID, the anchor is never repointed, and operation spans keep distinct SDK-generated IDs. OpenTelemetry supports custom ID generators (WithIDGenerator); this contract deliberately uses an unexported anchor rather than creating a real root span with that ID.

For https://github.com, container 274390431, kind 0x01, and entity 2468913570, the exact input is:

002166756c6c73656e642e7472616365636f6e746578742e6964656e746974792e7631
001268747470733a2f2f6769746875622e636f6d00000000105add9f01000000009328a1a2

Concatenate those hex lines before hashing. The TraceID is c9bdb0e38247ebbe2e0f1039250c32d4; the anchor is 892a346c55356aca. Additional independent GitLab/Jira vectors and an SDK exporter lifecycle test are linked from the implementation reference.

Signed envelope (wire format v1)

One fixed-layout binary encoding serves both message domains; all integers are big-endian, and the Ed25519 signature covers every byte from the magic through the nonce — there are no unsigned fields.

Offset	Size	Field	Constraints
0	4	Magic FSTC	exact bytes
4	1	Version	0x01; anything else rejects
5	1	Message domain	0x01 bound envelope, 0x02 pending marker
6	8	Key ID	first 8 bytes of SHA-256(public key)
14	16	Installation ID	nonzero
30	2	Instance length N	1 ≤ N ≤ 253
32	N	Forge instance	normalized form, UTF-8, no NUL
32+N	8	Container ID	int64 ≥ 1
40+N	1	Entity kind	0x01 work item, 0x02 change proposal
41+N	8	Entity ID	int64 ≥ 1; bound envelopes only — pending markers omit these 8 bytes, retaining the kind byte
·	16	Trace ID	nonzero
·	8	Parent/anchor Span ID	nonzero
·	1	Provenance kind	0x00 none, 0x01 source link, 0x02 scenario
·	0/24/32	Provenance fields	none; source link = 16B source TraceID + 8B source SpanID; scenario = 16B scenario TraceID + 16B invocation ID; every ID nonzero
·	16	Nonce	nonzero (checked); signers draw it from crypto/rand, unique per creation intent (not checked at admission)
end−64	64	Ed25519 signature	over bytes [0, end−64)

The maximum legal size is 439 bytes (bound envelope, scenario provenance, 253-byte instance); carriers hold the envelope as unwrapped standard base64 (≤ 588 characters, no line breaks).

Strict parsing rules:

• The total length must equal the exact structural length for the parsed domain and provenance kind; trailing bytes reject.
• Duplicate and unknown fields are structurally impossible in the fixed layout.
• Every enumerated byte and ID must satisfy its constraint; invalid values reject rather than degrade.
• Unknown versions reject — never a partial parse.
• Identical duplicate carriers are acceptable (idempotent publication); any differing carriers reject — never first-match.

Domains, keys, and nonces

The domain byte is covered by the signature, so a pending marker cannot be replayed as a bound envelope and vice versa. A pending marker carries the creation's intended context and provenance as signed intent, omits the entity ID (the destination does not exist yet), and grants neither context, parent, nor source link. The nonce links a pending marker to the bound envelope published after creation; admission never depends on having seen the marker.

The key selector resolves only against the verifier's configured eligible keys (active plus retained). Envelopes never carry public keys or key locations, and metadata can never select a signer or a remote key URL. After rotation, metadata signed by an older retained key remains verifiable while new metadata uses the active key. Missing or malformed-length verification keys yield unknown-key fallback without context or provenance; they never reach Ed25519 verification.

Provenance consistency

• Source-link provenance (ordinary created work) requires the envelope TraceID to differ from the source TraceID: the destination keeps its own trace and the source context is a link, never a parent.
• Scenario provenance (behaviour-test work) requires the envelope TraceID to equal the scenario TraceID: descendants inherit the scenario trace with distinct operation spans.

Admission

Admit(expected Identity, keys, candidates...) is the pure decision operation. It takes the trusted expected binding, the configured eligible verification keys, and bounded candidate envelope bytes, each decoded from its carrier with DecodeCarrier, and returns exactly one outcome:

• Admitted: a verified bound envelope matched every binding component. The result carries the admitted TraceID, parent SpanID, and authenticated provenance.
• Pending: a verified pending marker matched the expected scope — installation, instance, container, and kind, never the entity, because a pending marker carries no entity binding by design. A marker replayed onto another entity in the same container still grants nothing beyond a bounded wait. It grants no context; callers must bound that wait by a window from the entity's trusted creation metadata (for example created_at) before rereading and falling back, per ADR 0154.
• Fallback: nothing was admissible. The caller uses the entity-derived fallback, except for reason unresolved, where it postpones dispatch (see below).

The zero-value result selects fallback and grants no context or provenance.

Fallback reason codes are redacted diagnostics — absent, malformed, oversized, unknown-version, unknown-key, bad-signature, binding-mismatch, conflicting-carrier, provenance, unresolved — never key material or raw bytes. A plain W3C traceparent is never an envelope.

Any differing extra candidate, whether junk or a second envelope, deliberately forces fallback even when one candidate alone would admit; identical duplicates do not. An actor who can edit the body can deny continuity by appending junk or deleting the carrier, but can never forge or inject a context: only an envelope the installation signed for this entity admits. Admission has no freshness check, so an older valid envelope for the same entity still admits. Rejection is deliberately fail-closed so a forged carrier is reported rather than silently ignored. Publishing a bound envelope must remove the pending marker it replaces; leaving both present produces conflicting carriers and fallback, never a pick between them.

The result structurally cannot carry sampling flags, tracestate, baggage, or dispatch permission. Trace admission and dispatch authorization are independent decisions; a denied actor never dispatches regardless of admission, and an admitted envelope never authorizes anything.

An unresolved identity (a missing or invalid instance, container, kind, or entity, including a non-canonical instance) is explicit: admission returns fallback with reason unresolved before inspecting any candidate, and callers must postpone dispatch with diagnostics rather than derive a fallback or guess.

Compatibility

The conformance vectors pin the exact signed bytes of one envelope per domain and provenance kind.

v1 is provisional until the first pull request that publishes carriers merges. No production carrier exists yet, so the wire layout, derivation, and key-selector rules may still change without a new version byte while contract gaps surface in review. From the first carrier-publishing pull request onward, any such change is a compatibility break that requires a new version byte and a reviewed migration path. Unknown versions must reject cleanly.