Phase 3 — Scheduling & conflict avoidance (killer scenario)

[seonghobae]

Buyer outcome

Naruon's first unmistakable buyer workflow is not another calendar view. It is a trustworthy commitment engine that sees customer-owned calendars and communication evidence, distinguishes confirmed obligations from tentative or desired plans, resolves conflicts without leaking private reasons, and changes the authoritative provider only after an authorized correction/approval boundary.

This issue is the canonical implementation contract for scheduling and commitment closure under #1428.

Exact protected-branch baseline — 2026-08-20

Protected develop@c9bfba2dc2063b82741686a3b3120a66c269ab27 already provides:

• signed, scoped Calendar workspace reads and writeback intents;
• opaque server-authoritative CalDAV source selection;
• explicit execute_provider=true execution;
• ETag/If-Match evidence before connector dispatch;
• durable encrypted provider-write retry rows, exponential backoff, exhausted state, signal events, and aggregate queue observability.

It does not yet establish a shipped first-class typed Event/Commitment domain with status-weighted conflict decisions, organizer-vs-attendee iTIP semantics, complete free/busy/resource scheduling, or buyer-visible resolution evidence. The planning document and linked issues describe those as new/planned work. Refetch exact branch and overlapping PRs before implementation.

Domain model

Use normalized temporal objects such as:

event_record
event_occurrence
commitment_record
commitment_status
participant_assignment
organizer_assignment
resource_calendar
availability_window
provider_event_mapping
provider_revision
conflict_assessment
conflict_candidate
resolution_decision
resolution_evidence
schedule_correction
calendar_sync_cursor

Required distinctions:

• event occurrence is not the same as a person's commitment to attend;
• organizer and attendee direction are separate roles;
• confirmed, tentative, desired, declined, and cancelled are not interchangeable;
• series definition, recurrence exception, occurrence, and detached provider copy are separate facts;
• event time, provider-recorded time, Naruon-observed time, and decision time remain distinct;
• one person, resource, or event may belong to multiple projects, bands, organizations, and privacy contexts.

Conflict and resolution contract

1. confirmed > tentative > desired is a default evidence-backed priority, not the only rule.
2. Naruon never silently breaks or rewrites a confirmed commitment.
3. Travel time, location, setup/teardown, availability, organizer role, paid/non-refundable evidence, resource capacity, and tenant policy may affect the decision.
4. Group or norm-group patterns are priors only; they must not be imputed onto an individual without individual evidence.
5. A private fact may cross a context boundary only as the consented necessary consequence, such as unavailable, never the hidden reason.
6. Every recommendation exposes the selected resolution, alternatives behind it, evidence, confidence/calibration, affected provider objects, and one-step correction/hold.
7. Provider mutation is separate from model judgment and requires current authorization, source capability, confirmation policy, and conflict-safe provider revisions.

Protocol and synchronization requirements

• CalDAV collections, calendar-query/report behavior, recurrence, VTIMEZONE, free/busy, and calendar-access semantics must be covered with real interoperability fixtures.
• Scheduling messages use the applicable iTIP/iMIP organizer/attendee method and sequence semantics; REQUEST, REPLY, CANCEL, counter-proposals, and organizer changes must not be flattened into generic CRUD.
• CalDAV Scheduling support follows server capability discovery and scheduling extensions; implementations must not fabricate support when a provider lacks it.
• Collection synchronization uses provider sync tokens where available and falls back only through a documented bounded reconciliation path.
• ETag/If-Match and scheduling-tag preconditions are preserved according to provider capabilities; a stale remote object produces a conflict outcome rather than an overwrite.
• Resource/room calendars support capacity, permissions, availability, tentative holds, decline reasons appropriate for disclosure, and release of abandoned holds.
• Timezone, daylight-saving transitions, floating time, all-day events, leap-day recurrence, exceptions, and provider normalization are tested explicitly.

End-to-end scenarios

Band-rehearsal double booking

confirmed paid rehearsal
+ desired partner event RSVP
→ one resolved recommendation preserving the confirmed commitment
→ private context remains segregated
→ user can correct/hold
→ provider action executes only after approval and current revision check

Organizer RSVP aggregation

• aggregate attendee replies by UID/sequence/organizer authority;
• do not treat a forwarded invitation or unrelated calendar copy as organizer truth;
• surface missing/ambiguous replies and delivery evidence.

Find-time and room booking

• calculate mutual free/busy across authorized sources and working-hour policies;
• include travel/setup buffers and room/resource constraints;
• create bounded holds, confirm exactly once, and release failed/expired holds;
• retry safely without duplicate events or room reservations.

Approval-to-travel coordination

• an authoritative leave/travel approval can enable downstream candidate events;
• later approval revocation or schedule change invalidates stale recommendations;
• no medical, relationship, or other private reason is copied into the work calendar.

Reliability and audit

• every provider command has an idempotency identity and immutable decision/source revision receipt;
• retry, exhaustion, cancellation, late provider success, duplicate provider event, and reconciliation states are explicit;
• a late response cannot overwrite a newer correction or provider revision;
• the user can inspect whether a result was intent-only, dispatched, acknowledged, retried, reconciled, or failed;
• metrics/logs/traces omit event descriptions, attendees, credentials, and private reasons unless a separately authorized diagnostic policy permits a narrow sample.

TDD acceptance evidence

• recurrence and detached-instance property tests;
• timezone/DST/floating/all-day golden fixtures;
• organizer/attendee iTIP sequence and replay tests;
• provider sync-token invalidation and full-reconciliation tests;
• concurrent booking/hold atomicity and duplicate-command tests;
• ETag/scheduling-tag stale-write tests;
• multi-calendar, multi-tenant, and multiple-membership isolation;
• conflict decisions with confirmed/tentative/desired evidence and explicit abstention;
• privacy bridge tests proving only the necessary consequence crosses contexts;
• connector offline/retry/exhaustion/late-success reconciliation;
• real CalDAV/CardDAV interoperability profile against at least two supported servers;
• keyboard, screen-reader, and exact-value UI tests;
• production statement/branch coverage and public API docstrings 100% for owned code;
• unchanged exact-head CI/security/coverage/container/provenance/review/workflow gates.

Done

Close only when a buyer can connect authorized customer calendars, receive a source-cited conflict resolution, approve or correct it, execute an idempotent revision-safe provider action, and inspect durable success/retry/conflict evidence without a confirmed obligation being silently broken or a private reason being disclosed.

Primary standards

• Daboo, C., Desruisseaux, B., & Dusseault, L. M. (2007). Calendaring extensions to WebDAV (CalDAV) (RFC 4791). RFC Editor. https://doi.org/10.17487/RFC4791
• Daboo, C., & Quillaud, A. (2012). Collection synchronization for WebDAV (RFC 6578). RFC Editor. https://doi.org/10.17487/RFC6578
• Daboo, C., & Desruisseaux, B. (2012). Scheduling extensions to CalDAV (RFC 6638). RFC Editor. https://doi.org/10.17487/RFC6638
• Daboo, C. (2010). iCalendar transport-independent interoperability protocol (iTIP) (RFC 5546). RFC Editor. https://doi.org/10.17487/RFC5546

Related work

• [Product Completion] Establish Naruon GA scope, release train, and buyer-visible acceptance evidence #1428 — GA scope and release train
• Scheduling: status-weighted conflict + double-book prevention #988 — status-weighted conflict behavior
• Scheduling: RSVP (iTIP/iMIP) organizer-vs-attendee #989 — RSVP/iTIP organizer-vs-attendee semantics
• Scheduling: find-free-time (free-busy) + room booking #990 — free/busy and room booking
• Phase 4 — Privacy bridge (Digital-Trust) #979 / Privacy: consent minimal-disclosure bridge #991 — minimal-disclosure privacy bridge
• naruon: production connector lifecycle, protocol coverage, and OpenTelemetry operations #998 — connector and observability lifecycle

---

Roadmap item — CWL Project #1 (naruon Platform Roadmap). Phase P3 · Component naruon. Spec: #974 (docs/planning/naruon-platform-plan.md).

[seonghobae]

Cross-repository consumer contract added from LineageWeave:

• [Buyer Gap] Replace pseudo-CalDAV feed with a Naruon-owned calendar projection LineageWeave#336 identifies that the current LineageWeave JSON /events feed is not CalDAV and assigns provider authority to Naruon.
• Draft stacked PR superseded: define Naruon-owned event projection contract LineageWeave#337 defines the bounded v1 read projection consumed by LineageWeave: opaque source/event/occurrence references, provider revision, offset-aware start/end, timezone/all-day, status, disclosure level, truth_status_code=observed, observed time, strict page/window bounds, and a service-audience bearer credential.

The LineageWeave draft intentionally remains unwired until Naruon ships the matching policy-filtered read endpoint/media type and consumer/provider conformance fixtures. Naruon should continue to own CalDAV discovery, recurrence reconciliation, RFC 6578 sync tokens, provider credentials/revisions, scheduling/writeback, retry, and reconciliation; the read projection must not expose attendees, descriptions, provider URLs, credentials, or private conflict reasons beyond authorized disclosure.

[seonghobae]

CalendarWeave ownership correction — 2026-09-01

CalendarWeave PR #1 now defines the accepted DDD Context Map for generic calendar resources/protocol ownership. Revalidate its exact head before implementation; the current architecture head at this handoff is 3983e0b4cc2b6bea60f8d5943343bb44e8090630.

This changes the intended ownership of this Naruon issue without changing the buyer outcome.

Naruon continues to own

• commitment_record / commitment_status and the semantic distinction between confirmed, tentative, desired, declined and cancelled commitments;
• workspace-specific conflict assessment, alternatives, privacy bridge, resolution decision/evidence and correction/approval workflow;
• mail/task/project/travel/customer evidence that affects a scheduling recommendation;
• buyer-facing explanations and explicit authorization to execute an external calendar change;
• immutable evidence snapshots sufficient to explain a historical decision.

CalendarWeave is the target owner

Once CalendarWeave publishes a released executable contract with parity evidence, it owns authoritative generic calendar resources and protocol/provider mechanics:

• calendar collection/event/occurrence and recurrence/timezone semantics;
• RFC 5545 iCalendar and RFC 4791 CalDAV behavior;
• provider event mappings and provider revision/ETag/scheduling-tag state;
• sync tokens/cursors, calendar query/access and generic free/busy/provider capabilities;
• Google/Outlook/CalDAV adapter details and generic calendar serialization;
• calendar authorization/audit receipts at the resource/protocol boundary.

Accordingly, event_record, event_occurrence, provider_event_mapping, provider_revision, calendar_sync_cursor and equivalent mutable calendar-source-of-truth objects in this issue must not become a second authoritative Naruon calendar graph. Naruon should instead hold typed CalendarWeave references plus immutable observed-event evidence where needed for decision provenance.

Required architecture shape

Introduce a Naruon-owned CalendarPort / Anti-Corruption Layer. Naruon domain/application code consumes versioned CalendarWeave commands/queries/receipts and does not import CalendarWeave persistence DTOs or access its tables. Generic provider SDKs and calendar protocol implementations must stay behind that port and should leave Naruon only after CalendarWeave parity is proven.

Current develop evidence shows backend/services/calendar_service.py still directly owns Google Calendar OAuth/SDK writeback and backend/services/calendar_sync.py directly serializes iCalendar VTODO. These are migration candidates, not code to delete immediately. CalendarWeave protected main is still a seed and PR #1 explicitly says the PIMS implementation is pending.

TDD migration order

1. Characterize the current Naruon calendar behavior first, including conflict/approval semantics and provider failure boundaries.
2. CalendarWeave must first ship a versioned executable contract with real RFC fixtures and 100% owned production statement/branch coverage.
3. Add the Naruon CalendarPort/ACL and consumer contract tests against the released CalendarWeave API/package.
4. Prove parity for recurrence/timezones, revisions/stale writes, free/busy/provider capability, tenant/privacy boundaries and failure semantics.
5. Only then remove duplicated generic provider/protocol code from Naruon.
6. Add architecture-fitness tests so Naruon commitment policy cannot drift back into provider/calendar-resource ownership.

The Done criterion remains buyer-oriented: Naruon must still resolve commitment conflicts and execute approved changes safely. The authoritative mutable calendar object and sync mechanics, however, belong to CalendarWeave after the migration boundary becomes executable.

[seonghobae]

2026-09-26 update-writeback gap (current source evidence)

At protected develop@042b0c70531b229af3acbd0421a2f23098d848b3 and draft #1416 head d7505cb3adee7a54cc7b6ccd9c8f1bfa0c01f027, backend/api/calendar.py hashes request.action into the deterministic writeback UID (lines 219-239). The same source and summary therefore produce different .ics targets for create and update. The update If-Match value comes from CalendarWritebackSource.etag_value (lines 82-94, 361-373), which is a source row rather than a revision bound to the target event. I found no production writer for that field in this tree. Current tests cover a supplied update ETag, but do not prove create→update of the same provider resource.

#1416 now guards create PUT with If-None-Match: *; it does not resolve update identity/revision. #1332 owns buyer-visible conflict display, not provider resource mapping. Neither should count as end-to-end update acceptance.

When this P3 item is activated, bind update to the original provider resource and its current resource-specific revision through the CalendarWeave-owned calendar contract described in this issue. Acceptance should include a real create→update round trip on one resource, a stale-revision 412 conflict with no mutation, and tenant/source authorization. Until that contract is executable, preserve fail-closed update behavior and do not claim provider-backed update success from intent-only or mocked dispatch tests.