knowl

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package knowl contains the public non-Fx host composition API for Knowl. Domain contracts live in the pkg/knowl/types import path; the root package keeps transition aliases while embedders move to that dedicated contract package.

Package knowl continues to export the public domain contracts during the transition to pkg/knowl/types. New code should import the types subpackage directly.

Index

Examples

Constants

View Source 
const (
	StoreSQLite   = "sqlite"
	StorePostgres = "postgres"
	DefaultScope  = domain.ScopeRef("local")
	DefaultListen = "127.0.0.1:8080"
)
View Source 
const (
	// Deprecated: use knowltypes.StatusReceived from pkg/knowl/types.
	StatusReceived = knowltypes.StatusReceived
	// Deprecated: use knowltypes.StatusPlanned from pkg/knowl/types.
	StatusPlanned = knowltypes.StatusPlanned
	// Deprecated: use knowltypes.StatusAwaitingReview from pkg/knowl/types.
	StatusAwaitingReview = knowltypes.StatusAwaitingReview
	// Deprecated: use knowltypes.StatusApplying from pkg/knowl/types.
	StatusApplying = knowltypes.StatusApplying
	// Deprecated: use knowltypes.StatusCommitted from pkg/knowl/types.
	StatusCommitted = knowltypes.StatusCommitted
	// Deprecated: use knowltypes.StatusFailed from pkg/knowl/types.
	StatusFailed = knowltypes.StatusFailed
)

Variables

View Source 
var ErrHostClosed = errors.New("knowl host is closed")

ErrHostClosed reports that a Host-owned runtime resource is no longer usable.

Functions

func NormalizeSources added in v0.3.0 

func NormalizeSources(workspace, baseDir string, sources []domain.Source) ([]domain.Source, error)

NormalizeSources validates and canonicalizes configured sources without opening runtime resources. Relative roots are resolved from baseDir, or the process working directory when baseDir is empty.

func RebuildProjection added in v0.3.0 

func RebuildProjection(ctx context.Context, config Config, snapshot domain.WorkspaceSnapshot) error

RebuildProjection replaces the configured rebuildable search projection from one canonical workspace snapshot without starting a Host.

Types

type AcceptedSource deprecated 

type AcceptedSource = knowltypes.AcceptedSource

Deprecated: use knowltypes.AcceptedSource from pkg/knowl/types.

type Config 

type Config struct {
	Workspace     string
	Scope         domain.ScopeRef
	Sources       []domain.Source
	StoreDriver   string
	StorePath     string
	PostgresDSN   string
	ListenAddr    string
	OperatorToken string
	ReadLimits    domain.ReadLimits
	IngestOptions app.IngestOptions
	// WorkerQueueSize bounds only coalesced in-memory wake hints. Accepted work
	// remains durable and is recovered by scheduler scans when hints are lost.
	WorkerQueueSize int
	ShutdownTimeout time.Duration
}

Config controls one local Knowl host. The scope is trusted host context.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns conservative local defaults.

func (Config) Validate 

func (config Config) Validate() error

Validate checks configuration without opening files, sockets, or databases.

type ContentCommit deprecated 

type ContentCommit = knowltypes.ContentCommit

Deprecated: use knowltypes.ContentCommit from pkg/knowl/types.

type DrainResult added in v0.4.0 

type DrainResult struct {
	Completed int `json:"completed"`
	Failed    int `json:"failed"`
	Retried   int `json:"retried"`
	Total     int `json:"total"`
}

DrainResult summarizes maintenance operations processed during a drain cycle.

type Failure deprecated 

type Failure = knowltypes.Failure

Deprecated: use knowltypes.Failure from pkg/knowl/types.

type FileEdit deprecated 

type FileEdit = knowltypes.FileEdit

Deprecated: use knowltypes.FileEdit from pkg/knowl/types.

type HierarchyRunResult added in v0.4.0 

type HierarchyRunResult struct {
	OperationID domain.OperationID     `json:"operation_id"`
	Status      domain.OperationStatus `json:"status"`
	Changed     bool                   `json:"changed"`
	Generation  string                 `json:"generation,omitempty"`
	Files       []string               `json:"files,omitempty"`
}

HierarchyRunResult contains the outcome of hierarchy reconciliation if performed.

type Host 

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

Host composes canonical content, operational state, application services, HTTP, and MCP.

func New 

func New(ctx context.Context, options Options) (*Host, error)

New composes and preflights a host. Recovery, migrations, and projection readiness complete before return.

func NewHost 

func NewHost(ctx context.Context, config Config, maintainer app.Maintainer) (*Host, error)

NewHost is an explicit constructor alias for callers composing one local host.

Example 
package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"github.com/baldaworks/knowl/pkg/knowl"
	contentfs "github.com/baldaworks/knowl/pkg/knowl/content/fs"
	"github.com/baldaworks/knowl/pkg/knowl/provider"
)

func main() {
	root, err := os.MkdirTemp("", "knowl-host-example-")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(root) }()

	workspace, err := contentfs.New(root)
	if err != nil {
		panic(err)
	}
	if err := workspace.Init(); err != nil {
		panic(err)
	}

	config := knowl.DefaultConfig()
	config.Workspace = workspace.Root()
	config.StorePath = filepath.Join(workspace.Root(), ".knowl", "knowl.sqlite")

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	host, err := knowl.NewHost(ctx, config, provider.Fixture{})
	if err != nil {
		fmt.Println(false)
		return
	}
	defer func() { _ = host.Close() }()

	fmt.Println(host != nil && !host.Ready())

}

Output:
true

func (*Host) Addr 

func (host *Host) Addr() string

Addr returns the bound HTTP address, or the configured address before Start.

func (*Host) Close 

func (host *Host) Close() error

Close shuts down the host with its configured timeout.

func (*Host) Drain added in v0.4.0 

func (host *Host) Drain(ctx context.Context) (DrainResult, error)

Drain processes ready maintenance operations to completion without starting the HTTP listener or periodic background tickers.

func (*Host) Handler 

func (host *Host) Handler() http.Handler

Handler returns the loopback HTTP handler for in-process integration tests and embedding.

func (*Host) Index 

func (host *Host) Index() app.SearchIndex

Index returns the rebuildable search projection port.

func (*Host) Lint 

func (host *Host) Lint() *app.LintService

Lint returns the composed deterministic lint service.

func (*Host) MCP 

func (host *Host) MCP() *mcp.Server

MCP returns the server-bound read-only MCP tool registry.

func (*Host) Operations 

func (host *Host) Operations() app.OperationStore

Operations returns the redacted operational-state port.

func (*Host) PrepareReadOnly added in v0.3.0 

func (host *Host) PrepareReadOnly() error

PrepareReadOnly marks a composed, preflighted host ready for in-process read handlers without binding a listener or starting operation and source jobs.

func (*Host) Query 

func (host *Host) Query() *app.QueryService

Query returns the composed bounded query service.

func (*Host) Ready 

func (host *Host) Ready() bool

Ready reports whether recovery, migrations, projection preparation, and HTTP start completed.

func (*Host) ReconcileHierarchy added in v0.4.0 

func (host *Host) ReconcileHierarchy(ctx context.Context) (app.IngestResult, error)

ReconcileHierarchy runs the explicit, synchronous hierarchy mutation without starting the HTTP listener, general operation scheduler, or source jobs.

func (*Host) RetrySourceMaintenance added in v0.4.0 

func (host *Host) RetrySourceMaintenance(ctx context.Context, id domain.SourceID, failureClasses []string, dryRun bool) (app.SourceMaintenanceRetryResult, error)

RetrySourceMaintenance previews or requeues selected terminal maintenance operations without starting source synchronization or background workers.

func (*Host) Run 

func (host *Host) Run(ctx context.Context) error

Run starts the host and blocks until ctx is canceled or the HTTP server fails.

func (*Host) RunOnce added in v0.4.0 

func (host *Host) RunOnce(ctx context.Context, options RunOnceOptions) (RunOnceResult, error)

RunOnce performs one complete, bounded knowledge pipeline execution: 1. Optionally synchronizes configured sources (all or single). 2. Optionally drains ready maintenance operations to terminal states. 3. Optionally reconciles semantic OKF hierarchy if enabled and supported.

func (*Host) Shutdown 

func (host *Host) Shutdown(ctx context.Context) error

Shutdown is retained as an explicit alias for callers using the pre-Fx host API.

func (*Host) SourceStatus added in v0.3.0 

func (host *Host) SourceStatus(ctx context.Context, id domain.SourceID) (domain.SourceStatus, error)

SourceStatus returns the durable redacted status of one configured source.

func (*Host) Sources added in v0.3.0 

func (host *Host) Sources() []domain.Source

Sources returns a detached source-ID-sorted copy of the configured registry.

func (*Host) Start 

func (host *Host) Start(ctx context.Context) error

Start binds the loopback HTTP listener and marks the host ready after preflight. The context is used for the start operation; Stop owns the server lifetime.

func (*Host) Stop 

func (host *Host) Stop(ctx context.Context) error

Stop makes the host unavailable, stops request intake and new claims, gives active work the caller's bound, and then closes owned resources.

func (*Host) SyncAll added in v0.3.0 

func (host *Host) SyncAll(ctx context.Context) (SourceSyncAllResult, error)

SyncAll synchronizes every enabled configured source in deterministic order.

func (*Host) SyncSource added in v0.3.0 

func (host *Host) SyncSource(ctx context.Context, id domain.SourceID) (SourceSyncResult, error)

SyncSource synchronizes one enabled source from the Host's trusted registry.

func (*Host) Wait 

func (host *Host) Wait(ctx context.Context) error

Wait blocks until the host context is canceled or the HTTP server reports a fatal error.

func (*Host) Workspace 

func (host *Host) Workspace() *contentfs.Workspace

Workspace returns the canonical filesystem adapter.

type Lease deprecated 

type Lease = knowltypes.Lease

Deprecated: use knowltypes.Lease from pkg/knowl/types.

type LinkReference deprecated 

type LinkReference = knowltypes.LinkReference

Deprecated: use knowltypes.LinkReference from pkg/knowl/types.

type LintFinding deprecated 

type LintFinding = knowltypes.LintFinding

Deprecated: use knowltypes.LintFinding from pkg/knowl/types.

type LintReport deprecated 

type LintReport = knowltypes.LintReport

Deprecated: use knowltypes.LintReport from pkg/knowl/types.

type MaintenanceInput deprecated 

type MaintenanceInput = knowltypes.MaintenanceInput

Deprecated: use knowltypes.MaintenanceInput from pkg/knowl/types.

type ModelEditPlan deprecated 

type ModelEditPlan = knowltypes.ModelEditPlan

Deprecated: use knowltypes.ModelEditPlan from pkg/knowl/types.

type Operation deprecated 

type Operation = knowltypes.Operation

Deprecated: use knowltypes.Operation from pkg/knowl/types.

type OperationID deprecated 

type OperationID = knowltypes.OperationID

Deprecated: use knowltypes.OperationID from pkg/knowl/types.

type OperationKey deprecated 

type OperationKey = knowltypes.OperationKey

Deprecated: use knowltypes.OperationKey from pkg/knowl/types.

type OperationMeta deprecated 

type OperationMeta = knowltypes.OperationMeta

Deprecated: use knowltypes.OperationMeta from pkg/knowl/types.

type OperationStatus deprecated 

type OperationStatus = knowltypes.OperationStatus

Deprecated: use knowltypes.OperationStatus from pkg/knowl/types.

type Options 

type Options struct {
	Config         Config
	Maintainer     app.Maintainer
	RuntimeFactory runtimeprovider.RuntimeFactory
	ProviderID     string
	SourceAdapters map[domain.SourceType]app.SourceAdapter
	SourceObserver SourceObserver
}

Options supplies the host configuration plus either an explicit maintainer or the runtime-provider inputs needed to build one lazily.

type PageID deprecated 

type PageID = knowltypes.PageID

Deprecated: use knowltypes.PageID from pkg/knowl/types.

type PageReference deprecated 

type PageReference = knowltypes.PageReference

Deprecated: use knowltypes.PageReference from pkg/knowl/types.

type PageSnapshot deprecated 

type PageSnapshot = knowltypes.PageSnapshot

Deprecated: use knowltypes.PageSnapshot from pkg/knowl/types.

type PlanSummary deprecated 

type PlanSummary = knowltypes.PlanSummary

Deprecated: use knowltypes.PlanSummary from pkg/knowl/types.

type RawSourceRecord deprecated 

type RawSourceRecord = knowltypes.RawSourceRecord

Deprecated: use knowltypes.RawSourceRecord from pkg/knowl/types.

type ReadLimits deprecated 

type ReadLimits = knowltypes.ReadLimits

Deprecated: use knowltypes.ReadLimits from pkg/knowl/types.

type RecoveryResult deprecated 

type RecoveryResult = knowltypes.RecoveryResult

Deprecated: use knowltypes.RecoveryResult from pkg/knowl/types.

type RunOnceOptions added in v0.4.0 

type RunOnceOptions struct {
	SyncSources        bool            `json:"sync_sources"`
	SourceID           domain.SourceID `json:"source_id,omitempty"`
	DrainOperations    bool            `json:"drain_operations"`
	ReconcileHierarchy bool            `json:"reconcile_hierarchy"`
}

RunOnceOptions controls the execution of a synchronous one-shot run.

type RunOnceResult added in v0.4.0 

type RunOnceResult struct {
	Sources    []SourceSyncResult  `json:"sources,omitempty"`
	Operations DrainResult         `json:"operations"`
	Hierarchy  *HierarchyRunResult `json:"hierarchy,omitempty"`
}

RunOnceResult aggregates the results of all phases executed during RunOnce.

type SchemaDocument deprecated 

type SchemaDocument = knowltypes.SchemaDocument

Deprecated: use knowltypes.SchemaDocument from pkg/knowl/types.

type ScopeRef deprecated 

type ScopeRef = knowltypes.ScopeRef

Deprecated: use knowltypes.ScopeRef from pkg/knowl/types.

type SourceAttempt added in v0.3.0 

type SourceAttempt struct {
	SourceID     domain.SourceID `json:"source_id"`
	Trigger      SourceTrigger   `json:"trigger"`
	Result       string          `json:"result"`
	FailureClass string          `json:"failure_class,omitempty"`
	Changed      bool            `json:"changed"`
	Duration     time.Duration   `json:"duration"`
}

SourceAttempt is a bounded event suitable for structured logs and metrics.

type SourceEnvelope deprecated 

type SourceEnvelope = knowltypes.SourceEnvelope

Deprecated: use knowltypes.SourceEnvelope from pkg/knowl/types.

type SourceObserver added in v0.3.0 

type SourceObserver interface {
	ObserveSourceAttempt(attempt SourceAttempt)
}

SourceObserver receives redacted attempt events. Implementations must return promptly.

type SourceRef deprecated 

type SourceRef = knowltypes.SourceRef

Deprecated: use knowltypes.SourceRef from pkg/knowl/types.

type SourceSummary deprecated 

type SourceSummary = knowltypes.SourceSummary

Deprecated: use knowltypes.SourceSummary from pkg/knowl/types.

type SourceSyncAllResult added in v0.3.0 

type SourceSyncAllResult struct {
	Results []SourceSyncResult `json:"results"`
}

SourceSyncAllResult contains one deterministic result per enabled source.

type SourceSyncResult added in v0.3.0 

type SourceSyncResult struct {
	SourceID     domain.SourceID           `json:"source_id"`
	Run          domain.SyncRun            `json:"run"`
	Changed      bool                      `json:"changed"`
	FailureClass string                    `json:"failure_class,omitempty"`
	Diagnostics  []domain.SourceDiagnostic `json:"diagnostics,omitempty"`
}

SourceSyncResult is the bounded, redacted result of one configured source attempt.

type SourceTrigger added in v0.3.0 

type SourceTrigger string

SourceTrigger identifies why one source synchronization attempt began. 

const (
	SourceTriggerManual   SourceTrigger = "manual"
	SourceTriggerOnStart  SourceTrigger = "on_start"
	SourceTriggerInterval SourceTrigger = "interval"
	SourceTriggerRetry    SourceTrigger = "retry"
)

type SourceVersion deprecated 

type SourceVersion = knowltypes.SourceVersion

Deprecated: use knowltypes.SourceVersion from pkg/knowl/types.

type StagedChange deprecated 

type StagedChange = knowltypes.StagedChange

Deprecated: use knowltypes.StagedChange from pkg/knowl/types.

type ValidatedEditPlan deprecated 

type ValidatedEditPlan = knowltypes.ValidatedEditPlan

Deprecated: use knowltypes.ValidatedEditPlan from pkg/knowl/types.

type WorkspaceInspection deprecated 

type WorkspaceInspection = knowltypes.WorkspaceInspection

Deprecated: use knowltypes.WorkspaceInspection from pkg/knowl/types.

type WorkspaceSnapshot deprecated 

type WorkspaceSnapshot = knowltypes.WorkspaceSnapshot

Deprecated: use knowltypes.WorkspaceSnapshot from pkg/knowl/types.

Source Files

View all Source files

Directories

Path Synopsis
Package app owns Knowl application policy and its consuming ports.
 Package app owns Knowl application policy and its consuming ports.
content
fs
Package fs will provide the canonical filesystem workspace adapter.
 Package fs will provide the canonical filesystem workspace adapter.
internal
knowledgetest
Package knowledgetest contains the internal deterministic v0.1 knowledge loop corpus.
 Package knowledgetest contains the internal deterministic v0.1 knowledge loop corpus.
runnertest
Package runnertest provides the backend-neutral durable runner contract.
 Package runnertest provides the backend-neutral durable runner contract.
Package llmstxt renders a bounded llms.txt navigation document from an already-inspected Knowl workspace.
 Package llmstxt renders a bounded llms.txt navigation document from an already-inspected Knowl workspace.
Package mcp provides bounded, server-scoped Knowl MCP tools.
 Package mcp provides bounded, server-scoped Knowl MCP tools.
Package okf parses and renders Open Knowledge Format v0.2 documents.
 Package okf parses and renders Open Knowledge Format v0.2 documents.
Package provider contains adapters from the shared runtime provider registry to Knowl's structured maintainer boundary.
 Package provider contains adapters from the shared runtime provider registry to Knowl's structured maintainer boundary.
store
internal/contextpolicy
Package contextpolicy owns backend-independent maintenance context budgets and deterministic phase merging.
 Package contextpolicy owns backend-independent maintenance context budgets and deterministic phase merging.
internal/contexttest
Package contexttest defines the shared maintenance context contract for rebuildable search adapters.
 Package contexttest defines the shared maintenance context contract for rebuildable search adapters.
internal/lexical
Package lexical contains the backend-independent lexical retrieval policy.
 Package lexical contains the backend-independent lexical retrieval policy.
internal/operationpayload
Package operationpayload owns the bounded durable non-source descriptor envelope shared by SQLite and PostgreSQL stores.
 Package operationpayload owns the bounded durable non-source descriptor envelope shared by SQLite and PostgreSQL stores.
internal/projectionmeta
Package projectionmeta defines the shared OKF projection encoding used by both durable search adapters.
 Package projectionmeta defines the shared OKF projection encoding used by both durable search adapters.
internal/searchtest
Package searchtest defines the shared behavioral contract for lexical store adapters.
 Package searchtest defines the shared behavioral contract for lexical store adapters.
internal/storetest
Package storetest provides shared behavioral contracts for operational stores.
 Package storetest provides shared behavioral contracts for operational stores.
postgres
Package postgres implements Knowl operational state and search projections with PostgreSQL-native transactions and full-text search.
 Package postgres implements Knowl operational state and search projections with PostgreSQL-native transactions and full-text search.
sqlite
Package sqlite will provide the SQLite operational store and search projection.
 Package sqlite will provide the SQLite operational store and search projection.
Package knowl contains the public, transport-neutral Knowl domain contracts.
 Package knowl contains the public, transport-neutral Knowl domain contracts.
Package wiki contains the shared Markdown/wiki parsing and normalization rules that define canonical Knowl workspace semantics.
 Package wiki contains the shared Markdown/wiki parsing and normalization rules that define canonical Knowl workspace semantics.

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.