Raw source: Foundations/01-Composability/README.md

As in Structure and Interpretation of Computer Programs (SICP), the starting point here is that the power of software does not lie primarily in isolated procedures or data structures, but in the ways they can be combined. Complex systems become manageable when they are built from parts that can be understood locally and composed into larger wholes. Composability is therefore not an ornament of good design, but one of the main conditions under which software remains intelligible as it grows.

Abstraction is the companion principle. It allows us to work with stable interfaces while temporarily ignoring lower-level detail, and it allows us to construct larger systems without having to hold all of their internals in mind at once. In this sense, composability and abstraction are not separate topics: abstraction makes composition tractable, and composition gives abstraction something to organize.

This is also part of why ordng is developed in a Haskell/IHP/HTMX setting. Haskell gives composability unusually strong support at the level of functions, types, and explicit interfaces, while HTMX favors interfaces built from small server-rendered interactions rather than a large client-side control system. Neither technology guarantees good structure by itself, but both make compositional design more natural and more visible.

The following sections apply this general principle more specifically. In 02-CodeAbstraction/, the question is how code can be shaped into reusable helpers, interfaces, and lightly coupled structures. In 03-DomainAbstraction/, the question is how the same concern appears on the side of the modeled world: atomic units, typed relations, taxonomies, and polymorphic roles. The purpose of this first section is simply to keep the general principle in view before those more specific applications begin.

Raw source: Foundations/02-CodeAbstraction/README.md

The question is not only how to write correct code, but how to shape code so that generic concerns acquire stable names and interfaces, while concrete application code remains readable at the call site. Helpers, components, controllers, views, and scripts should not each solve the same general problem for themselves. Reusable structure should be extracted once, so that what remains local can stay genuinely local.

A good abstraction keeps generic implementation detail out of application code and places it instead into explicit helper functions, interfaces, and support modules. The scope reaches from idiomatic use of Haskell and HTMX, through recurring framework-level structures above raw IHP conventions, up to component-based and hierarchically organized design systems. The user interface is only the most visible case of this. The same compositional logic can be applied across the application, so that a substantial part of the system is shaped by explicit layers of reusable structure rather than by isolated one-off code. But extraction is not an end in itself. The decisive question is always whether a piece of code has become reusable enough, stable enough, and legible enough to justify abstraction. Reuse is therefore not just a convenience gained afterward, but one of the tests of whether the abstraction is real.

Once such abstractions have become clear enough to formulate canonically, they enter the pattern library in Patterns/. There they can be documented as reusable coding patterns above raw IHP and HTMX conventions, while concrete applications keep their own local realizations at the edge. This includes not only the patterns themselves, but also further architectural documentation of how such principles are realized, for example in Patterns/ARCHITECTURE.md, where the structure of pattern modules and the boundary between reusable helper infrastructure and concrete use are made explicit. The same applies to recurring project bootstrap work after generators such as ihp-new: once the post-generator baseline has stabilized, it belongs in Patterns/Bootstrap/ as a reusable setup pattern rather than as oral tradition. That bootstrap layer is part of the fully opinionated ordng path, while the other pattern topics remain usable independently of it. The aim is lightly coupled application code whose moving parts remain understandable, but whose recurring structures do not have to be reinvented in every file.

Raw source: Foundations/03-DomainAbstraction/README.md

03-DomainAbstraction/ carries the concerns of abstraction and composability over from code into the modeled world. It asks what the primary units are, how they relate, how they are classified, and how structure can become more explicit without collapsing into separate silos.

At the center is a simple claim: a good system should not force a choice between free association and structured classification. The same unit should be able to participate in both. A note, block, item, or entry should be linkable as a node in a graph, classifiable in one or more taxonomies, and enrichable with typed structure, without being rewritten into a different kind of thing each time.

The core modeling move is to treat content as atomic enough to be reusable, but not so rigidly typed that every new use case requires a new silo. At least at first, this means ordinary-language textual content: names, titles, descriptions, comments, and similar material that is meaningful to a human reader but not already structured for the program like enums, calculable numbers, or parseable URLs. Precisely because such content is not exhaustively understood by the program itself, it becomes valuable to model it as small reusable units that can exist meaningfully in several contexts at once.

That does not mean every text field must immediately become a node. The important distinction is whether the text should stay purely local to one entity or whether it should become reusable, addressable, or independently relatable across contexts.

Typical relation types in this area might include:

• description — a title or name node has a more detailed explanatory child
• definition_of_done — a project or task node points to criteria text
• outline_parent / outline_child — ordinary outliner hierarchy between text nodes
• comment — one text node comments on another
• example — a concept node points to an example node
• citation or reference — one node points to a source-like node
• revises / supersedes — one text node replaces or updates another
• supports / contradicts — argument-like relations between statements

This means small addressable units instead of monolithic documents only, typed relationships instead of mere unstructured linkage, graph navigation for association, discovery, and serendipity, taxonomy for reliable placement, maintenance, and traversal, and optional overlays, frames, or roles rather than one fixed essence per atom.

Many systems force one-sided choices. Classic document tools privilege linear structure. Outliners privilege explicit hierarchy. Graph tools privilege free linking but often neglect stable classification. Database-like tools privilege predefined schemas and rigid containers. Low-code systems often model structure well, but leave associative knowledge work impoverished. ordng is interested in a more general substrate where these are different views on the same underlying material.

A content system built in this spirit should be able to refer to small units directly, not only to whole pages or documents. These atoms may later appear as knowledge nodes, authoring blocks, tasks, definitions, sources, arguments, or records in a more operational system. The point is not that everything must look identical in the UI, but that the underlying model should permit reuse and recombination.

A recurring idea in the notes is that the same atom should be findable in at least two ways: via associative links, similarity, or relevance, and via explicit hierarchical or taxonomic placement. This is not an either-or. Graph-style association helps with discovery, cross-domain connections, non-linear thought, serendipitous retrieval, and low-friction capture. Taxonomic structure helps with reliable placement, maintainable classification, shared orientation, programmatic traversal, and explicit constraints and expectations. The model therefore needs both.

There is also no reason to assume one universal hierarchy. The same atom may belong simultaneously to several taxonomic structures, for example topic hierarchies, organizational hierarchies, onboarding or tutorial structures, workflow or process classifications, or required-knowledge trees. This matters because taxonomies serve different purposes. They are not merely alternate labels for the same tree.

This already implies that relationships cannot remain anonymous. Different relations behave differently: some are symmetric, some directional, some hierarchical, some temporal, some restrictive in cardinality. The system therefore needs explicit relation semantics.

Relationship Type Properties

Each relationship type can be understood as having its own characteristics:

This matters because a reference is symmetric, while a supports is not, and a defines relation may be constrained much more tightly than a loose cross-reference.

The question is not whether every domain relation must be lifted into an explicit relation-type system. Some relation semantics can already be read from ordinary relational structure, while others cannot.

In the atomic model, fields such as inverse_name with a foreign-key constraint to relation_types.name are still ordinary text columns; the constraint only adds referential integrity.

Multi-Dimensional Relationship Graphs

The same atom should be able to participate in several kinds of relationship structure at once:

• Free links: associative, similarity-based, graph-like
• Taxonomic hierarchy: broader/narrower, kind-of, part-of, and related classificatory structures

A useful first distinction is this:

Once this is made explicit, one can build not only generic graphs, but several kinds of navigable structure on the same atoms:

• Knowledge graphs: Terms → definitions → examples → counter-examples
• Argumentation maps: Thesis → supporting arguments → counter-arguments → rebuttals
• Citation networks: Block cites Block, visible in both directions
• Concept taxonomies: Broader/narrower term relationships
• Multiple parallel taxonomies: Topics, departments, document types — same block belongs to several

Taxonomy only becomes practically useful if the system helps with placement. That suggests features such as breadcrumb display, suggestions of existing parent concepts before near-duplicates are created, and directional rather than undifferentiated display for hierarchical relations. Backlinks remain useful, but they are only one retrieval mechanism among several. They do not by themselves create order.

Graph traversal also matters because it enables serendipity: accidental but meaningful discovery is not merely a UX flourish here, but one of the reasons to prefer a graph-capable model in the first place.

Polymorphic Atoms

One of the strongest ideas in the older notes is that a node should not have to stop being itself when it acquires more structure. The point is not that every concern should be collapsed into one uniform graph table. It is that reusable semantic units should not be trapped inside one local entity each time the domain becomes more structured.

In traditional systems, this is often the painful point. One decides too early whether something is a Task or a Note, and migration becomes expensive. The alternative explored here is to keep reusable nodes comparatively naked, then let explicit domain entities and typed relations carry the richer structure around them.

Frames are optional metadata overlays. They do not replace the atom beneath them. This sketch remains useful as a view model: it shows how one node can appear with multiple contextual frames in presentation and navigation. AtomicDomainModel.md addresses the persistence model instead.

At least in the first patterns we are currently exploring, these atoms or nodes are still text-bearing units. That is not a trivial detail. It is one of the reasons polymorphism is useful here in the first place: titles, names, descriptions, topic entries, and similar pieces of ordinary-language content are different in role, but alike enough in substance that a shared content-bearing micro-entity becomes valuable.

Even there, a minimal content-type distinction may still be useful. A first node model may therefore keep a simple closed distinction such as ordinary-language content versus code, without immediately turning node typing into a large taxonomy of content kinds.

The richer fields then belong on explicit domain entities or, when the relation itself carries domain structure, on explicit domain-relation tables. This keeps the node layer reusable while still allowing the surrounding model to stay strict.

This keeps migration cheap and lets a system evolve from loose capture toward stronger structure. It also shows why the relevant notion of a type system here is not only a programming-language concern. The content model itself may need to express which kinds of relations exist, which constraints hold on them, and where richer domain structure belongs instead of falling back to untyped property bags.

Attributes, Relations, and Aliases

A useful observation from the Podio comparison is that structured systems are not fundamentally alien here. Podio-like systems can be understood as a special case where relations are more predefined, some are mandatory, and entries also carry typed attributes. Roam-like systems can be understood as the opposite special case where relations are much freer, explicit attributes are minimal or absent, and text carries much of the burden. The interesting modeling task is therefore not choosing one camp, but finding an abstraction that can host both.

If atoms are to be first-class, they also need stable and human-usable ways to be addressed. That points toward aliases, generated short handles, searchable summaries, and link targets that do not depend on long raw text.

The same logic also applies to internal content structure. If a task title and a task description are both text-bearing semantic units, the model may benefit from treating them as related nodes inside one content structure rather than as unrelated scalar fields spread across separate tables. In that case, the difference between title and description is carried not by the bare existence of two different text columns, but by the typed relation that links one content node to another.

Aliases make atomic structure usable in practice. They support search autocomplete, quick linking, and the treatment of the same atom as page-like when it becomes a stable reference point.

Adjacent Pressures from Application Design

Some of the motivating notes are not pure foundation, but they reveal pressures that shape the model.

There is an unresolved but productive tension between page-based systems and endless-document systems. The deeper issue is not the exact UI choice, but whether the model privileges page containers or smaller atoms as the primary unit.

The notes on journals versus curated pages point to a related question: how rough captures relate to stabilized knowledge, how a system distinguishes inbox material from integrated material, and how backlinks should behave when rough and processed notes coexist. These are workflow questions, but they put pressure on the underlying model.

Another recurring theme is whether external content such as tweets, blog posts, or code should be copied in, referenced, indexed, or authored directly inside the system. This matters because the atomic model may need to host both native and imported material.

The notes also hint at a third top-level category beyond trees and nodes: queries. Once relations, types, and taxonomies become explicit, derived views and computed collections stop being incidental UI features and become part of the conceptual system.

Relationship to Patterns/

This strand stays on the conceptual side. It is concerned with questions such as what kind of thing the primary unit is, how graph relations and taxonomies coexist, what makes a node polymorphic, and which distinctions belong in the model itself.

When the ideas here become explicit reusable implementation guidance, they belong in Patterns/, especially in future domain/data-oriented pattern topics. This may include canonical worked examples or overtragbare structure patterns, but the point here is the principle rather than a ready-made schema to copy unchanged.

For adjacent model traditions and prior art, see AdjacentModels.md. For neighboring software products, see AdjacentProducts.md.

Adjacent Models and Prior Art

Raw source: Foundations/03-DomainAbstraction/AdjacentModels.md

This note collects nearby model traditions for the ideas discussed in README.md. The point is not to collapse ordng into one of them, but to make the neighborhood explicit.

Short Conclusion

The general idea is not new. Several established traditions already combine some of these elements:

• graph-shaped association,
• typed relationships,
• schema-bearing or schema-bound graph models,
• flexible polymorphic content or entity structures,
• and hybrid approaches that keep relational domain entities while exposing graph structure.

What seems more specific in the current ordng line of thought is the particular combination:

1. explicit operational domain entities remain intact,
2. only the semantic content layer is polymorphized into reusable nodes,
3. relation types are modeled explicitly as reusable semantic objects,
4. the same node layer supports both internal content structure and wider knowledge-graph relations.

In this sense, ordng should not simply adopt the standard property-graph vocabulary wholesale. node is a good fit, but relation remains more precise than edge, because the important point is not merely that two nodes are connected, but what semantically determined relation holds between them.

Property Graphs

The closest broad family is the property graph model.

Property graphs treat nodes and edges as first-class. Nodes and edges can carry properties. In the common labeled property graph style, nodes may also carry labels, while edges typically carry a single label naming the kind of connection. That already covers a large part of the desire for free association plus explicit relation semantics.

These properties are ordinary node or edge attributes, not vector embeddings. A property graph is therefore a logical graph model, not a commitment to a vector database, nor even necessarily to a native graph database. The same model can also be implemented, or projected, over relational tables.

At the same time, these labels and key-value properties are comparatively untyped. In practice, the same keys have to be reused consistently, whether programmatically or manually, if later queries, rendering, or application logic are supposed to treat them as the same property. The same applies to labels: if one writes a different string, whether intentionally or by typo, one has in effect created a different label.

That edge label is still weaker than an explicitly modeled relation type. It is closer to tagging a connection than to representing the relation type itself as a reusable semantic object with its own properties. The stronger move in the current ordng direction is therefore not merely to name a connection, but to make the relation type itself a reusable semantic object with explicit properties.

Distinction from Atomic Domain Modeling

In ordng, nodes are not primarily enriched by open-ended property bags, but by explicit assignment into one or more richer domain entities or overlays. That yields stricter and more expressive structure than free key-value extension alone.

Relations follow a similar logic. One could always introduce a domain-specific junction table when a particular relation needs extra fields. The stronger move here, however, is the introduction of a generalized relation type that is assigned rather than written as a free string. This makes reusable tree and graph structures programmable in a stricter and more reliable way, because the model depends on explicit assignment rather than repeated string conventions.

What property graphs do not by themselves settle is how strongly the graph remains bound to an explicit application domain model, or how much of the domain should remain relational and operational rather than being flattened into one generic graph substrate.

Reference:

• https://en.wikipedia.org/wiki/Property_graph

SQL/PGQ and Graph Views Over Relational Tables

The hybrid thought, relational domain entities plus graph structure, is now explicit in the SQL/PGQ direction.

SQL/PGQ and related PGQL work allow property graphs to be defined over existing relational tables. This means one does not have to choose between a relational model and a graph model in an all-or-nothing way. Instead, graph structure can be projected from or layered over a relational base.

This is especially relevant as neighboring prior art because it confirms that the combination of explicit domain tables and graph traversal is not an eccentric idea, but an emerging standard direction.

References:

• https://pgql-lang.org/
• https://www.enterprisedb.com/blog/representing-graphs-postgresql-sqlpgq

EAV and Related Extensible-Schema Models

The Entity-Attribute-Value family is another clear neighbor.

EAV is an older response to schema rigidity. It makes attributes more flexible and metadata-driven, often with explicit attribute-definition tables and dynamic validation metadata. Extensions such as EAV/CR and EAV/CSG add classes, relations, sets, and graph structure.

This is relevant because it shows that people have long tried to avoid premature commitment to rigid entity silos.

At the same time, ordng is not simply an EAV system. The current direction does not primarily start from sparse attributes or arbitrary user-defined fields. It starts from reusable semantic content units and typed relations between them, while still keeping explicit operational entities where that remains useful.

A useful contrast to property-graph thinking is that what those models often treat generically as node or edge properties gets split more strictly here: global schema-level fields stay ordinary columns, domain-specific fields stay attached to explicit domain entities or overlays, and only genuinely ad-hoc per-node or per-relation metadata would motivate a later property-like extension.

References:

• https://en.wikipedia.org/wiki/Entity%E2%80%93attribute%E2%80%93value_model
• https://pages.cs.wisc.edu/~ajkunen/eav/overview.html

Schema-Bound Typed Graph Models

Another close neighbor is work that criticizes schema-light property graphs and argues for stronger type discipline.

Fritz Laux's "The Typed Graph Model" is directly relevant here. It proposes a schema-bound typed graph model with properties and labels, explicitly arguing that graph flexibility should not require giving up data quality or structural guarantees.

This matters because it lands close to one of the central ordng intuitions: graph freedom is useful, but not sufficient. Relation semantics, admissible structures, and explicit types still matter.

Reference:

• Fritz Laux, "The Typed Graph Model": https://arxiv.org/abs/2110.00991

Haskell Ecosystem

Within the Haskell world, the nearest neighbors seem to fall into two separate camps rather than one combined model tradition.

On the graph side, libraries such as algebraic-graphs and fgl show serious work on graph representation, graph algebra, and labeled edges. They are relevant because they confirm that Haskell has a strong tradition of thinking carefully about graph structure. What they do not appear to provide is the particular synthesis explored here: explicit domain entities, a reusable node layer, explicit relation-type entities, and one shared semantic enforcement layer across both graph-like and domain-like relations.

On the relational side, libraries such as beam and persistent are strong exactly where one would expect Haskell to be strong: typed schemas, typed fields, typed joins, typed query construction, and generally much stricter correspondence between program structure and database structure than is common in dynamic frameworks. That is highly relevant to ordng, because it shows that Haskell already offers a mature culture of type-driven relational modeling. What seems missing there is not strictness, but the particular move of lifting relation semantics themselves into explicit reusable domain objects that bridge freer graph structure and traditional domain entities.

So the Haskell ecosystem does contain strong ingredients for this direction, but mostly in separate traditions: graph libraries on one side, strongly typed SQL and schema libraries on the other. The current ordng model still looks more like a synthesis across those traditions than like a straightforward reuse of one existing Hackage pattern.

Topic Maps

Topic Maps are older and come from a somewhat different tradition, but conceptually they are surprisingly close.

Their core vocabulary is topics, associations, and occurrences. All of these can be typed. Topic Maps also distinguish between the semantic subject layer and the concrete resources in which those subjects occur.

That makes them interesting adjacent prior art for at least three reasons:

• they treat relationships as explicitly typed,
• they separate semantic subjects from concrete resource occurrences,
• and they support a knowledge model that is not reducible to one simple hierarchy.

This is not the same as the current ordng pattern direction, but it is useful evidence that typed associations plus resource anchoring have deep precedent.

References:

• https://www.ontopia.net/topicmaps/materials/tao.html
• https://en.wikipedia.org/wiki/Topic_map

Working Distinction for ordng

A useful working distinction is therefore:

• Property graphs show that typed edges and rich relationship semantics are established.
• SQL/PGQ shows that relational and graph views can be deliberately combined.
• EAV-family models show that extensible, metadata-driven structure has a long history.
• Typed graph models show that graph flexibility can remain schema-bound.
• Topic Maps show that typed semantic associations and resource anchoring are older than the current graph-database wave.

The question for ordng is therefore not whether this territory is untouched. It is which synthesis is worth making explicit, and which boundaries matter so that the result does not dissolve into either a generic EAV system, a schema-light property graph, or a pure ontology stack.

Adjacent Products

Raw source: Foundations/03-DomainAbstraction/AdjacentProducts.md

This note collects software products that sit near the model territory discussed in README.md. The point is not to claim that they implement the same architecture as ordng, but to identify useful neighboring product directions.

Short Conclusion

No widely known personal knowledge management product appears to implement the exact combination currently explored in ordng:

• explicit operational domain entities,
• a reusable semantic node layer,
• generalized relation types as explicit semantic objects,
• and graph or tree structures built by assignment rather than by repeated free strings.

Still, several adjacent products illuminate parts of the space.

Anytype

Anytype is probably the closest broadly known product in this neighborhood.

It treats everything as an object, supports types, supports relations between objects, and exposes graph-like views over those connections. This already places it much closer to typed semantic structure than page-and-link tools such as Roam or Obsidian.

At the same time, it still appears to operate more as an object-property-relation system than as the particular synthesis explored in ordng. The current ordng direction keeps asking more explicitly how free semantic nodes, explicit operational entities, and generalized relation types can coexist in one stricter model.

References:

• https://doc.anytype.io/anytype-docs/getting-started/types
• https://doc.anytype.io/anytype-docs/getting-started/types/relations

Capacities

Capacities is also close, especially on the object-type side.

Its core unit is the object. Objects have types, types have properties, and object properties can point to other objects. This gives Capacities a stronger structural model than most wiki- or outliner-style PKM tools.

What seems less explicit there, compared with the current ordng direction, is the idea of a generalized relation-type layer that is itself modeled as a reusable semantic object rather than remaining mostly inside the object-property system.

References:

• https://docs.capacities.io/reference/content-types
• https://docs.capacities.io/reference/properties
• https://docs.capacities.io/reference/object-properties

Tana

Tana is another nearby product direction.

Its supertags and structured node model clearly move beyond plain free-form notes. A Tana node can remain freely linkable while also carrying a more explicit schema through its supertag and fields.

This makes Tana relevant as an example of how graph-like note systems and stronger structure can coexist. What is less clear, in comparison to ordng, is whether relation types themselves are elevated into an explicit reusable semantic layer, rather than remaining mostly implicit in fields, references, or application conventions.

Reference:

• https://tana.inc/

Logseq and Roam

Logseq and Roam remain important neighboring tools, but mainly as examples of the other side of the spectrum.

Both are strong in free linking, graph navigation, and flexible capture. Both also have some notion of attributes or properties. But in common usage they still lean much more toward free-form graph structure plus conventions than toward a strict semantic model with explicit reusable relation types.

They therefore help clarify what ordng is trying not to stop at.

References:

• https://logseq.com/
• https://roamresearch.com/

Working Distinction for ordng

A useful practical distinction is this:

• Anytype, Capacities, and Tana show that users do want freer note-like units and stronger structure in the same product.
• Logseq and Roam show the power of free graph navigation and low-friction capture.
• ordng is trying to make the semantic and domain-model side more explicit than these tools usually do, especially around node reuse, relation typing, and assignment into stricter modeled structures.

Atomic Domain Model

Raw source: Foundations/03-DomainAbstraction/AtomicDomainModel.md

This document describes the atomic domain model as a generic mental model for atomic domain abstraction.

The point of the model is not to dissolve the domain into one undifferentiated graph. Explicit domain entities remain. What changes is that reusable nodes and typed relations form a shared semantic layer around them.

Diagram Reading

The diagram above shows three structural containers.

• Explicit domain entities - domain_entity_a and domain_entity_b keep their own fields; the model does not dissolve the domain into generic property bags.
• Typed domain relations - a_b_relations connects explicit domain entities while still naming a shared relation_type.
• Atomic semantic layer - nodes, relation_types, and node_relations form the reusable semantic substrate. enums (content_type, cardinality_bound) live inside this layer as supporting value sets.

Edge colors:

• Red - connections to nodes (reusable node references)
• Green - connections to relation_types (typed relation semantics)
• Blue - connections between explicit domain entities
• Grey — connections to enums (value-set references)

Nodes

nodes are the reusable semantic units. They hold addressable content such as names, descriptions, topic entries, and similar small units. The model keeps a minimal content_type distinction so that ordinary-language content and code do not collapse into one undifferentiated text bucket.

They intentionally stay comparatively naked. Once richer structured fields are needed, the model should normally move into explicit domain entities or explicit domain-relation tables rather than reintroducing generic key-value bags at node level.

A useful decision rule is this:

• keep a field on nodes only if it is intrinsic to the node and should remain the same across all uses of that node,
• model something as an additional node plus typed relation when it is itself semantic content,
• keep workflow or view-specific state outside the node layer, typically on domain entities or other context-specific structures.

This is why content_type clearly belongs on the node, while things like comments are better modeled as nodes linked by a relation type such as comment, and draft or review state is usually better treated as context-dependent rather than intrinsic to the reusable node itself.

Domain Entities

domain_entity_a and domain_entity_b stand for explicit domain objects. They keep their own domain fields. This is important: the model does not replace ordinary domain structure with generic property bags.

What changes is that each domain entity points to a node_id. The reusable node carries the semantic unit that can later also participate in cross-cutting structures beyond the one local entity table.

Relation Types

relation_types make relation semantics explicit. A relation type is not just a string written onto a connection. It is a modeled object with its own identity and its own semantic properties, such as symmetry, hierarchy, and inverse relation.

This is the crucial step beyond loose graph labeling.

Relations

The model uses two relation families: node_relations for node-to-node structure and a_b_relations for relations between explicit domain entities. Both point to the same relation_types table.

This distinction matters. The purpose of separate domain-relation tables is not only to avoid polymorphic source and target fields. It is also to preserve rich domain-specific relation structure where the domain needs it. a_b_relations can therefore carry its own domain relation fields without collapsing back into generic key-value properties.

That shared relation_type field is the key to central enforcement logic. Because every relation must name a relation type, one general compliance layer can enforce symmetry rules, inverse relations, and cardinality bounds across the whole model instead of re-implementing them table by table. In that sense, the extra abstraction does not remove strictness. It relocates it into one reusable enforcement point.

If this typed relation substrate becomes central enough, a later data-layer step may also want reusable graph operations over it rather than only bespoke query code. For an adjacent implementation reference in that direction, see ../Literature/Sources/InductiveGraphsAndFunctionalGraphAlgorithms/.

Process modeling is a concrete candidate for this pattern. A task or activity should remain an explicit process-domain entity with fields such as implementation hook, version, expected inputs, output events, subject, or UI behavior. Its name or description can still point to reusable nodes. The edges and control-flow connectors of a process model, however, are naturally typed domain relations: sequence flow, conditional transition, message flow, subprocess boundary, and branch/join/loop structure all carry semantics that should be inspectable and enforceable. Some of these semantics may still be represented by explicit gateway or event entities rather than by relation rows alone. In either case, the right shape is usually not a bare generic node_relations row, but a process-specific relation table that still names a shared relation_type and can add fields such as condition, ordering, external export ID, gateway role, or projection metadata. For a related process-engine source, see ../Literature/Sources/ReferenziellTransparenteBusinessProzesse/.

In this model, typed relation tables use composite primary keys rather than surrogate id columns. The rule is strict: when a table is a relation table and carries the mandatory relation_type, its identity is the source-target-type triple itself.

Reading the Model

The intended reading order is:

1. domain entities stay explicit,
2. reusable nodes carry the semantic units that should not be trapped in one table,
3. typed relations connect nodes and domain entities in a way that remains semantically inspectable and programmatically reliable.

That is the core modeling move.

Raw source: Foundations/04-AgenticDevelopment/README.md

This strand is about implementing ordng patterns with AI agents without giving up the structural standards by which good software is usually judged. The central claim is simple: agents are most valuable in the mechanical part of software work, but only after the semantic decisions have been made and the success criteria have been made explicit. Tests are the machine-checkable subset of those criteria. In that sense, ordng is interested not merely in testable pattern rollout, but in success-criteria-driven rollout with as much of the verification as possible made executable.

For ordng, this is not a matter of prompt folklore in the abstract. The focus is narrower and more architectural: how code can serve simultaneously as implementation, specification, and documentation; how context systems, skills, and other forms of explicit guidance can reinforce that role; and how agent behavior can be tuned against such artifacts rather than against vague intentions alone. The point is to give both humans and agents clearer boundaries, more stable abstractions, and more reliable feedback loops.

This is also why agentic development cannot be separated cleanly from the rest of the repository. It depends on the same concern for composability, code abstraction, and explicit domain structure that appears in the earlier strands. AI assistance becomes useful when those structures are visible and pressure-tested, not when they are replaced by ad-hoc output. In this sense, agentic development is less a rival to ordinary software design than a stress test for it.

Armin Ronacher's MiniJinja port is a good concrete example of the stance taken here. The human decided the architecture and defended the semantics. The agent did the large volume of mechanical, test-backed work. The point was not to remove judgment, but to move repetitive rollout and verification effort onto the machine once the meaning of the work was already fixed. The mechanical part was not merely checked afterward; it was carried out against explicit criteria from the start.

For ordng, that means reusable patterns should usually be discovered and criteria-driven in a real target system first, not written in isolation. The target system is where friction, duplication, and unclear boundaries become visible; where a living example can be made to work end to end; and where the line between local behavior and reusable shape becomes easier to see. ordng is then the place where that insight is extracted, clarified, and stabilized as a shared pattern. After that, the refined pattern should be re-applied in the target system so that the shared abstraction and the living example do not drift apart.

A practical consequence is that agentic development benefits from repository shapes that reduce ambiguity before rollout starts. The human should decide the stable library/product boundary, keep the semantic core small, push volatile complexity into outer layers, and prefer names and module boundaries that make existing capabilities easy to discover. The agent should then be steered toward those surfaces rather than toward ad-hoc reinvention.

This is also the right place for negative constraints, but only at the layer where they actually belong. Rules such as avoiding bare catch-alls, raw SQL, raw UI inputs, or dynamic imports are not universal prompt advice; they are local repository policies that should sit next to the relevant pattern or subsystem. When possible, they should be enforced by typed wrappers, component boundaries, linting, or other executable checks rather than by prose alone.

In that sense, the job of the human is not just to prompt well, but to prepare a codebase that gives the agent good rails: explicit patterns, narrow interfaces, discoverable names, and machine-checkable constraints. The less the agent has to infer from vague intent, the less it falls back to generic internet priors.

This can happen in three increasingly structured execution modes:

1. manually, by copying, adapting, and checking the pattern without agent support,
2. interactively with an agent, step by step, whether through normal prompting, a plan file, or plan mode,
3. durably, when the mechanical rollout itself becomes checkpointed, testable, resumable, and approval-gated.

DurableExecution.md is about this third mode. It does not define the foundation itself, but one opinionated implementation path for the most structured form of pattern rollout.

A further consequence for ordng is that patterns should ideally expose their own rollout verification criteria. If a pattern can only be described but not checked, then the mechanical part of applying it still depends too much on human interpretation. If a pattern states its success criteria clearly, then the machine-checkable subset can be copied directly into an agentic rollout plan while the remaining criteria stay available for human judgment.

When these ideas become explicit reusable techniques, helper structures, promptable workflows, or application patterns, they belong in Patterns/. For downstream operational guidance on how to run this refinement loop with an agent, see Patterns/AGENTS_TEMPLATE.md.

Durable Execution for Pattern-Driven Agentic Development

Raw source: Foundations/04-AgenticDevelopment/DurableExecution.md

The Problem

Coding agents are good at mechanical work: apply a known pattern, fix tests one by one, migrate files to a new structure. But sessions are fragile. A crash, rate limit, or timeout at step 7 of 20 destroys all progress. The human restarts, re-explains, re-does steps 1–6.

Plan Mode in current agents makes it worse: the plan is a conversation artifact, not an execution artifact. "Step successful" means the agent says so. There's no checkpoint, no verifiable criterion, no resume.

The Solution: Absurd

Absurd is a Postgres-native durable execution system by Armin Ronacher (Flask, Rye/uv) and Earendil Inc. All runtime logic lives as stored procedures in one SQL file. No separate server, no broker. Apache 2.0.

A task is broken into steps. Each completed step is checkpointed in Postgres. Crash at step 7 → restart → steps 1–6 loaded from DB, continue at 7. Steps can await events (for human approval gates) or sleep (for scheduled work).

SDKs: TypeScript (~1,400 LOC), Python (~1,900 LOC), Go (experimental). CLI: absurdctl (Python, installed via uv/uvx). Dashboard: Habitat. Ships a Pi agent skill.

Absurd vs. Alternatives

Absurd is not Temporal, Inngest, or a message broker. The distinctions matter:

• vs. Kafka/RabbitMQ: Brokers transport messages. Absurd executes work — with checkpoints, retry, and state. What happens after delivery is their consumer's problem; it's Absurd's core job.
• vs. Temporal/Inngest: Full workflow platforms with deterministic replay, HTTP push, and large SDKs (Temporal's Python SDK: 170k LOC). Absurd is intentionally minimal: explicit step boundaries, pull-based workers, thin SDKs. Easier to explain, easier to self-host, fewer guarantees.
• vs. PGMQ: Pure queue, stops at message delivery. Absurd starts where PGMQ leaves off — tasks, checkpoints, events, sleep.

See Absurd's own comparison page for details.

Why Ronacher Built It (and What It's Not For)

Ronacher is explicitly anti-slop. His "Agent Psychosis" is a sharp critique of unattended agent loops that produce garbage. His position (shared by Pi creator Mario Zechner): autonomy for the mechanical parts, human judgment for the decisions.

The case study: porting MiniJinja from Rust to Go. 45 min human, 10h agent (7h unsupervised overnight), 2.2M tokens, $60. The agent ground through 400+ snapshot tests. Ronacher steered architecture and pushed back on shortcuts (agent wanted to skip error-message tests entirely instead of fuzzy-matching; agent tried to regress HTML escaping semantics and iterator behavior). The unsupervised phase started only after the semantic decisions were made. What remained was mechanical.

At Earendil, Absurd runs in production (5-month retrospective):

• Durable agent turns. Each LLM call is a checkpoint. Documented pattern for Pi SDK (patterns/pi-ai-agent), using @mariozechner/pi-agent-core. Each message_end event is persisted as a durable step; on retry, the agent loop rebuilds context from the step log and resumes with runAgentLoopContinue.
• Dedup'd cron jobs. Idempotency keys derived from task name + cron expression + time slot ensure each slot runs exactly once, even with multiple scheduler replicas.
• Deploy-safe background processing. Anything needing retry-and-resume.
• Child-task pipelines. Parent spawns children, awaits results. Added post-launch based on real need.

Production learnings: core design held up, hardened claim handling, watchdogs for broken workers, deadlock prevention, lease management edge cases. Decomposed steps (beginStep/completeStep) added for "before call / after call" patterns where you need to inspect before committing.

Ronacher on "The Final Bottleneck"

From The Final Bottleneck: the human is always the bottleneck — that's correct, because the human carries accountability. The machine speeds up the mechanical parts; it doesn't remove the need for understanding what's being shipped. Zechner's Pi embodies the same stance: 4 tools (Read, Write, Edit, Bash), shortest system prompt of any agent, no MCP, auto-closes PRs from untrusted contributors.

Durable Test-Driven Plan Mode

Today's Plan Mode is ephemeral. Absurd could make it an execution artifact for a test-driven plan:

1. Plan with success criteria. Each step defines an action and its pass condition. The machine-checkable subset can then run autonomously, for example tests green, file exists, grep matches, compiler errors = 0.
2. Steps become checkpoints. Completed steps are never re-executed. Crash → resume at the failed step.
3. Events as approval gates. A step can awaitEvent("human-approved-step-5") — staged autonomy: N steps autonomous, pause for review, continue.
4. Human reviews the plan, not the execution. Semantic decisions happen upfront. Grinding runs checkpoint-protected.

This is Ronacher's MiniJinja pattern generalized: the human defines the what and the success criteria, the agent grinds through the how, and Absurd ensures nothing is lost. In the best case, the human defines those criteria upfront and only re-enters the loop when a decision point or approval gate is actually needed.

The hard part isn't the tooling, it is writing good success criteria. This works best for tasks decomposable into criteria-driven steps with a substantial machine-checkable subset. For exploratory work, the human stays in the loop.

What Would Need to Be Built

Absurd has the primitives. The bridge between "plan in markdown" and "durable task" doesn't exist yet:

Why ordng Is a Natural Fit

Most projects can't use Durable Plan Mode effectively because their "patterns" are informal conventions — no machine can verify "did you apply the pattern correctly?" ordng solves this by design:

1. Patterns Are Typecheckable Specifications

Literate Haskell (.lhs) unifies prose, specification, and compilable code in one file. The success criterion for "apply this pattern" exists by construction:

ghci -fno-code Patterns/Htmx/Composed/LiveSearch.lhs  # exit 0 = correct

This gives Absurd something to checkpoint against. Not "the agent says done" but "the compiler says correct."

A stronger version of this would be for patterns to expose explicit rollout checks as part of the pattern itself. Then an execution system would not need a human to invent the verification step each time. It could copy the check from the pattern and run it mechanically.

2. Patterns Have Defined Application Order

The ordng Roadmap and extraction order define which patterns exist and how they relate. An agent rolling out patterns to a target system doesn't improvise a sequence — the sequence is documented.

3. The Refinement Loop Maps to Absurd Steps

ordng's development model (from this strand's README):

Reusable patterns should usually be discovered and pressure-tested in a real target system first [...] ordng is then the place where that insight is extracted, clarified, and stabilized [...] After that, the refined pattern should be re-applied in the target system.

Each phase is an Absurd step with a testable outcome:

Concrete Rollout Scenario

"Apply the HTMX Composed pattern LiveSearch to three search pages in the target system."

Each step is checkpointed. Crash at SearchB → SearchA stays done. Human reviews at approval gates, not at every compiler run.

Using ordng without Absurd

Everything in ordng works without Absurd. Patterns are patterns — use them manually, apply them with any agent, iterate in whatever workflow.

What Absurd adds is the last mile: once you know which pattern to apply where, the mechanical rollout becomes durable, testable, and resumable. For a single pattern, the difference is small. For rolling out patterns across a codebase, it's the difference between a frustrating afternoon and a reliable overnight run.

Practical Setup

Absurd needs only Postgres and one SQL file. If you're developing with IHP, you already have Postgres. Setup in the Pi Nix devShell is documented in <paths.repos.pi>/docs/agentic-os/absurd.md.

For the full technical reference (primitives, SDK details, comparison), see the Absurd docs.

Handover Notes from Initial Evaluation Session

The following points came up during the evaluation session and should inform next steps. Not all are resolved.

TigerFS — Related but Separate

TigerFS (GitHub: timescale/tigerfs) is a PostgreSQL-backed filesystem from the same ecosystem (Tiger Data = Timescale rebranded). It solves shared state (ACID file I/O, version history via .history/, instant cross-machine visibility), while Absurd solves durable execution. Both bet on "Postgres is enough." They share a Postgres instance, and adopting one lowers the barrier for the other. Evaluated separately in <paths.repos.pi>/docs/agentic-os/tigerfs.md.

Open Design Questions for Durable Plan Mode

• Plan format: Three obvious candidates exist: prose plans in Markdown, agent scripts in TypeScript, and, for the IHP-specific case, Haskell scripts. Needs a concrete proposal for which layer is canonical.
• Granularity: How fine-grained should steps be? Too coarse (one step = "apply pattern to entire module") loses crash-safety. Too fine (one step = "edit line 42") adds overhead and makes plans unreadable.
• Approval gate UX: awaitEvent is the primitive. A Pi-facing /approve command looks like the most natural first candidate, but the exact interaction still needs to be designed.
• Agent execution context: The likely model is a dedicated Pi session for the Absurd worker, so the worker keeps the normal tool environment instead of spawning a fresh agent context per step.
• Failure semantics: Retry should be reserved for transient external failures such as network errors, rate limits, or worker crashes. Failures of the success criteria themselves should normally pause for human intervention rather than loop blindly.

Nix Integration (Not Done Yet)

absurdctl is a Python CLI, installable via uv tool install absurdctl or uvx absurdctl. absurd-sdk is an npm package for the TypeScript SDK. Postgres runs in the Pi Nix devShell (shell-level, not system-level — explicit activation model). Tracked with concrete install plan in the Pi operational doc (<paths.repos.pi>/docs/agentic-os/absurd.md).

Effort Estimates (from Evaluation)

Sources

• Absurd Docs — Concepts — Patterns — Comparison
• Absurd in Production — Ronacher, April 2026
• Absurd Workflows — original announcement, November 2025
• Porting MiniJinja to Go — supervised autonomy case study
• Pi: The Minimal Agent — Ronacher on Zechner's design philosophy
• Agent Psychosis — anti-slop position
• The Final Bottleneck — human as accountability bottleneck
• Colin and Earendil — company founding, values
• A Language For Agents — Ronacher on what agents need from programming languages

Raw source: Patterns/Actions/README.md

Index and reference for action patterns in this directory.

This topic covers server-side request handling patterns: CRUD flows, authorization guards, response strategies, bulk operations, and error handling.

Planned Structure

Organize this topic by concern rather than by framework directory shape. Clusters include:

• single-entity CRUD flows
• bulk operations
• auth guards
• response strategies
• error handling

Catalog

Pattern Shape

.lhs files in this topic follow the seven-section pattern skeleton from ../ARCHITECTURE.md.

Actor-Target Authorization Gate

Raw source: Patterns/Actions/ActorTargetAuthGate.lhs

Pattern intent and mechanism

Separate the actor's policy record from the target resource. Load the actor's own record to compute policy; check ownership against the target resource.

This pattern prevents IDOR-style mistakes: the actor's authority comes from who they are and what they own, never from the target resource's properties.

Use this pattern when:

• a controller action operates on a resource that belongs to a different user,
• the actor's authority depends on their own relationship to the system (their subscription, their role, their membership),
• the target resource is identified by a user-supplied ID that could be swapped.

Critical rule: never derive actor authority from the target resource.

If you derive policy from the target, an attacker changes the target ID and inherits the target's authority. The actor's policy must come from the actor's own context alone.

Role-based decisions that are scoped to a single context (for example, "the actor's role in this project") are orthogonal to ownership. Centralize those role decisions in ScopedRolePermissionRegistry and compose them with the ownership check from this pattern.

Project-specific notes and rollout guidance

Load the actor's own record before the gate call. In IHP, this is typically a database query in the controller action. The gate receives both the actor's own record (for policy) and the target resource (for ownership).

When the actor has no own record (not subscribed, not a member), pass Nothing to the policy computation. The policy then falls back to the default (usually read-only or denied).

Keep the gate call at the top of the controller action, before any writes or side effects.

Supporting snippets

Actor-target gate:

ensureActorCanActOnTarget
    :: (?context :: ControllerContext, ...)
    => User -> Maybe OwnRecord -> TargetRecord -> Action -> IO ()
ensureActorCanActOnTarget user maybeOwnRecord target action =
    let actorCtx = mkActorContext user maybeOwnRecord
        policy = computePolicy actorCtx
        permitted = canDoActionWithOwnership actorCtx target policy action
    in accessDeniedUnless permitted

Controller usage:

action UpdateTargetAction { targetId } = do
    target <- fetch targetId
    currentUser <- getCurrentUser
    ownSubscription <- fetchOwnSubscription currentUser
    ensureActorCanActOnTarget currentUser ownSubscription target UpdateAction
    -- ... proceed with update

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}

module Patterns.Actions.ActorTargetAuthGate where

import Prelude
import IHP.ViewPrelude

-- | Re-export the pure policy vocabulary.
import Patterns.Actions.PurePolicyControllerGate
    ( ActorContext (..)
    , Policy (..)
    , Action (..)
    , canDoAction
    , canDoActionWithOwnership
    , Ownable (..)
    )

Helper implementation examples

-- | Actor-target authorization check (pure, no side effects).
-- | The caller supplies the already-computed policy (from the actor's own record).
-- | The helper checks ownership against the target resource.
-- | Returns True if permitted, False if denied.
actorCanActOnTarget
    :: Ownable target
    => ActorContext ownRole -> Policy -> target -> Action -> Bool
actorCanActOnTarget actorCtx policy target action =
    canDoActionWithOwnership actorCtx target policy action

Usage examples

A task system where the actor's authority comes from their membership in the task's parent project, not from direct ownership of the task.

data Task = Task
    { taskId :: Int
    , taskOwnerId :: Int
    , taskTitle :: Text
    }
    deriving (Eq, Show)

instance Ownable Task where
    ownerId = taskOwnerId

targetTask :: Task
targetTask = Task
    { taskId = 99
    , taskOwnerId = 7
    , taskTitle = "Target"
    }

The actor is a project member. Their FullAccess policy is derived from their membership in the task's parent project, not from owning the task itself.

projectMemberActor :: ActorContext Text
projectMemberActor = ActorContext
    { actorId = 42
    , actorIsAdmin = False
    , actorOwnedRole = Just "Member"
    }

-- | True: project member has FullAccess policy, can update any task.
memberCanUpdate :: Bool
memberCanUpdate = actorCanActOnTarget projectMemberActor FullAccess targetTask UpdateAction

The actor has no project role and cannot act on others' tasks.

outsiderActor :: ActorContext Text
outsiderActor = ActorContext
    { actorId = 99
    , actorIsAdmin = False
    , actorOwnedRole = Nothing
    }

-- | False: outsider gets ReadOnly policy, cannot update.
outsiderCannotUpdate :: Bool
outsiderCannotUpdate = actorCanActOnTarget outsiderActor ReadOnly targetTask UpdateAction

Standalone checks

The infrastructure and examples above compile as one module under the normal ordng pattern check. No extra scaffolding is required.

Case-Insensitive Account Identity

Raw source: Patterns/Actions/CaseInsensitiveIdentity.lhs

Pattern intent and mechanism

Handle email-based identity with case-insensitive lookup and case-insensitive uniqueness enforcement. This prevents new duplicates while tolerating legacy ones (created before the pattern was applied).

The mechanism:

1. Signup: Reject case-variant duplicates at the boundary using fetchCount with filterWhereCaseInsensitive. Note: this is race-prone under concurrency; a database unique index is required as backstop.
2. Login: Query case-insensitively; expect 0, 1, or N matches.
3. Safety: Use fetchCount first when legacy duplicates may exist; only proceed with single-match logic when count == 1.
4. Production backstop: Database-level case-insensitive unique index required for race-safe uniqueness; apply after deduplicating legacy data.

Project-specific notes and rollout guidance

Schema assumptions. This pattern assumes an email :: Text field on the user table. Case-insensitive lookup relies on database collation or explicit lower-casing in the query.

IHP specific. Use filterWhereCaseInsensitive for queries; for uniqueness validation use validateFieldIO with a custom IO validator.

Race safety. The fetchCount check at application level prevents duplicates in normal request flow but is not atomic. Under concurrent requests, two signups with the same case-variant email can both pass the count check before either inserts. The database unique index is the required backstop; it will reject the second insert with a constraint violation. Handle this exception in the controller (generic failure or retry) to prevent leakage of the duplicate existence.

Legacy handling. If duplicates exist:

• Signup rejects new variants (best effort without DB constraint; guaranteed once case-insensitive unique index is active).
• Login uses fetchCount to detect ambiguity and can fail safely or use oldest-match strategy rather than crashing.

Rollback safety. Adding case-insensitive unique index on existing data with duplicates will fail; deduplicate first or use partial index (WHERE created_at > migration_date).

Supporting snippets

Signup uniqueness check:

isEmailUniqueCaseInsensitive :: (?modelContext :: ModelContext) => Text -> IO ValidatorResult
isEmailUniqueCaseInsensitive email = do
    count <- query @User
        |> filterWhereCaseInsensitive (#email, email)
        |> fetchCount
    pure $ if count > 0
        then Failure "This email address is already in use"
        else Success

Edit uniqueness check (excludes current user):

-- | For edit actions: exclude the current user so keeping one's own email
-- does not falsely trigger a collision.
isEmailUniqueCaseInsensitiveExcludingUser
    :: (?modelContext :: ModelContext)
    => Id User -> Text -> IO ValidatorResult
isEmailUniqueCaseInsensitiveExcludingUser currentUserId email = do
    count <- query @User
        |> filterWhereCaseInsensitive (#email, email)
        |> filterWhereNot (#id, currentUserId)
        |> fetchCount
    pure $ if count > 0
        then Failure "This email address is already in use"
        else Success

Login lookup with safety:

-- | Safe login lookup when legacy duplicates may exist.
-- Returns Nothing for 0 matches, Just user for exactly 1, or handles
-- ambiguity (e.g., fail or use oldest) for N > 1.
findUserForLogin :: (?modelContext :: ModelContext) => Text -> IO (Maybe User)
findUserForLogin email = do
    count <- query @User
        |> filterWhereCaseInsensitive (#email, email)
        |> fetchCount
    case count of
        0 -> pure Nothing
        1 -> query @User
            |> filterWhereCaseInsensitive (#email, email)
            |> fetchOneOrNothing
        _ -> do
            -- Ambiguity: multiple users with case-variant emails.
            -- Options: fail, use oldest created, or require exact match.
            -- Use static marker only; do not log user-controlled input (email).
            Log.warn ("Login ambiguity: case-variant collision detected" :: Text)
            pure Nothing  -- or implement disambiguation strategy

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}
module Patterns.Actions.CaseInsensitiveIdentity where

import Prelude
import Data.Text (Text)
import Data.Time.Clock (UTCTime)

-- | Result type for uniqueness validation.
data ValidatorResult = Success | Failure Text

-- | Stub for logging.
warn :: Text -> IO ()
warn _ = pure ()

-- | Safe user lookup with ambiguity handling.
-- Demonstrates the fetchCount-first pattern for legacy safety.
findUserForLogin
    :: Text          -- ^ Email from login form
    -> (Text -> IO Int)   -- ^ Count function (inject for testing)
    -> (Text -> IO (Maybe User))  -- ^ Fetch-one function
    -> IO (Maybe User)
findUserForLogin email countFn fetchFn = do
    n <- countFn email
    case n of
        0 -> pure Nothing
        1 -> fetchFn email
        _ -> do
            warn "Login ambiguity: multiple users for case-variant email"
            pure Nothing  -- Conservative: treat as not found

Helper implementation examples

-- Example User type for compilation.
data User = User
    { userId :: Int
    , userEmail :: Text
    , createdAt :: UTCTime
    }

-- Example validation integration.
validateEmailUniqueness
    :: (Text -> IO Int)   -- ^ Case-insensitive count
    -> Text
    -> IO ValidatorResult
validateEmailUniqueness countFn email = do
    n <- countFn email
    pure $ if n > 0
        then Failure "This email address is already in use"
        else Success

Usage examples

Signup controller integration (IHP):

action CreateUserAction = do
    let user = newRecord @User
    user
        |> fill @'["email", "password"]
        -- Format check first (fast, no DB round-trip), then uniqueness
        |> validateField #email isEmail
        |> validateFieldIO #email isEmailUniqueCaseInsensitive
        |> validateField #password isNonEmpty
        >>= ifValid \case
            Left user -> render NewView { user }
            Right user -> do
                hashed <- hashPassword (get #password user)
                user <- user
                    |> set #passwordHash hashed
                    |> createRecord
                redirectTo UsersAction

Edit controller integration (IHP):

action UpdateUserAction { userId } = do
    -- State-changing action: enforce POST-only
    when (requestMethod request /= "POST") do
        redirectTo EditUserAction { userId }
    user <- fetch userId
    user
        |> fill @'["email"]
        |> validateField #email isEmail
        |> validateFieldIO #email (isEmailUniqueCaseInsensitiveExcludingUser userId)
        >>= ifValid \case
            Left user -> render EditView { user }
            Right user -> do
                user <- updateRecord user
                redirectTo UsersAction

Login controller integration (IHP) with legacy-safe lookup:

action CreateSessionAction = do
    -- POST-only guard (state-changing action)
    when (requestMethod request /= "POST") do
        redirectTo NewSessionAction

    email <- param @Text "email"
    password <- param @Text "password"

    -- Safe lookup: handles 0, 1, or N matches
    mUser <- findUserForLogin email

    case mUser of
        Nothing -> do
            Log.info ("Login failed: no unique user found" :: Text)
            genericLoginFailure
        Just user -> do
            if verifyPassword user password
                then login user
                else do
                    Log.info ("Login failed: wrong password" :: Text)
                    genericLoginFailure

Database migration (PostgreSQL) — safe case-insensitive unique index:

Use a DO block that pre-checks for duplicates and fails with a clear error message instead of an opaque constraint failure:

DO $$
DECLARE
    duplicate_emails TEXT;
BEGIN
    -- Pre-check: find duplicates (case-insensitive)
    SELECT string_agg(DISTINCT LOWER(email), ', ')
    INTO duplicate_emails
    FROM users
    GROUP BY LOWER(email)
    HAVING count(*) > 1;

    IF duplicate_emails IS NOT NULL THEN
        RAISE EXCEPTION 'Migration blocked: duplicate emails exist: %',
            duplicate_emails;
    END IF;

    -- Safe to create index
    CREATE UNIQUE INDEX idx_users_email_lower ON users (LOWER(email));
END $$;

Alternative simple form (fails with constraint error if duplicates exist):

-- Required: guarantees uniqueness under concurrent signups.
-- Only safe to create if no duplicates exist; deduplicate first if needed.
CREATE UNIQUE INDEX idx_users_email_lower ON users(LOWER(email));

-- Alternative: functional unique index with COALESCE for NULL safety
CREATE UNIQUE INDEX idx_users_email_lower
    ON users(COALESCE(LOWER(email), ''));

Standalone checks

GHC type-check (no runtime):

direnv exec . ghci -v0 -ignore-dot-ghci -fno-code \
  Patterns/Actions/CaseInsensitiveIdentity.lhs

Expected: clean type-check, no warnings.

Custom Session Lockout

Raw source: Patterns/Actions/CustomSessionLockout.lhs

Pattern intent and mechanism

IHP provides standard lockout when using the built-in auth schema and controller configuration. Custom login actions must enforce equivalent behavior themselves.

This pattern adds failed-attempt tracking and time-based lockout to a custom session controller. The mechanism:

1. Check lockout status before password verification.
2. Return generic failure responses for all error cases (unknown email, wrong password, locked account) to prevent enumeration.
3. Increment failed attempts via atomic SQL update to avoid races on concurrent login attempts.
4. Set lockedAt timestamp when threshold reached.
5. Reset failed attempts and lock after successful login (see note on concurrent increments in usage example).

Project-specific notes and rollout guidance

Schema fields. Add to your users table (or equivalent):

failed_login_attempts INT DEFAULT 0,
locked_at TIMESTAMP NULL

Integration points:

• Call isUserLockedOut early in CreateSessionAction, before password verify.
• Call recordFailedLogin after failed login for known users (wrong password).
• For unknown emails, use a global or email-based throttle (optional but recommended; per-user counter unavailable).
• Call resetLoginAttempts after successful login.
• Keep failure messages generic; log specifics server-side only.

Unlock strategies. This pattern implements time-based auto-unlock (lockoutDurationMinutes). Administrators can manually clear locked_at and failed_login_attempts via admin interface or database if needed.

Supporting snippets

Configuration:

maxFailedLoginAttempts :: Int
maxFailedLoginAttempts = 5

lockoutDurationMinutes :: NominalDiffTime
lockoutDurationMinutes = 30 * 60  -- 30 minutes

Lockout check (requires lockedAt field on User record):

isUserLockedOut :: User -> UTCTime -> Bool
isUserLockedOut user now =
    case get #lockedAt user of
        Just lockedAt -> diffUTCTime now lockedAt < lockoutDurationMinutes
        Nothing       -> False

Atomic failed-login recording (raw SQL to avoid races):

recordFailedLogin :: (?modelContext :: ModelContext) => Id User -> IO ()
recordFailedLogin userId = do
    now <- getCurrentTime
    sqlExecDiscardResult
        "UPDATE users SET failed_login_attempts = failed_login_attempts + 1, \
\        locked_at = CASE WHEN failed_login_attempts + 1 >= ? THEN ? ELSE locked_at END \
\        WHERE id = ?"
        (maxFailedLoginAttempts, now, userId)

Note: Some implementations pass User instead of Id User and extract the ID inside; either shape works, but the pattern uses explicit Id User for clarity.

Reset after successful login:

resetLoginAttempts :: (?modelContext :: ModelContext) => Id User -> IO ()
resetLoginAttempts userId =
    sqlExecDiscardResult
        "UPDATE users SET failed_login_attempts = 0, locked_at = NULL WHERE id = ?"
        (Only userId)

Note: Some implementations return the updated User record; this pattern shows IO () for simplicity. Adjust to IO User if you need the refreshed record.

Generic failure response (prevents enumeration; must halt control flow):

genericLoginFailure :: (?context :: ControllerContext) => IO ()
genericLoginFailure = do
    setErrorMessage "Invalid credentials."
    redirectTo NewSessionAction  -- redirect halts this action

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}
module Patterns.Actions.CustomSessionLockout where

import Prelude
import Data.Time.Clock (NominalDiffTime, UTCTime, diffUTCTime)

-- | Configuration: lock after this many failed attempts.
maxFailedLoginAttempts :: Int
maxFailedLoginAttempts = 5

-- | Configuration: lockout window in seconds (here: 30 minutes).
lockoutDurationMinutes :: NominalDiffTime
lockoutDurationMinutes = 30 * 60

-- | Check if a user is currently locked out.
-- Requires a record with a `lockedAt :: Maybe UTCTime` field.
isUserLockedOut
    :: (HasLockedAt user)  -- ^ Constraint for field access
    => user
    -> UTCTime             -- ^ Current time
    -> Bool
isUserLockedOut user now =
    case lockedAtField user of
        Just lockedAt -> diffUTCTime now lockedAt < lockoutDurationMinutes
        Nothing       -> False

-- Minimal type class for demonstration (IHP provides actual field accessors).
class HasLockedAt a where
    lockedAtField :: a -> Maybe UTCTime

Helper implementation examples

-- Example User type with HasLockedAt instance for compilation.
data User = User
    { userId :: Int
    , lockedAt :: Maybe UTCTime
    }

instance HasLockedAt User where
    lockedAtField = lockedAt

-- Example: check lockout for a user.
exampleCheck :: User -> UTCTime -> String
exampleCheck user now =
    if isUserLockedOut user now
        then "Account locked"
        else "Account active"

Usage examples

Schema migration (PostgreSQL):

ALTER TABLE users ADD COLUMN IF NOT EXISTS failed_login_attempts INT DEFAULT 0;
ALTER TABLE users ADD COLUMN IF NOT EXISTS locked_at TIMESTAMP NULL;

-- Optional: index for admin queries on locked users
CREATE INDEX idx_users_locked_at ON users(locked_at) WHERE locked_at IS NOT NULL;

Controller integration (IHP) — preferred single-case structure:

action CreateSessionAction = do
    -- State-changing action: enforce POST-only before any reads or mutations.
    when (requestMethod request /= "POST") do
        redirectTo NewSessionAction

    email <- param @Text "email"
    password <- param @Text "password"

    user <- query @User
        |> filterWhereCaseInsensitive (#email, email)
        |> fetchOneOrNothing

    now <- getCurrentTime

    -- Single case: handle all branches without risk of falling through
    case (user, password) of
        (Nothing, _) -> do
            -- Unknown email: log internally, return generic failure.
            -- Optional but recommended: global/email-based throttle here.
            Log.info ("Login failed: user not found" :: Text)
            genericLoginFailure
        (Just u, _) | isUserLockedOut u now -> do
            Log.info ("Login rejected: account locked" :: Text)
            genericLoginFailure
        (Just u, pwd) | verifyPassword u pwd -> do
            -- Re-fetch to observe any concurrent lockout set during verify
            u' <- fetch (get #id u)
            now' <- getCurrentTime
            if isUserLockedOut u' now'
                then do
                    Log.info ("Login rejected: account locked (race)" :: Text)
                    genericLoginFailure
                else do
                    -- Warning: concurrent failed-login increments between
                    -- verify and reset are lost. Use conditional UPDATE for
                    -- strict accounting (only reset if locked_at IS NULL).
                    _ <- resetLoginAttempts (get #id u')
                    login u'
        (Just u, _) -> do
            _ <- recordFailedLogin (get #id u)
            Log.info ("Login failed: wrong password" :: Text)
            genericLoginFailure

Note: genericLoginFailure must halt control flow (via redirectTo or respondHtml). All branches end in this helper; no fall-through possible.

Alternative two-case structure (early check + later handling) exists but requires careful control-flow management to prevent execution continuing past the early locked branch.

Standalone checks

GHC type-check (no runtime):

direnv exec . ghci -v0 -ignore-dot-ghci -fno-code \
  Patterns/Actions/CustomSessionLockout.lhs

Expected: clean type-check, no warnings.

Expiring User Token Flow

Raw source: Patterns/Actions/ExpiringUserTokenFlow.lhs

Pattern intent and mechanism

Password reset, email confirmation, account recovery, and invite acceptance share the same lifecycle:

1. Generate a random token.
2. Store token state with a timestamp.
3. Deliver the token out-of-band (usually by email).
4. Verify token and expiry when the user presents it.
5. Perform the guarded operation.
6. Invalidate the token immediately after success.

A recovery token is not a password, not a session, and not a permission. It is a short-lived proof delivered out-of-band and consumed exactly once. Treating it like any of those three things is a category error that leads to predictable security mistakes.

The pattern identity in host code is the named token type and the lifecycle order enforced in controller actions. Each step is visible and grepable; skipping a step (for example, forgetting to invalidate after success) should stand out in review.

Use this pattern when:

• a user must prove control of an email address or account without being logged in,
• the proof must expire and become unusable after a short time,
• the operation guarded by the token is state-changing and must happen at most once per token.

Project-specific notes and rollout guidance

Storage schema.

Choose one schema and do not carry both a separate token table and user-record fields forward. The IHP Authentication Guide stores password_reset_token :: Maybe Text and password_reset_token_created_at :: Maybe UTCTime directly on the users record. This is the guide-close default. A separate table is acceptable only if it is a deliberate design with valid foreign keys, atomic invalidation, and no competing migrations.

Token comparison.

Compare the raw token after fetching the user by userId. The link carries userId plus raw token; the handler fetches the user by userId, then compares the stored token and checks expiry.

Do not use hashPassword for token lookup or storage comparison. hashPassword is salted and non-deterministic. A second hash of the same token will not match the stored hash. If raw token storage is unacceptable, use a deterministic digest or HMAC, not hashPassword.

Verification happens twice.

Re-check token and expiry in both the edit action (renders the form) and the update action (accepts the new password). A user might leave the form open past expiry, or an attacker might replay a consumed token. Both checks must reject invalid or expired tokens.

Generic responses.

The reset-request action must return the same response for unknown email addresses and known ones. Do not disclose whether an account exists. Log internally for debugging, but keep the user-facing message generic.

POST-only state changes.

The reset request and the password update are POST actions. The link click that renders the reset form is GET and read-only. This aligns with IHP's SameSite=Lax CSRF model.

Invalidate after success.

After hashing the new password and updating the record, clear the token and timestamp fields. A token that survives a successful reset is a replay hazard.

Passwords are POST body fields.

Read the new password and confirmation with param @Text inside the update action. Do not put them into action constructors or generated URLs.

Supporting snippets

IHP route shape for reset flow:

data SessionsController
    = ...
    | ForgotPasswordAction          -- ^ Show request form
    | RetrievePasswordAction        -- ^ POST: generate token, send mail
    | ResetPasswordAction
        { userId :: !(Id User)
        , token  :: !Text
        }                           -- ^ GET: show new-password form
    | UpdatePasswordAction
        { userId :: !(Id User)
        , token  :: !Text
        }                           -- ^ POST: validate token, update password

Opaque token newtype at the boundary:

newtype PasswordResetToken = PasswordResetToken
    { unwrapPasswordResetToken :: Text }
    deriving (Eq)

Explicit export list with a boundary smart constructor:

module Web.Types
    ( PasswordResetToken
    , mkPasswordResetToken   -- controllers wrap raw route text here
    , unwrapPasswordResetToken
    -- raw constructor NOT exported
    ) where

-- | Wrap raw text from the route or URL into the token type.
-- Controllers at the route boundary use this; do not construct
-- tokens from arbitrary text in other contexts.
mkPasswordResetToken :: Text -> PasswordResetToken
mkPasswordResetToken = PasswordResetToken

Request action (POST-only, generic response):

action RetrievePasswordAction = do
    unless (requestMethod request == "POST") do
        redirectTo NewSessionAction

    case paramOrNothing @Text "email" of
        Nothing -> pure ()  -- generic response below
        Just email -> do
            user <- query @User
                |> filterWhereCaseInsensitive (#email, email)
                |> fetchOneOrNothing
            case user of
                Nothing -> pure ()  -- generic response below
                Just u  -> do
                    rawToken <- generateAuthenticationToken
                    now      <- getCurrentTime
                    userWithToken <- u
                        |> set #passwordResetToken (Just rawToken)
                        |> set #passwordResetTokenCreatedAt (Just now)
                        |> updateRecord
                    mailResult <- try @SomeException (sendMail (ResetPasswordMail
                        { user = userWithToken
                        , token = mkPasswordResetToken rawToken
                        }))
                    case mailResult of
                        Right () -> pure ()
                        Left _e  -> do
                            -- Mail delivery failed: clear the token so the
                            -- user cannot reach a broken reset form.
                            -- Log internally for operations; keep the user-
                            -- facing response generic to avoid enumeration.
                            Log.error ("Password reset mail failed: " <> tshow _e)
                            _ <- clearPasswordResetToken userWithToken
                            pure ()

    -- Same message whether the email exists or not.
    setSuccessMessage iPasswordResetRequestReceived
    redirectTo ForgotPasswordAction

Edit action (verify before rendering form):

action ResetPasswordAction { userId, token } = do
    maybeUser <- query @User
        |> filterWhere (#id, userId)
        |> fetchOneOrNothing
    case maybeUser of
        Nothing -> redirectWithError
        Just user -> do
            now <- getCurrentTime
            let resetToken = mkPasswordResetToken token
            if passwordResetTokenIsValid user resetToken now
                then render ResetPasswordView { userId, token = resetToken }
                else redirectWithError

Update action (verify again, then hash, then invalidate):

action UpdatePasswordAction { userId, token } = do
    when (requestMethod request /= "POST") do
        redirectTo NewSessionAction

    maybeUser <- query @User
        |> filterWhere (#id, userId)
        |> fetchOneOrNothing
    case maybeUser of
        Nothing -> redirectWithError
        Just user -> do
            now <- getCurrentTime
            let resetToken = mkPasswordResetToken token
            unless (passwordResetTokenIsValid user resetToken now) do
                redirectWithError

            let password     = param @Text "password"
            let confirmation = param @Text "passwordConfirmation"
            unless (password == confirmation) do
                setErrorMessage "Passwords do not match."
                redirectTo ResetPasswordAction { userId, token }

            hashed <- hashPassword password
            _ <- user
                |> set #passwordHash hashed
                |> set #passwordResetToken Nothing
                |> set #passwordResetTokenCreatedAt Nothing
                |> updateRecord

            setSuccessMessage "Password updated."
            redirectTo NewSessionAction

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}

module Patterns.Actions.ExpiringUserTokenFlow where

import Prelude
import Data.Text (Text)
import Data.Time.Clock
    ( UTCTime (..)
    , NominalDiffTime
    , diffUTCTime
    )
import Data.Time (fromGregorian)

-- | A boundary-wrapped token delivered out-of-band. The raw value only
-- exists at the route boundary; controllers wrap it immediately.
-- In application code, do not export the constructor; keep construction
-- inside the module that owns the route parser.
newtype ResetToken = ResetToken { unwrapResetToken :: Text }
    deriving (Eq)

-- | Generic account record with token lifecycle fields.
-- In IHP this is the generated database record.
data Account = Account
    { accountId :: Int
    , email :: Text
    , passwordHash :: Text
    , resetToken :: Maybe Text
    , resetTokenCreatedAt :: Maybe UTCTime
    }
    deriving (Eq)

Helper implementation examples

Maximum token age and validation logic.

-- | Tokens expire after this many seconds.
tokenMaxAge :: NominalDiffTime
tokenMaxAge = 3600  -- 1 hour

-- | Check whether a presented token matches the stored token and has
-- not expired. Returns 'False' when no token is stored.
tokenIsValid :: Account -> ResetToken -> UTCTime -> Bool
tokenIsValid account (ResetToken presented) now =
    case (resetToken account, resetTokenCreatedAt account) of
        (Just stored, Just createdAt) ->
            let age = diffUTCTime now createdAt
            in stored == presented && age >= 0 && age < tokenMaxAge
        _ -> False

Token invalidation after successful use.

-- | Clear the reset token and timestamp so the token cannot be reused.
-- Call this immediately after the guarded operation succeeds.
clearResetToken :: Account -> Account
clearResetToken account = account
    { resetToken = Nothing
    , resetTokenCreatedAt = Nothing
    }

Simulated password hashing for the compilable example.

-- | Simulated password hash. In IHP this is 'hashPassword' from
-- 'IHP.AuthSupport.Authentication'.
hashPassword :: Text -> Text
hashPassword pw = "hashed:" <> pw

Usage examples

A concrete token and account for demonstration.

-- | Example account with an active reset token.
exampleAccount :: Account
exampleAccount = Account
    { accountId = 1
    , email = "ada@example.com"
    , passwordHash = "oldhash"
    , resetToken = Just "abc123"
    , resetTokenCreatedAt = Just exampleTokenTime
    }

-- | A token that matches the stored value.
exampleValidToken :: ResetToken
exampleValidToken = ResetToken "abc123"

-- | A token that does not match.
exampleInvalidToken :: ResetToken
exampleInvalidToken = ResetToken "wrong"

-- | Fixed point in time for the example checks.
exampleNow :: UTCTime
exampleNow = UTCTime (fromGregorian 2024 1 1) 0

-- | The token was created five minutes before 'exampleNow'.
exampleTokenTime :: UTCTime
exampleTokenTime = UTCTime (fromGregorian 2024 1 1) (-300)

Token validation checks.

-- | True: the token matches and is within the expiry window.
validTokenCheck :: Bool
validTokenCheck = tokenIsValid exampleAccount exampleValidToken exampleNow

-- | False: the token value does not match.
invalidTokenCheck :: Bool
invalidTokenCheck = tokenIsValid exampleAccount exampleInvalidToken exampleNow

Password update with hash-and-invalidate.

-- | Simulated successful reset: hash the new password and clear the token.
examplePasswordUpdate :: Account -> Text -> Account
examplePasswordUpdate account newPassword =
    let hashed = hashPassword newPassword
    in (clearResetToken account) { passwordHash = hashed }

-- | The account after a successful reset. Token is gone; password is hashed.
resetAccount :: Account
resetAccount = examplePasswordUpdate exampleAccount "newsecret"

-- | True: the token was cleared after use.
tokenIsCleared :: Bool
tokenIsCleared = resetToken resetAccount == Nothing

-- | True: the new password was hashed.
passwordWasHashed :: Bool
passwordWasHashed = passwordHash resetAccount == hashPassword "newsecret"

Standalone checks

The infrastructure and examples above compile as one module under the normal ordng pattern check. The Account record and hashPassword simulation are stand-ins for IHP's generated record and framework hashing; the lifecycle order — generate, store, verify, consume, invalidate — is the invariant that survives across frameworks.

External Provider Endpoint Gate

Raw source: Patterns/Actions/ExternalProviderEndpointGate.lhs

Pattern intent and mechanism

Gate controller endpoints that can spend external provider resources before any provider operation is attempted. A route that triggers provider auth, quota, latency, or cost is not an ordinary read-only component route, even when it does not mutate the local database.

The gate is a request-boundary/resource guard:

1. check the HTTP method first,
2. check whether an actor is required and present,
3. check CSRF, same-origin, or equivalent request-forgery protection for browser-submitted requests,
4. fail with an explicit response before token, auth, search, or fetch calls,
5. continue only when the endpoint is allowed to spend provider resources.

This is not a domain permission pattern. It answers whether this request may use the application as a proxy to an external provider. Domain role questions such as who may import, persist, or edit provider-derived data belong to a later application action.

Use this pattern when:

• a public route can trigger provider auth or search,
• an anonymous caller could spend provider quota or request time,
• a read-like HTMX endpoint has provider side effects outside the local app,
• a controller action should fail before constructing provider requests.

Search aliases: endpoint hardening, abuse protection, quota protection, POST-only, login required, CSRF, same-origin.

Project-specific notes and rollout guidance

Call the gate at the top of the controller action. No token lookup, provider search, database write, or expensive local work should happen before it.

Prefer POST for HTMX endpoints that trigger provider work, even when the local action is read-like. The method is a resource-use boundary here, not merely a local database mutation signal. POST is not sufficient on its own: browser requests must also pass the framework's CSRF, same-origin, or equivalent request-forgery protection before provider resources are spent.

Keep actor presence separate from domain authorization. A logged-in-only gate can prevent anonymous quota abuse without saying that the actor may import, modify, or own the provider result. It also does not replace request-forgery protection: a logged-in browser can still be induced to send a POST unless the framework or the endpoint rejects forged requests.

In IHP, a helper that calls respondAndExit needs the implicit ?respond :: Respond constraint. If you give the helper an explicit signature, include it:

ensureExternalProviderAutocompleteAllowed
    :: ( ?context :: ControllerContext
       , ?request :: Wai.Request
       , ?respond :: Respond
       )
    => IO ()

A tiny local helper can also omit the explicit signature during exploration, but canonical application code should make the boundary grepable once it settles.

Supporting snippets

IHP controller shape:

action AutocompleteExternalProviderComponentAction = do
    ensureExternalProviderAutocompleteAllowed
    frozenContext <- freeze ?context
    let ?context = frozenContext in renderExternalProviderComponent (param "query")

IHP gate shape:

ensureExternalProviderAutocompleteAllowed
    :: ( ?context :: ControllerContext
       , ?request :: Wai.Request
       , ?respond :: Respond
       )
    => IO ()
ensureExternalProviderAutocompleteAllowed = do
    unless (Wai.requestMethod request == "POST") do
        respondAndExit
            (responseLBS status405
                [("Allow", "POST"), ("Content-Type", "text/plain; charset=utf-8")]
                "Method Not Allowed")
    case currentUserOrNothing of
        Just _ -> pure ()
        Nothing -> respondAndExit
            (responseLBS status401
                [("Content-Type", "text/plain; charset=utf-8")]
                "Login required")
    -- Verify the framework CSRF/same-origin boundary here when it is not
    -- guaranteed before the action runs. The provider call below must only run
    -- after that request-forgery boundary has accepted the request.

The provider call belongs after the gate:

searchExternalProviderComponent query = do
    result <- liftIO (searchExternalProvider query)
    respondHtml (renderExternalProviderResult result)

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}

module Patterns.Actions.ExternalProviderEndpointGate where

import Prelude
import Data.ByteString (ByteString)

-- | Configuration for an endpoint that can spend external provider resources.
data ExternalProviderEndpointGate = ExternalProviderEndpointGate
    { externalProviderAllowedMethod :: ByteString
    , externalProviderActorRequirement :: ExternalProviderActorRequirement
    , externalProviderRequestForgeryRequirement :: ExternalProviderRequestForgeryRequirement
    , externalProviderMethodNotAllowedBody :: ByteString
    , externalProviderLoginRequiredBody :: ByteString
    , externalProviderRequestRejectedBody :: ByteString
    }
    deriving (Show, Eq)

-- | Whether the endpoint may be used anonymously or requires an actor.
data ExternalProviderActorRequirement
    = ExternalProviderPublicEndpoint
    | ExternalProviderRequiresActor
    deriving (Show, Eq)

-- | Whether request-forgery protection must have accepted the request.
data ExternalProviderRequestForgeryRequirement
    = ExternalProviderRequestForgeryNotRequired
    | ExternalProviderRequiresRequestForgeryProtection
    deriving (Show, Eq)

-- | Result of the framework's CSRF, same-origin, or equivalent boundary.
data ExternalProviderRequestForgeryState
    = ExternalProviderRequestForgeryAccepted
    | ExternalProviderRequestForgeryRejected
    deriving (Show, Eq)

-- | Minimal request shape needed by the reusable gate decision.
data ExternalProviderRequest = ExternalProviderRequest
    { externalProviderRequestMethod :: ByteString
    , externalProviderRequestForgeryState :: ExternalProviderRequestForgeryState
    }
    deriving (Show, Eq)

-- | Gate failure before any provider operation is attempted.
data ExternalProviderGateFailure
    = ExternalProviderMethodNotAllowed ByteString ByteString
    | ExternalProviderLoginRequired ByteString
    | ExternalProviderRequestRejected ByteString
    deriving (Show, Eq)

The gate decision is pure. Framework-specific controller code maps failures to respondAndExit, redirects, JSON, CLI output, or another boundary response.

checkExternalProviderEndpointGate
    :: ExternalProviderEndpointGate
    -> ExternalProviderRequest
    -> Maybe actor
    -> Either ExternalProviderGateFailure ()
checkExternalProviderEndpointGate
        ExternalProviderEndpointGate
            { externalProviderAllowedMethod = allowedMethod
            , externalProviderActorRequirement = actorRequirement
            , externalProviderRequestForgeryRequirement = requestForgeryRequirement
            , externalProviderMethodNotAllowedBody = methodNotAllowedBody
            , externalProviderLoginRequiredBody = loginRequiredBody
            , externalProviderRequestRejectedBody = requestRejectedBody
            }
        ExternalProviderRequest
            { externalProviderRequestMethod = requestMethod
            , externalProviderRequestForgeryState = requestForgeryState
            }
        maybeActor
    | requestMethod /= allowedMethod =
        Left (ExternalProviderMethodNotAllowed allowedMethod methodNotAllowedBody)
    | actorRequirement == ExternalProviderRequiresActor && actorMissing =
        Left (ExternalProviderLoginRequired loginRequiredBody)
    | requestForgeryRequirement == ExternalProviderRequiresRequestForgeryProtection
        && requestForgeryState == ExternalProviderRequestForgeryRejected =
        Left (ExternalProviderRequestRejected requestRejectedBody)
    | otherwise = Right ()
  where
    actorMissing = case maybeActor of
        Nothing -> True
        Just _ -> False

Helper implementation examples

A typical external autocomplete gate accepts only POST, requires a logged-in actor, and requires request-forgery protection to have accepted the request.

externalAutocompleteGate :: ExternalProviderEndpointGate
externalAutocompleteGate = ExternalProviderEndpointGate
    { externalProviderAllowedMethod = "POST"
    , externalProviderActorRequirement = ExternalProviderRequiresActor
    , externalProviderRequestForgeryRequirement = ExternalProviderRequiresRequestForgeryProtection
    , externalProviderMethodNotAllowedBody = "Method Not Allowed"
    , externalProviderLoginRequiredBody = "Login required"
    , externalProviderRequestRejectedBody = "Request rejected"
    }

A small response representation keeps the standalone example independent of IHP while preserving HTTP semantics.

data GateResponse = GateResponse
    { gateResponseStatus :: Int
    , gateResponseHeaders :: [(ByteString, ByteString)]
    , gateResponseBody :: ByteString
    }
    deriving (Show, Eq)

renderGateFailure :: ExternalProviderGateFailure -> GateResponse
renderGateFailure (ExternalProviderMethodNotAllowed allowedMethod body) =
    GateResponse
        { gateResponseStatus = 405
        , gateResponseHeaders =
            [ ("Allow", allowedMethod)
            , ("Content-Type", "text/plain; charset=utf-8")
            ]
        , gateResponseBody = body
        }
renderGateFailure (ExternalProviderLoginRequired body) =
    GateResponse
        { gateResponseStatus = 401
        , gateResponseHeaders =
            [("Content-Type", "text/plain; charset=utf-8")]
        , gateResponseBody = body
        }
renderGateFailure (ExternalProviderRequestRejected body) =
    GateResponse
        { gateResponseStatus = 403
        , gateResponseHeaders =
            [("Content-Type", "text/plain; charset=utf-8")]
        , gateResponseBody = body
        }

Usage examples

Wrong methods fail before actor checks and before provider calls.

wrongMethodResponse :: Either GateResponse ()
wrongMethodResponse =
    case checkExternalProviderEndpointGate externalAutocompleteGate getRequest (Just Actor) of
        Left failure -> Left (renderGateFailure failure)
        Right () -> Right ()

Anonymous direct calls fail after the method is accepted.

anonymousPostResponse :: Either GateResponse ()
anonymousPostResponse =
    case checkExternalProviderEndpointGate externalAutocompleteGate postRequest (Nothing :: Maybe Actor) of
        Left failure -> Left (renderGateFailure failure)
        Right () -> Right ()

A logged-in forged POST still fails before provider work.

forgedPostResponse :: Either GateResponse ()
forgedPostResponse =
    case checkExternalProviderEndpointGate externalAutocompleteGate forgedPostRequest (Just Actor) of
        Left failure -> Left (renderGateFailure failure)
        Right () -> Right ()

A logged-in POST whose request-forgery boundary has accepted the request can continue to provider work.

allowedPostResponse :: Either GateResponse ()
allowedPostResponse =
    case checkExternalProviderEndpointGate externalAutocompleteGate postRequest (Just Actor) of
        Left failure -> Left (renderGateFailure failure)
        Right () -> Right ()

Example request and actor values:

data Actor = Actor
    deriving (Show, Eq)

getRequest :: ExternalProviderRequest
getRequest = ExternalProviderRequest
    { externalProviderRequestMethod = "GET"
    , externalProviderRequestForgeryState = ExternalProviderRequestForgeryRejected
    }

forgedPostRequest :: ExternalProviderRequest
forgedPostRequest = ExternalProviderRequest
    { externalProviderRequestMethod = "POST"
    , externalProviderRequestForgeryState = ExternalProviderRequestForgeryRejected
    }

postRequest :: ExternalProviderRequest
postRequest = ExternalProviderRequest
    { externalProviderRequestMethod = "POST"
    , externalProviderRequestForgeryState = ExternalProviderRequestForgeryAccepted
    }

Standalone checks

Not applicable in this pattern; sections 4, 5, and 6 compile standalone.

External Search Query Policy

Raw source: Patterns/Actions/ExternalSearchQueryPolicy.lhs

Pattern intent and mechanism

Normalize user-supplied free-text search before an external provider call. A local autocomplete input may emit empty, whitespace-only, very short, or very long values. Sending those values to a provider wastes request time and quota, and can produce broad low-value searches.

This pattern applies a small query policy at the provider boundary:

1. strip surrounding whitespace,
2. reject blank values and values shorter than the configured minimum,
3. cap values at the configured maximum,
4. call the provider only when a normalized query remains.

A rejected blank or short query is not invalid user input. For autocomplete-style external search it is a successful no-op: the caller should usually return an empty successful result and keep the UI quiet.

Use this pattern when:

• a user-typed free-text query can trigger an external search,
• auth or token retrieval has latency or quota impact,
• short broad searches have low value,
• the provider should not receive oversized query strings.

Search aliases: query normalization, input sanitization, autocomplete, typeahead, min length, max length, empty query.

Do not use this pattern unchanged for exact-ID lookups, URL lookups, barcode lookups, or other provider calls where a short or blank value may be meaningful.

Project-specific notes and rollout guidance

Run query normalization before provider auth, token retrieval, or HTTP search. If auth itself has latency or quota cost, a one-character query should not spend that cost.

Keep the policy generic and provider values local. The reusable helper should know only about minimum and maximum length; the provider module chooses concrete numbers for its provider surface and UI context.

Treat Nothing as a named policy outcome, not vague failure. The function name and policy type make the meaning explicit: no external search should be attempted for this input.

The direct record constructor is fine for static provider constants in trusted source code. If policy values come from configuration, an admin UI, or another runtime source, validate them with a smart constructor before use.

Preserve this boundary when composing with IntegrationResultBoundary: a blank or short query maps to IntegrationSucceeded [], while provider failures map to IntegrationUnavailable ....

Supporting snippets

Provider-local policy constant:

providerSearchQueryPolicy :: ExternalSearchQueryPolicy
providerSearchQueryPolicy = ExternalSearchQueryPolicy
    { externalSearchMinLength = 3
    , externalSearchMaxLength = 200
    }

Provider search shape:

searchExternalProvider rawQuery =
    case normaliseExternalSearchQuery providerSearchQueryPolicy rawQuery of
        Nothing -> pure (IntegrationSucceeded [])
        Just query -> callExternalProvider query

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}

module Patterns.Actions.ExternalSearchQueryPolicy where

import Prelude
import Data.Text (Text)
import qualified Data.Text as T
import Patterns.Actions.IntegrationResultBoundary

-- | Query-shaping policy for external free-text search endpoints.
--
-- Invariants for direct construction:
--
-- - 'externalSearchMinLength' must be >= 1.
-- - 'externalSearchMaxLength' must be >= 'externalSearchMinLength'.
--
-- Use 'mkExternalSearchQueryPolicy' when values come from runtime
-- configuration or other untrusted sources.
data ExternalSearchQueryPolicy = ExternalSearchQueryPolicy
    { externalSearchMinLength :: Int
    , externalSearchMaxLength :: Int
    } deriving (Show, Eq)

The smart constructor rejects impossible policies. Static trusted constants may use the record constructor directly; runtime configuration should use this function.

mkExternalSearchQueryPolicy :: Int -> Int -> Maybe ExternalSearchQueryPolicy
mkExternalSearchQueryPolicy minLength maxLength
    | minLength < 1 = Nothing
    | maxLength < minLength = Nothing
    | otherwise = Just ExternalSearchQueryPolicy
        { externalSearchMinLength = minLength
        , externalSearchMaxLength = maxLength
        }

The normalizer strips whitespace, treats blank and short queries as no-op decisions, and caps long values before they leave the application.

normaliseExternalSearchQuery :: ExternalSearchQueryPolicy -> Text -> Maybe Text
normaliseExternalSearchQuery ExternalSearchQueryPolicy
        { externalSearchMinLength = minLength
        , externalSearchMaxLength = maxLength
        } rawQuery
    | T.null strippedQuery = Nothing
    | T.length strippedQuery < minLength = Nothing
    | otherwise = Just (T.take maxLength strippedQuery)
  where
    strippedQuery = T.strip rawQuery

Helper implementation examples

A provider module supplies concrete values for its own search endpoint.

providerSearchQueryPolicy :: ExternalSearchQueryPolicy
providerSearchQueryPolicy = ExternalSearchQueryPolicy
    { externalSearchMinLength = 3
    , externalSearchMaxLength = 200
    }

Provider search applies normalization before any external operation.

searchProvider :: Text -> IO (IntegrationResult [Text])
searchProvider rawQuery =
    case normaliseExternalSearchQuery providerSearchQueryPolicy rawQuery of
        Nothing -> pure (IntegrationSucceeded [])
        Just query -> callProviderSearch query

The provider call shown here is a placeholder for auth, HTTP, and decode logic. It receives only normalized text.

callProviderSearch :: Text -> IO (IntegrationResult [Text])
callProviderSearch query =
    pure (IntegrationSucceeded ["searched: " <> query])

Usage examples

Short and whitespace-only queries are deliberate no-op searches.

blankQueryResult :: Maybe Text
blankQueryResult = normaliseExternalSearchQuery providerSearchQueryPolicy "   "

shortQueryResult :: Maybe Text
shortQueryResult = normaliseExternalSearchQuery providerSearchQueryPolicy "ab"

Long queries are capped, not rejected.

smallPolicy :: ExternalSearchQueryPolicy
smallPolicy = ExternalSearchQueryPolicy
    { externalSearchMinLength = 1
    , externalSearchMaxLength = 5
    }

cappedQueryResult :: Maybe Text
cappedQueryResult = normaliseExternalSearchQuery smallPolicy "abcdefghi"

Runtime policies should be parsed through the smart constructor.

validRuntimePolicy :: Maybe ExternalSearchQueryPolicy
validRuntimePolicy = mkExternalSearchQueryPolicy 3 200

invalidRuntimePolicy :: Maybe ExternalSearchQueryPolicy
invalidRuntimePolicy = mkExternalSearchQueryPolicy 0 200

invalidRuntimePolicyOrder :: Maybe ExternalSearchQueryPolicy
invalidRuntimePolicyOrder = mkExternalSearchQueryPolicy 10 3

Standalone checks

Not applicable in this pattern; sections 4, 5, and 6 compile standalone.

Integration Result Boundary

Raw source: Patterns/Actions/IntegrationResultBoundary.lhs

Pattern intent and mechanism

External provider calls fail in ways that ordinary in-process helpers do not: credentials may be absent, the provider may be slow, the network may fail, or response decoding may reveal schema drift. A caller still needs to distinguish those operational states from a successful provider response with an empty payload.

This pattern makes that distinction explicit:

• IntegrationSucceeded payload means the provider operation completed. An empty list inside this constructor is a successful no-hit result.
• IntegrationUnavailable reason means the provider was disabled, timed out, or failed operationally. It is not a successful empty result.

The boundary belongs around provider IO: auth requests, HTTP calls, response parsing, or equivalent third-party operations. Do not wrap an entire controller or domain workflow just to turn every exception into an integration result. Cancellation and shutdown exceptions are not provider failures and must be re-thrown.

Use this pattern when:

• an optional external provider enriches a local flow,
• provider absence is acceptable in local development or optional deployments,
• a UI, job, or CLI caller must preserve the fact that the provider failed,
• a slow provider must not hold a request/response handler indefinitely.

Search aliases: error handling, failure handling, timeout, unavailable provider, empty result vs failed request.

Project-specific notes and rollout guidance

Introduce this result type at the provider helper boundary. Controllers, components, jobs, and scripts should consume IntegrationResult; raw HTTP, auth, and decode exceptions should not leak past the provider module as ordinary empty payloads.

Map disabled providers deliberately. Local development may render nothing for a missing optional provider, but that choice belongs at the presentation boundary; the provider helper still returns IntegrationUnavailable (IntegrationDisabled provider).

Map runtime failures visibly enough for the current surface. A UI may show a small unavailable block, a job may log and continue, and a CLI may exit with a non-zero status. In every case the failure fact remains available. Do not render raw exception text directly to end users; use details for logs or diagnostic channels.

Use the timeout wrapper for provider operations made during request/response UI flows. Pick a conservative provider-specific budget and tune it from production evidence.

If the provider performs query shaping before auth or HTTP, return IntegrationSucceeded [] for a deliberate no-op search. That is a successful policy decision, not provider unavailability.

Supporting snippets

Controller or component response mapping:

case tracksResult of
    IntegrationSucceeded [] -> respondHtml mempty
    IntegrationSucceeded tracks -> respondHtml (renderTracks tracks)
    IntegrationUnavailable (IntegrationDisabled _) -> respondHtml mempty
    IntegrationUnavailable err -> respondHtml (renderProviderUnavailable err)

Provider helper boundary:

searchProvider rawQuery =
    case normaliseExternalSearchQuery providerQueryPolicy rawQuery of
        Nothing -> pure (IntegrationSucceeded [])
        Just query -> integrationTryWithTimeout providerName providerTimeout do
            token <- fetchProviderToken
            response <- fetchProviderSearchResults token query
            decodeProviderResults response

Core reusable pattern infrastructure

{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ScopedTypeVariables #-}

module Patterns.Actions.IntegrationResultBoundary where

import Prelude
import Control.Exception
    ( SomeAsyncException
    , SomeException
    , displayException
    , fromException
    , throwIO
    , try
    )
import Data.Text (Text)
import qualified Data.Text as T
import System.Timeout (timeout)

-- | Operational failure of an external integration.
--
-- 'IntegrationDisabled' is configuration-driven and often acceptable in local
-- development. 'IntegrationTimedOut' prevents a slow provider from tying up a
-- request handler indefinitely. 'IntegrationFailed' means the provider was
-- configured but a request, response decode, or other operational step failed.
data IntegrationError
    = IntegrationDisabled Text
    | IntegrationTimedOut Text Int
    | IntegrationFailed Text Text
    deriving (Show, Eq)

-- | Result of an external integration call.
--
-- Empty successful payloads stay inside 'IntegrationSucceeded'. Operational
-- failures use 'IntegrationUnavailable' and must not be collapsed into empty
-- payloads.
data IntegrationResult a
    = IntegrationSucceeded a
    | IntegrationUnavailable IntegrationError
    deriving (Show, Eq)

The plain wrapper catches synchronous exceptions at the provider boundary and preserves the provider name with a diagnostic message. Asynchronous exceptions such as cancellation and shutdown are re-thrown.

integrationTry :: Text -> IO a -> IO (IntegrationResult a)
integrationTry provider action = do
    result <- try action
    case result of
        Right value -> pure (IntegrationSucceeded value)
        Left (exception :: SomeException) -> integrationException provider exception

The timeout wrapper adds a provider-specific request budget and keeps timeout as a distinct failure constructor.

integrationTryWithTimeout :: Text -> Int -> IO a -> IO (IntegrationResult a)
integrationTryWithTimeout provider timeoutMicros action = do
    result <- try (timeout timeoutMicros action)
    case result of
        Right (Just value) -> pure (IntegrationSucceeded value)
        Right Nothing -> pure (IntegrationUnavailable (IntegrationTimedOut provider timeoutMicros))
        Left (exception :: SomeException) -> integrationException provider exception

integrationException :: Text -> SomeException -> IO (IntegrationResult a)
integrationException provider exception
    | Just (_ :: SomeAsyncException) <- fromException exception = throwIO exception
    | otherwise = pure (IntegrationUnavailable failure)
  where
    failure = IntegrationFailed provider (T.pack (displayException exception))

Helper implementation examples

A provider may be disabled by configuration before any HTTP request is built. Fully absent optional credentials are disabled; partial configuration is a visible failure.

loadProviderCredentials :: Maybe Text -> Maybe Text -> IntegrationResult (Text, Text)
loadProviderCredentials Nothing Nothing =
    IntegrationUnavailable (IntegrationDisabled "ExampleProvider")
loadProviderCredentials (Just clientId) (Just clientSecret) =
    IntegrationSucceeded (clientId, clientSecret)
loadProviderCredentials _ _ =
    IntegrationUnavailable (IntegrationFailed "ExampleProvider" "partial credentials")

A provider search returns a successful empty payload for deliberate no-op queries and wraps only the external operation.

searchExampleProvider :: Text -> IO (IntegrationResult [Text])
searchExampleProvider rawQuery
    | T.length (T.strip rawQuery) < 3 = pure (IntegrationSucceeded [])
    | otherwise = integrationTryWithTimeout "ExampleProvider" 5000000 do
        pure ["external result"]

Usage examples

Presentation code distinguishes empty success from provider unavailability.

renderSearchOutcome :: IntegrationResult [Text] -> Text
renderSearchOutcome (IntegrationSucceeded []) =
    "no provider results"
renderSearchOutcome (IntegrationSucceeded results) =
    "provider results: " <> T.intercalate ", " results
renderSearchOutcome (IntegrationUnavailable (IntegrationDisabled _provider)) =
    ""
renderSearchOutcome (IntegrationUnavailable (IntegrationTimedOut provider _timeoutMicros)) =
    "provider timed out: " <> provider
renderSearchOutcome (IntegrationUnavailable (IntegrationFailed provider _details)) =
    "provider unavailable: " <> provider

A job or CLI can keep the same boundary but choose a stricter mapping.

integrationSucceededOrMessage :: IntegrationResult a -> Either Text a
integrationSucceededOrMessage (IntegrationSucceeded value) =
    Right value
integrationSucceededOrMessage (IntegrationUnavailable (IntegrationDisabled provider)) =
    Left ("integration disabled: " <> provider)
integrationSucceededOrMessage (IntegrationUnavailable (IntegrationTimedOut provider _timeoutMicros)) =
    Left ("integration timed out: " <> provider)
integrationSucceededOrMessage (IntegrationUnavailable (IntegrationFailed provider _details)) =
    Left ("integration failed: " <> provider)

Standalone checks

Not applicable in this pattern; sections 4, 5, and 6 compile standalone.

Last-Guardian Protection

Raw source: Patterns/Actions/LastGuardianProtection.lhs

Pattern intent and mechanism

Prevent the removal or demotion of the last owner, admin, or lead of a group, project, or organization. Before the destructive action, count how many other guardians remain. If the count is zero, deny the action.

This is UX/app-level protection, not a hard invariant. The check is read-before-write without locking. Two parallel demotes can both see the same remaining guardian and proceed, leaving none.

Use this pattern when:

• a resource must retain at least one member with elevated privileges,
• the action removes or demotes the current guardian,
• a silent orphan (no owner) would break downstream workflows.

For hard invariants, combine this pattern with a database trigger or transactional SELECT ... FOR UPDATE. The app-level guard catches the common case; the trigger or lock catches the race.

Project-specific notes and rollout guidance

Call the guard after the actor-target authorization gate but before any database writes. The gate stack should be: policy check → ownership check → guardian check → write.

Keep the guard specific to one guardian role. Do not try to model a generic "any role with any privilege" check; the query becomes complex and slow. If multiple roles count as guardians (owner and admin), write separate guards or use a single query that counts both.

Document the race caveat in the pattern prose and in the host code. A comment like "read-before-write without locking — see LastGuardianProtection pattern" is enough.

For hard invariants, use a trigger that counts remaining guardians before the delete or update commits and raises an exception if the count would drop to zero. PostgreSQL CHECK constraints cannot contain subqueries, so a plain constraint is not sufficient.

Alternatively, use application-level locking (SELECT ... FOR UPDATE) in the guard query to serialize concurrent demotes. This prevents the race at the cost of holding a lock for the duration of the transaction.

Supporting snippets

IHP query that counts remaining guardians:

remaining <- query @Subscription
    |> filterWhere (#groupId, current.groupId)
    |> filterWhere (#role, Lead)
    |> filterWhereNot (#userId, current.userId)
    |> fetchCount

Deny if no guardians remain:

accessDeniedUnless (remaining > 0)

Core reusable pattern infrastructure

{-# LANGUAGE ImplicitParams #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}

module Patterns.Actions.LastGuardianProtection where

import Prelude
import IHP.ControllerPrelude

-- | Configuration for a last-guardian check.
-- | The caller supplies the count query. The deny action is either a throw
-- | (for IHP controller gates) or an explicit result (for UX decisions).
data LastGuardianConfig entity = LastGuardianConfig
    { remainingGuardians :: entity -> IO Int
    }

-- | Explicit result for callers that decide how to handle denial.
-- | Use this for UX paths (show a modal, redirect with a flash message)
-- | instead of a hard 403.
data GuardianResult = GuardiansRemain | LastGuardianDenied Text
    deriving (Eq, Show)

Helper implementation examples

-- | Throwing gate. Use this inside IHP controller actions, consistent with
-- | other 'ensure*' gates in 'PurePolicyControllerGate' and
-- | 'ActorTargetAuthGate'.
ensureRemainingGuardians
    :: (?context :: ControllerContext)
    => LastGuardianConfig entity -> entity -> IO ()
ensureRemainingGuardians LastGuardianConfig { remainingGuardians } entity = do
    count <- remainingGuardians entity
    accessDeniedUnless (count > 0)

-- | Non-throwing variant. Use this when the caller needs the result for
-- | conditional UI (e.g. disable the demote button with a tooltip).
checkRemainingGuardians :: LastGuardianConfig entity -> entity -> IO GuardianResult
checkRemainingGuardians LastGuardianConfig { remainingGuardians } entity = do
    count <- remainingGuardians entity
    if count > 0
        then pure GuardiansRemain
        else pure (LastGuardianDenied "last guardian cannot be removed")

Usage examples

A project membership system where each project needs at least one Lead.

data Membership = Membership
    { membershipId :: Int
    , membershipProjectId :: Int
    , membershipUserId :: Int
    , membershipRole :: Text
    }
    deriving (Eq, Show)

-- | Count remaining leads for this project, excluding the current member.
countRemainingLeads :: Membership -> IO Int
countRemainingLeads membership = do
    -- Simplified: real implementation uses IHP's query DSL
    pure 1  -- placeholder

lastLeadConfig :: LastGuardianConfig Membership
lastLeadConfig = LastGuardianConfig
    { remainingGuardians = countRemainingLeads
    }

The throwing gate is used inside controller actions.

-- | Before demoting a member from Lead to Contributor, throw 403 if
-- | this is the last lead. Called inside an IHP controller action.
canDemoteMember :: (?context :: ControllerContext) => Membership -> IO ()
canDemoteMember = ensureRemainingGuardians lastLeadConfig

The non-throwing variant is used for conditional UI.

-- | Check if demoting is allowed; return a result for UI handling.
-- | The view can show a disabled button with a tooltip when denied.
canDemoteMemberUI :: Membership -> IO GuardianResult
canDemoteMemberUI = checkRemainingGuardians lastLeadConfig

Race caveat: two parallel demotes of the only two Leads both see one remaining and proceed, leaving none. A trigger or SELECT ... FOR UPDATE prevents this.

Standalone checks

The infrastructure and examples above compile as one module under the normal ordng pattern check. No extra scaffolding is required.

Narrow Public Fill Boundary

Raw source: Patterns/Actions/NarrowPublicFillBoundary.lhs

Pattern intent and mechanism

IHP's fill @'[...] is an explicit field allowlist, but a single allowlist used by every controller action is a security boundary leak. If the public signup path can fill fields that belong to admin privilege changes or to server-controlled counters, the explicit list is correct in syntax and wrong in authority.

This pattern splits one monolithic builder into named, path-specific builders. Each builder carries only the fields that belong to its boundary:

1. Public construction path — fields supplied by an unauthenticated or weakly authenticated request (for example, signup).
2. Self-edit profile path — fields a normal authenticated user may change about themselves.
3. Privileged/admin path — fields only a guarded action may change.

Server-controlled fields (role, counters, lock state, media references, confirmation flags) are never in a public fill list. They are set explicitly, outside fill, after validation or inside the privileged path.

The pattern identity in host code is the named builder function: buildSignupUser, buildEditUser, buildAdminUserUpdate, or local domain equivalents. A grep for buildSignup should reveal the entire public boundary.

Use this pattern when:

• a record has fields that mix public input with internal server state,
• the same record is created or updated from more than one trust boundary,
• generated records make every column available and only a subset belongs to public input.

This is an action pattern because the security boundary lives in the request-to-domain construction path inside controller actions. The mechanism is server-side; it does not depend on view-level hiding or on form field omission.

Project-specific notes and rollout guidance

Inventory every fill call that touches user-facing create or update actions. For each call, classify the fields:

• Public — the unauthenticated user may supply this (name, email, password).
• Self-editable — the authenticated owner may change this (nickname, preferred language).
• Privileged — only an admin or guarded action may touch this (role, account state).
• Server-controlled — the application sets this and the user never does (counters, timestamps, lock flags, foreign keys to internal records).

Create one builder per boundary. Do not reuse a broad builder for a narrow path "because the form does not expose those fields." The server boundary is the authority; the form is only one client.

Set server-controlled fields after the narrow fill, never inside it:

user
    |> buildSignupUser
    |> set #privilege NormalUser
    |> set #failedLoginAttempts 0

Give each builder an explicit type signature. Use _ for the constraint when IHP's generated field names or implicit request context make a fully written signature fragile:

buildSignupUser :: _ => User -> User

The return type (User -> User) is never inferred loosely; keeping it explicit makes the boundary grepable and prevents silent type-driven changes.

Name builders after the boundary, not after the record. buildSignupUser signals the trust level; buildUser does not.

When an admin action needs the same public fields plus privileged ones, duplicate the public list rather than calling the public builder and then overwriting. The duplicated list is explicit; the call-and-overwrite pattern hides which fields are actually being written.

POST-only for state-changing actions.

IHP's CSRF protection relies on SameSite=Lax session cookies, not CSRF tokens. Every state-changing action must allow only the HTTP method(s) it expects. Form-backed create and update actions typically accept only POST; logout may accept POST or DELETE. Reject everything else before any database read or write.

action UpdateUserAction { userId } = do
    unless (Wai.requestMethod request == "POST") do
        redirectTo (EditUserAction userId)
    -- ... proceed with update

A GET (or HEAD, OPTIONS, or any unexpected method) that reaches fill or updateRecord is a CSRF risk. Actions that only render a form (EditUserAction) remain GET-safe.

Persisted secret fields never appear in rendered HTML.

Persisted secret fields such as passwordHash must never be prefilled from records into rendered HTML. Recovery or invite tokens may appear only at their intentional delivery boundary — for example an emailed link or a route parameter — and must not be copied from stored record fields into generic forms or hidden inputs.

IHP's HSX escapes interpolated values by default, which prevents XSS injection, but escaping does not make a secret safe to display. A persisted secret in HTML is a confidentiality leak even when it cannot execute scripts.

Audit every form that pre-fills values from a database record. Whitelist the fields explicitly and exclude secrets:

-- WRONG: passwordHash leaks into the HTML response
<input type="hidden" name="passwordHash" value={user.passwordHash} />

-- CORRECT: the form only carries fields the user may edit
[hsx|
    <input type="text" name="firstName" value={user.firstName} />
    <input type="text" name="email" value={user.email} />
|]

A one-line audit rule: if a field name contains "password", "token", "secret", or "hash" and it comes from a persisted record, verify it does not flow into HTML output.

Supporting snippets

IHP signup builder with narrow public allowlist and server-controlled fields set outside fill:

-- | Builder for public signup. Only fields the user may set during signup.
-- The password field here carries the raw input from the form; it must be
-- hashed with 'hashPassword' before persistence.
buildSignupUser :: _ => User -> User
buildSignupUser user = user
    |> fill @'[ "firstName", "lastName", "nickname", "email"
              , "passwordHash", "language"
              ]

-- Usage in controller, after validation:
--   let built = user |> buildSignupUser
--   hashed <- hashPassword (get #passwordHash built)
--   built
--       |> set #passwordHash hashed
--       |> set #privilege NormalUser
--       |> set #failedLoginAttempts 0
--       |> set #lockedAt Nothing
--       |> createRecord

Self-edit builder excluding privilege and server-controlled state:

-- | Builder for user profile edit. Allows editable profile fields only.
-- Privilege changes remain admin-only via a separate privileged action.
buildEditUser :: _ => User -> User
buildEditUser user = user
    |> fill @'[ "firstName", "lastName", "nickname", "email"
              , "language"
              ]

Admin update builder that includes privileged fields:

-- | Builder for admin-only user update. Includes fields that public or
-- self-edit paths must never touch.
buildAdminUserUpdate :: _ => User -> User
buildAdminUserUpdate user = user
    |> fill @'[ "firstName", "lastName", "nickname", "email"
              , "language", "privilege"
              ]

Explicit type signatures with inferred constraints. Use this shape when generated field or enum names collide with implicit request context:

buildSignupUser :: _ => User -> User
buildEditUser   :: _ => User -> User

Core reusable pattern infrastructure

{-# LANGUAGE OverloadedStrings #-}

module Patterns.Actions.NarrowPublicFillBoundary where

import Prelude
import Data.Text (Text)

-- | Forward pipe for readable record-update chains.
(|>) :: a -> (a -> b) -> b
(|>) x f = f x
infixl 0 |>

-- | Generic privilege level for examples.
data Privilege = NormalUser | Admin
    deriving (Eq, Show)

-- | Generic user record with mixed-sensitivity fields.
-- In IHP this is the generated database record; here it is reproduced
-- explicitly so the boundary examples compile without framework imports.
data User = User
    { firstName :: Text
    , lastName :: Text
    , nickname :: Maybe Text
    , email :: Text
    , passwordHash :: Text
    , language :: Text
    , privilege :: Privilege
    , failedLoginAttempts :: Int
    , lockedAt :: Maybe Text
    , profilePicId :: Maybe Int
    }
    deriving (Eq, Show)

-- | A fresh user with only server-controlled defaults.
-- Application code uses the framework's @newRecord@ instead.
newUser :: User
newUser = User
    { firstName = ""
    , lastName = ""
    , nickname = Nothing
    , email = ""
    , passwordHash = ""
    , language = "en"
    , privilege = NormalUser
    , failedLoginAttempts = 0
    , lockedAt = Nothing
    , profilePicId = Nothing
    }