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.

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.

Domain abstraction starts with the modeled world, not with its database schema. Which things retain identity through change? Which values, roles, relationships, and contexts matter? Which states and operations are valid? In ordng, types and constrained interfaces make those distinctions explicit before persistence is designed as a representation of the facts that must survive execution.

Model Meaning Before Storage

Thinking with types means using types to discover and express domain structure, not merely generating records from tables. Distinct identity types prevent accidental substitution; product and sum types express combinations and alternatives; opaque values and checked constructors protect accepted states. Operations describe permitted transitions rather than exposing arbitrary field updates.

The compiler establishes only encoded properties. A constructor may need runtime checks for amounts, membership, or whole-collection invariants. A valid value in memory does not establish authorization or a safe write against concurrently changing state. Accepted domain meaning, static guarantees, dynamic checks, and durable integrity have different responsibilities.

The Atomic Domain Model develops this order and its persistence boundary. It applies the existing Contract Layer, not a new contract format: accepted claims and property-appropriate checks precede assertions that an implementation is correct. A simple field or relation need not acquire a separate contract framework.

What Atomic Domain Modeling Adds

Atomic domain modeling is a focused modeling discipline within type-driven design, not a synonym for all good domain modeling. It brings explicit domain modeling and reliable rules together with graph-based association. Typed relations and shared semantic content across contextual roles are complementary mechanisms of this synthesis, integrated into domain types and operations and usable separately or together. Its subject is the separation and composition of:

• identity — what remains the same across observations and changes;
• content — what an identified semantic unit expresses;
• role — how that unit participates in a particular domain use;
• relation — what assertion connects identified things, with which payload;
• context — where, when, or under which revision that assertion applies.

The purpose is to let useful meaning participate in several structures without copying it unnecessarily or erasing the different rules of those structures. An application may need typed domain relations without shared content nodes, or shared content identity without a generalized relation catalog. These are separate decisions, not a package to install.

"Atomic" names the chosen granularity of an independently useful semantic unit. It does not mean smallest possible record, one database row, or transactional atomicity. The unit is small enough when further subdivision would not improve the required operations.

The ingredients have established prior art in domain-driven design, typed functional programming, content modeling, and typed graphs. The contribution sought here is a practical architectural synthesis and guidance for its selective application, not a new type system or graph primitive. The source-fit comparison distinguishes graph-schema conformance, static API guarantees, checked construction, and the still-proposed ADM synthesis. These are complementary sources of evidence, not interchangeable meanings of "typed".

Typed Relations Before Relation Tables

A relation has endpoint roles, meaning, and possibly payload and context. Its kind may be a closed algebraic data type with a dedicated interpreter. Distinct endpoint ID types and a checked collection can express useful guarantees without any runtime type catalog or universal node identity.

A shared metadata catalog is a further choice when several real predicates or relation families need common interpreted behavior. Many instances of one predicate do not alone justify that choice. A dedicated relation type and its ordinary persistence table can remain the smallest sufficient design.

Relation properties must be stated precisely:

• Direction assigns source and target roles. It does not imply asymmetry.
• Symmetry means that A R B implies B R A; it does not require two stored records. Asymmetry excludes the reverse pair, including self-relations. Unspecified symmetry does not forbid reciprocal pairs or cycles.
• Acyclicity, transitivity, and endpoint cardinalities are separate rules.
• Forward and reverse labels present one fact from different endpoints. A distinct inverse predicate needs its own explicit semantics.

A citation is directed even when both citation and backlink can be displayed. Support or contradiction does not become a taxonomy merely because it has a direction. These are domain decisions, not consequences of an edge label or foreign-key layout. An interpreter, constructor, or database mechanism must actually enforce any claimed invariant.

Shared Content and Polymorphic Roles

Content modeling is one important application of this discipline. A paragraph, definition, or other text-bearing unit may need independent reference, reuse, revision, or classification. Equal text does not prove shared identity, and an ordinary-language field does not automatically need a node.

A semantic node gives an independently useful unit an identity in a graph-capable model. It need not begin as a row in a nodes table. Prefer an existing domain identity when it already supports the required behavior.

Here, polymorphic means that the same semantic identity can take several contextual roles. It is not necessarily parametric polymorphism, inheritance, or an open-ended property bag. Strong typing helps preserve the different roles; it does not require a new content copy for each role.

This retained sketch illustrates a task use and topic classification, not a physical schema or two distinct content roles. Task state and topic placement remain explicit domain structures around the content. A separate document placement reusing the same content identity would illustrate a second contextual role; classification alone does not establish one.

A model must also decide whether a role refers to a content identity or to a specific revision. Editing shared content must not silently rewrite historical decisions. Shared content does not merge task completion, document revision, authorization, or process execution into one lifecycle. The ability to attach roles is not a promise of cheap migration between arbitrary domain objects.

Association, Classification, and Projection

Where product behavior needs it, the same unit can participate in associative links and one or more classifications. Citations, argument links, and topic hierarchies serve different purposes; there is no requirement for one universal tree. Classification and reachability may supply inputs to matching, capability assessment, assignment, authorization, allocation, or aggregation; each operation retains its own domain rules.

Aliases, stable links, search, and navigation make these identities usable. Derived views may present a graph, tree, table, or document without forcing the stored representation to have that shape. These operations justify abstraction more concretely than the mere availability of a generic schema.

Persistence as a Derived Representation

Ask which facts, identities, and historical decisions must survive execution, not which type mechanically becomes which table. Requests, accepted values, computed views, and durable records need not share a representation. One domain value may span several tables; a technical storage key need not be a domain ID.

Persistence is subordinate to domain meaning but has its own integrity work: referential constraints, uniqueness, concurrency control, atomic writes, versioning, migration, and checked restoration. These concerns can reveal gaps and feed back into the domain design. Derivation is not an irreversible waterfall or an assertion that serialization solves durable correctness.

The relational projection discussion explains how tables and constraints can represent facts selected for durability. It does not prescribe a standard ADM schema or require shared nodes and relation metadata.

Relationship to Patterns and Literature

Foundations own the conceptual distinctions and decision boundaries. Patterns own reusable implementation mechanisms and their verification; the literature dossier owns paper claims and dated host evidence. The type-driven domain design source provides adjacent background, while the ADM dossier records concrete investigations without making them universal product requirements.

Existing schema Patterns remain implementation material to assess against this foundation. Their type-first alignment, and the corresponding Domain Modeling recipe, are a separate follow-up; this foundation does not declare that work complete or introduce a generic relations framework.

For prior art, see Adjacent Models. For neighboring software products, see Adjacent Products.

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.

MusicBrainz demonstrates that even a close production combination of explicit entity tables, stable semantic identity, endpoint-typed relationship families, shared relationship types, and attributed relations is established prior art. The focus of ordng is therefore a practical synthesis of explicit domain modeling and graph-based association, together with the decisions governing its selective application:

1. model domain identities, values, roles, relations, and operations in types;
2. reuse an external semantic identity when it already fits;
3. justify shared content identity and shared relation interpretation separately;
4. derive persistence for the facts and historical decisions that must endure;
5. verify the result through observable construction, restoration, and durable behavior rather than through schema shape alone.

In this sense, ordng should not simply adopt the standard property-graph or MusicBrainz schema vocabulary wholesale. A semantic node identifies independently useful content; an ordinary domain entity can also appear as a node in a graph projection without becoming a separate content object. Relation emphasizes the domain assertion connecting participants rather than only the graph edge that represents it.

Source Fit for the Type-First Model

"Typed" does not identify one guarantee. A graph schema constrains admissible instances; a programming-language type constrains values and API combinations; a checked constructor establishes conditions on runtime input. A type can retain the result of such a check without the compiler proving the checking algorithm or the underlying business rule correct.

The source comparison below was reassessed on 30 October 2026. It separates mechanism-level prior art from the local application and the proposed ADM synthesis; it is not an exhaustive literature survey.

The invoice matrix dossier is separate evidence that ordinary Haskell domain types and whole-set checks can implement one useful relation family. It is not proof of the need for a generic graph substrate. The shared-content sketch remains a conceptual example rather than implemented host evidence.

The separation of identity, content, role, relation, and context, together with the decision to require durability before choosing storage, remains the proposed ADM synthesis. The reviewed sources support individual mechanisms, not that whole decision procedure or its effectiveness across applications. No claim of novelty follows from a gap in this bounded comparison. Shared-content lifecycle behavior and the practical value of the decision procedure still need independent examples and evaluation.

Source entries and exact reading scope:

• Koppmann: Type-Driven Domain Design
• King: Parse, Don't Validate
• Noonan: Ghosts of Departed Proofs
• Erwig: Inductive Graphs
• Laux: The Typed Graph Model
• GHC 9.12.2: Generalised Algebraic Data Types — complete documentation section read on 30 October 2026; this is a language mechanism reference, not a domain-modeling case study.

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.

In a schema-light use, labels and property keys depend on conventions. A typo can create a different label rather than a rejected relation. This is not an intrinsic limit of property graphs: application types and graph schemas can constrain those names and their interpretation.

The relevant distinction is between an unchecked label and an explicitly interpreted semantic kind. Either a closed algebraic data type or a validated metadata catalog can supply that kind. Making relation types persistent objects is not a prerequisite for typed relations.

Distinction from Atomic Domain Modeling

In ordng, shared content participates through explicitly modeled contextual roles with their own state and operations, rather than acquiring arbitrary properties. These roles and their relations remain part of the domain model. Their constrained interfaces express the rules of each use while preserving shared content identity.

Relations follow a similar logic: first define their endpoint types, kinds, payload, and invariants. A checked domain-specific relation may be sufficient. Its persistence can use concrete foreign keys without a generic relation-type catalog. Shared metadata is an additional mechanism to justify, not an inherently stronger replacement for dedicated types and code.

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

MusicBrainz Entities and Relationships

MusicBrainz is direct production prior art for identity-bearing domain entities connected through typed, inspectable relationships. It should not be described as merely a source of instrument names or as an untyped graph. Its layers must nevertheless remain distinct:

The schema keeps each primary entity kind in an explicit table and assigns stable MusicBrainz identifiers. Relationship storage is split into endpoint-specific l_* tables, a shared link table for relationship instances, and link_type for Relationship-Type metadata. This architecture is close to the proposed notion of relation families: endpoint-specific tables preserve referential integrity while sharing Relationship-Type and Relationship-Attribute infrastructure. It is not a universal node or polymorphic-edge table.

MusicBrainz also represents concrete Instrument taxonomies through the Instrument-Instrument Subtype Relationship Type. Its forward reading is, for example, bowed lyre has subtype talharpa; the reverse reads talharpa type of bowed lyre. The direction preferred by this repository expresses the same fact as talharpa specializes bowed lyre.

The historical paper chain Fender Rhodes -> E-Piano -> Keyboards is not a MusicBrainz taxonomy. MusicBrainz records Rhodes piano as an Instrument that is type of electric piano, but no reviewed path continues from there to Keyboards; independently, its Instrument Type is Percussion instrument. The three-step Contribution taxonomy was a local design experiment and is rejected as a claim about current or agreed seshn.org behavior.

MusicBrainz historical performance credits can provide evidence that an artist performed an Instrument or vocal role on a Recording. They do not establish that a current seshn.org user claims a Capability, accepts its scope, meets a Requirement, or should receive a concrete Assignment.

MusicBrainz therefore rules out novelty claims based on stable semantic identity, typed or attributed relationships, endpoint-typed relation storage, forward and reverse presentation labels, or relational/graph hybridity alone. The remaining question for ordng is whether a useful decision procedure can explain when a host application should retain an explicit entity, reference an external vocabulary, project a local taxonomy, or introduce a semantic node or relation family. This example alone does not justify a generic substrate.

Primary sources, retrieved 19 August 2026:

• MusicBrainz database schema
• MusicBrainz relationships
• MusicBrainz Relationship Attributes
• MusicBrainz Instrument model
• Rhodes piano Instrument
• Instrument-Instrument Subtype Relationship Type
• Artist-Recording Instrument Relationship Type
• Artist-Recording Vocal Relationship Type
• MusicBrainz identifiers
• Pinned schema source
• Pinned relationship attribute validation
• Pinned relationship creation path

The reviewed sources do not establish generic symmetry, asymmetry, acyclicity, or arbitrary hierarchy flags; a generic capability/requirement matcher; or a universal node table. Those absences should not be inferred merely from matching forward and reverse phrases or from the link_type parent hierarchy.

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. Its starting point is domain meaning expressed through types and operations, not sparse attributes or arbitrary user-defined fields. Shared content and typed relations are selective mechanisms within that model; explicit operational entities retain their rules.

A useful contrast to schema-light modeling is that domain-specific facts remain explicit typed fields of entities, roles, or relations. Their eventual storage may use ordinary columns. An open property extension needs its own validation and compatibility rules rather than replacing those domain types by default.

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" specifies node and edge types, structured properties, endpoint sets, multiplicities, and integrity constraints. Instances are related to the schema by a typing map. The paper locates constraint checking before database changes can be committed; it does not present Haskell types or an operational API. Its query and manipulation language remains future work.

This supports explicit relation structure and admissibility, not a claim that schema typing proves application operations correct. ordng does not adopt the paper's broad superiority claims over other data models or infer a need for hypergraph infrastructure. See the source excerption.

Reference:

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

Haskell Ecosystem

Typed functional domain modeling is prior art for the starting point itself: identity newtypes, algebraic data types, opaque values, checked construction, and operations that preserve domain invariants. The Type-Driven Domain Design source provides practical background. None of these mechanisms is an ADM invention.

King's Parse, Don't Validate provides a direct Haskell account of retaining checked conditions in result types. A runtime check can produce an opaque accepted value; clients then consume that value through a constrained interface. This is not the compiler proving the check's implementation or domain interpretation correct.

Noonan's Ghosts of Departed Proofs goes further: its Key ks k and JMap ks k v connect a key to a particular key set. A checked membership result can be carried to later operations, and the adjacency-list example constrains references to that same set. This is stronger than merely giving every endpoint a domain-specific ID type. The library still owns the correctness of its evidence-producing operations and axioms. Its fresh type-level names are not durable domain identifiers, and this technique is not required by the current invoice matrix.

A closed sum such as ContributionType is an ordinary type whose alternatives are selected by values. It does not by itself index endpoint or payload types by relation kind. GADTs can encode constructor-specific type indices when needed; that is a separate design choice, not an implication of saying "typed relation". The current host uses fixed endpoint types and dedicated runtime interpretation.

Graph libraries such as algebraic-graphs and fgl offer representations and operations for graph structure. In particular, Erwig's inductive graphs use integer node IDs with parameterized node and edge labels; this does not establish heterogeneous endpoint typing or domain relation invariants. Relational libraries such as beam and persistent offer typed persistence and query interfaces. These mechanisms do not decide the application's semantic identities, historical meaning, or invariant boundaries.

The relevant synthesis is not a presumed gap between two library camps. It is the application-level decision to separate identity, content, role, relation, and context, then choose the required graph and persistence mechanisms. No exhaustive ecosystem survey or claim of a missing universal library follows.

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:

• Type-driven domain design supplies established techniques for expressing meaning before persistence.
• Property graphs show that typed edges and rich relationship semantics are established.
• SQL/PGQ shows that relational and graph views can be deliberately combined.
• MusicBrainz shows a production relational architecture with stable entities, endpoint-typed relation families, shared relationship types, and typed attributes.
• 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.

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 modeling separates identity, content, role, relation, and context where a domain needs their independent composition. Types express the relevant distinctions; operations describe how valid values are constructed, connected, observed, and changed.

Its focus is narrower than type-driven domain design in general: how can identified semantic units and meaningful relations participate in several uses without merging the state and rules of those uses? The overview places that question within domain abstraction and its established prior art.

Identity, Content, Role, Relation, and Context

These distinctions answer different questions:

• Identity: Which thing is this, independently of its current attributes?
• Content: What does this semantic unit express?
• Role: In what capacity does it participate in this use?
• Relation: What assertion connects these things, with which payload?
• Context: Where, when, or under which revision does that assertion apply?

Identical content does not establish identical identity. One identity can serve several roles without making those roles interchangeable. A relation can carry information that belongs neither to its source nor to its target alone.

Not every domain concept needs all five distinctions. A bounded value may need no independent identity. An entity can retain its own content. A relation may have one fixed meaning. Introduce a distinction when the operations need it, not to fill out a universal model.

Expressing the Domain in Types

Start with the domain's valid combinations and permitted operations. A Haskell-oriented design can use:

• distinct identity types to separate source, target, owner, and context;
• product types for facts that belong together;
• sum types for alternatives and meaningful state distinctions;
• opaque values with checked constructors for runtime invariants;
• operation signatures that separate proposals, acceptance, and observations.

Values, input requests, errors, accepted aggregates, and derived views have different jobs. An entity's identity remains independent of its current fields. A relation's identity may be its endpoints and kind, or a separate assertion identity when the domain needs distinct occurrences, revisions, or decisions.

Types are also a means of inquiry. An awkward constructor or ambiguous operation can expose a missing distinction in the domain model. The direction is not mechanically from prose to code: candidate types and examples help refine the meaning that domain ownership must ultimately accept.

Contracts and Guarantee Boundaries

Accepted domain meaning remains the authority. Compilation establishes encoded properties, not that those properties describe the intended domain. For an invariant-rich model, a useful development loop connects:

accepted domain meaning and observable claims
→ domain types, operations, and interpreters
→ checked construction and behavioral examples
→ comparison with the accepted claims

This applies the existing Contract Layer. A neutral executable contract can specify observations separately from production types. It is not a mandatory new artifact or framework for every field. Independence depends on what a checker shares with production, not merely on placing it in another module.

Responsibility is property-specific:

• Static types distinguish representations and permitted API combinations.
• Checked construction establishes properties such as positivity, membership, and whole-collection totals. Opaque types protect the result while all construction paths respect that boundary.
• State transitions must preserve the invariants of the resulting state.
• Authorization and external trust remain separate unless explicitly established by the operation's inputs and boundary.

A value accepted under one set of assumptions does not automatically establish that an operation is permitted in every later context.

Typed Relations and Their Interpretation

A typed relation carries constrained endpoint roles, a semantic kind, and any required payload or context. A closed algebraic data type can name the kinds; a dedicated interpreter assigns each its rules.

For example, an attribution relation may identify a source and target, classify why an amount is attributed, and carry that amount. Its kind selects which source quantity and target role must agree. Checking each relation separately may be insufficient: an opaque collection can require conservation across the whole set before accepting it. Endpoint ID types do not themselves prove membership in the particular aggregate being checked.

The invoice contribution case in the host-evidence dossier provides a concrete implementation of that distinction. Its checks preserve attribution: source quantities are fully assigned within each contribution kind, and target totals agree with the required journal amounts. Gross receivable, net revenue, and VAT are different measures, not amounts to add into one invoice total. A single-line invoice flow and a matrix component supporting M:N are different levels of evidence.

Dedicated and Shared Interpretation

One known relation kind can have its own type and operations. Several kinds can form a closed sum interpreted within one coherent relation family. A family groups relations whose endpoints, payload, and rules belong together; it need not share an interpreter with unrelated families.

Shared relation metadata becomes useful when real predicates or families require common interpreted behavior. An interpreter might inspect endpoint roles, cardinality, or traversal rules. Such metadata needs its own admissibility checks and a policy for changes in meaning. Merely replacing a constructor with a text identifier supplies neither.

The choice is between mechanisms for the required behavior, not between an untyped local model and a necessarily superior generic one. A closed type with dedicated code may remain the clearest design.

Structural Properties

Relation properties must be stated independently:

• Direction assigns source and target roles; it does not imply asymmetry.
• Symmetry means that A R B implies B R A; it does not require two stored records. Asymmetry excludes the reverse pair, including self-relations. Unspecified symmetry does not forbid reciprocal pairs or cycles.
• Acyclicity, transitivity, and endpoint cardinalities are separate rules.
• Forward and reverse labels present one fact from different endpoints; a distinct inverse predicate has its own semantics.

A citation remains directed when both citation and backlink can be displayed. Classification and reachability may supply inputs to matching, capability assessment, assignment, authorization, allocation, or aggregation; each operation retains its own domain rules.

Content Identity and Contextual Roles

A semantic node represents an independently addressable content unit. Its useful granularity follows from operations such as reference, reuse, revision, and traversal. A paragraph may need an identity where a whole document is too coarse; a single word may be too small to serve any independent operation.

"Atomic" describes that chosen modeling granularity, not absolute indivisibility. An existing domain identity should be reused when it already supports the needed operations. Equal text alone is not a reason to merge two units.

Polymorphic Roles

Polymorphism here means one semantic identity serving several roles. It does not require untyped endpoints or a single lifecycle. A task and a document may refer to the same content while retaining different states and permissions. Task completion changes the task role, not the meaning or status of every other use.

For example, a task and a procedure placement may reference the same instruction node, while a typed relation connects that instruction to a specific account-mapping revision. A reference to the instruction need not reference the task that uses it. This conceptual combination connects content uses to domain entities through explicit types and operations, not a separate unconstrained graph layer.

Specify whether a role refers to current content or to a fixed revision. Shared content does not decide whether edits propagate to every use. Intrinsic content, contextual placement, and revision policy remain distinct parts of the model.

Shared content identity and shared relation interpretation are independent choices. A model may need either, both, or neither. Neither choice entails an open-ended property bag.

Operations and Observations

The model becomes useful through operations: construct an accepted value, connect identified units, revise content, change a role, validate an attribution, or derive a view. Choose them from the actual domain behavior rather than from the availability of a generalized representation.

Queries may expose a graph, tree, table, or document over the same values. An association can support discovery while a taxonomy supports classification. Neither projection must become the identity or lifecycle of the underlying unit.

At this point the model can be constructed, evaluated, and tested entirely within one execution. Its identities, roles, relation kinds, and invariants already have meaning. No further architectural layer is needed merely to make that model complete.

Domain Type Sketches

These sketches describe domain types and operations, not a persistence schema. Row-based boxes denote product types: their rows are typed constituents, not columns. Boxes listing alternatives denote closed sum types. Type and operation names are schematic rather than a proposed public API or exact host signatures. Opaque types are explicitly labeled; the collection type also has a double border. Rounded boxes denote operations, and example boxes are labeled as values.

Connections use five distinct conventions:

Content Identity and Contextual Roles

This conceptual example is not host evidence. It chooses references to current content; a use that must retain historical content would instead identify a specific revision. Distinct role identities and states keep task completion separate from document review.

Typed Relations and Checked Construction

The invoice contribution evidence supports this relation-family sketch, not the preceding shared-content example. The endpoint ID types and closed contribution kind are static distinctions. ContributionRequest nevertheless carries an unchecked Integer amount in minor units. PostingContribution has an opaque constructor and carries Doppik.PositiveAmount, preserving a runtime-checked amount property.

The public contributionMatrix operation receives requests and source/target facts. Only after all checks succeed does it expose an accepted matrix and its PostingContribution values. Amount validation alone does not establish endpoint membership, kind-compatible target roles and sides, or whole-matrix source and target totals. Context is supplied to validation, not stored in each relation. Dedicated code interprets the closed kind to select source quantities and target roles and sides; no runtime type catalog is required.

The matrix component has executable M:N examples; the evidenced invoice flow remains single-line. No Node reference or shared interpretation across unrelated relation families is required. Shared content identity and shared relation interpretation remain independent modeling decisions.

What Must Outlive an Execution?

A further requirement arises when later work must recover earlier facts or decisions. Which observations must remain possible after the current execution ends? Which identities and historical meanings must remain recognizable?

This is where persistence enters the design. The answer selects what must be durable; it does not turn every type into a persistent object.

• A request may be transient, or retained when audit or replay requires it.
• An accepted value may need its identity, constituent facts, and the decision context under which it was accepted.
• A derived view may be recomputed if its authoritative inputs and interpretation remain available. Otherwise a required historical observation may need a snapshot.
• A role may need to retain a particular content revision rather than resolve to whatever content is current when it is next read.

If no operation needs information beyond the execution, no persistence follows from the model alone.

Representation and Restoration

Choose a representation that preserves the required observations. One domain value may span several records. A technical storage key may serve a different purpose from a domain identity. Neither a one-type/one-table correspondence nor mechanical serialization is implied.

Storage followed by restoration should recover the observations required by the accepted contract, not necessarily incidental layout, order, or technical keys. Recompute only what the contract permits. Historical decisions must not be silently reinterpreted under today's rules.

Restoration is a trust boundary: decode stored facts, validate relevant combinations, and preserve identities and provenance rather than regenerating them. Unsupported historical data needs an explicit compatibility or migration policy; corrupt combinations must not silently become apparently valid values.

Durable Integrity

Persistence introduces additional obligations. A decision against observed state can become stale before it is written. Atomic writes, concurrency control, uniqueness, and referential constraints must protect the durable facts at their actual boundary. A pure accepted value does not guarantee a valid concurrent commit, and valid records do not alone establish every domain invariant.

These requirements can expose gaps in the earlier model and feed back into its types and operations. Persistence is derived from the required continuity of domain meaning, but its correctness is not a trivial consequence of type safety.

Candidate Relational Projection

When relational storage fits, concrete entity and relation tables can preserve the chosen identities, payload, and context. Foreign keys and unique constraints protect the corresponding references and identity rules. Domain validation and transaction protocols supply the guarantees those constraints do not express.

A closed relation kind can be encoded as a constrained value; it does not require a relation-type table. A shared metadata catalog or independently addressable content may need their own tables when those facts must endure. Their necessity comes from the model's operations and durability requirements, not from a standard ADM schema.

For a relation identified by its source, target, and kind, a composite key may express the identity directly. A framework may instead require a technical key plus a unique constraint on that triple. If the domain distinguishes occurrences or revisions, those distinctions must be represented as well.

MusicBrainz provides prior art for endpoint-specific relation tables with shared relationship metadata; see Adjacent Models. It is one useful comparison for this representation decision, not the definition of the mental model. Concrete schema Patterns and their implementation checks belong in Patterns/.

Controlled agentic development starts with responsibility. Humans remain accountable for product intent, semantic adequacy, architecture, accepted risks, and the delivered result. Agents are most useful for bounded mechanical work after the relevant decisions and success criteria are clear; they do not remove the need to review execution or outcome where meaning and risk are involved.

Software gives agents effective rails when recurring decisions are represented by explicit types, narrow interfaces, domain structures, named patterns, and deterministic checks. Constraints should be enforced at the closest suitable boundary—through types, component interfaces, generated artifacts, linting, compiler checks, or local policy—rather than left as fragile prompt instructions.

Compiler feedback is powerful, but its guarantees are property-scoped: it establishes only properties encoded in the checked types, generated artifacts, and static checks. Fast diagnostics help an agent generate and repair code; their speed does not establish independent acceptance or the semantic adequacy of the checked criteria. Types can encode positive invariants as well as exclude invalid states. For types, tests, and richer proofs alike, the relevant question is which property is established under which assumptions. Runtime behavior, browser interaction, accessibility, operational effects, and semantic adequacy require their own evidence or human judgment.

Typechecking an entire tool-composition program before execution can reject a static mistake before any effect in that program occurs. Haskell Agent's code-mode experiments demonstrate this cell-scoped protection, not transactional execution or a general reliability advantage. Structural tool types check shapes; domain types and trusted constructors can encode stronger distinctions, while restricted effects and interpreters can govern authority. Arbitrary IO, interchangeable text identifiers, runtime failures, and effects in earlier cells remain outside that structural guarantee. This pre-execution check is useful evidence about an execution mechanism, not acceptance of a normative claim or authorization by itself.

A persistent contract binds an accepted named claim to durable representation, responsible ownership, and property-appropriate verification. The Contract Layer is a lens over existing artifacts, not a uniform format, DSL, or additional artifact category. Tests may adapt accepted meaning to executable checks; they are not automatically its normative store. Type-correct contract data remains a proposal until its meaning is accepted. AuthorizationClaimRegistry supplies one bounded application mechanism.

Pre-execution authority and implementation conformance are separate trust boundaries. A harness decides which effects an agent may execute; project-side types, tests, graders, and reviews establish only the properties they encode. Normative claims and independent acceptance artifacts must remain outside the candidate's control and must not be silently weakened to make an implementation pass. Using the same implementation language on both sides does not merge their ownership or guarantees. Checker independence is property-specific: disclose shared helpers, data sources, fixture assumptions, and editable expectations. Separate modules alone do not protect contracts, fixtures, or checkers from coordinated changes; the registry Host Evidence does not establish such technical protection. Changes to those acceptance surfaces are meaning changes, not merely repairs to restore passing checks.

Product intent and reusable implementation mechanisms are separate concerns. Intent may emerge exploratively through prompting and prototypes or be stated in a task-local specification. In either case, ordng patterns can guide a known implementation mechanism without becoming the product specification or replacing task-specific acceptance criteria.

The ownership boundary must remain explicit. ordng owns reusable pattern contracts and quality semantics; the selected agent harness owns execution mechanics, model and provider choices, session state, previews, and review integration. Durable project knowledge belongs in repository artifacts rather than in an agent's transient context. Patterns/Bootstrap/AgenticHandoff.md describes how a project instantiates this boundary.

Host verification closes the feedback loop. Static checks cover encoded properties, while targeted runtime or browser checks cover behavior those checks cannot observe. Patterns should expose the success criteria that can be verified and the obligations that remain for human review; reusable gaps found in a host application should feed back into the ordng canon. Derived documents and generated assets need their own completeness and freshness checks when those properties are claimed; policy conformance does not establish rendered output or its accessibility.

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

IHP request and response contracts

Keep three response shapes distinct in Actions patterns:

• final controller responses such as redirectTo, render, and respondHtml return IO ResponseReceived directly;
• conditional combinators such as when and unless still require IO (), so lift a response with earlyReturn only inside those combinators;
• guard helpers such as accessDeniedUnless legitimately return IO () and require the exact implicit ?request :: Request and ?respond :: Respond constraints.

respondAndExit is already polymorphic (IO a) and needs no additional earlyReturn. Standalone IO () helpers that do not return a response also stay unchanged.

Mutation method boundary

A POST-only action rejects every other method with 405 Method Not Allowed and Allow: POST. An action that deliberately accepts POST and DELETE lists both in Allow. Do not redirect a wrong-method mutation request: the response must identify the rejected protocol boundary. Use a small application-local or shared helper such as ensurePostMethod so the boundary remains consistent and grepable.

Within the action body, run the method guard before the first effect: before body/query parameter reads, authorization, database reads or writes, transaction start, provider work, and file reads, writes, or deletes. Framework route decoding necessarily happens before action dispatch and is outside this ordering contract.

IHP middleware and beforeAction run before action, so an action-local helper cannot guard effects already performed there. If middleware or beforeAction performs authorization, database access, or another effect that wrong-method requests must not trigger, enforce the same method boundary at that earlier lifecycle point or move the effect behind the action-local guard. Rendering a read-only form remains GET-safe.

GET and HEAD cross the same wrong-method boundary and must produce the same status and Allow header without application side effects. Request-level tests do not assert a HEAD body; HTTP transport handling owns body suppression. They do assert that database state is unchanged, no transaction or partial mutation occurs, and no application file operation runs.

For transactional deletes, additionally prove that a cleanup failure rolls back all dependent-row and parent mutations.

Custom session lockout persistence boundary

The atomic update mechanism in CustomSessionLockout.lhs uses IHP Typed SQL. Its query must be compiled against the receiving application's schema; adapt the table and column names when the authentication record is not backed by the shown users.failed_login_attempts and users.locked_at fields. The reset uses generated record fields and updateRecord, so those field labels must match the same schema.

The controller examples use the current Request/Respond response boundary: conditional redirects use earlyReturn, while final failure helpers return ResponseReceived. Logging calls are deliberately omitted because applications must use their configured logger rather than the removed IHP.Log.* API.

Catalog

Pattern Shape

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

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).

Ownership or control claims may be indirect. A target can confer control through more than one domain reference: a direct parent, an ancestor reached through the parent, or another related record loaded for the action. Define one claim extraction boundary for the target and include every domain reference that confers ownership or control. Do not let the throwing controller gate and the view permission map use different claim definitions.

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
    :: ( ?request :: Request
       , ?respond :: Respond
       , ...
       )
    => 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

Shared claim extraction for gates and view permission maps:

data TargetClaims = TargetClaims
    { directOwnerId :: Id User
    , controllingScopeIds :: [Id Project]
    }

claimsForTarget :: TargetRecord -> [RelatedRecord] -> TargetClaims
claimsForTarget target relatedRecords = TargetClaims
    { directOwnerId = get #ownerId target
    , controllingScopeIds = collectControllingScopes target relatedRecords
    }

Build these claims once and feed both the throwing gate and any row/view permission map from the same value.

Controller usage:

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

Core reusable pattern infrastructure

Reuse the pure policy and ownership vocabulary rather than defining a second permission model for the actor-target gate.

{-# 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

Compose the supplied actor policy with the ownership check for the concrete target.

-- | 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.

Pattern intent and mechanism

Represent accepted authorization claims in one heterogeneous, sum-type-backed registry. Derive family and audience views from that registry, then compare its typed expectations with separately implemented executable policy through family-specific conformance adapters.

The registry becomes normative through responsible human acceptance of its meaning, not through compilation or a passing checker. Stable claim IDs and prose identify and explain a claim; typed fields carry machine-readable meaning. Do not parse prose or IDs to decide authorization.

This example keeps authenticated capabilities and ownership exceptions separate. An own-target allowance says nothing about access to other targets, which may require scoped authority. Do not flatten authentication, ownership, roles, claimed state, dependency blockers, or target-state invariants into one boolean matrix. Add a family only when its distinct semantics require one.

The deliberate checker moat is small: contract-owned expectations are compared with observations of policy that does not consume those expectations. Calling the same policy function to construct both expected and actual values would remove that separation. Registry projections share contract data intentionally; production authorization must not silently become a registry interpreter.

Project-specific notes and rollout guidance

Copy the mechanism into normal application modules, not imports of Patterns.*. Keep claim data, production policy, and conformance adapters in separate modules in the receiving application. Here they share one file solely for standalone compilation. Separate modules are not technical protection from coordinated edits.

Before adopting a claim, name its responsible acceptor, meaning, covered inputs, and verification surface. Preserve IDs across wording-only changes; treat semantic changes as acceptance decisions, not automatic test maintenance. Do not copy the illustrative policy below as a universal authorization rule.

Family lists, public references, and test groups must project from the registry, not maintain parallel normative claim lists. Audience is publication metadata, not actor privilege or execution authorization. Public consumers may curate and order projections, but must not invent additional authorization rules. No HTML renderer is supplied here.

Use ScopedRolePermissionRegistry for scoped role policy and ActorTargetAuthGate for actor/target composition. This pattern checks selected policy properties; it does not replace those mechanisms or their controller gates.

Guarantees and limits:

• Exhaustive consumers force a case for each claim-family constructor. They do not prove that all needed claims exist, IDs are unique, prose matches fields, or accepted domain meaning is true. This example has no ID-uniqueness check.
• Checks cover only the declared observations. The ownership family below checks an authenticated owner, not anonymous access, other-target authority, or correct loading of identity and scope.
• Shared capability constructors, identity types, fixture assumptions, and adapter mappings can carry common-mode errors. A wrong capability-to-policy mapping or an omitted capability can evade a passing comparison. An accidentally empty registry could make a registry-only comparison vacuous; the example checks the current observation count separately.
• Contract fields, fixtures, comparison code, and policy remain jointly editable. Changing expected values or weakening the checker can restore green without fixing policy. Review these as separate meaning boundaries; the code provides no protected files, immutable grader, or candidate-resistant enforcement.
• No controller, request, database, renderer, accessibility, generated-document freshness, or runtime authorization conformance is established. Evidence is limited to the policy functions and inputs actually checked.
• Contract data states expectations; the checker compares; an executed result is evidence; domain acceptance grants normative meaning. Execution authorization belongs to a separate authority boundary. None implies harness authority, Language-Based Agent Control (LBAC), or a formal proof.

Supporting snippets

No schema, framework, renderer, or external test package is required. The narrow PolicySubject below supplies two family-specific observation seams, not a universal Contract DSL. Host adapters should call the real production predicates and disclose any shared helpers or fixture sources.

Core reusable pattern infrastructure

The standalone module makes exhaustiveness and unused-import checks local.

{-# LANGUAGE OverloadedStrings #-}
{-# OPTIONS_GHC -Werror=incomplete-patterns -Werror=unused-imports #-}
module Patterns.Actions.AuthorizationClaimRegistry where

import Data.Text (Text)
import qualified Data.Text as Text

Metadata does not determine permission outcomes.

newtype ClaimId = ClaimId Text
    deriving (Eq, Show)

data Audience = PublicReference | InternalReference
    deriving (Eq, Show)

data ClaimMetadata = ClaimMetadata
    { claimId :: ClaimId
    , claimProse :: Text
    , claimAudience :: Audience
    } deriving (Eq, Show)

Each family encodes only the axis it claims. Outcome is a typed expected result, not a combined authorization matrix.

data Outcome = Permit | Refuse
    deriving (Eq, Show)

data AuthenticatedCapability = SubmitTarget
    deriving (Eq, Show)

data OwnershipCapability = ModifyOwnTarget
    deriving (Eq, Show)

data AuthenticatedClaim = AuthenticatedClaim
    { authenticatedMetadata :: ClaimMetadata
    , authenticatedCapability :: AuthenticatedCapability
    , anonymousOutcome :: Outcome
    , signedInOutcome :: Outcome
    } deriving (Eq, Show)

data OwnershipClaim = OwnershipClaim
    { ownershipMetadata :: ClaimMetadata
    , ownershipCapability :: OwnershipCapability
    , ownTargetOutcome :: Outcome
    } deriving (Eq, Show)

data AuthorizationClaim
    = AuthenticatedAuthorizationClaim AuthenticatedClaim
    | OwnershipAuthorizationClaim OwnershipClaim
    deriving (Eq, Show)

All metadata and family projections handle the closed sum explicitly.

authorizationClaimMetadata :: AuthorizationClaim -> ClaimMetadata
authorizationClaimMetadata (AuthenticatedAuthorizationClaim claim) =
    authenticatedMetadata claim
authorizationClaimMetadata (OwnershipAuthorizationClaim claim) =
    ownershipMetadata claim

claimsForAudience :: Audience -> [AuthorizationClaim] -> [AuthorizationClaim]
claimsForAudience audience =
    filter ((== audience) . claimAudience . authorizationClaimMetadata)

authenticatedClaims :: [AuthorizationClaim] -> [AuthenticatedClaim]
authenticatedClaims = concatMap project
  where
    project :: AuthorizationClaim -> [AuthenticatedClaim]
    project (AuthenticatedAuthorizationClaim claim) = [claim]
    project (OwnershipAuthorizationClaim _) = []

ownershipClaims :: [AuthorizationClaim] -> [OwnershipClaim]
ownershipClaims = concatMap project
  where
    project :: AuthorizationClaim -> [OwnershipClaim]
    project (AuthenticatedAuthorizationClaim _) = []
    project (OwnershipAuthorizationClaim claim) = [claim]

Shared vocabulary identifies the observation boundary, not expected policy.

newtype ActorId = ActorId Int
    deriving (Eq, Show)

data Identity = Anonymous | SignedIn ActorId
    deriving (Eq, Show)

data TargetAuthority = NoTargetAuthority | TargetAuthorityGranted
    deriving (Eq, Show)

data PolicySubject = PolicySubject
    { observeAuthenticated :: AuthenticatedCapability -> Identity -> Bool
    , observeOwnership :: OwnershipCapability -> Identity -> ActorId
        -> TargetAuthority -> Bool
    }

Family adapters compare typed fields with policy observations. Synthetic inputs are checker-owned and do not come from the policy implementation.

data Scenario = AnonymousActor | SignedInActor | OwnTargetWithoutAuthority
    deriving (Eq, Show)

data Observation = Observation
    { observationClaimId :: ClaimId
    , observationScenario :: Scenario
    , expectedOutcome :: Outcome
    , actualOutcome :: Outcome
    } deriving (Eq, Show)

outcomeFromBool :: Bool -> Outcome
outcomeFromBool True = Permit
outcomeFromBool False = Refuse

checkAuthenticated :: PolicySubject -> AuthenticatedClaim -> [Observation]
checkAuthenticated PolicySubject { observeAuthenticated = observe } claim =
    [ Observation identifier AnonymousActor (anonymousOutcome claim)
        (outcomeFromBool (observe capability Anonymous))
    , Observation identifier SignedInActor (signedInOutcome claim)
        (outcomeFromBool (observe capability (SignedIn (ActorId 7))))
    ]
  where
    identifier = claimId (authenticatedMetadata claim)
    capability = authenticatedCapability claim

checkOwnership :: PolicySubject -> OwnershipClaim -> [Observation]
checkOwnership PolicySubject { observeOwnership = observe } claim =
    [ Observation (claimId (ownershipMetadata claim)) OwnTargetWithoutAuthority
        (ownTargetOutcome claim)
        (outcomeFromBool
            (observe (ownershipCapability claim) (SignedIn (ActorId 7))
                (ActorId 7) NoTargetAuthority))
    ]

checkClaim :: PolicySubject -> AuthorizationClaim -> [Observation]
checkClaim subject (AuthenticatedAuthorizationClaim claim) =
    checkAuthenticated subject claim
checkClaim subject (OwnershipAuthorizationClaim claim) =
    checkOwnership subject claim

conformanceObservations :: PolicySubject -> [AuthorizationClaim] -> [Observation]
conformanceObservations subject = concatMap (checkClaim subject)

policyMismatches :: PolicySubject -> [AuthorizationClaim] -> [Observation]
policyMismatches subject = filter disagrees . conformanceObservations subject
  where
    disagrees observation =
        expectedOutcome observation /= actualOutcome observation

Helper implementation examples

Illustrative production policy is intentionally implemented without reading the registry, its expected outcomes, or any contract evaluator. Target authority models an already-established grant; its derivation is outside this example.

canSubmitTarget :: Identity -> Bool
canSubmitTarget Anonymous = False
canSubmitTarget (SignedIn _) = True

canModifyTarget :: Identity -> ActorId -> TargetAuthority -> Bool
canModifyTarget Anonymous _ _ = False
canModifyTarget (SignedIn actor) owner authority =
    actor == owner || authority == TargetAuthorityGranted

examplePolicy :: PolicySubject
examplePolicy = PolicySubject
    { observeAuthenticated = observe
    , observeOwnership = observeOwn
    }
  where
    observe SubmitTarget = canSubmitTarget
    observeOwn ModifyOwnTarget = canModifyTarget

Usage examples

One illustrative registry holds both families. Actual receiving projects must accept their own claim meanings; these entries do not mandate a product policy.

authorizationClaims :: [AuthorizationClaim]
authorizationClaims =
    [ AuthenticatedAuthorizationClaim AuthenticatedClaim
        { authenticatedMetadata = ClaimMetadata
            { claimId = ClaimId "authenticated.submit-target"
            , claimProse = "Target submission requires an authenticated actor."
            , claimAudience = PublicReference
            }
        , authenticatedCapability = SubmitTarget
        , anonymousOutcome = Refuse
        , signedInOutcome = Permit
        }
    , OwnershipAuthorizationClaim OwnershipClaim
        { ownershipMetadata = ClaimMetadata
            { claimId = ClaimId "ownership.modify-own-target"
            , claimProse = "An owner needs no additional target authority "
                <> "to modify it."
            , claimAudience = InternalReference
            }
        , ownershipCapability = ModifyOwnTarget
        , ownTargetOutcome = Permit
        }
    ]

Family groups and public reference input are registry projections, not additional claim stores. A renderer may consume publicClaims but is not tested here.

authenticatedContractGroup :: [AuthenticatedClaim]
authenticatedContractGroup = authenticatedClaims authorizationClaims

ownershipContractGroup :: [OwnershipClaim]
ownershipContractGroup = ownershipClaims authorizationClaims

publicClaims :: [AuthorizationClaim]
publicClaims = claimsForAudience PublicReference authorizationClaims

Standalone checks

Run typechecking and executable checks separately; compilation does not execute runChecks:

direnv exec . ghci -v0 -ignore-dot-ghci -fno-code \
  Patterns/Actions/AuthorizationClaimRegistry.lhs
direnv exec . ghci -v0 -ignore-dot-ghci \
  Patterns/Actions/AuthorizationClaimRegistry.lhs -e runChecks

Also run the authoritative multi-topic command documented in Patterns/README.md. Keep the targeted command even when that broad check is blocked by an unrelated pattern dependency.

The checks cover the three declared observations, projections, and two deliberate policy defects. They neither establish claim completeness nor ID uniqueness.

runChecks :: IO ()
runChecks = mapM_ (uncurry assertCheck)
    [ ("all declared policy observations agree",
        null (policyMismatches examplePolicy authorizationClaims))
    , ("both families have executable observations",
        length (conformanceObservations examplePolicy authorizationClaims) == 3)
    , ("family projections retain registry entries",
        length authenticatedContractGroup == 1
        && length ownershipContractGroup == 1)
    , ("audience projection selects public metadata only",
        publicClaims == map AuthenticatedAuthorizationClaim authenticatedContractGroup
        && claimsForAudience InternalReference authorizationClaims
            == map OwnershipAuthorizationClaim ownershipContractGroup)
    , ("anonymous-policy defect is reported precisely",
        policyMismatches anonymousAllowedPolicy authorizationClaims ==
            [ Observation (ClaimId "authenticated.submit-target") AnonymousActor
                Refuse Permit ])
    , ("ownership-policy defect is reported precisely",
        policyMismatches ownerDeniedPolicy authorizationClaims ==
            [ Observation (ClaimId "ownership.modify-own-target")
                OwnTargetWithoutAuthority Permit Refuse ])
    ]
  where
    anonymousAllowedPolicy = examplePolicy
        { observeAuthenticated = \SubmitTarget _ -> True }
    ownerDeniedPolicy = examplePolicy
        { observeOwnership = \ModifyOwnTarget _ _ _ -> False }

assertCheck :: Text -> Bool -> IO ()
assertCheck label True = putStrLn ("PASS: " <> Text.unpack label)
assertCheck label False = ioError (userError ("FAIL: " <> Text.unpack label))

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.

Migration safety. Adding a case-insensitive unique index to existing data with duplicates will fail. Resolve those duplicates first, then create the index across all identity rows before claiming database-enforced uniqueness. A partial index such as WHERE created_at > migration_date is not a substitute: it allows a new account to duplicate an older address excluded from the index. Keep any interim application check explicitly best-effort until the complete database constraint is active.

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

The standalone vocabulary supplies a validation result and a logging stub for the identity-boundary examples.

{-# 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 ()

Count case-insensitive matches before choosing the single-account lookup path; ambiguous results remain a deliberate denial.

-- | 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

The user fixture and injected count function illustrate uniqueness validation without making a database query.

-- 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
    ensurePostMethod
    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 = user }
            Right user -> do
                hashed <- hashPassword (get #password user)
                user <- user
                    |> set #passwordHash hashed
                    |> createRecord
                redirectTo UsersAction

Edit controller integration (IHP):

action UpdateUserAction { userId = userId } = do
    -- State-changing action: enforce POST-only
    ensurePostMethod
    user <- fetch userId
    user
        |> fill @'["email"]
        |> validateField #email isEmail
        |> validateFieldIO #email (isEmailUniqueCaseInsensitiveExcludingUser userId)
        >>= ifValid \case
            Left user -> render EditView { user = 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)
    ensurePostMethod

    let 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.

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.

Compatibility notice:

The atomic lockout implementation uses IHP Typed SQL and must compile against the receiving application's schema. The shown query assumes a users table with failed_login_attempts, locked_at, and id columns; adapt those names when the authentication record uses a different table or generated fields. The controller examples use IHP 1.6 response semantics and deliberately leave logging to the application's configured logger.

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. The authentication record needs a non-null integer failed-attempt field with a zero default and a nullable lock timestamp compatible with UTCTime. The snippets use generated fields failedLoginAttempts and lockedAt, backed by users.failed_login_attempts and users.locked_at. Adapt the table, columns, generated labels, and identifier type together when the receiving schema differs.

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 with IHP Typed SQL requires QuasiQuotes and import IHP.TypedSql (sqlExecTyped, typedSql):

recordFailedLogin :: (?modelContext :: ModelContext) => User -> IO ()
recordFailedLogin user = do
    let userId = get #id user
    now <- getCurrentTime
    _ <- sqlExecTyped [typedSql|
        UPDATE users
        SET failed_login_attempts = failed_login_attempts + 1,
            locked_at = CASE
                WHEN failed_login_attempts + 1 >= ${maxFailedLoginAttempts} THEN ${now}
                ELSE locked_at
            END
        WHERE id = ${userId}
    |]
    pure ()

${...} expressions remain prepared-statement parameters; do not replace them with text interpolation. The single UPDATE preserves the atomic increment and sets the lock timestamp on the attempt that reaches the threshold.

Reset after successful login through generated record fields:

resetLoginAttempts :: (?modelContext :: ModelContext) => User -> IO User
resetLoginAttempts user =
    user
        |> set #failedLoginAttempts 0
        |> set #lockedAt Nothing
        |> updateRecord

Use the returned record if subsequent logic needs the reset state. The reset belongs only on the successful-login path.

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

genericLoginFailure
    :: ( ?request :: Request
       , ?respond :: Respond
       )
    => IO ResponseReceived
genericLoginFailure = do
    setErrorMessage "Invalid credentials."
    redirectTo NewSessionAction

Core reusable pattern infrastructure

Name the failure threshold and lockout duration independently of the authentication record.

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

import Prelude
import Data.Text (Text)
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

Project the optional lock timestamp through a small field-access seam and compare it with the current time.

-- | 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

A minimal user fixture supplies the timestamp needed to render an example lockout status.

-- 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 -> Text
exampleCheck user now =
    if isUserLockedOut user now
        then "Account locked"
        else "Account active"

Usage examples

Schema adaptation checklist:

• add a non-null integer failed-attempt column with default 0 to the receiving authentication table;
• add a nullable lock timestamp whose generated Haskell field is compatible with Maybe UTCTime;
• regenerate models so the reset field labels match the schema;
• adapt and compile the Typed SQL table, column, and identifier names against that schema.

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

action CreateSessionAction = do
    -- State-changing action: enforce POST-only before any reads or mutations.
    ensurePostMethod

    let 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: record details through the configured logger if
            -- needed, then return the generic failure response.
            -- Optional but recommended: global/email-based throttle here.
            genericLoginFailure
        (Just u, _) | isUserLockedOut u now ->
            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 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 u'
                    login u'
                    -- Replace with the application's configured post-login path.
                    redirectToPathSeeOther "/"
        (Just u, _) -> do
            _ <- recordFailedLogin u
            genericLoginFailure

Note: genericLoginFailure returns ResponseReceived, and each failure branch returns that response as its final expression. There is no fall-through.

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.

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 and invalidate the token in one atomic write.
6. Report success only after that write commits.

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.

Bearer-secret boundary.

Treat the out-of-band token as a bearer secret: whoever has the URL can perform the guarded operation until the token expires or is consumed. Put that token only in the actual consume URL (for example, reset-password or confirm-email). Do not copy the same token into pending, status, resend, or "check your email" URLs.

A resend action needs its own boundary mechanism. Choose one deliberately:

• session-bound pending state,
• a separate resend token with its own expiry and semantics,
• or server-side pending state that is handled generically and non-enumerably.

A non-secret pending identifier is not a credential. It must not by itself prove requester authority or authorize resend. If a pending identifier appears in a request, pair it with session binding or a resend-specific secret, or make the response generic/non-enumerating and enforce abuse controls before any mail is sent.

Do not use the confirmation/consume token as the resend credential.

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.

Resource-spending actions.

A valid token, valid session, or valid pending state proves eligibility; it is not an abuse boundary. Actions that send email, call providers, create invites, or spend other external resources need a separate replay/cooldown/rate-limit control, or an explicit documented risk acceptance. This applies even when the resend request is legitimate.

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.

Consume atomically.

Hash the validated password before taking a database row lock. Then perform one conditional UPDATE that matches the account id, presented token, and current expiry window while changing the password and clearing both token fields. Only one affected row means success; zero means the token expired, was replaced, or was already consumed. A prior Haskell validity check is useful for early rejection but does not authorize an unconditional updateRecord later.

PostgreSQL rechecks the UPDATE predicate after waiting for a concurrent writer under Read Committed isolation. At stronger isolation, handle a serialization failure by retrying the whole operation and checking its result again. Never turn a failed consume into success. The password change and token clear must commit together; a transaction around an earlier unlocked read is insufficient.

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

Pending and resend routes must not reuse that bearer token:

data SessionsController
    = ...
    | PendingConfirmationAction     -- ^ GET: no confirmation token in URL
    | ResendConfirmationAction      -- ^ POST: session/pending/resend boundary

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
    ensurePostMethod

    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 = userId, token = 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 = userId, token = resetToken }
                else redirectWithError

The receiving application implements the atomic consume with IHP Typed SQL (import IHP.TypedSql (sqlExecTyped, typedSql) and QuasiQuotes). This example assumes the generated User maps to users with the shown snake-case columns; compile the query against the receiving schema. sqlExecTyped returns an Int64 affected-row count. The database clock checks expiry at statement start.

consumePasswordReset
    :: (?modelContext :: ModelContext)
    => Id User -> PasswordResetToken -> Text -> IO Bool
consumePasswordReset userId resetToken hashed = do
    let presented = unwrapPasswordResetToken resetToken
        maxAgeSeconds = realToFrac tokenMaxAge :: Double
    changed <- sqlExecTyped [typedSql|
        UPDATE users
        SET password_hash = ${hashed},
            password_reset_token = NULL,
            password_reset_token_created_at = NULL
        WHERE id = ${userId}
          AND password_reset_token = ${presented}
          AND password_reset_token_created_at <= statement_timestamp()
          AND password_reset_token_created_at >
              statement_timestamp() - (${maxAgeSeconds} * INTERVAL '1 second')
    |]
    case changed of
        0 -> pure False
        1 -> pure True
        _ -> ioError (userError "reset consume changed more than one account")

Update action (verify early, hash, then atomically consume and update):

action UpdatePasswordAction { userId = userId, token = token } = do
    ensurePostMethod

    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
                earlyReturn redirectWithError

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

            hashed <- hashPassword password
            consumed <- consumePasswordReset userId resetToken hashed
            unless consumed do
                earlyReturn redirectWithError

            setSuccessMessage "Password updated."
            redirectTo NewSessionAction

Core reusable pattern infrastructure

The token wrapper and account fixture expose the lifecycle fields used by the pure validation and invalidation examples.

{-# 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.
-- Persist this clear together with the guarded operation in the atomic write.
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)

A matching token within the expiry window passes validation.

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

A different token value fails against the same account and timestamp.

-- | 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. These pure examples do not establish a database concurrency guarantee. The host must compile the Typed SQL adapter against its schema and prove that two concurrent consumes of one token yield exactly one successful password update. Also cover expiry, replacement, replay, and rollback: rejected attempts must change neither the password nor the current token.

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 request and response boundary. If you give the helper an explicit signature, include the exact constraints:

ensureExternalProviderAutocompleteAllowed
    :: ( ?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
    renderExternalProviderComponent (param "query")

IHP gate shape:

ensureExternalProviderAutocompleteAllowed
    :: ( ?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

Represent endpoint requirements, observed request properties, and gate failures without performing provider IO.

{-# 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.

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

The query policy records the minimum useful length and the maximum outgoing length chosen by the provider boundary.

{-# 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.

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.

Provider unavailability does not establish that a remote mutation had no effect. Use RemoteWriteOutcome when a write caller must distinguish confirmed success, contractual no-effect rejection, and unknown outcome. This result type alone is not evidence that retrying a write is safe.

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 response mapping. A component may render the result state, but the controller selects and sends the HTTP response:

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

The result type preserves successful payloads separately from disabled, timed-out, or failed integrations.

{-# 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)