agentspecbackfill

Documentation

Overview

Package agentspecbackfill owns the pure immutable request, verification, and archive seam for Agent-spec backfill.

Index

• Variables
• type ArchiveBundle
  • func NewArchiveBundle(evidence TerminalArchiveEvidence) (ArchiveBundle, error)
  • func (bundle ArchiveBundle) AuditCode() AuditCode
  • func (bundle ArchiveBundle) Canonical() ([]byte, error)
  • func (bundle ArchiveBundle) CertificatePresent() bool
  • func (bundle ArchiveBundle) Digest() (string, error)
  • func (bundle ArchiveBundle) Key(prefix string) string
• type ArchiveExportConfig
• type ArchiveReceipt
• type Audit
• type AuditCode
• type CertificateInput
• type ConditionalArchive
• type FrozenLegacyReader
• type FrozenLegacySet
• type ImmutableContentVerifier
• type LegacyRevision
• type Phase
• type Reason
• type Reconciler
  • func NewReconciler(statuses TerminalStatusStore) (*Reconciler, error)
  • func (reconciler *Reconciler) Reconcile(ctx context.Context, request Request, reader FrozenLegacyReader, ...) (Status, error)
• type Request
  • func (request Request) Canonical() ([]byte, error)
  • func (request Request) Digest() (string, error)
  • func (request Request) Name() (string, error)
  • func (request Request) ValidateAt(now time.Time) error
• type Snapshot
• type Status
  • func Verify(ctx context.Context, request Request, reader FrozenLegacyReader, ...) (Status, error)
  • func (status Status) Canonical() ([]byte, error)
  • func (status Status) ValidateFor(request Request, now time.Time) error
  • func (status Status) ValidateTransitionFrom(previous Status) error
• type TerminalArchiveEvidence
• type TerminalArchiveExporter
  • func NewTerminalArchiveExporter(config ArchiveExportConfig, archives ConditionalArchive) (*TerminalArchiveExporter, error)
  • func (exporter *TerminalArchiveExporter) Export(ctx context.Context, evidence TerminalArchiveEvidence, observedAt time.Time) (ArchiveReceipt, error)
• type TerminalStatusStore

Variables

var (
	// ErrStaleSnapshot reports a request whose frozen legacy snapshot no longer matches.
	ErrStaleSnapshot = errors.New("agent spec backfill stale snapshot")
	// ErrWrongOwner reports a legacy revision outside the verified owner boundary.
	ErrWrongOwner = errors.New("agent spec backfill wrong owner")
	// ErrContentIntegrity reports immutable content that does not verify against its reference.
	ErrContentIntegrity = errors.New("agent spec backfill immutable content integrity")
	// ErrExpiredRequest reports a request outside its immutable admission window.
	ErrExpiredRequest = errors.New("agent spec backfill request expired")
	// ErrFutureRequest reports a request before its immutable creation time.
	ErrFutureRequest = errors.New("agent spec backfill request is not yet admitted")
)

var (
	// ErrArchiveConflict reports an existing request-keyed archive whose observed canonical digest differs.
	ErrArchiveConflict = errors.New("agent spec backfill archive conflict")
)

Types

type ArchiveBundle

type ArchiveBundle struct {
	// contains filtered or unexported fields
}

ArchiveBundle is one immutable terminal request evidence bundle.

func NewArchiveBundle

func NewArchiveBundle(evidence TerminalArchiveEvidence) (ArchiveBundle, error)

NewArchiveBundle constructs one CR-UID and request-digest-keyed terminal archive bundle.

func (ArchiveBundle) AuditCode

func (bundle ArchiveBundle) AuditCode() AuditCode

AuditCode reports the bounded redacted audit classification retained in this bundle.

func (ArchiveBundle) Canonical

func (bundle ArchiveBundle) Canonical() ([]byte, error)

Canonical returns bounded redacted immutable archive bytes.

func (ArchiveBundle) CertificatePresent

func (bundle ArchiveBundle) CertificatePresent() bool

CertificatePresent reports whether the terminal request committed v4 certificate evidence.

func (ArchiveBundle) Digest

func (bundle ArchiveBundle) Digest() (string, error)

Digest returns the SHA-256 digest of one canonical immutable archive bundle.

func (ArchiveBundle) Key

func (bundle ArchiveBundle) Key(prefix string) string

Key returns the deterministic archive object key under one declared prefix.

type ArchiveExportConfig

type ArchiveExportConfig struct{ Prefix string }

ArchiveExportConfig is the explicit capability-bounded object prefix for one archive exporter.

type ArchiveReceipt

type ArchiveReceipt struct {
	Created         bool
	Key             string
	CanonicalDigest string
}

ArchiveReceipt reports the immutable canonical digest observed after one conditional archive write.

type Audit

type Audit struct{ Code AuditCode }

Audit is bounded redacted terminal evidence. Code is validated against the terminal Status, so arbitrary source-provided text is never archived.

type AuditCode

type AuditCode string

AuditCode is one closed redacted terminal-audit classification.

const (
	// AuditVerified records a verified immutable legacy snapshot.
	AuditVerified AuditCode = "verified"
	// AuditRefusedSnapshot records a safe snapshot refusal.
	AuditRefusedSnapshot AuditCode = "refused_snapshot"
	// AuditRefusedContent records a safe content/owner refusal.
	AuditRefusedContent AuditCode = "refused_content"
	// AuditRefusedExpired records a safe expiry refusal.
	AuditRefusedExpired AuditCode = "refused_expired"
	// AuditRefusedNotAdmitted records a safe pre-admission refusal.
	AuditRefusedNotAdmitted AuditCode = "refused_not_admitted"
)

type CertificateInput

type CertificateInput struct{ Digest string }

CertificateInput is the safe certificate projection when v4 committed.

type ConditionalArchive

type ConditionalArchive interface {
	PutIfAbsent(context.Context, string, ArchiveBundle, string) (ArchiveReceipt, error)
}

ConditionalArchive conditionally retains one immutable request-keyed ArchiveBundle without overwriting it. It must verify and return the expected canonical digest when the object already exists.

type FrozenLegacyReader

type FrozenLegacyReader interface {
	ReadFrozen(context.Context) (FrozenLegacySet, error)
}

FrozenLegacyReader reads the fenced historical revision set.

type FrozenLegacySet

type FrozenLegacySet struct {
	Snapshot  Snapshot
	Revisions []LegacyRevision
}

FrozenLegacySet is read under the migration fence.

type ImmutableContentVerifier

type ImmutableContentVerifier interface {
	VerifyImmutable(context.Context, LegacyRevision) error
}

ImmutableContentVerifier validates one revision against its immutable content reference and manifest.

type LegacyRevision

type LegacyRevision struct {
	TenantID, AgentID, RevisionID, SpecificationDigest string
	SpecificationSizeBytes                             int64
}

LegacyRevision is one minimal immutable historical Agent revision reference.

type Phase

type Phase string

Phase identifies one terminal or in-progress verification state.

const (
	// PhasePending identifies a request not yet examined by the controller.
	PhasePending Phase = "Pending"
	// PhaseVerifying identifies an in-progress verification.
	PhaseVerifying Phase = "Verifying"
	// PhaseVerified identifies a successfully verified immutable legacy set.
	PhaseVerified Phase = "Verified"
	// PhaseRefused identifies a terminal safe refusal.
	PhaseRefused Phase = "Refused"
)

type Reason

type Reason string

Reason is a bounded terminal refusal classification.

const (
	// RefusalSnapshot identifies a stale or malformed frozen snapshot.
	RefusalSnapshot Reason = "snapshot"
	// RefusalContent identifies content or owner integrity failure.
	RefusalContent Reason = "content"
	// RefusalExpired identifies an expired request.
	RefusalExpired Reason = "expired"
	// RefusalNotAdmitted identifies a request before its immutable creation time.
	RefusalNotAdmitted Reason = "not_admitted"
)

type Reconciler

type Reconciler struct {
	// contains filtered or unexported fields
}

Reconciler coordinates one pure Agent-spec-backfill verification pass through the terminal-status port.

func NewReconciler

func NewReconciler(statuses TerminalStatusStore) (*Reconciler, error)

NewReconciler constructs a Reconciler with its required terminal-status port.

func (*Reconciler) Reconcile

func (reconciler *Reconciler) Reconcile(ctx context.Context, request Request, reader FrozenLegacyReader, verifier ImmutableContentVerifier, now time.Time) (Status, error)

Reconcile verifies one immutable request and persists only its terminal winner.

type Request

type Request struct {
	StackDigest              string
	MigrationVersion         uint32
	MigrationArtifactDigest  string
	ManifestDigest           string
	ControllerImageDigest    string
	SnapshotFingerprint      string
	SnapshotCount            uint64
	FenceNonce               string
	StaticReadinessDigest    string
	DatabaseAuthorityDigest  string
	BlobReadCapabilityDigest string
	CreatedAt                time.Time
	ExpiresAt                time.Time
}

Request is the immutable, bounded controller request with no raw Agent specification or object key.

func (Request) Canonical

func (request Request) Canonical() ([]byte, error)

Canonical returns the deterministic CBOR request envelope.

func (Request) Digest

func (request Request) Digest() (string, error)

Digest returns the canonical request digest.

func (Request) Name

func (request Request) Name() (string, error)

Name returns the deterministic Kubernetes-safe request capability name.

func (Request) ValidateAt

func (request Request) ValidateAt(now time.Time) error

ValidateAt verifies the immutable request admission window at an explicit UTC time.

type Snapshot

type Snapshot struct {
	Fingerprint string
	Count       uint64
}

Snapshot describes the deterministic frozen legacy set.

type Status

type Status struct {
	Phase               Phase
	RequestDigest       string
	SnapshotFingerprint string
	SnapshotCount       uint64
	Reason              Reason
	CompletedAt         time.Time
}

Status is the bounded redacted result for one immutable request.

func Verify

func Verify(ctx context.Context, request Request, reader FrozenLegacyReader, verifier ImmutableContentVerifier, now time.Time) (Status, error)

Verify reads and verifies a frozen set, returning only a bounded terminal status.

func (Status) Canonical

func (status Status) Canonical() ([]byte, error)

Canonical returns the deterministic bounded CBOR terminal-status envelope.

func (Status) ValidateFor

func (status Status) ValidateFor(request Request, now time.Time) error

ValidateFor proves the status matches one request at an explicit time.

func (Status) ValidateTransitionFrom

func (status Status) ValidateTransitionFrom(previous Status) error

ValidateTransitionFrom rejects any transition from a terminal status.

type TerminalArchiveEvidence

type TerminalArchiveEvidence struct {
	RequestUID    string
	RequestDigest string
	Request       Request
	Status        Status
	Audit         Audit
	Certificate   *CertificateInput
}

TerminalArchiveEvidence is the redacted, immutable terminal evidence selected by the distinct archive-export authority. RequestUID is the observed CR UID, never a caller-supplied display name.

type TerminalArchiveExporter

type TerminalArchiveExporter struct {
	// contains filtered or unexported fields
}

TerminalArchiveExporter conditionally retains redacted evidence for one already-terminal backfill request.

func NewTerminalArchiveExporter

func NewTerminalArchiveExporter(config ArchiveExportConfig, archives ConditionalArchive) (*TerminalArchiveExporter, error)

NewTerminalArchiveExporter constructs a TerminalArchiveExporter with its required conditional archive port.

func (*TerminalArchiveExporter) Export

func (exporter *TerminalArchiveExporter) Export(ctx context.Context, evidence TerminalArchiveEvidence, observedAt time.Time) (ArchiveReceipt, error)

Export conditionally retains the CR-UID-bound canonical archive bundle for one terminal status. Terminal integrity is evaluated at completion, while observedAt only prevents exporting a result from the future.

type TerminalStatusStore

type TerminalStatusStore interface {
	ReadTerminal(context.Context, Request) (Status, bool, error)
	CreateTerminal(context.Context, Request, Status) (stored Status, created bool, err error)
}

TerminalStatusStore atomically reads and conditionally records one request's terminal Status.