emit

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 27, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

README

capsule-emit-go

Go emission core for Agent Action Capsule format 4. The library builds deterministic, signature-free Capsules and creates independent COSE_Sign1 Producer Envelopes over their raw 32-byte Capsule IDs.

The Go API keeps persistence explicit: Seal builds and signs but does not append to a CLL or contact a witness. Applications that need ordered persistence and witnessed checkpoints compose it with cll-go.

It supports format 4 only. There is no legacy Create or signed-payload statement API, and verification rejects formats 2 and 3.

Every Capsule it builds carries spec_version draft-mih-scitt-agent-action-capsule-05 (emit.SpecVersion). VerifyCapsule accepts the revisions that define format 4, -04 and -05 (emit.AcceptedSpecVersions), and never rejects a Capsule for its spec_version alone: the value selects no algorithm, and an unrecognized one is not a rejection. Released -04 records keep verifying.

Install

Requires Go 1.27 or newer. DigestJSON uses encoding/json/v2.

go get github.com/action-state-group/capsule-emit-go

Build, sign, and verify

package main

import (
	"bytes"
	"crypto/ed25519"
	"crypto/rand"
	"fmt"
	"log"
	"time"

	"github.com/action-state-group/capsule-emit-go"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	publicKey, privateKey, err := ed25519.GenerateKey(rand.Reader)
	if err != nil {
		return err
	}
	identity, err := emit.NewEd25519SigningIdentity(privateKey)
	if err != nil {
		return err
	}

	input := emit.Input{
		ActionID:   "send-018f6f4d",
		ActionType: emit.ActionTypeDecide,
		Operator:   "local-operator",
		Developer:  "example-agent@1.0.0",
		Timestamp:  time.Now(),
		Disposition: &emit.Disposition{
			Decision:      emit.DecisionAccept,
			Approver:      emit.ApproverPolicy,
			VerdictClass:  emit.VerdictExecuted,
			HumanDisposed: false,
		},
	}

	result, err := emit.Seal(emit.SealInput{
		Capsule: input,
		Payload: map[string]any{
			"channel": "C123",
			"text":    "hello",
		},
		AgentOutput: map[string]any{"message_id": "M456"},
		Model: &emit.Model{
			Provider: "anthropic",
			ModelID:  "claude-sonnet-4-6",
		},
		Runtime:  "example-runtime",
		Identity: identity,
	})
	if err != nil {
		return err
	}
	class1, err := emit.VerifyCapsule(result.Payload)
	if err != nil || !class1.OK {
		return err
	}
	authenticated, err := emit.VerifyEnvelope(result.CapsuleID, result.Envelope)
	if err != nil {
		return err
	}
	if !bytes.Equal(authenticated.PublicKey, publicKey) {
		return fmt.Errorf("Producer Envelope signer is not authorized")
	}
	return nil
}

Production code must handle every error. VerifyCapsule validates Capsule identity and structure; embedded local-only signature and key_id fields are not authenticated by it. VerifyEnvelope authenticates the public key carried in the envelope. A consumer of a stored Capsule must also compare that result's PublicKey with the outer key_id before trusting the outer field. Whether the authenticated key is authorized for an operator, developer, or action remains caller policy.

Multiple signers call Sign independently with the same BuiltPayload. Envelope order and signer count do not change the Capsule or its ID.

Seal is the recommended application-facing API. It computes agent_input_digest from non-nil Payload, computes agent_output_digest when AgentOutput is present, maps provider and model ID into model_attestation, maps runtime into compute_attestation, then delegates to Build and Sign. A nil payload, including a typed nil pointer, map, or slice, is absent; use a non-nil json.RawMessage("null") to commit explicit JSON null. Raw payload values never enter the Capsule.

DigestJSON, Build, BuildComposition, and Sign remain public stable primitives for applications that need to control projections, commitments, construction, or signing separately. Effect request and response digests stay caller-owned; Seal does not replace them with the general agent digests.

AAC drafts -04 and -05 define only fyi and decide as conformant action_type values. The package rejects other values so every Build result continues to pass the current AAC Class 1 verifier.

Optional artifact storage

artifact defines originals, digest bindings, and verification. Three peer backends provide the same core New/Init/Put/Get/Purge contract (each is a concrete *Store type, not a shared Go interface): artifact/mysql (MySQL 8.4/InnoDB) and artifact/sqlite (modernc, pure-Go, single file) add transactional PutTx/GetTx; artifact/jsonl (a flat JSONL file, single writer, no database driver) does not. The root emit package remains storage-free and imports no storage driver; an application links only the backend it selects. See artifact storage for initialization, limits, trusted-key policy, retention, and tests. Application workflow state remains caller-owned.

Persist and append to CLL

capsule-emit-go and cll-go do not depend on each other. An application may import both and connect them through their public APIs. Keep the complete Capsule and Producer Envelope in application-owned storage; CLL stores only the decoded 32-byte Capsule ID.

package integration

import (
	"bytes"
	"context"
	"crypto/ed25519"
	"encoding/hex"
	"fmt"
	"time"

	emit "github.com/action-state-group/capsule-emit-go"
	"github.com/action-state-group/cll-go/cll"
)

// CapsuleStore is application-owned persistence. Its schema and transaction
// model can be adapted to the optional artifact/mysql backend.
type CapsuleStore interface {
	PutCapsule(
		ctx context.Context,
		capsuleID string,
		capsule []byte,
		envelope []byte,
	) error
}

func PersistAndAppend(
	ctx context.Context,
	records CapsuleStore,
	log cll.EntryStore,
	result emit.Result,
	producerPublicKey ed25519.PublicKey,
	observedAt time.Time,
) (cll.AppendResult, error) {
	verified, err := emit.VerifyCapsule(result.Payload)
	if err != nil {
		return cll.AppendResult{}, fmt.Errorf("verify Capsule: %w", err)
	}
	if verified.CapsuleID == nil || *verified.CapsuleID != result.CapsuleID {
		return cll.AppendResult{}, fmt.Errorf("Capsule ID mismatch")
	}
	authenticated, err := emit.VerifyEnvelope(result.CapsuleID, result.Envelope)
	if err != nil {
		return cll.AppendResult{}, err
	}
	if !bytes.Equal(authenticated.PublicKey, producerPublicKey) {
		return cll.AppendResult{}, fmt.Errorf("Producer Envelope signer is not authorized")
	}

	identity, err := hex.DecodeString(result.CapsuleID)
	if err != nil || len(identity) != cll.EntryBytes ||
		hex.EncodeToString(identity) != result.CapsuleID {
		return cll.AppendResult{}, fmt.Errorf("invalid Capsule ID")
	}

	// Persist exact business evidence before publishing its identity to CLL.
	if err := records.PutCapsule(
		ctx,
		result.CapsuleID,
		result.Payload,
		result.Envelope,
	); err != nil {
		return cll.AppendResult{}, err
	}

	return log.Append(ctx, cll.AppendInput{
		Value:      identity,
		AppendedAt: observedAt,
	})
}

If application persistence succeeds but the CLL append fails, retry the append with the same identity. CLL append is idempotent and returns the original entry and timestamp. The application decides how to make that retry durable, for example with its own outbox.

Pass any cll.EntryStore implementation to this function. Backend selection, checkpointing, and witness delivery remain entirely in cll-go; see its backend documentation.

Typed construction

Carry binds exact opaque bytes as a generic foreign-artifact. Received does the same with a non-empty caller-declared CPB type. Both record the raw SHA-256 digest as carried_artifact.digest and carried_input_digest; they never reinterpret foreign bytes as JSON.

Who, Can, Did, and Audit assign existing BuiltPayload values or high-level Seal results to the four format-4 composition roles. BuildComposition writes references in the canonical WHO, CAN, DID, AUDIT order regardless of argument order. It rejects empty membership, duplicate slots, duplicate Capsule IDs, and members whose stored bytes do not verify against their claimed IDs.

// Illustrative: inputs and identity are caller-owned; run inside an error-returning function.
identityCapsule, err := emit.Build(identityInput)
if err != nil {
	return err
}
carried, err := emit.Received(input, artifactBytes, "provider-ack")
if err != nil {
	return err
}
actionCapsule, err := emit.Build(actionInput)
if err != nil {
	return err
}
composed, err := emit.BuildComposition(
    input,
    emit.Who(identityCapsule),
    emit.Can(carried),
    emit.Did(actionCapsule),
)
if err != nil {
	return err
}
envelope, err := emit.Sign(composed, identity)
if err != nil {
	return err
}

The same DID composition can use the high-level signing path:

result, err := emit.Seal(emit.SealInput{
	Capsule:  input,
	Members:  []emit.SlotMember{emit.Did(actionCapsule)},
	Identity: identity,
})
if err != nil {
	return err
}

Slot helpers reference existing Capsules unchanged. They do not mint or persist member Capsules.

Received and BuildComposition may carry provider, model, and runtime metadata, but reject explicit agent input or output digests. Carried bytes and slot members already own those construction commitments; mixing authored payload digests into the same record would make provenance ambiguous.

These functions build records only. They do not append logs, persist Capsules, deliver checkpoints, retry effects, or authorize signers.

JSON digests

DigestJSON accepts any JSON-marshalable value and returns its AAC JSON-DIGEST: lowercase hexadecimal SHA-256 over RFC 8785 JCS. It rejects duplicate object names, excessive depth, floats, and integers outside the interoperable JSON safe range. Marshaling follows Go encoding/json/v2 semantics, including strict UTF-8 and Unicode surrogate validation. Represent fractional quantities as strings or integers in their smallest unit. When another encoder produces the transmitted bytes, digest the decoded wire JSON value rather than assuming its output matches encoding/json/v2.

// Illustrative: request and response are caller-owned values.
requestDigest, err := emit.DigestJSON(request)
if err != nil {
	return err
}
responseDigest, err := emit.DigestJSON(response)
if err != nil {
	return err
}

Callers own the JSON shape. The producer does not impose a transport-specific wrapper around the values being digested. Assign the results to Effect.RequestDigest and Effect.ResponseDigest on an Effect whose type, status, irreversibility class, and attestation are populated by the caller.

All business IDs and timestamps are caller supplied. Assurance fields are derived from the supplied effect and chain values. A format-4 Capsule declares canonicalization_id: "jcs"; its Capsule ID commits every field except top-level capsule_id and local-only Producer Envelope fields signature and key_id. The chain field remains committed.

Cross-record references

Input.References adds AAC external citations to the committed payload. Use Reference{Type: "agent-action-capsule", DigestAlg: "SHA-256", Digest: id, CitationPurpose: "responds_to"} to cite another AAC record. acted_on is also seeded; additional purposes remain informational. References must not duplicate the Capsule's own chain parent. Foreign artifact types retain their own digest representation, and their content is not resolved by this producer.

Optional LogCoordinates is caller-owned JSON containing log_id, leaf_index and inclusion_proof. All three are recorded claims; Class 1 does not verify the proof. A nil References slice omits the field; an empty slice emits []. Those forms have different format-4 IDs because JCS preserves the distinction.

package main

import (
	"fmt"
	"time"

	emit "github.com/action-state-group/capsule-emit-go"
)

func main() {
	if err := run(); err != nil {
		panic(err)
	}
}

func run() error {
	input := emit.Input{
		ActionID: "request/1", ActionType: emit.ActionTypeFYI,
		Operator: "example-org", Developer: "example-agent@v1",
		Timestamp: time.Date(2026, 9, 2, 12, 0, 0, 0, time.UTC),
	}
	request, err := emit.Build(input)
	if err != nil {
		return err
	}
	input.ActionID = "response/1"
	input.References = []emit.Reference{{
		Type: "agent-action-capsule", DigestAlg: "SHA-256",
		Digest: request.CapsuleID, CitationPurpose: "responds_to",
	}}
	response, err := emit.Build(input)
	if err != nil {
		return err
	}
	if _, err := emit.VerifyCapsule(response.JSON); err != nil {
		return err
	}
	fmt.Println(request.CapsuleID, response.CapsuleID)
	return nil
}

The reference enters through Input, including SealInput.Capsule when using Seal. There is no separate reference builder or closed purpose enum.

Development

DigestJSON keeps JCS negative-zero normalization. Python's optional strict raw-input verification tier is a separate API, not a new Capsule-ID algorithm.

go fmt ./...
go mod tidy
go vet ./...
go test ./...
go test -race ./...
scripts/check-coverage.sh 90.0

scripts/check-producer-cll-interop.sh exercises both producers through both Go/TypeScript CLL append and checkpoint runners, then verifies every checkpoint with Python. It uses a temporary module so CLL is not a production dependency. Build the sibling capsule-emit-ts and cll-ts packages first, and use a Python environment with checkpointed-local-log installed. PYTHON selects its interpreter; sibling locations can be set through AAC_REPO, CAPSULE_EMIT_TS_ROOT, CLL_GO_ROOT and CLL_TS_ROOT. This is an in-memory, offline integration check, not a witness-delivery or durable-storage recovery test.

Emission-core non-goals

  • Executing or retrying provider actions
  • Generating business IDs or timestamps
  • Persistence, journals, local logs, or transparency receipts
  • Signer authorization policy
  • Workflow-engine or provider-specific business semantics

License

Apache-2.0. The upstream Agent Action Capsule Go dependency is BSD-3-Clause.

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

View Source
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"
)
View Source
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

View Source
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

func DecodePayload(payload []byte) (map[string]any, error)

DecodePayload decodes payload bytes with json.Number preservation and JCS negative-zero normalization.

func DigestJSON

func DigestJSON(value any) (string, error)

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.

const (
	ApproverHuman        Approver = "human"
	ApproverPolicy       Approver = "policy"
	ApproverCounterparty Approver = "counterparty"
)

type AttestationMode

type AttestationMode string

AttestationMode is the producer or transparency attestation tier.

type BuiltPayload

type BuiltPayload struct {
	CapsuleID string
	Value     map[string]any
	JSON      []byte
}

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.

func Carry

func Carry(input Input, artifact []byte) (BuiltPayload, error)

Carry builds a Capsule that binds an opaque foreign artifact exactly as received, without reinterpreting or canonicalizing its bytes.

func Received

func Received(input Input, artifact []byte, artifactType string) (BuiltPayload, error)

Received builds a Capsule that binds an opaque foreign artifact and its caller-declared registered CPB type.

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

type Class1Error struct {
	Findings []verify.Finding
}

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

type ComputeAttestation struct {
	AgentInputDigest  string
	AgentOutputDigest string
	Runtime           string
}

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.

const (
	DecisionAccept     Decision = "accept"
	DecisionReject     Decision = "reject"
	DecisionNeedsInput Decision = "needs_input"
	DecisionDeferred   Decision = "deferred"
)

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.

const (
	DomainAction    Domain = "action"
	DomainMemory    Domain = "memory"
	DomainReasoning Domain = "reasoning"
)

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 EffectMode

type EffectMode string

EffectMode is the effect assurance derived from an Effect.

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

type Model struct {
	Provider string
	ModelID  string
}

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 Result

type Result struct {
	CapsuleID string
	Payload   []byte
	Envelope  []byte
}

Result contains a signature-free Capsule and one Producer Envelope.

func Seal

func Seal(input SealInput) (Result, error)

Seal digest-commits caller-owned JSON, builds one signature-free Capsule, and attaches one Producer Envelope. It delegates canonicalization and signing to DigestJSON, Build or BuildComposition, and Sign.

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

func NewSigningIdentity(signer cose.Signer, publicKey ed25519.PublicKey) (SigningIdentity, error)

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.

const (
	TimeRungSelfAttested TimeRung = "self_attested"
	TimeRungWitnessed    TimeRung = "witnessed"
)

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"
)

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL