Catalog

PFCL language reference · composure.systems

1.Scope

The catalog is the storage substrate for every function in a PFCL program. This document specifies the function catalog and the rules governing its content, admission, and lifecycle.

1. A catalog entry is a definition consisting of a name, a type, a body, and metadata. The body is the substantive content; the name and metadata are attached to it.
2. A catalog is a set of entries such that each entry's identity is unique and each entry's name resolves to at most one identity.
3. A loader is an implementation that reads a set of catalog files, verifies the admission rules of section 3, and constructs an in-memory catalog. A conforming loader either produces a catalog or refuses with a diagnostic; there is no partial admission.

2.Content addressing

Identity in the catalog is a function of the body alone.

1. Every catalog entry has an identity equal to the SHA-256 of the canonical form of its typed source body. The canonical form is the source text of the type and the body, in the language's parser-input encoding.
2. Two entries with byte-identical typed source bodies have identical identities. Two entries whose typed source bodies differ in any byte have different identities.
3. A name is a metadata field attached to an identity. The name is not part of the identity's computation. Two authors may use the same name for different bodies; the loader resolves names within a catalog per the admission rules of section 3.
4. A hash reference is a caller's declaration to reference a specific identity directly, bypassing name resolution. A body pinned by hash is stable regardless of any upstream rename, replacement, or supersession. Hash references are the mechanism by which a third-party consumer pins the exact body it audited.

3.Admission and loading

A loader admits or refuses each entry against the rules of this section. A catalog fails to load if any entry is refused.

1. A loader refuses an entry whose declared type does not typecheck against its body.
2. A loader refuses two entries within the same catalog that share a name but differ in identity.
3. A loader refuses an entry that references a name unresolvable in the catalog, unless the reference is a hash reference resolving directly.
4. A loader refuses an entry whose recursion is not admitted under the totality specification. See /totality for the admission rules on recursive bodies.
5. A loader refuses an entry that violates a layer-stratification cap. See section 4.
6. A loader that succeeds produces a catalog in which every name resolves to exactly one identity and every identity's body typechecks.

4.Layer stratification

Catalog entries are stratified into layers. Each layer admits progressively more complex bodies, and each caps composition depth and body size to a maximum. A layer is a metadata field on the entry; the loader enforces layer caps at admission.

1. The layers, in order from most restrictive to least: prim (primitives implemented outside PFCL, native to the host), std (standard-library functions composed over primitives), domain (domain-specific compositions), app (application-level compositions).
2. Each layer declares a maximum composition depth and a maximum node count. A body exceeding either cap for its declared layer is either refused or demoted to a deeper layer whose caps admit it, per the entry's declaration.
3. The caps at each layer reflect what a well-formed entry at that layer should look like. A prim entry is a leaf; an std entry is a shallow composition; a domain entry is deeper but still bounded; an app entry admits the deepest compositions and is expected to be a top-level orchestrator.

5.Governance at admission

Beyond structural validity, the loader applies governance mechanisms that push authoring toward small, composable units, and refuses or restructures entries that would degrade the catalog's utility as a substrate for composition. These mechanisms — machine-granularity naming, complexity limits, composability scoring, and forced decomposition — are specified separately at /catalog/governance.

6.Retirement

The catalog is append-only. An entry admitted once remains resolvable forever. When a new entry supersedes an existing one, the mechanism is name-alias rebind, not deletion.

1. An entry's identity is permanent. No mechanism removes an admitted identity from the catalog.
2. A newer entry may declare that it supersedes an older entry. The declaration rebinds the older entry's name to the newer entry's identity in the catalog's name index. The older identity remains addressable by hash reference.
3. A retired entry's body may be moved to a retired region of the catalog file layout, but its identity remains resolvable. Hash references to the retired identity continue to work.
4. Rollback of a supersession is a single name-alias rebind operation, resolving the name back to the older identity. Rollback latency matches deployment latency: minutes, not the days a package-manager rollback would require.

7.Exclusions

The catalog specification does not cover the following.

1. The analyzer's own soundness — whether the admission rules genuinely imply the properties they claim — rests on inspection and testing, not on a mechanical proof. Mechanical verification is future work.
2. The loader's implementation — file layout on disk, index representations, incremental load pipelines, error diagnostics — is left to conforming loaders. This specification fixes what the loader must decide, not how it implements the decision.
3. Physical storage — how catalog files are laid out on disk, distributed across a network, replicated for durability, or served from a bootstrap image — is out of scope. The catalog specification fixes the abstract structure; physical realizations are separate.
4. Synthesis — the process by which new entries are proposed for admission — is a separate surface with its own specification. The admission rules of this document govern what is accepted at load time; the mechanisms that produce candidates are elsewhere.
5. Equivalence between distinct identities — whether two catalog entries with different hashes behave the same way — is governed by a separate graded relation, specified at /catalog/equivalence. This document governs identity and admission, not equivalence.