schema

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package schema loads the vault's machine-readable contract (System/schemas/vault-schema.toml) and answers status state-machine questions. It is the only package allowed to read that contract: nowhere else holds a second copy of an enum, a field list, or a lifecycle rule.

Index

Constants

View Source 
const (
	// ContractRelPath is where the contract lives inside the vault.
	ContractRelPath = "System/schemas/vault-schema.toml"

	// SealStatus is the status of a note that has been reviewed and approved.
	// It is pinned here rather than derived because no contract field singles
	// the value out.
	SealStatus = "ready"

	// PublishedStatus records a completed publication outside the vault.
	// Nothing here can attest one, so no control offers a transition to it and
	// the write face refuses one; the value enters a note by hand.
	PublishedStatus = "published"

	// DraftStatus is the status a note carries before anyone has offered it to
	// a reader. Like SealStatus it is pinned here rather than derived: a
	// lifecycle table can start a type anywhere, and no field singles the value
	// out, so the faces that reason about "not offered yet" ask for this
	// instead of each writing the word down.
	DraftStatus = "draft"
)

Variables

View Source 
var (
	ErrUnknownStatus     = errors.New("status not defined for this type")
	ErrIllegalTransition = errors.New("transition not allowed by lifecycle")
)

Sentinel errors for state-machine answers. Callers match with errors.Is.

Functions

func ContractAbsent 

func ContractAbsent(err error) bool

ContractAbsent reports whether err from Load, LoadFile, or LoadReader means the folder carries no contract at all, as distinct from one that exists and could not be read. A folder that declared nothing is not one in trouble.

func NormalizeStatus added in v0.2.0 

func NormalizeStatus(s string) string

NormalizeStatus is the one spelling rule for a status word: every comparison against a declared status goes through it, both the contract's values as they are read and a note's own value as it is judged. A status arrives decomposed from the filesystem and composed from the search index, so the bytes are folded before anything compares them. Case is deliberately not folded — two statuses differing only in case are two declarations the contract meant.

func ParseLanguageTag 

func ParseLanguageTag(raw string) (string, error)

ParseLanguageTag validates and canonicalizes one authored BCP 47 tag.

func SameDirName added in v0.2.0 

func SameDirName(a, b string) bool

SameDirName reports whether two path components name the same directory. It is the one comparison every vault directory scope makes, so no scope drifts from another on how a directory name is spelled.

Case folds because a case-insensitive filesystem opens the same file under any case spelling; strings.EqualFold folds per rune, so ß matches ẞ but never "ss". Composition is deliberately not folded: a scan reports composed paths, so a contract spelling a directory in decomposed form matches nothing.

Types

type ArticleLanguage 

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

ArticleLanguage resolves the optional BCP 47 language tag a vault contract declares for authored note content. Its zero value answers with no tag at all, never with one inferred from a note's path, domain, or text.

func (ArticleLanguage) Resolve 

func (l ArticleLanguage) Resolve(frontmatter map[string]any) (string, error)

Resolve returns a canonical BCP 47 tag for one note frontmatter map. A tag comes back only where the contract gives the field authority and the note declares a value the tag grammar accepts; missing authority, a missing field, and a rejected value all come back empty, the last with an error.

An empty answer states nothing, so a page's article inherits the language its chrome is written in. It is not a claim that the note's language is unknown — a note declaring the undetermined tag by hand still gets it back.

type ArtifactPolicy 

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

ArtifactPolicy identifies vault directories whose files are readable artifacts but not governed note instances. The zero value is unclaimed, so the excluded set is empty and every readable file is an ordinary instance.

func (ArtifactPolicy) Available 

func (p ArtifactPolicy) Available() bool

Available reports whether the contract declared a valid artifact policy.

func (ArtifactPolicy) Capture 

func (p ArtifactPolicy) Capture() ArtifactPolicy

Capture validates the source once and returns an immutable policy for one request, so the classification cannot change underneath a response already using it.

func (ArtifactPolicy) Claim 

func (p ArtifactPolicy) Claim() Claim

Claim reports how far the artifact declaration got. A policy whose source bytes changed after startup can no longer be honoured, whatever it said.

func (ArtifactPolicy) Diagnostic 

func (p ArtifactPolicy) Diagnostic() string

Diagnostic explains why the artifact policy could not be honoured. It is empty when the policy was read cleanly and empty when nothing declared one.

func (ArtifactPolicy) IsNonInstance 

func (p ArtifactPolicy) IsNonInstance(rel string) bool

IsNonInstance reports whether rel is equal to or below a declared artifact directory, comparing whole components through the folded identity every vault directory scope shares. An unclaimed policy excludes nothing; an unresolved one also answers false, so callers gate on Trustworthy first.

func (ArtifactPolicy) Trustworthy 

func (p ArtifactPolicy) Trustworthy() bool

Trustworthy reports whether the excluded set may be projected over: true when it was read cleanly or never declared, false when a declaration was made and could not be honoured.

func (ArtifactPolicy) ValidateSource 

func (p ArtifactPolicy) ValidateSource() ArtifactPolicy

ValidateSource returns p only while the contract source it was derived from is unchanged. Copies of one Contract share a one-way stale latch, so once any consumer observes drift every instance projection stays unavailable. A source that cannot be read at all closes this caller's projection and nothing more: it is no evidence the declaration was withdrawn, and the next caller reads the file again.

type Capabilities added in v0.2.0 

type Capabilities struct {
	Navigation NavigationRoles
	Knowledge  KnowledgeScope
	Artifacts  ArtifactPolicy
	Language   ArticleLanguage
}

Capabilities are the four declarations one process runs on, resolved together so no consumer can combine a vault-level fault with a zero capability and conclude that nothing was excluded.

type Claim 

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

Claim is one declaration's outcome: how far it got, why it failed where a caller can act on the answer, and the operator-facing sentence when the outcome is news. The zero Claim is unclaimed and silent. A Claim can be closed from outside this package but never opened — authority comes from a contract that was read, never from a caller asserting it.

func Rejected 

func Rejected(diagnostic string) Claim

Rejected returns the claim for a declaration that was made and could not be honoured. The closure is a fact about the declaration, not about whether anyone wrote a sentence for it: a capability answered from the presence of a message is the failure this type exists to remove.

func (Claim) Cause added in v0.2.0 

func (c Claim) Cause() error

Cause is the error behind the rejection, nil where there is none. It travels beside Reason so a surface can name the fault in its own words and still quote what the loader said.

func (Claim) Claimed 

func (c Claim) Claimed() bool

Claimed reports whether anything ever asserted this at all.

func (Claim) Diagnostic 

func (c Claim) Diagnostic() string

Diagnostic is the operator-facing sentence, empty unless there is news.

func (Claim) Reason added in v0.2.0 

func (c Claim) Reason() Reason

Reason names why this declaration was rejected, where a caller can act on the answer rather than only print it. It is ReasonUnstated for a claim that holds, for one nothing ever made, and for a rejection with nothing more to say.

func (Claim) Trustworthy 

func (c Claim) Trustworthy() bool

Trustworthy reports whether a projection over this declaration's set may be answered. It holds for a declaration read cleanly and for one never made — an undeclared set is the empty set — and fails only where an assertion was made and could not be honoured.

type Contract 

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

Contract is the validated, immutable vault authority. Its zero value carries no authority; load one with Load, LoadFile, or LoadReader. A nil *Contract answers as an ungoverned vault: every method is safe to call and returns what a folder that declared nothing declares — no version, no vocabulary, no capability, no legal transition.

func Load 

func Load(root string) (*Contract, error)

Load reads the contract from the vault rooted at root, and LoadFile from an explicit path. Neither is on the served path, which loads through LoadReader so a capability binds to the exact file it came from; these two serve a caller that holds only a path.

func LoadFile 

func LoadFile(path string) (*Contract, error)

func LoadReader 

func LoadReader(ctx context.Context, reader *vaultfs.Reader) (*Contract, error)

LoadReader reads the contract through the same pinned vault capability that an agent-facing action uses for note collection and source revalidation.

func (*Contract) ArticleLanguage 

func (c *Contract) ArticleLanguage() ArticleLanguage

ArticleLanguage returns the contract-derived article-language resolver. The field is authoritative only when the universal fields.known vocabulary declares "lang"; a lesson-only declaration cannot describe every note.

func (*Contract) ArtifactPolicy 

func (c *Contract) ArtifactPolicy() ArtifactPolicy

ArtifactPolicy returns the contract-derived artifact policy capability.

func (*Contract) Capabilities added in v0.2.0 

func (c *Contract) Capabilities(g Governance) Capabilities

Capabilities resolves this contract's declarations against what the folder asserted about the contract as a whole. A folder with no contract answers with the zero capabilities, every declared set being empty; one that claimed authority and could not be read closes every projection, its sets unknown.

Each withheld capability carries the vault-level sentence rather than silence. Language is the exception: it has no Available or Diagnostic for a claim to feed, so it returns the same "not declared" zero value.

func (*Contract) ConceptType added in v0.2.0 

func (c *Contract) ConceptType() (name string, declared bool)

ConceptType returns the note type a vault files as its distilled ideas, and whether this contract declares it at all. The name comes back either way, so a caller can say which type it looked for.

func (*Contract) DeclaresType added in v0.2.0 

func (c *Contract) DeclaresType(noteType string) bool

DeclaresType reports whether noteType is listed in the contract's own type vocabulary, so a face can decline a rule about a type this vault never named.

func (*Contract) Definition 

func (c *Contract) Definition() Definition

Definition returns a detached copy of the contract's declarative vocabulary and validation policy. A vault no contract governs declares an empty vocabulary.

func (*Contract) Governance 

func (c *Contract) Governance() Governance

Governance reports what this contract asserts. A nil contract governs nothing.

func (*Contract) InboxRequiredFields added in v0.2.0 

func (c *Contract) InboxRequiredFields() (noteType string, fields []string, declared bool)

InboxRequiredFields returns the note type a vault reserves for captures whose shape is not yet decided, the fields it requires of one, and whether the contract declared that requirement at all. An explicitly empty list is still a declaration: it says a capture is required to carry nothing.

func (*Contract) KnowledgeScope 

func (c *Contract) KnowledgeScope() KnowledgeScope

KnowledgeScope returns the top-level directories this vault calls its knowledge layer.

func (*Contract) LessonType added in v0.2.0 

func (c *Contract) LessonType() (name string, declared bool)

LessonType returns the note type a vault files its course members as, and whether this contract declares it at all. The name comes back either way, so a caller can say which type it looked for.

func (*Contract) NavigationRoles 

func (c *Contract) NavigationRoles() NavigationRoles

NavigationRoles returns the contract-derived navigation role capability.

func (*Contract) PrivacyPolicy 

func (c *Contract) PrivacyPolicy() PrivacyPolicy

PrivacyPolicy returns the contract-derived fail-closed egress capability.

func (*Contract) RequiresFrontmatter added in v0.2.0 

func (c *Contract) RequiresFrontmatter() bool

RequiresFrontmatter reports whether this vault treats a note carrying no frontmatter block as a fault. Only a contract that wrote the scan declaration down and set it against legality asks for that; silence is not a prohibition.

func (*Contract) Stage 

func (c *Contract) Stage(noteType, status string) (Stage, bool)

Stage returns the lifecycle entry for setting status on a note of the given type, or false when the contract defines none.

func (*Contract) StageCount 

func (c *Contract) StageCount() int

StageCount returns the number of lifecycle rows declared by the contract.

func (*Contract) StatusGroup 

func (c *Contract) StatusGroup(noteType string) string

StatusGroup returns which status enum group applies to a declared note type. An empty note type selects the default "note" group for aggregate views. An undeclared non-empty type returns "".

func (*Contract) Statuses 

func (c *Contract) Statuses(noteType string) []string

Statuses returns the legal status values for a declared note type. An empty note type selects the default "note" group; an undeclared type returns nil, and so does a vault no contract governs.

func (*Contract) Supersession 

func (c *Contract) Supersession() (Supersession, bool)

Supersession returns the configured replacement-ledger vocabulary, or false when the contract declares none.

func (*Contract) Transition 

func (c *Contract) Transition(noteType, from, to string) error

Transition reports whether a note of the given type may move from one status to another. An empty from means the note is being given its initial status. Lifecycle owner lists are declarative data and play no part. The returned error wraps one of the package sentinels; a vault no contract governs refuses every move as an unknown status.

func (*Contract) Version 

func (c *Contract) Version() string

Version returns the contract format version, empty for a vault no contract governs.

type Definition 

type Definition struct {
	Enums  Enums      `toml:"enums"`
	Fields Fields     `toml:"fields"`
	Rules  Rules      `toml:"rules"`
	Scan   ScanPolicy `toml:"scan"`
}

Definition is a detached copy of the contract's declarative vocabulary and validation policy. Mutating it never changes the loaded Contract.

type Enums 

type Enums struct {
	Type           []string            `toml:"type"`
	Domain         []string            `toml:"domain"`
	SourceKind     []string            `toml:"source_kind"`
	SourceProvider []string            `toml:"source_provider"`
	Level          []string            `toml:"level"`
	MapKind        []string            `toml:"map_kind"`
	Status         map[string][]string `toml:"status"`
}

Enums holds the closed value sets for frontmatter fields.

type Fields 

type Fields struct {
	Required      []string            `toml:"required"`
	RequiredInbox []string            `toml:"required_inbox"`
	DomainExempt  []string            `toml:"domain_exempt_types"`
	Known         []string            `toml:"known"`
	LessonOnly    []string            `toml:"lesson_only"`
	StatusGroup   map[string][]string `toml:"status_group"`
}

Fields describes required and known frontmatter keys.

type Governance 

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

Governance is what a folder asserted about its own contract, whether or not that assertion could be honoured. A folder carrying no contract governs nothing and is not in trouble; one whose contract cannot be read claimed governance it failed to deliver.

func Ungoverned 

func Ungoverned() Governance

Ungoverned is the answer for a folder that carries no contract file.

func Unreadable 

func Unreadable(err error) Governance

Unreadable records a contract file that exists and could not be loaded, which without this is indistinguishable from a folder carrying none. The claim carries the reason and the loader's error rather than a finished sentence: a contract loads at startup, before any reader has asked for anything, so only the surface knows which language to say it in.

func (Governance) Claim 

func (g Governance) Claim() Claim

Claim returns the vault-level outcome as a capability claim, so a projection closed by the contract itself carries the same reason value as one closed by a single declaration.

func (Governance) Diagnostic 

func (g Governance) Diagnostic() string

Diagnostic is the vault-level sentence, empty unless the contract asserted governance it could not deliver.

func (Governance) Governed 

func (g Governance) Governed() bool

Governed reports whether anything claimed authority over this vault. It is true for a contract that loaded, for one that could not be read, and for one that left a section out: the claim is what governs, not its completeness.

func (Governance) Reason added in v0.2.0 

func (g Governance) Reason() Reason

Reason names why the contract could not be honoured, empty of meaning unless this vault claimed governance and failed to deliver it.

func (Governance) Trustworthy 

func (g Governance) Trustworthy() bool

Trustworthy reports whether the contract's declarations may be projected over.

type KnowledgeScope 

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

KnowledgeScope is the set of top-level directories a vault calls its knowledge layer, separating the notes its owner reads from generated reports, templates and machinery. A folder that declares nothing has no scope, and then nothing is outside it.

func (KnowledgeScope) Available 

func (s KnowledgeScope) Available() bool

Available reports whether the contract declared a knowledge layer.

func (KnowledgeScope) Claim 

func (s KnowledgeScope) Claim() Claim

Claim reports how far the scan declaration got.

func (KnowledgeScope) Includes 

func (s KnowledgeScope) Includes(relPath string) bool

Includes reports whether a vault-relative path is inside the knowledge layer, and true for everything when no scope was declared: an undeclared set excludes nothing. Only the first path segment is consulted, folded the way every other vault directory scope folds one. 

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

NavigationRoles classifies note types used for ordered study paths and general maps; its membership sets cannot be changed after loading. The zero value is unclaimed, so both sets are empty and no note is either. 

func (r NavigationRoles) Available() bool

Available reports whether the contract declared a valid navigation role set. 

func (r NavigationRoles) Claim() Claim

Claim reports how far the navigation declaration got. 

func (r NavigationRoles) Diagnostic() string

Diagnostic explains why navigation roles could not be honoured. It is empty when they were read cleanly and empty when nothing declared them. 

func (r NavigationRoles) IsMapType(noteType string) bool

IsMapType reports whether noteType is declared as a general map. 

func (r NavigationRoles) IsPathType(noteType string) bool

IsPathType reports whether noteType is declared as an ordered study path. 

func (r NavigationRoles) Trustworthy() bool

Trustworthy reports whether the role sets may be projected over: true when they were read cleanly or never declared, false when a declaration was made and could not be honoured.

type PrivacyPolicy 

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

PrivacyPolicy is the vault contract's fail-closed egress capability. Its zero value is unavailable, and callers ask the positive EgressAllowed question so a missing or invalid policy cannot be mistaken for permission. It is the one capability where an unclaimed declaration and a rejected one behave alike; only the reporting differs.

What it binds is the agent-facing output — the check, coverage and exists commands, which are its only consumers. The reading pages serve every note the folder holds and never ask this question, so a note withheld from a command is still served to the reader at the keyboard. Binding the pages too would be a different decision, not a repair to this one.

func (PrivacyPolicy) Available 

func (p PrivacyPolicy) Available() bool

Available reports whether the contract declared a valid privacy policy.

func (PrivacyPolicy) Claim 

func (p PrivacyPolicy) Claim() Claim

Claim reports how far the privacy declaration got.

func (PrivacyPolicy) Diagnostic 

func (p PrivacyPolicy) Diagnostic() string

Diagnostic explains why the privacy policy could not be honoured. It is empty when the policy was read cleanly and empty when nothing declared one.

func (PrivacyPolicy) EgressAllowed 

func (p PrivacyPolicy) EgressAllowed(rel string) bool

EgressAllowed reports whether rel is a valid vault-relative path outside every never-egress directory. The unavailable and malformed-path cases are deliberately false: permission is positive authority, never the absence of a deny match.

func (PrivacyPolicy) Trustworthy 

func (p PrivacyPolicy) Trustworthy() bool

Trustworthy reports whether the never-egress set may be reasoned over.

func (PrivacyPolicy) ValidateSource 

func (p PrivacyPolicy) ValidateSource() PrivacyPolicy

ValidateSource returns p only while the contract source it was derived from is unchanged. Copies of one Contract share a one-way stale latch, so once any consumer observes drift all agent-facing output stays unavailable. A source that cannot be read at all withholds this caller's answer and nothing more: it is no evidence the declaration was withdrawn, and the next caller reads the file again.

type Reason added in v0.2.0 

type Reason uint8

Reason names, in a value a caller can branch on, why a declaration could not be honoured. Most rejections carry only an operator's sentence; the vault-level one reaches an ordinary reader's page, which is written in a language chosen per request rather than when the contract was loaded. 

const (
	// ReasonUnstated is a rejection with no machine-readable reason: the
	// diagnostic sentence is the whole of what is known.
	ReasonUnstated Reason = iota
	// ReasonContractUnreadable is a contract file that exists and could not be
	// loaded. Cause carries the loader's own error, so a surface can name the
	// fault in whichever language it is speaking.
	ReasonContractUnreadable
)

func (Reason) String added in v0.2.0 

func (r Reason) String() string

String names a rejection reason for a diagnostic, a log line or a panic. These words are for an operator reading a machine's output; a reader's own sentence comes from the dictionary at the surface. A reason outside the constants is a programming error and panics.

type Rules 

type Rules struct {
	DomainEqualsFolderUnder   []string `toml:"domain_equals_folder_under"`
	ConceptRequiresProvenance []string `toml:"concept_requires_provenance"`
	SlugPattern               string   `toml:"slug_pattern"`
	ForbidTagWithSlash        bool     `toml:"forbid_tag_with_slash"`
}

Rules holds structural rules beyond plain enums.

type ScanPolicy 

type ScanPolicy struct {
	KnowledgeDirs        []string `toml:"knowledge_dirs"`
	SkipBasenames        []string `toml:"skip_basenames"`
	NoFrontmatterIsLegal bool     `toml:"no_frontmatter_is_legal"`
}

ScanPolicy is the checker's default scan policy (tool policy, not schema fact).

type Stage 

type Stage struct {
	Status    string   `toml:"status"`
	AppliesTo []string `toml:"applies_to"`
	Initial   bool     `toml:"initial"`
	From      []string `toml:"from"`
	Owner     []string `toml:"owner"`
}

Stage is one lifecycle entry: a status, the types it applies to, whether a note may start there, its legal predecessor states, and who may set it. "*" in From or AppliesTo means any.

Initial and From answer separate questions. A contract naming the initial key states both; one that names it nowhere has Initial inferred from an empty or wildcard From.

type Supersession 

type Supersession struct {
	PredecessorField string
	SuccessorField   string
	GeneralLinkField string
	ArchivedStatus   string
}

Supersession names the frontmatter fields and archive status that form the vault's explicit replacement ledger.

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.