Construct the dependency graph in one place

tags := tagging.NewRepository(s)
targets := tagging.NewRegistry()
auditWriter := audit.NewWriter(s)
pipeline := middleware.NewPipeline(middleware.PipelineConfig{
    Store:          s,
    Dispatcher:     dispatcher.New(s, tags),
    Metrics:        telemetry.FromContext(ctx),
    RecordActivity: auditWriter.RecordActivity,
})
ingredientsModule := ingredients.NewModule(
    ctx, s, tags, targets, pipeline,
)

Code: app/app.go

Copy operation state, retain transaction identity

func (c *Context) forOperation() *Context {
    derived := *c
    derived.Context = c.Context
    derived.events = make([]any, 0, 4)
    derived.activity = nil
    return &derived
}

Code: pkg/middleware/context.go

The ID is a defined type, with generated behavior

type DrinkID cedar.EntityUID

func ParseDrinkID(id string) (DrinkID, error) {
    uid, err := parseID(TypeDrink, PrefixDrink, id)
    return DrinkID(uid), err
}
func (id DrinkID) EntityUID() cedar.EntityUID {
    return cedar.EntityUID(id)
}
func (id DrinkID) String() string {
    return string(cedar.EntityUID(id).ID)
}

Code: app/kernel/entity/entities_gen.go

A closed variant still needs runtime validation

// Selected Amount methods.
type Amount interface {
    Unit() Unit
    Value() float64
    Add(Amount) (Amount, error)
    Convert(Unit) (Amount, error)
    isAmount()
}

// Executable example.
volume := measurement.MustAmount(30, measurement.UnitMl)
pieces := measurement.MustAmount(1, measurement.UnitPiece)
_, err := volume.Add(pieces)
// Invalid: "unit mismatch: ml vs piece"

Code: app/kernel/measurement/amount.go

Represent physical quantity separately from display units

type Volume struct { ml float64 }
type Quantity struct {
    Volume Volume
    Unit   Unit // preferred display unit
}

// Convert retains the same Volume; it changes the display unit.
q := measurement.MustQuantity(1, measurement.UnitOz)
ml, _ := q.Convert(measurement.UnitMl)
q.Value()  // 1
ml.Value() // 29.5735

// Pieces, dashes, and splashes cannot convert to liquid volume.

Code: app/kernel/measurement/quantity.go

Two types separate classification from payload

// Shared payload (error.go).
type Error struct {
    kind        Kind
    detail      string
    userMessage string
    cause       error
}

// Generated wrapper (errors_gen.go).
type InternalError struct { err *Error }

func Internalf(format string, args ...any) *InternalError {
    return &InternalError{err: newErrorf(KindInternal, format, args...)}
}

Code: pkg/errors/errors_gen.go

Build one failure and let the real evaluator wrap it

// Injected failure; the evaluator and wrapping are real.
cause := errors.New("database is locked")
failure := errors.Internalf("load readiness: %w", cause).
    WithUserMessage("Readiness is temporarily unavailable")

_, err := actions.Evaluate(ctx, actions.Group{
    Permission: actions.Public(),
    Controls: []actions.Control{{ID: "publish",
        Conditions: []actions.Condition{
            func(context.Context) (bool, string, error) {
                return false, "", failure
            },
        },
    }},
})

Code: pkg/presentation/actions/actions.go

Read the complete error chain

Evaluate → evaluateGroup → evaluateControl → condition
                                               ↓
*fmt.wrapError
  actions: control "publish": condition 0:
    load readiness: database is locked
  └─ *fmt.wrapError
       condition 0: load readiness: database is locked
       └─ *errors.InternalError
            load readiness: database is locked
            └─ *errors.errorString
                 database is locked

Code: pkg/presentation/actions/actions.go

As reaches both the typed wrapper and shared payload

var typed *errors.InternalError
var payload *errors.Error

errors.As(err, &typed)   // true
errors.As(err, &payload) // true: generated As method
errors.Is(err, cause)    // true: same original cause
payload.Kind()          // KindInternal
payload.UserMessage()   // "Readiness is temporarily unavailable"

// The generated bridge, abbreviated:
if p, ok := target.(**Error); ok {
    *p = e.err
    return true
}

Code: pkg/errors/errors_gen.go

The same failure has different diagnostic and UI output

Diagnostic Error():
  actions: control "publish": condition 0:
  load readiness: database is locked

CLI: exit code 50
  Readiness is temporarily unavailable

TUI: style "error", original cause retained
  Readiness is temporarily unavailable

GUI: severity Error, original cause retained
  Readiness is temporarily unavailable

Without WithUserMessage:
  internal error

Code: pkg/errors/cli.go

The CLI makes error kinds observable

$ echo '{"name":"","category":"spirit","unit":"oz"}' |
    ./mixology ingredients create --stdin
name is required
$ echo $?
10

$ ./mixology ingredients create --category spirit --unit oz "London Dry Gin"
insert ingredient "London Dry Gin"
$ echo $?
40

$ ./deck-error-probe # injected Internal from the preceding example
Readiness is temporarily unavailable
$ echo $?
50

Captured process output · real CLI for Invalid / Conflict · injected Internal probe

Choose where to preserve, translate, or classify

// Current store mapping, selected branches.
if errors.IsConflict(err) || isUniqueConstraint(err) {
    return errors.Conflictf(format, args...)
}
return errors.Internalf(format+": %w", append(args, err)...)

// Adding context without changing a known kind:
return fmt.Errorf("publish menu: %w", err)

// Unknown errors have no automatic safe-message guarantee.
errors.ToCLIExit(errors.New("raw dependency detail"))
// exit 1, message "raw dependency detail"

Code: pkg/store/errors.go

The actual command chain is nested function calls

command: NewChain(
    SerializeTransaction(),
    Logging(),
    Metrics(config.Metrics),
    TrackActivity(config.Store, config.RecordActivity),
    UnitOfWork(config.Store),
    recordSuccessfulActivity(config.RecordActivity),
    DispatchEvents(config.Dispatcher),
)

Code: pkg/middleware/chains.go

Publish authorizes persisted state, then the result

func (m *Module) Publish(
    ctx *middleware.Context, menu *models.Menu,
) (*models.Menu, error) {
    return m.pipeline.LoadCommand(ctx, authz.ActionPublish,
        func(ctx *middleware.Context) (*models.Menu, error) {
            return m.queries.Get(ctx, menu.ID)
        },
        m.commands.Publish,
    )
}

Code: app/domains/menus/publish.go

Inject a late failure and inspect what persisted

// Selected recorder branches from the rollback test.
recordCalls++
if !activity.Success {
    return insertTransactionProbe(ctx, "failure-audit")
}
if err := insertTransactionProbe(ctx, "success-audit"); err != nil {
    return err
}
return errors.Internalf("audit unavailable")

// After the pipeline call that also inserted "business-write":
testutil.Equals(t, recordCalls, 2)
testutil.Equals(t, transactionProbeKinds(t, ctx, s),
    []string{"failure-audit"})

Code: pkg/middleware/command_tx_test.go

Store.Write and store.Write have different ownership

// Managed boundary: opens, commits, or rolls back a transaction.
err := s.Write(ctx, func(tx *store.Tx) error {
    // Return an error to reject the entire unit of work.
    return nil
})

// DAO helper: joins an existing transaction; never opens one.
func Write(ctx Context, f func(*Tx) error) error {
    tx, ok := ctx.Transaction()
    if !ok || tx == nil {
        return errors.Internalf("missing transaction")
    }
    return f(tx)
}

Code: pkg/store/access.go

A caller-owned transaction owns every nested outcome

application composition opens transaction T
  command A joins T
    business write + reactions + success activity
  command B joins T
    business write + reactions + success activity
  caller returns nil  → commit all of T
  caller returns err  → roll back all of T

If B fails:
  propagate the error; do not commit A's tentative success
  joined middleware does not open a separate failure-audit write

Code: pkg/middleware/track_activity.go

Serialize shared transactions, not whole application instances

func SerializeTransaction() Middleware {
    return func(ctx *Context, _ Operation, next Next) error {
        if tx, ok := ctx.Transaction(); ok && tx != nil {
            defer store.LockTransaction(tx)()
        }
        return next(ctx)
    }
}

// LockTransaction keys a sync.Mutex by *store.Tx.
// Separate transactions are coordinated by SQLite.

Code: pkg/middleware/transaction.go

An import can compile and still violate ownership

Importer: app/domains/drinks/surfaces/gui

Import drinks/internal/dao
  Go internal rule: allowed, importer is inside drinks/
  arch-lint: rejected, a surface is not an allowed consumer

Import ingredients/internal/dao
  Go internal rule: rejected, importer is outside ingredients/

Import drinks/surfaces/tui
  Go compiler: allowed
  arch-lint: rejected, GUI must not depend on TUI

Run: go tool arch-lint -config=.arch-lint.yaml

Code: .arch-lint.yaml

Generated registration depends on concrete source conventions

Event:   struct under an events directory
Handler: method under app/.../handlers

func (h *StockAdjusted) Handle(
    ctx *middleware.HandlerContext,
    e inventoryevents.StockAdjusted,
) error

func NewStockAdjusted(
    s *store.Store, tags tag.Repository,
) *StockAdjusted

go generate ./pkg/dispatcher

Code: pkg/dispatcher/README.md

A fixture must exercise the real commit boundary

f := testutil.NewFixture(t)
_, hasTx := f.OwnerContext().Transaction()
testutil.IsFalse(t, hasTx)

// Complete an order using 2 oz from 10 oz.
f.Orders.Complete(ctx, &ordersmodels.Order{ID: order.ID})
// stock == 8 oz

// Reuse ctx for an unrelated command.
f.Ingredients.Create(ctx, &ingredient)
// stock must still be 8 oz; old events must not replay.

Code: pkg/testutil/transaction_test.go

Identity enters through the operation context

principal := authn.Sommelier()
// Mixology::Actor::"sommelier"

ctx := authn.ToContext(context.Background(), principal)
// The application's session/fixture constructs middleware.Context.
// The pipeline reads middleware.Context.Principal().

// Current demo actors:
owner, manager, sommelier, bartender, anonymous

Code: pkg/authn/authn.go

Inspect the request and the entity separately

// Selected fields from AuthorizeWithEntity.
req := cedar.Request{
    Principal: principal,
    Action:    action,
    Resource:  resource.UID,
    Context:   cedar.NewRecord(nil),
}
entities := cedar.EntityMap{
    principal:    {/* UID; empty attributes, parents, tags */},
    resource.UID: resource,
}
decision, diagnostic := cedar.Authorize(ps, entities, req)

Code: pkg/authz/authorize.go

The schema defines what a policy can inspect

namespace Mixology {
    entity Actor enum [
        "owner", "manager", "sommelier", "bartender", "anonymous"
    ];
    entity Drink {
        Name: String,
        Category: String,
        Glass: String,
        Description: String
    } tags String;
}
namespace Mixology::Drink {
    action list, get, create, update, delete, tag, untag appliesTo {
        principal: Mixology::Actor,
        resource: Mixology::Drink,
        context: {}
    };
}

Code: app/domains/drinks/authz/schema.cedarschema

CedarEntity is security-sensitive mapping code

func (d Drink) CedarEntity() cedar.Entity {
    return drinkauthz.Drink{
        UID: d.ID.EntityUID(), Name: d.Name,
        Category: string(d.Category),
        Glass: string(d.Glass), Description: d.Description,
        Tags: d.Tags.Map(),
    }.CedarEntity()
}

Code: app/domains/drinks/models/drink.go

Read the actual sommelier management policy

permit(
    principal == Mixology::Actor::"sommelier",
    action in [
        Mixology::Drink::Action::"create",
        Mixology::Drink::Action::"update",
        Mixology::Drink::Action::"delete",
        Mixology::Drink::Action::"tag",
        Mixology::Drink::Action::"untag"
    ],
    resource is Mixology::Drink
) when {
    resource.Category == "wine"
};

Code: app/domains/drinks/authz/policies.cedar

A separate permit grants narrower, tag-based access

permit(
    principal == Mixology::Actor::"sommelier",
    action in [
        Mixology::Drink::Action::"list",
        Mixology::Drink::Action::"get"
    ],
    resource is Mixology::Drink
) when {
    resource.hasTag("audience") &&
    resource.getTag("audience") == "sommelier"
};

Code: app/domains/drinks/authz/policies.cedar

Permits compose; an applicable forbid overrides them

// Application-wide base.cedar:
permit(
    principal == Mixology::Actor::"owner", action, resource
);

// Audit domain, one of its explicit non-owner forbids:
forbid(
    principal == Mixology::Actor::"manager",
    action in [
        Mixology::AuditEntry::Action::"list",
        Mixology::AuditEntry::Action::"get"
    ],
    resource
);

Code: app/domains/audit/authz/policies.cedar

Mixology treats evaluator diagnostics as failure

decision, diagnostic := cedar.Authorize(ps, entities, req)
if len(diagnostic.Errors) > 0 {
    return errors.Internalf(
        "authz evaluation error: %s",
        diagnostic.Errors[0].Message,
    )
}
if decision == cedar.Deny {
    return errors.Permissionf(/* principal, action, resource */)
}
return nil

Cedar reference

The pipeline checks every action at both gates

// Inside authorizeCommandActions; declarations omitted.
for _, action := range actions {
    err := authz.AuthorizeWithEntity(
        ctx.Principal(), action, in.CedarEntity())
    if err != nil { return zero, err }
}

out, err := next(ctx, in)
if err != nil { return zero, err }

for _, action := range actions {
    err := authz.AuthorizeWithEntity(
        ctx.Principal(), action, out.CedarEntity())
    if err != nil { return zero, err }
}
return out, nil

Code: pkg/middleware/run.go

Drinks.Update checks three distinct resource states

LoadCommand
  load persisted drink in the transaction
  authorize update on PERSISTED state
  │
  └─ AuthorizeCommand around commands.Update
       authorize update on SUBMITTED proposal
       run commands.Update
       authorize update on ACTUAL result
  │
  authorize update on ACTUAL result
  dispatch events → record success → commit

Code: app/domains/drinks/update.go

Read the complete update facade

func (m *Module) Update(
    ctx *middleware.Context, drink *models.Drink,
) (*models.Drink, error) {
    authorizedUpdate := middleware.AuthorizeCommand(
        authz.ActionUpdate, m.commands.Update)
    return m.pipeline.LoadCommand(ctx, authz.ActionUpdate,
        func(ctx *middleware.Context) (*models.Drink, error) {
            return m.queries.Get(ctx, drink.ID)
        },
        func(
            ctx *middleware.Context, _ *models.Drink,
        ) (*models.Drink, error) {
            return authorizedUpdate(ctx, drink)
        },
    )
}

Code: app/domains/drinks/update.go

A forged category cannot authorize an existing target

Persisted target:  ID=drk-X, Category=cocktail
Submitted update: ID=drk-X, Category=wine
Principal:        sommelier
Action:           Drink::Action::"update"

If we authorize only the proposal:
  wine satisfies the sommelier policy

Current LoadCommand path:
  load drk-X → cocktail → Permission
  commands.Update never runs

Code: app/domains/drinks/update.go

Isolate the result gate with a real pipeline test

// TestLoadCommand_AuthorizesResultAfterHandle, excerpt.
handled := false
_, err := pipeline.LoadCommand(
    fix.ActorContext("sommelier"), drinksauthz.ActionUpdate,
    func(*middleware.Context) (testEntity, error) {
        return wine, nil
    },
    func(_ *middleware.Context, out testEntity) (testEntity, error) {
        handled = true
        out.Attributes["Category"] = cedar.String("beer")
        return out, nil
    },
)
testutil.ErrorIsPermission(t, err)
testutil.IsTrue(t, handled)

Code: pkg/middleware/command_tx_test.go

Result denial must undo work, not just hide output

// Probe handler inside LoadCommand, using the real store:
func(
    ctx *middleware.Context, out drinkauthz.Drink,
) (drinkauthz.Drink, error) {
    if err := store.Write(ctx, func(tx *store.Tx) error {
        return tx.Insert(&probe{Kind: "tentative-write"})
    }); err != nil {
        return out, err
    }
    ctx.AddEvent("tentative-event")
    out.Category = "beer"
    return out, nil
}

Code: pkg/middleware/uow.go

Follow result denial all the way out

Observed probe:
  handler ran                     true
  returned error kind             Permission
  persisted tentative-write rows  0
  dispatched tentative events     0
  successful activity callbacks   0
  failed activity callbacks       1

Result gate denies
  → DispatchEvents returns the error without dispatch
  → success activity is skipped
  → managed transaction rolls back
  → failure activity is attempted separately

Code: pkg/middleware/chains.go

Tag replacement can require several permissions

current: audience=sommelier, featured
desired: audience=bartender

replaceActions(current, desired):
  changed audience value → tag
  removed featured key   → untag

Before mutation: allow(tag, current) AND allow(untag, current)
After mutation:  allow(tag, result)  AND allow(untag, result)

No derived actions → Internal, handler does not run
No-op replacement → tag is still required

Code: app/domains/tagging/module.go

Walk an individual grant through the application

// Existing tag ABAC test; fixture setup omitted.
grant := tag.Tag{Key: "audience", Value: "sommelier"}

_, err := f.App.Tags.Upsert(sommelier, cocktail.EntityUID(), grant)
testutil.ErrorIsPermission(t, err) // cannot self-grant

_, err = f.App.Tags.Upsert(manager, cocktail.EntityUID(), grant)
testutil.Ok(t, err)
_, err = f.Drinks.Get(sommelier, cocktail.ID)
testutil.Ok(t, err)

_, err = f.App.Tags.Remove(manager, cocktail.EntityUID(), "audience")
testutil.Ok(t, err)
_, err = f.Drinks.Get(sommelier, cocktail.ID)
testutil.ErrorIsPermission(t, err)

Code: app/tag_abac_test.go

Permission denial is a branch in the paging loop

err = authz.AuthorizeWithEntity(
    c.Principal(), action, item.CedarEntity(),
)
switch {
case err == nil:
    if len(page.Items) == pageRequest.Limit {
        page.Next = cursor(page.Items[len(page.Items)-1])
        return nil
    }
    page.Items = append(page.Items, item)
case errors.IsPermission(err):
    continue
default:
    return err
}

Code: pkg/middleware/run.go

Counts reuse the authorized list, not raw SQL

func (m *Module) Count(
    ctx *middleware.Context, req ListRequest,
) (int, error) {
    return paging.Count(func(
        cursor paging.Cursor,
    ) (paging.Page[*models.Drink], error) {
        req.Cursor = cursor
        req.Limit = paging.DefaultLimit
        return m.List(ctx, req)
    })
}

Code: app/domains/drinks/list.go

A real policy separates reading from management

permit(
    principal,
    action in [
        Mixology::Menu::Action::"list",
        Mixology::Menu::Action::"get"
    ],
    resource
);

// The manager permit includes these actions, among others:
principal == Mixology::Actor::"manager"
action in [Mixology::Menu::Action::"publish",
           Mixology::Menu::Action::"readiness"]
resource is Mixology::Menu

Code: app/domains/menus/authz/policies.cedar

A Publish control carries its own permission

// Selected declaration from Menus' action projector.
Permission: permission(menusauthz.ActionUpdate, resource),
Controls: []actions.Control{
    {
        ID:         ControlPublish,
        Permission: permission(menusauthz.ActionPublish, resource),
        Conditions: []actions.Condition{publishCondition(selected)},
    },
}

// Control permission replaces the inherited default.
// Permission runs first; conditions run only when authorized.

Code: app/domains/menus/actions.go

One denied command, two observability decisions

// Logging: expected denial is informational.
case errors.IsPermission(err):
    logger.Info(string(op.Kind)+" denied",
        slog.Duration("duration", duration), log.Err(err))

// Metrics: every non-nil result is counted as an error.
if err != nil {
    mc.commandTotal.Inc(actionLabel, "error")
    mc.commandErrors.Inc(actionLabel)
}

Code: pkg/middleware/logging.go

Measure the operation's final outcome, including unwind

command body returns nil
  → result authorization permits
  → event reaction succeeds
  → successful activity recorder fails
  → transaction rolls back
  → Metrics records error, not success
  → Logging emits "command failed"

Duration includes everything inside those wrappers.
Caller transaction lock wait happens outside both wrappers.

Code: pkg/middleware/chains.go

Test metric meaning without a running exporter

memory := telemetry.Memory()
// Supply memory as PipelineConfig.Metrics.

// After a denied or otherwise failed Drink update:
memory.CounterValue(
    telemetry.MetricCommandTotal, "Drink.update", "error",
) // 1
memory.CounterValue(
    telemetry.MetricCommandErrors, "Drink.update",
) // 1

// The equivalent successful call uses result="success".

Code: pkg/middleware/metrics.go

The activity stores explanations, not a replay log

// Selected fields; actor, action, resource and times omitted.
type Activity struct {
    WorkflowID   string
    Touches      []cedar.EntityUID
    Participants []cedar.EntityUID
    Effects      []Effect
    Success      bool
    Error        string
}
type Effect struct {
    Kind     string
    Resource cedar.EntityUID
    Changes  []Change // Field, Before, After are strings.
}

Code: pkg/middleware/events/activity.go

A composed failure has one outer owner

// RunWorkflow control flow, success/failure construction omitted.
state := &workflowState{id: ksuid.New().String()}
derived := *ctx
derived.workflow = state
err := s.Write(ctx, func(tx *store.Tx) error {
    return run(derived.WithTransaction(tx))
})
// On failure, aggregate child touches, participants and effects.
// Complete a failed Mixology::Workflow::Action activity.
// Record it in a new write after the business rollback.
return errors.Join(err, auditErr)

Code: pkg/middleware/workflow.go

Generated dispatch constructs event-local receivers

IngredientDeleted case (error branches omitted here):

construct drinksHandler, inventoryHandler,
          menusHandler, ordersHandler

drinksHandler.Handling(hctx, e)
inventoryHandler.Handling(hctx, e)
menusHandler.Handling(hctx, e)
────────────────────────────────── preparation barrier
drinksHandler.Handle(hctx, e)
inventoryHandler.Handle(hctx, e)
menusHandler.Handle(hctx, e)
ordersHandler.Handle(hctx, e)

Code: pkg/dispatcher/dispatcher_gen.go

Prepare the resulting state, not just a list of IDs

OrderPlaced.Handling:
  capture stock; project the added reservations
  calculate resulting availability for active menus
  retain only changed Menu values

IngredientDeleted.Handling:
  override retired stock as unavailable for future service
  project recipes with Drink.RetireIngredient (pure rule)
  calculate resulting Menu values

Handle:
  persist prepared values; do not re-read sibling state

Code: app/domains/menus/handlers/prepared.go

Dispatch snapshots the event list and wraps failures

if err := next(ctx); err != nil {
    return err
}
if d == nil {
    return nil
}
events := slices.Clone(ctx.Events())
for _, event := range events {
    if err := d.Dispatch(ctx, event); err != nil {
        return errors.Internalf("dispatch event %T: %w", event, err)
    }
}
return nil

Code: pkg/middleware/dispatch_events.go

The preparation barrier is per event, not per command

command queues E1, then E2
  E1: construct fresh receivers
      all Handling calls
      all Handle calls
  E2: construct fresh receivers
      all Handling calls
      all Handle calls
  record successful activity
  commit

A failure stops remaining delivery and rolls back the operation.

Code: pkg/middleware/dispatch_events.go

Unhandled events and durable delivery are different contracts

Known event, no matching reaction → debug log; success
Unknown event type               → debug log; success
Handler error                    → remaining delivery stops

Current delivery:
  synchronous Go calls
  one local transaction
  no durable event log, retry queue, or replay cursor

Code: pkg/dispatcher/dispatcher_test.go

The target registry contains capabilities, not domain models

type Target struct {
    Type        cedar.EntityType
    GetAction   cedar.EntityUID
    TagAction   cedar.EntityUID
    UntagAction cedar.EntityUID
    Load        LoadTarget
    Active      ActiveTargets
}
type TargetState struct {
    Entity      cedar.Entity
    DisplayName string
    Tags        tag.Tags
}

Code: app/domains/tagging/registry.go

Replace derives authority from the tag delta

Current:  featured, region=west
Desired:  region=east, seasonal

region changes west → east  : requires tag
seasonal is added           : requires tag
featured is removed         : requires untag
──────────────────────────────────────────
authorize {tag, untag} against loaded state
replace associations
load complete resulting state
authorize {tag, untag} against result
record one tag activity

Code: app/domains/tagging/module.go

Two pipeline commands share one transaction

compose := func(txCtx *middleware.Context) error {
    var err error
    result, err = mutate(txCtx)
    if err != nil { return err }

    replaced, err := application.Tags.Replace(
        txCtx, result.EntityUID(), *desired, expected...,
    )
    if err != nil { return err }
    result.SetTags(replaced.Tags)
    return nil
}
err := middleware.RunWorkflow(ctx, application.Store,
    "tagged_mutation", audit.NewWriter(application.Store).RecordActivity,
    compose)

Code: app/tagged_mutation.go

Protect the editor's intent, not only the latest row

Editor loads: entity revision=7; tags={region=west}
Another actor adds: seasonal
Editor submits: revision=7; tags={region=east}

The entity revision alone cannot detect the tag change.

RunTaggedMutation(..., expectedTags)
  domain command checks its captured revision
  Tags.Replace compares the expected complete tag set
  mismatch → Conflict → both changes roll back

Code: app/tagged_mutation.go

Association identity belongs in a database invariant

target = (EntityType, EntityID)
association = (EntityType, EntityID, Key)

audience=sommelier → audience=bartender
  same association; replace Value

Repeat identical Upsert / Replace
  successful no-op; Changed=false

Repeat the same business command
  not automatically an idempotent request

Code: app/domains/tagging/repository.go

The schema makes the query contract inspectable

type ListFilterView struct {
    Name string `expr:"name" filter:"Drink name" filter-column:"Name"`
    Tags []string `expr:"tags" filter:"Tags (key or key=value)"`
    Recipe RecipeFilterView `expr:"recipe"`
}
type RecipeFilterView struct {
    Garnish string `expr:"garnish" filter:"Recipe garnish"`
}

expr, err := filter.Parse(models.ListFilterSchema(),
    `name == "Daiquiri" && tags contains "featured"`)

Code: app/domains/drinks/models/filter.go

The DAO hydrates before the final predicate

// Inside the row loop, after tags were loaded in one batch:
drink, err := toModel(row)
if err != nil { return err }
drink.Tags = tagsByTarget[drink.EntityUID()]
matched, err := filter.Expression.Match(
    listFilterView(row, drink.Tags.Strings()),
)
if err != nil { return err }
if !matched { continue }
if !yield(&drink, nil) { return nil }

Code: app/domains/drinks/internal/dao/list.go

A pushdown must be necessary, not merely useful

E = the complete expression on a hydrated domain view
P = the predicates applied to persisted rows

Required safety property:
  E(record) = true  ⇒  P(row) = true

Candidate rows may include false positives.
A false negative cannot be recovered by later hydration.

Final result = candidates that satisfy E

Code: pkg/filter/sql.go

Walk the OR counterexample with two rows

Expression:
  category == "spirit" || name == "Beer"

Rows:
  Gin   / spirit → true from the left branch
  Beer  / mixer  → true from the right branch

Unsafe SQL: WHERE Category = 'spirit'
  drops Beer, which satisfies the full expression

Current behavior: retain both candidates; evaluate the OR

Code: pkg/filter/sql_test.go

Widen alternatives only when both constrain the same field

(category == "spirit" && tags contains "featured")
||
(category == "mixer" && tags contains "seasonal")

Safe candidate constraint:
  Category IN ("spirit", "mixer")

Still requires exact matching:
  a spirit tagged only seasonal must be rejected
  a mixer tagged only featured must be rejected

Code: pkg/filter/sql.go

Negation changes the connective before extracting constraints

if node.Kind == KindUnary && node.Operator == "!" {
    return e.impliedPushdowns(node.Children[0], !negated)
}
// For a binary boolean node under negation:
// && becomes ||; || becomes &&
// comparison leaves use negateComparison

!(category == "spirit" || category == "mixer")
  ⇒ Category != "spirit" AND Category != "mixer"

!(category == "spirit" && tags contains "featured")
  ⇒ no category-only constraint is necessary

Code: pkg/filter/sql.go

Own the supported language even when borrowing its compiler

program, err := expr.Compile(source,
    expr.Env(zero),
    expr.AsBool(),
    expr.Optimize(false),
    expr.Patch(dotPredicatePatcher{}),
    expr.Patch(collectionContainsPatcher{fields: collectionFields(schema)}),
)
// Compile errors become Invalid.
tree, err := buildTree(program.Node())
// Unsupported constructs also become Invalid.

// Source: user's trimmed text
// String: canonical syntax
// Tree:   application-owned nodes, not Expr AST

Code: pkg/filter/filter.go

Test candidate safety and final truth separately

TestApplySQLPushdownsDeferHydratedFields:
  three stored rows → two spirit candidates
  attach tags → Match the complete view

TestApplySQLDoesNotPushUnsafeOR:
  Gin/spirit and Beer/mixer must both survive

TestApplySQLPushdownsExtractNecessaryORConstraints:
  alternative categories produce a safe widened set

TestApplySQLPushdownBooleanSemantics:
  negation and boolean columns keep their meaning

Code: pkg/filter/sql_test.go

The SQLite storage shape is more specific than “tables”

-- Selected SQL actually issued by the store:
INSERT INTO records(model, id, data, revision)
VALUES (?, ?, ?, 1);

SELECT data, revision
FROM records
WHERE model = ? AND id = ?;

UPDATE records
SET data = ?, revision = revision + 1
WHERE model = ? AND id = ? AND revision = ?;

Code: pkg/store/query.go

A stale revision becomes a typed conflict

n, _ := r.RowsAffected()
if n == 0 {
    var current uint64
    err := t.tx.QueryRowContext(t.ctx,
        "SELECT revision FROM records WHERE model=? AND id=?",
        modelName(typ), idString(id),
    ).Scan(&current)
    if errors.Is(err, sql.ErrNoRows) {
        return errors.NotFoundf("record absent")
    }
    if err != nil { return err }
    return errors.Conflictf(
        "record changed: expected revision %d, current revision %d",
        revision, current)
}

Code: pkg/store/query.go

Three counters protect three different races

Database change epoch:
  commit observed → epoch increases → cached screen becomes stale

UI request generation:
  load A starts → load B starts → A finishes late → A is ignored

Entity revision:
  read revision 7 → another writer saves revision 8
  submit revision 7 → conditional UPDATE changes 0 rows → Conflict

Code: pkg/store/changes.go

Acquire write intent before reading mutation state

Store.Begin(ctx, writable=true):
  pin a connection
  BEGIN IMMEDIATE
  return a Tx using that connection

Command:
  load current state
  authorize → mutate → authorize result
  dispatch → audit → COMMIT

Competing writer waits or returns an error at acquisition.

Code: pkg/store/store.go

Persistent identity includes the Go row type

func modelName(t reflect.Type) string {
    return t.PkgPath() + "." + t.Name()
}

records primary key:
  (model, id)

Example model discriminator:
  .../app/domains/drinks/internal/dao.DrinkRow

Domain values ↔ row conversion ↔ JSON-backed record

Code: pkg/store/store.go

Migration startup is itself a coordinated write

BEGIN IMMEDIATE
  CREATE TABLE IF NOT EXISTS schema_migrations
  read highest version and applied count
  reject a version newer than this binary understands
  reject a non-contiguous ledger
  apply each outstanding statement
  record each version in the same transaction
COMMIT

On error: rollback using a non-cancelled cleanup context.

Code: pkg/store/store.go

The monitor pins the connection whose counter it compares

conn, version := openChangeConnection(...)
repeat:
  current := dataVersion(conn)
  if current != version:
    version = current
    publish invalidation

If the connection fails:
  reconnect with backoff
  establish a new baseline
  publish anyway: changes may have occurred in the gap

Code: pkg/store/changes.go

Coalescing drops edges but retains an invalidation level

func (m *ChangeMonitor) publish() {
    m.epoch.Add(1)
    select {
    case m.signals <- struct{}{}:
    default:
    }
}

// signals has capacity one.
// Epoch counts monitor publications, not database commits.
// A signal carries no entity ID or business payload.

Code: pkg/store/changes.go

Prove commit visibility using two store instances

reader := Open(path)
writer := Open(path)
monitor := reader.MonitorChanges(...)

writer.Write(insert "committed")
  → monitor signals
  → Epoch > 0

tx := writer.Begin(writable=true)
tx.Insert("rolled back")
writer.Rollback(tx)
  → no invalidation for that rollback

Code: pkg/store/changes_test.go

Place saves the concrete fulfillment plan

usage, err := c.fulfillmentSnapshot(ctx, created)
if err != nil { return nil, err }
created.IngredientUsage = usage

if err := created.Validate(); err != nil {
    return nil, err
}
if err := c.dao.Insert(ctx, &created); err != nil {
    return nil, err
}
ctx.RecordEffect("order_placed", created.ID.EntityUID(),
    middleware.Change("acceptance", "", created.Acceptance))
ctx.AddEvent(events.OrderPlaced{Order: created})
return &created, nil

Code: app/domains/orders/internal/commands/place.go

Readiness is both a report and a command precondition

if err := menu.RequirePublishable(); err != nil {
    return nil, err
}
report, err := c.availability.Readiness(ctx, menu)
if err != nil { return nil, err }
if err := report.RequireReady(); err != nil {
    return nil, err
}

// Only after those checks:
updated := *menu
updated.Status = models.MenuStatusPublished
updated.PublishedAt = optional.Some(now)

Code: app/domains/menus/internal/commands/publish.go

Plan the whole order, not each drink independently

for each order item:
  load its recipe
  retain optional ingredients as optional requirements
  multiply each amount by item quantity
  append to one requirements slice

menus.FulfillIngredients(ctx, requirements)
  → PlanIngredients across the complete slice

Aggregate picks by ingredient ID
  → sort the resulting IngredientUsage snapshot

Code: app/domains/orders/internal/commands/complete.go

Candidate preference is deterministic, not arbitrary

Build candidates:
  original ingredient
  explicit recipe substitutes, with catalog ratios when present
  remaining catalog rules, deduplicated by ingredient ID

Keep candidates with enough individually available stock.

Sort:
  original before substitute
  higher quality rank
  greater available amount
  ingredient ID as final tie-break

Code: app/domains/menus/internal/availability/calculator.go

Force a choice that a greedy planner cannot repair

Requirements, each 1 oz:
  A can use Shared or Fallback
  B can use Shared only

Available: Shared=1.5 oz, Fallback=1 oz
Both substitutes have the same quality.

Try A=Shared:
  B would need total Shared=2 oz → impossible

Undo A's reservation.
Try A=Fallback, then B=Shared → complete plan

Code: app/domains/orders/fulfillment_test.go

Backtracking restores the tentative reservation map

// Inside assign(index), after checking available stock.
selected[index] = pick
reserved[key] = total
if assign(index + 1) {
    return true
}
if hadPrior {
    reserved[key] = prior
} else {
    delete(reserved, key)
}

// No candidate works at this index.
return false

Code: app/domains/menus/internal/availability/calculator.go

Follow the selected plan into persisted inventory

Adversarial fixture:
  A candidates: Shared, Fallback
  B candidates: Shared
  Shared=1.5 oz; Fallback=1 oz

After Place:
  IngredientUsage: Fallback=1 oz, Shared=1 oz
  two Inventory reservations
  on-hand amounts unchanged

After Complete:
  Shared on hand=0.5 oz; Fallback on hand=0 oz
  order reservations removed

Code: app/domains/orders/fulfillment_test.go

Optional means omittable, not unaccounted for

// After all candidate branches at this index fail:
if requirements[index].Optional {
    selected[index] = PickResult{Omitted: true}
    if assign(index + 1) {
        return true
    }
}
return false

// Included optional: snapshot → reserve → consume → cost.
// Omitted optional: explicit selection with Omitted=true.

Code: app/domains/menus/internal/availability/calculator.go

Cost a feasible plan in its price unit

Whole recipe → PlanIngredients once
For each included pick:
  load the chosen stock
  convert required quantity into stock.CostUnit
  multiply by CostPerUnit
  accumulate matching-currency prices

Omitted optional → no cost
Missing price    → unknown, not zero
No complete plan → FailedPrecondition

Code: app/domains/menus/queries/cost.go

Inventory rechecks availability when reserving

// Reserve, inside the originating command transaction.
requested, err := reservation.Amount.Convert(stockUnit)
// Conversion errors propagate.
reserved := sum(existingReservationRows)
if stock.Quantity-reserved < requested.Value() {
    return errors.FailedPreconditionf(/* shortage details */)
}
return tx.Insert(&ReservationRow{
    ID: reservationID(orderID, ingredientID),
    // OrderID, IngredientID, Quantity, Unit
})

Code: app/domains/inventory/internal/dao/reservations.go

Blocked is a set of unresolved causes, not a toggle

Pending order uses A and B.

A shortage → BlockedIngredients={A};   status=blocked
B shortage → BlockedIngredients={A,B}; status=blocked
A restock  → BlockedIngredients={B};   status=blocked
B restock  → BlockedIngredients={};    status=pending

StockAdjusted changes only its ingredient's membership.
The stored list is sorted by ingredient ID.

Code: app/domains/orders/handlers/stock-adjusted.go

Authoritative availability preserves dependency errors

// PlanIngredients:
(picks, true, nil) // complete feasible plan
(nil, false, nil)  // no feasible plan
(nil, false, err)  // dependency or conversion failure

// Strict paths propagate err:
CalculateDetail → PlanIngredients
CalculateStrict → CalculateDetail
Readiness → CalculateDetail
FulfillIngredients → PlanIngredients

// Presentation fallback remains separate:
Calculate → unavailable on error
PickIngredients → (nil, false) on error

Code: app/domains/menus/internal/availability/calculator.go

A bounded search still has a real cost model

N requirements, candidate counts C1 ... CN
Worst-case branches grow like the product of candidate counts,
with an extra omission branch for each optional requirement.

The implementation:
  builds candidate sets before recursion
  prunes when cumulative stock exceeds availability
  returns the first complete feasible assignment
  has no memoization or explicit search budget

It does not split one requirement across several sources.

Code: app/domains/menus/internal/availability/calculator.go

One order carries three different records

AcceptanceSnapshot
  menu identity/name; ordered items and notes
  agreed prices; recipe steps and garnish
  selected and omitted ingredients, quantities and ratios

Plan
  current approved line-by-line preparation

Amendments[]
  actor, time, reason, before/after Plan

IngredientUsage
  aggregated quantities backing current reservations

Code: app/domains/orders/models/snapshot.go

Placement owns lifecycle initialization

created := models.Order{
    MenuID: order.MenuID,
    Items:  order.Items,
    Notes:  order.Notes,
}
created.ID = entity.NewOrderID()
created.Status = models.OrderStatusPending
created.CreatedAt = now
created.CompletedAt = optional.None[time.Time]()

// fulfillmentSnapshot populates Plan and Acceptance.
// DAO insert owns the initial revision.

Code: app/domains/orders/internal/commands/place.go

Amendment is explicit, revisioned intent

type Amendment struct {
    OrderID      entity.OrderID
    Revision     uint64
    Reason       string
    Replacements []Replacement
    Preparation  []PreparationAmendment
}

// Replacement: current selected ID → replacement ID + ratio.
// Preparation: approved steps/garnish for selected drink lines.
// Unspecified preparation retains the previous approved values.

Code: app/domains/orders/models/snapshot.go

Replan without spending your own reservation twice

Load current order and validate expected revision
Copy Plan; apply approved replacements and quantity ratios
Project stock with this order's reservations released
Plan every included requirement as required
Preserve unchanged preparation unless explicitly amended
Save current Plan + aggregate IngredientUsage + amendment
Emit OrderAmended{Before, Order, Reason}

Inventory: validate old reservations, release, reserve new
Menus: prepare availability from net reservation change
Orders: reconcile peers helped by the released commitment

Code: app/domains/orders/internal/commands/amend.go

Validate a batch before its own effects change revisions

App.AmendOrders(requests):
  reject duplicate order IDs
  load every selected order
  require every submitted revision to match

  then, for each request:
    reload the current order in this transaction
    use that revision for Orders.Amend

App.RetireIngredient(..., requests):
  amend the explicit selection
  retire the ingredient in the same workflow

Code: app/amend_orders.go

Prove that the second failure undoes the first success

Two selected orders; replacement stock can fulfill only one.

Attempt App.RetireIngredient with both amendments:
  first amendment provisionally succeeds
  second amendment fails
  outer transaction rolls back

Assert:
  first order equals its original value
  replacement reserved amount = 0
  original ingredient remains active
  audit count = before + 1; failed workflow has effects

Code: app/cross_domain_regression_test.go

Historical references can veto deletion

Delete Drink:
  Menus checks active menu references
  Orders checks all historical order usage

Delete Menu:
  Orders checks all historical order usage

A veto during Handling rolls back the source deletion.
Errors identify dependencies and the corrective action.
Redrafting preserves the previous PublishedAt value.

Code: app/domains/orders/internal/dao/usage.go

Canonical quantity, display unit, price basis

Stock row:
  Quantity + Unit       canonical physical amount (ml for volume)
  DisplayUnit           operator-facing quantity unit
  CostPerUnit + CostUnit explicit price basis

Example:
  10 oz on hand → stored as 295.735 ml
  change display to ml → same stock and reservations
  $2 per oz remains $2 per oz, not $2 per ml

Discrete units retain their own canonical unit.

Code: app/domains/inventory/internal/dao/convert.go

Retirement does not mean throwing stock away

Discontinue:
  exclude ingredient from new service
  retain stock, tags, identity and usable reservations

Withdraw (Retirement.Withdraw=true):
  quarantine retained stock
  block affected open orders

Release quarantine:
  active catalog item → active stock
  retired catalog item → discontinued stock

Neither replacement nor release transfers physical inventory.

Code: app/domains/inventory/handlers/ingredient-deleted.go

Disposal preserves evidence of physical loss

Inventory.Dispose:
  require expected stock revision
  require discontinued/quarantined eligibility
  require positive amount and reason
  subtract from physical stock; reject negative remainder
  at zero, mark disposed
  save movement history and retain the stock row
  emit StockAdjusted to reconcile commitments

Inventory.History reads retained movements.

Code: app/domains/inventory/internal/commands/dispose.go

Recovery must be as complete as blocking

On hand=3; two orders each reserve 2
Aggregate reserved=4 → both orders blocked

Cancel one order:
  release its reservation
  project remaining reserved=2
  clear that ingredient's blocker on the other order
  return to pending only if no blockers remain

Amendment release and quarantine release also reconcile.

Code: app/domains/orders/handlers/order-cancelled.go

Persist substitution rules by identity

type SubstitutionRule struct {
    Revision      uint64
    Disabled      bool
    IngredientID  entity.IngredientID
    SubstituteID  entity.IngredientID
    Ratio         float64
    QualityImpact Quality
    Notes         string
}

// SetSubstitution authorizes update on the original ingredient.
// SubstitutionRules includes disabled rules for administration.

Code: app/domains/ingredients/models/substitution.go

Walk the lifecycle through the CLI

mixology ingredients substitution --id ing-A \
  --substitute-id ing-B --ratio 0.75 --quality similar
mixology ingredients substitutions --id ing-A
mixology orders amend --id ord-A --ingredient-id ing-A \
  --replacement-id ing-B --revision 3 --reason 'approved'
mixology orders amend-batch --file amendments.json

mixology inventory quarantine --ingredient-id ing-A --reason 'inspect'
mixology inventory release --ingredient-id ing-A --reason 'cleared'
mixology inventory dispose --ingredient-id ing-A \
  --quantity 5 --reason 'discard remainder'
mixology inventory history --ingredient-id ing-A

Code: main/cli/order_amend.go

Proposed receipt processing needs durable identity

Design exercise, not implemented:

ReceivePurchaseOrder(purchaseOrderID, receiptID, lines)
  load purchase order; authorize receiving
  reject invalid quantities
  detect an already accepted receiptID
  persist receipt and receiving state
  emit ReceiptAccepted{receiptID, ingredient quantities}
  Inventory applies the receipt in the same transaction

External delivery, if later introduced:
  store an outbox record with the receipt commit
  deliver after commit; deduplicate by receiptID

Code: docs/architecture.md

CLI rows are projections of application models

type DrinkRow struct {
    ID          string `table:"ID" json:"id"`
    Name        string `table:"NAME" json:"name"`
    Status      string `table:"STATUS" json:"status"`
    Ingredients int    `table:"INGREDIENTS" json:"ingredients"`
    // Category, Glass, Tags omitted.
}

// Selected conversion fields:
ID:          d.ID.String(),
Status:      string(d.Status),
Ingredients: len(d.Recipe.Ingredients),

Code: app/domains/drinks/surfaces/cli/views.go

The command chooses the output contract

// ingredients list, after the authorized application query:
if cmd.Bool("json") {
    return clitoolkit.WriteJSON(cmd.Writer,
        paging.Page[ingredientscli.IngredientRow]{
            Items: ingredientscli.ToIngredientRows(res.Items), Next: res.Next,
        })
}
if err := clitable.PrintTable(cmd.Writer,
    ingredientscli.ToIngredientRows(res.Items)); err != nil {
    return err
}
return printNextCursor(cmd.Writer, res.Next)

Code: main/cli/ingredients.go

Table and detail rendering have different field rules

// Selected IngredientRow fields:
ID       string `table:"ID" json:"id,omitempty"`
Revision uint64 `table:"-" json:"revision,omitempty"`
Name     string `table:"NAME" json:"name"`
// Revision is absent from the table, present in detail when nonzero.

TestPrintTable fixture        TestPrintDetail fixture
ID     NAME   COUNT            ID:          ord-1
ing-1  Vodka  2                Menu ID:     mnu-1
                              Created At:  2025-02-03T04:05:06Z
                              Status:      pending

Code: table/table.go · Tests: table/table_test.go · IngredientRow

The process boundary consumes the typed error

cmd := cliApp.Command()
if err := cmd.Run(context.Background(), os.Args); err != nil {
    cli.HandleExitCoder(errors.ToCLIExit(err))
    os.Exit(errors.ExitGeneral)
}

Code: main/cli/main.go

Trace JSON input through the validation boundaries

--template              → print example; no mutation
--file OR --stdin        → choose one input source
ReadJSONInput[DTO]       → decode the transport shape
domain CLI conversion   → parse IDs, units, revision, tags
public facade           → authorization + business validation
DAO                     → constraints + optimistic revision

JSON decoding is not business validation.

Code: pkg/toolkits/cli/json.go

The JSON toolkit standardizes mechanics, not models

func WriteJSON(w io.Writer, v any) error {
    b, err := json.MarshalIndent(v, "", "  ")
    if err != nil {
        return err
    }
    b = append(b, '\n')
    _, err = w.Write(b)
    return err
}

Code: pkg/toolkits/cli/json.go

Capture a request before returning a Bubble Tea effect

m.loadToken++
token := m.loadToken
req := m.request
req.Cursor = cursor

return func() tea.Msg {
    page, err := m.app.Ingredients.List(m.context(), req)
    if err != nil {
        return IngredientsLoadedMsg{Err: err, Token: token}
    }
    // Convert page.Items to the message's []models.Ingredient.
    return IngredientsLoadedMsg{
        Ingredients: items, Next: page.Next, Token: token,
    }
}

Code: app/domains/ingredients/surfaces/tui/list_vm.go

Reject a stale message before changing list state

case IngredientsLoadedMsg:
    if msg.Token != m.loadToken {
        return m, nil
    }
    if msg.Err != nil {
        m.shell.SetResult(m.items, msg.Err)
        return m, nil
    }
    m.next = msg.Next
    selected := selectedIngredientID(m.selectedIngredient())
    // Rebuild list items, then restore selection by entity ID.
    m.selectIngredient(selected)

Code: app/domains/ingredients/surfaces/tui/list_vm.go

Typing and navigation require explicit input ownership

type Interaction struct {
    HandlesBack  bool
    CapturesText bool
}

// Root shell, simplified routing:
rune key + CapturesText → child gets text, not global q / ?
Escape + help open     → close help
Escape + HandlesBack   → child cancels local interaction
Escape otherwise       → navigate application history

Code: main/tui/app.go

Defer invalidation without losing the need to refresh

databaseChangedMsg arrives:
  mark inactive views stale
  active view owns Back or text?
    yes → mark active stale; keep interaction
    no  → send DataInvalidatedMsg now

acceptViewUpdate:
  still editing/detail-owned → keep stale flag
  returned to browse         → clear flag; issue normal reload

Code: main/tui/app.go

Check freshness when the UI callback executes

func (r *LatestRequest[T]) dispatch(
    generation uint64, fn func(),
) {
    r.dispatcher.Dispatch(func() {
        r.mu.Lock()
        current := generation == r.generation
        r.mu.Unlock()
        if current {
            fn()
        }
    })
}

Code: pkg/toolkits/gui/async.go

Publication copies the mutable containers it exposes

func cloneState(state State) State {
    state.Items = append([]models.Ingredient(nil), state.Items...)
    state.History = append([]paging.Cursor(nil), state.History...)
    actionsCopy := make(map[actions.ID]actions.State, len(state.Actions))
    maps.Copy(actionsCopy, state.Actions)
    state.Actions = actionsCopy
    if state.Selected != nil {
        selected := *state.Selected
        state.Selected = &selected
    }
    return state
}

Code: app/domains/ingredients/surfaces/gui/presenter.go

Reads and mutations have different admission semantics

LatestRequest:
  a newer load supersedes the older load
  cancellation reduces obsolete work
  generation checks reject stale publication

Submission:
  first submit marks active=true
  another submit while active returns false
  completion is dispatched to the UI
  release active, then publish the result

Code: pkg/toolkits/gui/async.go

Stop admission atomically with work accounting

e.mu.Lock()
if e.closed {
    e.mu.Unlock()
    return false
}
e.work.Add(1)
e.mu.Unlock()

go func() {
    defer e.work.Done()
    fn()
}()
return true

Code: pkg/toolkits/gui/executor.go

Closing the window is an ordered protocol

desktop.Close, guarded by sync.Once:
  stop change monitor; wait for its delivery goroutine
  close dashboard's separately owned lifecycle
  close executor: reject new work, cancel reads, drain
  close UI dispatcher gate
  close application/store
  close log and telemetry resources

Dashboard stops before executor admission closes.

Code: main/gui/desktop.go

The publication gate checks queued callbacks again

d.dispatcher.Dispatch(func() {
    d.mu.Lock()
    if d.closed {
        d.mu.Unlock()
        return
    }
    d.active++
    d.mu.Unlock()
    defer finishAndSignalDrained()
    fn()
})

// Close sets closed and waits for active callbacks only.

Code: pkg/toolkits/gui/dispatcher.go

Hold real domain work open while closing the desktop

start two accepted tasks:
  Ingredients.Count
  Ingredients.Create
both wait on a controlled release channel

start desktop.Close in another goroutine
assert Close has not returned
assert the store is still queryable

release both tasks
assert both domain calls succeed
assert Close then completes

Code: main/gui/desktop_test.go

The parity test crosses a real process boundary

// CLI runs as a built executable in a temporary directory.
run("tags", "add", ingredientID, "origin=cli")

// A composed desktop opens the same database.
driver.Type(tagginggui.ControlValue, "origin=fyne")
driver.Tap(tagginggui.ControlSubmit)
// Assert the GUI result, then close desktop and GUI app.

output := run("tags", "list", ingredientID)
testutil.ErrorIf(t, !strings.Contains(output, "origin=fyne"),
    "CLI did not observe Fyne tag after a fresh lifecycle:\n%s", output)

Code: main/gui/cross_surface_test.go

Test atomic composition by forcing the second step to fail

TestRunTaggedMutationRollsBackDomainMutationWhenTagReplacementFails

Fixture:
  ingredient name = "Before"
  audit count = N

Mutation callback:
  update the real ingredient to "After"
  return a syntactically valid, nonexistent tag target

Tags.Replace:
  fails to load that target

Assertions after the outer call:
  error != nil; ingredient name == "Before"; audit count == N

Code: app/tagged_mutation_test.go

A dashboard can be partial without inventing zeros

data := UnknownDashboard() // each count starts at -1
load := func(target *int, fn func() (int, error)) {
    value, err := fn()
    if err != nil {
        if first == nil && !errors.IsPermission(err) {
            first = err
        }
        return
    }
    *target = value
}
// Return data plus the first non-permission error.

Code: app/dashboard.go

Make an old result wait in the UI queue

executor := &fynetest.ManualExecutor{}
dispatcher := &fynetest.ManualDispatcher{}
request := gui.NewLatestRequest[int](executor, dispatcher)
// publish appends only Loaded values to values.

request.Load(func() (int, error) { return 1, nil }, publish)
executor.RunNext() // Result 1 is queued for publication.
request.Load(func() (int, error) { return 2, nil }, publish)
executor.RunNext()
dispatcher.Drain()

testutil.ErrorIf(t, len(values) != 1 || values[0] != 2,
    "published values = %v, want [2]", values)

Code: pkg/toolkits/gui/async_test.go

Exercise actual controls by semantic identity

app := test.NewApp()
t.Cleanup(app.Quit)
entry := gui.NewEntry("drink-name")
tapped := false
button := gui.NewButton("save-drink", "Save",
    func() { tapped = true })
driver := fynetest.NewDriver(t, container.NewVBox(entry, button))

driver.Type("drink-name", "Gimlet")
driver.Tap("save-drink")
testutil.ErrorIf(t, entry.Text != "Gimlet" || !tapped,
    "entry=%q tapped=%v", entry.Text, tapped)

Code: pkg/toolkits/gui/semantic_test.go

Permission runs before prerequisites

state := State{ID: control.ID, Visible: true, Enabled: true}
if authorize != nil {
    if err := authorize(ctx); err != nil {
        if errors.IsPermission(err) {
            state.Visible = false
            state.Enabled = false
            return state, nil
        }
        return State{}, err
    }
}
// Only now evaluate Conditions in declaration order.

Code: pkg/presentation/actions/actions.go

Inspect the values a surface actually receives

// Same illustrative control, three successful evaluations:
{"id":"publish","visible":false,"enabled":false}

{"id":"publish","visible":true,"enabled":false,
 "disabled_reason":"Recipe review required"}

{"id":"publish","visible":true,"enabled":true}

// A condition returning a dependency error instead produces:
// states == nil, err != nil

Code: pkg/presentation/actions/actions.go