Configuration Domain API Guidelines

Core Semantics

document = immutable rooted tree of typed configuration values
section = named map, ordered list, or text-indexed map of child values
name path = absolute or relative sequence of configuration names
source = configuration input with a stable identity
source authorization = independent trust decision for every resolved source
signature validation = application trust decision over the parser's exact digest and signature data

Validation Rule Model

root rule = implicit rule for the complete document or section branch passed to validation

Primary Types

Value // immutable node in a parsed configuration tree
Document // root value and metadata of one configuration document
Parser // ELCL parser and policy coordinator

Value and Document Types

Integer, Float // configuration scalar numeric representations
Name, NamePath // configuration key component and complete value path
Location // source location attached to a parsed value
DocumentBuilder // programmatic configuration document builder
ValueIterator, ValueList, ValueMatrix // tree traversal and aggregate value types
Matrix❮Value❯ // rectangular aggregate with per-row defined lengths
ValueType, NameType // value and name classifications

Source and Trust Types

Source, SourceResolver, FileSourceResolver // configuration input and include resolution
SourceIdentifier, SourceResolverContext // stable source identity and include context
AccessCheck, FileAccessCheck // custom and file-based source authorization
AccessCheckResult, AccessSources // access decision and source classification
Signer, SignatureSigner // document signing service and application signature callback
SignatureValidator // application signature validation callback
SignatureSignerData, SignatureValidatorData // exact signing and validation inputs
SignatureValidatorResult // accepted, rejected, or unsupported signature result

Validation Rules Types

Rules // finalized, reusable validation schema
RulesBuilder // public programmatic construction entry point
RuleDefinition // stable mutation interface supplied to builder attributes
Rule, Constraint // read-only validated rule metadata
RuleType, ConstraintType, DependencyMode // rule, constraint, and dependency classifications

Error Types

ConfError // configuration parsing, access, validation, or signing failure
ConfErrorContext // structured configuration diagnostic context
ConfErrorCategory // stable configuration failure category

Pattern Definitions

C = ❮CoreType❯ // matching Core scalar type
Vp = ValuePtr/ValueConstPtr // shared mutable or immutable configuration value

Value Access Patterns

o.type()/name()/namePath()/location() -> T // inspect a value's identity and source metadata
o.as❮Type❯() -> C // get a scalar value or its documented fallback
o.as❮Type❯OrThrow() -> C // get a scalar value or throw ConfError for a type mismatch
o.value(path) -> Vp // find a child value or return an empty pointer
o.valueOrThrow(path) -> Vp // find a child value or throw ConfError
o.get❮Type❯(path[, default]) -> C // get a typed child or a fallback
o.get❮Type❯OrThrow(path) -> C // get a typed child or throw ConfError
o.begin()/end() -> ValueIterator // iterate direct children without flattening the tree

Document Construction Patterns

o.addSectionMap/addSectionList(path) // add a section container
o.add❮Type❯(path, value) // add a scalar using the shared scalar mapping
o.document() -> DocumentPtr // finish or access the built document
o.reset() // discard the current construction state
o.toFlatValueMap() -> ValueMap // index all values by absolute name path

Parsing Patterns

o.parse(source) -> DocumentPtr // parse or return an empty pointer and retain the error context
o.parseOrThrow(source) -> DocumentPtr // parse or throw ConfError
o.parseFile/parseText(input) -> DocumentPtr // convenience parsing with non-throwing failure reporting
o.parseFileOrThrow/parseTextOrThrow(input) -> DocumentPtr // convenience parsing with exceptions
o.lastError() -> ConfErrorContext // inspect the latest non-throwing parse failure
o.setSourceResolver/setAccessCheck/setSignatureValidator(policy) // install parsing trust policies

Validation Rule Construction Patterns

o.configureRoot([attributes]) // configure the implicit document/section root rule
o.addRule(path, type[, attributes]) // add one named rule
o.addAlternative(path, type[, attributes]) // add one permitted alternative at a path
o.takeRules() -> RulesPtr // validate, finalize, and reset the builder
T(mode, sources, targets[, error]) // create a dependency builder attribute
o.apply(rule) // custom attributes mutate RuleDefinition without implementation types

Source and Trust Patterns

T::fromString/fromFile(input) -> SourcePtr // create a closed in-memory or file source
o.resolve(context) -> SourceList // resolve an include into deterministic candidate sources
o.check(source, context) -> AccessCheckResult // authorize one source independently
o.validate(data) -> SignatureValidatorResult // validate exact parser-produced signature data
o.sign(source, destination, signer) // insert or replace a document signature