providerapi

type AdoptionDecision ¶

type AdoptionDecision struct {
	Adopt       bool
	Name        string
	Enabled     bool
	Data        json.RawMessage
	Diagnostics []diagnostic.Diagnostic
}

AdoptionDecision is provider-owned semantic intent. Artifact Store owns artifact ID generation, artifact construction, validation, persistence, reconciliation, revisions, and timestamps.

func (d AdoptionDecision) Clone() AdoptionDecision

func (d AdoptionDecision) Validate() error

type AdoptionInput ¶

type AdoptionInput struct {
	Collection Collection
	Attachment Attachment
	Occurrence Occurrence
	Definition definition.Definition
}

AdoptionInput contains one valid source occurrence that Artifact Store is considering for automatic artifact adoption.

func (i AdoptionInput) Clone() AdoptionInput

type Attachment ¶

type Attachment struct {
	RootID       root.RootID               `json:"rootID"`
	CollectionID collection.CollectionID   `json:"collectionID"`
	SourceID     source.SourceID           `json:"sourceID"`
	Role         collection.AttachmentRole `json:"role"`
	Enabled      bool                      `json:"enabled"`
	Revision     uint64                    `json:"revision"`
	Data         json.RawMessage           `json:"data"`
}

Attachment is a provider-safe view of a persisted Collection attachment.

func (a Attachment) Clone() Attachment

type Candidate ¶

type Candidate struct {
	SourceID            source.SourceID
	SourceKind          source.SourceKind
	Locator             basespec.Locator
	SourceContentDigest cryptoutil.Digest
	Content             []byte
	RequestedDecoderIDs []basespec.DecoderID
}

Candidate is one bounded source entry selected by Artifact Store discovery.

Artifact Store owns snapshot opening, bounded reads, source-content digest calculation, and source generation confirmation. A decoder receives only the candidate bytes and generic source identity.

func (c Candidate) RequestsDecoder(id basespec.DecoderID) bool

type Collection ¶

type Collection struct {
	ID          collection.CollectionID   `json:"id"`
	RootID      root.RootID               `json:"rootID"`
	Kind        collection.CollectionKind `json:"kind"`
	DisplayName string                    `json:"displayName"`
	Description string                    `json:"description,omitempty"`
	Enabled     bool                      `json:"enabled"`
	Revision    uint64                    `json:"revision"`
	Data        json.RawMessage           `json:"data"`
}

Collection is a provider-safe view of a persisted Collection.

It deliberately excludes repositories, SQLite handles, source config, and feature-private runtime state.

func (c Collection) Clone() Collection

type CollectionBehavior ¶

type CollectionBehavior interface {
	CollectionKind() collection.CollectionKind

	// Revision must change whenever provider behavior can alter discovery
	// scope, decoder selection, automatic-adoption eligibility, or default
	// local artifact data.
	Revision() string

	DecideAutomaticAdoption(
		ctx context.Context,
		input AdoptionInput,
	) (AdoptionDecision, error)
}

CollectionBehavior is the common Artifact Store inbound behavior for one CollectionKind.

Artifact Store validates generic Collection, Attachment, and Source values before invoking a behavior. A behavior owns collection-kind-specific semantics and must additionally implement exactly one planning role below.

It receives immutable generic views and returns declarations. It must not perform direct Artifact Store mutations or depend on system.Components.

type CollectionPlanner ¶

type CollectionPlanner interface {
	CollectionBehavior

	BuildDiscoveryPlan(
		ctx context.Context,
		collection Collection,
		attachments []Attachment,
		sources []Source,
	) (Plan, error)
}

CollectionPlanner is the normal provider planning role. It receives only persisted generic views and returns a declarative discovery plan.

type Decoded ¶

type Decoded struct {
	SubresourceLocator basespec.SubresourceLocator
	Definition         definition.Definition
	Diagnostics        []diagnostic.Diagnostic
}

Decoded is one provider-derived definition emitted from a source candidate.

type Decoder ¶

type Decoder interface {
	ID() basespec.DecoderID
	Revision() string

	Recognize(
		ctx context.Context,
		candidate Candidate,
	) Recognition

	Decode(
		ctx context.Context,
		candidate Candidate,
	) ([]Decoded, []diagnostic.Diagnostic)
}

Decoder is an Artifact Store inbound content-decoding plugin.

Artifact Store owns decoder selection, read limits, content hashing, occurrence state transitions, definition persistence, and catalog publication. The decoder owns format recognition and semantic projection.

type DecoderHint ¶

type DecoderHint struct {
	Locator    basespec.Locator     `json:"locator"`
	Recursive  bool                 `json:"recursive"`
	DecoderIDs []basespec.DecoderID `json:"decoderIDs"`
}

DecoderHint identifies decoders preferred for a source-relative scope.

func (h DecoderHint) Clone() DecoderHint

type Descriptor ¶

type Descriptor struct {
	Name string

	CollectionBehaviors []CollectionBehavior
	Schemas             []SchemaCodec
	Decoders            []Decoder
}

Descriptor is immutable provider registration metadata.

CollectionKinds establishes exclusive ownership of persisted collection kinds through executable CollectionBehavior implementations.

func (d Descriptor) Clone() Descriptor

func (d Descriptor) Validate() error

type DirectoryRoot ¶

type DirectoryRoot struct {
	Root            basespec.Locator `json:"root"`
	Recursive       bool             `json:"recursive"`
	IncludePatterns []string         `json:"includePatterns,omitempty"`
}

DirectoryRoot declares one source-relative directory discovery scope.

func (r DirectoryRoot) Clone() DirectoryRoot

func (r DirectoryRoot) Validate() error

type DocumentPlanningBehavior ¶

type DocumentPlanningBehavior interface {
	CollectionBehavior

	BuildDiscoveryPlanWithDocuments(
		ctx context.Context,
		collection Collection,
		attachments []Attachment,
		sources []Source,
		documents PlanningDocumentReader,
	) (Plan, error)
}

DocumentPlanningBehavior is the exceptional planning role for collection kinds whose declared discovery scope depends on one source-owned canonical document. Workspace implements this for workspace.json.

The supplied reader is intentionally narrower than source.Runtime. It can read only canonical documents through Artifact Store controls.

type EntityCanonicalizer ¶

type EntityCanonicalizer interface {
	CanonicalizeEntity(
		ctx context.Context,
		entity schema.EntityType,
		raw []byte,
	) (schema.ParsedDocument, error)
}

EntityCanonicalizer supports dispatch by an entity type inferred from a caller-owned context.

type ExpectedCanonicalizer ¶

type ExpectedCanonicalizer interface {
	CanonicalizeExpected(
		ctx context.Context,
		expected schema.Key,
		raw []byte,
	) (schema.ParsedDocument, error)
}

ExpectedCanonicalizer is the narrow Artifact Store capability required by a provider that accepts a document with a known schema identity.

type Occurrence ¶

type Occurrence struct {
	RootID             root.RootID                 `json:"rootID"`
	CollectionID       collection.CollectionID     `json:"collectionID"`
	SourceID           source.SourceID             `json:"sourceID"`
	Locator            basespec.Locator            `json:"locator"`
	SubresourceLocator basespec.SubresourceLocator `json:"subresourceLocator,omitempty"`
	Kind               artifact.ArtifactKind       `json:"kind"`
}

Occurrence is the provider-safe observation supplied to automatic adoption.

type Plan ¶

type Plan struct {
	// Revision identifies provider-owned discovery behavior. Artifact Store
	// includes it in the catalog plan fingerprint.
	Revision string       `json:"revision,omitempty"`
	Sources  []SourcePlan `json:"sources"`
}

Plan is a provider-owned declaration of source discovery scope.

Artifact Store validates and converts this contract into its internal discovery.Plan before it opens source snapshots or publishes a catalog.

func (p Plan) BySource() map[source.SourceID]SourcePlan

func (p Plan) Clone() Plan

func (p Plan) Fingerprint() (cryptoutil.Digest, error)

func (p Plan) Normalized() Plan

func (p Plan) Validate() error

type PlanningDocument ¶

type PlanningDocument struct {
	SourceID   source.SourceID
	Generation string
	Found      bool
	Document   *schema.ParsedDocument
}

PlanningDocument is a Store-verified result of a planning document read.

A missing document is represented by Found=false and Document=nil. The confirmed Source generation is returned in both the found and missing cases so the provider can place it into the resulting SourcePlan as an optimistic precondition.

func (d PlanningDocument) Clone() PlanningDocument

func (d PlanningDocument) Validate() error

type PlanningDocumentReader ¶

type PlanningDocumentReader interface {
	ReadCanonicalDocument(
		ctx context.Context,
		request PlanningDocumentRequest,
	) (PlanningDocument, error)
}

PlanningDocumentReader is the only source-read capability available to a document-aware collection planner.

Artifact Store validates that the requested Source is attached to the Collection, opens and confirms the snapshot, bounds the read, dispatches the expected schema codec, and closes the snapshot. Providers never receive source configuration, source paths, a Snapshot, or raw filesystem access.

type PlanningDocumentRequest ¶

type PlanningDocumentRequest struct {
	SourceID       source.SourceID
	Locator        basespec.Locator
	ExpectedSchema schema.Key
}

PlanningDocumentRequest identifies one source-relative portable document needed to derive a provider discovery plan.

func (r PlanningDocumentRequest) Validate() error

type Provider ¶

type Provider interface {
	Descriptor() Descriptor
}

Provider is one Artifact Store inbound artifact-family registration.

It registers schemas, decoders, and collection-kind behavior without requiring Artifact Store to import the concrete provider package.

type Recognition ¶

type Recognition int

const (
	RecognitionNone Recognition = iota
	RecognitionPossible
	RecognitionPreferred
)

type SchemaCanonicalizerBinder ¶

type SchemaCanonicalizerBinder interface {
	RequiredSchemaKeys() []schema.Key

	BindExpectedCanonicalizer(
		schemas SchemaCatalog,
	) error
}

SchemaCanonicalizerBinder is optional. A decoder implements it when its source bytes must be canonicalized through the registered Artifact Store schema catalog before the decoder can project definitions.

This replaces direct decoder dependencies on *shareable.Registry.

type SchemaCatalog ¶

type SchemaCatalog interface {
	ExpectedCanonicalizer

	Keys() []schema.Key
}

SchemaCatalog is the narrow setup-time capability supplied to a decoder that must canonicalize source documents through Artifact Store's schema registry.

type SchemaCodec ¶

type SchemaCodec interface {
	Key() schema.Key
	JSONSchema() []byte

	Canonicalize(
		ctx context.Context,
		raw []byte,
	) (schema.ParsedDocument, error)
}

SchemaCodec supplies one published JSON Schema and domain-specific semantic canonicalization.

Artifact Store owns schema registration, schema execution, registry dispatch, canonical JSON checks, and output verification. The provider owns only its schema semantics and canonicalization rules.

type Source ¶

type Source struct {
	ID          source.SourceID     `json:"id"`
	RootID      root.RootID         `json:"rootID"`
	StorageKey  basespec.StorageKey `json:"storageKey"`
	Kind        source.SourceKind   `json:"kind"`
	DisplayName string              `json:"displayName"`
	Enabled     bool                `json:"enabled"`
	Revision    uint64              `json:"revision"`
}

Source is a provider-safe summary of an attached Source.

It deliberately excludes Source.Config. A collection provider decides discovery semantics from source identity and kind, while Artifact Store owns source configuration, snapshot opening, and filesystem access.

type SourcePlan ¶

type SourcePlan struct {
	SourceID               source.SourceID                        `json:"sourceID"`
	ExplicitLocators       []basespec.Locator                     `json:"explicitLocators,omitempty"`
	DirectoryRoots         []DirectoryRoot                        `json:"directoryRoots,omitempty"`
	DecoderHints           []DecoderHint                          `json:"decoderHints,omitempty"`
	ExpectedContentDigests map[basespec.Locator]cryptoutil.Digest `json:"expectedContentDigests,omitempty"`
	ExpectedGeneration     string                                 `json:"expectedGeneration,omitempty"`
	AllowedDecoderIDs      []basespec.DecoderID                   `json:"allowedDecoderIDs,omitempty"`
	Authoritative          bool                                   `json:"authoritative"`
	MaxCandidateBytes      int64                                  `json:"maxCandidateBytes"`
	MaxTotalBytes          int64                                  `json:"maxTotalBytes"`
	MaxCandidates          int                                    `json:"maxCandidates"`
	MaxEntries             int                                    `json:"maxEntries"`
	MaxDepth               int                                    `json:"maxDepth"`
}

SourcePlan declares discovery scope for one attached Source.

func (p SourcePlan) Clone() SourcePlan

func (p SourcePlan) Normalized() SourcePlan

func (p SourcePlan) RequestedDecoderIDs(
	locator basespec.Locator,
) []basespec.DecoderID

func (p SourcePlan) Validate() error