Food Diary

List persisted meals for one explicit diaryDate in bounded pages. Results include stable entry IDs and entry revisions needed by update_meal, are owner-scoped, and order unknown consumedAt values first followed by UTC timestamps and entry ID. Follow nextCursor while reading an unchanged dataset; cursors are signed for this owner and date and support null consumedAt positions.

list_meals

Read an explicit inclusive startDate/endDate range of at most 366 days. Use raw events or the daily latest-event projection; follow signed nextCursor pages. Missing body fat is never copied from another event. Measurement dates are independent of open food diary days.

list_measurements

Compare recorded intake with CURRENT optional goals for an explicit diaryDate and the seven calendar days ending there. Return daily coverage, remaining/exceeded amounts and weekly averages with explicit eligible-day denominators. Missing dates and unknown nutrients are excluded with separate denominators. Current day is excluded by default; includeCurrentDay counts it once and marks progress provisional. Future dates are always excluded. Coverage describes recorded data, not completeness of actual food intake. Calories are an upper budget; protein is a target to reach. Use after food writes and for progress advice.

read_goal_progress

Read this user's optional daily calorie budget (kcal), protein target (g), and revision. Unset goals are null. Offer optional setup on first use, but never block logging or invent targets.

get_goals

Read one explicit diaryDate and its current revision. hasData distinguishes recorded food from missing dates; revision remains available for empty technical days. Totals include calories, protein, fat, carbs, fiber, and knownItems/totalItems coverage. value is null for incomplete nutrition; knownValue is the separate known sum, and complete describes nutrient coverage; unknown values remain unknown and do not become zero.

read_day

Read live daily nutrition, period totals and equal-weight daily averages for 1–366 inclusive calendar dates. Uses the owner's IANA timezone and local midnight. Missing dates are gaps, unknown nutrients exclude only that nutrient's day, and each denominator is returned. Current day is excluded by default; includeCurrentDay counts its recorded food once and marks the report provisional. Future dates are shown but always excluded. value/total are null for incomplete coverage; knownValue/knownTotal are partial known sums. No completeness of actual eating is implied.

read_nutrition_stats

Read the current user-chosen weight plan, derived consecutive phase dates and target weights, and revision. An absent plan is null with revision 0 initially. Read before setting or editing a plan.

get_weight_plan

Record an owner-scoped scale observation with explicit measurementDate and timezone. Supply weightKg and/or bodyFatPercent (0 to 100); unknown values remain null. measuredAt is optional: omit unknown time, never invent it. Multiple readings per day are preserved. source may describe home bioimpedance scales. Supply requestId for identical retry safety.

record_measurement

Record one to twenty food items atomically for an explicit diaryDate. Every item must include per-serving caloriesKcal, proteinG, fatG, carbsG, and fiberG as finite nonnegative numbers; a known zero is valid. consumedAt is optional and remains null when unknown; timezone remains required. For usual or favorite foods, call get_favs first and copy the selected saved item at its default portion. For other foods without stated nutrition, look up typical values for the food, preparation, and portion from a reliable source and record them; mention in the answer that they are estimates. Reuse requestId only to replay the identical normalized result; changing its payload conflicts.

record_meal

Set or edit user-chosen daily caloriesKcal and/or proteinG. Omitted fields retain their values; null removes a goal. Both are optional for diary use. Read get_goals for expectedRevision (0 initially). Supply a fresh requestId; identical retries replay the saved response. Targets apply to current-goal comparisons, including past days.

set_goals

Save a complete user-chosen plan with startDate, startWeightKg, and consecutive phases containing name, durationWeeks and signed weeklyChangeKg (negative loss, positive gain, zero maintenance). Read get_weight_plan for expectedRevision and use requestId. plan:null clears the plan. Durations represent elapsed weeks: each phase ends start+7*weeks days, and the next starts on that boundary. Use the stated baseline weight or the latest recorded weight; ask only if neither exists. Clarify ambiguous dates; never prescribe targets. Replacing the plan also changes comparisons for past dates.

set_weight_plan

Correct exactly one owner-scoped meal entry identified by stable entryId and explicit diaryDate. Read list_meals first and pass both expectedEntryRevision and expectedDayRevision. In replacement mode, title, quantity, unit, caloriesKcal, proteinG, fatG, carbsG, and fiberG are all required; consumedAt/timezone can be omitted to preserve their saved values. In rescale mode, pass only a new quantity; the unit and every saved nutrition value are scaled deterministically at fixed precision, and incomplete legacy nutrition is rejected. requestId retries are idempotent only for the identical payload.

update_meal