knowl

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package knowl contains the public, transport-neutral Knowl domain contracts.

Index

Constants

View Source 
const (
	// SourceTypeFilesystem selects the built-in filesystem source contract.
	SourceTypeFilesystem SourceType = "filesystem"
	// SourceTypeGit selects the remote Git source contract.
	SourceTypeGit SourceType = "git"
	// SourceFlavorMarkdown preserves ordinary Markdown references.
	SourceFlavorMarkdown = "markdown"
	// SourceFlavorObsidian enables Obsidian reference normalization.
	SourceFlavorObsidian = "obsidian"
	// SourceFlavorOKF preserves validated Open Knowledge Format semantics.
	SourceFlavorOKF = "okf"
	// GitRefKindBranch identifies branch ref tracking.
	GitRefKindBranch = "branch"
	// GitRefKindTag identifies tag ref tracking.
	GitRefKindTag = "tag"
)
View Source 
const (
	DiagnosticCitationUnknownSource   = "citation.unknown_source"
	DiagnosticOriginalLinkUnresolved  = "link.original_unresolved"
	DiagnosticCatalogDependencyReject = "catalog.dependency_rejected"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptedSource 

type AcceptedSource struct {
	Scope          ScopeRef       `json:"scope"`
	Source         SourceRef      `json:"source"`
	Version        SourceVersion  `json:"version"`
	MediaType      string         `json:"media_type"`
	SourceDocument SourceDocument `json:"source_document,omitzero"`
	ManifestRef    string         `json:"manifest_ref"`
}

AcceptedSource describes an immutable source version stored in the workspace.

type ContentCommit 

type ContentCommit struct {
	OperationID string                  `json:"operation_id"`
	Generation  string                  `json:"generation"`
	Files       []string                `json:"files"`
	Snapshot    WorkspaceSnapshot       `json:"snapshot"`
	CommittedAt time.Time               `json:"committed_at"`
	Diagnostics []MaintenanceDiagnostic `json:"diagnostics,omitempty"`
}

ContentCommit describes a canonical workspace commit.

type Document added in v0.3.0 

type Document struct {
	DocumentRef
	Title     string `json:"title"`
	URI       string `json:"uri"`
	MediaType string `json:"media_type"`
	Content   []byte `json:"content"`
}

Document is one fetched immutable source revision.

type DocumentID added in v0.3.0 

type DocumentID string

DocumentID identifies one logical document within a configured source.

type DocumentPage added in v0.3.0 

type DocumentPage struct {
	Documents     []DocumentRef `json:"documents"`
	NextPageToken string        `json:"next_page_token,omitempty"`
}

DocumentPage is one deterministic page of source descriptors.

type DocumentRef added in v0.3.0 

type DocumentRef struct {
	ExternalID DocumentID        `json:"external_id"`
	Revision   string            `json:"revision"`
	Path       string            `json:"path"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

DocumentRef is a cheap source descriptor used before content is fetched.

type DocumentState added in v0.3.0 

type DocumentState struct {
	Scope                  ScopeRef       `json:"scope"`
	SourceID               SourceID       `json:"source_id"`
	DocumentID             DocumentID     `json:"document_id"`
	Revision               string         `json:"revision"`
	AcceptedSource         AcceptedSource `json:"accepted_source,omitempty"`
	MaintenanceRevision    string         `json:"maintenance_revision,omitempty"`
	MaintenanceOperationID OperationID    `json:"maintenance_operation_id,omitempty"`
	MaintenanceGeneration  string         `json:"maintenance_generation,omitempty"`
	MirrorPath             string         `json:"mirror_path,omitempty"`
	MirrorDigest           string         `json:"mirror_digest,omitempty"`
	LastSeenRunID          SyncRunID      `json:"last_seen_run_id"`
	Deleted                bool           `json:"deleted"`
	DeletedAt              time.Time      `json:"deleted_at,omitempty"`
	CreatedAt              time.Time      `json:"created_at"`
	UpdatedAt              time.Time      `json:"updated_at"`
}

DocumentState is the durable head or tombstone for one logical document.

type ExecutionDescriptor 

type ExecutionDescriptor struct {
	OperationID           OperationID                   `json:"operation_id"`
	Kind                  WorkKind                      `json:"kind,omitempty"`
	Source                AcceptedSource                `json:"source,omitzero"`
	Hierarchy             *HierarchyExecutionDescriptor `json:"hierarchy,omitempty"`
	Schema                SchemaDocument                `json:"schema"`
	MaintenanceGeneration string                        `json:"maintenance_generation,omitempty"`
}

ExecutionDescriptor contains the bounded durable inputs needed to resume an accepted operation. It is internal operational state, not a public operation read model.

type Failure 

type Failure struct {
	Class       string `json:"class"`
	Reason      string `json:"reason,omitempty"`
	OperationID string `json:"operation_id"`
}

Failure is a stable, redacted operation failure.

type FileEdit 

type FileEdit struct {
	Path           string `json:"path"`
	ExpectedDigest string `json:"expected_digest,omitempty"`
	Content        []byte `json:"content"`
}

FileEdit is one validated canonical workspace file replacement.

type FilesystemSourceConfig added in v0.3.0 

type FilesystemSourceConfig struct {
	Root    string   `json:"root"`
	Include []string `json:"include,omitempty"`
	Flavor  string   `json:"flavor,omitempty"`
	URIBase string   `json:"uri_base,omitempty"`
}

FilesystemSourceConfig configures a filesystem-backed source.

type GitAuthConfig added in v0.4.0 

type GitAuthConfig struct {
	SecretEnv string `json:"secret_env,omitempty"`
	KeyFile   string `json:"key_file,omitempty"`
}

GitAuthConfig configures credentials for Git source authentication.

type GitSourceConfig added in v0.4.0 

type GitSourceConfig struct {
	Remote           string        `json:"remote"`
	Ref              string        `json:"ref"`
	RefKind          string        `json:"ref_kind,omitempty"`
	Include          []string      `json:"include,omitempty"`
	Flavor           string        `json:"flavor,omitempty"`
	URIBase          string        `json:"uri_base,omitempty"`
	Auth             GitAuthConfig `json:"auth,omitempty"`
	AllowRewrite     bool          `json:"allow_rewrite,omitempty"`
	RebindAck        bool          `json:"rebind_ack,omitempty"`
	KnownHosts       []string      `json:"known_hosts,omitempty"`
	RepositoryID     string        `json:"repository_id,omitempty"`
	MaxTransferBytes int64         `json:"max_transfer_bytes,omitempty"`
	MaxCacheBytes    int64         `json:"max_cache_bytes,omitempty"`
}

GitSourceConfig configures a remote Git repository source.

type HierarchyCatalog added in v0.4.0 

type HierarchyCatalog struct {
	Path     string   `json:"path"`
	Digest   string   `json:"digest"`
	Title    string   `json:"title"`
	Children []string `json:"children,omitempty"`
}

HierarchyCatalog describes current catalog membership without exposing catalog Markdown to a semantic planner.

type HierarchyCatalogSpec added in v0.4.0 

type HierarchyCatalogSpec struct {
	Path     string   `json:"path"`
	Title    string   `json:"title"`
	Children []string `json:"children"`
}

HierarchyCatalogSpec is one desired managed catalog and its complete child membership. Paths are canonical workspace paths below wiki/.

type HierarchyExecutionDescriptor added in v0.4.0 

type HierarchyExecutionDescriptor struct {
	SnapshotDigest string `json:"snapshot_digest"`
	PlannerVersion string `json:"planner_version"`
}

HierarchyExecutionDescriptor is the bounded versioned payload needed to re-inspect and execute one reserved hierarchy snapshot.

type HierarchyInput added in v0.4.0 

type HierarchyInput struct {
	Scope           ScopeRef           `json:"scope"`
	SchemaDigest    string             `json:"schema_digest"`
	SnapshotDigest  string             `json:"snapshot_digest"`
	MinRootCatalogs int                `json:"min_root_catalogs,omitempty"`
	Pages           []HierarchyPage    `json:"pages"`
	Catalogs        []HierarchyCatalog `json:"catalogs"`
	Limits          HierarchyLimits    `json:"limits"`
}

HierarchyInput is the complete bounded context supplied for one hierarchy plan. MinRootCatalogs is zero for a trivial wiki and at least two when the caller has classified the workspace as multi-domain.

type HierarchyLimits added in v0.4.0 

type HierarchyLimits struct {
	MaxPages             int `json:"max_pages"`
	MaxCatalogs          int `json:"max_catalogs"`
	MaxEdges             int `json:"max_edges"`
	MaxDepth             int `json:"max_depth"`
	MaxInputBytes        int `json:"max_input_bytes"`
	MaxExcerptCharacters int `json:"max_excerpt_characters"`
	MaxPlanBytes         int `json:"max_plan_bytes"`
	MaxEdits             int `json:"max_edits"`
	MaxPathBytes         int `json:"max_path_bytes"`
	MaxCatalogBytes      int `json:"max_catalog_bytes"`
	MaxManifestBytes     int `json:"max_manifest_bytes"`
}

HierarchyLimits bounds semantic hierarchy planning and catalog rendering. A complete input must fit these limits; callers must not silently truncate it.

type HierarchyModelPlan added in v0.4.0 

type HierarchyModelPlan struct {
	SchemaDigest   string                 `json:"schema_digest"`
	SnapshotDigest string                 `json:"snapshot_digest"`
	Catalogs       []HierarchyCatalogSpec `json:"catalogs"`
}

HierarchyModelPlan is structured provider output before application validation and deterministic Markdown rendering.

type HierarchyMutation added in v0.4.0 

type HierarchyMutation struct {
	Action         SourceMutationAction `json:"action"`
	Path           string               `json:"path"`
	ExpectedDigest string               `json:"expected_digest,omitempty"`
	Content        []byte               `json:"content,omitempty"`
}

HierarchyMutation is one application-rendered managed catalog write or delete. A model never supplies this type directly.

type HierarchyPage added in v0.4.0 

type HierarchyPage struct {
	ID          PageID   `json:"id"`
	Path        string   `json:"path"`
	Digest      string   `json:"digest"`
	Type        string   `json:"type"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Excerpt     string   `json:"excerpt,omitempty"`
	Catalogs    []string `json:"catalogs,omitempty"`
}

HierarchyPage is bounded semantic context for one ordinary canonical page. It intentionally excludes raw source bytes and source-native paths.

type Lease 

type Lease struct {
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expires_at"`
}

Lease prevents duplicate worker completion.

type LinkReference 

type LinkReference struct {
	From      PageID `json:"from"`
	To        PageID `json:"to"`
	Relation  string `json:"relation"`
	Untrusted bool   `json:"untrusted"`
}

LinkReference is an untrusted bounded graph result.

type LintFinding 

type LintFinding struct {
	Code       string   `json:"code"`
	Severity   string   `json:"severity"`
	Path       string   `json:"path,omitempty"`
	PageID     PageID   `json:"page_id,omitempty"`
	Message    string   `json:"message"`
	Suggestion bool     `json:"suggestion,omitempty"`
	SourceRefs []string `json:"source_refs,omitempty"`
}

LintFinding is one deterministic or suggestion-only workspace diagnostic.

type LintReport 

type LintReport struct {
	Scope     ScopeRef      `json:"scope"`
	Findings  []LintFinding `json:"findings"`
	CheckedAt time.Time     `json:"checked_at"`
}

LintReport contains bounded, redacted workspace health findings.

func (LintReport) Healthy 

func (report LintReport) Healthy() bool

Healthy reports whether lint found no error or warning findings.

type MaintenanceCounts added in v0.3.0 

type MaintenanceCounts struct {
	Queued    int64 `json:"queued"`
	Retrying  int64 `json:"retrying"`
	Replayed  int64 `json:"replayed"`
	Committed int64 `json:"committed"`
	Failed    int64 `json:"failed"`
}

MaintenanceCounts summarizes the asynchronous operations reserved by the active documents of one configured source. Replayed counts operations with more than one durable worker attempt and may overlap another outcome.

type MaintenanceDiagnostic added in v0.5.0 

type MaintenanceDiagnostic struct {
	Code   string `json:"code" yaml:"code"`
	Path   string `json:"path" yaml:"path"`
	Target string `json:"target,omitempty" yaml:"target,omitempty"`
}

MaintenanceDiagnostic is bounded redacted metadata for a preserved warning or a document-local rejection.

type MaintenanceInput 

type MaintenanceInput struct {
	Scope      ScopeRef       `json:"scope"`
	Schema     SchemaDocument `json:"schema"`
	Source     AcceptedSource `json:"source"`
	SourceText string         `json:"source_text"`
	Pages      []PageSnapshot `json:"pages"`
	Catalogs   []PageSnapshot `json:"catalogs,omitempty"`
	Limits     ReadLimits     `json:"limits"`
}

MaintenanceInput is the bounded data supplied to a maintainer provider.

type MaintenanceSample added in v0.3.0 

type MaintenanceSample struct {
	DocumentID       DocumentID      `json:"document_id"`
	Revision         string          `json:"revision"`
	OperationID      OperationID     `json:"operation_id"`
	GenerationPrefix string          `json:"generation_prefix,omitempty"`
	Status           OperationStatus `json:"status"`
	Replayed         bool            `json:"replayed"`
	WorkAttempt      int             `json:"work_attempt"`
	RetryAttempt     int             `json:"retry_attempt"`
	ManualRetryCount int             `json:"manual_retry_count"`
	FailureClass     string          `json:"failure_class,omitempty"`
	FailureReason    string          `json:"failure_reason,omitempty"`
	NextRetryAt      time.Time       `json:"next_retry_at,omitempty"`
}

MaintenanceSample is one bounded, redacted source-to-operation correlation.

type ModelEditPlan 

type ModelEditPlan struct {
	SchemaDigest string     `json:"schema_digest"`
	SourceRefs   []string   `json:"source_refs"`
	Edits        []FileEdit `json:"edits"`
	Rationale    string     `json:"rationale,omitempty"`
}

ModelEditPlan is structured provider output before application validation.

type Operation 

type Operation struct {
	ID               OperationID             `json:"id"`
	Kind             WorkKind                `json:"kind,omitempty"`
	Key              OperationKey            `json:"key,omitzero"`
	Status           OperationStatus         `json:"status"`
	Attempt          int                     `json:"attempt"`
	WorkAttempt      int                     `json:"work_attempt"`
	RetryAttempt     int                     `json:"retry_attempt"`
	ManualRetryCount int                     `json:"manual_retry_count"`
	ReadyAt          time.Time               `json:"ready_at,omitempty"`
	Failure          *Failure                `json:"failure,omitempty"`
	Diagnostics      []MaintenanceDiagnostic `json:"diagnostics,omitempty"`
	UpdatedAt        time.Time               `json:"updated_at"`
}

Operation is a redacted operation read model.

type OperationID 

type OperationID string

OperationID identifies an ingest or filing operation.

type OperationIdentity added in v0.4.0 

type OperationIdentity struct {
	Scope    ScopeRef `json:"scope"`
	Kind     WorkKind `json:"kind"`
	Subject  string   `json:"subject"`
	Revision string   `json:"revision"`
	Digest   string   `json:"digest"`
}

OperationIdentity is the generic deterministic identity of durable work.

type OperationKey 

type OperationKey struct {
	Scope                 ScopeRef      `json:"scope"`
	Source                SourceRef     `json:"source"`
	Version               SourceVersion `json:"version"`
	MaintenanceGeneration string        `json:"maintenance_generation,omitempty"`
}

OperationKey is the idempotency identity for an immutable source revision.

type OperationMeta 

type OperationMeta struct {
	Key                   OperationKey   `json:"key"`
	AcceptedSource        AcceptedSource `json:"accepted_source"`
	Schema                SchemaDocument `json:"schema"`
	SchemaDigest          string         `json:"schema_digest"`
	MaintenanceGeneration string         `json:"maintenance_generation,omitempty"`
	CreatedAt             time.Time      `json:"created_at"`
}

OperationMeta contains the bounded internal inputs persisted at reservation.

type OperationStatus 

type OperationStatus string

OperationStatus is the lifecycle state of a maintenance operation. 

const (
	StatusReceived       OperationStatus = "received"
	StatusPlanned        OperationStatus = "planned"
	StatusAwaitingReview OperationStatus = "awaiting_review"
	StatusApplying       OperationStatus = "applying"
	StatusCommitted      OperationStatus = "committed"
	StatusFailed         OperationStatus = "failed"
)

type PageID 

type PageID string

PageID is a stable wiki page identifier.

type PageReference 

type PageReference struct {
	ID              PageID           `json:"id"`
	Path            string           `json:"path"`
	Title           string           `json:"title"`
	Snippet         string           `json:"snippet"`
	SourceRefs      []string         `json:"source_refs"`
	SourceDocument  *SourceDocument  `json:"source_document,omitempty"`
	SourceDocuments []SourceDocument `json:"source_documents,omitempty"`
	OKF             *okf.Metadata    `json:"okf,omitempty"`
	Untrusted       bool             `json:"untrusted"`
}

PageReference is an untrusted bounded search result.

type PageSnapshot 

type PageSnapshot struct {
	ID              PageID           `json:"id"`
	Path            string           `json:"path"`
	Digest          string           `json:"digest"`
	Title           string           `json:"title"`
	Content         string           `json:"content"`
	Body            string           `json:"body"`
	OKF             *okf.Metadata    `json:"okf,omitempty"`
	SourceRefs      []string         `json:"source_refs,omitempty"`
	SourceDocument  *SourceDocument  `json:"source_document,omitempty"`
	SourceDocuments []SourceDocument `json:"source_documents,omitempty"`
	Untrusted       bool             `json:"untrusted"`
	UpdatedAt       time.Time        `json:"updated_at"`
}

PageSnapshot is a bounded read of a canonical Markdown page.

type PlanSummary 

type PlanSummary struct {
	OperationID string                  `json:"operation_id"`
	Digest      string                  `json:"digest"`
	FileCount   int                     `json:"file_count"`
	CreatedAt   time.Time               `json:"created_at"`
	Diagnostics []MaintenanceDiagnostic `json:"diagnostics,omitempty"`
}

PlanSummary is the durable redacted summary of a model plan.

type RawSourceRecord 

type RawSourceRecord struct {
	Path          string         `json:"path"`
	Source        AcceptedSource `json:"source"`
	ContentDigest string         `json:"content_digest,omitempty"`
	Valid         bool           `json:"valid"`
	ErrorClass    string         `json:"error_class,omitempty"`
}

RawSourceRecord is a bounded, metadata-only inspection of one raw source version.

type ReadLimits 

type ReadLimits struct {
	Pages      int           `json:"pages"`
	Bytes      int           `json:"bytes"`
	Characters int           `json:"characters"`
	Depth      int           `json:"depth"`
	Deadline   time.Duration `json:"deadline"`
}

ReadLimits bounds context and retrieval operations.

type RecoveryResult 

type RecoveryResult struct {
	OperationID string `json:"operation_id"`
	Action      string `json:"action"`
	ErrorClass  string `json:"error_class,omitempty"`
}

RecoveryResult describes recovery of one interrupted content operation.

type SchemaDocument 

type SchemaDocument struct {
	Scope     ScopeRef  `json:"scope"`
	Digest    string    `json:"digest"`
	Version   string    `json:"version"`
	Content   []byte    `json:"content"`
	UpdatedAt time.Time `json:"updated_at"`
}

SchemaDocument is the operator-owned workspace policy document.

type ScopeRef 

type ScopeRef string

ScopeRef identifies an opaque knowledge scope. Knowl does not interpret it.

type Source added in v0.3.0 

type Source struct {
	ID           SourceID         `json:"id"`
	Type         SourceType       `json:"type"`
	Enabled      bool             `json:"enabled"`
	Config       SourceConfig     `json:"config"`
	Sync         SourceSyncPolicy `json:"sync"`
	ConfigDigest string           `json:"config_digest,omitempty"`
}

Source describes one configured authoritative source.

type SourceConfig added in v0.3.0 

type SourceConfig struct {
	Filesystem *FilesystemSourceConfig `json:"filesystem,omitempty"`
	Git        *GitSourceConfig        `json:"git,omitempty"`
}

SourceConfig is the typed configuration union for one source.

type SourceDiagnostic added in v0.3.0 

type SourceDiagnostic struct {
	Code            string `json:"code"`
	Path            string `json:"path"`
	ObservedVersion string `json:"observed_version,omitempty"`
}

SourceDiagnostic reports one bounded, non-fatal source compatibility observation without exposing source content or host filesystem paths.

type SourceDocument added in v0.3.0 

type SourceDocument struct {
	SourceID   SourceID   `json:"source_id" yaml:"source_id"`
	DocumentID DocumentID `json:"document_id" yaml:"document_id"`
	Revision   string     `json:"revision" yaml:"revision"`
	URI        string     `json:"uri" yaml:"uri"`
}

SourceDocument is the canonical provenance of one configured-source revision.

type SourceEnvelope 

type SourceEnvelope struct {
	Scope          ScopeRef       `json:"scope"`
	Source         SourceRef      `json:"source"`
	Version        SourceVersion  `json:"version"`
	MediaType      string         `json:"media_type"`
	SourceDocument SourceDocument `json:"source_document,omitzero"`
	Content        []byte         `json:"content"`
	Provenance     map[string]any `json:"provenance,omitempty"`
	ReceivedAt     time.Time      `json:"received_at"`
}

SourceEnvelope is the bounded input accepted from a source adapter.

type SourceID added in v0.3.0 

type SourceID string

SourceID identifies one configured authoritative knowledge source.

type SourceMaintenanceStatus added in v0.3.0 

type SourceMaintenanceStatus struct {
	Counts    MaintenanceCounts   `json:"counts"`
	Samples   []MaintenanceSample `json:"samples"`
	Truncated bool                `json:"truncated"`
}

SourceMaintenanceStatus separates raw sync reservation success from the asynchronous maintenance operation outcomes visible at read time.

type SourceMutation added in v0.3.0 

type SourceMutation struct {
	Action         SourceMutationAction `json:"action"`
	Path           string               `json:"path"`
	ExpectedDigest string               `json:"expected_digest,omitempty"`
	Content        []byte               `json:"content,omitempty"`
}

SourceMutation is one bounded write or delete in a source namespace.

type SourceMutationAction added in v0.3.0 

type SourceMutationAction string

SourceMutationAction selects one canonical source-owned filesystem action. 

const (
	// SourceMutationWrite replaces or creates one source-owned file.
	SourceMutationWrite SourceMutationAction = "write"
	// SourceMutationDelete removes one source-owned file while retaining recovery state.
	SourceMutationDelete SourceMutationAction = "delete"
)

type SourceMutationPlan added in v0.3.0 

type SourceMutationPlan struct {
	RunID     SyncRunID        `json:"run_id"`
	Scope     ScopeRef         `json:"scope"`
	SourceID  SourceID         `json:"source_id"`
	Mutations []SourceMutation `json:"mutations"`
}

SourceMutationPlan is one deterministic canonical mutation request.

type SourceRef 

type SourceRef struct {
	Adapter string `json:"adapter"`
	ID      string `json:"id"`
}

SourceRef identifies a source adapter and a stable source identity.

type SourceStatus added in v0.3.0 

type SourceStatus struct {
	Scope               ScopeRef                `json:"scope"`
	SourceID            SourceID                `json:"source_id"`
	Type                SourceType              `json:"type"`
	ConfigDigest        string                  `json:"config_digest"`
	Checkpoint          string                  `json:"checkpoint,omitempty"`
	AttemptCheckpoint   string                  `json:"attempt_checkpoint,omitempty"`
	LastAttemptRunID    SyncRunID               `json:"last_attempt_run_id,omitempty"`
	LastSuccessfulRunID SyncRunID               `json:"last_successful_run_id,omitempty"`
	Status              SyncStatus              `json:"status,omitempty"`
	Counts              SyncCounts              `json:"counts"`
	Maintenance         SourceMaintenanceStatus `json:"maintenance"`
	CreatedAt           time.Time               `json:"created_at"`
	LastAttemptAt       time.Time               `json:"last_attempt_at,omitempty"`
	LastSuccessfulAt    time.Time               `json:"last_successful_at,omitempty"`
	UpdatedAt           time.Time               `json:"updated_at"`
	// RepositoryIdentity is an internal credential-free lineage binding. It is
	// intentionally excluded from operator-facing status serialization.
	RepositoryIdentity string `json:"-"`
}

SourceStatus is a bounded, redacted status for one configured source.

type SourceSummary 

type SourceSummary struct {
	Source  SourceRef     `json:"source"`
	Version SourceVersion `json:"version"`
	Title   string        `json:"title"`
}

SourceSummary is bounded source context for a maintainer or index.

type SourceSyncPolicy added in v0.3.0 

type SourceSyncPolicy struct {
	OnStart      bool          `json:"on_start"`
	Interval     time.Duration `json:"interval,omitempty"`
	RetryInitial time.Duration `json:"retry_initial,omitempty"`
	RetryMaximum time.Duration `json:"retry_maximum,omitempty"`
}

SourceSyncPolicy controls on-start, periodic, and bounded retry scheduling.

type SourceType added in v0.3.0 

type SourceType string

SourceType selects a source adapter family.

type SourceVersion 

type SourceVersion struct {
	Version string `json:"version"`
	Digest  string `json:"digest"`
}

SourceVersion identifies an immutable source revision.

type StagedChange 

type StagedChange struct {
	OperationID string                  `json:"operation_id"`
	Digest      string                  `json:"digest"`
	Files       []string                `json:"files"`
	CreatedAt   time.Time               `json:"created_at"`
	Diagnostics []MaintenanceDiagnostic `json:"diagnostics,omitempty"`
}

StagedChange identifies a plan staged for review or apply.

type StagedSourceMutation added in v0.3.0 

type StagedSourceMutation struct {
	RunID      SyncRunID `json:"run_id"`
	Scope      ScopeRef  `json:"scope"`
	SourceID   SourceID  `json:"source_id"`
	Generation string    `json:"generation"`
	Files      []string  `json:"files"`
	CreatedAt  time.Time `json:"created_at"`
}

StagedSourceMutation identifies one verified source-owned staged artifact.

type SyncCounts added in v0.3.0 

type SyncCounts struct {
	Added     int64 `json:"added"`
	Updated   int64 `json:"updated"`
	Unchanged int64 `json:"unchanged"`
	Deleted   int64 `json:"deleted"`
	Failed    int64 `json:"failed"`
}

SyncCounts summarizes reconciliation outcomes for one run.

type SyncRun added in v0.3.0 

type SyncRun struct {
	ID                SyncRunID  `json:"id"`
	Scope             ScopeRef   `json:"scope"`
	SourceID          SourceID   `json:"source_id"`
	ConfigDigest      string     `json:"config_digest"`
	Status            SyncStatus `json:"status"`
	Cursor            string     `json:"cursor,omitempty"`
	NextPageToken     string     `json:"next_page_token,omitempty"`
	CompleteScan      bool       `json:"complete_scan"`
	Counts            SyncCounts `json:"counts"`
	FailureClass      string     `json:"failure_class,omitempty"`
	ContentGeneration string     `json:"content_generation,omitempty"`
	Checkpoint        string     `json:"checkpoint,omitempty"`
	StartedAt         time.Time  `json:"started_at"`
	UpdatedAt         time.Time  `json:"updated_at"`
	CompletedAt       time.Time  `json:"completed_at,omitempty"`
}

SyncRun is the redacted durable read model for one synchronization attempt.

type SyncRunID added in v0.3.0 

type SyncRunID string

SyncRunID identifies one durable source synchronization attempt.

type SyncStatus added in v0.3.0 

type SyncStatus string

SyncStatus is the durable lifecycle status of one synchronization run. 

const (
	SyncStatusScanning         SyncStatus = "scanning"
	SyncStatusPrepared         SyncStatus = "prepared"
	SyncStatusContentCommitted SyncStatus = "content_committed"
	SyncStatusProjected        SyncStatus = "projected"
	SyncStatusSucceeded        SyncStatus = "succeeded"
	SyncStatusFailed           SyncStatus = "failed"
)

type ValidatedEditPlan 

type ValidatedEditPlan struct {
	OperationID       string                  `json:"operation_id"`
	Scope             ScopeRef                `json:"scope"`
	SchemaDigest      string                  `json:"schema_digest"`
	RequiredSourceRef string                  `json:"required_source_ref,omitempty"`
	SourceRefs        []string                `json:"source_refs"`
	Edits             []FileEdit              `json:"edits"`
	Diagnostics       []MaintenanceDiagnostic `json:"diagnostics,omitempty"`
}

ValidatedEditPlan is an application-validated model plan ready to stage.

type ValidatedHierarchyPlan added in v0.4.0 

type ValidatedHierarchyPlan struct {
	Scope          ScopeRef               `json:"scope"`
	SchemaDigest   string                 `json:"schema_digest"`
	SnapshotDigest string                 `json:"snapshot_digest"`
	Catalogs       []HierarchyCatalogSpec `json:"catalogs"`
	Mutations      []HierarchyMutation    `json:"mutations"`
}

ValidatedHierarchyPlan is a normalized semantic graph plus deterministic catalog-only mutations ready for a hierarchy content adapter.

type WorkClaim 

type WorkClaim struct {
	Operation  Operation           `json:"operation"`
	Descriptor ExecutionDescriptor `json:"descriptor"`
	Lease      WorkLease           `json:"lease"`
}

WorkClaim combines an exclusively claimed operation with its durable inputs.

type WorkKind added in v0.4.0 

type WorkKind string

WorkKind distinguishes durable source maintenance from hierarchy work. 

const (
	WorkSourceMaintenance WorkKind = "source"
	WorkHierarchy         WorkKind = "hierarchy"
)

type WorkLease 

type WorkLease struct {
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expires_at"`
}

WorkLease grants temporary ownership of application-level operation work. It is separate from Lease, which fences canonical content application.

type WorkspaceInspection 

type WorkspaceInspection struct {
	Scope      ScopeRef          `json:"scope"`
	Snapshot   WorkspaceSnapshot `json:"snapshot"`
	Index      PageSnapshot      `json:"index"`
	Catalogs   []PageSnapshot    `json:"catalogs,omitempty"`
	Log        PageSnapshot      `json:"log"`
	RawSources []RawSourceRecord `json:"raw_sources"`
}

WorkspaceInspection combines canonical projections needed by deterministic lint.

type WorkspaceSnapshot 

type WorkspaceSnapshot struct {
	Scope        ScopeRef          `json:"scope"`
	SchemaDigest string            `json:"schema_digest"`
	PageDigests  map[string]string `json:"page_digests"`
	Pages        []PageSnapshot    `json:"pages"`
	Links        []LinkReference   `json:"links"`
	CapturedAt   time.Time         `json:"captured_at"`
}

WorkspaceSnapshot identifies canonical content used to build projections.

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.