@mgcrea/mcp-apple-calendar 0.0.0-bootstrap

package/dist/server-B2HtiXLF.js

@@ -0,0 +1,2337 @@
+import { AppBusyError as CalendarBusyError, AppNotRunningError as CalendarNotRunningError, AppleAutomationError, AppleAutomationError as AppleCalendarError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, PreconditionError, SchemaDriftError, columnsOf, confirmArg, createOsascriptRunner, describeStore, escapeLike, fingerprintSchema, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, readPackageIdentity, trimmed, withBusyRetry, wrap } from "@mgcrea/mcp-apple-core";
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+//#region src/build-info.ts
+const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
+	name: "@mgcrea/mcp-apple-calendar",
+	version: "0.0.0"
+});
+const BUILD_INFO = {
+	name: pkg.name,
+	version: pkg.version,
+	gitCommit: "df06e7f",
+	gitCommitDate: "2026-08-22T16:20:23+02:00"
+};
+//#endregion
+//#region src/client/errors.ts
+/**
+* Calendar's error surface. The taxonomy lives in `@mgcrea/mcp-apple-core`;
+* what belongs here is the identity those messages are written against, and the
+* errors that are genuinely about calendars.
+*/
+/**
+* Named in every user-facing error and in the env vars they mention.
+*
+* `appName` is the display name, which is NOT the bundle id: Calendar.app is
+* still `com.apple.iCal` underneath. Every other surface has the two agreeing,
+* so the mismatch is written down in both places it matters.
+*/
+const CALENDAR_SURFACE = {
+	appName: "Calendar",
+	envPrefix: "APPLE_CALENDAR"
+};
+/** Calendar's Apple Events target. Not `com.apple.Calendar`, which does not exist. */
+const CALENDAR_BUNDLE_ID = "com.apple.iCal";
+/**
+* A date argument could not be understood.
+*
+* Carries the accepted grammar rather than just rejecting, because the caller is
+* usually a model that will retry once and needs to know what shape to retry in.
+*/
+var InvalidDateError = class extends AppleAutomationError {
+	name = "InvalidDateError";
+	constructor(field, raw, reason) {
+		super(`Could not read ${field} from ${JSON.stringify(raw)}: ${reason}. Accepted: an ISO-8601 date "2026-08-20" (a whole day) or date-time "2026-08-20T09:00" (an instant), or a relative offset like "+2d", "+3h", "+45m", "+1w", "today", "tomorrow", "tomorrow 09:00", or "next monday".`, {
+			field,
+			raw
+		});
+	}
+};
+/** A CalendarRef no longer resolves — deleted, or moved to another calendar. */
+var EventNotFoundError = class extends AppleAutomationError {
+	name = "EventNotFoundError";
+	constructor(ref) {
+		super(`No event for ref "${ref}". It was probably deleted or moved since the search ran. Re-run the search to get a current ref.`, { ref });
+	}
+};
+/** A calendar was named that Calendar does not have. */
+var CalendarNotFoundError = class extends AppleAutomationError {
+	name = "CalendarNotFoundError";
+	constructor(name, available = []) {
+		super(`No calendar named "${name}".` + (available.length ? ` Available: ${available.slice(0, 20).join(", ")}${available.length > 20 ? ", …" : ""}.` : ` Use apple_calendar_list_calendars to see what exists.`), { requested: name });
+	}
+};
+/**
+* A write was aimed at a calendar that cannot accept one.
+*
+* Its own error rather than a generic failure because the cause is almost
+* always structural rather than a mistake: holiday, birthday and subscribed
+* calendars are read-only by nature, and a caller that hits one needs to pick a
+* different target, not retry.
+*/
+var CalendarNotWritableError = class extends AppleAutomationError {
+	name = "CalendarNotWritableError";
+	constructor(name) {
+		super(`The calendar "${name}" is read-only, so nothing can be written to it. Subscribed calendars — holidays, birthdays, and anything added by URL — are read-only by nature. Use apple_calendar_list_calendars to find one where "writable" is true.`, { calendar: name });
+	}
+};
+//#endregion
+//#region src/client/dates.ts
+/**
+* Date handling for the Calendar tools.
+*
+* ## Two halves
+*
+* INPUT is the grammar `packages/reminders/src/client/dates.ts` established, and
+* it is deliberately identical: a caller writing `2026-08-20` names a day, one
+* writing `2026-08-20T09:00` names an instant, `+2d` names a duration, and day
+* and week offsets are calendar arithmetic while hour and minute offsets are
+* elapsed time. That split is not cosmetic — getting it backwards drifts every
+* date by an hour twice a year.
+*
+* OUTPUT is Calendar's own problem and has no analogue in Reminders. An event
+* carries a start AND an end, a timezone of its own, and an all-day flag that
+* changes what the stored number even means. Rendering that wrongly is the
+* quietest bug on this surface, so `EventInstant` makes the caller's two cases
+* two different shapes rather than one shape with a boolean to remember.
+*
+* ## The timezone rules, measured rather than assumed
+*
+* `docs/calendar.md` records 8 distinct `start_tz` values across 1,350 rows,
+* with no nulls, of which two are not IANA names and mean OPPOSITE things:
+*
+*   `_float`     a floating date — an instant deliberately without a zone
+*   `GMT+0200`   a perfectly definite fixed offset that is merely not IANA
+*
+* Collapsing the second into the first silently discards two hours, so they are
+* classified apart here. Anything matching `GMT±HHMM` is honoured as an offset;
+* only what is left over floats.
+*/
+const DAY_NAMES = [
+	"sunday",
+	"monday",
+	"tuesday",
+	"wednesday",
+	"thursday",
+	"friday",
+	"saturday"
+];
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_DATETIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/;
+const OFFSET = /^\+(\d+)\s*(m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days|w|week|weeks)$/;
+const DAY_WORD = /^(today|tomorrow)(?:\s+(\d{1,2}):(\d{2}))?$/;
+const NEXT_DAY = /^next\s+([a-z]+)(?:\s+(\d{1,2}):(\d{2}))?$/;
+const DURATION = /^(\d+)\s*(m|min|mins|minute|minutes|h|hr|hrs|hour|hours)?$/;
+/** `GMT+0200`, `UTC-05:00`. A definite zone that is simply not an IANA name. */
+const FIXED_OFFSET = /^(?:GMT|UTC)([+-])(\d{2}):?(\d{2})$/i;
+const pad$1 = (n, w = 2) => String(n).padStart(w, "0");
+/** `+02:00` / `-05:00` / `Z` for a given instant, in the system zone. */
+const offsetOf = (d) => {
+	const mins = -d.getTimezoneOffset();
+	if (mins === 0) return "Z";
+	const sign = mins < 0 ? "-" : "+";
+	const abs = Math.abs(mins);
+	return `${sign}${pad$1(Math.floor(abs / 60))}:${pad$1(abs % 60)}`;
+};
+/**
+* Local wall-clock time rendered with its offset.
+*
+* Deliberately not `toISOString()`, which converts to UTC and would report a
+* 09:00 meeting as `07:00Z` — correct as an instant, unreadable in a result
+* whose purpose is confirming what the caller asked for.
+*/
+const toLocalIso = (d) => `${d.getFullYear()}-${pad$1(d.getMonth() + 1)}-${pad$1(d.getDate())}T${pad$1(d.getHours())}:${pad$1(d.getMinutes())}:${pad$1(d.getSeconds())}${offsetOf(d)}`;
+const startOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);
+const endOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+/** Calendar-aware day arithmetic: same wall-clock time, n days later. */
+const addDays = (d, n) => {
+	const out = new Date(d.getTime());
+	out.setDate(out.getDate() + n);
+	return out;
+};
+const at = (day, hours, minutes) => new Date(day.getFullYear(), day.getMonth(), day.getDate(), hours, minutes, 0, 0);
+const result = (kind, when, raw) => ({
+	kind,
+	at: when,
+	iso: toLocalIso(when),
+	raw
+});
+/**
+* Parse one date argument.
+*
+* @param field Named in the error, so a failure says WHICH argument was bad.
+* @param raw   The caller's string.
+* @param now   Injected for hermetic tests.
+*/
+const parseDate = (field, raw, now = /* @__PURE__ */ new Date()) => {
+	const text = String(raw ?? "").trim();
+	if (!text) throw new InvalidDateError(field, String(raw), "it is empty");
+	const lower = text.toLowerCase();
+	const dt = ISO_DATETIME.exec(text);
+	if (dt) {
+		const [, y, mo, d, hh, mm, ss, zone] = dt;
+		const when = zone ? new Date(text.replace(" ", "T")) : new Date(Number(y), Number(mo) - 1, Number(d), Number(hh), Number(mm), Number(ss ?? "0"), 0);
+		if (Number.isNaN(when.getTime())) throw new InvalidDateError(field, text, "it is not a real date");
+		return result("timed", when, text);
+	}
+	const only = ISO_DATE.exec(text);
+	if (only) {
+		const [, y, mo, d] = only;
+		const when = new Date(Number(y), Number(mo) - 1, Number(d), 0, 0, 0, 0);
+		if (Number.isNaN(when.getTime())) throw new InvalidDateError(field, text, "it is not a real date");
+		if (when.getMonth() !== Number(mo) - 1 || when.getDate() !== Number(d)) throw new InvalidDateError(field, text, `there is no day ${d} in month ${mo}`);
+		return result("allDay", when, text);
+	}
+	const off = OFFSET.exec(lower);
+	if (off) {
+		const n = Number(off[1]);
+		const unit = String(off[2]);
+		if (!Number.isFinite(n)) throw new InvalidDateError(field, text, "the amount is not a number");
+		if (unit.startsWith("d")) return result("timed", addDays(now, n), text);
+		if (unit.startsWith("w")) return result("timed", addDays(now, n * 7), text);
+		const ms = unit.startsWith("h") ? n * 36e5 : n * 6e4;
+		return result("timed", new Date(now.getTime() + ms), text);
+	}
+	const word = DAY_WORD.exec(lower);
+	if (word) {
+		const day = word[1] === "tomorrow" ? addDays(now, 1) : now;
+		if (word[2] === void 0) return result("allDay", startOfDay(day), text);
+		const [hh, mm] = [Number(word[2]), Number(word[3])];
+		if (hh > 23 || mm > 59) throw new InvalidDateError(field, text, `${hh}:${word[3]} is not a time`);
+		return result("timed", at(day, hh, mm), text);
+	}
+	const next = NEXT_DAY.exec(lower);
+	if (next) {
+		const idx = DAY_NAMES.findIndex((n) => n === next[1] || n.slice(0, 3) === next[1]);
+		if (idx === -1) throw new InvalidDateError(field, text, `"${next[1]}" is not a day of the week`);
+		const ahead = (idx - now.getDay() + 7) % 7 || 7;
+		const day = addDays(now, ahead);
+		if (next[2] === void 0) return result("allDay", startOfDay(day), text);
+		const [hh, mm] = [Number(next[2]), Number(next[3])];
+		if (hh > 23 || mm > 59) throw new InvalidDateError(field, text, `${hh}:${next[3]} is not a time`);
+		return result("timed", at(day, hh, mm), text);
+	}
+	throw new InvalidDateError(field, text, "it matches none of the accepted forms");
+};
+/**
+* Parse a bound for a range filter.
+*
+* A bare day means the WHOLE day, so which edge it resolves to depends on which
+* side of the range it is. Resolving both to midnight would make an end bound
+* quietly exclude the day the caller named.
+*/
+const parseBound = (field, raw, edge, now = /* @__PURE__ */ new Date()) => {
+	const parsed = parseDate(field, raw, now);
+	if (parsed.kind !== "allDay") return parsed.at;
+	return edge === "end" ? endOfDay(parsed.at) : startOfDay(parsed.at);
+};
+/**
+* Resolve a query window.
+*
+* Unlike a note list, a calendar has no natural "everything": it stretches
+* indefinitely in both directions and `MAX(start_date)` on the probed store
+* already reads 2030. So an unbounded default would scan a decade to report
+* next Tuesday, and every window is bounded on both ends.
+*/
+const parseRange = (opts, now = /* @__PURE__ */ new Date()) => {
+	const from = opts.from ? parseBound("from", opts.from, "start", now) : startOfDay(now);
+	const to = opts.to ? parseBound("to", opts.to, "end", now) : endOfDay(addDays(from, opts.defaultRangeDays - 1));
+	if (to.getTime() < from.getTime()) throw new InvalidDateError("to", String(opts.to ?? ""), `it resolves to ${toLocalIso(to)}, which is before from (${toLocalIso(from)})`);
+	const maxMs = opts.maxRangeDays * 864e5;
+	if (to.getTime() - from.getTime() > maxMs) return {
+		from,
+		to: new Date(from.getTime() + maxMs),
+		clamped: true
+	};
+	return {
+		from,
+		to,
+		clamped: false
+	};
+};
+/** `90`, `"90"`, `"90m"`, `"2h"` -> minutes. */
+const parseDuration = (field, raw) => {
+	const text = String(raw ?? "").trim().toLowerCase();
+	if (!text) throw new InvalidDateError(field, String(raw), "it is empty");
+	const m = DURATION.exec(text);
+	if (!m) throw new InvalidDateError(field, text, "expected minutes, or a value like \"90m\" or \"2h\"");
+	const n = Number(m[1]);
+	if (!Number.isFinite(n) || n <= 0) throw new InvalidDateError(field, text, "the amount must be a positive number");
+	return m[2]?.startsWith("h") ? n * 60 : n;
+};
+/** Whether a stored `start_tz` names a zone this process can actually resolve. */
+const isIanaZone = (tz) => {
+	try {
+		Intl.DateTimeFormat("en-US", { timeZone: tz });
+		return true;
+	} catch {
+		return false;
+	}
+};
+/**
+* A stored timezone string, classified.
+*
+* `null` means floating, and floating is a real state rather than missing data:
+* the event names a wall-clock time that is correct wherever you open it.
+*/
+const resolveZone = (tz) => {
+	if (!tz) return null;
+	const text = String(tz).trim();
+	if (!text || text === "_float") return null;
+	if (isIanaZone(text)) return text;
+	const fixed = FIXED_OFFSET.exec(text);
+	if (fixed) {
+		const [, sign, hh, mm] = fixed;
+		if (mm === "00") {
+			const name = `Etc/GMT${sign === "+" ? "-" : "+"}${Number(hh)}`;
+			if (isIanaZone(name)) return name;
+		}
+	}
+	return null;
+};
+const partsIn = (d, tz) => {
+	const fmt = Intl.DateTimeFormat("en-US", {
+		timeZone: tz,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		timeZoneName: "longOffset"
+	});
+	const out = {};
+	for (const p of fmt.formatToParts(d)) out[p.type] = p.value;
+	return out;
+};
+/**
+* Render a stored instant as an event start or end.
+*
+* ## Why all-day is derived in the event's own zone, falling back to local
+*
+* An all-day event names a DAY, and the day you get depends entirely on which
+* frame you read the stored instant in. MEASURED against a live store:
+*
+*   stored          2026-08-20T22:00:00Z
+*   UTC getters     2026-08-20    <- a day early
+*   local getters   2026-08-21    <- what Calendar.app shows
+*
+* Calendar anchors an all-day event at midnight in the event's own zone, which
+* for a floating date is the local one. So the day comes from local components,
+* or from `start_tz` when that names a real zone.
+*
+* THIS WAS ORIGINALLY WRITTEN THE OTHER WAY ROUND, and the mistake is worth
+* keeping on the record. `docs/reminders.md` documents that REMINDERS' store
+* holds UTC midnight while its Apple Events lane holds local midnight; that was
+* generalised to Calendar without measuring, and the unit tests agreed because
+* their fixtures were built on the same wrong assumption. It survived a
+* four-timezone test matrix and was caught only by reading a real calendar,
+* where the rendered day disagreed with the ref in the same result.
+*
+* The anchor is a property of the store, not a general rule. Measure it per
+* surface. `dates.test.ts` now builds its fixtures at LOCAL midnight, which is
+* what the data actually looks like.
+*
+* @param appleSeconds Core Data seconds, straight from the column.
+* @param tz           The row's `start_tz` / `end_tz`, unclassified.
+* @param allDay       The row's all-day flag. Authoritative; never inferred.
+* @param epochOffset  From `StoreCapabilities`, so the 31-year bug has one home.
+*/
+const renderInstant = (appleSeconds, tz, allDay, epochOffset) => {
+	if (appleSeconds === null || appleSeconds === void 0 || !Number.isFinite(appleSeconds)) return null;
+	const d = /* @__PURE__ */ new Date((appleSeconds + epochOffset) * 1e3);
+	if (Number.isNaN(d.getTime())) return null;
+	if (allDay) {
+		const zone = resolveZone(tz);
+		if (zone) {
+			const p = partsIn(d, zone);
+			return {
+				allDay: true,
+				day: `${p.year}-${p.month}-${p.day}`,
+				timeZone: null
+			};
+		}
+		return {
+			allDay: true,
+			day: `${d.getFullYear()}-${pad$1(d.getMonth() + 1)}-${pad$1(d.getDate())}`,
+			timeZone: null
+		};
+	}
+	const zone = resolveZone(tz);
+	if (!zone) return {
+		allDay: false,
+		iso: toLocalIso(d),
+		timeZone: null
+	};
+	const p = partsIn(d, zone);
+	const raw = p.timeZoneName ?? "";
+	const offset = raw === "GMT" ? "Z" : raw.replace(/^GMT/, "");
+	return {
+		allDay: false,
+		iso: `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}${offset}`,
+		timeZone: zone
+	};
+};
+//#endregion
+//#region src/client/jxa/core.ts
+/**
+* JXA script fragments.
+*
+* Every script here is a static constant. None may contain a template
+* interpolation — `assertStaticScript` rejects any script containing a dollar
+* sign followed by a brace, including template literals written INSIDE the JXA
+* source. Use string concatenation in JXA code.
+*
+* Every script follows the same contract:
+*   - it reads its parameters from `JSON.parse(argv[0])`
+*   - it returns `JSON.stringify({ok: true, data})` on success
+*   - it returns `JSON.stringify({ok: false, error: {code, message}})` on an
+*     application-level failure, still exiting 0
+* so a non-zero exit always means infrastructure rather than "no such event".
+*
+* ## There is no read.ts here, and that is the design
+*
+* Mail, Notes and Reminders all carry an Apple Events read lane. Calendar does
+* not, because `docs/calendar.md` measured one: a single ±90-day range query
+* costs 3.4 s over 1,349 events, and the cost falls per ROUND TRIP rather than
+* per event — about 2 s per property, flat — so no batching rescues it. That is
+* not a slower fallback, it is no fallback. Reads go through the file lane and
+* these scripts exist only to make Calendar change something.
+*
+* `test/jxa.test.ts` asserts that `read.ts` does not exist, so this stays a
+* decision rather than an accident.
+*
+* ## Finding an event costs a bulk fetch, which is why refs carry a calendar
+*
+* Calendar has no `events.byId()`. The two options are `whose({uid})`, measured
+* at 4.5-7.3 s and — worse than slow — UNSTABLE across runs, or one bulk
+* `cal.events.uid()` fetch plus an index in JS at about 1.8 s. The second only
+* stays affordable if it is scoped to ONE calendar, so `ref.ts` carries the
+* calendar uid and every script below narrows before it scans.
+*/
+/**
+* Shared prelude.
+*
+* THE BUNDLE IDENTIFIER IS `com.apple.iCal`. Calendar.app kept the id it
+* shipped with as iCal, and this is the only surface in the project where the
+* display name and the bundle id disagree — `Application("Calendar")` is
+* correct, and `com.apple.Calendar` does not exist.
+* `runningApplicationsWithBundleIdentifier` matches exactly and does not fold
+* case, so getting this wrong makes every write report "not running".
+*/
+const PRELUDE = `
+ObjC.import("AppKit");
+
+function isCalendarRunning() {
+  var apps = $.NSRunningApplication.runningApplicationsWithBundleIdentifier("com.apple.iCal");
+  return apps.count > 0;
+}
+
+function ok(data) { return JSON.stringify({ ok: true, data: data }); }
+function err(code, message) { return JSON.stringify({ ok: false, error: { code: code, message: String(message) } }); }
+
+function iso(d) {
+  try { return d ? d.toISOString() : null; } catch (e) { return null; }
+}
+
+/** Read one property defensively: Calendar throws on properties it cannot supply. */
+function prop(fn, fallback) {
+  try {
+    var v = fn();
+    return v === undefined ? fallback : v;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+/**
+ * Find a calendar BY NAME.
+ *
+ * MEASURED, macOS 26.6: \`calendar.uid()\` throws \`AppleEvent handler failed\`
+ * (-10000) for EVERY calendar, including ones this process just created. So a
+ * calendar cannot be addressed by uid across Apple Events at all, and the
+ * store's \`Calendar.UUID\` has no counterpart on this side.
+ *
+ * This is NOT the event id bridge, which docs/calendar.md measured as exact
+ * (\`CalendarItem.UUID\` matched an event's \`uid\` 198/198). That result was
+ * assumed to carry over to calendars; it does not. Events are addressable by
+ * uid, calendars are addressable by name, and the caller resolves the name
+ * before it gets here — including refusing an ambiguous one, which this side
+ * has no way to detect.
+ */
+function findCalendar(C, wanted) {
+  if (!wanted) {
+    return prop(function () { return C.defaultCalendar(); }, null);
+  }
+  var cals = prop(function () { return C.calendars(); }, []);
+  for (var i = 0; i < cals.length; i++) {
+    var name = prop(function () { return String(cals[i].name()); }, null);
+    if (name === wanted) return cals[i];
+  }
+  return null;
+}
+
+/**
+ * Find one event inside a calendar, by uid.
+ *
+ * ONE bulk fetch of every uid in the calendar, then an index in JS.
+ *
+ * Deliberately NOT a specifier applied to the events collection, which was
+ * measured slower AND unstable — 4,564 / 5,290 / 7,303 ms across three runs of
+ * the same query — against a steady 3.4 s for a bulk scan. test/jxa.test.ts
+ * enforces that by string match, which is why the disallowed form is described
+ * here rather than written out.
+ */
+function findEvent(cal, uid) {
+  var uids = prop(function () { return cal.events.uid(); }, null);
+  if (!uids) return null;
+  for (var i = 0; i < uids.length; i++) {
+    if (String(uids[i]) === uid) {
+      return prop(function () { return cal.events[i]; }, null);
+    }
+  }
+  return null;
+}
+
+/** Millisecond-tolerant instant comparison, for the excluded-dates path. */
+function sameInstant(a, b) {
+  if (!a || !b) return false;
+  return Math.abs(a.getTime() - b.getTime()) < 1000;
+}
+
+/**
+ * Whether a calendar accepts writes.
+ *
+ * Subscribed calendars — holidays, birthdays, anything added by URL — are
+ * read-only, and assigning to one fails deep inside Calendar with a message
+ * that does not say so. Asking first turns that into an error naming the cause.
+ */
+function isWritable(cal) {
+  return prop(function () { return cal.writable(); }, true);
+}
+
+function readback(ev, cal) {
+  return {
+    uid: prop(function () { return String(ev.uid()); }, null),
+    summary: prop(function () { return String(ev.summary()); }, null),
+    startDate: iso(prop(function () { return ev.startDate(); }, null)),
+    endDate: iso(prop(function () { return ev.endDate(); }, null)),
+    alldayEvent: prop(function () { return ev.alldayEvent(); }, false),
+    location: prop(function () { var v = ev.location(); return v === null ? null : String(v); }, null),
+    description: prop(function () { var v = ev.description(); return v === null ? null : String(v); }, null),
+    url: prop(function () { var v = ev.url(); return v === null ? null : String(v); }, null),
+    stampDate: iso(prop(function () { return ev.stampDate(); }, null)),
+    // No calendarUid: cal.uid() throws on every calendar (see findCalendar).
+    // The caller already knows which calendar it targeted, and re-derives the
+    // store uuid from this name.
+    calendarName: prop(function () { return String(cal.name()); }, null)
+  };
+}
+
+/**
+ * Apply the optional fields a create and an update have in common.
+ *
+ * ## The dates go first, and in an order that is never briefly invalid
+ *
+ * MEASURED: moving an event later failed with
+ *
+ *     Failed to save event [...], with error
+ *     [{ NSLocalizedDescription = "The start date must be before the end date." }]
+ *
+ * because start and end are two assignments, not one. Setting start to 16:00 on
+ * an event still ending at 15:30 makes the interval invalid, and EventKit
+ * validates on save rather than on assignment. Which order is safe depends on
+ * which way the event is moving, so the current end decides: moving later, the
+ * end is pushed out first; moving earlier, the start is pulled back first.
+ *
+ * They also go BEFORE the text fields. Apple Events has no transaction, so a
+ * failure part-way through leaves whatever already applied — and the first
+ * version of this wrote the new location, then failed on the dates, leaving the
+ * event half-updated. Doing the fragile part first means a date failure changes
+ * nothing else.
+ */
+function applyFields(ev, f) {
+  var newStart = f.startDate !== undefined && f.startDate !== null ? new Date(f.startDate) : null;
+  var newEnd = f.endDate !== undefined && f.endDate !== null ? new Date(f.endDate) : null;
+
+  if (newStart !== null && newEnd !== null) {
+    var currentEnd = prop(function () { return ev.endDate(); }, null);
+    var movingLater = currentEnd === null || newEnd.getTime() >= currentEnd.getTime();
+    if (movingLater) {
+      ev.endDate = newEnd;
+      ev.startDate = newStart;
+    } else {
+      ev.startDate = newStart;
+      ev.endDate = newEnd;
+    }
+  } else if (newStart !== null) {
+    ev.startDate = newStart;
+  } else if (newEnd !== null) {
+    ev.endDate = newEnd;
+  }
+
+  if (f.allDay !== undefined && f.allDay !== null) ev.alldayEvent = Boolean(f.allDay);
+  if (f.summary !== undefined && f.summary !== null) ev.summary = String(f.summary);
+  if (f.location !== undefined) ev.location = f.location === null ? "" : String(f.location);
+  if (f.description !== undefined) ev.description = f.description === null ? "" : String(f.description);
+  if (f.url !== undefined) ev.url = f.url === null ? "" : String(f.url);
+}
+`;
+/**
+* Wrap a script body in the prelude and the liveness gate.
+*
+* Every script in `write.ts` sets `allowLaunch`, and that is not an oversight:
+* a write is a deliberate side effect, so launching Calendar to perform one is
+* expected in a way that launching it for a read never is. There are no read
+* scripts here to keep it false for.
+*/
+const script = (body, opts = {}) => `
+${PRELUDE}
+function run(argv) {
+  var p = JSON.parse(argv[0] || "{}");
+  if (!isCalendarRunning() && !${opts.allowLaunch ? "true" : "false"}) {
+    return err("APP_NOT_RUNNING", "Calendar is not running.");
+  }
+  try {
+    var C = Application("Calendar");
+    ${body}
+  } catch (e) {
+    var msg = String(e && e.message ? e.message : e);
+    if (msg.indexOf("-1743") !== -1) return err("NOT_AUTHORIZED", msg);
+    return err("SCRIPT_ERROR", msg);
+  }
+}
+`;
+//#endregion
+//#region src/client/jxa/write.ts
+/**
+* Mutating scripts.
+*
+* These are the only place Calendar is asked to change anything, and every one
+* re-reads the affected event afterwards: what a tool returns is what Calendar
+* STORED, never what the caller requested. The two differ more often than you
+* would expect — setting `alldayEvent` reshapes the start and end, and Calendar
+* decides the final values, not us.
+*
+* Dates arrive as ISO-8601 strings carrying an explicit offset (see `dates.ts`)
+* and are turned back into Date objects here. Passing a bare local string would
+* have Calendar resolve it in whatever zone it feels like.
+*
+* ## Real side effects, said plainly
+*
+* A create on a CalDAV or Exchange calendar syncs within seconds and other
+* people see it. There is no draft state and no undo. That is why the tools
+* that call these carry the warning in their descriptions, and why attendees
+* are not a parameter anywhere in this file: adding one emails a human.
+*/
+const CREATE_EVENT = script(`
+  var cal = findCalendar(C, p.calendar);
+  if (!cal) return err("CALENDAR_NOT_FOUND", p.calendar || "(default)");
+  if (!isWritable(cal)) return err("CALENDAR_NOT_WRITABLE", prop(function () { return String(cal.name()); }, "?"));
+
+  // Build with the required dates, push, THEN apply the optional fields.
+  // An object that is not yet in a container has nowhere to store a property,
+  // so assignments made before the push are silently lost.
+  var ev = C.Event({
+    summary: String(p.summary),
+    startDate: new Date(p.startDate),
+    endDate: new Date(p.endDate)
+  });
+  cal.events.push(ev);
+  applyFields(ev, p);
+
+  return ok(readback(ev, cal));
+`, { allowLaunch: true });
+const UPDATE_EVENT = script(`
+  var cal = findCalendar(C, p.calendar);
+  if (!cal) return err("CALENDAR_NOT_FOUND", p.calendar || "(default)");
+  if (!isWritable(cal)) return err("CALENDAR_NOT_WRITABLE", prop(function () { return String(cal.name()); }, "?"));
+
+  var ev = findEvent(cal, String(p.uid));
+  if (!ev) return err("EVENT_NOT_FOUND", String(p.uid));
+
+  applyFields(ev, p);
+  return ok(readback(ev, cal));
+`, { allowLaunch: true });
+/**
+* Delete whole events, and VERIFY that each one actually went.
+*
+* MEASURED, macOS 26.6: `C.delete(ev)` on a RECURRING event neither throws nor
+* deletes. Event count before 1, after 1, still present — while the same call
+* removes a non-repeating event correctly. Trusting "it did not throw" therefore
+* reported `deleted: true` for an event that is still on the calendar, which is
+* the worst thing a delete can say.
+*
+* So the uid list is re-read afterwards and `deleted` is decided by ABSENCE.
+* The sibling script that excluded one occurrence had this check from the start
+* and it is what caught that property being broken; this one did not, and this
+* is what that omission cost.
+*
+* Per-id results rather than a bulk throw: deleting five events where the third
+* has already gone should remove four and say which one was missing.
+*/
+const DELETE_EVENTS = script(`
+  var cal = findCalendar(C, p.calendar);
+  if (!cal) return err("CALENDAR_NOT_FOUND", p.calendar || "(default)");
+  if (!isWritable(cal)) return err("CALENDAR_NOT_WRITABLE", prop(function () { return String(cal.name()); }, "?"));
+
+  var results = [];
+  for (var i = 0; i < p.uids.length; i++) {
+    var uid = String(p.uids[i]);
+    var ev = findEvent(cal, uid);
+    if (!ev) {
+      results.push({ uid: uid, found: false, deleted: false, repeats: false });
+      continue;
+    }
+    var repeats = false;
+    try {
+      var r = ev.recurrence();
+      repeats = r !== null && r !== undefined && String(r) !== "";
+    } catch (e) {
+      repeats = false;
+    }
+    var threw = null;
+    try { C.delete(ev); } catch (e) { threw = String(e).slice(0, 120); }
+    results.push({ uid: uid, found: true, deleted: null, repeats: repeats, error: threw });
+  }
+
+  // ONE bulk re-read decides the truth for every id at once.
+  var after = prop(function () { return cal.events.uid(); }, null);
+  for (var j = 0; j < results.length; j++) {
+    if (!results[j].found) continue;
+    if (after === null) {
+      results[j].deleted = null;
+      results[j].reason = "could not re-read the calendar to confirm";
+      continue;
+    }
+    var gone = true;
+    for (var k = 0; k < after.length; k++) {
+      if (String(after[k]) === results[j].uid) gone = false;
+    }
+    results[j].deleted = gone;
+    if (!gone) {
+      results[j].reason = results[j].repeats
+        ? "Calendar did not delete it and reported no error, which is what it does for a repeating event. Delete it in Calendar.app."
+        : "Calendar reported no error but the event is still there.";
+    }
+  }
+  return ok({ results: results });
+`, { allowLaunch: true });
+/**
+* REMOVED: excluding one occurrence, which Calendar cannot do.
+*
+* MEASURED, macOS 26.6, against a real repeating event:
+*
+*   ev.excludedDates()            -> ["1903-12-31T23:50:39.000Z"]
+*   ev.excludedDates = [aDate]    -> TypeError: undefined is not an object
+*
+* The read returns a sentinel rather than the empty list the event actually
+* has, and the assignment throws — while `ev.summary = "x"` on the very same
+* specifier works, so this is the property, not the specifier or the lane.
+*
+* A script was written here that assigned the whole array back and then read it
+* again to confirm, precisely because a silent no-op on a delete is the worst
+* lie this surface could tell. The verification worked: it caught this. But a
+* write path that can only ever report failure is not a capability, so the tool
+* no longer offers "delete one occurrence" at all — `delete_events` refuses an
+* occurrence ref and says why, which is the same shape as `update_event`.
+*
+* Deleting a single occurrence is possible in Calendar.app itself, so this is a
+* limit of the scripting interface rather than of the data.
+*/
+//#endregion
+//#region src/client/locate.ts
+/**
+* Find Calendar's store.
+*
+* ## Why this is the easy case
+*
+* Reminders keeps its database under a generated directory name, so resolving
+* it means *listing* a protected directory — which is itself the privileged
+* operation, leaving no path to even stat without the grant. Calendar does not:
+*
+*     ~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb
+*
+* is a constant. `statSync` succeeds on a TCC-protected file (only `access(2)`
+* is denied — see packages/core/src/fs.ts), so this locator can tell "exists but
+* unreadable" from "not there at all" with no permission whatsoever. Those are
+* different failures with different fixes, and saying so is most of what
+* diagnostics is for.
+*
+* ## Why it still walks the container
+*
+* `docs/calendar.md` recorded per-account stores sitting beside the main one,
+* and the probe picked between them by size. The known filename is *preferred*,
+* so the common case costs one `describeStore` and no listing at all; the walk
+* is a fallback for a machine whose layout differs, and for the day Apple moves
+* the file the way it moved Reminders' out of `~/Library/Reminders`.
+*/
+/** `group.com.apple.calendar`, under `~/Library/Group Containers`. */
+const GROUP_CONTAINER = "group.com.apple.calendar";
+/** The observed filename. Preferred when present; not required. */
+const STORE_FILENAME = "Calendar.sqlitedb";
+/** Sits beside the store. 32 KB, and its contents are not used by this server. */
+const EXTRAS_FILENAME = "Extras.db";
+/** Depth cap for the fallback walk. The real store sits at depth 0. */
+const MAX_DEPTH = 3;
+const STORE_SUFFIX = /\.(sqlitedb|sqlite)$/i;
+const defaultContainerPath = (home = homedir()) => join(home, "Library", "Group Containers", GROUP_CONTAINER);
+const defaultStorePath = (home = homedir()) => join(defaultContainerPath(home), STORE_FILENAME);
+const listDir = (dir) => {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).flatMap((e) => e.isDirectory() ? [] : [e.name]);
+	} catch {
+		return [];
+	}
+};
+const walk = (dir, depth, out) => {
+	if (depth > MAX_DEPTH) return out;
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const e of entries) {
+		const p = join(dir, e.name);
+		if (e.isDirectory()) walk(p, depth + 1, out);
+		else if (STORE_SUFFIX.test(e.name)) out.push(p);
+	}
+	return out;
+};
+const FDA_HINT = "Grant Full Disk Access to the app running this server (System Settings > Privacy & Security > Full Disk Access) and restart it. Granting it to Calendar.app does nothing — the reader needs the permission.";
+const locateStore = (opts = {}) => {
+	const containerPath = defaultContainerPath(opts.home);
+	if (opts.storePath) {
+		const facts = describeStore(opts.storePath);
+		return {
+			...facts,
+			containerPath,
+			storePath: opts.storePath,
+			candidates: [{
+				...facts,
+				path: opts.storePath
+			}],
+			containerListable: true,
+			extrasPresent: false,
+			reason: facts.readable ? null : facts.exists ? `The store at ${opts.storePath} exists but cannot be read. ${FDA_HINT}` : `No file at ${opts.storePath}. APPLE_CALENDAR_STORE points at nothing.`
+		};
+	}
+	const known = defaultStorePath(opts.home);
+	const knownFacts = describeStore(known);
+	const listing = listDir(containerPath);
+	const containerListable = listing.length > 0;
+	const extrasPresent = listing.includes(EXTRAS_FILENAME);
+	const paths = knownFacts.readable ? [known] : walk(containerPath, 0, []);
+	const candidates = (paths.includes(known) ? paths : [known, ...paths]).map((p) => ({
+		...describeStore(p),
+		path: p
+	})).filter((c) => c.exists).toSorted((a, b) => (b.size ?? 0) - (a.size ?? 0));
+	const chosen = knownFacts.readable ? {
+		...knownFacts,
+		path: known
+	} : candidates.find((c) => c.readable) ?? candidates[0] ?? null;
+	const reason = chosen?.readable ? null : knownFacts.exists ? `Found the Calendar store at ${known} but cannot read it. ${FDA_HINT}` : containerListable ? `No store file under ${containerPath}. Has Calendar ever been set up on this account?` : `Neither ${known} nor its container could be reached. If Calendar is set up on this account this is a permission problem. ${FDA_HINT}`;
+	return {
+		...chosen ? {
+			exists: chosen.exists,
+			readable: chosen.readable,
+			size: chosen.size,
+			mtime: chosen.mtime,
+			walPresent: chosen.walPresent,
+			walSizeBytes: chosen.walSizeBytes
+		} : knownFacts,
+		containerPath,
+		storePath: chosen?.path ?? null,
+		candidates,
+		containerListable,
+		extrasPresent,
+		reason
+	};
+};
+//#endregion
+//#region src/client/recurrence.ts
+/**
+* Merging the two legs of a range query, and saying honestly what the result
+* does not cover.
+*
+* ## Why this is its own module
+*
+* It is the piece most likely to be rewritten. `store.ts` knows how to ask the
+* database questions; this file encodes what the answers MEAN, and that meaning
+* rests on measurements (`docs/calendar.md`) rather than on documentation Apple
+* publishes. Keeping it separate means a future correction swaps this file
+* rather than picking through SQL.
+*
+* ## Why a merge is needed at all
+*
+* Measured: `OccurrenceCache` holds 489 distinct parents, of which **456 carry
+* no recurrence rule**. So the cache is not "the repeating events" — it holds
+* plain one-shot events too, and a naive union of "items" and "occurrences"
+* double-counts most of an ordinary calendar. Dedupe here is load-bearing, not
+* defensive.
+*
+* ## Why the coverage edge is published rather than hidden
+*
+* The cache reaches about two years either side of today on the probed store,
+* which is a real expansion rather than a month-view cache. It is still an edge.
+* A query running past it gets fewer repeating events than it should, and a
+* short list of events is indistinguishable from a free afternoon — the quietest
+* possible failure on this surface. So the edge travels with the result.
+*/
+/**
+* Identity for deduping.
+*
+* `(uuid, rendered start)` rather than uuid alone: two occurrences of the same
+* series are the same event at different times, and collapsing them by uuid
+* would return a weekly meeting once — the exact bug the two-leg design exists
+* to avoid.
+*
+* ## Why the RENDERED start and not the raw column
+*
+* MEASURED, against a live calendar: an all-day event created through this
+* server came back TWICE — once from each leg, same uuid, both rendering as
+* 17 September. `CalendarItem.start_date` and `OccurrenceCache.occurrence_date`
+* do not hold the identical number for an all-day event, so a key built on the
+* raw value saw two different events and let both through.
+*
+* Rendering first collapses that: two all-day rows for one uuid on one DAY are
+* the same event, whatever the two columns disagree about underneath. For a
+* timed event the rendered ISO is second-precision, which also absorbs the
+* float wobble a REAL column can introduce.
+*/
+const keyOf = (r, epochOffset) => {
+	const at = renderInstant(r.startApple, r.startTz, r.allDay, epochOffset);
+	const when = at ? at.allDay ? at.day : at.iso : String(r.startApple);
+	return `${String(r.uuid).toUpperCase()}|${when}`;
+};
+/**
+* The identity of the occurrence a detached row REPLACES.
+*
+* When someone drags one instance of a series to a new time, Calendar writes a
+* detached `CalendarItem` carrying `orig_item_id` (the series) and `orig_date`
+* (the slot it came from). The stale cache row for that slot may still exist, so
+* keying on `(uuid, start)` alone will not catch it: the instants differ, which
+* is the entire point of the move.
+*/
+const replacedKeyOf = (r) => r.origItemPk !== null && r.origDateApple !== null ? `${r.origItemPk}|${r.origDateApple}` : null;
+const occurrenceSlotOf = (r) => `${r.itemPk}|${r.startApple}`;
+const mergeRange = (opts) => {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	let dropped = 0;
+	const replaced = /* @__PURE__ */ new Set();
+	for (const r of opts.items) {
+		const k = replacedKeyOf(r);
+		if (k) replaced.add(k);
+	}
+	for (const r of [...opts.items, ...opts.occurrences]) {
+		if (r.startApple === null) {
+			dropped += 1;
+			continue;
+		}
+		if (r.source === "occurrence" && replaced.has(occurrenceSlotOf(r))) continue;
+		const k = keyOf(r, opts.epochOffset);
+		if (seen.has(k)) continue;
+		seen.add(k);
+		out.push(r);
+	}
+	out.sort((a, b) => (a.startApple ?? 0) - (b.startApple ?? 0));
+	const merged = {
+		rows: out.slice(0, opts.limit),
+		expansion: opts.hasOccurrenceCache ? "expanded" : "unavailable",
+		coverage: opts.coverage,
+		dropped
+	};
+	if (!opts.hasOccurrenceCache) {
+		merged.expansionReason = opts.unavailableReason ?? "this store has no OccurrenceCache table, so occurrences of repeating events are not expanded; each repeating event appears once, at its series start";
+		return merged;
+	}
+	const cov = opts.coverage;
+	if (cov) {
+		const past = opts.fromApple < cov.fromApple;
+		const future = opts.toApple > cov.toApple;
+		if (past || future) merged.truncated = {
+			reason: "the requested window extends past the range the store has expanded, so repeating events outside it are missing from this result",
+			...past ? { uncoveredFromApple: opts.fromApple } : {},
+			...future ? { uncoveredToApple: opts.toApple } : {},
+			affects: "repeating events only — single events are correct at any distance"
+		};
+	}
+	return merged;
+};
+//#endregion
+//#region src/client/ref.ts
+/**
+* CalendarRef — the one identifier any tool accepts or returns.
+*
+* Wire format:  c1:<calendarUid>/<occurrence>/<eventUid>
+*
+*   calendarUid  `Calendar.UUID`. Always a UUID in this store.
+*   occurrence   "-" for a single event or a whole series, otherwise the
+*                occurrence start as ISO-8601 basic with offset,
+*                e.g. 20260821T090000+0200.
+*   eventUid     `CalendarItem.UUID`, verbatim, as the greedy tail.
+*
+* The `c1:` prefix follows the same reasoning as Notes' `n1:` and Reminders'
+* `r1:`: if the scheme ever changes, a versioned prefix makes that an additive
+* change instead of a silent reinterpretation of every ref already sitting in a
+* conversation.
+*
+* ## Why the uid is the greedy tail, and why `@` is not a separator
+*
+* `docs/calendar.md` measured the id bridge on an iCloud account, where every
+* uid is a bare UUID. That is a property of the ACCOUNT, not of Calendar: a
+* Google event's uid looks like `abc123def@google.com`, and an Exchange one is
+* a long hex blob. Requiring a UUID here would work perfectly on the machine it
+* was written on and fail completely on anyone else's — so the uid is carried
+* through verbatim and the UUID is only extracted opportunistically.
+*
+* That also rules out `@` as a field separator, which is otherwise the obvious
+* choice for pinning an occurrence to a time.
+*
+* ## Why the calendar uid rides along
+*
+* Calendar's scripting dictionary has no `events.byId()`. Finding an event over
+* Apple Events means either `whose({uid})` — measured at 4.5-7.3 s and, worse,
+* UNSTABLE across runs — or one bulk `cal.events.uid()` fetch and an index in
+* JS, at about 1.8 s. The bulk fetch is only affordable if it is scoped to ONE
+* calendar, so every write narrows by calendar before it scans.
+*
+* That is a concrete thing the file lane hands the write lane: the store knows
+* which calendar an event is in, so Apple Events never has to search for it.
+*/
+const REF_VERSION = "c1";
+/** Used to FIND a uuid inside an id, never to require one. */
+const UUID = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i;
+/** `20260821T090000+0200` / `20260821T070000Z` — ISO-8601 basic. */
+const BASIC = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z|[+-]\d{4})$/;
+const SEPARATOR = "/";
+const NO_OCCURRENCE = "-";
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+/** The inverse of BASIC: local wall clock plus its offset, no punctuation. */
+const toBasic = (d) => {
+	const mins = -d.getTimezoneOffset();
+	const sign = mins < 0 ? "-" : "+";
+	const abs = Math.abs(mins);
+	const zone = mins === 0 ? "Z" : `${sign}${pad(Math.floor(abs / 60))}${pad(abs % 60)}`;
+	return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}T${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}${zone}`;
+};
+const fromBasic = (text) => {
+	const m = BASIC.exec(text);
+	if (!m) return null;
+	const [, y, mo, d, hh, mm, ss, zone] = m;
+	const iso = `${y}-${mo}-${d}T${hh}:${mm}:${ss}` + (zone === "Z" ? "Z" : `${zone.slice(0, 3)}:${zone.slice(3)}`);
+	const when = new Date(iso);
+	return Number.isNaN(when.getTime()) ? null : when;
+};
+const encodeRef = (calendarUid, eventUid, occurrenceStart) => [
+	"c1:" + String(calendarUid ?? ""),
+	occurrenceStart ? toBasic(occurrenceStart) : NO_OCCURRENCE,
+	String(eventUid ?? "")
+].join(SEPARATOR);
+const decodeRef = (raw) => {
+	const text = String(raw ?? "");
+	const colon = text.indexOf(":");
+	const version = colon === -1 ? "" : text.slice(0, colon);
+	if (version !== "c1") {
+		if (/^[a-z]\d+$/.test(version)) throw new PreconditionError(`That is a "${version}:" ref, which belongs to another surface. This server issues "c1:" refs — get one from apple_calendar_list_events or apple_calendar_search_events.`);
+		throw new PreconditionError(`Malformed calendar ref ${JSON.stringify(raw)}. Refs come from the search and list tools — construct them from those results rather than by hand.`, { expected: `c1:<calendarUid>/<occurrence>/<eventUid>` });
+	}
+	const body = text.slice(colon + 1);
+	const first = body.indexOf(SEPARATOR);
+	const second = body.indexOf(SEPARATOR, first + 1);
+	if (first === -1 || second === -1) throw new PreconditionError(`Malformed calendar ref ${JSON.stringify(raw)}: expected two "${SEPARATOR}" separators.`, { expected: `c1:<calendarUid>/<occurrence>/<eventUid>` });
+	const calendarUid = body.slice(0, first);
+	const occurrence = body.slice(first + 1, second);
+	const eventUid = body.slice(second + 1);
+	if (!eventUid) throw new PreconditionError(`Malformed calendar ref ${JSON.stringify(raw)}: it names no event.`, { expected: `c1:<calendarUid>/<occurrence>/<eventUid>` });
+	const occurrenceStart = occurrence === NO_OCCURRENCE ? null : fromBasic(occurrence);
+	if (occurrence !== NO_OCCURRENCE && !occurrenceStart) throw new PreconditionError(`Malformed calendar ref ${JSON.stringify(raw)}: ${JSON.stringify(occurrence)} is not an occurrence start. Expected ISO-8601 basic, e.g. 20260821T090000+0200, or "-".`);
+	return {
+		calendarUid,
+		eventUid,
+		occurrenceStart,
+		isOccurrence: occurrenceStart !== null
+	};
+};
+/** The series a ref belongs to. Identity for a ref that is already a series. */
+const seriesRefOf = (ref) => encodeRef(ref.calendarUid, ref.eventUid);
+/** The bare UUID inside an id, when there is one. Null is legitimate, not an error. */
+const uuidOf = (id) => UUID.exec(String(id ?? ""))?.[1]?.toUpperCase() ?? null;
+//#endregion
+//#region src/client/store.ts
+/**
+* Calendar's file lane.
+*
+* ## Why there is a file lane at all
+*
+* Unlike Notes and Reminders, this one is justified on SPEED rather than
+* capability. `docs/calendar.md` measured a ±90-day range query over Apple
+* Events at 3.4 s across 1,349 events, with the cost falling per round trip
+* rather than per event (~1.8-2.2 s per property, flat), so no amount of
+* batching rescues it. Calendar's scripting dictionary is unusually complete —
+* attendees, alarms and recurrence are all in it — so the usual "the store buys
+* you the rich stuff" argument is much weaker here than elsewhere. The store is
+* how a range query returns before the caller gives up.
+*
+* ## What is measured, and what is not
+*
+* Measured (`docs/calendar.md`): the store is
+* `~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb`, it is
+* plain Core Data with no `Z_PRIMARYKEY`, the main table is `CalendarItem`, and
+* the id bridge to Apple Events is exact — `CalendarItem.UUID` against the `uid`
+* Calendar hands back, 198/198 sampled.
+*
+* NOT yet measured, and the reason this file introspects but does not query:
+* `OccurrenceCache` (1,946 rows) and `OccurrenceCacheDays` (2,630) both out-row
+* `CalendarItem` (1,350), which means expanded recurrences live outside the main
+* table and a naive `SELECT ... FROM CalendarItem` returns a weekly standup
+* once. `scripts/probe-calendar.mjs` was extended to settle that with a set diff
+* against Apple Events; until it has run on a machine with Full Disk Access,
+* shipping a range query would be guessing at the one thing that fails silently.
+* A short list is indistinguishable from a free afternoon.
+*/
+/** Tables the lane cannot work without. Anything else degrades to a null field. */
+const REQUIRED = ["CalendarItem", "Calendar"];
+/**
+* The schema this was written against. Named in the drift error, not enforced.
+*
+* CAUTION: this is the PROBE's fingerprint and it is NOT comparable to the one
+* `diagnostics` reports. `fingerprintSchema` in packages/core orders
+* sqlite_master by `type, name`; `dumpSchema` in scripts/lib/probe-kit.mjs
+* orders it by a CASE expression putting tables before indexes, so the same
+* schema hashes to two different values. Measured here: this store reports
+* cd2424fea732 at runtime against the 2bf4e34ff75f docs/calendar.md recorded
+* from the probe, and Reminders shows the same split (510062aad004 at runtime
+* against the 278b001e3c55 in its own drift message and in docs/verify.md).
+*
+* So compare a probe fingerprint with a probe fingerprint. Reconciling the two
+* orderings is a one-line change in packages/core, but it moves the value for
+* every surface at once and is therefore its own decision.
+*/
+const PROBED_FINGERPRINT = "2bf4e34ff75f";
+const PROBED_MACOS = "26.6";
+const bool = (v) => v === 1 || v === true;
+const num = (v) => typeof v === "number" ? v : null;
+const text = (v) => typeof v === "string" ? v : null;
+var CalendarStore = class {
+	db;
+	mode;
+	caps;
+	constructor(db, mode, caps) {
+		this.db = db;
+		this.mode = mode;
+		this.caps = caps;
+	}
+	/**
+	* Project a column, or a typed NULL when this store does not have it.
+	*
+	* The same guard `packages/reminders/src/client/store.ts` uses, and for the
+	* same reason: the schema is reverse-engineered and unversioned, so an Apple
+	* rename should cost one field rather than the whole lane.
+	*/
+	#col(present, table, name, alias = name) {
+		return present.has(name) ? `${table}."${name}" AS ${alias}` : `NULL AS ${alias}`;
+	}
+	#itemColumns() {
+		const c = this.caps.itemColumns;
+		return [
+			`ci."ROWID" AS itemPk`,
+			this.#col(c, "ci", "UUID", "uuid"),
+			this.#col(c, "ci", "summary", "summary"),
+			this.#col(c, "ci", "description", "description"),
+			this.#col(c, "ci", "url", "url"),
+			this.#col(c, "ci", "conference_url", "conferenceUrl"),
+			this.#col(c, "ci", "all_day", "allDay"),
+			this.#col(c, "ci", "start_tz", "startTz"),
+			this.#col(c, "ci", "end_tz", "endTz"),
+			this.#col(c, "ci", "status", "status"),
+			this.#col(c, "ci", "invitation_status", "invitationStatus"),
+			this.#col(c, "ci", "availability", "availability"),
+			this.#col(c, "ci", "has_recurrences", "hasRecurrences"),
+			this.#col(c, "ci", "has_attendees", "hasAttendees"),
+			this.#col(c, "ci", "orig_item_id", "origItemPk"),
+			this.#col(c, "ci", "orig_date", "origDateApple"),
+			this.#col(c, "ci", "calendar_id", "calendarPk"),
+			`cal."UUID" AS calendarUuid`,
+			`cal."title" AS calendarTitle`,
+			this.caps.hasLocation ? `loc."title" AS locationTitle` : `NULL AS locationTitle`
+		].join(",\n         ");
+	}
+	#joins() {
+		return `JOIN "Calendar" cal ON cal."ROWID" = ci."calendar_id"${this.caps.hasLocation && this.caps.itemColumns.has("location_id") ? `\n    LEFT JOIN "Location" loc ON loc."ROWID" = ci."location_id"` : ""}`;
+	}
+	/**
+	* Rows this lane must never return, whichever leg found them.
+	*
+	* `entity_type` is 2 for events. The probed store holds nothing else — 0 rows
+	* carry a due date or a completion date — but `CalendarItem` shares its schema
+	* with Reminders, so the predicate is cheap insurance rather than dead code.
+	*
+	* `hidden` and `phantom_master` are INFERRED rather than measured. A phantom
+	* master is the placeholder row EventKit keeps for a series whose occurrences
+	* have all been detached; showing it would put an event on the calendar that
+	* Calendar.app does not draw. Both are excluded conservatively, and both are
+	* on the list for the next probe run to confirm.
+	*/
+	#excluded(alias = "ci") {
+		const c = this.caps.itemColumns;
+		const out = [];
+		if (c.has("entity_type")) out.push(`${alias}."entity_type" = 2`);
+		if (c.has("hidden")) out.push(`(${alias}."hidden" IS NULL OR ${alias}."hidden" = 0)`);
+		if (c.has("phantom_master")) out.push(`(${alias}."phantom_master" IS NULL OR ${alias}."phantom_master" = 0)`);
+		return out.length ? `AND ${out.join("\n            AND ")}` : "";
+	}
+	#calendarFilter(uuids) {
+		if (!uuids?.length) return {
+			sql: "",
+			params: []
+		};
+		return {
+			sql: `AND cal."UUID" IN (${uuids.map(() => "?").join(", ")})`,
+			params: [...uuids]
+		};
+	}
+	#rowsFrom(sql, params, source) {
+		return this.db.prepare(sql).all(...params).map((r) => ({
+			itemPk: Number(r.itemPk),
+			uuid: text(r.uuid),
+			calendarPk: num(r.calendarPk),
+			calendarUuid: text(r.calendarUuid),
+			calendarTitle: text(r.calendarTitle),
+			summary: text(r.summary),
+			description: text(r.description),
+			url: text(r.url),
+			conferenceUrl: text(r.conferenceUrl),
+			locationTitle: text(r.locationTitle),
+			startApple: num(r.startApple),
+			endApple: num(r.endApple),
+			allDay: bool(r.allDay),
+			startTz: text(r.startTz),
+			endTz: text(r.endTz),
+			status: num(r.status),
+			invitationStatus: num(r.invitationStatus),
+			availability: num(r.availability),
+			hasRecurrences: bool(r.hasRecurrences),
+			hasAttendees: bool(r.hasAttendees),
+			origItemPk: num(r.origItemPk),
+			origDateApple: num(r.origDateApple),
+			source
+		}));
+	}
+	/**
+	* LEG 1 — items carried by the table itself.
+	*
+	* Overlap, not containment: `start < to AND COALESCE(end, start) > from`. A
+	* naive `BETWEEN` on the start silently drops the all-hands that began at
+	* 09:00 when the caller asked about 10:00 onward.
+	*
+	* Items whose occurrences are expanded in the cache are excluded here and
+	* picked up by leg 2, so a repeating event is not also returned once at its
+	* master start.
+	*/
+	rangeItems(q) {
+		const c = this.caps.itemColumns;
+		if (!c.has("start_date")) return [];
+		const cal = this.#calendarFilter(q.calendarUuids);
+		const endExpr = c.has("end_date") ? `COALESCE(ci."end_date", ci."start_date")` : `ci."start_date"`;
+		const notExpanded = c.has("has_recurrences") ? `AND (ci."has_recurrences" IS NULL OR ci."has_recurrences" = 0)` : this.caps.hasRecurrence ? `AND NOT EXISTS (SELECT 1 FROM "Recurrence" r WHERE r."owner_id" = ci."ROWID")` : "";
+		const sql = `
+      SELECT ci."start_date" AS startApple,
+             ${c.has("end_date") ? `ci."end_date"` : `NULL`} AS endApple,
+             ${this.#itemColumns()}
+        FROM "CalendarItem" ci
+        ${this.#joins()}
+       WHERE ci."start_date" < ?
+         AND ${endExpr} > ?
+         ${notExpanded}
+         ${this.#excluded()}
+         ${cal.sql}
+       ORDER BY ci."start_date" ASC
+       LIMIT ?`;
+		return this.#rowsFrom(sql, [
+			q.toApple,
+			q.fromApple,
+			...cal.params,
+			q.limit
+		], "item");
+	}
+	/**
+	* LEG 2 — expanded occurrences.
+	*
+	* `OccurrenceCache.event_id` -> `CalendarItem.ROWID` was measured at a 100%
+	* resolve rate. `occurrence_date` is the start; `occurrence_start_date` exists
+	* too and reaches only +256 days against `occurrence_date`'s +724, so using it
+	* would silently truncate the far half of the window.
+	*/
+	rangeOccurrences(q) {
+		if (!this.caps.hasOccurrenceCache) return [];
+		const o = this.caps.occurrenceColumns;
+		if (!o.has("occurrence_date") || !o.has("event_id")) return [];
+		const cal = this.#calendarFilter(q.calendarUuids);
+		const endExpr = o.has("occurrence_end_date") ? `COALESCE(oc."occurrence_end_date", oc."occurrence_date")` : `oc."occurrence_date"`;
+		const sql = `
+      SELECT oc."occurrence_date" AS startApple,
+             ${o.has("occurrence_end_date") ? `oc."occurrence_end_date"` : `NULL`} AS endApple,
+             ${this.#itemColumns()}
+        FROM "OccurrenceCache" oc
+        JOIN "CalendarItem" ci ON ci."ROWID" = oc."event_id"
+        ${this.#joins()}
+       WHERE oc."occurrence_date" < ?
+         AND ${endExpr} > ?
+         ${this.#excluded()}
+         ${cal.sql}
+       ORDER BY oc."occurrence_date" ASC
+       LIMIT ?`;
+		return this.#rowsFrom(sql, [
+			q.toApple,
+			q.fromApple,
+			...cal.params,
+			q.limit
+		], "occurrence");
+	}
+	/**
+	* Text search, unbounded in time by default.
+	*
+	* Searching is the one place a caller legitimately wants all of history, so
+	* the window is the caller's to set rather than a default. Runs over items
+	* only: an occurrence carries no text of its own, and matching the series once
+	* is what a search result should be.
+	*/
+	searchItems(q) {
+		const c = this.caps.itemColumns;
+		const cal = this.#calendarFilter(q.calendarUuids);
+		const needle = `%${escapeLike(q.text)}%`;
+		const fields = ["summary"];
+		if (q.scope === "full") {
+			if (c.has("description")) fields.push("description");
+			if (this.caps.hasLocation) fields.push("__location");
+		}
+		const match = fields.map((f) => f === "__location" ? `loc."title" LIKE ? ESCAPE '\\'` : `ci."${f}" LIKE ? ESCAPE '\\'`).join(" OR ");
+		const sql = `
+      SELECT ci."start_date" AS startApple,
+             ${c.has("end_date") ? `ci."end_date"` : `NULL`} AS endApple,
+             ${this.#itemColumns()}
+        FROM "CalendarItem" ci
+        ${this.#joins()}
+       WHERE (${match})
+         AND ci."start_date" < ?
+         AND COALESCE(ci."end_date", ci."start_date") > ?
+         ${this.#excluded()}
+         ${cal.sql}
+       ORDER BY ci."start_date" DESC
+       LIMIT ?`;
+		const params = [
+			...fields.map(() => needle),
+			q.toApple,
+			q.fromApple,
+			...cal.params,
+			q.limit
+		];
+		return this.#rowsFrom(sql, params, "item");
+	}
+	/** One event by its Apple Events uid. The bridge measured 198/198 exact. */
+	byUuid(uuid) {
+		const c = this.caps.itemColumns;
+		if (!c.has("UUID")) return null;
+		const sql = `
+      SELECT ci."start_date" AS startApple,
+             ${c.has("end_date") ? `ci."end_date"` : `NULL`} AS endApple,
+             ${this.#itemColumns()}
+        FROM "CalendarItem" ci
+        ${this.#joins()}
+       WHERE UPPER(ci."UUID") = ?
+         ${this.#excluded()}
+       LIMIT 1`;
+		return this.#rowsFrom(sql, [uuid.toUpperCase()], "item")[0] ?? null;
+	}
+	/**
+	* How far the expansion reaches.
+	*
+	* Published with every range result. Measured at -732 to +724 days on the
+	* probed store, which is a real expansion rather than a month-view cache —
+	* but it is still an edge, and nothing guarantees the next machine's is as
+	* deep. A range running past it must say so rather than return a short list.
+	*/
+	coverage() {
+		if (!this.caps.hasOccurrenceCache || !this.caps.occurrenceColumns.has("occurrence_date")) return null;
+		const row = this.db.prepare(`SELECT MIN("occurrence_date") AS lo, MAX("occurrence_date") AS hi, COUNT(*) AS n
+           FROM "OccurrenceCache" WHERE "occurrence_date" IS NOT NULL`).get();
+		const lo = num(row?.lo);
+		const hi = num(row?.hi);
+		if (lo === null || hi === null) return null;
+		return {
+			fromApple: lo,
+			toApple: hi,
+			rows: Number(row?.n ?? 0)
+		};
+	}
+	calendars() {
+		const c = this.caps.calendarColumns;
+		const store = this.caps.storeColumns.size > 0;
+		const sql = `
+      SELECT ${this.#col(c, "cal", "UUID", "uuid")},
+             ${this.#col(c, "cal", "title", "title")},
+             ${this.#col(c, "cal", "color", "color")},
+             ${this.#col(c, "cal", "type", "type")},
+             ${this.#col(c, "cal", "sharing_status", "sharingStatus")},
+             ${this.#col(c, "cal", "is_published", "isPublished")},
+             ${this.#col(c, "cal", "subcal_url", "subcalUrl")},
+             ${store ? `st."name"` : `NULL`} AS accountName
+        FROM "Calendar" cal
+        ${store ? `LEFT JOIN "Store" st ON st."ROWID" = cal."store_id"` : ""}
+       ORDER BY ${c.has("display_order") ? `cal."display_order" ASC,` : ""} cal."title" ASC`;
+		return this.db.prepare(sql).all().map((r) => ({
+			uuid: text(r.uuid),
+			title: text(r.title),
+			color: text(r.color),
+			type: text(r.type),
+			accountName: text(r.accountName),
+			isSubscribed: Boolean(text(r.subcalUrl)),
+			isPublished: bool(r.isPublished),
+			isShared: (num(r.sharingStatus) ?? 0) > 0,
+			sharingStatus: num(r.sharingStatus)
+		}));
+	}
+	accounts() {
+		if (!this.caps.storeColumns.size) return [];
+		return this.db.prepare(`SELECT st."name" AS name, st."type" AS type, COUNT(cal."ROWID") AS calendars
+           FROM "Store" st
+           LEFT JOIN "Calendar" cal ON cal."store_id" = st."ROWID"
+          GROUP BY st."ROWID"
+          ORDER BY st."name" ASC`).all().map((r) => ({
+			name: text(r.name),
+			type: num(r.type),
+			calendars: Number(r.calendars ?? 0)
+		}));
+	}
+	close() {
+		try {
+			this.db.close();
+		} catch {}
+	}
+};
+const introspect = (db) => {
+	const itemColumns = new Set(columnsOf(db, "CalendarItem"));
+	const calendarColumns = new Set(columnsOf(db, "Calendar"));
+	for (const t of REQUIRED) if ((t === "CalendarItem" ? itemColumns : calendarColumns).size === 0) throw new SchemaDriftError(`This Calendar store has no ${t} table. It was probed on macOS ${PROBED_MACOS} with schema fingerprint ${PROBED_FINGERPRINT} (a PROBE fingerprint — compare it against another probe run, not against the one diagnostics reports); re-run \`pnpm probe:calendar\` to see what changed.`);
+	const occurrenceColumns = new Set(columnsOf(db, "OccurrenceCache"));
+	return {
+		fingerprint: fingerprintSchema(db),
+		itemColumns,
+		calendarColumns,
+		occurrenceColumns,
+		recurrenceColumns: new Set(columnsOf(db, "Recurrence")),
+		storeColumns: new Set(columnsOf(db, "Store")),
+		hasOccurrenceCache: occurrenceColumns.size > 0,
+		hasOccurrenceDays: columnsOf(db, "OccurrenceCacheDays").length > 0,
+		hasRecurrence: columnsOf(db, "Recurrence").length > 0,
+		hasExceptionDates: columnsOf(db, "ExceptionDate").length > 0,
+		hasLocation: columnsOf(db, "Location").length > 0,
+		hasAttachments: columnsOf(db, "Attachment").length > 0,
+		hasParticipants: columnsOf(db, "Participant").length > 0,
+		hasAlarms: columnsOf(db, "Alarm").length > 0,
+		epochOffset: CORE_DATA_EPOCH_OFFSET
+	};
+};
+const openStore = (path, mode, logger) => {
+	if (!path) return null;
+	const { db, mode: used, validated } = openReadOnly(path, mode, {
+		label: "Calendar store",
+		envVar: "APPLE_CALENDAR_INDEX_MODE",
+		validate: introspect,
+		fatal: (err) => err instanceof SchemaDriftError,
+		onFallback: () => logger?.debug?.("opened the Calendar store with immutable=1, which skips the write-ahead log — very recent changes may be missing until Calendar checkpoints.")
+	});
+	return new CalendarStore(db, used, validated);
+};
+//#endregion
+//#region src/client/calendar.ts
+/**
+* EventKit's public status constants, which this store appears to mirror.
+*
+* Taken from the framework rather than measured: `EKEventStatus` and
+* `EKParticipantStatus` are documented API, and a store written by EventKit is
+* overwhelmingly likely to hold the same integers. "Overwhelmingly likely" is
+* not "measured", so both filters are off unless the caller asks, every result
+* reports its own raw `status`, and `diagnostics` says the mapping is inferred.
+* Confirming it is on the probe's list.
+*/
+const STATUS_CANCELLED = 3;
+const PARTICIPANT_DECLINED = 3;
+var AppleCalendarClient = class {
+	config;
+	runner;
+	#logger;
+	#now;
+	#located = null;
+	#store = null;
+	#storeTried = false;
+	constructor(opts) {
+		this.config = opts.config;
+		this.#logger = opts.logger;
+		this.#now = opts.now ?? (() => /* @__PURE__ */ new Date());
+		this.runner = opts.osascript ?? createOsascriptRunner({
+			osascriptPath: opts.config.osascriptPath,
+			timeoutMs: opts.config.osascriptTimeoutMs,
+			surface: CALENDAR_SURFACE,
+			logger: opts.logger
+		});
+	}
+	/** Cached: the answer cannot change without the process being restarted anyway. */
+	locate() {
+		this.#located ??= locateStore({ storePath: this.config.storePath });
+		return this.#located;
+	}
+	/**
+	* The store, opened lazily and at most once.
+	*
+	* Returns null rather than throwing, because "no index" is a state the caller
+	* has to render, not an exception. The reason lives on the locate result.
+	*/
+	index() {
+		if (this.#storeTried) return this.#store;
+		this.#storeTried = true;
+		if (this.config.indexMode === "off") return null;
+		try {
+			this.#store = openStore(this.locate().storePath, this.config.indexMode, this.#logger);
+		} catch (err) {
+			this.#logger?.debug?.("could not open the Calendar store", err);
+			this.#store = null;
+		}
+		return this.#store;
+	}
+	/**
+	* Drop the open handle so the next read reopens.
+	*
+	* Called after a write: Calendar owns the store and reconciles it against a
+	* server, so an event created over Apple Events lands in the file on the
+	* app's schedule, not ours.
+	*/
+	invalidate() {
+		this.#store?.close();
+		this.#store = null;
+		this.#storeTried = false;
+		this.#located = null;
+	}
+	/**
+	* The store, or a structured refusal.
+	*
+	* Never an empty list: Calendar has no Apple Events read lane to fall back to
+	* (`docs/distribution.md`), so "no index" means this server cannot answer at
+	* all — and an empty array would read as an empty calendar, which is the one
+	* answer that must never be invented.
+	*/
+	#require() {
+		const store = this.index();
+		if (store) return store;
+		const located = this.locate();
+		throw new IndexUnavailableError(located.reason ?? "The Calendar store could not be opened, and this surface has no Apple Events read lane to fall back to. Run apple_calendar_diagnostics for the details.");
+	}
+	#toApple(d, store) {
+		return Math.round(d.getTime() / 1e3) - store.caps.epochOffset;
+	}
+	#fromApple(seconds, store) {
+		return (/* @__PURE__ */ new Date((seconds + store.caps.epochOffset) * 1e3)).toISOString();
+	}
+	/** Resolve a caller's calendar name or uid to the uids the SQL filters on. */
+	#calendarUuids(store, named) {
+		const configured = this.config.calendars;
+		const all = store.calendars();
+		const pick = (want) => {
+			const lower = want.toLowerCase();
+			const hits = all.filter((c) => c.uuid?.toLowerCase() === lower || c.title?.toLowerCase() === lower);
+			if (!hits.length) throw new CalendarNotFoundError(want, all.map((c) => c.title ?? "").filter(Boolean));
+			return hits.map((c) => c.uuid).filter((u) => Boolean(u));
+		};
+		if (named) {
+			const chosen = pick(named);
+			if (configured.length) {
+				const allowed = new Set(configured.flatMap(pick));
+				const kept = chosen.filter((u) => allowed.has(u));
+				if (!kept.length) throw new CalendarNotFoundError(named, configured);
+				return kept;
+			}
+			return chosen;
+		}
+		if (configured.length) return configured.flatMap(pick);
+	}
+	#visible(row, opts) {
+		if (!opts.cancelled && row.status === STATUS_CANCELLED) return false;
+		if (!opts.declined && row.invitationStatus === PARTICIPANT_DECLINED) return false;
+		return true;
+	}
+	#summarise(row, store) {
+		const start = renderInstant(row.startApple, row.startTz, row.allDay, store.caps.epochOffset);
+		/**
+		* OPEN: the all-day `end` convention is not settled, so it is reported RAW.
+		*
+		* Measured against a live calendar, creating one all-day event on
+		* 21 September: Apple Events reads the end back as `2026-09-21T21:59:59`
+		* (23:59:59 local — inclusive), while the store renders a day later. The two
+		* legs also disagree with each other: an occurrence row reports end on the
+		* same day as start, an item row a day after.
+		*
+		* A "subtract a second before rendering" normalisation was tried and turned
+		* out to be a no-op on real data, which means the anchoring differs in a way
+		* that has not been pinned down — `start_date` reads as local midnight while
+		* `end_date` appears to be anchored differently. Guessing again on top of an
+		* unverified premise is how the start-of-day bug got here in the first
+		* place, so this stays raw and documented until the raw columns are read.
+		* See docs/calendar.md, "Still open".
+		*/
+		const end = renderInstant(row.endApple, row.endTz ?? row.startTz, row.allDay, store.caps.epochOffset);
+		const isOccurrence = row.source === "occurrence";
+		return {
+			ref: encodeRef(row.calendarUuid ?? "", row.uuid ?? "", isOccurrence && row.startApple !== null ? /* @__PURE__ */ new Date((row.startApple + store.caps.epochOffset) * 1e3) : null),
+			summary: row.summary,
+			start,
+			end,
+			allDay: row.allDay,
+			calendar: row.calendarTitle,
+			location: row.locationTitle,
+			isOccurrence,
+			...isOccurrence ? { seriesRef: encodeRef(row.calendarUuid ?? "", row.uuid ?? "") } : {},
+			status: row.status,
+			invitationStatus: row.invitationStatus,
+			source: row.source
+		};
+	}
+	listEvents(filters) {
+		const store = this.#require();
+		const range = parseRange({
+			from: filters.from,
+			to: filters.to,
+			defaultRangeDays: this.config.defaultRangeDays,
+			maxRangeDays: this.config.maxRangeDays
+		}, this.#now());
+		const fromApple = this.#toApple(range.from, store);
+		const toApple = this.#toApple(range.to, store);
+		const calendarUuids = this.#calendarUuids(store, filters.calendar);
+		const legLimit = Math.min(filters.limit * 4 + 50, 5e3);
+		const q = {
+			fromApple,
+			toApple,
+			limit: legLimit,
+			...calendarUuids ? { calendarUuids } : {}
+		};
+		const merged = mergeRange({
+			items: store.rangeItems(q),
+			occurrences: store.rangeOccurrences(q),
+			coverage: store.coverage(),
+			hasOccurrenceCache: store.caps.hasOccurrenceCache,
+			fromApple,
+			toApple,
+			limit: legLimit,
+			epochOffset: store.caps.epochOffset
+		});
+		const declined = filters.includeDeclined ?? this.config.includeDeclined;
+		const cancelled = filters.includeCancelled ?? this.config.includeCancelled;
+		return {
+			events: merged.rows.filter((r) => this.#visible(r, {
+				declined,
+				cancelled
+			})).slice(0, filters.limit).map((r) => this.#summarise(r, store)),
+			expansion: merged.expansion,
+			...merged.expansionReason ? { expansionReason: merged.expansionReason } : {},
+			window: {
+				from: range.from.toISOString(),
+				to: range.to.toISOString(),
+				clamped: range.clamped
+			},
+			coverage: merged.coverage ? {
+				from: this.#fromApple(merged.coverage.fromApple, store),
+				to: this.#fromApple(merged.coverage.toApple, store),
+				rows: merged.coverage.rows
+			} : null,
+			...merged.truncated ? { truncated: {
+				reason: merged.truncated.reason,
+				affects: merged.truncated.affects,
+				...merged.truncated.uncoveredFromApple !== void 0 ? { uncoveredFrom: this.#fromApple(merged.truncated.uncoveredFromApple, store) } : {},
+				...merged.truncated.uncoveredToApple !== void 0 ? { uncoveredTo: this.#fromApple(merged.truncated.uncoveredToApple, store) } : {}
+			} } : {},
+			...merged.dropped ? { dropped: merged.dropped } : {}
+		};
+	}
+	/**
+	* Text search over events.
+	*
+	* Runs on items only. An occurrence carries no text of its own, so matching
+	* the series once is what a search result should be — expanding it here would
+	* bury one answer under fifty identical ones.
+	*/
+	searchEvents(args) {
+		const store = this.#require();
+		const now = this.#now();
+		const fromApple = args.from ? this.#toApple(parseRange({
+			from: args.from,
+			to: args.from,
+			defaultRangeDays: 1,
+			maxRangeDays: 1
+		}, now).from, store) : Number.MIN_SAFE_INTEGER;
+		const toApple = args.to ? this.#toApple(parseRange({
+			from: args.to,
+			to: args.to,
+			defaultRangeDays: 1,
+			maxRangeDays: 1
+		}, now).to, store) : Number.MAX_SAFE_INTEGER;
+		const calendarUuids = this.#calendarUuids(store, args.calendar);
+		const rows = store.searchItems({
+			fromApple,
+			toApple,
+			limit: Math.min(args.limit * 4 + 50, 5e3),
+			text: args.query,
+			scope: args.scope ?? "summary",
+			...calendarUuids ? { calendarUuids } : {}
+		});
+		const declined = args.includeDeclined ?? this.config.includeDeclined;
+		const cancelled = args.includeCancelled ?? this.config.includeCancelled;
+		return {
+			events: rows.filter((r) => this.#visible(r, {
+				declined,
+				cancelled
+			})).slice(0, args.limit).map((r) => this.#summarise(r, store)),
+			expansion: "unavailable",
+			expansionReason: "search matches each event once, at its series start; use apple_calendar_list_events with a date range to see individual occurrences",
+			window: {
+				from: args.from ? this.#fromApple(fromApple, store) : "unbounded",
+				to: args.to ? this.#fromApple(toApple, store) : "unbounded",
+				clamped: false
+			},
+			coverage: null
+		};
+	}
+	getEvent(ref) {
+		const store = this.#require();
+		const decoded = decodeRef(ref);
+		const row = store.byUuid(decoded.eventUid);
+		if (!row) throw new EventNotFoundError(ref);
+		const shaped = decoded.occurrenceStart ? {
+			...row,
+			startApple: this.#toApple(decoded.occurrenceStart, store),
+			endApple: row.startApple !== null && row.endApple !== null ? this.#toApple(decoded.occurrenceStart, store) + (row.endApple - row.startApple) : row.endApple,
+			source: "occurrence"
+		} : row;
+		const summary = this.#summarise(shaped, store);
+		return {
+			...summary,
+			ref,
+			...decoded.isOccurrence ? { seriesRef: seriesRefOf(decoded) } : {},
+			description: row.description,
+			url: row.url,
+			conferenceUrl: row.conferenceUrl,
+			hasAttendees: row.hasAttendees,
+			hasRecurrences: row.hasRecurrences,
+			timeZone: summary.start && !summary.start.allDay ? summary.start.timeZone : null
+		};
+	}
+	calendars() {
+		return this.#require().calendars();
+	}
+	accounts() {
+		return this.#require().accounts();
+	}
+	/**
+	* Resolve the calendar a write targets, and refuse a read-only one up front.
+	*
+	* Asking the store first means the refusal names the cause. Letting the Apple
+	* Event fail instead produces a message from deep inside Calendar that does
+	* not mention writability at all.
+	*/
+	#writeTarget(named) {
+		const store = this.index();
+		const wanted = named ?? this.config.defaultCalendar;
+		if (!store) return {
+			name: wanted,
+			uuid: null
+		};
+		const all = store.calendars();
+		if (!wanted) return {
+			name: void 0,
+			uuid: null
+		};
+		const lower = wanted.toLowerCase();
+		const hits = all.filter((c) => c.uuid?.toLowerCase() === lower || c.title?.toLowerCase() === lower);
+		if (!hits.length) throw new CalendarNotFoundError(wanted, all.map((c) => c.title ?? "").filter(Boolean));
+		/**
+		* Duplicate titles are real: the machine this was measured on has two
+		* calendars both named `olouvignes@me.com`. A read can legitimately span
+		* both, but a write has to land in exactly one — and only a NAME crosses to
+		* Apple Events, so an ambiguous one is refused rather than resolved by coin
+		* flip.
+		*/
+		if (hits.length > 1) throw new PreconditionError(`"${wanted}" matches ${hits.length} calendars, and a write has to name exactly one. Calendars are addressed by name when writing — Apple Events cannot resolve a calendar uid at all — so duplicates cannot be told apart. Rename one in Calendar.app, or write to a calendar whose name is unique.`, {
+			requested: wanted,
+			matches: hits.length
+		});
+		const hit = hits[0];
+		if (hit.isSubscribed) throw new CalendarNotWritableError(hit.title ?? wanted);
+		return {
+			name: hit.title ?? wanted,
+			uuid: hit.uuid
+		};
+	}
+	/** Map a calendar name reported by Apple Events back to its store uuid. */
+	#calendarUuidByName(name) {
+		if (!name) return null;
+		const store = this.index();
+		if (!store) return null;
+		return store.calendars().find((c) => c.title === name)?.uuid ?? null;
+	}
+	/**
+	* The calendar NAME a ref points at, for a write.
+	*
+	* A ref carries the store uuid, which Apple Events cannot resolve, so it has
+	* to be turned back into a name before it crosses.
+	*/
+	#nameForRefCalendar(calendarUid) {
+		if (!calendarUid) return void 0;
+		const store = this.index();
+		if (!store) return void 0;
+		const lower = calendarUid.toLowerCase();
+		return store.calendars().find((c) => c.uuid?.toLowerCase() === lower)?.title ?? void 0;
+	}
+	/**
+	* Run a write script, re-inflating its application-level failures.
+	*
+	* Core turns a `{ok:false, error:{code, message}}` envelope into a generic
+	* `ProtocolError` carrying the code, which surfaces as a bare `"Birthdays"`.
+	* That matters more here than it looks: the store-side writability check is
+	* derived from `subcal_url` and MISSES calendars that are read-only for other
+	* reasons — Birthdays and Siri Suggestions both report `writable() === false`
+	* while carrying no subscription URL. The JXA lane catches them correctly, so
+	* the only thing lost was the explanation. This puts it back.
+	*/
+	async #run(scriptText, params) {
+		try {
+			return await withBusyRetry(() => this.runner.run(scriptText, params));
+		} catch (err) {
+			const code = err?.details?.code;
+			const message = err instanceof Error ? err.message : String(err);
+			if (code === "CALENDAR_NOT_WRITABLE") throw new CalendarNotWritableError(message);
+			if (code === "CALENDAR_NOT_FOUND") throw new CalendarNotFoundError(message);
+			if (code === "EVENT_NOT_FOUND") throw new EventNotFoundError(message);
+			throw err;
+		}
+	}
+	#shapeWrite(data, calendarUid) {
+		const uid = typeof data.uid === "string" ? data.uid : null;
+		return {
+			ref: encodeRef(calendarUid ?? "", uid ?? ""),
+			uid,
+			summary: typeof data.summary === "string" ? data.summary : null,
+			start: typeof data.startDate === "string" ? data.startDate : null,
+			end: typeof data.endDate === "string" ? data.endDate : null,
+			allDay: data.alldayEvent === true,
+			calendar: typeof data.calendarName === "string" ? data.calendarName : null,
+			source: "apple-events"
+		};
+	}
+	/**
+	* Work out an event's end from whichever of the three forms the caller used.
+	*
+	* `end` wins over `durationMinutes`; with neither, the configured default
+	* length applies. A zero-length event is refused rather than created, because
+	* Calendar renders one as a point in time that is almost impossible to click.
+	*/
+	#resolveWindow(start, end, durationMinutes) {
+		const now = this.#now();
+		const from = parseDate("start", start, now);
+		if (end !== void 0) {
+			/**
+			* A bare day as `end` means THROUGH that day, not midnight at its start.
+			*
+			* `parseBound` already encodes this for range queries, and list_events
+			* documents it — "naming the same day for both gives that whole day". Using
+			* plain `parseDate` here made create disagree with list about the same
+			* word: `{start: "2026-09-21", end: "2026-09-21"}`, the natural way to say
+			* "a one-day event", was refused as ending before it began.
+			*/
+			const to = parseBound("end", end, "end", now);
+			if (to.getTime() <= from.at.getTime()) throw new PreconditionError(`end (${toLocalIso(to)}) is not after start (${from.iso}). An event cannot finish before it begins.`);
+			return {
+				startIso: from.iso,
+				endIso: toLocalIso(to),
+				allDayHint: from.kind === "allDay"
+			};
+		}
+		const minutes = durationMinutes === void 0 ? this.config.defaultEventDurationMinutes : parseDuration("durationMinutes", durationMinutes);
+		const to = new Date(from.at.getTime() + minutes * 6e4);
+		return {
+			startIso: from.iso,
+			endIso: toLocalIso(to),
+			allDayHint: from.kind === "allDay"
+		};
+	}
+	async createEvent(fields) {
+		const target = this.#writeTarget(fields.calendar);
+		const win = this.#resolveWindow(fields.start, fields.end, fields.durationMinutes);
+		const data = await this.#run(CREATE_EVENT, {
+			calendar: target.name ?? null,
+			summary: fields.summary,
+			startDate: win.startIso,
+			endDate: win.endIso,
+			allDay: fields.allDay ?? win.allDayHint,
+			...fields.location !== void 0 ? { location: fields.location } : {},
+			...fields.description !== void 0 ? { description: fields.description } : {},
+			...fields.url !== void 0 ? { url: fields.url } : {}
+		});
+		this.invalidate();
+		const uuid = target.uuid ?? this.#calendarUuidByName(typeof data.calendarName === "string" ? data.calendarName : null);
+		return this.#shapeWrite(data, uuid);
+	}
+	async updateEvent(fields) {
+		const ref = decodeRef(fields.ref);
+		/**
+		* An occurrence ref is REFUSED rather than quietly applied to the series.
+		*
+		* Calendar's scripting dictionary has no way to detach a single occurrence —
+		* the "This Event" edit in the UI has no scripting equivalent. Applying the
+		* change to the series would move every future standup because someone
+		* asked to move one lunch, which is a data-loss bug wearing a success
+		* message. "All future" is absent for a related reason: it needs a rule
+		* split, which is two writes with no transaction between them.
+		*/
+		if (ref.isOccurrence) throw new PreconditionError("That ref names one occurrence of a repeating event, and Calendar's scripting interface cannot edit a single occurrence — only the whole series. Applying your change to the series would move every other occurrence too, so this is refused rather than done silently. To change just this one: delete it with apple_calendar_delete_events (scope \"occurrence\"), then create a replacement. To change them all, pass the seriesRef from apple_calendar_get_event instead.", {
+			ref: fields.ref,
+			seriesRef: seriesRefOf(ref)
+		});
+		const window = fields.start !== void 0 ? this.#resolveWindow(fields.start, fields.end, fields.durationMinutes) : null;
+		const data = await this.#run(UPDATE_EVENT, {
+			calendar: this.#nameForRefCalendar(ref.calendarUid) ?? null,
+			uid: ref.eventUid,
+			...fields.summary !== void 0 ? { summary: fields.summary } : {},
+			...window ? {
+				startDate: window.startIso,
+				endDate: window.endIso
+			} : {},
+			...fields.allDay !== void 0 ? { allDay: fields.allDay } : {},
+			...fields.location !== void 0 ? { location: fields.location } : {},
+			...fields.description !== void 0 ? { description: fields.description } : {},
+			...fields.url !== void 0 ? { url: fields.url } : {}
+		});
+		this.invalidate();
+		return this.#shapeWrite(data, ref.calendarUid);
+	}
+	/**
+	* Delete whole events.
+	*
+	* Only whole events: Calendar's scripting interface cannot remove a single
+	* occurrence of a repeating one. `excludedDates` — the property Calendar.app
+	* itself uses for "Delete This Event" — reads back a 1903 sentinel and throws
+	* on assignment, measured on macOS 26.6. So an occurrence ref is refused
+	* rather than silently deleting the whole series, which is the same shape of
+	* refusal `updateEvent` makes and for the same underlying reason.
+	*/
+	async deleteEvents(refs) {
+		const decoded = refs.map((r, i) => ({
+			ref: refs[i],
+			parsed: decodeRef(r)
+		}));
+		const occurrence = decoded.find((d) => d.parsed.isOccurrence);
+		if (occurrence) throw new PreconditionError("That ref names one occurrence of a repeating event, and Calendar's scripting interface cannot delete a single occurrence — the excluded-dates property it would need is not writable. Deleting the series instead would remove every other occurrence too, so this is refused rather than done silently. Delete this one in Calendar.app, or pass the seriesRef from apple_calendar_get_event to delete the whole series.", {
+			ref: occurrence.ref,
+			seriesRef: seriesRefOf(occurrence.parsed)
+		});
+		const byCalendar = /* @__PURE__ */ new Map();
+		for (const { parsed } of decoded) {
+			const key = parsed.calendarUid || "";
+			byCalendar.set(key, [...byCalendar.get(key) ?? [], parsed.eventUid]);
+		}
+		const results = [];
+		for (const [calendar, uids] of byCalendar) {
+			const data = await this.#run(DELETE_EVENTS, {
+				calendar: this.#nameForRefCalendar(calendar) ?? null,
+				uids
+			});
+			results.push(...data.results ?? []);
+		}
+		this.invalidate();
+		return {
+			results,
+			scope: "series"
+		};
+	}
+	lanes() {
+		const located = this.locate();
+		const store = this.index();
+		return {
+			applescript: "not-used",
+			index: this.config.indexMode === "off" ? "disabled" : store ? "live" : "unavailable",
+			indexMode: store?.mode ?? null,
+			storeFingerprint: store?.caps.fingerprint ?? null,
+			reason: store ? null : located.reason
+		};
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Configuration is environment-only — this server holds no secret at all, its
+* access is the macOS permission the user granted.
+*
+* `allowWrites`, `debug`, `osascriptPath`, `osascriptTimeoutMs` and `maxResults`
+* come from `BaseConfigSchema`.
+*
+* Note what is deliberately ABSENT relative to `packages/reminders`: there is no
+* `searchCacheTtlMs` and no degraded-listing cap, because both exist there to
+* manage an Apple Events READ lane. Calendar has none by design
+* (`docs/distribution.md`), and config for a lane that does not exist would
+* advertise a fallback this server cannot provide.
+*/
+const ConfigSchema = BaseConfigSchema.extend({
+	/** Account allowlist (names or ids). Empty means every account. */
+	accounts: z.array(z.string().min(1)).default([]),
+	/**
+	* Calendar allowlist (names or uids). Empty means every calendar.
+	*
+	* The important one for this surface: a work calendar and a personal one
+	* routinely live in the same account, so the account is the wrong unit to
+	* scope by whenever scoping is the point.
+	*/
+	calendars: z.array(z.string().min(1)).default([]),
+	/** Explicit store path. Bypasses discovery — for tests and forensic copies. */
+	storePath: z.string().optional(),
+	indexMode: z.enum([
+		"auto",
+		"ro",
+		"immutable",
+		"off"
+	]).default("auto"),
+	/** Calendar a new event goes to when the caller names none. Empty = Calendar's default. */
+	defaultCalendar: z.string().optional(),
+	/**
+	* Window for a range query that names only a start.
+	*
+	* A calendar has no natural "everything" answer the way a note list does, and
+	* an unbounded default would scan a decade to report next Tuesday.
+	*/
+	defaultRangeDays: z.number().int().min(1).max(366).default(7),
+	/** Hard clamp, so one query cannot ask for a decade. */
+	maxRangeDays: z.number().int().min(1).max(3660).default(366),
+	/** Length of a created event when the caller gives neither an end nor a duration. */
+	defaultEventDurationMinutes: z.number().int().min(1).max(1440).default(60),
+	/** Whether events the user declined are included when the caller does not say. */
+	includeDeclined: z.boolean().default(false),
+	/** Whether events an organiser cancelled are included when the caller does not say. */
+	includeCancelled: z.boolean().default(false),
+	/**
+	* Render override for timed events. Empty means the system zone.
+	*
+	* Validated as a real IANA name here rather than at render time: a bad zone
+	* should fail at startup with the variable named, not once per event.
+	*/
+	timeZone: z.string().refine((v) => {
+		try {
+			Intl.DateTimeFormat("en-US", { timeZone: v });
+			return true;
+		} catch {
+			return false;
+		}
+	}, { message: "not an IANA time zone name, e.g. \"Europe/Paris\"" }).optional()
+}).strict();
+/**
+* `env` is a parameter with a default so tests are hermetic — they pass their
+* own object rather than mutating (and having to restore) process.env.
+*/
+const loadConfig = (env = process.env) => parseConfig(ConfigSchema, {
+	allowWrites: parseBool(env.APPLE_CALENDAR_ALLOW_WRITES),
+	debug: parseBool(env.APPLE_CALENDAR_DEBUG),
+	accounts: parseList(env.APPLE_CALENDAR_ACCOUNTS),
+	calendars: parseList(env.APPLE_CALENDAR_CALENDARS),
+	storePath: trimmed(env.APPLE_CALENDAR_STORE),
+	indexMode: trimmed(env.APPLE_CALENDAR_INDEX_MODE),
+	defaultCalendar: trimmed(env.APPLE_CALENDAR_DEFAULT_CALENDAR),
+	defaultRangeDays: parseIntOpt(env.APPLE_CALENDAR_DEFAULT_RANGE_DAYS),
+	maxRangeDays: parseIntOpt(env.APPLE_CALENDAR_MAX_RANGE_DAYS),
+	defaultEventDurationMinutes: parseIntOpt(env.APPLE_CALENDAR_DEFAULT_EVENT_DURATION_MINUTES),
+	includeDeclined: parseBool(env.APPLE_CALENDAR_INCLUDE_DECLINED),
+	includeCancelled: parseBool(env.APPLE_CALENDAR_INCLUDE_CANCELLED),
+	osascriptPath: trimmed(env.APPLE_CALENDAR_OSASCRIPT_PATH),
+	osascriptTimeoutMs: parseIntOpt(env.APPLE_CALENDAR_OSASCRIPT_TIMEOUT_MS),
+	maxResults: parseIntOpt(env.APPLE_CALENDAR_MAX_RESULTS),
+	timeZone: trimmed(env.APPLE_CALENDAR_TIMEZONE)
+});
+//#endregion
+//#region src/tools/util.ts
+const eventRefArg = z.string().min(1).describe("An opaque event ref from a list or search result (looks like \"c1:<calendar>/<occurrence>/<uid>\"). Do not construct one by hand.");
+const calendarArg = z.string().optional().describe("A calendar name or uid, e.g. \"Work\". Use apple_calendar_list_calendars to see what exists.");
+/**
+* The date grammar, written out in full.
+*
+* Load-bearing: the caller is usually a model that gets one retry, and the
+* difference between naming a day and naming an instant is the difference
+* between a whole-day range and a one-minute one.
+*/
+const fromArg = z.string().optional().describe("Start of the window. ISO-8601 \"2026-08-21\" or \"2026-08-21T09:00\", or \"today\", \"tomorrow\", \"next monday\", \"+2d\". A bare day starts at that morning. Defaults to today.");
+const toArg = z.string().optional().describe("End of the window. A bare day runs through that EVENING, so naming the same day for both gives that whole day. Defaults to a week after the start.");
+const includeDeclinedArg = z.boolean().optional().describe("Include events you have declined. Off by default; they are still on the calendar.");
+const includeCancelledArg = z.boolean().optional().describe("Include events an organiser cancelled but that are still in the store. Off by default.");
+//#endregion
+//#region src/tools/actions.ts
+/**
+* The mutating tools.
+*
+* Registered only when `allowWrites` is on — not merely refused, absent, so a
+* host is never told they exist.
+*
+* ## No `attendees` parameter, anywhere
+*
+* Adding an attendee sends an email to a person. That is not something to do
+* behind a tool call, and leaving it out of the schema is a stronger guarantee
+* than validating it away. `test/jxa.test.ts` asserts the scripts cannot set it
+* either, so there are two places to remove rather than one to forget.
+*/
+const startArg = z.string().describe("When it starts. ISO-8601 \"2026-08-21\" for an all-day event or \"2026-08-21T09:00\" for a timed one, or \"tomorrow 09:00\", \"next monday\", \"+2d\". Naming a bare day makes it all-day.");
+const endArg = z.string().optional().describe("When it ends. Give this or durationMinutes; with neither, the default length applies.");
+const durationArg = z.number().int().min(1).max(527040).optional().describe("Length in minutes, as an alternative to `end`.");
+const registerActionTools = (server, client) => {
+	server.registerTool("apple_calendar_create_event", {
+		description: "Create an event. THIS IS A REAL EVENT ON A REAL CALENDAR: on an iCloud, CalDAV or Exchange calendar it syncs within seconds and there is no draft state and no undo. Check apple_calendar_list_calendars first — writing to one where `isShared` is true is visible to everyone else on that calendar, so prefer a personal one unless the user meant to share it. Read-only calendars are refused. This tool cannot add attendees, which would email a person. The result reports what Calendar actually stored, which is not always what was asked for.",
+		inputSchema: {
+			summary: z.string().min(1).describe("The event's title."),
+			calendar: calendarArg,
+			start: startArg,
+			end: endArg,
+			durationMinutes: durationArg,
+			allDay: z.boolean().optional().describe("Force an all-day event. Usually unnecessary: a bare day in `start` means one."),
+			location: z.string().optional(),
+			description: z.string().optional().describe("The event's notes."),
+			url: z.string().optional()
+		}
+	}, async (args) => wrap(() => client.createEvent(args)));
+	server.registerTool("apple_calendar_update_event", {
+		description: "Change an existing event. On a shared calendar the change is visible to everyone else on it. Note that Apple Events has no transaction: if a change is refused part-way through, earlier fields may already have been written, so the result is the truth about what the event now looks like. Only whole events can be edited: a ref naming ONE occurrence of a repeating event is refused, because Calendar's scripting interface cannot detach a single occurrence and applying the change to the series would move every other one too. To change a single occurrence, delete it with scope \"occurrence\" and create a replacement.",
+		inputSchema: {
+			ref: eventRefArg,
+			summary: z.string().min(1).optional(),
+			start: startArg.optional(),
+			end: endArg,
+			durationMinutes: durationArg,
+			allDay: z.boolean().optional(),
+			location: z.string().optional(),
+			description: z.string().optional(),
+			url: z.string().optional()
+		}
+	}, async (args) => wrap(() => client.updateEvent(args)));
+	server.registerTool("apple_calendar_delete_events", {
+		description: "Delete whole events. Each result says whether the event ACTUALLY went — Calendar silently declines to delete a repeating event, reporting no error, so `deleted` is decided by re-reading the calendar rather than by the call succeeding. A ref naming ONE occurrence of a repeating event is refused: Calendar's scripting interface cannot remove a single occurrence, and deleting the series instead would take every other one with it. Delete a single occurrence in Calendar.app, or pass the `seriesRef` from get_event to remove the whole series. \"All future occurrences\" is not offered either — it needs two writes with no transaction between them.",
+		inputSchema: {
+			refs: z.array(z.string().min(1)).min(1).max(100).describe("Event refs from a list or search result. Each must name a whole event, not one occurrence of a repeating one."),
+			confirm: confirmArg
+		}
+	}, async ({ refs }) => wrap(() => client.deleteEvents(refs)));
+};
+//#endregion
+//#region src/tools/calendars.ts
+/**
+* NOTE ON `async` BELOW: core's `wrap` is typed `() => Promise<T>` because every
+* other surface reaches Apple Events. Calendar reads synchronous SQLite, so the
+* thunks are marked async here rather than widening a shared signature for all
+* four surfaces to accommodate one.
+*/
+const registerCalendarTools = (server, client) => {
+	server.registerTool("apple_calendar_list_calendars", {
+		description: "List every calendar with the account it belongs to, whether it is SHARED with other people, and whether it looks writable. Two cautions. `isShared` means anything you write there is visible to the others on it. And `isSubscribed` catches URL-subscribed calendars but not every read-only one — Birthdays and Siri Suggestions are also read-only — so a write can still be refused by Calendar itself.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => client.calendars()));
+	server.registerTool("apple_calendar_list_accounts", {
+		description: "List the accounts Calendar syncs, with how many calendars each holds. Use this to scope a search when the same calendar name exists in more than one account.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => client.accounts()));
+};
+//#endregion
+//#region src/tools/diagnostics.ts
+/**
+* One tool that answers "why is this not working".
+*
+* Unlike the Reminders equivalent this probes no Apple Event before reading:
+* Calendar has no Apple Events read lane to probe (`docs/distribution.md`), so
+* firing one here would trigger the Automation prompt for a capability the
+* server does not yet have.
+*/
+const registerDiagnosticsTools = (server, client, ctx) => {
+	server.registerTool("apple_calendar_diagnostics", {
+		description: "Report which lanes are live, which macOS permissions are granted, and what each missing one is blocking. Start here when a tool fails or reports nothing — it names the exact System Settings pane to open.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => {
+		const lanes = client.lanes();
+		const located = client.locate();
+		const store = client.index();
+		/**
+		* Three-valued, and the middle value is the useful one.
+		*
+		* Calendar's store has a constant filename, so `stat` answers "is it
+		* there" even when `access(2)` is denied. That lets this separate "the
+		* grant is missing" from "Calendar was never set up on this account",
+		* which Reminders cannot do — its filename carries a generated UUID, so
+		* without the grant there is no path to test at all.
+		*/
+		const fullDiskAccess = located.readable ? "granted" : located.exists ? "denied (found the store, cannot read it)" : "unknown (no store file at the expected path)";
+		return {
+			server: { lanes },
+			permissions: {
+				fullDiskAccess,
+				automation: ctx.allowWrites ? "needed for writes only. Reads never send an Apple Event, so a read-only setup prompts for nothing." : "not needed — writes are off, and reads never send an Apple Event. Turning writes on will prompt for Automation the first time one runs.",
+				...located.readable ? {} : { howToGrant: [
+					"System Settings > Privacy & Security > Full Disk Access",
+					"Add the app that launches this server (Terminal, iTerm, VS Code, Claude...), then restart it.",
+					"Granting it to Calendar.app does nothing — the reader needs the permission, not Calendar."
+				] }
+			},
+			store: {
+				containerPath: located.containerPath,
+				path: located.storePath,
+				containerListable: located.containerListable,
+				extrasPresent: located.extrasPresent,
+				candidates: located.candidates.length,
+				exists: located.exists,
+				readable: located.readable,
+				sizeBytes: located.size,
+				walPresent: located.walPresent,
+				walSizeBytes: located.walSizeBytes,
+				fingerprint: lanes.storeFingerprint,
+				reason: located.reason
+			},
+			capabilities: store ? {
+				hasOccurrenceCache: store.caps.hasOccurrenceCache,
+				hasOccurrenceDays: store.caps.hasOccurrenceDays,
+				hasRecurrence: store.caps.hasRecurrence,
+				hasExceptionDates: store.caps.hasExceptionDates,
+				hasLocation: store.caps.hasLocation,
+				hasAttachments: store.caps.hasAttachments,
+				hasParticipants: store.caps.hasParticipants,
+				hasAlarms: store.caps.hasAlarms,
+				itemColumns: store.caps.itemColumns.size,
+				calendarColumns: store.caps.calendarColumns.size
+			} : null,
+			settings: {
+				allowWrites: ctx.allowWrites,
+				accountAllowlist: client.config.accounts,
+				calendarAllowlist: client.config.calendars,
+				defaultCalendar: client.config.defaultCalendar ?? null,
+				defaultRangeDays: client.config.defaultRangeDays,
+				maxRangeDays: client.config.maxRangeDays,
+				includeDeclined: client.config.includeDeclined,
+				includeCancelled: client.config.includeCancelled,
+				indexMode: client.config.indexMode,
+				maxResults: client.config.maxResults,
+				timeZone: client.config.timeZone ?? null
+			},
+			caveats: [
+				"Writes go through Apple Events and are real side effects: on a shared, CalDAV or Exchange calendar a created event syncs within seconds and other people see it. There is no draft state and no undo.",
+				"Single occurrences of a repeating event can be neither edited nor deleted through this server, and that is a limit of Calendar's scripting interface rather than a choice: there is no way to detach one occurrence, and the excluded-dates property reads back a 1903 sentinel and throws on assignment (measured, macOS 26.6). Both are refused rather than applied to the whole series. Calendar.app can still do them.",
+				"Attendees cannot be set, because that emails a person. There is no \"all future occurrences\" either, which would need two writes with no transaction between them.",
+				"Calendar reads through the file lane only. Apple Events was measured at 3.4s for a single 90-day range query, with the cost falling per round trip rather than per event, so there is no slower-but-working fallback to offer when Full Disk Access is missing. Reads need the grant.",
+				"Repeating events are expanded from OccurrenceCache, which was measured to reach about two years either side of today on the probed store. That is an edge: a range running past it returns fewer repeating events than exist, so every list_events result carries `coverage`, and sets `truncated` rather than returning a short list silently.",
+				"The `status` and `invitationStatus` numbers are EventKit's documented constants, and this store is assumed to mirror them — likely, but not measured. That is why cancelled and declined events are only hidden when you ask, and why the raw value is on every result.",
+				"Writes will go through Apple Events, targeting com.apple.iCal. Note the bundle id is iCal, not Calendar, which is the one place this surface differs from the other three."
+			]
+		};
+	}).then((r) => r ?? ok({})));
+};
+//#endregion
+//#region src/tools/events.ts
+/** Declared once and spread into both tools, so the two cannot drift apart. */
+const filterSchema = {
+	calendar: calendarArg,
+	includeDeclined: includeDeclinedArg,
+	includeCancelled: includeCancelledArg,
+	limit: limitArg
+};
+const registerEventTools = (server, client) => {
+	server.registerTool("apple_calendar_list_events", {
+		description: "List events in a date range, earliest first. Occurrences of repeating events are expanded, so a weekly standup appears once per week rather than once. The result carries a `coverage` block naming the window the expansion is known to cover; if your range runs past it, `truncated` is set and says what is missing rather than returning a short list silently. Returns a `ref` per event for get_event.",
+		inputSchema: {
+			from: fromArg,
+			to: toArg,
+			...filterSchema
+		},
+		annotations: { readOnlyHint: true }
+	}, async (args) => wrap(async () => client.listEvents({
+		...args,
+		limit: args.limit ?? Math.min(50, client.config.maxResults)
+	})));
+	server.registerTool("apple_calendar_search_events", {
+		description: "Search events by text, most recent first. Unbounded in time unless you give `from` or `to`. Matches each event ONCE at its series start — it does not expand occurrences, so use list_events with a range to see individual instances of a repeating event.",
+		inputSchema: {
+			query: z.string().min(1).describe("Text to look for. Matched case-insensitively."),
+			scope: z.enum(["summary", "full"]).optional().describe("\"summary\" (default) searches titles; \"full\" adds notes and location."),
+			from: fromArg,
+			to: toArg,
+			...filterSchema
+		},
+		annotations: { readOnlyHint: true }
+	}, async (args) => wrap(async () => client.searchEvents({
+		...args,
+		limit: args.limit ?? Math.min(50, client.config.maxResults)
+	})));
+	server.registerTool("apple_calendar_get_event", {
+		description: "Full detail for one event: notes, location, URL, conference link, and whether it has attendees or repeats. A ref naming one occurrence reports that occurrence's times and carries a `seriesRef` pointing at the whole series.",
+		inputSchema: { ref: eventRefArg },
+		annotations: { readOnlyHint: true }
+	}, async ({ ref }) => wrap(async () => client.getEvent(ref)));
+};
+//#endregion
+//#region src/tools/index.ts
+/**
+* Register the Apple Calendar tools.
+*
+* The registered set is a pure function of `allowWrites` and nothing else. In
+* particular it does NOT vary with whether Full Disk Access is granted: that is
+* a runtime condition which can change while the process lives, and MCP clients
+* cache the tool list, so a tool that appears and disappears would leave clients
+* calling names the server no longer has. Tools that need the store instead
+* report their source, or explain what is missing.
+*
+* Writes go through Apple Events, always. Not a preference: `PRAGMA query_only`
+* is set on the store because Calendar owns it, holds it open and reconciles it
+* against a server, so writing to it would corrupt sync state.
+*/
+const registerTools = (server, client, ctx) => {
+	registerDiagnosticsTools(server, client, ctx);
+	registerCalendarTools(server, client);
+	registerEventTools(server, client);
+	if (!ctx.allowWrites) return;
+	registerActionTools(server, client);
+};
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = BUILD_INFO.name;
+const SERVER_VERSION = BUILD_INFO.version;
+/**
+* Build the server. Side-effect free: it opens no connection, spawns no
+* process and reads no file, so a test can construct it freely and every
+* external dependency arrives through an option.
+*
+*/
+const createServer = (opts) => {
+	const { config } = opts;
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const client = new AppleCalendarClient({
+		config,
+		...opts.logger ? { logger: opts.logger } : {},
+		...opts.osascript ? { osascript: opts.osascript } : {},
+		...opts.now ? { now: opts.now } : {}
+	});
+	registerTools(server, client, { allowWrites: config.allowWrites });
+	return {
+		server,
+		client
+	};
+};
+//#endregion
+export { BUILD_INFO as A, CALENDAR_SURFACE as C, CalendarNotWritableError as D, CalendarNotRunningError as E, EventNotFoundError as O, CALENDAR_BUNDLE_ID as S, CalendarNotFoundError as T, STORE_FILENAME as _, loadConfig as a, locateStore as b, introspect as c, decodeRef as d, encodeRef as f, GROUP_CONTAINER as g, EXTRAS_FILENAME as h, registerTools as i, InvalidDateError as k, openStore as l, uuidOf as m, SERVER_VERSION as n, AppleCalendarClient as o, seriesRefOf as p, createServer as r, CalendarStore as s, SERVER_NAME as t, REF_VERSION as u, defaultContainerPath as v, CalendarBusyError as w, AppleCalendarError as x, defaultStorePath as y };
+
+//# sourceMappingURL=server-B2HtiXLF.js.map