School-week coordination agent

IDEA 1

A plan depends on a particular snapshot

A snapshot is a recorded view of data at a particular version. A proposed study slot depends on the calendar version used to build it. If the event changes, the proposal must be checked again; an old snapshot is evidence about the old calendar, not proof of the current one.

This bounded capstone models one task and one event within a fictional week. readCalendar checks the expected version, and refreshEvent returns a newer observation or an explicit temporary failure. The small scope makes the version and approval rules inspectable before extending to many events.

Track which calendar your plan used

1. Snapshot. Version 1 places the club event at minutes 30–60.
2. Refresh. Version 2 reports that the event now begins at minute 0.
3. Replan. A 20-minute task originally at 0–20 must move after the event.
4. Identify. The plan key includes the new calendar version and exact interval.

Authored event updates; no real calendar or account is contacted.

Detect overlap before moving a task

const overlaps = start < event.end && event.start < end;
if (overlaps) { start = event.end; end = start + task.minutes; }

Both comparisons must hold for half-open intervals to overlap. Moving the task after the event is this exercise's explicit replanning rule; a later check still verifies the available window.

Think it through: The calendar is now version 2, but the request expects version 1. What should the first read do?

IDEA 2

Refresh failures need a limit and an honest result

A temporary failed read may be worth retrying, but the number of attempts must be bounded. Our demonstration makes at most two immediate refresh attempts. Real services can need timeouts and backoff; this synchronous exercise does not pretend to wait or measure network behavior.

If both attempts fail, the coordinator keeps the last verified calendar version in its report and produces no new plan. It does not turn the old event into a fresh observation. If a refresh succeeds, it records whether the calendar version changed before checking the revised placement.

Keep failed reads in the story

1. Attempt 1. A temporary read failure yields no new event.
2. Attempt 2. One more attempt is allowed under this read-only policy.
3. Stop. Exhaustion returns refresh-failed with the last verified version.

Failures are deterministic classroom fixtures, not real service outages.

Bound the refresh

let latest = null;
for (let attempt = 0; attempt < 2; attempt++) {
  const result = tools.refreshEvent(input.eventId);
  if (result.ok) { latest = result; break; }
}

The loop stops on success or after two tries. latest remains null when no fresh observation exists, which the coordinator must report before attempting a save.

Think it through: Both refresh attempts fail. Which calendar can be labeled current?

IDEA 3

Approval belongs to the exact proposal

Approval should identify the action a person reviewed. This fixture uses a plan key made from calendar version, task ID, start, and end. Changing any of those fields changes the key, so an approval for the old interval cannot authorize the revised one.

The controller checks the approval before calling saveCalendarPreview, and that tool checks it again against trusted fixture data. The preview exists only in the run result. These checks illustrate an action boundary; they are not a real authentication or cryptographic approval system.

A changed plan returns to review

1. Propose. Build the exact key for the refreshed plan.
2. Compare. The reviewed key must match, including the interval.
3. Review or save. A mismatch returns needs-review with zero save calls.

An approval token in these examples is synthetic and permits only an in-memory preview.

Approval is not a general yes

if (!input.approval || input.approval.planKey !== key) {
  return { status: "needs-review", plan };
}

A nonempty approval object is insufficient. Its scope must match the proposal that is about to cross the action boundary.

Think it through: A new plan has the same task ID but a different start time. Can the old plan key authorize it?

Put it into practice

Refresh one event, produce a checked task placement, and save a preview only for the exact approved key.

1. Read the original and latest calendar versions together.
2. Run the starter and inspect its missing-approval preview attempt.
3. Insert the approval-key guard immediately before saveCalendarPreview.
4. Compare approved, changed-event, exhausted-refresh, and stale-snapshot cases.
5. In the experiment, update the approval to the exact new plan key and rerun.

Your next experiment: Change approval.planKey to 2|review|30|50. Explain why this new review matches the revised placement.

Fresh observations can change a plan; changed plans need a fresh match to the approval scope.

Key terms

Snapshot

A recorded view of data at a particular version.

Approval scope

The exact action details and version that a reviewer permitted.

Bounded retry

Another attempt allowed only within an explicit retry limit.

Sources and scope

Original Stemtiq teaching, reviewed 2026-09-14. The named researchers and organizations do not endorse this course. Classroom cases are authored exercises, not published findings.