app

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: MIT Imports: 15 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")
	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")
)

Functions

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 PlanDigest 

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

PlanDigest returns a deterministic digest of a validated plan.

func SourceRefKey 

func SourceRefKey(source knowl.AcceptedSource) string

SourceRefKey is the stable citation key required in a plan.

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 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.

Types

type ApplyResult 

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

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

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 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) 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 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 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) (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) ([]knowl.PageReference, error)

Search returns bounded, untrusted page references from the projection.

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) ([]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.

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.