Composability

Composure platform reference · composure.systems

1.Scope

This document specifies the composition surfaces of Composure and the mechanisms by which each supports composition. It is a property of the catalog and the platform, not of any individual artifact.

1. A composition surface is a category of Composure artifacts that admits a closed operation for combining artifacts of that category into further artifacts of the same category.
2. Composure has four composition surfaces: functions, handlers and apps, data definitions, and the data algebra derived from a data definition's type.
3. Composability is the property that composition on each surface is well-defined, free of accidental interference between artifacts, and does not degrade the guarantees of the composed parts.
4. The function-level surface and the mechanisms operating on it are inherited from PFCL and are specified further at /composability. This document restates them for completeness and then extends the specification to the handler, app, data-definition, and data-algebra surfaces the platform adds.

2.Function composability

Seven mechanisms of the language and the catalog structure make functions compose freely.

1. Content addressing. Every function is identified by the SHA-256 of its typed source body. Identity is a function of the body, not of the name or the storage location.
2. Names are aliases. A function's name is metadata, not identity. Two authors may use the same name for different bodies; the hashes distinguish them. Namespace conflict is removed as a reason to write larger functions.
3. Purity composes. A function composed of pure functions is pure. See /purity.
4. Totality composes. A function composed of admitted functions is itself admitted. See /totality.
5. Direct hash reference. A caller may reference a function by its hash directly, bypassing name resolution. A body pinned by hash is stable through any upstream rename or replacement.
6. No versioning. A semantic change to a function produces a new function at a new hash. Existing references continue to resolve to the exact body they were audited against.
7. Effects are values. A function that needs to describe an effect returns a command record; a host reads the record and performs the action. Composition is uniform across effect-describing and effect-free functions, up to the host boundary. See /effects-as-data.

3.Handler and app composability

A handler is a pure PFCL function of the shape (Resources, State, Event) → (State, Commands). An app is a bundle of a handler with a resource type, a state type, and configuration. Handlers and apps compose through a closed algebra with three composition primitives.

1. Handlers are pure functions. A handler inherits every function-level composability mechanism from section 2. Handler composition is function composition at a specific signature.
2. The handler algebra is closed. Every composition of handlers is itself a handler with the shape (R, S, Event) → (S, Commands) for some R and S determined by the composition. The algebra admits no shape outside this signature; composition never produces a non-handler.
3. Three composition primitives. The primitives are: compose, which combines two handlers into a handler over the product of their resources and their states; compose_shared, which combines handlers sharing a common resource; pipe, which composes handlers by piping the output signals of one into the event stream of another.
4. Product types thread resources and state through arbitrary nesting. A composed handler's resource type is the product of its sub-handlers' resource types; the same holds for state. The type system tracks the product structure through arbitrary levels of composition.
5. Content-addressed identity for composed handlers. A composed handler is identified by the hash of its composition. Identical compositions deduplicate; different compositions have different hashes.
6. Purity and totality pass through composition. Handlers are pure PFCL functions, so their compositions are pure. Handlers admitted under the totality specification compose without additional witnesses at the composition site.
7. IoProvider-agnostic composition. Composition operates entirely in the pure handler layer. An IoProvider needs no modification to run a composed handler; it sees a handler with a signature it already understands.
8. Recursively nestable. Compositions of compositions work without special handling. compose(compose(a, b), pipe(c, d)) yields a handler with the appropriate composed signature, and the composed handler participates in further composition on the same terms.
9. App contracts. A handler's behavioural contract — the events it consumes, the commands it emits, the data operations it performs on its state — is inferred from its abstract syntax tree and stored as non-identity metadata. Contracts do not affect handler hashes.
10. Pipe compatibility from contract overlap. Whether two handlers can be composed via pipe is derivable from the overlap between the first handler's output contract and the second handler's input contract. The compatibility relation is a query over contracts.

4.Data definition composability

A data definition is a description of a data structure — its interfaces, its performance contracts, its sharing profile. Data definitions compose through an interface hierarchy and through cross-references to the function catalog.

1. Interface hierarchy. Interfaces such as Indexed, Keyed, Ordered, Appendable, Membership, FixedCapacity, and their extensions form an inheritance hierarchy. A caller reasoning about a data structure at the interface level is decoupled from the concrete structure.
2. Multiple structures per interface. The same interface is implemented by several concrete data structures. Structure selection is a query over the interface hierarchy, filtered by performance affinity and sharing profile.
3. Cross-references to the function catalog. A data definition declares which catalog functions it supports and at what cost. The function catalog owns the operations; the data definition owns the guarantees under which the operations execute against a specific structure.
4. Content-addressed identity. A data definition is identified by the hash of its definition, not by its name. The identity model matches the function catalog's.
5. Structural sharing. Immutable updates propagate through composed data by path-copy, append-only, or copy-on-write, depending on the structure. Composition of large data structures does not require copying the parts that did not change.

5.The data algebra

Every data definition determines a bounded menu of operations derivable from its type. The menu is closed by a single law.

1. A data definition is a type built from known constructors: records, lists, sums, primitives, nominal types.
2. Any operation that is a function of the type's structure alone is derivable from the type without author work. The derived menu includes optics per field, prisms per variant, traversal over the enumeration, find and filter, diff, codec, validation.
3. An operation is on the derived menu iff it is a function of structure. Operations that require domain knowledge stay authored.
4. The data algebra composes with the function algebra and with the handler algebra. Derived optics thread into handlers as focus targets; derived traversals combine with catalog functions to produce further catalog entries.

6.Cross-surface references

The four surfaces reference each other through content-addressed identity.

1. Functions reference other functions by hash.
2. Handlers are functions and follow the same rules. Composed handlers reference their sub-handlers by hash.
3. App contracts reference data definition interfaces by name; the resolution happens against the data definition catalog at contract inference time.
4. Data definitions reference function catalog operations by name for their contract declarations.
5. The data algebra supplies operations that catalog functions and handlers call on values of the corresponding data definition.

The composition graph is content-addressed at every reference. A change to any one artifact propagates through hashes rather than through name resolution, which is what makes composition across authorship boundaries safe: a third-party module dropped into a consumer's catalog cannot silently alter any hash-pinned reference already in use.

7.Exclusions

The composability guarantee does not cover the following.

1. Composability is not automatic. It rests on structural mechanisms of the language, the catalog structure, and the platform's composition primitives. Removing any of these mechanisms would degrade the property.
2. Composability is not the mathematical property of function composition alone. That follows from purity. This document specifies the platform mechanisms that make composition of many small units easier than composition of few large ones.
3. Catalog governance is out of scope for this page. The mechanisms that push authoring toward small composable units at admission time — complexity limits, composability scoring, layer stratification, forced decomposition, machine granularity as a naming principle, retirement via supersession — are specified at /catalog. This page describes composition of already-authored artifacts; the catalog page describes how the catalog stays well-composed as it grows.
4. IoProvider composition is out of scope for this page. IoProviders are the platform's boundary to the host environment and follow their own composition rules, specified separately.