# V1 Block 12 — Occupancy Policy and Scheduling Correctness

Status: Complete on 2026-06-25.

Purpose: Make every scheduling operation use one explicit occupancy policy so
protected free slots, surprise work, required commitments, and hidden locked
time behave consistently without breaking flexible-task order.

## Chunk 12.1 — Central occupancy policy

Recommended Codex level: extra high

Status: Complete on 2026-06-25.

Tasks:

- Introduce one UI-independent occupancy classifier/policy used by insertion,
  next-slot push, tomorrow push, rollover, surprise repair, and overlap analysis.
- Classify at minimum:
  - hidden locked constraints
  - required visible critical/inflexible intervals
  - protected free slots
  - movable planned flexible tasks
  - active work
  - completed actual occupancy, including surprise work
  - non-occupying backlog/cancelled/no-longer-relevant records
  - retained historical missed intervals
- Define separately whether an interval is immovable, blocks automatic flexible
  placement, may be explicitly overlapped by a required commitment, and should
  be reported as a conflict.
- Replace duplicated hard-coded blocker lists in scheduling operations with the
  central policy.
- Ensure locked and inflexible items are never emitted as movement changes.
- Add a matrix test that runs each task type/status combination through the
  policy.

Rules:

- Occupancy is not the same as visibility; hidden locked time still blocks.
- A task being completed does not erase a known actual interval from historical
  occupancy.
- Backlog and cancelled/no-longer-relevant tasks do not block placement.
- Preserve flexible order unless the user explicitly selected a different
  destination.
- Do not use UI card categories as scheduling policy inputs.

Acceptance criteria:

- Every scheduling operation obtains blockers/movable work from the same policy.
- Policy tests cover every V1 task type and lifecycle state.
- Locked and inflexible records remain byte-for-byte placement-stable after
  automatic operations.
- The policy exposes conflict-reporting behavior independently from movement
  behavior.
- Existing scheduling tests pass or are intentionally updated to the resolved
  V1 contract.

BREAKPOINT: Stop here. Confirm `high` mode before implementing protected free-slot
and surprise-occupancy behavior.

## Chunk 12.2 — Protected Free Slot scheduling behavior

Recommended Codex level: high

Status: Complete on 2026-06-25.

Tasks:

- Add validated creation/update helpers for scheduled Free Slot records.
- Treat Free Slots as protected blockers for automatic flexible insertion,
  pushing, tomorrow placement, and rollover.
- Allow an explicitly scheduled critical or inflexible commitment to overlap a
  Free Slot without moving the Free Slot, while returning a typed interrupt or
  conflict result for the application layer.
- Ensure an exact boundary touch is not treated as overlap.
- Ensure a flexible task that cannot fit around a Free Slot remains unchanged and
  returns a no-slot outcome.
- Cover multiple adjacent Free Slots, whole-day protected rest, and Free Slots at
  the start/end of a planning window.
- Preserve Free Slot timeline metadata for the later Today read model.

Rules:

- Free Slot means intentional protected rest, not unused capacity.
- The scheduler must not consume a Free Slot simply because it appears empty.
- Do not add automatic best-fit task suggestions in this chunk.
- Do not move a Free Slot during repair.
- Reminder suppression is implemented in Block 13, but this chunk must expose the
  occupancy facts needed by that policy.

Acceptance criteria:

- Flexible tasks never land inside a protected Free Slot through any automatic
  V1 scheduling operation.
- Explicit required overlap produces a typed result and does not move either the
  required item or Free Slot.
- Boundary and no-fit behavior is regression-tested.
- Free Slot records remain visible to read-model mapping but never act as normal
  flexible quick-action cards.

## Chunk 12.3 — Surprise, active, and completed actual occupancy

Recommended Codex level: high

Status: Complete on 2026-06-25.

Tasks:

- Persist and classify a surprise task’s actual interval as occupied time after
  the initial logging operation.
- Ensure subsequent same-day insertion, push, and repair operations cannot place
  flexible work over known surprise occupancy.
- Define and implement active-task occupancy using planned and/or actual interval
  data from Block 11.
- Preserve known actual intervals for completed planned tasks when later
  operations rebuild the day.
- Repair all overlapping planned flexible tasks in stable order when surprise
  work is logged.
- Report required and locked overlap categories without exposing hidden locked
  details unless reveal mode is explicitly requested.
- Make surprise logging idempotent by operation ID so retries do not duplicate
  the task or push the same flexible work twice.
- Add tests for multiple surprise entries, nested overlaps, exact boundaries,
  and a retry of the same operation.

Rules:

- Surprise work is already completed and is never moved by the repair operation.
- Required and locked intervals are reported, never moved.
- Hidden locked names/details must not leak through default result DTOs.
- Actual historical occupancy must not be inferred from `updatedAt`.
- Statistics are updated in Block 13; this chunk establishes scheduling facts.

Acceptance criteria:

- A logged surprise interval remains a blocker in all later same-day operations.
- Flexible repair preserves order and applies each movement once.
- Required/locked overlap outputs are typed and privacy-safe by default.
- Retrying the same surprise operation is a no-op with the original result or an
  equivalent idempotent result.
- All surprise and scheduling regression tests pass.

BREAKPOINT: Stop here. Confirm `extra high` mode before replacing scheduling
message contracts and adding invariant/property tests.

## Chunk 12.4 — Structured scheduling outcomes and invariant test suite

Recommended Codex level: extra high

Status: Complete on 2026-06-25.

Tasks:

- Replace English notice text as the machine contract with stable scheduling
  operation, issue, movement, and conflict codes plus structured parameters.
- Keep optional debug/default text only as non-authoritative presentation data.
- Standardize not-found, invalid-state, no-slot, overflow, conflict, and no-op
  outcomes across all scheduling operations.
- Ensure overflow/no-slot paths do not partially mutate returned task state.
- Add shared invariant assertions for:
  - no movable task overlaps a blocker after success
  - immovable placements do not change
  - flexible relative order is preserved
  - task IDs remain unique
  - intervals remain valid
  - an idempotent replay does not add changes
- Add deterministic randomized/property-style tests over varied windows,
  blockers, durations, and task order.
- Add a practical performance baseline for a large single-day task set and record
  the threshold as a regression guard rather than a microbenchmark promise.
- Update callers/tests to branch on codes, not message strings.

Rules:

- Localization belongs outside the scheduling core.
- Do not silently drop warnings when converting old notice objects.
- Randomized tests must use fixed seeds and print a reproducible failing case.
- Performance work must not replace clear/correct code with opaque premature
  optimization.
- Do not add non-V1 scheduling heuristics.

Acceptance criteria:

- No application/domain test relies on exact English scheduling text for logic.
- Every scheduler operation returns the same typed outcome categories.
- Property tests protect the main scheduling invariants.
- No-slot and conflict results are non-destructive.
- The standard verification suite and new scheduling matrix pass.

Verification on 2026-06-25:

- `dart format lib test`: passed, 0 files changed
- `dart analyze`: passed, no issues found
- `dart test`: passed, 203 tests
- `git diff --check`: passed

BREAKPOINT: Stop here. Confirm `high` mode before beginning Block 13.

Commit suggestion:

```text
feat(scheduling): unify v1 occupancy and structured outcomes
```
