app

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: 22 Imported by: 0

Documentation

Overview

Package app owns Knowl application policy and its consuming ports.

Index

Constants

View Source 
const DefaultHierarchyPlannerVersion = "hierarchy-v3"
View Source 
const SourceMaintenanceContractVersion = "source-maintenance-v1"

SourceMaintenanceContractVersion identifies the output-affecting maintainer and validation contract. Compatibility-only changes must retain this value.

Variables

View Source 
var (
	// ErrHierarchyPlanInvalid reports malformed or incomplete semantic output.
	ErrHierarchyPlanInvalid = errors.New("invalid hierarchy plan")
	// ErrHierarchyDigestMismatch reports a plan made for other canonical inputs.
	ErrHierarchyDigestMismatch = errors.New("hierarchy plan digest mismatch")
	// ErrHierarchyLimitExceeded reports a configured hierarchy bound violation.
	ErrHierarchyLimitExceeded = errors.New("hierarchy plan exceeds a limit")
	// ErrHierarchyForbiddenPath reports a path outside the managed catalog boundary.
	ErrHierarchyForbiddenPath = errors.New("hierarchy plan targets a forbidden path")
)
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")
	ErrSourceRetryConflict   = errors.New("knowl source maintenance retry conflicts")
	ErrSourceLineageConflict = errors.New("knowl source repository identity conflicts")
)
View Source 
var ErrMaintenanceDiagnosticInvalid = errors.New("invalid maintenance diagnostic")

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 DecodeMaintenanceDiagnostics added in v0.5.0 

func DecodeMaintenanceDiagnostics(payload string) ([]knowl.MaintenanceDiagnostic, error)

DecodeMaintenanceDiagnostics fails closed on malformed or non-canonical durable payloads.

func DefaultHierarchyLimits added in v0.4.0 

func DefaultHierarchyLimits() knowl.HierarchyLimits

DefaultHierarchyLimits returns bounded defaults large enough for local multi-source workspaces while remaining below repository hard ceilings.

func DefaultReadLimits 

func DefaultReadLimits() knowl.ReadLimits

DefaultReadLimits returns the local bounded context defaults.

func EncodeMaintenanceDiagnostics added in v0.5.0 

func EncodeMaintenanceDiagnostics(input []knowl.MaintenanceDiagnostic) (string, error)

EncodeMaintenanceDiagnostics returns the canonical bounded persistence form.

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 HierarchyPlanDigest added in v0.4.0 

func HierarchyPlanDigest(plan knowl.ValidatedHierarchyPlan) (string, error)

HierarchyPlanDigest returns a deterministic SHA-256 digest of a normalized validated hierarchy plan.

func IsManagedHierarchyCatalog added in v0.4.0 

func IsManagedHierarchyCatalog(candidate string) bool

IsManagedHierarchyCatalog reports whether a canonical workspace path is owned by hierarchy reconciliation.

func MaintenanceGenerationPrefix added in v0.5.0 

func MaintenanceGenerationPrefix(generation string) (string, error)

MaintenanceGenerationPrefix returns the bounded operator-facing portion of a generation while retaining the empty legacy sentinel.

func MaintenancePolicyGeneration added in v0.5.0 

func MaintenancePolicyGeneration(policy MaintenancePolicy) (string, error)

MaintenancePolicyGeneration returns the full lowercase SHA-256 digest of a canonical, allow-listed policy payload.

func MaxSourceMaintenanceRetryResultIDs added in v0.4.0 

func MaxSourceMaintenanceRetryResultIDs() int

MaxSourceMaintenanceRetryResultIDs is the public bound for affected IDs.

func NormalizeHierarchyInput added in v0.4.0 

func NormalizeHierarchyInput(input knowl.HierarchyInput) (knowl.HierarchyInput, error)

NormalizeHierarchyInput validates and deterministically orders the complete bounded semantic input before it crosses the provider trust boundary.

func NormalizeMaintenanceDiagnostics added in v0.5.0 

func NormalizeMaintenanceDiagnostics(input []knowl.MaintenanceDiagnostic) ([]knowl.MaintenanceDiagnostic, error)

NormalizeMaintenanceDiagnostics validates, de-duplicates, sorts, and copies the bounded redacted diagnostics attached to one maintenance operation.

func NormalizeRetryFailureClasses added in v0.4.0 

func NormalizeRetryFailureClasses(classes []string) ([]string, error)

NormalizeRetryFailureClasses validates, de-duplicates, and sorts the operator-selected stable failure identifiers.

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 OperationIDForIdentity added in v0.4.0 

func OperationIDForIdentity(identity knowl.OperationIdentity) (knowl.OperationID, error)

OperationIDForIdentity returns the deterministic ID used by non-legacy generic work. Legacy source reservations keep their historical ID format.

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 SourceOperationID added in v0.5.0 

func SourceOperationID(key knowl.OperationKey) (knowl.OperationID, error)

SourceOperationID returns the historical source ID for a legacy empty generation and a generation-discriminated ID for current maintenance work.

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 ValidateExecutionSchema added in v0.5.0 

func ValidateExecutionSchema(scope knowl.ScopeRef, schema knowl.SchemaDocument) error

ValidateExecutionSchema verifies that a schema snapshot is safe to persist as a durable execution input.

func ValidateGenericExecutionDescriptor added in v0.4.0 

func ValidateGenericExecutionDescriptor(scope knowl.ScopeRef, descriptor knowl.ExecutionDescriptor) error

ValidateGenericExecutionDescriptor validates a descriptor read from durable storage when its original identity fields are no longer needed by callers.

func ValidateHierarchyPlan added in v0.4.0 

func ValidateHierarchyPlan(ctx context.Context, input knowl.HierarchyInput, model knowl.HierarchyModelPlan, options HierarchyValidationOptions) (knowl.ValidatedHierarchyPlan, error)

ValidateHierarchyPlan validates a complete semantic graph and renders the desired managed OKF catalogs. It never accepts provider-supplied file bytes.

func ValidateMaintenanceGeneration added in v0.5.0 

func ValidateMaintenanceGeneration(generation string) error

ValidateMaintenanceGeneration accepts the legacy empty sentinel or one canonical full policy digest.

func ValidateOperationDescriptor added in v0.4.0 

func ValidateOperationDescriptor(identity knowl.OperationIdentity, descriptor knowl.ExecutionDescriptor) error

ValidateOperationDescriptor verifies one generic identity and descriptor.

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 ValidateRepositoryIdentity added in v0.4.0 

func ValidateRepositoryIdentity(identity string) error

ValidateRepositoryIdentity accepts the bounded SHA-256 lineage binding used by durable source state without exposing the repository URL.

func ValidateSafeFailure added in v0.4.0 

func ValidateSafeFailure(failure knowl.Failure, requireReason bool) bool

ValidateSafeFailure verifies bounded metadata before it crosses a durable store boundary. A reason is required for retry scheduling, while terminal legacy failures may omit it.

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"`
	PreviousMaintenanceRevision string               `json:"previous_maintenance_revision,omitempty"`
	PreviousOperationID         knowl.OperationID    `json:"previous_operation_id,omitempty"`
	PreviousGeneration          string               `json:"previous_generation,omitempty"`
}

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
	RepositoryIdentity string
	AllowRebind        bool
}

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 ClassifiedExecutionError added in v0.4.0 

type ClassifiedExecutionError interface {
	error
	FailureClass() string
	FailureReason() string
	Retryable() bool
}

ClassifiedExecutionError is a safely renderable execution failure whose retry policy does not depend on parsing its Error string.

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)
	HierarchySnapshotDigest(ctx context.Context, scope knowl.ScopeRef) (string, 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)
	StageHierarchyPlan(ctx context.Context, id knowl.OperationID, plan knowl.ValidatedHierarchyPlan) (knowl.StagedChange, error)
	LoadHierarchyStage(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID) (knowl.StagedChange, error)
	CommitHierarchy(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 ExecutionFailureInfo added in v0.4.0 

type ExecutionFailureInfo struct {
	Class     string
	Reason    string
	Retryable bool
}

ExecutionFailureInfo is the validated, redacted policy carried by a ClassifiedExecutionError.

func ClassifyExecutionFailure added in v0.4.0 

func ClassifyExecutionFailure(err error) (ExecutionFailureInfo, bool)

ClassifyExecutionFailure returns only bounded identifier-shaped metadata. Invalid implementations are ignored rather than trusted as safe output.

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 HierarchyMaintainer added in v0.4.0 

type HierarchyMaintainer interface {
	PlanHierarchy(ctx context.Context, input knowl.HierarchyInput) (knowl.HierarchyModelPlan, error)
}

HierarchyMaintainer produces a structured semantic catalog graph. The application remains responsible for graph validation and Markdown rendering.

type HierarchyOptions added in v0.4.0 

type HierarchyOptions struct {
	Limits         knowl.HierarchyLimits
	PlannerVersion string
	LeaseDuration  time.Duration
}

HierarchyOptions configures explicit hierarchy reconciliation.

type HierarchyService added in v0.4.0 

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

HierarchyService coordinates durable, explicit catalog-only reconciliation.

func NewHierarchyService added in v0.4.0 

func NewHierarchyService(content ContentStore, operations OperationStore, index SearchIndex, maintainer HierarchyMaintainer, options HierarchyOptions) (*HierarchyService, error)

func (*HierarchyService) Reconcile added in v0.4.0 

func (service *HierarchyService) Reconcile(ctx context.Context, scope knowl.ScopeRef) (IngestResult, error)

Reconcile reserves, exclusively claims, and synchronously executes the hierarchy operation for an explicit trusted mutation workflow.

func (*HierarchyService) Reserve added in v0.4.0 

func (service *HierarchyService) Reserve(ctx context.Context, scope knowl.ScopeRef) (OperationReservation, error)

Reserve captures immutable execution identity without invoking the provider.

func (*HierarchyService) RunToTerminal added in v0.4.0 

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

RunToTerminal executes one exclusively claimed hierarchy operation.

type HierarchyValidationOptions added in v0.4.0 

type HierarchyValidationOptions struct {
	// ForbiddenCatalogTerms are configured source IDs or source-native namespace
	// names. A nested catalog path segment or complete title may not equal one.
	ForbiddenCatalogTerms []string
}

HierarchyValidationOptions contains application-only policy that must not be exposed as semantic provider context.

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) CurrentMaintenancePolicy added in v0.5.0 

func (service *IngestService) CurrentMaintenancePolicy(ctx context.Context, scope knowl.ScopeRef) (knowl.SchemaDocument, string, error)

CurrentMaintenancePolicy returns the current schema snapshot and its effective source-maintenance generation for an explicit manual transition.

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 MaintenanceOutcome added in v0.5.0 

type MaintenanceOutcome string

MaintenanceOutcome is the bounded decision made while reconciling accepted source work against its current effective maintenance policy. 

const (
	MaintenanceQueued     MaintenanceOutcome = "queued"
	MaintenanceReplayed   MaintenanceOutcome = "replayed"
	MaintenanceConverged  MaintenanceOutcome = "converged"
	MaintenanceManualGate MaintenanceOutcome = "manual_gate"
)

type MaintenancePolicy added in v0.5.0 

type MaintenancePolicy struct {
	ContractVersion string
	SchemaDigest    string
	ReadLimits      knowl.ReadLimits
	PlanLimits      PlanLimits
}

MaintenancePolicy is the explicit non-secret input to source-maintenance generation. It intentionally cannot carry provider or runtime configuration.

func SourceMaintenancePolicy added in v0.5.0 

func SourceMaintenancePolicy(schemaDigest string, readLimits knowl.ReadLimits, planLimits PlanLimits) MaintenancePolicy

SourceMaintenancePolicy constructs the effective policy used by ingestion.

type MaintenanceReservation added in v0.3.0 

type MaintenanceReservation struct {
	OperationID      knowl.OperationID  `json:"operation_id"`
	Generation       string             `json:"generation,omitempty"`
	PolicyGeneration string             `json:"-"`
	Outcome          MaintenanceOutcome `json:"outcome,omitempty"`
	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)
	ReserveOperation(ctx context.Context, identity knowl.OperationIdentity, descriptor knowl.ExecutionDescriptor) (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)
	ClaimOperation(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID, 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
	ScheduleRetry(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID, token string, failure knowl.Failure, readyAt time.Time) 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
	FailClaim(ctx context.Context, scope knowl.ScopeRef, id knowl.OperationID, token string, 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
	AttemptCheckpoint string
	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 SnapshotPreparation added in v0.4.0 

type SnapshotPreparation struct {
	PageToken  string
	Checkpoint string
}

SnapshotPreparation pins one source scan to an immutable adapter checkpoint.

type SnapshotSourceAdapter added in v0.4.0 

type SnapshotSourceAdapter interface {
	PrepareSnapshot(ctx context.Context, source knowl.Source, previousCheckpoint string) (SnapshotPreparation, error)
}

SnapshotSourceAdapter prepares an immutable scan before descriptor paging. Reconciliation uses this optional capability for moving remote sources.

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 SourceMaintenanceRetryRequest added in v0.4.0 

type SourceMaintenanceRetryRequest struct {
	Scope                 knowl.ScopeRef       `json:"scope"`
	SourceID              knowl.SourceID       `json:"source_id"`
	FailureClasses        []string             `json:"failure_classes"`
	MaintenanceGeneration string               `json:"maintenance_generation,omitempty"`
	Schema                knowl.SchemaDocument `json:"-"`
	DryRun                bool                 `json:"dry_run"`
}

SourceMaintenanceRetryRequest selects terminal current-revision maintenance operations for explicit operator recovery.

type SourceMaintenanceRetryResult added in v0.4.0 

type SourceMaintenanceRetryResult struct {
	SourceID     knowl.SourceID      `json:"source_id"`
	DryRun       bool                `json:"dry_run"`
	Matched      int64               `json:"matched"`
	Requeued     int64               `json:"requeued"`
	Rejected     int64               `json:"rejected"`
	OperationIDs []knowl.OperationID `json:"operation_ids"`
	Truncated    bool                `json:"truncated"`
}

SourceMaintenanceRetryResult is bounded even when the selected source has more matching operations than can be listed individually.

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)
	RetrySourceMaintenance(ctx context.Context, request SourceMaintenanceRetryRequest) (SourceMaintenanceRetryResult, 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.