@mulmoclaude/core 5.0.1 → 5.3.0

package/assets/helps/error-recovery.md

@@ -657,6 +657,84 @@ workspace is already on a real filesystem and a conflict still will not
 clear, that is a new bug — report it with the calendar id and the
 record.
 
+## Push skips a record: "the record id cannot be used as a Google event id"
+
+### Symptoms
+
+Push reports a record as skipped and names its id. It never reaches
+Google, however many times the user presses the button. Editing the
+record's other fields changes nothing.
+
+### Cause
+
+A push CREATES the Google event with the record's own primary-key value
+as the event id, so a record keeps its identity across the round trip.
+Google constrains an event id to **lower-case base32hex**: 5-1024
+characters from `0-9a-v` only. So no `w`, `x`, `y` or `z`, no upper
+case, no hyphen, no underscore, no dot.
+
+A semantic id anyone would reach for — `team-standup`, `Weekly_Sync`,
+`2026-07-17` — breaks the rule on the hyphen, the case or the letters.
+Records created through the collection UI get a generated id that
+satisfies it; only a primary key someone typed or imported can fail.
+
+### Fix
+
+Recreate the record without setting the primary field, and let the UI
+generate the id. If the id has to be meaningful, it can be — as long as
+every character is a digit or a letter `a` through `v` and there are at
+least five of them (`teamstandup` passes, `team-standup` does not).
+
+Renaming the primary key of an EXISTING record means deleting it and
+adding it again: the primary key is the record's identity, so nothing
+else reassigns it.
+
+## A record keeps showing as "edited" and the same push repeats forever
+
+### Symptoms
+
+The same record is pushed on every cycle with content that never
+changes, and the Google event's `updated` moves each time. No conflict
+is reported and no data is lost — the calendar just receives the same
+write over and over.
+
+### Cause
+
+The push compares the record against the BASELINE in
+`<workspace>/data/calendar/.push-state.json`, and the baseline advances
+only when a PULL reports the event as changed. If a write reaches Google
+but does NOT change the event's stored value — Google normalising the
+value it was sent, or a write of the value the event already held — then
+Google reports no change, the pull never sees the event, and the
+baseline stays behind. The next push sees the same difference again.
+
+This was checked on a live calendar and the Events API did **not**
+normalise `description` HTML (empty `<div>`, `style` attributes and all
+survived a round trip byte-for-byte), so it is not the common case. It
+is written down because the SYMPTOM is indistinguishable from a real
+repeated edit, and the two are told apart the same way.
+
+### Fix
+
+Look at the baseline, not at the record. Read the event's entry in
+`.push-state.json` and compare it with what `google` (`kind:
+"calendarListEvents"`) reports for that event id:
+
+- **Baseline matches Google, record differs** — an ordinary unpushed
+  edit. Nothing is wrong; the next push sends it.
+- **Baseline differs from Google** — the baseline is stale. `autoPush`
+  does NOT fix this one: it converges only when the push actually
+  changed the stored value, because only then does the pull carry the
+  event. Press Sync to force a pull; if the event is still not reported,
+  the value Google holds is already what the push keeps sending, and the
+  baseline has to be rebuilt.
+
+Rebuilding: delete the calendar's entry from `.push-state.json` (or the
+file, if it covers only that calendar) and press Sync. The next pull
+writes a fresh baseline from Google's current values. Tell the user
+first — until that pull lands, a genuine unpushed local edit would be
+indistinguishable from a mirrored one.
+
 ## A calendar collection only ever holds a handful of records
 
 ### Symptoms

package/assets/helps/google-calendar-collection.md

@@ -17,6 +17,7 @@ author the schema when the user asks for one.
 | Google → collection | the `googleCalendar` block | hourly, on creation, and on the **Sync** button |
 | collection → Google | the **Push to Google** button | whenever the user clicks it |
 | collection → Google | `"autoPush": true` in the block | hourly, immediately before each pull |
+| collection → Google, deletions | `"propagateDeletes": true` in the block | with every push. Off by default; see "Deleting" |
 
 When a user asks for "two-way sync", `autoPush` is the answer: set it and each
 scheduled run pushes local edits up and then pulls Google's changes down, as one
@@ -66,6 +67,9 @@ it isn't, sync silently does nothing until they link it in settings.
   would see rows with no content.
 - `autoPush` — push local edits on the sync schedule, just before each pull.
   Omit it (the default) and the push stays a button. See "Both directions".
+- `propagateDeletes` — delete the Google event when its record is deleted here.
+  Omit it (the default) and a local deletion is reported and nothing else. See
+  "Deleting".
 
 Mappable event fields, two-way first: `summary`, `start`, `end`, `description`,
 `location`, `colorId`.
@@ -78,15 +82,56 @@ time),
 `transparency` (`"transparent"` when the event does not consume the attendee's
 time; `""` means opaque), `eventType` (all six Google returns: `default` / `birthday` / `focusTime` /
 `fromGmail` / `outOfOffice` / `workingLocation`), `hangoutLink` (the Meet URL),
-`recurringEventId` and `originalStartTime`.
+`recurringEventId`, `originalStartTime`, `selfResponseStatus` and
+`conferenceVideoUri`.
 
-The last two are how a recurring series stays legible. The sync asks Google to
-expand recurrences, so a weekly meeting arrives as one event per occurrence;
-`recurringEventId` names the series each occurrence came from (`""` for a
-one-off), and `originalStartTime` is the slot the occurrence held before anyone
-dragged it — so a moved occurrence reads as a move rather than as a deletion
-plus a new event. Map them when the user asks why one calendar edit produced a
-large batch of record changes.
+`recurringEventId` and `originalStartTime` are how a recurring series stays
+legible. The sync asks Google to expand recurrences, so a weekly meeting arrives
+as one event per occurrence; `recurringEventId` names the series each occurrence
+came from (`""` for a one-off), and `originalStartTime` is the slot the
+occurrence held before anyone dragged it — so a moved occurrence reads as a move
+rather than as a deletion plus a new event. Map them when the user asks why one
+calendar edit produced a large batch of record changes.
+
+### `selfResponseStatus` and `conferenceVideoUri`
+
+These two are not Google field names. Google answers `attendees` as an ARRAY and
+`conferenceData` as an array inside an object, and a collection field holds one
+value — so each is folded down to the single scalar the collection asks it for.
+The rest of those structures is dropped; there is no way to map the attendee
+list itself.
+
+**`selfResponseStatus`** — the signed-in user's own `responseStatus`:
+`needsAction`, `declined`, `tentative` or `accepted`.
+
+`""` means Google reported none, and that is the COMMON case, not an edge one:
+an event with no attendees has no entry to mark as the user, which is most of a
+personal calendar. So it reads as "nothing said", never as "not going".
+
+Filter with **`!= "declined"`**, never with `== "accepted"` — the second hides
+every solo event too. A `flag` field is the usual way:
+
+```jsonc
+"fields": {
+  "rsvp":    { "type": "string", "label": "RSVP" },
+  "onMySchedule": {
+    "type": "flag",
+    "label": "Mine",
+    "where": [{ "field": "rsvp", "op": "ne", "value": "declined" }]
+  }
+},
+"googleCalendar": { "map": { "rsvp": "selfResponseStatus" } }
+```
+
+**`conferenceVideoUri`** — the URL that joins the meeting, taken from the
+`video` entry point. `""` when the event has no conference, and also when its
+only entry points are a phone number or a dial-in page: a column named for
+joining that sometimes held `tel:` would be worse than one the caller can see is
+empty.
+
+`hangoutLink` already carries this for Google Meet. `conferenceVideoUri` is what
+reaches a calendar whose meetings are Zoom or Teams. A Meet event fills both, so
+map whichever the user's calendar actually uses.
 
 `description` is the event body, and Google stores limited **HTML** in it. It is
 kept verbatim — mirroring it through a plain-text field and pushing it back would
@@ -106,6 +151,39 @@ Declaring it in `map` is a schema error.
 Use `datetime` (not `date`) for start/end when events have real clock times —
 the calendar day view then draws each record as a proportional time block.
 
+## All-day events
+
+A `datetime` column stores an all-day event as `2026-07-17T00:00`, because that
+is where the day view places it. That is fine for mirroring, but it is also
+exactly how a real midnight appointment is stored — so a record CREATED locally
+in a `datetime` column is pushed as a midnight event, never as an all-day one.
+
+For a calendar whose events are all-day, give start/end a **`date`** column
+instead. Google's bare date is then kept verbatim, and a record the user creates
+by typing two dates is pushed as a real all-day event.
+
+```jsonc
+"fields": {
+  "on":    { "type": "date", "label": "From" },
+  "until": { "type": "date", "label": "To" }
+},
+"googleCalendar": { "map": { "on": "start", "until": "end" } }
+```
+
+Google's all-day `end` is **exclusive** — it is the day AFTER the last day, so a
+single day on the 17th is `on: 2026-07-17`, `until: 2026-07-18`. Records
+mirrored from Google already carry it that way. Say so when the user asks why
+the end date "looks a day late"; do not offset it, because the push sends the
+stored value straight back.
+
+An existing all-day event stays all-day when its dates are edited, whatever the
+column type: the push reads what Google last reported for that event and keeps
+its kind. Only a record with no such history — one created locally — depends on
+the column type.
+
+To create a one-off all-day event without a collection, use the `google` tool's
+`calendarCreateEvent` with a bare date on both ends.
+
 ## When sync runs
 
 - **On creation** — the first sync starts as soon as the schema lands, so the
@@ -157,10 +235,9 @@ What the button does and deliberately does not do:
 - **Creates** an event for a record that never came from a sync.
 - **Updates** only the fields the user actually changed, so attendees,
   reminders and recurrence rules stay untouched.
-- **Never deletes.** A record deleted locally leaves its Google event alone —
-  a Google delete removes the event for every attendee and cannot be undone.
-  The count is reported so the user knows it was skipped; deleting for real is
-  the `google` tool's `calendarDeleteEvent`, after confirming with them.
+- **Never deletes, unless the collection asked it to.** See "Deleting" below;
+  without `propagateDeletes` a record deleted locally leaves its Google event
+  alone and the count is reported so the user knows.
 - **Skips a record edited on both sides** and reports it, rather than picking a
   winner. The user resolves it by editing one side to match. Under `autoPush`
   the pull that follows leaves that record alone too, so the local edit is not
@@ -174,9 +251,11 @@ What the button does and deliberately does not do:
 Reasons a record can be reported as skipped:
 
 - **Its record id cannot be a Google event id.** Google requires 5-1024
-  characters from `0-9a-v`. Records created through the UI get a valid
-  generated id; a semantic id you authored (`team-standup`) cannot be used. Fix
-  by recreating the record without setting the primary field.
+  characters from `0-9a-v` (lower-case base32hex: digits plus `a`-`v`, so no
+  `w`-`z`, no upper case, no hyphen). Records created through the UI get a
+  valid generated id; a semantic id you authored (`team-standup`) cannot be
+  used. Fix by recreating the record without setting the primary field, or by
+  choosing an id that satisfies the rule.
 - **No `start` / `end` is mapped, on a record being CREATED.** An event cannot
   be created without a span. Editing an existing event is unaffected — a changed
   title or colour is patched on its own.
@@ -190,6 +269,42 @@ reach by id but has not added to their calendar list has no role to check, so
 the push goes ahead and reports Google's own refusal if the write turns out not
 to be allowed — being unlisted is not treated as being read-only.
 
+## Deleting
+
+By default, a record deleted in the collection leaves its Google event alone.
+The push reports the count and does nothing else, and the next sync brings the
+record back — which is correct for a calendar Google owns, and wrong for one
+where the collection is the primary copy.
+
+`"propagateDeletes": true` in the `googleCalendar` block makes the push delete
+those events too. **Ask the user before adding it**, the same as `autoPush` and
+for a stronger reason: `autoPush` changes WHEN a write happens, this makes a
+write irreversible.
+
+Even on, the push **refuses an event that carries attendees** and reports it
+instead. Deleting an invited event withdraws it from the guests' calendars,
+which is a different act from tidying your own. **Any** attendee entry refuses,
+including the one Google adds for the organiser — so an event only the user was
+ever on is refused too, deliberately: telling the two apart means deciding which
+entry is the user from a payload that may not say, and being wrong there
+withdraws a real invitation. Either way, an event the user actually wants gone
+is deleted with the `google` tool's `calendarDeleteEvent`, after confirming with
+them.
+
+The delete also carries the version the check was made against, so an attendee
+added while the push was running makes Google refuse it rather than letting a
+decision taken a moment earlier stand. That is reported like any other refusal;
+pressing Push again re-checks.
+
+There is no undo here and this app keeps no copy of what it deleted. Google
+Calendar's own Trash holds a deleted event for a while, and that is where a
+mistake is recovered from.
+
+A deletion that carried stops being reported, because its baseline entry goes
+with it. A deletion that was REFUSED keeps being reported on every push — the
+event is still standing in Google, and the report is the only thing that says
+so.
+
 ## Not for this
 
 A `dataSource` (CSV-backed) collection is read-only and cannot declare

package/assets/helps/google.md

@@ -32,13 +32,23 @@ from `calendarListCalendars` — to target another.
 | `calendarColors` | Palettes mapping a `colorId` to hex, for events and for calendars |
 | `calendarListEvents` | Upcoming events. Optional `calendarId`, `timeMin`, `maxResults` (1-50, default 10) |
 | `calendarSync` | Only what CHANGED since the last sync, via a stored token. Returns counts plus a capped sample |
-| `calendarCreateEvent` | Create. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
+| `calendarCreateEvent` | Create, timed or all-day. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
 | `calendarUpdateEvent` | Edit in place. Requires `eventId` + at least one of `summary`, `start`, `end`, `description`, `colorId` |
 | `calendarDeleteEvent` | Delete. Requires `eventId` |
 
-**Date-times must carry a timezone offset** — `2026-07-17T09:00:00+09:00`, not
-`2026-07-17` and not `2026-07-17T09:00:00`. Calendar rejects the others with an
-opaque 400.
+**A timed event's ends must carry a timezone offset** —
+`2026-07-17T09:00:00+09:00`, not `2026-07-17T09:00:00`. Calendar rejects an
+offset-less value with an opaque 400. The same goes for `timeMin`.
+
+**An all-day event takes a bare date on BOTH ends** — `start: "2026-07-17"`,
+`end: "2026-07-18"`. Its `end` is **exclusive**: it is the day AFTER the last
+day, so a single day on the 17th ends on the 18th, and a three-day event
+starting the 17th ends on the 20th. This is Google's own convention and the
+values it reports back, so do not "correct" it.
+
+One end of each kind is rejected. Editing an all-day event needs **both** ends —
+a lone date is refused, because whether the stored event is all-day cannot be
+told from the argument.
 
 **Editing is a patch.** Fields you omit keep their current value, so changing a
 title needs `eventId` + `summary` and nothing else. `description: ""` clears the

package/dist/collection/core/schemaZ.d.ts

@@ -513,8 +513,12 @@ export declare const AgentIngestZ: z.ZodObject<{
  *  limitation: `transparency` is writable and `eventType` is writable at
  *  creation, yet neither is sent. That is also why
  *  widening this enum needs no `.push-state.json` migration: the push baseline
- *  (`ShadowEvent`) is keyed off the pushable list, not off this one. */
-export declare const GOOGLE_CALENDAR_SOURCE_FIELDS: readonly ["summary", "start", "end", "description", "location", "colorId", "htmlLink", "status", "recurringEventId", "originalStartTime", "updated", "transparency", "eventType", "hangoutLink"];
+ *  (`ShadowEvent`) is keyed off the pushable list, not off this one.
+ *
+ *  The last two are not Google field names but DERIVED scalars
+ *  (`google/eventDerived.ts`): the structures they come from are arrays, and a
+ *  collection field holds one value. */
+export declare const GOOGLE_CALENDAR_SOURCE_FIELDS: readonly ["summary", "start", "end", "description", "location", "colorId", "htmlLink", "status", "recurringEventId", "originalStartTime", "updated", "transparency", "eventType", "hangoutLink", "selfResponseStatus", "conferenceVideoUri"];
 /** Marks a collection as the destination of the LLM-free Google Calendar
  *  sync (#2095). `map` is collectionField → Google event field, so the user's
  *  collection keeps whatever field names it already uses. */
@@ -535,8 +539,11 @@ export declare const GoogleCalendarSyncZ: z.ZodObject<{
         transparency: "transparency";
         eventType: "eventType";
         hangoutLink: "hangoutLink";
+        selfResponseStatus: "selfResponseStatus";
+        conferenceVideoUri: "conferenceVideoUri";
     }>>;
     autoPush: z.ZodOptional<z.ZodBoolean>;
+    propagateDeletes: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** `ingest` is a discriminated union on `kind`: the three declarative
  *  retrievers fetch-and-map; `agent` dispatches a hidden worker. Optional on
@@ -1148,8 +1155,11 @@ declare const CollectionObjectZ: z.ZodObject<{
             transparency: "transparency";
             eventType: "eventType";
             hangoutLink: "hangoutLink";
+            selfResponseStatus: "selfResponseStatus";
+            conferenceVideoUri: "conferenceVideoUri";
         }>>;
         autoPush: z.ZodOptional<z.ZodBoolean>;
+        propagateDeletes: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     dynamicIcon: z.ZodOptional<z.ZodObject<{
         source: z.ZodObject<{
@@ -1646,8 +1656,11 @@ export declare const CollectionSchemaZ: z.ZodPreprocess<z.ZodObject<{
             transparency: "transparency";
             eventType: "eventType";
             hangoutLink: "hangoutLink";
+            selfResponseStatus: "selfResponseStatus";
+            conferenceVideoUri: "conferenceVideoUri";
         }>>;
         autoPush: z.ZodOptional<z.ZodBoolean>;
+        propagateDeletes: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     dynamicIcon: z.ZodOptional<z.ZodObject<{
         source: z.ZodObject<{

package/dist/collection/core/viewChatPolicy.d.ts

@@ -7,7 +7,10 @@ import { CollectionCustomView } from './schema';
  *  code composes the prompt text; letting it also decide whether that text runs
  *  would put both halves of the decision inside the sandbox.
  *
- *  The phone runtime does not consult this: it always sends, because a phone has
- *  no Enter key for the user to press (receptron/mulmoterminal#1253). The flag
- *  governs the desktop custom view and the desktop phone-frame preview. */
+ *  EVERY surface consults this, the phone included. The phone once always sent,
+ *  on the grounds that it has no Enter key to press — but that made the same
+ *  view behave differently depending on where it was opened, and it silently
+ *  overrode default-deny on a device the author never tested. The phone is
+ *  served the resolved flag in its view payload rather than re-reading the
+ *  schema, because it never sees the schema. */
 export declare function customViewSendsChat(view: Pick<CollectionCustomView, "allowSendChat">): boolean;

package/dist/collection/index.cjs

@@ -368,9 +368,12 @@ function firstMissingRequiredField(draft, schema) {
 *  code composes the prompt text; letting it also decide whether that text runs
 *  would put both halves of the decision inside the sandbox.
 *
-*  The phone runtime does not consult this: it always sends, because a phone has
-*  no Enter key for the user to press (receptron/mulmoterminal#1253). The flag
-*  governs the desktop custom view and the desktop phone-frame preview. */
+*  EVERY surface consults this, the phone included. The phone once always sent,
+*  on the grounds that it has no Enter key to press — but that made the same
+*  view behave differently depending on where it was opened, and it silently
+*  overrode default-deny on a device the author never tested. The phone is
+*  served the resolved flag in its view payload rather than re-reading the
+*  schema, because it never sees the schema. */
 function customViewSendsChat(view) {
 	return view.allowSendChat === true;
 }