publication

package
v0.1.14 Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package publication builds deterministic, schema-validated publication records.

Index

Constants

This section is empty.

Variables

View Source 
var ErrFollowupStructuredRejected = errors.New("followup structured material rejected")

ErrFollowupStructuredRejected marks structured followup material that failed schema/semantic/evidence checks and may demote to reports-only publication. Inventory, lineage, identity, and other publication integrity failures must not wrap this sentinel.

Functions

func CommittedPublicationManifestPathFromError 

func CommittedPublicationManifestPathFromError(err error) (ports.SafeRelativePath, bool)

CommittedPublicationManifestPathFromError returns the manifest path retained by a post-commit diagnostic failure.

Types

type AttemptArtifactInput 

type AttemptArtifactInput struct {
	AttemptID          domain.AttemptID
	InvocationSequence uint64
	Artifact           ports.CapturedAttemptArtifact
}

AttemptArtifactInput binds one captured provider stream to an immutable attempt invocation. Rejected streams retain no bytes and are never persisted.

type CommittedRoleReport added in v0.1.4 

type CommittedRoleReport struct {
	Role             string
	Path             string
	SHA256           string
	ByteLength       int
	ProviderInstance string
	AttemptID        string
	ContentType      string
	Transport        string
}

CommittedRoleReport is one verified role-report identity from a committed publication manifest. It never invents source_invocation_id. Transport is the provider output transport that carried the accepted content for the role.

func ProjectCommittedRoleReports added in v0.1.4 

func ProjectCommittedRoleReports(snapshot ports.CommittedPublicationSnapshot) ([]CommittedRoleReport, error)

ProjectCommittedRoleReports reopens role-report inventory from the already schema/semantic-verified committed manifest and cross-checks each entry against final role outcome and attempt authority. Callers must not invent paths from coordinator summaries.

type FailureDiagnostic added in v0.1.4 

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

FailureDiagnostic is the redacted machine classification for a publication failure. It deliberately excludes native paths and underlying error text.

func FailureDiagnosticFromError added in v0.1.4 

func FailureDiagnosticFromError(err error) (FailureDiagnostic, bool)

FailureDiagnosticFromError returns only the stable, redacted publication classification carried by err.

func (FailureDiagnostic) Cause added in v0.1.4 

func (diagnostic FailureDiagnostic) Cause() domain.RuntimeDiagnosticCause

func (FailureDiagnostic) Failure added in v0.1.4 

func (diagnostic FailureDiagnostic) Failure() string

func (FailureDiagnostic) Mitigation added in v0.1.4 

func (diagnostic FailureDiagnostic) Mitigation() string

func (FailureDiagnostic) Phase added in v0.1.4 

func (diagnostic FailureDiagnostic) Phase() domain.RuntimeDiagnosticPhase

func (FailureDiagnostic) Valid added in v0.1.4 

func (diagnostic FailureDiagnostic) Valid() bool

type FollowupCandidateInput 

type FollowupCandidateInput struct {
	Run                 domain.Run
	SourceSessionID     domain.SessionID
	SourceRunID         domain.RunID
	SourceReviewID      domain.ReviewID
	SourceFindingID     string
	SourceTargetSHA256  string
	SourceExcerptSHA256 string
	AttemptID           domain.AttemptID
	Provider            string
	Output              validation.ValidatedFollowup
	Observation         ports.ProviderExecutionObservation
	Runtime             FollowupRuntimeArtifactInput
	Observations        []ports.ProviderExecutionObservation
	Runtimes            []FollowupRuntimeArtifactInput
	Repaired            bool
	InitialCandidate    []byte
	SeverityThreshold   domain.Severity
	MulgaeVersion       string
	MulgaeCommit        string
}

FollowupCandidateInput is the complete trusted input for a one-role followup publication. Provider output is accepted only after FollowupValidator has normalized it.

type FollowupRuntimeArtifactInput 

type FollowupRuntimeArtifactInput struct {
	RuntimeRunID                 domain.RunID
	RuntimeAttemptID             domain.AttemptID
	RuntimeSequence              uint64
	RuntimePurpose               domain.InvocationPurpose
	RuntimeRole                  domain.Role
	RuntimeTarget                []byte
	RuntimeCapturedArchive       []byte
	RuntimeTargetIdentity        domain.TargetIdentity
	RuntimeStdin                 []byte
	RuntimeStdinSHA256           string
	RuntimeTemplateID            string
	RuntimeTemplateVersion       string
	RuntimeTemplateSHA256        string
	RuntimeSourceInvocationID    string
	RuntimeExecutionInvocationID string
	RuntimeScope                 string
	RuntimeAdapterProfile        string
	RuntimeAdapterParameters     map[string]string
	RuntimeCaptures              []ports.CapturedAttemptArtifact
}

FollowupRuntimeArtifactInput is the complete immutable runtime inventory for the specialized followup invocation. Its fields intentionally mirror the coordinator runtime inventory so followups use the same P2 retention rules.

func (FollowupRuntimeArtifactInput) AdapterParameters 

func (input FollowupRuntimeArtifactInput) AdapterParameters() map[string]string

func (FollowupRuntimeArtifactInput) AdapterProfile 

func (input FollowupRuntimeArtifactInput) AdapterProfile() string

func (FollowupRuntimeArtifactInput) AttemptID 

func (input FollowupRuntimeArtifactInput) AttemptID() domain.AttemptID

func (FollowupRuntimeArtifactInput) CapturedArchive 

func (input FollowupRuntimeArtifactInput) CapturedArchive() []byte

func (FollowupRuntimeArtifactInput) Captures 

func (input FollowupRuntimeArtifactInput) Captures() []ports.CapturedAttemptArtifact

func (FollowupRuntimeArtifactInput) ExecutionInvocationID 

func (input FollowupRuntimeArtifactInput) ExecutionInvocationID() string

func (FollowupRuntimeArtifactInput) Purpose 

func (input FollowupRuntimeArtifactInput) Purpose() domain.InvocationPurpose

func (FollowupRuntimeArtifactInput) Role 

func (input FollowupRuntimeArtifactInput) Role() domain.Role

func (FollowupRuntimeArtifactInput) RunID 

func (input FollowupRuntimeArtifactInput) RunID() domain.RunID

func (FollowupRuntimeArtifactInput) Scope 

func (input FollowupRuntimeArtifactInput) Scope() string

func (FollowupRuntimeArtifactInput) Sequence 

func (input FollowupRuntimeArtifactInput) Sequence() uint64

func (FollowupRuntimeArtifactInput) SourceInvocationID 

func (input FollowupRuntimeArtifactInput) SourceInvocationID() string

func (FollowupRuntimeArtifactInput) Stdin 

func (input FollowupRuntimeArtifactInput) Stdin() []byte

func (FollowupRuntimeArtifactInput) StdinSHA256 

func (input FollowupRuntimeArtifactInput) StdinSHA256() string

func (FollowupRuntimeArtifactInput) Target 

func (input FollowupRuntimeArtifactInput) Target() []byte

func (FollowupRuntimeArtifactInput) TargetIdentity 

func (input FollowupRuntimeArtifactInput) TargetIdentity() domain.TargetIdentity

func (FollowupRuntimeArtifactInput) TemplateID 

func (input FollowupRuntimeArtifactInput) TemplateID() string

func (FollowupRuntimeArtifactInput) TemplateSHA256 

func (input FollowupRuntimeArtifactInput) TemplateSHA256() string

func (FollowupRuntimeArtifactInput) TemplateVersion 

func (input FollowupRuntimeArtifactInput) TemplateVersion() string

type LifecycleEvent 

type LifecycleEvent string
const (
	LifecyclePreparationStarted LifecycleEvent = "preparation_started"
	LifecycleStaged             LifecycleEvent = "staged"
	LifecycleInstalled          LifecycleEvent = "installed"
	LifecycleCommitted          LifecycleEvent = "committed"
	LifecycleFailed             LifecycleEvent = "failed"
)

func (LifecycleEvent) Valid 

func (event LifecycleEvent) Valid() bool

type LifecycleObservation added in v0.1.4 

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

LifecycleObservation carries either a normal publication transition or a redacted failure classification. Failure details are present only for the failed transition.

func (LifecycleObservation) Event added in v0.1.4 

func (observation LifecycleObservation) Event() LifecycleEvent

func (LifecycleObservation) FailureDiagnostic added in v0.1.4 

func (observation LifecycleObservation) FailureDiagnostic() (FailureDiagnostic, bool)

type LifecycleObserver 

type LifecycleObserver interface {
	ObservePublicationLifecycle(context.Context, LifecycleObservation) error
}

type NoChangeProvenance 

type NoChangeProvenance struct {
	BuildProduct             string
	BuildVersion             string
	BuildCommit              string
	ObjectiveSHA256          string
	HasObjective             bool
	SnapshotManifestSHA256   string
	WorkspaceTerminalReceipt string
}

type ObservedPublicationCommitter 

type ObservedPublicationCommitter interface {
	PublishNextObserved(context.Context, ports.AnchoredRoot, PreparedCandidate, LifecycleObserver) (PublicationResult, error)
}

type PreparedCandidate 

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

PreparedCandidate is a fully semantically validated terminal review result. It deliberately has no ReviewID. A ReviewID is supplied only after this pre-publication validation has completed.

func PrepareCandidate 

func PrepareCandidate(
	result review.CoordinatorResult,
	target domain.TargetIdentity,
	severityThreshold domain.Severity,
	mulgaeVersion string,
	mulgaeCommit string,
) (PreparedCandidate, error)

PrepareCandidate validates every semantic fact available before a ReviewID is issued. It preserves the root-review API and its serialized bytes.

func PrepareCandidateWithContext 

func PrepareCandidateWithContext(
	result review.CoordinatorResult,
	target domain.TargetIdentity,
	severityThreshold domain.Severity,
	mulgaeVersion string,
	mulgaeCommit string,
	context RunPublicationContext,
) (PreparedCandidate, error)

PrepareCandidateWithContext validates a root or child publication candidate.

func PrepareCandidateWithRuntimeArtifacts 

func PrepareCandidateWithRuntimeArtifacts(
	result review.CoordinatorResult,
	target domain.TargetIdentity,
	severityThreshold domain.Severity,
	mulgaeVersion string,
	mulgaeCommit string,
	context RunPublicationContext,
	inputs []review.RuntimeArtifactInventory,
) (PreparedCandidate, error)

PrepareCandidateWithRuntimeArtifacts binds one complete immutable runtime inventory to every coordinator invocation and rejects missing source material before P2 publication.

func PrepareFollowupCandidate 

func PrepareFollowupCandidate(input FollowupCandidateInput) (PreparedCandidate, error)

PrepareFollowupCandidate builds the regular P2 candidate shape for the specialized single-role followup execution. Structured findings/resolution are optional; reports-only acceptance still publishes the role report with lineage and inventory digests.

func PrepareNoChangeCandidate 

func PrepareNoChangeCandidate(
	sessionID domain.SessionID,
	runID domain.RunID,
	target domain.TargetIdentity,
	selectedRoles []domain.Role,
	severityThreshold domain.Severity,
	provenance NoChangeProvenance,
) (PreparedCandidate, error)

PrepareNoChangeCandidate constructs the provider-free P2 candidate for an empty Git capture. Patch and stdin targets are deliberately ineligible.

func (PreparedCandidate) Build 

func (candidate PreparedCandidate) Build(
	ctx context.Context,
	validator SchemaValidator,
	reviewID domain.ReviewID,
	createdAt time.Time,
	epoch uint64,
) (PublicationBundle, error)

Build assigns the post-validation ReviewID and constructs every deterministic publication member. It validates final-review and manifest bytes against the embedded schema assets before returning any bundle.

func (PreparedCandidate) RunID 

func (candidate PreparedCandidate) RunID() domain.RunID

RunID returns the immutable review-run identity bound by validation.

func (PreparedCandidate) SessionID 

func (candidate PreparedCandidate) SessionID() domain.SessionID

SessionID returns the immutable review-session identity bound by validation.

func (PreparedCandidate) Valid 

func (candidate PreparedCandidate) Valid() bool

Valid reports whether this value is a complete semantic pre-publication candidate. A zero value is never valid.

func (PreparedCandidate) ValidatedCandidateSHA256 

func (candidate PreparedCandidate) ValidatedCandidateSHA256() string

ValidatedCandidateSHA256 returns a deterministic, domain-separated identity over every semantic input validated before ReviewID issuance. It returns an empty string for an invalid candidate.

type ProductionProviderProvenance 

type ProductionProviderProvenance struct {
	Family                    string
	Instance                  string
	Version                   string
	Executable                string
	ExecutableSHA256          string
	Launcher                  string
	LauncherSHA256            string
	ProfileGeneration         string
	AdapterProfile            string
	QualificationReceiptIDs   []string
	PacketTransportReceiptIDs []string
	NamespaceTerminalReceipt  string // Canonical receipt ID.
}

type ProductionReviewProvenance 

type ProductionReviewProvenance struct {
	BuildProduct             string
	BuildVersion             string
	BuildCommit              string
	ObjectiveSHA256          string
	HasObjective             bool
	SnapshotManifestSHA256   string
	Providers                []ProductionProviderProvenance
	WorkspaceTerminalReceipt string
}

ProductionReviewProvenance is the immutable closure authority for a changed root review. It retains canonical receipt IDs rather than credentials, settings, or mutable workspace paths.

type PublicationBundle 

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

PublicationBundle is the defensive publication payload for one P2 composite. Its authority is represented solely by serialized records; this Go value has no authority flag or authorization accessor.

func (PublicationBundle) Epoch 

func (bundle PublicationBundle) Epoch() ports.PublicationEpoch

Epoch returns the positive immutable epoch record.

func (PublicationBundle) Excerpts 

func (bundle PublicationBundle) Excerpts() []ports.ImmutablePublicationArtifact

Excerpts returns caller-owned immutable excerpt artifact values.

func (PublicationBundle) Final 

func (bundle PublicationBundle) Final() ports.FinalReviewArtifact

Final returns the final review artifact with defensive byte accessors.

func (PublicationBundle) Journal 

func (bundle PublicationBundle) Journal() PublicationDocument

Journal returns the exact mutable journal replacement.

func (PublicationBundle) LineageEdge 

func (bundle PublicationBundle) LineageEdge() ports.ImmutablePublicationArtifact

LineageEdge returns the immutable publication lineage edge.

func (PublicationBundle) Manifest 

func (bundle PublicationBundle) Manifest() ports.ImmutablePublicationArtifact

Manifest returns the immutable committed manifest.

func (PublicationBundle) StagedFinal 

func (bundle PublicationBundle) StagedFinal() ports.ImmutablePublicationArtifact

StagedFinal returns final bytes at their required staged temporary identity.

func (PublicationBundle) Status 

func (bundle PublicationBundle) Status() PublicationDocument

Status returns the exact mutable status replacement.

func (PublicationBundle) SupportArtifacts 

func (bundle PublicationBundle) SupportArtifacts() []ports.ImmutablePublicationArtifact

SupportArtifacts returns caller-owned immutable excerpts and attempt-capture artifacts. Their paths are validated against the closed run-support grammar by the persistence boundary.

func (PublicationBundle) Valid 

func (bundle PublicationBundle) Valid() bool

Valid reports whether every bundle member remains self-consistent. It does not assert reader authority; only the serialized P2 records can do that.

type PublicationCommitter 

type PublicationCommitter interface {
	PublishNext(context.Context, ports.AnchoredRoot, PreparedCandidate) (PublicationResult, error)
}

PublicationCommitter is the root-bound publication boundary used by root-review orchestration. It deliberately does not expose caller-selected epochs.

type PublicationDocument 

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

PublicationDocument is an exact mutable publication record. Bytes returns a caller-owned copy; its path and digest identify the complete replacement.

func (PublicationDocument) Bytes 

func (document PublicationDocument) Bytes() []byte

Bytes returns a caller-owned copy of the exact record bytes.

func (PublicationDocument) Path 

func (document PublicationDocument) Path() ports.SafeRelativePath

Path returns the canonical mutable record path.

func (PublicationDocument) SHA256 

func (document PublicationDocument) SHA256() string

SHA256 returns the canonical exact-byte digest.

func (PublicationDocument) Valid 

func (document PublicationDocument) Valid() bool

Valid reports whether this document has a coherent immutable identity.

type PublicationResult 

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

PublicationResult is a defensive result of a completed P2 publication or a recovery observation that must resume collection. Snapshot is present only when P2 is authoritative.

func (PublicationResult) Decision 

func (result PublicationResult) Decision() domain.PublicationDecision

Decision returns the app-owned durable classification.

func (PublicationResult) Exit 

func (result PublicationResult) Exit() *domain.OperationalExitDecision

Exit returns the optional exact domain-reduced terminal exit decision. A nonterminal P0/P1 recovery result has no exit, so it cannot project a zero-value committed-pass outcome.

func (PublicationResult) Final 

func (result PublicationResult) Final() (ports.FinalReviewIdentity, bool)

Final returns the immutable final identity when it is known.

func (PublicationResult) IssuedReviewID 

func (result PublicationResult) IssuedReviewID() (ports.IssuedReviewID, bool)

IssuedReviewID returns the post-validation issued ID when this invocation created one. Recovery never invents an ID.

func (PublicationResult) PersistedRunSupportArtifacts 

func (result PublicationResult) PersistedRunSupportArtifacts() []RunSupportArtifactIdentity

PersistedRunSupportArtifacts returns defensive copies of the exact support artifact identities persisted and re-read by this invocation before P2.

func (PublicationResult) PromptManifestArtifact 

func (result PublicationResult) PromptManifestArtifact(
	attemptID domain.AttemptID,
	invocationSequence uint64,
) (RunSupportArtifactIdentity, bool)

PromptManifestArtifact returns the exact persisted prompt-manifest identity for one attempt invocation. It fails closed when this result has no verified support view, or the attempt/invocation is absent or ambiguous.

func (PublicationResult) Snapshot 

func (result PublicationResult) Snapshot() (ports.CommittedPublicationSnapshot, bool)

Snapshot returns the exact P2 snapshot with defensive byte accessors.

func (PublicationResult) TerminalExit 

func (result PublicationResult) TerminalExit() (domain.OperationalExitDecision, bool)

TerminalExit returns the terminal exit decision only when this result can project one. Normal content exits 0, 1, and 4 are available only from P2.

type ReplayMode 

type ReplayMode string

ReplayMode describes how a rerun obtains its prompt material. 

const (
	ReplayModeExact     ReplayMode = "exact"
	ReplayModeRecompose ReplayMode = "recompose"
)

type RoleReportURI added in v0.1.4 

type RoleReportURI struct {
	Role       string
	URI        string
	SHA256     string
	ByteLength int
}

RoleReportURI is one project-relative role-report identity projected from a committed publication snapshot and its verified support inventory.

func ProjectRoleReportURIs added in v0.1.4 

func ProjectRoleReportURIs(result PublicationResult) ([]RoleReportURI, error)

ProjectRoleReportURIs projects canonical project-relative role-report URIs from a P2 PublicationResult. Each URI is bound to the committed manifest inventory and the exact support artifact identities re-read before commit. Callers must not query the live directory or invent paths.

type RunPublicationContext 

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

RunPublicationContext binds a candidate to its immutable run lineage. The zero value is the byte-compatible root review context.

func NewChildPublicationContext 

func NewChildPublicationContext(
	runType domain.RunType,
	parentRunID domain.RunID,
	sourceRunID domain.RunID,
	sourceReviewID domain.ReviewID,
	sourceFindingRef *string,
	replayMode *ReplayMode,
) (RunPublicationContext, error)

NewChildPublicationContext validates the complete immutable lineage for a followup, delta, or rerun publication.

func NewProductionPublicationContext 

func NewProductionPublicationContext(provenance ProductionReviewProvenance) (RunPublicationContext, error)

NewProductionPublicationContext creates the root-only context for a normal production review and defensively owns every caller-provided slice.

type RunSupportArtifactIdentity 

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

RunSupportArtifactIdentity is the exact immutable identity of one run-support artifact re-read by publication before P2. It has no public constructor so callers cannot present synthesized support identities as persisted evidence.

func (RunSupportArtifactIdentity) Path 

func (identity RunSupportArtifactIdentity) Path() ports.SafeRelativePath

Path returns the exact persisted support-artifact path.

func (RunSupportArtifactIdentity) SHA256 

func (identity RunSupportArtifactIdentity) SHA256() string

SHA256 returns the exact persisted support-artifact hash.

type SchemaValidator 

type SchemaValidator interface {
	Validate(context.Context, ports.AssetID, []byte) error
}

SchemaValidator validates bytes against one embedded schema asset. It is consumer-owned because publication owns byte construction, not schema lookup.

type Service 

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

Service owns publication ordering and recovery policy. PublicationStore owns only mechanics and durable observation.

func NewService 

func NewService(
	store ports.PublicationStore,
	validator SchemaValidator,
	clock ports.Clock,
	maxBytes int64,
) (*Service, error)

NewService constructs a publication state-machine service.

func (*Service) Publish 

func (service *Service) Publish(
	ctx context.Context,
	artifactRoot ports.AnchoredRoot,
	candidate PreparedCandidate,
	epoch uint64,
) (PublicationResult, error)

Publish validates a candidate before issuing its ReviewID, writes all recoverable material before a journal hint, and returns only after a fresh P2 observation and snapshot confirm publication authority.

func (*Service) PublishFollowup 

func (service *Service) PublishFollowup(
	ctx context.Context,
	artifactRoot ports.AnchoredRoot,
	input FollowupCandidateInput,
	epoch uint64,
) (PublicationResult, error)

PublishFollowup prepares and commits the specialized one-role followup in the same P2 composite transaction used for every review publication.

func (*Service) PublishFollowupNext 

func (service *Service) PublishFollowupNext(
	ctx context.Context,
	artifactRoot ports.AnchoredRoot,
	input FollowupCandidateInput,
) (PublicationResult, error)

PublishFollowupNext prepares the specialized one-role followup and commits it under the next root-scoped epoch selected atomically by the publication store.

func (*Service) PublishNext 

func (service *Service) PublishNext(
	ctx context.Context,
	artifactRoot ports.AnchoredRoot,
	candidate PreparedCandidate,
) (PublicationResult, error)

PublishNext selects and commits the next root-scoped durable epoch as one store-authorized transaction. It is the production entry point; Publish remains available for compatibility callers that explicitly control epochs.

func (*Service) PublishNextObserved 

func (service *Service) PublishNextObserved(
	ctx context.Context,
	artifactRoot ports.AnchoredRoot,
	candidate PreparedCandidate,
	observer LifecycleObserver,
) (PublicationResult, error)

func (*Service) Recover 

func (service *Service) Recover(ctx context.Context, run ports.PublicationRun) (PublicationResult, error)

Recover applies only the action selected by a fresh domain classification. It never adopts ambiguous files, regenerates final/composite bytes, or downgrades P2 authority.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.