Przejdź do treści

Whisper Trace v1

Source schema: doc/schemas/whisper-trace.v1.schema.json

Content-body contract for a bounded Whisper provenance statement about creating, dispatching, receiving, or holding an artifact. A trace is a signed assertion by the enclosing envelope author, not by itself proof of delivery, possession, or truth. The default disclosure is digest-only; inline bytes require an explicit consent reference and remain subject to stricter host policy and byte limits.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: whisper-trace.v1
trace/kind yes enum: artifact-created, artifact-dispatched, artifact-received, artifact-held The author's bounded assertion. artifact-dispatched means handed to an outbound transport, not delivered to the recipient. artifact-received and artifact-held remain claims unless strengthened by an independently verifiable evidence reference.
trace/occurred-at yes string Author-asserted event time. The enclosing signed record timestamp remains the publication time.
artifact yes ref: #/$defs/artifact
disclosure/mode yes enum: digest-only, digest-and-content Disclosure shape. digest-only minimizes transferred data but is not anonymous: a digest of predictable content may remain guessable and linkable. digest-and-content requires exact sender-host consent resolution and transient integrity validation.
disclosure/scope yes enum: private-correlation, federation-scoped, cross-federation, public Maximum disclosure surface for this trace. Public Agora deployments reject private-correlation; direct-only traces travel through AD/INAC.
consent/ref no ref: #/$defs/ref Opaque reference to the sender-side authorization or consent fact that permitted disclosure of inline content. Presence is not proof of valid consent; before publication the authoring host must resolve an active decision bound to the exact artifact digest, disclosure scope, represented subject or authority, and validity window.
causal/context no ref: causal-context.v1.schema.json Optional canonical causal context for the operation that produced this trace. Transport request ids and local sequence numbers do not belong here.
operation/ref no ref: #/$defs/ref
delivery/ref no ref: #/$defs/ref
evidence/refs no array Optional refs to receipts, attestations, or other independently verifiable facts. Their presence may strengthen the assertion but does not change this artifact into a receipt.
context/facets no array
routing/profile yes enum: direct, relayed, onion-relayed
routing/failure-mode yes enum: soft-fail, hard-fail
forwarding/max-hops yes integer
extensions no object Explicit extension namespace. Extensions may add advisory metadata but must not redefine trace kind, artifact identity, consent, disclosure, or routing semantics.

Definitions

Definition Shape Description
artifact object
ref string

Conditional Rules

Rule 1

When:

{
  "properties": {
    "disclosure/mode": {
      "const": "digest-and-content"
    }
  },
  "required": [
    "disclosure/mode"
  ]
}

Then:

{
  "required": [
    "consent/ref"
  ],
  "properties": {
    "artifact": {
      "required": [
        "bytes/base64"
      ],
      "properties": {
        "size/bytes": {
          "maximum": 32768
        }
      }
    }
  }
}

Rule 2

When:

{
  "properties": {
    "routing/profile": {
      "const": "onion-relayed"
    }
  },
  "required": [
    "routing/profile"
  ]
}

Then:

{
  "properties": {
    "forwarding/max-hops": {
      "minimum": 1
    }
  }
}

Rule 3

When:

{
  "properties": {
    "routing/profile": {
      "const": "direct"
    }
  },
  "required": [
    "routing/profile"
  ]
}

Then:

{
  "properties": {
    "forwarding/max-hops": {
      "const": 0
    }
  }
}

Rule 4

When:

{
  "properties": {
    "routing/failure-mode": {
      "const": "hard-fail"
    }
  },
  "required": [
    "routing/failure-mode"
  ]
}

Then:

{
  "properties": {
    "routing/profile": {
      "enum": [
        "relayed",
        "onion-relayed"
      ]
    }
  }
}

Field Semantics

schema

  • Required: yes
  • Shape: const: whisper-trace.v1

trace/kind

  • Required: yes
  • Shape: enum: artifact-created, artifact-dispatched, artifact-received, artifact-held

The author's bounded assertion. artifact-dispatched means handed to an outbound transport, not delivered to the recipient. artifact-received and artifact-held remain claims unless strengthened by an independently verifiable evidence reference.

trace/occurred-at

  • Required: yes
  • Shape: string

Author-asserted event time. The enclosing signed record timestamp remains the publication time.

artifact

  • Required: yes
  • Shape: ref: #/$defs/artifact

disclosure/mode

  • Required: yes
  • Shape: enum: digest-only, digest-and-content

Disclosure shape. digest-only minimizes transferred data but is not anonymous: a digest of predictable content may remain guessable and linkable. digest-and-content requires exact sender-host consent resolution and transient integrity validation.

disclosure/scope

  • Required: yes
  • Shape: enum: private-correlation, federation-scoped, cross-federation, public

Maximum disclosure surface for this trace. Public Agora deployments reject private-correlation; direct-only traces travel through AD/INAC.

consent/ref

  • Required: no
  • Shape: ref: #/$defs/ref

Opaque reference to the sender-side authorization or consent fact that permitted disclosure of inline content. Presence is not proof of valid consent; before publication the authoring host must resolve an active decision bound to the exact artifact digest, disclosure scope, represented subject or authority, and validity window.

causal/context

  • Required: no
  • Shape: ref: causal-context.v1.schema.json

Optional canonical causal context for the operation that produced this trace. Transport request ids and local sequence numbers do not belong here.

operation/ref

  • Required: no
  • Shape: ref: #/$defs/ref

delivery/ref

  • Required: no
  • Shape: ref: #/$defs/ref

evidence/refs

  • Required: no
  • Shape: array

Optional refs to receipts, attestations, or other independently verifiable facts. Their presence may strengthen the assertion but does not change this artifact into a receipt.

context/facets

  • Required: no
  • Shape: array

routing/profile

  • Required: yes
  • Shape: enum: direct, relayed, onion-relayed

routing/failure-mode

  • Required: yes
  • Shape: enum: soft-fail, hard-fail

forwarding/max-hops

  • Required: yes
  • Shape: integer

extensions

  • Required: no
  • Shape: object

Explicit extension namespace. Extensions may add advisory metadata but must not redefine trace kind, artifact identity, consent, disclosure, or routing semantics.

Definition Semantics

$defs.artifact

  • Shape: object

$defs.ref

  • Shape: string