Favorite
Table of contents
Summary
Favorite lets a person mark an item so they can find it again later: a product, a recipe, an article, anything the business shows them. On a screen it is a heart: one tap fills it, the next tap empties it. A person’s favorites are that person’s own list, and an item is on the list once or not at all. Emptying a heart does not throw the favorite away: it keeps the moment it was first marked, so filling the heart again puts the item back exactly where it was in the list the atom answers, and a slip of the finger costs one tap. The same tap arriving twice changes nothing the second time. A favorite stays on the list even when the item is discontinued or taken down, because the person saved it and should see what became of it. There is no limit on how many a person may keep. Whether an item is in stock, who is signed in, sharing a list with someone else, and counting how many people like an item each belong to another pattern, which is why one favorite serves a shop, a recipe site and a library alike.
Intent
WHY
A person browsing more than they can use today wants to come back to some of it, and the shape recurs wherever a business shows people items: a heart on a product, a star on a recipe, a bookmark on an article. This atom is that and nothing more. Two decisions carry the weight. Marking and unmarking are two requests, each safe to repeat, so a double tap or a slow connection never undoes what the person meant; the screen sends whichever fits the heart it is showing. And unmarking keeps the favorite with the moment it was first marked, so marking it again restores it where it stood; the list the atom answers never reshuffles because of a slip, and how a page shows that list is the page’s (Non-goal 6). What the item is, whether it can still be had, and who may look are other patterns’ questions, and declining them is what lets one favorite serve products, recipes and articles alike.
Structure
Identity model
Identity 1: The atom MUST identify a favorite by the favorite's pair.
Identity 2: The atom MUST NOT normalize a person reference.
Identity 3: The atom MUST compare two person references codepoint for codepoint.
Identity 4: The atom MUST NOT normalize an item reference.
Identity 5: The atom MUST compare two item references codepoint for codepoint.
Term favorite: one person’s mark on one item, kept from the first mark on — a Favorite.
Term pair: the person reference and the item reference a favorite carries, or a call names.
Term person reference: the string naming the person a favorite belongs to, in the deployment’s own scheme — a Person Reference; the atom reads nothing in it.
Term item reference: the string naming the item a favorite is for, such as a product, a recipe or an article, in the deployment’s own scheme — an Item Reference; the atom reads nothing in it.
Term string cap: the bound on a person reference’s length and on an item reference’s length in Unicode code points; 1,024 code points where a deployment declares none.
Term seam: the atom’s I/O boundary as the section titled Logic Confinement Principle in execution-contract.md declares it; the host injects the clock reading, now, at the seam.
NOTE: Capability requirement 4 and Capability requirement 5 are the atom’s own rule for the canonical form of each reference, which stands in place of Execution Contract Logic confinement 13 (as that rule’s last sentence allows a specification that gives the canonical form another owner), so each person reference and each item reference is recorded as the call carries it (Execution Contract Input 4; Identity 2 through 5).
State
State 1: EVERY favorite MUST carry person reference, item reference, first marked instant and status.
State 2: EVERY favorite MUST stand in EXACTLY ONE OF marked, unmarked.
State 3: The atom MUST NOT remove a favorite.
Term first marked instant: the instant of the first Mark call that recorded a favorite — the First Marked Instant; set once, never changed.
Term status: where a favorite stands, marked or unmarked — the Status.
Term marked: the status of a favorite the person keeps — Marked; the heart is filled.
Term unmarked: the status of a favorite the person has let go — Unmarked; the heart is empty, and the favorite keeps its first marked instant.
Capability requirement
Capability requirement 1: The deployment MUST supply the database PER Execution Contract Database 1 through 7, Execution Contract Read 1 through 6, Execution Contract Refusal 1, Execution Contract Input 1 and Execution Contract Query 5.
Capability requirement 2: The deployment MUST supply now at the seam PER Execution Contract Logic confinement 11.
Capability requirement 3: The deployment MAY declare the string cap PER Execution Contract Input 2 and Execution Contract Logic confinement 17.
Capability requirement 4: The deployment MUST NOT normalize a person reference at the seam.
Capability requirement 5: The deployment MUST NOT normalize an item reference at the seam.
Operations
mark(person_reference, item_reference)
answers ok
refuses invalid-person-reference | invalid-item-reference | storage-failure
unmark(person_reference, item_reference)
answers ok
refuses invalid-person-reference | invalid-item-reference | storage-failure
look_up(person_reference, item_reference)
answers marked | unmarked
list(person_reference)
answers favorites(item_reference, first_marked_instant)
Operation 1: IF the person reference EQUALS blank OR the person reference EXCEEDS the string cap THEN a writing action MUST answer invalid-person-reference.
Operation 2: IF the item reference EQUALS blank OR the item reference EXCEEDS the string cap THEN a writing action MUST answer invalid-item-reference.
Operation 3: IF no favorite EXISTS for the pair THEN [Mark] MUST record EXACTLY ONE favorite carrying the person reference AND the item reference of the call.
Operation 4: IF no favorite EXISTS for the pair THEN [Mark] MUST stamp first marked instant from the injected now.
Operation 5: IF no favorite EXISTS for the pair THEN [Mark] MUST stand the favorite in marked.
Operation 6: IF the favorite's status EQUALS unmarked THEN [Mark] MUST stand the favorite in marked.
Operation 7: IF the favorite's status EQUALS marked THEN [Mark] MUST NOT write.
Operation 8: [Mark] MUST answer ok.
Operation 9: IF the favorite's status EQUALS marked THEN [Unmark] MUST stand the favorite in unmarked.
Operation 10: IF the favorite's status EQUALS unmarked THEN [Unmark] MUST NOT write.
Operation 11: IF no favorite EXISTS for the pair THEN [Unmark] MUST NOT write.
Operation 12: [Unmark] MUST answer ok.
Operation 13: [Look Up] MUST answer EXACTLY ONE OF marked, unmarked.
Operation 14: [Look Up] MUST answer marked ONLY IF a marked favorite EXISTS for the pair.
Operation 15: [Look Up] MUST NOT write.
Operation 16: [List] MUST answer EVERY marked favorite carrying the person reference.
Operation 17: [List] MUST answer a favorite's item reference AND first marked instant.
Operation 18: [List] MUST answer an empty list for a person reference no marked favorite carries.
Operation 19: [List] MUST NOT write.
Operation 20: IF the person reference is malformed THEN a writing action MUST answer invalid-person-reference (Execution Contract Input 1).
Operation 21: IF the item reference is malformed THEN a writing action MUST answer invalid-item-reference (Execution Contract Input 1).
Operation 22: IF the person reference is malformed OR the person reference EQUALS blank OR the person reference EXCEEDS the string cap THEN [Look Up] MUST answer unmarked (Execution Contract Query 5).
Operation 23: IF the item reference is malformed OR the item reference EQUALS blank OR the item reference EXCEEDS the string cap THEN [Look Up] MUST answer unmarked (Execution Contract Query 5).
Operation 24: IF the person reference is malformed OR the person reference EQUALS blank OR the person reference EXCEEDS the string cap THEN [List] MUST answer an empty list (Execution Contract Query 5).
Operation 25: [List] MUST answer favorites by first marked instant, earliest first, then by item reference (Execution Contract Read 5, Execution Contract Logic confinement 10).
The case space, and the rule that owns each case:
| Call | Case | Answer | Effect on the favorites |
|---|---|---|---|
| Mark | both references valid, no favorite for the pair, database accepts | ok | one favorite lands, marked, its first marked instant now (Operation 3 through 5, Invariant 1.1) |
| Mark | both references valid, the favorite stands unmarked | ok | the favorite stands marked; its first marked instant, person reference and item reference stand (Operation 6, Invariant 2.1, Invariant 2.2, Invariant 2.3) |
| Mark | both references valid, the favorite stands marked | ok | none, no write (Operation 7) |
| Unmark | both references valid, the favorite stands marked | ok | the favorite stands unmarked; its person reference and item reference stand; nothing is removed (Operation 9, State 3, Invariant 2.2, Invariant 2.3) |
| Unmark | both references valid, the favorite stands unmarked or no favorite for the pair | ok | none, no write (Operation 10, Operation 11) |
| a writing action | person reference blank, over the string cap, or not a string | Invalid Person Reference | none (Operation 1, Operation 20) |
| a writing action | item reference blank, over the string cap, or not a string | Invalid Item Reference | none (Operation 2, Operation 21) |
| Look Up | a marked favorite for the pair | marked | none (Operation 14, Operation 15) |
| Look Up | an unmarked favorite, or none, for the pair | unmarked | none (Operation 13, Operation 15) |
| Look Up | a person reference or an item reference blank, over the string cap, or not a string | unmarked | none (Operation 22, Operation 23) |
| List | the person keeps marked favorites | each one’s item reference and first marked instant, earliest first, then by item reference | none (Operation 16, Operation 17, Operation 19, Operation 25) |
| List | the person keeps none, or the person reference is blank, over the string cap, or not a string | an empty list | none (Operation 18, Operation 24) |
| any writing call | database refuses the write | Storage Failure | none (Execution Contract Read 4) |
| any call | its read of the database fails | state-unavailable |
none (Execution Contract Read 1, Execution Contract Read 3) |
| any call | more than one refusal applies | the refusal listed first on the action’s refuses line | none (Execution Contract Refusal 1) |
Invariants
- Invariant 1 — An item is a person’s favorite once or not at all.
Invariant 1.1: Two favorites MUST NOT share a pair. - Invariant 2 — A favorite never moves.
Invariant 2.1: The atom MUST NOT change a favorite's first marked instant. Invariant 2.2: The atom MUST NOT change a favorite's person reference. Invariant 2.3: The atom MUST NOT change a favorite's item reference.
Examples
The same pattern in two domains, then the rejection paths.
Online store
A shopper, ana, taps the heart on a blue kettle: mark("ana", "kettle-blue") answers ok, and the favorite’s first marked instant is that moment, 9:14 on Monday. She marks a teapot on Tuesday. Her favorites page asks list("ana") and is answered the kettle, then the teapot, each with its first marked instant, and the page, which sets its own order (Non-goal 6), shows the teapot above the kettle. On Wednesday she taps the kettle’s heart by mistake: unmark("ana", "kettle-blue") answers ok, and the kettle leaves what list("ana") answers, while the shop still shows the kettle with an empty heart. She taps it again: mark("ana", "kettle-blue") answers ok, and the kettle is marked with the first marked instant it always had, 9:14 on Monday, so list("ana") answers it first again. Nothing moved. A week later the shop discontinues the kettle; list("ana") still answers it, and the page shows it as discontinued from the shop’s own catalog.
Recipe site
A cook, r7, stars a lentil soup: mark("r7", "recipe-lentil-soup") answers ok. The page checks the star for each recipe it shows: look_up("r7", "recipe-lentil-soup") answers marked, and look_up("r7", "recipe-flatbread") answers unmarked, since r7 never marked the flatbread. A slow connection sends the same star twice; the second mark("r7", "recipe-lentil-soup") answers ok and writes nothing.
Rejection paths
mark("", "kettle-blue")— rejected as Invalid Person Reference: the reference is blank.mark("ana", " ")— rejected as Invalid Item Reference: the reference is blank.mark("", "")— rejected as Invalid Person Reference: two refusals apply, and the one listed first on Mark’s refuses line answers (Execution Contract Refusal 1).mark(42, "kettle-blue")— rejected as Invalid Person Reference: the reference is not a string (Operation 20).unmark("ana", "Kettle-Blue")— answers ok and writes nothing: two item references are compared codepoint for codepoint, and neither the atom nor the deployment normalizes one, soanaholds no favorite for that one (Identity 5, Capability requirement 5, Operation 11).look_up("", "kettle-blue")— answers unmarked: the reference is blank, and no favorite carries a blank reference (Operation 22).
This covers every refusal but Storage Failure, which answers when the database refuses a write.
Generation acceptance
Acceptable when the checks below are provable to an external auditor from the favorites the database holds, with their earlier versions (Execution Contract Database 5, Execution Contract Generation acceptance 1). The atom is not regulated and carries no adversarial scenarios.
Conformance checks
Check 1.1: An auditor MUST find EVERY favorite carrying person reference, item reference, first marked instant AND status (State 1).
Check 1.2: An auditor MUST find EVERY favorite standing in EXACTLY ONE OF marked, unmarked (State 2).
Check 2.1: An auditor MUST find no two favorites sharing a pair (Invariant 1.1).
Check 3.1: An auditor MUST find EVERY version of a favorite carrying the first marked instant of the favorite's first version (Invariant 2.1).
Check 3.2: An auditor MUST find EVERY version of a favorite carrying the person reference of the favorite's first version (Invariant 2.2).
Check 3.3: An auditor MUST find EVERY version of a favorite carrying the item reference of the favorite's first version (Invariant 2.3).
Term version: a record as it stood at the commit that wrote it, which Execution Contract Database 5 keeps readable after the record changes and Execution Contract Generation acceptance 1 has a check read.
NOTE: EVERY check names the rule the check tests.
External checks
External check 1: An auditor needing an item reference confirmed as naming a real item MUST read the deployment's catalog (Non-goal 3).
Non-goals
Non-goal 1: The atom MUST NOT tell who may read a person's favorites.
Non-goal 2: The atom MUST NOT tell who may change a person's favorites.
Non-goal 3: The atom MUST NOT check an item reference against a catalog.
Non-goal 4: The atom MUST NOT hold an item's availability.
Non-goal 5: The atom MUST NOT share a person's favorites.
Non-goal 6: The atom MUST NOT order a person's favorites for display.
Non-goal 7: The atom MUST NOT count the persons marking an item.
Non-goal 8: The atom MUST NOT hold a save-for-later list.
NOTE: the owners — the composing pattern that knows the caller, such as one built on Session or Permissions (Non-goal 1, 2); Catalog (forthcoming) (Non-goal 3, 4; External check 1); Favorite Sharing (forthcoming) (Non-goal 5); the composing pattern that shows the list, in whatever order it sets (Non-goal 6); Reaction (forthcoming) (Non-goal 7); Save For Later (forthcoming) (Non-goal 8).
NOTE: watch the order an atom forbids — List’s answer comes in the order Operation 25 states, which stands in place of Execution Contract Read 5’s default order, and any other order a page shows is the composing pattern’s (Non-goal 6).
Where the atom breaks down: a list an item leaves when the person is done with it, which is save for later; a mark other people are meant to see and count, which is a reaction.
Edge cases
Concurrency
Two Mark calls for one pair are serialized (Execution Contract Database 2): the later reads the favorite the earlier recorded and writes nothing, so a person never holds two favorites for one item (Invariant 1.1). A Mark and an Unmark for one pair are serialized the same way, and the favorite stands where the later call left it.
Indeterminate outcome
A caller whose answer is lost may call again, and the repeat is a second call (Execution Contract Error model 1). A repeated Mark where the first landed writes nothing and answers ok; a repeated Unmark where the first landed writes nothing and answers ok. So a caller repeats either call freely, and a caller needing the truth asks Look Up.
An item that is no longer offered
The atom keeps a favorite whatever becomes of the item (State 3, Non-goal 4). The composing pattern that shows the list reads the item’s availability from the deployment’s catalog and shows it beside the favorite.
What undoes a write
Unmark undoes Mark and Mark undoes Unmark, and State 3 keeps the favorite either way, so no undo is owed beyond the pair (Execution Contract Undo 4).
Composition notes
Composition note 1: A composing pattern MUST own what this atom declines.
Composition note 2: A composing pattern MUST supply the person reference of the caller the composing pattern authenticated.
NOTE: composing patterns — none yet. Forthcoming: Catalog, Favorite Sharing.
Terms
Each [Term] marker above links to its term entry here; a term entry states what the concept is and its Kind.
Vocabulary
Term actors: the atom; the host; the deployment (also: a deployment); a composing pattern; the database; a favorite; a writing action; an auditor.
Term records: favorite — one person’s mark on one item, carrying person reference, item reference, first marked instant and status.
Term record verbs: identify, normalize, compare, carry, stand, remove, supply, declare, record, stamp, answer, write, change, share, find, read, tell, check, hold, order, count, own, refuse.
| Term value sets: writing action is declared above and cited here (GRACE-lang Closed vocabulary 15); status — marked | unmarked; action rejection — invalid-person-reference | invalid-item-reference | storage-failure. |
Term bounds: string cap (the bound on a person reference’s length and on an item reference’s length in Unicode code points, 1,024 where a deployment declares none).
Term cadences: empty.
Term qualifiers: migrated — drafted in GRACE lang v0.73 (2026-11-14) through the Grace connector.
Term terms: favorite, favorites, pair, person reference, item reference, string cap, seam, first marked instant, status, marked, unmarked, writing action, version.
Mark
Marks an item as a person’s favorite: records the Favorite where the pair has none, stamping its First Marked Instant, or stands an Unmarked favorite back in Marked, leaving its first marked instant as it was. A favorite already marked is left as it is. Answers ok.
Kind: Operation
Unmark
Lets a favorite go: stands a Marked favorite in Unmarked and removes nothing. A favorite already unmarked, or a pair with no favorite, is left as it is. Answers ok.
Kind: Operation
Look Up
Answers whether one item is a person’s favorite now, Marked or Unmarked, and changes nothing; a pair with no favorite answers unmarked.
Kind: Operation
List
Answers every Marked favorite of one person, each with its Item Reference and First Marked Instant, and changes nothing; an empty list where the person keeps none.
Kind: Operation
Favorite
One person’s mark on one item: recorded by the first Mark, stood in Unmarked by Unmark and back in Marked by Mark; never removed by the atom.
Kind: Type
Person Reference
Names the person a favorite belongs to, in the deployment’s own scheme. Stored as supplied and compared codepoint for codepoint; the atom reads nothing in it, and whether the caller is that person is the composing pattern’s question.
Kind: Field Field of: Favorite Projection: person_reference
Item Reference
Names the item a favorite is for, in the deployment’s own scheme. Stored as supplied and compared codepoint for codepoint; the atom reads nothing in it, and whether it names a real item, and whether that item can still be had, are a catalog’s questions.
Kind: Field Field of: Favorite Projection: item_reference
First Marked Instant
The instant of the Mark call that recorded the favorite, stamped from the injected now; never changed, so a favorite unmarked and marked again keeps it.
Kind: Field Field of: Favorite Projection: first_marked_instant
Status
Where a favorite stands: Marked or Unmarked.
Kind: Field Field of: Favorite Projection: status
Marked
The status of a favorite the person keeps, and Look Up’s answer for one.
Kind: Member Member of: the status Projection: marked
Unmarked
The status of a favorite the person has let go, and Look Up’s answer for one and for a pair with no favorite.
Kind: Member Member of: the status Projection: unmarked
Invalid Person Reference
The refusal of a blank Person Reference, one over the string cap, or one that is not a string, on Mark or Unmark (Operation 1, Operation 20).
Kind: Member Member of: the action rejection Role: Outcome Projection: invalid-person-reference
Invalid Item Reference
The refusal of a blank Item Reference, one over the string cap, or one that is not a string, on Mark or Unmark (Operation 2, Operation 21).
Kind: Member Member of: the action rejection Role: Outcome Projection: invalid-item-reference
Storage Failure
The refusal Mark or Unmark answers when the database refuses its write after every precondition passes: the Execution Contract’s Step 3 failure.
Kind: Member Member of: the action rejection Role: Outcome Projection: storage-failure
Standards references
Favorite is a primitive with no regulatory anchor. It inherits from:
- Daniel Jackson, The Essence of Software — the concept as a freestanding, composable unit of software design. The concept was raised in the Concept Design Community forum’s concept catalog, where a favorite is a user saving an item for their own review later.
Status
done — 2026-11-17 — see the Ledger.
Ledger
status: done — 2026-11-17
formal: verified — favorite.als + 7 twins (the static data model: State 1 and 2, Identity 3 and 5, Operation 3, 4 and 5, Invariant 1.1 checked on every version a sequence of admitted calls leaves, Identity 1 caught by the Invariant 1.1 check, Identity 2 and 4 by the Operation 3 check); favorite.tla + 24 twins (across steps: State 3, Invariant 2.1 through 2.3, Operation 1 through 3 and 6 through 25, the other half of Operation 14 and 16 read from the terms Look Up and List); on the maintainer's ruling of 2026-11-09 (both models; only the writing vetoes one), neither vetoed, 2026-11-14
last gate: 2026-11-17 — Final Critique 5, a delta round, frozen at b2e418cf — foundational count 0 after the blind second triage, clean, one sample (Linus's one foundational report, that Input 2 bars a zero string cap only on a deployment's declaration and not on a specification's default, placed refining, Kind B, by both triages: its two implementations serve different specifications and Favorite's default is 1,024; refining 2 on the Execution Contract; all three cured by held replacements to the Execution Contract, none by the page); 2026-11-17 — Final Critique 4, a delta round, frozen at f7caec5a — foundational count 1 after the blind second triage, cured by a held cure, not clean, one sample (Linus's three foundational reports, all on the Execution Contract and reached through Capability requirement 3: F1, that Logic confinement 17 names no start for an instance with no scheduled leg, and F3, that Input 2 counts the cap on two bases, both refuted by both triages, F3 since Capability requirement 4 and 5 and the NOTE at page line 57 replace Logic confinement 13 here and the carried value finds the record; F2, that Input 2's start-time floor and Logic confinement 17 permit an unplanned restart to start the instance on a declared cap a held value exceeds, which the blind second triage placed foundational, Kind A, cured by two held replacements to the Execution Contract; refining 1 and rhetorical 1 not cured); 2026-11-17 — Final Critique 3, a delta round, frozen at d9b6ee5a — foundational count 1, cured by a held cure, not clean, one sample
open: none
Decisions
Decisions are kept in the pattern’s history, one dated entry for each turn the pattern took; everything smaller lives in the commit that made it: git log -- atoms/favorite.md.
NOTE: End of Favorite.