Governance

PFCL language reference · composure.systems

1.Machine granularity as naming principle

A function earns a catalog entry when a synthesized composition would need it as an independently reachable building block, not when a programmer would give it a name.

1. Any intermediate type appearing in more than one function's body is a candidate for its own named entry, whether or not a human author would have named that intermediate step.
2. This principle produces more named entries than a hand-authored library would carry. A conventional standard library is named at the granularity a human finds convenient to remember; the PFCL catalog is named at the granularity a composition search finds convenient to reach.
3. The trade-off is explicit: a larger catalog, navigated by search and type rather than by browsing, in exchange for finer-grained reuse and shallower compositions.

2.Complexity limits

Two structural measurements are extracted from every candidate body at admission time: composition depth and node count.

1. Composition depth is the maximum nesting of function applications in the body.
2. Node count is the total number of intermediate representation nodes the body compiles to.
3. Each layer (see /catalog §4) declares a hard cap on each measurement. A body exceeding its layer's cap is refused outright, unless it can be admitted at a deeper layer whose caps accommodate it, or unless it qualifies for forced decomposition (section 4).

3.Composability scoring

A composability score is computed at admission from the entry's own type signature, independent of its body.

1. Output type currency. Whether the output is a universal type reusable across many downstream functions (e.g. List<A>, Maybe<A>) or a compound domain type reusable in few (e.g. a bespoke record shape). The former scores higher.
2. Signature generality. Whether the function's type parameters are polymorphic (A -> A) or fixed to concrete domain types. Polymorphic signatures score higher: they compose into more contexts.
3. Semantic role. Whether the function performs a medial transformation (an intermediate step other compositions can route through) or a terminal aggregation (an endpoint few things compose past). Medial functions score higher.
4. An entry scoring below a fixed threshold, with no active demand for it in the growth queue, is refused. A low-scoring entry with active demand is admitted — desirability is necessary, not sufficient, and demand can override a low score.

4.Forced decomposition

A body that exceeds its layer's complexity caps (section 2) is not always refused outright.

1. The loader identifies natural split points at intermediate types appearing in the body.
2. It produces sub-specifications for each split point. The original entry is deferred, not refused; the sub-specifications enter the growth queue as separate admission candidates.
3. If every sub-specification is independently admitted, the original caller is rewritten to compose the resulting sub-entries, and the original entry is retired in favor of the composition.
4. If any sub-specification fails to admit, the original entry is refused outright — decomposition does not lower the bar, it only offers a second path to the same bar.

5.What governance does not decide

Governance operates only on candidates already reachable by name resolution and already typechecking under /catalog §3. It does not decide:

1. Whether two admitted entries are semantically equivalent despite differing identity — that is a separate, still-developing mechanism (near-duplicate detection and canonical-representative redirection at admission time). See /catalog/equivalence for the mechanism once it exists; this page does not describe it in advance of being built.
2. Where new candidates come from — the synthesis process that proposes entries for admission is out of scope here, per /catalog §7.