Module 03

Household intent, stored as versioned settings.

Preferences define when to prepare, what tradeoffs are acceptable, how much may be spent, and how the user wants to be notified. Every order records the exact version it used.

4preference groups

1immutable version per edit

1IANA timezone

0raw address data required

Model

Preference aggregate and snapshots

User preferences module — The settings service validates a complete household aggregate, stores an immutable version, and binds that version to each order cycle.

Settings taxonomy

Four groups the user can reason about

Delivery

Where and when

Address reference, IANA timezone, preferred days and windows, ranked fallbacks, preparation lead time, and review deadline.

Basket

How much and how flexible

Target amount, hard maximum, price increase limit, size tolerance, global substitution default, and excluded categories.

Automation

What the agent may do

Preview, assisted, approval-required, or future autopilot mode; pause; vacation; approval expiration; reconnect policy.

Notifications

When attention is needed

Cart-ready message, authentication request, exception alert, review reminder, delivery reminder, and selected channels.

Contract

Representative aggregate

interface HouseholdPreferences {
  householdId: string;
  timezone: string;
  delivery: {
    addressRef: string;
    rankedWindows: DeliveryWindowPreference[];
    allowFallbackDay: boolean;
  };
  basket: {
    targetAmountCents?: number;
    hardMaximumCents: number;
    maximumPriceIncreasePercent: number;
    defaultSubstitutionPolicy: SubstitutionPolicy;
  };
  automation: {
    mode: 'preview' | 'assisted' | 'approval-required';
    prepareLeadHours: number;
    approvalExpiresMinutes: number;
  };
  version: number;
}

Validation

Bad settings fail before a schedule runs

Setting	Validation	Failure behavior
Timezone	Valid IANA identifier	Cannot enable schedule
Hard maximum	Positive USD amount and compatible with policy	Inline correction required
Delivery windows	At least one ranked allowed window	Schedule remains draft
Automation mode	Consent and release gate allow selected mode	Downgrade to available mode
Address reference	Belongs to connected retailer context	Reconnect or reselect