knowl

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

Documentation

Overview

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

Index

Constants

View Source 
const (
	// SourceTypeFilesystem selects the built-in filesystem source contract.
	SourceTypeFilesystem SourceType = "filesystem"
	// SourceFlavorMarkdown preserves ordinary Markdown references.
	SourceFlavorMarkdown = "markdown"
	// SourceFlavorObsidian enables Obsidian reference normalization.
	SourceFlavorObsidian = "obsidian"
	// SourceFlavorOKF preserves validated Open Knowledge Format semantics.
	SourceFlavorOKF = "okf"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptedSource 

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

AcceptedSource describes an immutable source version stored in the workspace.

type ContentCommit 

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

ContentCommit describes a canonical workspace commit.

type Document added in v0.3.0 

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

Document is one fetched immutable source revision.

type DocumentID added in v0.3.0 

type DocumentID string

DocumentID identifies one logical document within a configured source.

type DocumentPage added in v0.3.0 

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

DocumentPage is one deterministic page of source descriptors.

type DocumentRef added in v0.3.0 

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

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

type DocumentState added in v0.3.0 

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

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

type ExecutionDescriptor 

type ExecutionDescriptor struct {
	OperationID OperationID    `json:"operation_id"`
	Source      AcceptedSource `json:"source"`
	Schema      SchemaDocument `json:"schema"`
}

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

type Failure 

type Failure struct {
	Class       string `json:"class"`
	OperationID string `json:"operation_id"`
}

Failure is a stable, redacted operation failure.

type FileEdit 

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

FileEdit is one validated canonical workspace file replacement.

type FilesystemSourceConfig added in v0.3.0 

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

FilesystemSourceConfig configures a filesystem-backed source.

type Lease 

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

Lease prevents duplicate worker completion.

type LinkReference 

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

LinkReference is an untrusted bounded graph result.

type LintFinding 

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

LintFinding is one deterministic or suggestion-only workspace diagnostic.

type LintReport 

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

LintReport contains bounded, redacted workspace health findings.

func (LintReport) Healthy 

func (report LintReport) Healthy() bool

Healthy reports whether lint found no error or warning findings.

type MaintenanceCounts added in v0.3.0 

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

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

type MaintenanceInput 

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

MaintenanceInput is the bounded data supplied to a maintainer provider.

type MaintenanceSample added in v0.3.0 

type MaintenanceSample struct {
	DocumentID   DocumentID      `json:"document_id"`
	Revision     string          `json:"revision"`
	OperationID  OperationID     `json:"operation_id"`
	Status       OperationStatus `json:"status"`
	Replayed     bool            `json:"replayed"`
	FailureClass string          `json:"failure_class,omitempty"`
}

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

type ModelEditPlan 

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

ModelEditPlan is structured provider output before application validation.

type Operation 

type Operation struct {
	ID        OperationID     `json:"id"`
	Key       OperationKey    `json:"key"`
	Status    OperationStatus `json:"status"`
	Attempt   int             `json:"attempt"`
	Failure   *Failure        `json:"failure,omitempty"`
	UpdatedAt time.Time       `json:"updated_at"`
}

Operation is a redacted operation read model.

type OperationID 

type OperationID string

OperationID identifies an ingest or filing operation.

type OperationKey 

type OperationKey struct {
	Scope   ScopeRef      `json:"scope"`
	Source  SourceRef     `json:"source"`
	Version SourceVersion `json:"version"`
}

OperationKey is the idempotency identity for an immutable source revision.

type OperationMeta 

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

OperationMeta contains the bounded internal inputs persisted at reservation.

type OperationStatus 

type OperationStatus string

OperationStatus is the lifecycle state of a maintenance operation. 

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

type PageID 

type PageID string

PageID is a stable wiki page identifier.

type PageReference 

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

PageReference is an untrusted bounded search result.

type PageSnapshot 

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

PageSnapshot is a bounded read of a canonical Markdown page.

type PlanSummary 

type PlanSummary struct {
	OperationID string    `json:"operation_id"`
	Digest      string    `json:"digest"`
	FileCount   int       `json:"file_count"`
	CreatedAt   time.Time `json:"created_at"`
}

PlanSummary is the durable redacted summary of a model plan.

type RawSourceRecord 

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

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

type ReadLimits 

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

ReadLimits bounds context and retrieval operations.

type RecoveryResult 

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

RecoveryResult describes recovery of one interrupted content operation.

type SchemaDocument 

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

SchemaDocument is the operator-owned workspace policy document.

type ScopeRef 

type ScopeRef string

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

type Source added in v0.3.0 

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

Source describes one configured authoritative source.

type SourceConfig added in v0.3.0 

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

SourceConfig is the typed configuration union for one source.

type SourceDiagnostic added in v0.3.0 

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

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

type SourceDocument added in v0.3.0 

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

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

type SourceEnvelope 

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

SourceEnvelope is the bounded input accepted from a source adapter.

type SourceID added in v0.3.0 

type SourceID string

SourceID identifies one configured authoritative knowledge source.

type SourceMaintenanceStatus added in v0.3.0 

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

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

type SourceMutation added in v0.3.0 

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

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

type SourceMutationAction added in v0.3.0 

type SourceMutationAction string

SourceMutationAction selects one canonical source-owned filesystem action. 

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

type SourceMutationPlan added in v0.3.0 

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

SourceMutationPlan is one deterministic canonical mutation request.

type SourceRef 

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

SourceRef identifies a source adapter and a stable source identity.

type SourceStatus added in v0.3.0 

type SourceStatus struct {
	Scope               ScopeRef                `json:"scope"`
	SourceID            SourceID                `json:"source_id"`
	Type                SourceType              `json:"type"`
	ConfigDigest        string                  `json:"config_digest"`
	Checkpoint          string                  `json:"checkpoint,omitempty"`
	LastAttemptRunID    SyncRunID               `json:"last_attempt_run_id,omitempty"`
	LastSuccessfulRunID SyncRunID               `json:"last_successful_run_id,omitempty"`
	Status              SyncStatus              `json:"status,omitempty"`
	Counts              SyncCounts              `json:"counts"`
	Maintenance         SourceMaintenanceStatus `json:"maintenance"`
	CreatedAt           time.Time               `json:"created_at"`
	LastAttemptAt       time.Time               `json:"last_attempt_at,omitempty"`
	LastSuccessfulAt    time.Time               `json:"last_successful_at,omitempty"`
	UpdatedAt           time.Time               `json:"updated_at"`
}

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

type SourceSummary 

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

SourceSummary is bounded source context for a maintainer or index.

type SourceSyncPolicy added in v0.3.0 

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

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

type SourceType added in v0.3.0 

type SourceType string

SourceType selects a source adapter family.

type SourceVersion 

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

SourceVersion identifies an immutable source revision.

type StagedChange 

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

StagedChange identifies a plan staged for review or apply.

type StagedSourceMutation added in v0.3.0 

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

StagedSourceMutation identifies one verified source-owned staged artifact.

type SyncCounts added in v0.3.0 

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

SyncCounts summarizes reconciliation outcomes for one run.

type SyncRun added in v0.3.0 

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

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

type SyncRunID added in v0.3.0 

type SyncRunID string

SyncRunID identifies one durable source synchronization attempt.

type SyncStatus added in v0.3.0 

type SyncStatus string

SyncStatus is the durable lifecycle status of one synchronization run. 

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

type ValidatedEditPlan 

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

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

type WorkClaim 

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

WorkClaim combines an exclusively claimed operation with its durable inputs.

type WorkLease 

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

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

type WorkspaceInspection 

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

WorkspaceInspection combines canonical projections needed by deterministic lint.

type WorkspaceSnapshot 

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

WorkspaceSnapshot identifies canonical content used to build projections.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.