app

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package app owns Knowl application policy and its consuming ports.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrOperationNotApplyable = errors.New("operation is not ready to apply")
	ErrMaintainerUnavailable = errors.New("knowl maintainer is unavailable")
	ErrProjection            = errors.New("canonical content committed but projection failed")
)
View Source 
var (
	ErrPlanInvalid       = errors.New("invalid maintainer edit plan")
	ErrSchemaMismatch    = errors.New("edit plan schema digest mismatch")
	ErrForbiddenEdit     = errors.New("edit plan targets a forbidden path")
	ErrPlanLimitExceeded = errors.New("edit plan exceeds a limit")
)
View Source 
var (
	// ErrNoReadyOperation reports that durable work inspection found no claimable operation.
	ErrNoReadyOperation = errors.New("no ready Knowl operation")
	// ErrExecutionDescriptorUnavailable reports missing or invalid durable execution inputs.
	ErrExecutionDescriptorUnavailable = errors.New("knowl execution descriptor is unavailable")
	// ErrWorkLeaseConflict reports that another worker owns or replaced a work lease.
	ErrWorkLeaseConflict = errors.New("knowl operation work lease conflicts")
	// ErrStageNotFound reports that no complete staged artifact exists for an operation.
	ErrStageNotFound = errors.New("knowl staged artifact not found")
	// ErrApplyLeaseConflict reports that canonical application is still owned by another attempt.
	ErrApplyLeaseConflict = errors.New("knowl operation application lease conflicts")
)
View Source 
var (
	ErrQueryInvalid      = errors.New("invalid Knowl query")
	ErrPageNotFound      = errors.New("knowl page not found")
	ErrOperationNotFound = errors.New("knowl operation not found")
	ErrFilingInvalid     = errors.New("invalid explicit wiki filing")
)
View Source 
var (
	ErrSourceInvalid         = errors.New("invalid Knowl source")
	ErrSourceNotFound        = errors.New("knowl source not found")
	ErrSyncRunNotFound       = errors.New("knowl sync run not found")
	ErrSyncConflict          = errors.New("knowl sync state conflict")
	ErrSyncStateTransition   = errors.New("invalid Knowl sync state transition")
	ErrSourceMutationInvalid = errors.New("invalid Knowl source mutation")
	ErrSourceMutationLimit   = errors.New("knowl source mutation exceeds a limit")
)

Functions

func AddSyncCounts added in v0.3.0 

func AddSyncCounts(left, right knowl.SyncCounts) (knowl.SyncCounts, error)

AddSyncCounts accumulates reconciliation counters without permitting signed integer overflow to become valid-looking durable state.

func DefaultReadLimits 

func DefaultReadLimits() knowl.ReadLimits

DefaultReadLimits returns the local bounded context defaults.

func ExecutionDescriptorFromMeta 

func ExecutionDescriptorFromMeta(id knowl.OperationID, key knowl.OperationKey, meta knowl.OperationMeta) (knowl.ExecutionDescriptor, error)

ExecutionDescriptorFromMeta validates reservation inputs and builds the bounded descriptor that operational stores persist atomically.

func NormalizeSourceMutationPlan added in v0.3.0 

func NormalizeSourceMutationPlan(plan knowl.SourceMutationPlan) (knowl.SourceMutationPlan, error)

NormalizeSourceMutationPlan validates, copies, and deterministically orders a source-owned canonical plan before it reaches a content store.

func NormalizeSourcesFilter added in v0.3.0 

func NormalizeSourcesFilter(sources []knowl.SourceID) ([]knowl.SourceID, error)

NormalizeSourcesFilter returns a canonical bounded source identity filter. Empty input means unfiltered retrieval.

func PlanDigest 

func PlanDigest(plan knowl.ValidatedEditPlan) (string, error)

PlanDigest returns a deterministic digest of a validated plan.

func PreparedSyncDigest added in v0.3.0 

func PreparedSyncDigest(prepared PreparedSyncState) (string, error)

PreparedSyncDigest returns the canonical lowercase SHA-256 candidate digest of one prepared payload. The reconciliation service and both concrete stores recompute it so an arbitrary caller-supplied digest cannot bless different durable candidates. Timing fields are excluded; deleted timestamps are encoded at microsecond precision for backend parity.

func ResolveSourceDocument added in v0.3.0 

func ResolveSourceDocument(sourceID knowl.SourceID, accepted knowl.AcceptedSource, fallback knowl.SourceDocument) (knowl.SourceDocument, error)

ResolveSourceDocument returns persisted configured-source provenance, or a validated deterministic fallback for a legacy accepted manifest.

func SourceConfigDigest added in v0.3.0 

func SourceConfigDigest(source knowl.Source) (string, error)

SourceConfigDigest returns a deterministic one-way digest of normalized config.

func SourceRefKey 

func SourceRefKey(source knowl.AcceptedSource) string

SourceRefKey is the stable citation key required in a plan.

func ValidateDocument added in v0.3.0 

func ValidateDocument(document knowl.Document, maxContentBytes int) error

ValidateDocument validates one fetched adapter result against an explicit content limit and the common source metadata bounds.

func ValidateDocumentID added in v0.3.0 

func ValidateDocumentID(id knowl.DocumentID) error

ValidateDocumentID validates a canonical relative logical document identity.

func ValidateDocumentPage added in v0.3.0 

func ValidateDocumentPage(page knowl.DocumentPage, maxDocuments int) error

ValidateDocumentPage validates a bounded descriptor page returned by an adapter.

func ValidateDocumentRef added in v0.3.0 

func ValidateDocumentRef(ref knowl.DocumentRef) error

ValidateDocumentRef validates one untrusted source descriptor.

func ValidateExecutionDescriptor 

func ValidateExecutionDescriptor(key knowl.OperationKey, descriptor knowl.ExecutionDescriptor) error

ValidateExecutionDescriptor verifies durable execution identity and bounded schema content without exposing descriptor data in errors.

func ValidateOwnedSourceDocument added in v0.3.0 

func ValidateOwnedSourceDocument(sourceID knowl.SourceID, document knowl.SourceDocument) error

ValidateOwnedSourceDocument validates provenance against its configured owner.

func ValidatePlan 

func ValidatePlan(ctx context.Context, input knowl.MaintenanceInput, plan knowl.ModelEditPlan, limits PlanLimits) (knowl.ValidatedEditPlan, error)

ValidatePlan turns provider data into an application-owned plan.

func ValidateScanDocumentLimit added in v0.3.0 

func ValidateScanDocumentLimit(limit int) error

ValidateScanDocumentLimit validates one bounded descriptor read limit.

func ValidateSource added in v0.3.0 

func ValidateSource(source knowl.Source) error

ValidateSource validates the source discriminator, identity, and digest shape.

func ValidateSourceDigestLimit added in v0.3.0 

func ValidateSourceDigestLimit(limit int) error

ValidateSourceDigestLimit validates one bounded canonical inventory limit.

func ValidateSourceDocument added in v0.3.0 

func ValidateSourceDocument(document knowl.SourceDocument) error

ValidateSourceDocument validates complete bounded canonical provenance.

func ValidateSourceID added in v0.3.0 

func ValidateSourceID(id knowl.SourceID) error

ValidateSourceID validates a canonical configured source identifier.

func ValidateSyncCounts added in v0.3.0 

func ValidateSyncCounts(counts knowl.SyncCounts) error

ValidateSyncCounts rejects negative reconciliation counters.

func ValidateSyncRun added in v0.3.0 

func ValidateSyncRun(run knowl.SyncRun) error

ValidateSyncRun validates one bounded redacted sync-run read model.

func ValidateSyncRunID added in v0.3.0 

func ValidateSyncRunID(id knowl.SyncRunID) error

ValidateSyncRunID validates one bounded opaque durable run identifier.

Types

type AcceptedMaintenanceRequest added in v0.3.0 

type AcceptedMaintenanceRequest struct {
	Source         knowl.AcceptedSource `json:"source"`
	SourceDocument knowl.SourceDocument `json:"source_document"`
	ContentType    string               `json:"content_type"`
}

AcceptedMaintenanceRequest identifies one configured textual source revision that has already been accepted into immutable raw storage.

type ApplyResult 

type ApplyResult struct {
	Operation knowl.Operation
	Commit    *knowl.ContentCommit
}

ApplyResult contains the durable operation and the canonical commit, when one occurred.

type BeginSyncRequest added in v0.3.0 

type BeginSyncRequest struct {
	Run  knowl.SyncRun
	Type knowl.SourceType
}

BeginSyncRequest begins or idempotently replays one durable run.

type Citation 

type Citation struct {
	Kind      string       `json:"kind"`
	Reference string       `json:"reference"`
	PageID    knowl.PageID `json:"page_id,omitempty"`
	Path      string       `json:"path,omitempty"`
	SourceRef string       `json:"source_ref,omitempty"`
	Untrusted bool         `json:"untrusted"`
}

Citation is an untrusted wiki or raw-source reference assembled from query results.

type ContentStore 

type ContentStore interface {
	AcceptSource(ctx context.Context, envelope knowl.SourceEnvelope) (knowl.AcceptedSource, error)
	ReadSource(ctx context.Context, source knowl.AcceptedSource, limits knowl.ReadLimits) ([]byte, error)
	Schema(ctx context.Context, scope knowl.ScopeRef) (knowl.SchemaDocument, error)
	ReadPages(ctx context.Context, scope knowl.ScopeRef, ids []knowl.PageID, limits knowl.ReadLimits) ([]knowl.PageSnapshot, error)
	StagePlan(ctx context.Context, plan knowl.ValidatedEditPlan) (knowl.StagedChange, error)
	LoadStage(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID) (knowl.StagedChange, error)
	Commit(ctx context.Context, staged knowl.StagedChange) (knowl.ContentCommit, error)
	Recover(ctx context.Context) ([]knowl.RecoveryResult, error)
	Snapshot(ctx context.Context, scope knowl.ScopeRef) (knowl.WorkspaceSnapshot, error)
	Inspect(ctx context.Context, scope knowl.ScopeRef) (knowl.WorkspaceInspection, error)
}

ContentStore owns canonical workspace content and recovery.

type DocumentListOptions added in v0.3.0 

type DocumentListOptions struct {
	IncludeDeleted bool
	Limit          int
}

DocumentListOptions bounds source document-state reads.

func ValidateDocumentListOptions added in v0.3.0 

func ValidateDocumentListOptions(options DocumentListOptions) (DocumentListOptions, error)

ValidateDocumentListOptions validates and defaults a bounded state read.

type FilingRequest 

type FilingRequest struct {
	Query  string              `json:"query"`
	Result QueryResult         `json:"result"`
	Plan   knowl.ModelEditPlan `json:"plan"`
}

FilingRequest explicitly submits a query result and typed edit plan to the normal filing gate.

type IngestOptions 

type IngestOptions struct {
	PlanLimits    PlanLimits
	ReadLimits    knowl.ReadLimits
	LeaseDuration time.Duration
	AutoApply     bool
}

IngestOptions configures bounded planning and the review gate.

type IngestResult 

type IngestResult struct {
	Operation knowl.Operation
	Plan      knowl.ValidatedEditPlan
	Staged    knowl.StagedChange
	Commit    *knowl.ContentCommit
}

IngestResult contains the durable operation and any plan or commit produced by this call.

type IngestService 

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

IngestService coordinates source acceptance, planning, review, commit, and projection.

func NewIngestService 

func NewIngestService(content ContentStore, operations OperationStore, index SearchIndex, maintainer Maintainer, options IngestOptions) (*IngestService, error)

NewIngestService constructs the application workflow with conservative defaults.

func (*IngestService) Apply 

func (service *IngestService) Apply(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID) (ApplyResult, error)

Apply explicitly applies a planned operation after review.

func (*IngestService) Execute 

func (service *IngestService) Execute(ctx context.Context, submission IngestSubmission) (IngestResult, error)

Execute runs host-owned maintenance for a previously accepted source revision.

func (*IngestService) FailSubmission 

func (service *IngestService) FailSubmission(ctx context.Context, submission IngestSubmission, class string) error

FailSubmission records a failure after durable submission could not be scheduled.

func (*IngestService) FilePlan 

func (service *IngestService) FilePlan(ctx context.Context, envelope knowl.SourceEnvelope, plan knowl.ModelEditPlan) (IngestResult, error)

FilePlan files an explicitly supplied query or maintenance plan through the same ingest gate.

func (*IngestService) Ingest 

func (service *IngestService) Ingest(ctx context.Context, envelope knowl.SourceEnvelope) (IngestResult, error)

Ingest is a synchronous application convenience that submits then executes one source revision.

func (*IngestService) Preview 

func (service *IngestService) Preview(ctx context.Context, envelope knowl.SourceEnvelope) (IngestResult, error)

Preview accepts and stages one source revision without applying it, even when auto-apply is enabled.

func (*IngestService) Recover 

func (service *IngestService) Recover(ctx context.Context) ([]knowl.RecoveryResult, error)

Recover rolls back prepared canonical commits before the caller announces readiness.

func (*IngestService) ReserveAccepted added in v0.3.0 

func (service *IngestService) ReserveAccepted(ctx context.Context, request AcceptedMaintenanceRequest) (MaintenanceReservation, error)

ReserveAccepted reserves maintenance for one structured textual revision without accepting or reading the raw bytes again.

func (*IngestService) RunToTerminal 

func (service *IngestService) RunToTerminal(ctx context.Context, claim knowl.WorkClaim) (IngestResult, error)

RunToTerminal reconciles one exclusively claimed durable operation through the public sidecar path. Review is an internal convenience, not a runner stop.

func (*IngestService) Submit 

func (service *IngestService) Submit(ctx context.Context, envelope knowl.SourceEnvelope) (IngestSubmission, error)

Submit accepts one immutable source revision and reserves its durable operation. It does not invoke the maintainer or make canonical workspace changes.

type IngestSubmission 

type IngestSubmission struct {
	Operation knowl.Operation
	// contains filtered or unexported fields
}

IngestSubmission is the durable handoff from request-time source acceptance to host-owned maintenance execution.

func (IngestSubmission) NeedsExecution 

func (submission IngestSubmission) NeedsExecution() bool

NeedsExecution reports whether this submission created work for the host queue.

type LintOptions 

type LintOptions struct {
	ReadLimits knowl.ReadLimits
	Maintainer Maintainer
}

LintOptions configures deterministic lint and optional suggestion-only model lint.

type LintService 

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

LintService inspects canonical workspace metadata without mutating it.

func NewLintService 

func NewLintService(content ContentStore, index SearchIndex, options LintOptions) (*LintService, error)

NewLintService constructs a deterministic lint service.

func (*LintService) Lint 

func (service *LintService) Lint(ctx context.Context, scope knowl.ScopeRef) (knowl.LintReport, error)

Lint returns deterministic structural, provenance, index, log, and projection findings.

type Maintainer 

type Maintainer interface {
	Plan(ctx context.Context, input knowl.MaintenanceInput) (knowl.ModelEditPlan, error)
}

Maintainer produces structured data-only edit plans.

type MaintenanceReservation added in v0.3.0 

type MaintenanceReservation struct {
	OperationID knowl.OperationID `json:"operation_id"`
	Replayed    bool              `json:"replayed"`
}

MaintenanceReservation is the bounded durable handoff returned to source reconciliation. Replayed reports that the operation already existed.

type OperationKind 

type OperationKind string

OperationKind identifies the policy operation being authorized. 

const (
	OperationRead   OperationKind = "read"
	OperationWrite  OperationKind = "write"
	OperationReview OperationKind = "review"
)

type OperationReservation 

type OperationReservation struct {
	knowl.Operation
	Descriptor knowl.ExecutionDescriptor
	New        bool
}

OperationReservation is the durable result of reserving one immutable source revision. New reports whether this call created the operation rather than replaying it.

type OperationStore 

type OperationStore interface {
	Reserve(ctx context.Context, key knowl.OperationKey, meta knowl.OperationMeta) (OperationReservation, error)
	Execution(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID) (knowl.ExecutionDescriptor, error)
	ResumeReady(ctx context.Context, scope knowl.ScopeRef, limit int) ([]knowl.OperationID, error)
	ClaimReady(ctx context.Context, scope knowl.ScopeRef, lease knowl.WorkLease) (knowl.WorkClaim, error)
	RenewClaim(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID, currentToken string, next knowl.WorkLease) error
	ReleaseClaim(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID, token string) error
	DescriptorFailures(ctx context.Context, scope knowl.ScopeRef, limit int) ([]knowl.OperationID, error)
	SavePlan(ctx context.Context, id knowl.OperationID, summary knowl.PlanSummary) error
	MarkAwaitingReview(ctx context.Context, id knowl.OperationID) error
	MarkApplying(ctx context.Context, id knowl.OperationID, lease knowl.Lease) error
	CommitOutcome(ctx context.Context, id knowl.OperationID, commit knowl.ContentCommit) error
	Fail(ctx context.Context, id knowl.OperationID, failure knowl.Failure) error
	Operation(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID) (knowl.Operation, error)
}

OperationStore owns durable operation state, leases, and redacted outcomes.

type PlanLimits 

type PlanLimits struct {
	MaxFiles         int
	MaxFileBytes     int
	MaxSourceRefs    int
	MaxRationaleSize int
}

PlanLimits bounds model output before it reaches a content adapter.

func DefaultPlanLimits 

func DefaultPlanLimits() PlanLimits

DefaultPlanLimits returns conservative local plan limits.

type PreparedDocumentState added in v0.3.0 

type PreparedDocumentState struct {
	Action SyncDocumentAction
	State  knowl.DocumentState
}

PreparedDocumentState is one durable candidate applied only at finalization.

func NormalizePreparedDocuments added in v0.3.0 

func NormalizePreparedDocuments(scope knowl.ScopeRef, sourceID knowl.SourceID, runID knowl.SyncRunID, documents []PreparedDocumentState) ([]PreparedDocumentState, error)

NormalizePreparedDocuments copies, deterministically orders, and validates the candidate set of one complete-scan prepared state against its owning run.

type PreparedSyncRead added in v0.3.0 

type PreparedSyncRead struct {
	RunID           knowl.SyncRunID         `json:"run_id"`
	Scope           knowl.ScopeRef          `json:"scope"`
	SourceID        knowl.SourceID          `json:"source_id"`
	Checkpoint      string                  `json:"checkpoint,omitempty"`
	Counts          knowl.SyncCounts        `json:"counts"`
	Documents       []PreparedDocumentState `json:"documents,omitempty"`
	CandidateDigest string                  `json:"candidate_digest"`
}

PreparedSyncRead is the immutable prepared-scan result restored from durable state.

type PreparedSyncState added in v0.3.0 

type PreparedSyncState struct {
	RunID           knowl.SyncRunID
	Scope           knowl.ScopeRef
	SourceID        knowl.SourceID
	CompleteScan    bool
	Checkpoint      string
	Counts          knowl.SyncCounts
	Documents       []PreparedDocumentState
	CandidateDigest string
	PreparedAt      time.Time
}

PreparedSyncState is the immutable complete-scan result prepared for commit.

type QueryOptions 

type QueryOptions struct {
	ReadLimits knowl.ReadLimits
}

QueryOptions configures bounded wiki-first reads.

type QueryResult 

type QueryResult struct {
	Scope     knowl.ScopeRef        `json:"scope"`
	Query     string                `json:"query"`
	Pages     []knowl.PageReference `json:"pages"`
	Links     []knowl.LinkReference `json:"links"`
	Citations []Citation            `json:"citations"`
}

QueryResult is a bounded, read-only composition of wiki references and raw citations.

type QueryService 

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

QueryService owns bounded wiki-first reads and explicit filing.

func NewQueryService 

func NewQueryService(content ContentStore, operations OperationStore, index SearchIndex, filer *IngestService, options QueryOptions) (*QueryService, error)

NewQueryService constructs a read service. Filing is available when filer is non-nil.

func (*QueryService) File 

func (service *QueryService) File(ctx context.Context, scope knowl.ScopeRef, request FilingRequest) (IngestResult, error)

File explicitly files a query result through the standard immutable-source and plan/apply workflow. 

func (service *QueryService) Links(ctx context.Context, scope knowl.ScopeRef, page knowl.PageID, limits knowl.ReadLimits) ([]knowl.LinkReference, error)

Links returns bounded, untrusted graph references for one page.

func (*QueryService) Operation 

func (service *QueryService) Operation(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID) (knowl.Operation, error)

Operation returns the redacted durable status for one scoped operation.

func (*QueryService) Page 

func (service *QueryService) Page(ctx context.Context, scope knowl.ScopeRef, id knowl.PageID, limits knowl.ReadLimits) (knowl.PageSnapshot, error)

Page returns one bounded, untrusted canonical page read.

func (*QueryService) Query 

func (service *QueryService) Query(ctx context.Context, scope knowl.ScopeRef, query string, limits knowl.ReadLimits, sources []knowl.SourceID) (QueryResult, error)

Query assembles page references, link context, and page/raw citations without mutating state.

func (*QueryService) Search 

func (service *QueryService) Search(ctx context.Context, scope knowl.ScopeRef, query string, limits knowl.ReadLimits, sources []knowl.SourceID) ([]knowl.PageReference, error)

Search returns bounded, untrusted page references from the projection.

type ScanPageRecord added in v0.3.0 

type ScanPageRecord struct {
	RunID             knowl.SyncRunID
	Scope             knowl.ScopeRef
	SourceID          knowl.SourceID
	ExpectedPageToken string
	NextPageToken     string
	Documents         []knowl.DocumentRef
	RecordedAt        time.Time
}

ScanPageRecord atomically records one listed descriptor page and next token.

type ScopeAuthorizer 

type ScopeAuthorizer interface {
	Authorize(ctx context.Context, scope knowl.ScopeRef, operation OperationKind) error
}

ScopeAuthorizer enforces the host's trusted scope boundary.

type SearchIndex 

type SearchIndex interface {
	SelectContext(ctx context.Context, scope knowl.ScopeRef, source knowl.SourceSummary, limits knowl.ReadLimits) ([]knowl.PageID, error)
	Search(ctx context.Context, scope knowl.ScopeRef, query string, limits knowl.ReadLimits, sources []knowl.SourceID) ([]knowl.PageReference, error)
	Links(ctx context.Context, scope knowl.ScopeRef, page knowl.PageID, limits knowl.ReadLimits) ([]knowl.LinkReference, error)
	Project(ctx context.Context, commit knowl.ContentCommit) error
	Rebuild(ctx context.Context, snapshot knowl.WorkspaceSnapshot) error
}

SearchIndex owns rebuildable context, text, and link projections.

type SourceAdapter added in v0.3.0 

type SourceAdapter interface {
	List(ctx context.Context, source knowl.Source, pageToken string) (knowl.DocumentPage, error)
	Fetch(ctx context.Context, source knowl.Source, ref knowl.DocumentRef) (knowl.Document, error)
}

SourceAdapter lists cheap descriptors and fetches only selected documents.

type SourceContentStore added in v0.3.0 

type SourceContentStore interface {
	SourceDigests(ctx context.Context, scope knowl.ScopeRef, sourceID knowl.SourceID, limit int) ([]SourceDigestEntry, error)
	StageSourcePlan(ctx context.Context, plan knowl.SourceMutationPlan) (knowl.StagedSourceMutation, error)
	LoadSourceStage(ctx context.Context, scope knowl.ScopeRef, sourceID knowl.SourceID, runID knowl.SyncRunID) (knowl.StagedSourceMutation, error)
	CommitSource(ctx context.Context, staged knowl.StagedSourceMutation) (knowl.ContentCommit, error)
}

SourceContentStore owns deterministic canonical source mirrors and assets.

type SourceDigestEntry added in v0.3.0 

type SourceDigestEntry struct {
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

SourceDigestEntry is the exact write precondition of one canonical source file.

type SourceMaintenanceQueue added in v0.3.0 

type SourceMaintenanceQueue interface {
	ReserveAccepted(ctx context.Context, request AcceptedMaintenanceRequest) (MaintenanceReservation, error)
}

SourceMaintenanceQueue reserves already accepted source revisions for the existing host-owned operation scheduler.

type SourceNormalizationInput added in v0.3.0 

type SourceNormalizationInput struct {
	Source    knowl.Source
	Document  knowl.Document
	RawSource knowl.AcceptedSource
	Catalog   []knowl.DocumentRef
}

SourceNormalizationInput requests deterministic normalization of one fetched or restored raw document against its complete descriptor catalog.

type SourceNormalizationResult added in v0.3.0 

type SourceNormalizationResult struct {
	FormatVersion string
	CatalogDigest string
	MirrorDigest  string
	Mutations     []knowl.SourceMutation
	Diagnostics   []knowl.SourceDiagnostic
}

SourceNormalizationResult carries immutable identities plus detached, deterministically ordered canonical write mutations.

type SourceNormalizer added in v0.3.0 

type SourceNormalizer interface {
	NormalizeSource(ctx context.Context, input SourceNormalizationInput) (SourceNormalizationResult, error)
}

SourceNormalizer renders raw source documents into canonical mirrors without exposing any concrete catalog representation.

type SourceStateStore added in v0.3.0 

type SourceStateStore interface {
	BeginSync(ctx context.Context, request BeginSyncRequest) (run knowl.SyncRun, replay bool, err error)
	SyncRun(ctx context.Context, scope knowl.ScopeRef, id knowl.SyncRunID) (knowl.SyncRun, error)
	ScanDocuments(ctx context.Context, scope knowl.ScopeRef, id knowl.SyncRunID, limit int) ([]knowl.DocumentRef, error)
	RecordScanPage(ctx context.Context, record ScanPageRecord) (knowl.SyncRun, error)
	PrepareSync(ctx context.Context, prepared PreparedSyncState) (knowl.SyncRun, error)
	PreparedSync(ctx context.Context, scope knowl.ScopeRef, id knowl.SyncRunID) (PreparedSyncRead, error)
	MarkContentCommitted(ctx context.Context, generation SyncGeneration) (knowl.SyncRun, error)
	MarkProjected(ctx context.Context, generation SyncGeneration) (knowl.SyncRun, error)
	FinalizeSync(ctx context.Context, finalization SyncFinalization) (knowl.SyncRun, error)
	FailSync(ctx context.Context, scope knowl.ScopeRef, id knowl.SyncRunID, failureClass string, failedAt time.Time) (knowl.SyncRun, error)
	DocumentState(ctx context.Context, scope knowl.ScopeRef, sourceID knowl.SourceID, documentID knowl.DocumentID) (knowl.DocumentState, error)
	DocumentStates(ctx context.Context, scope knowl.ScopeRef, sourceID knowl.SourceID, options DocumentListOptions) ([]knowl.DocumentState, error)
	SourceStatus(ctx context.Context, scope knowl.ScopeRef, sourceID knowl.SourceID) (knowl.SourceStatus, error)
	ResumableSyncRuns(ctx context.Context, scope knowl.ScopeRef, limit int) ([]knowl.SyncRun, error)
}

SourceStateStore owns durable sync runs, document heads, and checkpoints.

type SyncDocumentAction added in v0.3.0 

type SyncDocumentAction string

SyncDocumentAction identifies the prepared active or tombstone outcome. 

const (
	SyncDocumentActive    SyncDocumentAction = "active"
	SyncDocumentTombstone SyncDocumentAction = "tombstone"
)

type SyncFinalization added in v0.3.0 

type SyncFinalization struct {
	RunID           knowl.SyncRunID
	Scope           knowl.ScopeRef
	SourceID        knowl.SourceID
	CandidateDigest string
	Generation      string
	Checkpoint      string
	Counts          knowl.SyncCounts
	FinalizedAt     time.Time
}

SyncFinalization atomically publishes prepared document heads and checkpoint.

type SyncGeneration added in v0.3.0 

type SyncGeneration struct {
	RunID      knowl.SyncRunID
	Scope      knowl.ScopeRef
	SourceID   knowl.SourceID
	Generation string
	UpdatedAt  time.Time
}

SyncGeneration records a canonical or projection generation transition.

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.