spec

package
v0.2.7 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MPL-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package spec defines Artifact Store's portable and app-local data contracts.

Index

Constants

View Source 
const (
	// ArtifactDefinitionFileFormatV1 is the JSON-file envelope used for portable
	// definition export, import, capture, and content-addressed definition storage.
	// It is not required for a frontend's native source format.
	ArtifactDefinitionFileFormatV1 = "artifact-definition/v1"

	// PortablePackageManifestFormatV1 is the JSON-file manifest used for a
	// portable Artifact Store package. It is an interchange format, not a
	// mandatory source envelope for frontends.
	PortablePackageManifestFormatV1 = "artifact-package/v1"
)
View Source 
const (
	MaxKindBytes                  = 128
	MaxSchemaIDBytes              = 256
	MaxDisplayNameBytes           = 256
	MaxDescriptionBytes           = 16 * 1024
	MaxLogicalNameBytes           = 256
	MaxVersionBytes               = 256
	MaxSourceGenerationBytes      = 512
	MaxSourceLocatorBytes         = 4096
	MaxFilesystemPathBytes        = 16 * 1024
	MaxDiagnosticCodeBytes        = 128
	MaxDiagnosticMessageBytes     = 4096
	MaxLabelsPerDefinition        = 64
	MaxLabelValueBytes            = 256
	MaxAssetsPerDefinition        = 4096
	MaxSelectorsPerDefinition     = 1024
	MaxDiagnosticsPerEntity       = 128
	MaxConfigJSONBytes            = 1 << 20
	MaxLocalDataJSONBytes         = 1 << 20
	MaxDefinitionJSONBytes        = 4 << 20
	MaxExtensionsJSONBytes        = 1 << 20
	MaxPortablePackageDefinitions = 4096
	MaxAttachmentPriority         = 1_000_000
	MaxSlugRunes                  = 64
	DefaultMaxScanCandidates      = 10_000
	DefaultMaxScanEntries         = 100_000
	DefaultMaxTraversalDepth      = 64
	DefaultMaxMaterializedEntries = 100_000
	DefaultMaxMaterializedFiles   = 50_000
	DefaultMaxMaterializedBytes   = int64(512 << 20)
	MaxTransferPayloadBytes       = int64(512 << 20)
	MaxObservationRevision        = uint64(1<<63 - 1)
)
View Source 
const (
	FSDirectoryConfigSchemaID         SchemaID = "artifactstore.fs-directory.config.v1"
	EmbeddedFSDirectoryConfigSchemaID SchemaID = "artifactstore.embedded-fs-directory.config.v1"
	MemoryDirectoryConfigSchemaID     SchemaID = "artifactstore.memory-directory.config.v1"

	PortableDefinitionFrontendID FrontendID = "artifactstore.portable-definition"
)

Variables

View Source 
var (
	ErrClosed                    = errors.New("artifactstore: closed")
	ErrNotFound                  = errors.New("artifactstore: not found")
	ErrConflict                  = errors.New("artifactstore: conflict")
	ErrInvalidRequest            = errors.New("artifactstore: invalid request")
	ErrUnsupported               = errors.New("artifactstore: unsupported")
	ErrSourceNotAttached         = errors.New("artifactstore: source is not attached to root")
	ErrContentNotFound           = errors.New("artifactstore: portable content not found")
	ErrDigestMismatch            = errors.New("artifactstore: digest mismatch")
	ErrDriverUnavailable         = errors.New("artifactstore: source driver unavailable")
	ErrMaterializerUnavailable   = errors.New("artifactstore: source materializer unavailable")
	ErrFrontendUnavailable       = errors.New("artifactstore: artifact frontend unavailable")
	ErrVersionMatcherUnavailable = errors.New("artifactstore: version matcher unavailable")
)
View Source 
var ErrInvalid = errors.New("artifactstore: invalid")

Functions

This section is empty.

Types

type ArtifactCandidate 

type ArtifactCandidate struct {
	Source                 ArtifactSource
	Locator                SourceLocator
	SourceContentDigest    Digest
	Content                []byte
	PackageManifestLocator SourceLocator
}

ArtifactCandidate is bounded source content supplied to an artifact frontend.

type ArtifactCollection 

type ArtifactCollection struct {
	CollectionID CollectionID   `json:"collectionID"`
	RootID       RootID         `json:"rootID"`
	Kind         CollectionKind `json:"kind"`
	Slug         CollectionSlug `json:"slug"`
	DisplayName  string         `json:"displayName"`
	Description  string         `json:"description,omitempty"`
	Enabled      bool           `json:"enabled"`

	DataSchemaID SchemaID        `json:"dataSchemaID,omitempty"`
	Data         json.RawMessage `json:"data"`

	CreatedAt     time.Time  `json:"createdAt"`
	ModifiedAt    time.Time  `json:"modifiedAt"`
	SoftDeletedAt *time.Time `json:"softDeletedAt,omitempty"`
}

ArtifactCollection is an app-local grouping of records. It maps to current bundle semantics but is not a portable package.

type ArtifactDefinitionFile 

type ArtifactDefinitionFile struct {
	Format     string              `json:"format"`
	Definition CanonicalDefinition `json:"definition"`
}

ArtifactDefinitionFile is the portable JSON envelope for an exported, imported, captured, or content-addressed canonical definition. Frontends remain free to use their own native source formats.

type ArtifactDependencySnapshot 

type ArtifactDependencySnapshot struct {
	RootID               RootID                    `json:"rootID"`
	RecordID             RecordID                  `json:"recordID"`
	CatalogGeneration    uint64                    `json:"catalogGeneration"`
	RootDefinitionDigest Digest                    `json:"rootDefinitionDigest"`
	DefinitionDigest     Digest                    `json:"definitionDigest"`
	SelectorIndex        int                       `json:"selectorIndex"`
	Selector             ArtifactSelector          `json:"selector"`
	State                DependencyResolutionState `json:"state"`
	Candidates           []DependencyCandidateRef  `json:"candidates"`
	Diagnostics          []Diagnostic              `json:"diagnostics,omitempty"`
	ModifiedAt           time.Time                 `json:"modifiedAt"`
}

ArtifactDependencySnapshot records one selector resolution against one published root catalog generation.

type ArtifactFrontend 

type ArtifactFrontend interface {
	ID() FrontendID
	Recognizes(ctx context.Context, candidate ArtifactCandidate) Recognition
	Decode(ctx context.Context, candidate ArtifactCandidate) ([]DecodedArtifact, []Diagnostic)
	ValidateStructure(ctx context.Context, definition CanonicalDefinition) []Diagnostic
	ValidateSemantic(ctx context.Context, definition CanonicalDefinition) []Diagnostic
	ExtractDependencies(
		ctx context.Context,
		definition CanonicalDefinition,
	) ([]ArtifactSelector, []Diagnostic)
	ValidateRecordData(
		ctx context.Context,
		definition CanonicalDefinition,
		record ArtifactRecordDraft,
	) []Diagnostic
	DescribeExportClosure(ctx context.Context, definition CanonicalDefinition) (ExportClosure, []Diagnostic)
}

ArtifactFrontend owns domain-specific recognition, decoding, and validation. It must not implement transport behavior or depend on app-local source paths.

type ArtifactKind 

type ArtifactKind string

type ArtifactMetadataRepository 

type ArtifactMetadataRepository interface {
	Close() error

	CreateRoot(ctx context.Context, root ArtifactRoot) error
	GetRoot(ctx context.Context, rootID RootID, includeSoftDeleted bool) (ArtifactRoot, error)
	ListRoots(ctx context.Context, includeSoftDeleted bool) ([]ArtifactRoot, error)
	UpdateRoot(ctx context.Context, root ArtifactRoot, expectedModifiedAt time.Time) error

	CreateSource(ctx context.Context, source ArtifactSource) error
	GetSource(ctx context.Context, sourceID SourceID) (ArtifactSource, error)
	ListSources(ctx context.Context) ([]ArtifactSource, error)
	UpdateSource(ctx context.Context, source ArtifactSource, expectedModifiedAt time.Time) error
	DeleteSource(ctx context.Context, sourceID SourceID, expectedModifiedAt time.Time) error

	CreateRootSourceAttachment(ctx context.Context, attachment RootSourceAttachment) error
	GetRootSourceAttachment(
		ctx context.Context,
		rootID RootID,
		sourceID SourceID,
	) (RootSourceAttachment, error)
	ListRootSourceAttachments(ctx context.Context, rootID RootID) ([]RootSourceAttachment, error)
	UpdateRootSourceAttachment(
		ctx context.Context,
		attachment RootSourceAttachment,
		expectedModifiedAt time.Time,
	) error
	DeleteRootSourceAttachment(
		ctx context.Context,
		rootID RootID,
		sourceID SourceID,
		expectedModifiedAt time.Time,
	) error

	CreateCollection(ctx context.Context, collection ArtifactCollection) error
	GetCollection(
		ctx context.Context,
		collectionID CollectionID,
		includeSoftDeleted bool,
	) (ArtifactCollection, error)
	GetCollectionByRootSlug(
		ctx context.Context,
		rootID RootID,
		slug CollectionSlug,
		includeSoftDeleted bool,
	) (ArtifactCollection, error)
	ListCollections(ctx context.Context, rootID RootID, includeSoftDeleted bool) ([]ArtifactCollection, error)
	UpdateCollection(
		ctx context.Context,
		collection ArtifactCollection,
		expectedModifiedAt time.Time,
	) error
	CountRecordsInCollection(ctx context.Context, collectionID CollectionID) (int64, error)

	GetArtifactPackage(
		ctx context.Context,
		sourceID SourceID,
		manifestLocator SourceLocator,
	) (ArtifactPackage, error)
	ListArtifactPackagesForSource(ctx context.Context, sourceID SourceID) ([]ArtifactPackage, error)
	UpsertArtifactPackage(ctx context.Context, artifactPackage ArtifactPackage) error

	GetCatalogResource(ctx context.Context, key CatalogResourceKey) (CatalogResource, error)
	ListCatalogResourcesForSource(ctx context.Context, sourceID SourceID) ([]CatalogResource, error)
	ListPublishedCatalogResourcesForRoot(ctx context.Context, rootID RootID) ([]CatalogResource, error)
	ListCatalogResourceRevisions(
		ctx context.Context,
		key CatalogResourceKey,
	) ([]CatalogResourceRevision, error)
	PublishRootScan(
		ctx context.Context,
		publication RootScanPublication,
	) (RootCatalogGeneration, error)
	GetRootCatalogGeneration(ctx context.Context, rootID RootID) (RootCatalogGeneration, error)

	CreateRecord(ctx context.Context, record ArtifactRecord) error
	GetRecord(ctx context.Context, recordID RecordID) (ArtifactRecord, error)
	ListRecordsForRoot(ctx context.Context, rootID RootID) ([]ArtifactRecord, error)
	FindRecordBySource(
		ctx context.Context,
		rootID RootID,
		key CatalogResourceKey,
		kind ArtifactKind,
	) (ArtifactRecord, error)
	UpdateRecord(ctx context.Context, record ArtifactRecord, expectedModifiedAt time.Time) error
	DeleteRecord(ctx context.Context, recordID RecordID, expectedModifiedAt time.Time) error

	PublishRecordSynchronization(
		ctx context.Context,
		publication RecordSynchronizationPublication,
	) error
	PublishRecordTransfer(ctx context.Context, publication RecordTransferPublication) error

	ListTransferProvenance(ctx context.Context, recordID RecordID) ([]TransferProvenance, error)

	ReplaceDependencySnapshots(
		ctx context.Context,
		publication DependencySnapshotPublication,
	) error
	ListDependencySnapshots(
		ctx context.Context,
		recordID RecordID,
	) ([]ArtifactDependencySnapshot, error)
}

ArtifactMetadataRepository is the app-local data-access boundary. Business logic depends only on this interface, allowing SQLite to be replaced by a different metadata backend without changing service behavior.

type ArtifactPackage 

type ArtifactPackage struct {
	SourceID        SourceID      `json:"sourceID"`
	ManifestLocator SourceLocator `json:"manifestLocator"`

	Name        LogicalName    `json:"name,omitempty"`
	Version     LogicalVersion `json:"version,omitempty"`
	DisplayName string         `json:"displayName,omitempty"`
	Description string         `json:"description,omitempty"`

	CurrentManifestDigest *Digest      `json:"currentManifestDigest,omitempty"`
	State                 CatalogState `json:"state"`
	Diagnostics           []Diagnostic `json:"diagnostics,omitempty"`

	FirstSeenAt time.Time `json:"firstSeenAt"`
	LastSeenAt  time.Time `json:"lastSeenAt"`
}

ArtifactPackage is app-local catalog metadata for one occurrence of a portable package manifest. The portable manifest itself is a JSON file and is represented by PortablePackageManifest.

type ArtifactRecord 

type ArtifactRecord struct {
	RecordID     RecordID      `json:"recordID"`
	RootID       RootID        `json:"rootID"`
	CollectionID *CollectionID `json:"collectionID,omitempty"`

	Kind    ArtifactKind  `json:"kind"`
	Name    RecordName    `json:"name"`
	Version RecordVersion `json:"version,omitempty"`

	SourceID           SourceID           `json:"sourceID"`
	Locator            SourceLocator      `json:"locator"`
	SubresourceLocator SubresourceLocator `json:"subresourceLocator,omitempty"`

	RecordMode                   RecordMode   `json:"recordMode"`
	TrackingMode                 TrackingMode `json:"trackingMode"`
	PinnedDefinitionDigest       *Digest      `json:"pinnedDefinitionDigest,omitempty"`
	LastResolvedDefinitionDigest *Digest      `json:"lastResolvedDefinitionDigest,omitempty"`

	Enabled      bool            `json:"enabled"`
	DataSchemaID SchemaID        `json:"dataSchemaID,omitempty"`
	Data         json.RawMessage `json:"data"`
	State        RecordState     `json:"state"`
	Diagnostics  []Diagnostic    `json:"diagnostics,omitempty"`

	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`
}

ArtifactRecord is the only generic app-side artifact item. Its identity and local data are app-local, while its resolved definition remains portable.

type ArtifactRecordDraft 

type ArtifactRecordDraft struct {
	RootID       RootID
	CollectionID *CollectionID

	Kind    ArtifactKind
	Name    RecordName
	Version RecordVersion

	SourceID           SourceID
	Locator            SourceLocator
	SubresourceLocator SubresourceLocator

	RecordMode             RecordMode
	TrackingMode           TrackingMode
	PinnedDefinitionDigest *Digest
	Enabled                bool
	DataSchemaID           SchemaID
	Data                   json.RawMessage
}

ArtifactRecordDraft is the caller-provided portion of a new app-local record. Artifact Store assigns RecordID, state, resolved digest, and timestamps.

type ArtifactRoot 

type ArtifactRoot struct {
	RootID      RootID   `json:"rootID"`
	Kind        RootKind `json:"kind"`
	DisplayName string   `json:"displayName"`
	Description string   `json:"description,omitempty"`
	Enabled     bool     `json:"enabled"`

	DataSchemaID SchemaID        `json:"dataSchemaID,omitempty"`
	Data         json.RawMessage `json:"data"`

	CreatedAt     time.Time  `json:"createdAt"`
	ModifiedAt    time.Time  `json:"modifiedAt"`
	SoftDeletedAt *time.Time `json:"softDeletedAt,omitempty"`
}

ArtifactRoot is app-local metadata. It is never part of a portable package.

type ArtifactSelector 

type ArtifactSelector struct {
	Kind              ArtifactKind      `json:"kind"`
	LogicalName       LogicalName       `json:"logicalName,omitempty"`
	VersionConstraint string            `json:"versionConstraint,omitempty"`
	Labels            map[string]string `json:"labels,omitempty"`
}

ArtifactSelector is a portable dependency declaration. It intentionally contains no root, record, source, path, secret, or runtime identity.

type ArtifactSource 

type ArtifactSource struct {
	SourceID    SourceID   `json:"sourceID"`
	Kind        SourceKind `json:"kind"`
	DisplayName string     `json:"displayName"`
	Enabled     bool       `json:"enabled"`

	ConfigSchemaID SchemaID        `json:"configSchemaID"`
	Config         json.RawMessage `json:"config"`

	LastObservedGeneration *SourceGeneration `json:"lastObservedGeneration,omitempty"`
	LastScannedAt          *time.Time        `json:"lastScannedAt,omitempty"`
	ObservationRevision    uint64            `json:"observationRevision"`
	Diagnostics            []Diagnostic      `json:"diagnostics,omitempty"`

	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`
}

ArtifactSource is an app-local source registration. In particular, fs-directory configuration may contain an absolute local path and must not be exported as portable artifact content.

type ArtifactVersionMatcher 

type ArtifactVersionMatcher interface {
	Kind() ArtifactKind
	MatchesVersionConstraint(
		ctx context.Context,
		constraint string,
		version LogicalVersion,
	) (bool, error)
}

ArtifactVersionMatcher owns version-constraint syntax for one artifact kind. Artifact Store deliberately does not interpret semver, date versions, tags, ranges, or domain-specific version aliases.

type AssetManifestEntry 

type AssetManifestEntry struct {
	Path      PortablePath `json:"path"`
	Digest    Digest       `json:"digest"`
	MediaType string       `json:"mediaType,omitempty"`
	SizeBytes int64        `json:"sizeBytes"`
}

AssetManifestEntry describes portable content that belongs to a canonical definition. Path is relative to the package or export root.

type AttachmentRole 

type AttachmentRole string

type CanonicalDefinition 

type CanonicalDefinition struct {
	Digest        Digest       `json:"digest"`
	Kind          ArtifactKind `json:"kind"`
	SchemaID      SchemaID     `json:"schemaID"`
	SchemaVersion string       `json:"schemaVersion"`

	LogicalName    LogicalName    `json:"logicalName"`
	LogicalVersion LogicalVersion `json:"logicalVersion,omitempty"`
	DisplayName    string         `json:"displayName,omitempty"`
	Description    string         `json:"description,omitempty"`

	Labels              map[string]string    `json:"labels,omitempty"`
	Extensions          json.RawMessage      `json:"extensions"`
	DefinitionJSON      json.RawMessage      `json:"definitionJSON"`
	DependencySelectors []ArtifactSelector   `json:"dependencySelectors,omitempty"`
	AssetManifest       []AssetManifestEntry `json:"assetManifest,omitempty"`
}

CanonicalDefinition is immutable and portable. It is persisted as a content-addressed JSON file or included in a portable export, never as the authoritative definition body in SQLite metadata.

The Digest is calculated from the canonical portable fields. It excludes app-local observations such as source IDs, records, roots, timestamps, and diagnostics.

type CaptureRecordRequest 

type CaptureRecordRequest struct {
	OriginRecordID      RecordID
	Destination         TransferDestination
	MaterializationMode TransferMaterializationMode
}

type CatalogResource 

type CatalogResource struct {
	SourceID           SourceID           `json:"sourceID"`
	Locator            SourceLocator      `json:"locator"`
	SubresourceLocator SubresourceLocator `json:"subresourceLocator,omitempty"`

	PackageManifestLocator SourceLocator  `json:"packageManifestLocator,omitempty"`
	Kind                   ArtifactKind   `json:"kind,omitempty"`
	LogicalName            LogicalName    `json:"logicalName,omitempty"`
	LogicalVersion         LogicalVersion `json:"logicalVersion,omitempty"`

	CurrentDefinitionDigest *Digest      `json:"currentDefinitionDigest,omitempty"`
	SourceContentDigest     *Digest      `json:"sourceContentDigest,omitempty"`
	FrontendID              FrontendID   `json:"frontendID,omitempty"`
	State                   CatalogState `json:"state"`

	FirstSeenAt time.Time    `json:"firstSeenAt"`
	LastSeenAt  time.Time    `json:"lastSeenAt"`
	Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
}

CatalogResource is app-local metadata for one discovered source occurrence. Its natural key is SourceID + Locator + SubresourceLocator.

type CatalogResourceKey 

type CatalogResourceKey struct {
	SourceID           SourceID           `json:"sourceID"`
	Locator            SourceLocator      `json:"locator"`
	SubresourceLocator SubresourceLocator `json:"subresourceLocator,omitempty"`
}

CatalogResourceKey is the natural identity of a source-local occurrence.

type CatalogResourceRevision 

type CatalogResourceRevision struct {
	SourceID           SourceID           `json:"sourceID"`
	Locator            SourceLocator      `json:"locator"`
	SubresourceLocator SubresourceLocator `json:"subresourceLocator,omitempty"`

	DefinitionDigest    Digest       `json:"definitionDigest"`
	SourceContentDigest Digest       `json:"sourceContentDigest"`
	Kind                ArtifactKind `json:"kind"`
	FrontendID          FrontendID   `json:"frontendID"`

	FirstSeenAt time.Time `json:"firstSeenAt"`
	LastSeenAt  time.Time `json:"lastSeenAt"`
}

CatalogResourceRevision retains durable source-occurrence history. Its natural key is SourceID + Locator + SubresourceLocator + DefinitionDigest. It makes ListDefinitionHistory possible without assigning a revision ID.

type CatalogState 

type CatalogState string
const (
	CatalogStateValid   CatalogState = "valid"
	CatalogStateInvalid CatalogState = "invalid"
	CatalogStateMissing CatalogState = "missing"
)

type CollectionDraft 

type CollectionDraft struct {
	RootID       RootID
	Kind         CollectionKind
	Slug         CollectionSlug
	DisplayName  string
	Description  string
	Enabled      bool
	DataSchemaID SchemaID
	Data         json.RawMessage
}

CollectionDraft is the caller-provided portion of a newly created collection.

type CollectionID 

type CollectionID string

type CollectionKind 

type CollectionKind string

type CollectionKindHook 

type CollectionKindHook interface {
	Kind() CollectionKind
	ValidateCollectionData(ctx context.Context, collection ArtifactCollection) []Diagnostic
	ValidateRecordPlacement(
		ctx context.Context,
		collection ArtifactCollection,
		record ArtifactRecord,
	) []Diagnostic
}

CollectionKindHook validates app-local typed collection data and record placement without interpreting the record's runtime behavior.

type CollectionSlug 

type CollectionSlug string

type DecodedArtifact 

type DecodedArtifact struct {
	SubresourceLocator SubresourceLocator
	Definition         CanonicalDefinition
}

DecodedArtifact maps a portable definition to one source-local subresource. The frontend leaves Digest empty; Artifact Store canonicalizes and calculates it before storage.

type DefinitionMaterialization 

type DefinitionMaterialization struct {
	SourceContentDigest Digest
	Receipt             string
}

DefinitionMaterialization is returned only after the destination publication is durable and visible. Receipt is opaque and scoped to safe compensation.

type DefinitionMaterializationRequest 

type DefinitionMaterializationRequest struct {
	Source      ArtifactSource
	Destination TransferDestination
	Payload     DefinitionTransferPayload
	Exclusive   bool
}

type DefinitionMaterializer 

type DefinitionMaterializer interface {
	Kind() SourceKind
	MaterializeDefinition(
		ctx context.Context,
		request DefinitionMaterializationRequest,
	) (DefinitionMaterialization, error)
	DiscardDefinition(
		ctx context.Context,
		source ArtifactSource,
		receipt string,
	) error
}

DefinitionMaterializer owns source-kind-specific writes for transfer operations. MaterializeDefinition must honor Exclusive without overwriting an existing destination. DiscardDefinition must only remove data represented by the supplied receipt.

type DefinitionTransferPayload 

type DefinitionTransferPayload struct {
	RootDefinitionDigest Digest
	Definitions          []ArtifactDefinitionFile
	Assets               []PortableAssetContent
}

DefinitionTransferPayload contains shareable files only. It contains no root, source, collection, record, local path, secret, or runtime identity.

type DependencyCandidate 

type DependencyCandidate struct {
	Resource   CatalogResource
	Definition CanonicalDefinition
}

DependencyCandidate is one catalog definition matching a portable selector.

type DependencyCandidateRef 

type DependencyCandidateRef struct {
	Resource         CatalogResourceKey `json:"resource"`
	DefinitionDigest Digest             `json:"definitionDigest"`
}

DependencyCandidateRef is the durable, app-local representation of a dependency candidate. Canonical definition bodies are deliberately excluded.

type DependencyExplanation 

type DependencyExplanation struct {
	Selector    ArtifactSelector
	Candidates  []DependencyCandidate
	Diagnostics []Diagnostic
}

DependencyExplanation preserves all candidates because Artifact Store does not choose feature-specific precedence rules.

type DependencyGraph 

type DependencyGraph struct {
	RootRecordID RecordID
	Nodes        map[Digest]CanonicalDefinition
	Edges        map[Digest][]DependencyExplanation
	Diagnostics  []Diagnostic
}

DependencyGraph is a diagnostic graph rooted at one record definition.

type DependencyResolutionState 

type DependencyResolutionState string
const (
	DependencyResolutionStateResolved  DependencyResolutionState = "resolved"
	DependencyResolutionStateMissing   DependencyResolutionState = "missing"
	DependencyResolutionStateAmbiguous DependencyResolutionState = "ambiguous"
)

type DependencySnapshotPublication 

type DependencySnapshotPublication struct {
	RootID                   RootID
	RecordID                 RecordID
	RootDefinitionDigest     Digest
	CatalogGeneration        uint64
	ExpectedRecordModifiedAt time.Time
	Snapshots                []ArtifactDependencySnapshot
}

DependencySnapshotPublication replaces one record's resolution snapshot for one root definition and catalog generation.

type Diagnostic 

type Diagnostic struct {
	Severity DiagnosticSeverity  `json:"severity"`
	Code     string              `json:"code"`
	Message  string              `json:"message"`
	Location *DiagnosticLocation `json:"location,omitempty"`
}

Diagnostic is a current, structured observation attached to a source, package, catalog resource, record, or catalog generation.

type DiagnosticLocation 

type DiagnosticLocation struct {
	Locator            SourceLocator      `json:"locator,omitempty"`
	SubresourceLocator SubresourceLocator `json:"subresourceLocator,omitempty"`
	Line               int                `json:"line,omitempty"`
	Column             int                `json:"column,omitempty"`
}

DiagnosticLocation identifies an optional source position for a diagnostic. It must never contain an absolute filesystem path.

type DiagnosticSeverity 

type DiagnosticSeverity string
const (
	DiagnosticSeverityError   DiagnosticSeverity = "error"
	DiagnosticSeverityWarning DiagnosticSeverity = "warning"
	DiagnosticSeverityInfo    DiagnosticSeverity = "info"
)

type Digest 

type Digest string

type DirectoryPublication 

type DirectoryPublication interface {
	MakeDirectory(
		ctx context.Context,
		relativePath PortablePath,
		mode uint32,
	) error
	WriteFile(
		ctx context.Context,
		relativePath PortablePath,
		mode uint32,
		content io.Reader,
	) error
	Commit(ctx context.Context) (publishedRootPath string, err error)
	Abort(ctx context.Context) error
}

DirectoryPublication represents an isolated staging directory. Commit must publish the staging tree atomically from a consumer's perspective. Abort must remove only staging state owned by this publication.

type DirectoryPublisher 

type DirectoryPublisher interface {
	BeginDirectoryPublication(
		ctx context.Context,
		publicationKey string,
		generation SourceGeneration,
	) (DirectoryPublication, error)
}

DirectoryPublisher is the write-side storage port used by the generic source materializer. A production implementation should be backed by verified LLMTools create, write, move, and delete operations.

type DirectoryScanRoot 

type DirectoryScanRoot struct {
	Root            SourceLocator `json:"root"`
	IncludePatterns []string      `json:"includePatterns"`
	Recursive       bool          `json:"recursive"`
}

DirectoryScanRoot selects regular files beneath a source-relative directory.

type EmbeddedFSDirectorySourceConfig 

type EmbeddedFSDirectorySourceConfig struct {
	ProviderKey string        `json:"providerKey"`
	RootLocator SourceLocator `json:"rootLocator"`
}

EmbeddedFSDirectorySourceConfig addresses an application-registered fs.FS provider. ProviderKey is app-local registration metadata; portable package contents remain ordinary files within that provider.

type ExportClosure 

type ExportClosure struct {
	DefinitionDigests []Digest
	Assets            []AssetManifestEntry
}

ExportClosure describes portable definition and asset content required to export a definition without relying on app-local source registrations.

type ExportedRecord 

type ExportedRecord struct {
	Record     ArtifactRecord
	Definition ArtifactDefinitionFile
	Closure    ExportClosure
}

ExportedRecord is the portable result of exporting an app-local record. The caller chooses where a MapStore-backed package repository persists it.

type FSDirectorySourceConfig 

type FSDirectorySourceConfig struct {
	RootPath       string `json:"rootPath"`
	FollowSymlinks bool   `json:"followSymlinks"`
	ManagedByApp   bool   `json:"managedByApp"`
}

FSDirectorySourceConfig is app-local configuration for a filesystem source. RootPath is deliberately allowed only here, never in portable definitions.

type ForkRecordRequest 

type ForkRecordRequest struct {
	OriginRecordID      RecordID
	Destination         TransferDestination
	MaterializationMode TransferMaterializationMode
}

type FrontendID 

type FrontendID string

type FrontendVersionMatcher 

type FrontendVersionMatcher interface {
	MatchesVersionConstraint(
		ctx context.Context,
		constraint string,
		version LogicalVersion,
	) (bool, error)
}

FrontendVersionMatcher lets a frontend own version syntax for definitions it emitted. It takes precedence over a kind-wide registered matcher.

type ImportDefinitionRequest 

type ImportDefinitionRequest struct {
	File        ArtifactDefinitionFile
	Assets      []PortableAssetContent
	Destination TransferDestination
}

type LogicalName 

type LogicalName string

type LogicalVersion 

type LogicalVersion string

type MaterializeSourceRequest 

type MaterializeSourceRequest struct {
	SourceID       SourceID
	Root           SourceLocator
	PublicationKey string
	MaxEntries     int
	MaxFiles       int
	MaxBytes       int64
}

MaterializeSourceRequest requests a stable real-directory projection of a source. PublicationKey is app-local and must not be placed in portable data.

type MaterializedSource 

type MaterializedSource struct {
	PublicationKey string
	RootPath       string
	Generation     SourceGeneration
	Entries        int
	Files          int
	Bytes          int64
}

MaterializedSource is an app-local runtime projection. RootPath must never be written into portable definitions or package manifests.

type MemoryDirectorySourceConfig 

type MemoryDirectorySourceConfig struct {
	ProviderKey string        `json:"providerKey"`
	RootLocator SourceLocator `json:"rootLocator"`
}

MemoryDirectorySourceConfig is test-only configuration for an application-registered in-memory directory provider.

type PortableAssetContent 

type PortableAssetContent struct {
	Manifest AssetManifestEntry
	Content  []byte
}

type PortableContentRepository 

type PortableContentRepository interface {
	Close() error
	PutDefinition(ctx context.Context, file ArtifactDefinitionFile) (CanonicalDefinition, error)
	GetDefinition(ctx context.Context, digest Digest) (CanonicalDefinition, error)
	PutAsset(ctx context.Context, content []byte) (Digest, int64, error)
	GetAsset(ctx context.Context, digest Digest) ([]byte, error)
	PutPackageManifest(ctx context.Context, key string, manifest PortablePackageManifest) error
	GetPackageManifest(ctx context.Context, key string) (PortablePackageManifest, error)
}

PortableContentRepository is the boundary for shareable JSON/files. Its implementation must use approved MapStore APIs and never direct filesystem calls from Artifact Store business logic.

type PortablePackageDefinitionRef 

type PortablePackageDefinitionRef struct {
	Digest Digest       `json:"digest"`
	File   PortablePath `json:"file"`
}

PortablePackageDefinitionRef maps a definition digest to a JSON file inside a portable package directory or archive.

type PortablePackageManifest 

type PortablePackageManifest struct {
	Format      string         `json:"format"`
	Name        LogicalName    `json:"name"`
	Version     LogicalVersion `json:"version"`
	DisplayName string         `json:"displayName,omitempty"`
	Description string         `json:"description,omitempty"`

	Definitions []PortablePackageDefinitionRef `json:"definitions,omitempty"`
	Assets      []AssetManifestEntry           `json:"assets,omitempty"`
	Extensions  json.RawMessage                `json:"extensions"`
}

PortablePackageManifest is the shareable JSON package manifest. It contains no source IDs, root IDs, record IDs, local paths, app state, or secrets.

type PortablePath 

type PortablePath string

type ProvenanceID 

type ProvenanceID string

type Recognition 

type Recognition int

Recognition ranks a frontend's confidence that it owns a candidate. 

const (
	RecognitionNone Recognition = iota
	RecognitionPossible
	RecognitionPreferred
)

type RecordDerivation 

type RecordDerivation struct {
	CollectionID *CollectionID
	Name         RecordName
	Version      RecordVersion
	Enabled      bool
	DataSchemaID SchemaID
	Data         json.RawMessage
}

RecordDerivation is a policy-owned set of local values for a record created by synchronization.

type RecordID 

type RecordID string

type RecordMode 

type RecordMode string
const (
	RecordModeLinked          RecordMode = "linked"
	RecordModeCaptured        RecordMode = "captured"
	RecordModeForked          RecordMode = "forked"
	RecordModeAppLocal        RecordMode = "app-local"
	RecordModeEmbeddedOverlay RecordMode = "embedded-overlay"
)

type RecordName 

type RecordName string

type RecordState 

type RecordState string
const (
	RecordStateAvailable    RecordState = "available"
	RecordStateStale        RecordState = "stale"
	RecordStateMissing      RecordState = "missing"
	RecordStateInvalid      RecordState = "invalid"
	RecordStateIncompatible RecordState = "incompatible"
)

type RecordSyncPolicy 

type RecordSyncPolicy interface {
	DeriveRecord(
		ctx context.Context,
		root ArtifactRoot,
		resource CatalogResource,
		definition CanonicalDefinition,
	) (RecordDerivation, bool, []Diagnostic)
}

RecordSyncPolicy chooses whether a catalog resource should create a local linked record and, if so, its app-local placement and data.

type RecordSyncResult 

type RecordSyncResult struct {
	RootID      RootID
	Created     []RecordID
	Updated     []RecordID
	Diagnostics []Diagnostic
}

RecordSyncResult describes record synchronization after catalog publication.

type RecordSynchronizationPublication 

type RecordSynchronizationPublication struct {
	RootID                    RootID
	ExpectedCatalogGeneration uint64
	Creates                   []ArtifactRecord
	Updates                   []RecordSynchronizationUpdate
}

RecordSynchronizationPublication commits one root synchronization as a single app-metadata transaction. Portable definition content is already content-addressed and is not part of this transaction.

type RecordSynchronizationUpdate 

type RecordSynchronizationUpdate struct {
	Record               ArtifactRecord
	ExpectedModifiedAt   time.Time
	ExpectedRecordMode   RecordMode
	ExpectedTrackingMode TrackingMode
}

RecordSynchronizationUpdate is an optimistic source-state update. Expected values prevent synchronization from overwriting a concurrent local record mutation such as pinning, detaching, or moving a record.

type RecordTransferPublication 

type RecordTransferPublication struct {
	Resource                          CatalogResource
	Revision                          CatalogResourceRevision
	Record                            ArtifactRecord
	Provenance                        TransferProvenance
	ExpectedSourceModifiedAt          time.Time
	ExpectedSourceObservationRevision uint64
	ExpectedAttachmentModifiedAt      time.Time
}

RecordTransferPublication atomically publishes the app-local metadata for an imported, captured, or forked record. The portable definition is immutable content and may be persisted before this transaction without compromising metadata consistency.

type RecordUpdate 

type RecordUpdate struct {
	ExpectedModifiedAt time.Time
	CollectionID       *CollectionID
	ClearCollection    bool
	Enabled            *bool
	DataSchemaID       *SchemaID
	Data               *json.RawMessage
}

RecordUpdate replaces mutable app-local record fields. ClearCollection is explicit because a nil CollectionID otherwise cannot distinguish clear from leave-unchanged semantics.

type RecordVersion 

type RecordVersion string

type RootCatalogGeneration 

type RootCatalogGeneration struct {
	RootID            RootID                        `json:"rootID"`
	Generation        uint64                        `json:"generation"`
	SourceGenerations map[SourceID]SourceGeneration `json:"sourceGenerations"`
	ScanPlanDigest    Digest                        `json:"scanPlanDigest"`
	CatalogDigest     Digest                        `json:"catalogDigest"`
	CreatedAt         time.Time                     `json:"createdAt"`
	Diagnostics       []Diagnostic                  `json:"diagnostics,omitempty"`
}

RootCatalogGeneration is app-local durable scan-publication metadata. Its natural key is RootID + Generation.

type RootCatalogPublication 

type RootCatalogPublication struct {
	RootID            RootID
	SourceGenerations map[SourceID]SourceGeneration
	ScanPlanDigest    Digest
	CatalogDigest     Digest
	CreatedAt         time.Time
	Diagnostics       []Diagnostic
}

RootCatalogPublication records a durable root-level catalog generation after one or more source publications have completed.

type RootDraft 

type RootDraft struct {
	Kind         RootKind
	DisplayName  string
	Description  string
	Enabled      bool
	DataSchemaID SchemaID
	Data         json.RawMessage
}

RootDraft is the caller-provided portion of a newly created root.

type RootID 

type RootID string

type RootKind 

type RootKind string

type RootKindHook 

type RootKindHook interface {
	Kind() RootKind
	ValidateRootData(ctx context.Context, root ArtifactRoot) []Diagnostic
	ValidateSourceAttachment(
		ctx context.Context,
		root ArtifactRoot,
		attachment RootSourceAttachment,
	) []Diagnostic
}

RootKindHook validates app-local typed root data and source attachment rules.

type RootScanAttachmentExpectation 

type RootScanAttachmentExpectation struct {
	SourceID   SourceID
	ModifiedAt time.Time
	Enabled    bool
}

RootScanAttachmentExpectation protects a scan against concurrent attachment changes, including attaching or detaching another source.

type RootScanPublication 

type RootScanPublication struct {
	RootCatalog            RootCatalogPublication
	ExpectedRootModifiedAt time.Time
	Attachments            []RootScanAttachmentExpectation
	Sources                []RootScanSourceExpectation
	SourceCatalogs         []SourceCatalogPublication
	CatalogResources       []CatalogResource
}

RootScanPublication atomically publishes all source observations and the resulting root generation. CatalogResources is the exact root-local snapshot calculated by the business layer. The repository verifies it against the post-publication source catalog before committing.

type RootScanSourceExpectation 

type RootScanSourceExpectation struct {
	SourceID            SourceID
	ModifiedAt          time.Time
	ObservationRevision uint64
	Enabled             bool
}

RootScanSourceExpectation protects both source configuration and mutable source observation state used to construct a root catalog snapshot.

type RootSourceAttachment 

type RootSourceAttachment struct {
	RootID   RootID         `json:"rootID"`
	SourceID SourceID       `json:"sourceID"`
	Role     AttachmentRole `json:"role"`
	Priority int            `json:"priority"`
	Enabled  bool           `json:"enabled"`

	DataSchemaID SchemaID        `json:"dataSchemaID,omitempty"`
	Data         json.RawMessage `json:"data"`

	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`
}

RootSourceAttachment is app-local metadata with the natural key RootID + SourceID.

type ScanPlan 

type ScanPlan struct {
	SourcePlans []SourceScanPlan `json:"sourcePlans"`
}

ScanPlan is supplied by a consumer feature. With no source plans, ScanRoot performs an authoritative recursive scan of every enabled attachment.

type ScanResult 

type ScanResult struct {
	RootID      RootID
	Generation  RootCatalogGeneration
	Sources     []SourceScanResult
	Diagnostics []Diagnostic
}

ScanResult describes a published root catalog generation.

type SchemaID 

type SchemaID string

type SourceCatalogPublication 

type SourceCatalogPublication struct {
	SourceID                    SourceID
	ExpectedSourceModifiedAt    time.Time
	ExpectedObservationRevision uint64
	ObservedGeneration          SourceGeneration
	ObservedAt                  time.Time
	Diagnostics                 []Diagnostic
	Resources                   []CatalogResource
	Revisions                   []CatalogResourceRevision
	Authoritative               bool
}

SourceCatalogPublication is the driver-independent result of observing one source. A repository publishes it atomically to app-local metadata.

type SourceConfigNormalizer 

type SourceConfigNormalizer interface {
	NormalizeConfig(
		ctx context.Context,
		config json.RawMessage,
	) (json.RawMessage, []Diagnostic)
}

SourceConfigNormalizer optionally canonicalizes source-kind-specific configuration before it is validated and persisted. Normalization must be deterministic and must not access source content.

type SourceDraft 

type SourceDraft struct {
	Kind           SourceKind
	DisplayName    string
	Enabled        bool
	ConfigSchemaID SchemaID
	Config         json.RawMessage
}

SourceDraft is the caller-provided portion of a newly created source.

type SourceDriver 

type SourceDriver interface {
	Kind() SourceKind

	ValidateConfig(ctx context.Context, config json.RawMessage) []Diagnostic
	Snapshot(ctx context.Context, source ArtifactSource) (SourceGeneration, error)
	Open(ctx context.Context, source ArtifactSource, locator SourceLocator) (io.ReadCloser, error)
	Stat(ctx context.Context, source ArtifactSource, locator SourceLocator) (SourceEntry, error)
	ReadDir(ctx context.Context, source ArtifactSource, locator SourceLocator) ([]SourceEntry, error)
	Walk(ctx context.Context, source ArtifactSource, root SourceLocator, walk WalkFunc) error
}

SourceDriver owns source transport, traversal safety, and generation calculation for one Artifact Store-owned source kind.

type SourceEntry 

type SourceEntry struct {
	Locator     SourceLocator
	Name        string
	Mode        uint32
	SizeBytes   int64
	ModifiedAt  time.Time
	IsDirectory bool
	IsRegular   bool
	IsSymlink   bool
}

SourceEntry is a driver-provided, source-relative directory entry.

type SourceGeneration 

type SourceGeneration string

type SourceID 

type SourceID string

type SourceKind 

type SourceKind string
const (
	SourceKindFSDirectory         SourceKind = "fs-directory"
	SourceKindEmbeddedFSDirectory SourceKind = "embedded-fs-directory"
	SourceKindMemoryDirectory     SourceKind = "memory-directory"
)

type SourceLocator 

type SourceLocator string

type SourceMaterializationInput 

type SourceMaterializationInput struct {
	Source         ArtifactSource
	Driver         SourceDriver
	Root           SourceLocator
	PublicationKey string
	MaxEntries     int
	MaxFiles       int
	MaxBytes       int64
}

SourceMaterializationInput is passed to the injected source materializer. Driver remains the sole source transport implementation.

type SourceMaterializer 

type SourceMaterializer interface {
	Materialize(
		ctx context.Context,
		input SourceMaterializationInput,
	) (MaterializedSource, error)
}

SourceMaterializer copies a SourceDriver snapshot into a real directory publication. Implementations must not use direct operating-system filesystem APIs from Artifact Store business logic.

type SourceScanPlan 

type SourceScanPlan struct {
	SourceID            SourceID            `json:"sourceID"`
	ExplicitLocators    []SourceLocator     `json:"explicitLocators,omitempty"`
	DirectoryRoots      []DirectoryScanRoot `json:"directoryRoots,omitempty"`
	AllowedFrontendIDs  []FrontendID        `json:"allowedFrontendIDs,omitempty"`
	MaxFileBytes        int64               `json:"maxFileBytes,omitempty"`
	MaxCandidates       int                 `json:"maxCandidates,omitempty"`
	MaxTraversalEntries int                 `json:"maxTraversalEntries,omitempty"`
	MaxTraversalDepth   int                 `json:"maxTraversalDepth,omitempty"`
	Authoritative       bool                `json:"authoritative,omitempty"`
}

SourceScanPlan controls candidate discovery for one attached source. An authoritative plan marks previously known resources outside this result as missing; partial scans must leave Authoritative false.

type SourceScanResult 

type SourceScanResult struct {
	SourceID         SourceID
	Generation       SourceGeneration
	Candidates       int
	ValidResources   int
	InvalidResources int
	Diagnostics      []Diagnostic
}

SourceScanResult summarizes one source observation in a root scan.

type SubresourceLocator 

type SubresourceLocator string

type TrackingMode 

type TrackingMode string
const (
	TrackingModeFollowSource  TrackingMode = "follow-source"
	TrackingModePinDigest     TrackingMode = "pin-digest"
	TrackingModeManualRefresh TrackingMode = "manual-refresh"
)

type TransferDestination 

type TransferDestination struct {
	RootID       RootID
	CollectionID *CollectionID

	SourceID           SourceID
	Locator            SourceLocator
	SubresourceLocator SubresourceLocator

	Name    RecordName
	Version RecordVersion
	Enabled bool

	DataSchemaID SchemaID
	Data         json.RawMessage

	FrontendID             FrontendID
	PackageManifestLocator SourceLocator
}

TransferDestination is the complete app-local destination for import, capture, and fork. Artifact Store derives kind and pinned digest from the portable definition.

type TransferMaterializationMode 

type TransferMaterializationMode string
const (
	TransferMaterializeDefinitionOnly TransferMaterializationMode = "definition-only"
	TransferMaterializeExportClosure  TransferMaterializationMode = "export-closure"
)

type TransferOperation 

type TransferOperation string
const (
	TransferOperationImport  TransferOperation = "import"
	TransferOperationCapture TransferOperation = "capture"
	TransferOperationFork    TransferOperation = "fork"
)

type TransferProvenance 

type TransferProvenance struct {
	ProvenanceID   ProvenanceID      `json:"provenanceID"`
	TargetRecordID RecordID          `json:"targetRecordID"`
	Operation      TransferOperation `json:"operation"`

	OriginRecordID         *RecordID           `json:"originRecordID,omitempty"`
	OriginResource         *CatalogResourceKey `json:"originResource,omitempty"`
	OriginDefinitionDigest Digest              `json:"originDefinitionDigest"`

	CreatedAt time.Time `json:"createdAt"`
}

TransferProvenance is app-local audit metadata for a record created through import, capture, or fork. It does not alter portable definition content.

type WalkFunc 

type WalkFunc func(context.Context, SourceEntry) error

WalkFunc receives one source-relative entry during SourceDriver.Walk.

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.