Documentation
¶
Overview ¶
Package policy loads governance/protocol policy metadata from a YAML file and converts it into NodePolicy + EdgeGovernedBy rows that fold into the main CKG graph.
Why a separate package (and an external YAML rather than parsed code): the policies CKG cares about — fork block activations, gas schedules, consensus parameters, security pattern annotations — are typically described in documentation and config files that don't have a single canonical place in the source tree. Parsing them out of source would either miss most of the signal (the rationale lives in comments) or over-fit each codebase's idiosyncratic file layout. A separate YAML per project keeps the policy surface explicit and editable without forcing CKG to know each project's conventions.
See docs/PROJECT-BLUEPRINT-ALIGNMENT.md §4.2 P1 #4 for the design intent and the go-stablenet-specific use cases (params/config.go fork blocks, consensus/wbft/* policies, systemcontracts/*).
Schema ¶
The YAML envelope:
policies:
- id: "fork.berlin"
name: "Berlin Hard Fork"
category: "consensus"
description: "Increases gas cost for SLOAD/SSTORE..."
activated_at: 12244000 # optional, fork-style policies
governs: # qnames of code symbols this policy constrains
- "params.MainnetChainConfig.BerlinBlock"
- "core/vm.gasSLoadEIP2929"
Every Policy node carries id, name, category, description as node fields (id → QualifiedName; name → Name; category → SubKind). activated_at and any other typed metadata fall into the attrs JSON blob via marshalNodeAttrs at persist time — this keeps the schema extensible without per-field column churn.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry struct {
ID string `yaml:"id" json:"id"`
Name string `yaml:"name" json:"name"`
Category string `yaml:"category,omitempty" json:"category,omitempty"`
Description string `yaml:"description,omitempty" json:"description,omitempty"`
ActivatedAt int64 `yaml:"activated_at,omitempty" json:"activated_at,omitempty"`
Governs []string `yaml:"governs,omitempty" json:"governs,omitempty"`
}
Entry is one policy row from the YAML file. Field tags use snake_case to match the canonical YAML form; the lowerCamelCase JSON tags exist so the same struct can round-trip through internal/manifest if a caller wants to embed loaded policies in a build report.
type File ¶
type File struct {
Policies []Entry `yaml:"policies"`
}
File is the top-level YAML envelope. Single key "policies" keeps the document explicit (a bare list at the root is valid YAML but harder to read in editors and harder to extend with envelope-level metadata — version, source-of-truth pointer, etc.).
func LoadFromFile ¶
LoadFromFile reads, parses, and validates a policy YAML file. Returns an error wrapping the underlying yaml.Unmarshal / os.ReadFile error when the file is missing or malformed — callers should treat policy loading as best-effort enrichment and fall back to building without it when this errors. An empty / absent `policies:` key is NOT an error; the result has zero entries.
Validation: every entry must have a non-empty ID. Duplicate IDs are flagged because Resolve treats ID as the node's primary key (it becomes QualifiedName); two entries sharing an ID would collide on INSERT OR REPLACE and silently drop one. Empty governs lists are allowed — a policy entry that documents context without a direct code anchor still adds searchable rationale to the graph.
type ResolveResult ¶
type ResolveResult struct {
Nodes []types.Node
Edges []types.Edge
Warnings []ResolveWarning
}
ResolveResult bundles the outcome of Resolve so the buildpipe caller can persist the rows and surface the warnings as build metadata.
func Resolve ¶
func Resolve(f *File, codeNodes []types.Node, policyFilePath string) ResolveResult
Resolve builds the Policy nodes + governed_by edges to fold into the main graph.
- One NodePolicy per entry, with QualifiedName=ID, Name=Name, SubKind=Category, DocComment=Description. FilePath cites the loading file (set by the caller before persist if a citation is wanted; Resolve doesn't see the path).
- One EdgeGovernedBy per (matched governs[i], policy) pair. Direction = governed code symbol → policy.
The matching loop walks an index built once from byQname so a 50-entry policy file × 200k code nodes stays at the O(P+N) order rather than O(P·N). Missing references emit a ResolveWarning instead of failing the build — policy metadata is additive; an outage in the YAML must not block the parsing-derived graph from landing.
type ResolveWarning ¶
ResolveWarning records a governs[] entry that didn't find a matching code node in the parsed graph. Surfaced verbatim in the build log so editors of the policy YAML can spot stale references (a function got renamed, a config field got moved) without having to compare the YAML against the source tree by hand.
Source Files