policy

Documentation

Overview

Package policy compiles source policy configurations into a versioned JSON artifact (compiled/policies.json) that the daemon loads at startup for fast, lock-free policy enforcement.

Policy compilation is a build-time step run via `bubblefish build`. It validates all [source.policy] blocks against the known destination set and serialises the result atomically. The daemon never re-reads raw TOML on the hot path — only the compiled artifact.

Index

• func Compile(entries []PolicyEntry, outputDir string, logger *slog.Logger) error
• func OutputPath(compiledDir string) string
• func Validate(entries []PolicyEntry, knownDestinations map[string]bool) error
• type CompiledPolicies
• type FieldVisibilityEntry
• type PolicyCacheEntry
• type PolicyDecayEntry
• type PolicyEntry

Functions

func Compile

func Compile(entries []PolicyEntry, outputDir string, logger *slog.Logger) error

Compile writes a compiled/policies.json artifact to outputDir containing all provided PolicyEntry values. Validation is the caller's responsibility (call Validate before Compile).

The write is atomic: data is written to a temp file in outputDir, fsynced, then renamed to policies.json. Both the temp file and the final file receive 0600 permissions. outputDir is created with 0700 if it does not exist.

Reference: Tech Spec Section 9.1, Phase 1 Behavioral Contract items 4–5.

func OutputPath

func OutputPath(compiledDir string) string

OutputPath returns the canonical path for the compiled policies artifact within the given compiled directory.

func Validate

func Validate(entries []PolicyEntry, knownDestinations map[string]bool) error

Validate checks that every allowed_destinations entry in each PolicyEntry names a known destination. It also checks for duplicate entries within the same source's allowed_destinations list.

knownDestinations is the set of destination names loaded from the destinations/ directory. Build must fail (SCHEMA_ERROR) on the first violation; callers must not proceed to Compile on error.

Reference: Tech Spec Section 6.1, Phase 1 Behavioral Contract item 2.

Types

type CompiledPolicies

type CompiledPolicies struct {
	Version    string        `json:"version"`
	CompiledAt time.Time     `json:"compiled_at"`
	Policies   []PolicyEntry `json:"policies"`
}

CompiledPolicies is the root structure written to compiled/policies.json. It records the daemon version and timestamp so operators can audit when policies were last compiled.

type FieldVisibilityEntry

type FieldVisibilityEntry struct {
	IncludeFields []string `json:"include_fields"`
	StripMetadata bool     `json:"strip_metadata"`
}

FieldVisibilityEntry mirrors [source.policy.field_visibility].

type PolicyCacheEntry

type PolicyCacheEntry struct {
	ReadFromCache               bool    `json:"read_from_cache"`
	WriteToCache                bool    `json:"write_to_cache"`
	MaxTTLSeconds               int     `json:"max_ttl_seconds"`
	SemanticSimilarityThreshold float64 `json:"semantic_similarity_threshold"`
}

PolicyCacheEntry mirrors [source.policy.cache].

type PolicyDecayEntry

type PolicyDecayEntry struct {
	HalfLifeDays      float64 `json:"half_life_days"`
	DecayMode         string  `json:"decay_mode"`
	StepThresholdDays float64 `json:"step_threshold_days"`
}

PolicyDecayEntry mirrors [source.policy.decay] (per-source override). All fields are optional; zero values mean "use the daemon-level default".

type PolicyEntry

type PolicyEntry struct {
	Source                string               `json:"source"`
	AllowedDestinations   []string             `json:"allowed_destinations"`
	AllowedOperations     []string             `json:"allowed_operations"`
	AllowedRetrievalModes []string             `json:"allowed_retrieval_modes"`
	AllowedProfiles       []string             `json:"allowed_profiles"`
	MaxResults            int                  `json:"max_results"`
	MaxResponseBytes      int                  `json:"max_response_bytes"`
	FieldVisibility       FieldVisibilityEntry `json:"field_visibility"`
	Cache                 PolicyCacheEntry     `json:"cache"`
	Decay                 PolicyDecayEntry     `json:"decay"`
}

PolicyEntry is the compiled policy for a single source. It mirrors all [source.policy] TOML fields verbatim so no TOML parsing is required at runtime.

Reference: Tech Spec Section 9.3.