Documentation
¶
Overview ¶
Package emit builds format-4 Agent Action Capsules and independent Producer Envelopes from values observed at an external-effect boundary. DigestJSON produces the request and response digests stored in Effect.
The package does not execute actions, generate business operation IDs, retry calls, persist Capsules, authorize signers, or maintain a ledger.
Index ¶
- Constants
- Variables
- func DecodePayload(payload []byte) (map[string]any, error)
- func DigestJSON(value any) (string, error)
- func IsV4IrreversibilityClass(value IrreversibilityClass) bool
- func Sign(built BuiltPayload, identity SigningIdentity) ([]byte, error)
- func VerifyCapsule(data []byte) (verify.VerificationResult, error)
- func VerifyEnvelope(capsuleID string, data []byte) (upstreamenvelope.VerificationResult, error)
- type ActionType
- type Approver
- type AttestationMode
- type BuiltPayload
- type Chain
- type ChainRelation
- type Class1Error
- type ComputeAttestation
- type Decision
- type Disposition
- type Domain
- type Effect
- type EffectAttestation
- type EffectMode
- type EffectStatus
- type Input
- type IrreversibilityClass
- type LedgerMode
- type Model
- type Provenance
- type ProvenanceMode
- type ProvenanceModeValue
- type Reference
- type Result
- type SealInput
- type SigningIdentity
- type SlotMember
- type TimeRung
- type VerdictClass
Constants ¶
const ( // SpecVersion is the spec_version every Capsule this package builds // carries: a producer conforming to draft -05 emits -05. It mirrors // agent-action-capsule/go verify.CurrentSpecVersion. SpecVersion = "draft-mih-scitt-agent-action-capsule-05" // FormatVersion is the AAC serialization-suite version. FormatVersion = "4" // CanonicalizationID is the only profile emitted for format-4 Capsules. CanonicalizationID = "jcs" // ContentType is the Producer Envelope payload media type. ContentType = "application/agent-action-capsule-id" )
const ( EffectModeNotApplicable EffectMode = "not_applicable" EffectModeDispatchedUnconfirmed EffectMode = "dispatched_unconfirmed" EffectModeConfirmed EffectMode = "confirmed" AttestationModeSelfAttested AttestationMode = "self_attested" AttestationModeAnchored AttestationMode = "anchored" LedgerModeStandalone LedgerMode = "standalone" LedgerModeChained LedgerMode = "chained" LedgerModeAnchored LedgerMode = "anchored" )
Variables ¶
var AcceptedSpecVersions = []string{ "draft-mih-scitt-agent-action-capsule-04", SpecVersion, }
AcceptedSpecVersions are the spec_version values a verifier MUST accept: the draft revisions that define format 4. It mirrors agent-action-capsule/go verify.AcceptedSpecVersions and is informational only: spec_version selects no digest or verification algorithm, and an unrecognized value is never by itself a reason to reject, so VerifyCapsule never branches on it.
Functions ¶
func DecodePayload ¶
DecodePayload decodes payload bytes with json.Number preservation and JCS negative-zero normalization.
func DigestJSON ¶
DigestJSON marshals value as JSON and returns its AAC JSON-DIGEST: lowercase hexadecimal SHA-256 over RFC 8785 JCS. It accepts ordinary JSON-tagged Go values and types with custom MarshalJSON methods using encoding/json v2 semantics. It rejects invalid UTF-8, invalid surrogate pairs, duplicate object names, excessive depth, floats, and integers outside the interoperable JSON safe range. Negative zero is canonicalized to zero as required by RFC 8785.
func IsV4IrreversibilityClass ¶
func IsV4IrreversibilityClass(value IrreversibilityClass) bool
IsV4IrreversibilityClass reports whether value is seeded by AAC v4.
func Sign ¶
func Sign(built BuiltPayload, identity SigningIdentity) ([]byte, error)
Sign creates one Producer Envelope over an already-built Capsule ID.
func VerifyCapsule ¶
func VerifyCapsule(data []byte) (verify.VerificationResult, error)
VerifyCapsule decodes a format-4 Capsule and performs Class 1 verification. Local-only signature and key_id fields are neither committed by the Capsule ID nor authenticated here. Verify the decoded signature with VerifyEnvelope, and bind any carried key_id to that result's PublicKey before trusting it.
func VerifyEnvelope ¶
func VerifyEnvelope(capsuleID string, data []byte) (upstreamenvelope.VerificationResult, error)
VerifyEnvelope authenticates one Producer Envelope against a Capsule ID. The public key in result is evidence, not an authorization decision.
Types ¶
type ActionType ¶
type ActionType string
ActionType states whether the Capsule is informational or records a decision.
const ( ActionTypeFYI ActionType = "fyi" ActionTypeDecide ActionType = "decide" )
type Approver ¶
type Approver string
Approver identifies who disposed the action. Unlike registry-backed values, AAC defines this as a closed enumeration.
type AttestationMode ¶
type AttestationMode string
AttestationMode is the producer or transparency attestation tier.
type BuiltPayload ¶
BuiltPayload is a validated signature-free format-4 Capsule.
func Build ¶
func Build(input Input) (BuiltPayload, error)
Build validates input, derives assurance, computes capsule_id with the upstream AAC implementation, and returns deterministic JCS payload bytes.
func BuildComposition ¶
func BuildComposition(input Input, members ...SlotMember) (BuiltPayload, error)
BuildComposition builds a Capsule that binds existing signature-free Capsules into WHO, CAN, DID, and AUDIT roles. It emits members in canonical slot order regardless of argument order and asserts no new facts about the members' contents or signers.
type Chain ¶
type Chain struct {
ParentCapsuleID string
Relation ChainRelation
}
Chain links a format-4 Capsule to one parent Capsule.
type ChainRelation ¶
type ChainRelation string
ChainRelation states how a Capsule relates to its parent. The registry is extensible.
const ( // ChainConfirms links a later Capsule confirming its parent. ChainConfirms ChainRelation = "confirms" ChainSupersedes ChainRelation = "supersedes" ChainEpochOpens ChainRelation = "epoch_opens" // ChainDuplicates links a backfilled Capsule to the contemporaneous twin // it duplicates (draft -05 §5.3(bis)); verifiers count the pair once, // the contemporaneous parent governing. ChainDuplicates ChainRelation = "duplicates" )
type Class1Error ¶
Class1Error reports structured AAC Class 1 findings.
func (*Class1Error) Error ¶
func (e *Class1Error) Error() string
Error returns a stable rendering of Class 1 findings.
type ComputeAttestation ¶
ComputeAttestation binds the model invocation to its input, output, and runtime. Digests are AAC JSON-DIGEST values produced by DigestJSON.
type Decision ¶
type Decision string
Decision records how an action was disposed. The registry is extensible; these constants are the values seeded by AAC format 4.
type Disposition ¶
type Disposition struct {
Decision Decision
Approver Approver
HumanDisposed bool
VerdictClass VerdictClass
ReasonDigest string
}
Disposition records how a decision was disposed.
type Domain ¶
type Domain string
Domain describes the epistemic role of the recorded action. The registry is extensible.
type Effect ¶
type Effect struct {
Type string
Status EffectStatus
IrreversibilityClass IrreversibilityClass
EffectAttestation EffectAttestation
RequestDigest string
ResponseDigest string
ExternalRef string
}
Effect describes an external side effect and binds request and response JSON by digest.
type EffectAttestation ¶
type EffectAttestation string
EffectAttestation states who vouches for execution. The registry is extensible.
const ( AttestationGateExecuted EffectAttestation = "gate_executed" AttestationRuntimeClaimed EffectAttestation = "runtime_claimed" )
type EffectStatus ¶
type EffectStatus string
EffectStatus states how far an external effect progressed.
const ( EffectPlanned EffectStatus = "planned" EffectDispatched EffectStatus = "dispatched" EffectConfirmed EffectStatus = "confirmed" EffectFailed EffectStatus = "failed" EffectReverted EffectStatus = "reverted" )
type Input ¶
type Input struct {
ActionID string
ActionType ActionType
Operator string
Developer string
Timestamp time.Time
EpochID string
Domain Domain
Provenance Provenance
Disposition *Disposition
Effect *Effect
Chain *Chain
References []Reference
Model *Model
Compute *ComputeAttestation
ProvenanceMode *ProvenanceMode
// contains filtered or unexported fields
}
Input contains the application-owned values needed to build one Capsule. ActionID and Timestamp are supplied explicitly so the library never invents business identity or wall-clock semantics. Timestamp is normalized to microsecond precision, matching capsule-emit's UTC datetime wire form.
type IrreversibilityClass ¶
type IrreversibilityClass string
IrreversibilityClass orders effects by consequence. The registry is extensible.
const ( IrreversibilityTwoWay IrreversibilityClass = "two_way" IrreversibilityOneWayRecoverable IrreversibilityClass = "one_way_recoverable" IrreversibilityOneWayConsequential IrreversibilityClass = "one_way_consequential" IrreversibilityOneWayTerminal IrreversibilityClass = "one_way_terminal" )
type LedgerMode ¶
type LedgerMode string
LedgerMode is the custody tier derived from chain and receipt evidence.
type Model ¶
Model identifies the provider and model that performed the recorded work. Either field may be omitted when the application did not observe it.
type Provenance ¶
type Provenance string
Provenance identifies the producer tier. The registry is extensible.
const ( ProvenanceGate Provenance = "gate" ProvenanceRuntime Provenance = "runtime" ProvenanceCollector Provenance = "collector" )
type ProvenanceMode ¶
type ProvenanceMode struct {
Mode ProvenanceModeValue
SourceRef *Reference
SourceAssertedAt string
ImportBatch string
ImportedAt string
TimeRung TimeRung
}
ProvenanceMode marks a Capsule as a backfilled import of a pre-existing external event, rather than a contemporaneous observation (draft -05 §5.3(bis), a MODE on the ordinary Capsule -- never a distinct record type, and a different key from the unrelated Input.Provenance dedup-rank signal above). Mode "backfilled" REQUIRES the four companion fields; TimeRung is meaningful only when Mode is "backfilled".
type ProvenanceModeValue ¶
type ProvenanceModeValue string
ProvenanceModeValue states whether a Capsule is a contemporaneous observation or a backfilled import (draft -05 §5.3(bis)). A closed enumeration, unlike the registry-backed value types above.
const ( ProvenanceModeContemporaneous ProvenanceModeValue = "contemporaneous" ProvenanceModeBackfilled ProvenanceModeValue = "backfilled" )
type Reference ¶
type Reference struct {
Type string
DigestAlg string
Digest string
CitationPurpose string
LogCoordinates map[string]any
}
Reference cites an external artifact under its own CPB digest context (draft-04 §5.5.5). Digest representation is defined by Type, not by AAC. LogCoordinates, when present, carries log_id, leaf_index and inclusion_proof as an opaque recorded claim. The producer does not verify that proof.
type SealInput ¶
type SealInput struct {
Capsule Input
Payload any
AgentOutput any
Model *Model
Runtime string
Members []SlotMember
Identity SigningIdentity
}
SealInput is the application-facing one-call producer API. For a regular Capsule, non-nil Payload is digest-committed as agent_input_digest and non-nil AgentOutput is digest-committed as agent_output_digest. Nil includes typed nil pointer, map, and slice values. Use a non-nil json.RawMessage("null") to commit explicit JSON null. For a composition, set Members to values returned by Who, Can, Did, or Audit; Payload and AgentOutput must then be nil.
type SigningIdentity ¶
type SigningIdentity struct {
// contains filtered or unexported fields
}
SigningIdentity is an immutable signer and matching raw Ed25519 public key. Keeping the pair together prevents rotation between header construction and signature creation.
func NewEd25519SigningIdentity ¶
func NewEd25519SigningIdentity(privateKey ed25519.PrivateKey) (SigningIdentity, error)
NewEd25519SigningIdentity constructs a local Ed25519 signing identity.
func NewSigningIdentity ¶
NewSigningIdentity binds an EdDSA signer from a KMS or HSM to its raw Ed25519 public key for one immutable Producer Envelope identity.
type SlotMember ¶
type SlotMember struct {
// contains filtered or unexported fields
}
SlotMember binds an existing built or sealed Capsule to one composition role. Valid values come from Who, Can, Did, or Audit; its zero value is rejected.
func Audit ¶
func Audit[T compositionMember](member T) SlotMember
Audit assigns an existing built or sealed Capsule to the independent-review slot.
func Can ¶
func Can[T compositionMember](member T) SlotMember
Can assigns an existing built or sealed Capsule to the authority or mandate slot.
func Did ¶
func Did[T compositionMember](member T) SlotMember
Did assigns an existing built or sealed Capsule to the performed-action slot.
func Who ¶
func Who[T compositionMember](member T) SlotMember
Who assigns an existing built or sealed Capsule to the identity or pedigree slot.
type TimeRung ¶
type TimeRung string
TimeRung caps the occurrence-time claim a backfilled Capsule may make (draft -05 §5.3(bis)). A closed enumeration.
type VerdictClass ¶
type VerdictClass string
VerdictClass classifies the terminal or open verdict. The registry is extensible.
const ( VerdictExecuted VerdictClass = "executed" VerdictBlocked VerdictClass = "blocked" VerdictHITLDispatched VerdictClass = "hitl_dispatched" VerdictDenied VerdictClass = "denied" VerdictTimeout VerdictClass = "timeout" VerdictErrored VerdictClass = "errored" VerdictEngineFailure VerdictClass = "engine_failure" VerdictDeferred VerdictClass = "deferred" VerdictNeedsDecision VerdictClass = "needs_decision" VerdictExpired VerdictClass = "expired" VerdictEscalated VerdictClass = "escalated" VerdictResolved VerdictClass = "resolved" VerdictEpochBoundary VerdictClass = "epoch_boundary" )
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package artifact persists exact sealed Capsules, Producer Envelopes, and associated business originals.
|
Package artifact persists exact sealed Capsules, Producer Envelopes, and associated business originals. |
|
internal/testutil
Package testutil provides synthetic, locally signed artifact test fixtures.
|
Package testutil provides synthetic, locally signed artifact test fixtures. |
|
jsonl
Package jsonl implements the artifact Store on a flat JSONL file.
|
Package jsonl implements the artifact Store on a flat JSONL file. |
|
mysql
Package mysql implements the artifact Store on MySQL 8.4/InnoDB.
|
Package mysql implements the artifact Store on MySQL 8.4/InnoDB. |
|
sqlite
Package sqlite implements the artifact Store on SQLite (modernc, pure Go).
|
Package sqlite implements the artifact Store on SQLite (modernc, pure Go). |