documents

package
v0.9.2 Latest Latest
Warning

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

 Go to latest Published: May 1, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package documents indexes managed local markdown roots for model-facing rediscovery, browse, search, and section retrieval.

The operator-facing contract for what counts as a managed document root lives in docs/understanding/document-roots.md. Keep that document in sync with behavioral changes here, especially when changing how config paths become indexed corpora or how the documents capability is meant to differ from raw file access.

Index

Constants

View Source 
const (
	// GeneratedFieldBy is the frontmatter field naming the subsystem or
	// loop that produced a generated document.
	GeneratedFieldBy = "generated_by"
	// GeneratedFieldAt is the frontmatter field recording when a generated
	// document was produced.
	GeneratedFieldAt = "generated_at"
	// GeneratedFieldSourceRefs is the frontmatter field listing source
	// references used to produce a generated document.
	GeneratedFieldSourceRefs = "source_refs"
	// GeneratedFieldDocumentKind is the frontmatter field describing the
	// semantic kind of generated document.
	GeneratedFieldDocumentKind = "document_kind"
	// GeneratedFieldRefreshStrategy is the frontmatter field describing how
	// repeated generation should treat the document.
	GeneratedFieldRefreshStrategy = "refresh_strategy"
	// GeneratedFieldManagedRoot is the optional frontmatter field naming the
	// managed root prefix when the writer knows it.
	GeneratedFieldManagedRoot = "managed_root"
)
View Source 
const (
	// RefreshStrategyImmutable marks generated documents that should be
	// written once and left unchanged.
	RefreshStrategyImmutable = "immutable"
	// RefreshStrategyReplace marks generated documents that are replaced in
	// full on refresh.
	RefreshStrategyReplace = "replace"
	// RefreshStrategyAppend marks generated documents that grow by appending
	// new entries.
	RefreshStrategyAppend = "append"
	// RefreshStrategyRollingWindow marks generated documents that keep a
	// bounded recent window.
	RefreshStrategyRollingWindow = "rolling-window"
)
View Source 
const (
	// DocumentKindMediaAnalysis identifies a generated media analysis page.
	DocumentKindMediaAnalysis = "media_analysis"
	// DocumentKindMediaChannelIndex identifies an automatically maintained
	// media channel index page.
	DocumentKindMediaChannelIndex = "media_channel_index"
)

Variables

This section is empty.

Functions

func RenderGeneratedFrontmatter 

func RenderGeneratedFrontmatter(m GeneratedMetadata) (string, error)

RenderGeneratedFrontmatter renders generated-document metadata as YAML frontmatter lines suitable for insertion into a larger frontmatter block.

Types

type AuthoringMode 

type AuthoringMode string

AuthoringMode describes whether managed document mutation APIs may write to a root. 

const (
	// AuthoringManaged allows managed document mutation APIs to write
	// to the root.
	AuthoringManaged AuthoringMode = "managed"
	// AuthoringReadOnly prevents managed document mutation APIs from
	// writing to the root.
	AuthoringReadOnly AuthoringMode = "read_only"
	// AuthoringRestricted reserves the root for narrower policy-aware
	// authoring flows and blocks generic document mutations.
	AuthoringRestricted AuthoringMode = "restricted"
)
type Backlink struct {
	Ref              string   `json:"ref"`
	Path             string   `json:"path"`
	Title            string   `json:"title"`
	ModifiedAt       string   `json:"modified_at"`
	Targets          []string `json:"targets,omitempty"`
	TargetsTruncated bool     `json:"targets_truncated,omitempty"`
}

Backlink is one indexed document that links to another document.

type BrowseArgs 

type BrowseArgs struct {
	Root       string `json:"root"`
	PathPrefix string `json:"path_prefix,omitempty"`
	Limit      int    `json:"limit,omitempty"`
}

BrowseArgs requests one rooted browse step through an indexed corpus.

type BrowseDirectory 

type BrowseDirectory struct {
	Name          string `json:"name"`
	PathPrefix    string `json:"path_prefix"`
	DocumentCount int    `json:"document_count"`
}

BrowseDirectory describes one child directory in a rooted browse view.

type BrowseResult 

type BrowseResult struct {
	Root        string            `json:"root"`
	PathPrefix  string            `json:"path_prefix,omitempty"`
	Directories []BrowseDirectory `json:"directories,omitempty"`
	Documents   []DocumentSummary `json:"documents,omitempty"`
}

BrowseResult is the rooted "phone tree" view for one root/prefix.

type CommitArgs 

type CommitArgs struct {
	IntakeID string       `json:"intake_id"`
	Action   IntakeAction `json:"action,omitempty"`
	Body     string       `json:"body,omitempty"`
	Section  string       `json:"section,omitempty"`
	Heading  string       `json:"heading,omitempty"`
	Window   string       `json:"window,omitempty"`
	Confirm  bool         `json:"confirm,omitempty"`
}

CommitArgs commits an approved document intake plan.

type CommitResult 

type CommitResult struct {
	IntakeID string       `json:"intake_id"`
	Action   IntakeAction `json:"action"`
	Ref      string       `json:"ref,omitempty"`
	Status   string       `json:"status"`
	Result   any          `json:"result,omitempty"`
}

CommitResult describes the mutation, or draft, created from an intake.

type CopyArgs 

type CopyArgs struct {
	Ref            string `json:"ref"`
	DestinationRef string `json:"destination_ref"`
	Overwrite      bool   `json:"overwrite,omitempty"`
}

CopyArgs duplicates one managed document at a new semantic ref.

type CopyResult 

type CopyResult struct {
	Action      string   `json:"action"`
	FromRef     string   `json:"from_ref"`
	ToRef       string   `json:"to_ref"`
	FromRoot    string   `json:"from_root"`
	FromPath    string   `json:"from_path"`
	ToRoot      string   `json:"to_root"`
	ToPath      string   `json:"to_path"`
	Overwrote   bool     `json:"overwrote,omitempty"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
}

CopyResult summarizes one managed document copy.

type DeleteArgs 

type DeleteArgs struct {
	Ref string `json:"ref"`
}

DeleteArgs removes one managed document by semantic ref.

type DeleteResult 

type DeleteResult struct {
	Action      string   `json:"action"`
	DeletedRef  string   `json:"deleted_ref"`
	Root        string   `json:"root"`
	Path        string   `json:"path"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
}

DeleteResult summarizes one managed document deletion. 

type DocumentLink struct {
	Target string `json:"target"`
	Kind   string `json:"kind"`
	Ref    string `json:"ref,omitempty"`
	Title  string `json:"title,omitempty"`
	URL    string `json:"url,omitempty"`
	Anchor string `json:"anchor,omitempty"`
}

DocumentLink is one outgoing link projected from an indexed document.

type DocumentRecord 

type DocumentRecord struct {
	Root        string              `json:"root"`
	Ref         string              `json:"ref"`
	Path        string              `json:"path"`
	Title       string              `json:"title"`
	Description string              `json:"description,omitempty"`
	Tags        []string            `json:"tags,omitempty"`
	Frontmatter map[string][]string `json:"frontmatter,omitempty"`
	Body        string              `json:"body"`
	Outline     []Section           `json:"outline,omitempty"`
	ModifiedAt  string              `json:"modified_at"`
	WordCount   int                 `json:"word_count"`
	SizeBytes   int64               `json:"size_bytes"`
}

DocumentRecord is the full model-facing view of one managed document.

type DocumentSummary 

type DocumentSummary struct {
	Root        string              `json:"root"`
	Ref         string              `json:"ref"`
	Path        string              `json:"path"`
	Title       string              `json:"title"`
	Summary     string              `json:"summary,omitempty"`
	Tags        []string            `json:"tags,omitempty"`
	Frontmatter map[string][]string `json:"frontmatter,omitempty"`
	ModifiedAt  string              `json:"modified_at"`
	WordCount   int                 `json:"word_count"`
}

DocumentSummary is the compact search/browse view of a document.

type EditArgs 

type EditArgs struct {
	Ref         string              `json:"ref"`
	Mode        string              `json:"mode"`
	Content     string              `json:"content,omitempty"`
	Section     string              `json:"section,omitempty"`
	Heading     string              `json:"heading,omitempty"`
	Level       int                 `json:"level,omitempty"`
	Title       string              `json:"title,omitempty"`
	Description string              `json:"description,omitempty"`
	Tags        []string            `json:"tags,omitempty"`
	Frontmatter map[string][]string `json:"frontmatter,omitempty"`
}

EditArgs updates part of a managed document without leaving the semantic document abstraction.

type GeneratedMetadata 

type GeneratedMetadata struct {
	GeneratedBy     string    `json:"generated_by" yaml:"generated_by"`
	GeneratedAt     time.Time `json:"generated_at" yaml:"generated_at"`
	SourceRefs      []string  `json:"source_refs,omitempty" yaml:"source_refs,omitempty"`
	DocumentKind    string    `json:"document_kind" yaml:"document_kind"`
	RefreshStrategy string    `json:"refresh_strategy" yaml:"refresh_strategy"`
	ManagedRoot     string    `json:"managed_root,omitempty" yaml:"managed_root,omitempty"`
}

GeneratedMetadata is the document-local provenance contract for generated markdown artifacts in managed document roots. It intentionally uses only flat frontmatter fields so the document index can filter and expose it without nested YAML support.

func (GeneratedMetadata) Frontmatter 

func (m GeneratedMetadata) Frontmatter() map[string][]string

Frontmatter returns the generated-document metadata as index-compatible frontmatter values. Empty optional fields are omitted.

func (GeneratedMetadata) Validate 

func (m GeneratedMetadata) Validate() error

Validate reports whether metadata has the minimum fields required for a generated document to be machine-legible.

type IntakeAction 

type IntakeAction string

IntakeAction is the document mutation shape recommended by intake. 

const (
	// IntakeActionCreateNew creates a new managed document at proposed_ref.
	IntakeActionCreateNew IntakeAction = "create_new"
	// IntakeActionUpdateExisting updates an existing related document.
	IntakeActionUpdateExisting IntakeAction = "update_existing"
	// IntakeActionAppendExisting appends a journal-style note to an
	// existing related document.
	IntakeActionAppendExisting IntakeAction = "append_existing"
	// IntakeActionDraftForReview declines mutation and returns a draft
	// plan for human or later review.
	IntakeActionDraftForReview IntakeAction = "draft_for_review"
)

type IntakeArgs 

type IntakeArgs struct {
	Root          string   `json:"root,omitempty"`
	Intent        string   `json:"intent,omitempty"`
	Summary       string   `json:"summary,omitempty"`
	BodySnippet   string   `json:"body_snippet,omitempty"`
	ContentDigest string   `json:"content_digest,omitempty"`
	DesiredTitle  string   `json:"desired_title,omitempty"`
	DesiredRef    string   `json:"desired_ref,omitempty"`
	Tags          []string `json:"tags,omitempty"`
	PathPrefix    string   `json:"path_prefix,omitempty"`
}

IntakeArgs describes a proposed managed-document addition before it is assigned to a final corpus destination.

type IntakeCommitPlan 

type IntakeCommitPlan struct {
	IntakeID              string              `json:"intake_id,omitempty"`
	RecommendedAction     IntakeAction        `json:"recommended_action"`
	ProposedRef           string              `json:"proposed_ref,omitempty"`
	TargetRef             string              `json:"target_ref,omitempty"`
	NormalizedTitle       string              `json:"normalized_title,omitempty"`
	NormalizedTags        []string            `json:"normalized_tags,omitempty"`
	NormalizedFrontmatter map[string][]string `json:"normalized_frontmatter,omitempty"`
	RequiresConfirmation  bool                `json:"requires_confirmation,omitempty"`
	ConfirmationReason    string              `json:"confirmation_reason,omitempty"`
}

IntakeCommitPlan is the exact structured handoff expected by doc_commit.

type IntakeRelatedDocument 

type IntakeRelatedDocument struct {
	Ref       string   `json:"ref"`
	Title     string   `json:"title"`
	Path      string   `json:"path"`
	Tags      []string `json:"tags,omitempty"`
	Score     float64  `json:"score"`
	Rationale string   `json:"rationale,omitempty"`
}

IntakeRelatedDocument describes a corpus document that overlaps with the proposed intake.

type IntakeResult 

type IntakeResult struct {
	IntakeID              string                  `json:"intake_id,omitempty"`
	Status                IntakeStatus            `json:"status"`
	Reason                string                  `json:"reason,omitempty"`
	Root                  string                  `json:"root"`
	RootPolicy            RootPolicySummary       `json:"root_policy"`
	RecommendedAction     IntakeAction            `json:"recommended_action"`
	ProposedRef           string                  `json:"proposed_ref,omitempty"`
	TargetRef             string                  `json:"target_ref,omitempty"`
	NormalizedTitle       string                  `json:"normalized_title,omitempty"`
	NormalizedTags        []string                `json:"normalized_tags,omitempty"`
	NormalizedFrontmatter map[string][]string     `json:"normalized_frontmatter,omitempty"`
	ObservedTags          []ValueCount            `json:"observed_tags,omitempty"`
	RelatedDocuments      []IntakeRelatedDocument `json:"related_documents,omitempty"`
	Rationale             []string                `json:"rationale,omitempty"`
	CommitPlan            IntakeCommitPlan        `json:"commit_plan"`
}

IntakeResult is the model-facing corpus-aware placement analysis.

type IntakeStatus 

type IntakeStatus string

IntakeStatus describes whether an intake can be committed directly or needs a second explicit decision. 

const (
	// IntakeReady means the proposed commit can proceed without extra
	// confirmation.
	IntakeReady IntakeStatus = "ready"
	// IntakeConfirmCreate means a new document is possible, but similar
	// documents make an update the safer default.
	IntakeConfirmCreate IntakeStatus = "confirm_create"
	// IntakeConfirmUpdate means the intake is likely an update or append
	// to an existing document and should be confirmed before committing.
	IntakeConfirmUpdate IntakeStatus = "confirm_update"
	// IntakeDraftForReview means root policy or corpus ambiguity suggests
	// leaving the content as a draft instead of committing it.
	IntakeDraftForReview IntakeStatus = "draft_for_review"
	// IntakeRefused means the target root cannot accept managed commits.
	IntakeRefused IntakeStatus = "refused"
)

type JournalUpdateArgs 

type JournalUpdateArgs struct {
	Ref          string              `json:"ref"`
	Entry        string              `json:"entry"`
	Window       string              `json:"window,omitempty"`
	MaxWindows   int                 `json:"max_windows,omitempty"`
	HeadingLevel int                 `json:"heading_level,omitempty"`
	Title        string              `json:"title,omitempty"`
	Description  string              `json:"description,omitempty"`
	Tags         []string            `json:"tags,omitempty"`
	Frontmatter  map[string][]string `json:"frontmatter,omitempty"`
}

JournalUpdateArgs appends a timestamped note into a rolling window journal document while keeping window headings and timestamps stable.

type LinksArgs 

type LinksArgs struct {
	Ref              string `json:"ref"`
	Mode             string `json:"mode,omitempty"`
	Limit            int    `json:"limit,omitempty"`
	PerBacklinkLimit int    `json:"per_backlink_limit,omitempty"`
}

LinksArgs requests outgoing links, backlinks, or both for one document.

type LinksResult 

type LinksResult struct {
	Ref                string         `json:"ref"`
	Mode               string         `json:"mode"`
	Limit              int            `json:"limit,omitempty"`
	PerBacklinkLimit   int            `json:"per_backlink_limit,omitempty"`
	Outgoing           []DocumentLink `json:"outgoing,omitempty"`
	OutgoingTruncated  bool           `json:"outgoing_truncated,omitempty"`
	Backlinks          []Backlink     `json:"backlinks,omitempty"`
	BacklinksTruncated bool           `json:"backlinks_truncated,omitempty"`
}

LinksResult is the outgoing/backlink view for one indexed document.

type MoveArgs 

type MoveArgs struct {
	Ref            string `json:"ref"`
	DestinationRef string `json:"destination_ref"`
	Overwrite      bool   `json:"overwrite,omitempty"`
}

MoveArgs relocates one managed document to a new semantic ref.

type MoveResult 

type MoveResult struct {
	Action      string   `json:"action"`
	FromRef     string   `json:"from_ref"`
	ToRef       string   `json:"to_ref"`
	FromRoot    string   `json:"from_root"`
	FromPath    string   `json:"from_path"`
	ToRoot      string   `json:"to_root"`
	ToPath      string   `json:"to_path"`
	Overwrote   bool     `json:"overwrote,omitempty"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
}

MoveResult summarizes one managed document move/rename.

type MutationResult 

type MutationResult struct {
	Action      string   `json:"action"`
	Ref         string   `json:"ref"`
	Root        string   `json:"root"`
	Path        string   `json:"path"`
	Existed     bool     `json:"existed"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
	Section     string   `json:"section,omitempty"`
	Window      string   `json:"window,omitempty"`
}

MutationResult summarizes one managed document write/edit.

type RefArgs 

type RefArgs struct {
	Ref string `json:"ref"`
}

RefArgs identifies one managed document by canonical semantic ref.

type RootDocumentHint 

type RootDocumentHint struct {
	Ref        string `json:"ref"`
	Path       string `json:"path"`
	Title      string `json:"title"`
	ModifiedAt string `json:"modified_at"`
}

RootDocumentHint is a compact example document attached to a root summary.

type RootGitPolicy 

type RootGitPolicy struct {
	Enabled          bool             `json:"enabled"`
	SignCommits      bool             `json:"sign_commits,omitempty"`
	VerifySignatures VerificationMode `json:"verify_signatures,omitempty"`
	RepoPath         string           `json:"-"`
}

RootGitPolicy describes git-backed provenance policy for a managed document root.

type RootGitPolicySummary 

type RootGitPolicySummary struct {
	Enabled          bool             `json:"enabled"`
	SignCommits      bool             `json:"sign_commits,omitempty"`
	VerifySignatures VerificationMode `json:"verify_signatures,omitempty"`
}

RootGitPolicySummary is the model-facing form of RootGitPolicy.

type RootPolicy 

type RootPolicy struct {
	Indexing  bool          `json:"indexing"`
	Authoring AuthoringMode `json:"authoring"`
	Git       RootGitPolicy `json:"git,omitempty"`
}

RootPolicy describes indexing, authoring, and integrity policy for a managed document root.

type RootPolicySummary 

type RootPolicySummary struct {
	Indexing  bool                 `json:"indexing"`
	Authoring AuthoringMode        `json:"authoring"`
	Git       RootGitPolicySummary `json:"git"`
}

RootPolicySummary is the model-facing form of RootPolicy. It omits local filesystem paths and key material.

type RootSummary 

type RootSummary struct {
	Root            string                 `json:"root"`
	Path            string                 `json:"-"`
	Policy          RootPolicySummary      `json:"policy"`
	Verification    *SignatureVerification `json:"verification,omitempty"`
	DocumentCount   int                    `json:"document_count"`
	TotalSizeBytes  int64                  `json:"total_size_bytes"`
	TotalWordCount  int                    `json:"total_word_count"`
	LastModifiedAt  string                 `json:"last_modified_at,omitempty"`
	TopTags         []string               `json:"top_tags,omitempty"`
	TopDirectories  []BrowseDirectory      `json:"top_directories,omitempty"`
	RecentDocuments []RootDocumentHint     `json:"recent_documents,omitempty"`
}

RootSummary describes one indexed document root.

type RootVerifier 

type RootVerifier interface {
	Verify(ctx context.Context, filename string) (SignatureVerification, error)
	VerifyRoot(ctx context.Context) (SignatureVerification, error)
}

RootVerifier verifies that a git-backed root or file is clean and trusted before policy-sensitive consumers load it.

type RootWriter 

type RootWriter interface {
	Write(ctx context.Context, filename, content, message string) error
	Delete(ctx context.Context, filename, message string) error
}

RootWriter applies a managed document mutation to a root. Git-backed roots use this hook to sign and commit writes without exposing git to the model.

type SearchArgs 

type SearchArgs struct {
	Root            string              `json:"root,omitempty"`
	PathPrefix      string              `json:"path_prefix,omitempty"`
	Query           string              `json:"query,omitempty"`
	Tags            []string            `json:"tags,omitempty"`
	Frontmatter     map[string][]string `json:"frontmatter,omitempty"`
	FrontmatterKeys []string            `json:"frontmatter_keys,omitempty"`
	ModifiedAfter   string              `json:"modified_after,omitempty"`
	ModifiedBefore  string              `json:"modified_before,omitempty"`
	Limit           int                 `json:"limit,omitempty"`
}

SearchArgs requests structured document search over indexed roots.

type SearchQuery 

type SearchQuery struct {
	Root            string              `json:"root,omitempty"`
	PathPrefix      string              `json:"path_prefix,omitempty"`
	Query           string              `json:"query,omitempty"`
	Tags            []string            `json:"tags,omitempty"`
	Frontmatter     map[string][]string `json:"frontmatter,omitempty"`
	FrontmatterKeys []string            `json:"frontmatter_keys,omitempty"`
	ModifiedAfter   *time.Time          `json:"-"`
	ModifiedBefore  *time.Time          `json:"-"`
	Limit           int                 `json:"limit,omitempty"`
}

SearchQuery filters document search results.

type Section 

type Section struct {
	Heading   string `json:"heading"`
	Slug      string `json:"slug"`
	Level     int    `json:"level"`
	StartLine int    `json:"start_line"`
	EndLine   int    `json:"end_line"`
	Content   string `json:"content,omitempty"`
}

Section captures one heading-defined region in a markdown document.

type SectionArgs 

type SectionArgs struct {
	Ref     string `json:"ref"`
	Section string `json:"section,omitempty"`
}

SectionArgs selects one document section by ref and optional heading.

type SectionTransferArgs 

type SectionTransferArgs struct {
	Ref                string `json:"ref"`
	Section            string `json:"section"`
	DestinationRef     string `json:"destination_ref"`
	DestinationSection string `json:"destination_section,omitempty"`
	DestinationLevel   int    `json:"destination_level,omitempty"`
}

SectionTransferArgs copies or moves one section into another managed doc.

type SectionTransferResult 

type SectionTransferResult struct {
	Action             string   `json:"action"`
	SourceRef          string   `json:"source_ref"`
	SourceRoot         string   `json:"source_root"`
	SourcePath         string   `json:"source_path"`
	SourceSection      string   `json:"source_section"`
	DestinationRef     string   `json:"destination_ref"`
	DestinationRoot    string   `json:"destination_root"`
	DestinationPath    string   `json:"destination_path"`
	DestinationSection string   `json:"destination_section"`
	DestinationLevel   int      `json:"destination_level"`
	DestinationExisted bool     `json:"destination_existed"`
	Title              string   `json:"title"`
	Description        string   `json:"description,omitempty"`
	Tags               []string `json:"tags,omitempty"`
	CreatedAt          string   `json:"created_at,omitempty"`
	UpdatedAt          string   `json:"updated_at,omitempty"`
	ModifiedAt         string   `json:"modified_at"`
	WordCount          int      `json:"word_count"`
	SizeBytes          int64    `json:"size_bytes"`
}

SectionTransferResult summarizes one section-level copy or move.

type SignatureStatus 

type SignatureStatus string

SignatureStatus describes the last known signature verification state for a root or document. 

const (
	// SignatureTrusted means the checked content is clean and covered by
	// trusted signed git history.
	SignatureTrusted SignatureStatus = "trusted"
	// SignatureFailed means signature policy could not verify the checked
	// content.
	SignatureFailed SignatureStatus = "failed"
	// SignatureUnavailable means signature verification was requested but
	// no verifier could be configured.
	SignatureUnavailable SignatureStatus = "unavailable"
)

type SignatureVerification 

type SignatureVerification struct {
	Status    SignatureStatus  `json:"status"`
	Mode      VerificationMode `json:"mode,omitempty"`
	Commit    string           `json:"commit,omitempty"`
	Message   string           `json:"message,omitempty"`
	CheckedAt string           `json:"checked_at,omitempty"`
	Consumer  string           `json:"consumer,omitempty"`
}

SignatureVerification is the document package's verifier-neutral signature status shape.

type Store 

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

Store indexes managed markdown roots into the primary Thane SQLite DB.

func NewStore 

func NewStore(db *sql.DB, roots map[string]string, logger *slog.Logger) (*Store, error)

NewStore creates a document index store backed by db.

func NewStoreWithOptions 

func NewStoreWithOptions(db *sql.DB, roots map[string]string, logger *slog.Logger, opts StoreOptions) (*Store, error)

NewStoreWithOptions creates a document index store backed by db and optional per-root policy.

func (*Store) Browse 

func (s *Store) Browse(ctx context.Context, root, prefix string, limit int) (*BrowseResult, error)

Browse returns the immediate child directories and documents for a rooted prefix.

func (*Store) Copy 

func (s *Store) Copy(ctx context.Context, args CopyArgs) (*CopyResult, error)

func (*Store) CopySection 

func (s *Store) CopySection(ctx context.Context, args SectionTransferArgs) (*SectionTransferResult, error)

func (*Store) Delete 

func (s *Store) Delete(ctx context.Context, args DeleteArgs) (*DeleteResult, error)

func (*Store) Edit 

func (s *Store) Edit(ctx context.Context, args EditArgs) (*MutationResult, error)

func (*Store) Intake 

func (s *Store) Intake(ctx context.Context, args IntakeArgs) (*IntakeResult, error)

Intake analyzes a proposed document contribution against existing corpus structure.

func (*Store) JournalUpdate 

func (s *Store) JournalUpdate(ctx context.Context, args JournalUpdateArgs) (*MutationResult, error)
func (s *Store) Links(ctx context.Context, ref string, mode string, limit int, perBacklinkLimit int) (*LinksResult, error)

Links returns outgoing links, backlinks, or both for one indexed document.

func (*Store) Move 

func (s *Store) Move(ctx context.Context, args MoveArgs) (*MoveResult, error)

func (*Store) MoveSection 

func (s *Store) MoveSection(ctx context.Context, args SectionTransferArgs) (*SectionTransferResult, error)

func (*Store) Outline 

func (s *Store) Outline(ctx context.Context, ref string) ([]Section, error)

Outline returns the heading tree for a document ref.

func (*Store) Read 

func (s *Store) Read(ctx context.Context, ref string) (*DocumentRecord, error)

func (*Store) Refresh 

func (s *Store) Refresh(ctx context.Context) error

Refresh incrementally refreshes all indexed roots.

func (*Store) Roots 

func (s *Store) Roots(ctx context.Context) ([]RootSummary, error)

Roots returns the current indexed root summaries.

func (*Store) RunRefresher 

func (s *Store) RunRefresher(ctx context.Context)

RunRefresher keeps the index warm in the background using the store's refresh interval. Errors are logged and retried on the next tick.

func (*Store) Search 

func (s *Store) Search(ctx context.Context, q SearchQuery) ([]DocumentSummary, error)

Search returns matching documents, sorted by relevance and recency.

func (*Store) Section 

func (s *Store) Section(ctx context.Context, ref string, selector string) (*Section, error)

Section returns one section by heading text or slug. An empty selector returns the whole document.

func (*Store) Values 

func (s *Store) Values(ctx context.Context, root, key string, limit int) ([]ValueCount, error)

Values returns observed frontmatter values for one key.

func (*Store) VerifyMutationPath 

func (s *Store) VerifyMutationPath(_ context.Context, path string, consumer string) error

VerifyMutationPath reports whether a raw filesystem mutation is allowed for path. Paths outside configured roots are ignored.

This is deliberately stricter than Store.VerifyPath. A trusted file inside a signed root may be safe to read, but raw writes would dirty the tree without using the root writer that signs managed document mutations. Read-only/restricted roots are also blocked here so file tools cannot bypass root authoring policy.

func (*Store) VerifyPath 

func (s *Store) VerifyPath(ctx context.Context, path string, consumer string) error

VerifyPath verifies an absolute file path when it belongs to a managed document root. Paths outside configured roots are ignored.

func (*Store) VerifyRef 

func (s *Store) VerifyRef(ctx context.Context, ref string, consumer string) error

VerifyRef verifies a managed semantic ref for policy-sensitive consumers.

func (*Store) Write 

func (s *Store) Write(ctx context.Context, args WriteArgs) (*MutationResult, error)

type StoreOptions 

type StoreOptions struct {
	RootPolicies  map[string]RootPolicy
	RootWriters   map[string]RootWriter
	RootVerifiers map[string]RootVerifier
}

StoreOptions configures optional root policy and backing writers for Store.

type Tools 

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

Tools exposes model-facing document navigation tools.

func NewTools 

func NewTools(store *Store) *Tools

NewTools creates a document tool surface.

func (*Tools) Browse 

func (t *Tools) Browse(ctx context.Context, args BrowseArgs) (string, error)

Browse returns one rooted browse step through an indexed corpus.

func (*Tools) Commit 

func (t *Tools) Commit(ctx context.Context, args CommitArgs) (string, error)

Commit applies a previously returned intake plan through managed document mutation paths.

func (*Tools) Copy 

func (t *Tools) Copy(ctx context.Context, args CopyArgs) (string, error)

Copy clones one managed document to a new semantic ref.

func (*Tools) CopySection 

func (t *Tools) CopySection(ctx context.Context, args SectionTransferArgs) (string, error)

CopySection copies one section into another managed document.

func (*Tools) Delete 

func (t *Tools) Delete(ctx context.Context, args DeleteArgs) (string, error)

Delete removes one managed document.

func (*Tools) Edit 

func (t *Tools) Edit(ctx context.Context, args EditArgs) (string, error)

Edit applies one structured edit to a managed document.

func (*Tools) Intake 

func (t *Tools) Intake(ctx context.Context, args IntakeArgs) (string, error)

Intake analyzes where new knowledge should land in a managed corpus.

func (*Tools) JournalUpdate 

func (t *Tools) JournalUpdate(ctx context.Context, args JournalUpdateArgs) (string, error)

JournalUpdate appends one journal-window entry to a managed document. 

func (t *Tools) Links(ctx context.Context, args LinksArgs) (string, error)

Links returns outgoing links, backlinks, or both for one indexed document.

func (*Tools) Move 

func (t *Tools) Move(ctx context.Context, args MoveArgs) (string, error)

Move relocates one managed document to a new semantic ref.

func (*Tools) MoveSection 

func (t *Tools) MoveSection(ctx context.Context, args SectionTransferArgs) (string, error)

MoveSection moves one section into another managed document.

func (*Tools) Outline 

func (t *Tools) Outline(ctx context.Context, args RefArgs) (string, error)

Outline returns the heading tree for one indexed document.

func (*Tools) Read 

func (t *Tools) Read(ctx context.Context, args RefArgs) (string, error)

Read returns one indexed document payload.

func (*Tools) Roots 

func (t *Tools) Roots(ctx context.Context) (string, error)

Roots returns summaries of the indexed document roots.

func (*Tools) Search 

func (t *Tools) Search(ctx context.Context, args SearchArgs) (string, error)

Search returns compact summaries for documents matching the structured filters.

func (*Tools) Section 

func (t *Tools) Section(ctx context.Context, args SectionArgs) (string, error)

Section returns one named section, or the whole body when no selector is given.

func (*Tools) Values 

func (t *Tools) Values(ctx context.Context, args ValuesArgs) (string, error)

Values returns observed frontmatter values for one key.

func (*Tools) Write 

func (t *Tools) Write(ctx context.Context, args WriteArgs) (string, error)

Write creates or replaces one managed document.

type ValueCount 

type ValueCount struct {
	Value string `json:"value"`
	Count int    `json:"count"`
}

ValueCount counts observed frontmatter values.

type ValuesArgs 

type ValuesArgs struct {
	Root  string `json:"root,omitempty"`
	Key   string `json:"key"`
	Limit int    `json:"limit,omitempty"`
}

ValuesArgs requests observed values for one frontmatter key.

type VerificationMode 

type VerificationMode string

VerificationMode describes the desired signature verification policy for consumers of a managed document root. 

const (
	// VerificationNone disables signature verification enforcement.
	VerificationNone VerificationMode = "none"
	// VerificationWarn records verification failures without blocking
	// consumers.
	VerificationWarn VerificationMode = "warn"
	// VerificationRequired marks the root as requiring trusted signed
	// history before high-integrity consumers should load or activate
	// content from it.
	VerificationRequired VerificationMode = "required"
)

type WriteArgs 

type WriteArgs struct {
	Ref          string              `json:"ref"`
	Title        string              `json:"title,omitempty"`
	Description  string              `json:"description,omitempty"`
	Tags         []string            `json:"tags,omitempty"`
	Frontmatter  map[string][]string `json:"frontmatter,omitempty"`
	Body         *string             `json:"body,omitempty"`
	JournalEntry string              `json:"journal_entry,omitempty"`
}

WriteArgs creates or replaces a whole managed document.

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.