@chipmobilesdk/rn-notification 0.6.0 → 0.7.0

package/lib/module/schedule/anchor.js

@@ -0,0 +1,234 @@
+"use strict";
+
+/**
+ * Time-zone anchoring and re-anchoring.
+ *
+ * Wall-clock is the default because reminders are wall-clock things: an 08:00
+ * reminder should stay 08:00 after the user crosses a time zone, and a caller
+ * who does not choose should get what their users expect rather than a silent
+ * shift.
+ *
+ * The cost is re-anchoring. When the device zone changes, every scheduled
+ * wall-clock entry must be rewritten to preserve the clock time it named, and
+ * every absolute entry must be left completely alone.
+ *
+ * The limit this cannot fix is stated rather than hidden: a wall-clock
+ * notification whose moment arrives while the app has not run since the zone
+ * changed fires at the previously anchored instant. The anchoring generation on
+ * each entry is what makes that detectable instead of invisible.
+ */
+
+import { getDateTimeFormat, isValidTimeZone as isZoneValid, lazyPeer } from '@chipmobilesdk/rn-core';
+import { DEFAULT_ANCHORING_MODE } from "../contract/notification.js";
+
+/** Reads the platform time zone. Injected so the pure logic needs no native module. */
+
+const localizePeer = lazyPeer('react-native-localize', () => {
+  // Inside `try`, so Metro bundles an app that leaves this optional peer out.
+  try {
+    return require('react-native-localize');
+  } catch (cause) {
+    throw cause;
+  }
+});
+
+/**
+ * Resolves the platform zone via `react-native-localize`.
+ *
+ * Pure JavaScript is not sufficient here: `Intl.DateTimeFormat().resolvedOptions().timeZone`
+ * is documented in React Native as not reliably updating when the device zone
+ * changes, so it cannot back re-anchoring. Falls back to `Intl` only when the
+ * module is absent, which is better than failing outright.
+ */
+export function createPlatformTimeZoneReader() {
+  return () => {
+    const localize = localizePeer.get();
+    try {
+      if (localize.ok) return localize.module.getTimeZone();
+      return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+    } catch {
+      try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+      } catch {
+        return 'UTC';
+      }
+    }
+  };
+}
+
+/** The calendar fields a wall-clock moment actually names. */
+
+/**
+ * Whether a zone name is one the runtime can actually format against.
+ *
+ * Hermes throws a hard `JSRangeErrorException: Invalid timezone name!` for a
+ * bad zone, which kills the JavaScript thread rather than returning an error.
+ * A stored anchoring generation is data that can be wrong — a corrupted record,
+ * an entry written by an older build, or a defect like the one that stored a
+ * tone id here — so it must be checked before it reaches `Intl`.
+ */
+export function isValidTimeZone(timeZone) {
+  // rn-core memoizes the answer per zone: a recurrence expansion asks thousands
+  // of times about the same few zones (PERF-01).
+  return isZoneValid(timeZone);
+}
+
+/** The options `partsInZone` formats with; one shared formatter per zone. */
+const PARTS_OPTIONS = {
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hour12: false
+};
+
+/**
+ * Decomposes an instant into the clock reading it produces in a given zone.
+ *
+ * Falls back to UTC for an unusable zone rather than throwing: a bad stored
+ * value should degrade one entry's anchoring, not crash the app.
+ */
+export function partsInZone(instant, timeZone) {
+  const zone = isValidTimeZone(timeZone) ? timeZone : 'UTC';
+  // Built once per zone and reused (PERF-01): constructing one per call was
+  // most of the cost of expanding a recurrence.
+  const formatter = getDateTimeFormat('en-US', {
+    ...PARTS_OPTIONS,
+    timeZone: zone
+  });
+  const fields = {};
+  for (const part of formatter.formatToParts(new Date(instant))) {
+    if (part.type !== 'literal') {
+      fields[part.type] = Number.parseInt(part.value, 10);
+    }
+  }
+  return {
+    year: fields.year,
+    month: fields.month,
+    day: fields.day,
+    // Intl renders midnight as hour 24 in some environments; normalize it.
+    hour: fields.hour === 24 ? 0 : fields.hour,
+    minute: fields.minute,
+    second: fields.second
+  };
+}
+
+/** The zone's offset from UTC, in milliseconds, at a given instant. */
+function offsetAt(instant, timeZone) {
+  const parts = partsInZone(instant, timeZone);
+  const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+  return asUtc - Math.floor(instant / 1000) * 1000;
+}
+
+/**
+ * Finds the instant at which a zone shows the given clock reading.
+ *
+ * Two passes, because the offset itself depends on the instant: the first guess
+ * uses the offset at the naive UTC interpretation, the second corrects for a
+ * daylight-saving boundary crossed by that guess.
+ *
+ * Daylight-saving resolution, per the documented rule:
+ * - a clock time that does not exist resolves **forward** to the next valid instant;
+ * - a clock time that occurs twice resolves to its **first** occurrence, so
+ *   exactly one notification results rather than two.
+ */
+export function instantForParts(parts, timeZone) {
+  const naive = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+  let candidate = naive - offsetAt(naive, timeZone);
+  candidate = naive - offsetAt(candidate, timeZone);
+  const rendered = partsInZone(candidate, timeZone);
+  if (rendered.hour === parts.hour && rendered.minute === parts.minute) {
+    // Ambiguous readings (the repeated hour) land here on the first, earlier
+    // offset, which is the documented choice.
+    return candidate;
+  }
+
+  // The reading does not exist in this zone — a spring-forward gap. Step
+  // forward to the next instant that does exist rather than skipping the
+  // occurrence or failing.
+  const gapStep = 60 * 60 * 1000;
+  for (let attempt = 1; attempt <= 4; attempt += 1) {
+    const shifted = candidate + gapStep * attempt;
+    const shiftedParts = partsInZone(shifted, timeZone);
+    if (shiftedParts.day === parts.day || shiftedParts.hour > parts.hour) {
+      return shifted;
+    }
+  }
+  return candidate;
+}
+/**
+ * Resolves a caller-supplied moment into a firing instant.
+ *
+ * An absolute moment passes through untouched — that is the entire distinction.
+ */
+export function anchorMoment(input, timeZone) {
+  const anchoring = input.anchoring ?? DEFAULT_ANCHORING_MODE;
+  if (anchoring === 'absolute') {
+    return {
+      resolvedAt: input.at,
+      anchoring
+    };
+  }
+  return {
+    resolvedAt: input.at,
+    anchoring,
+    generation: timeZone
+  };
+}
+/**
+ * Computes what a zone change requires.
+ *
+ * Returns an empty plan when the zone has not moved, which is what makes
+ * re-anchoring idempotent: the no-change check costs one comparison per entry
+ * and issues zero platform operations.
+ */
+export function planReAnchor(pending, currentZone) {
+  const rewrites = [];
+  const unreadableGeneration = [];
+  let fromZone;
+  for (const entry of pending) {
+    // Absolute-instant entries are never re-anchored, re-scheduled, or touched.
+    if (entry.anchoring === 'absolute') continue;
+    const generation = entry.anchoringGeneration;
+    if (generation === undefined || generation === currentZone) continue;
+
+    // A stored generation is data, and data can be wrong. Re-anchoring against
+    // a zone the runtime cannot read would move the entry to an arbitrary
+    // instant, which is worse than leaving it where it is and saying so.
+    if (!isValidTimeZone(generation)) {
+      unreadableGeneration.push(entry.id);
+      continue;
+    }
+    fromZone ??= generation;
+
+    // Preserve the clock reading the entry originally named, not the instant.
+    const originalParts = partsInZone(entry.resolvedAt, generation);
+    const resolvedAt = instantForParts(originalParts, currentZone);
+    if (resolvedAt !== entry.resolvedAt) {
+      rewrites.push({
+        entry,
+        resolvedAt
+      });
+    }
+  }
+  return {
+    rewrites,
+    fromZone,
+    toZone: currentZone,
+    zoneChanged: rewrites.length > 0 || fromZone !== undefined,
+    unreadableGeneration
+  };
+}
+
+/**
+ * True when an entry was anchored against a zone the device has since left.
+ *
+ * This is the FR-007c condition: the entry will fire at its old instant, and a
+ * consumer can detect and explain that rather than being told nothing happened.
+ */
+export function isStaleAnchor(entry, currentZone) {
+  return entry.anchoring === 'wallClock' && entry.anchoringGeneration !== undefined && entry.anchoringGeneration !== currentZone;
+}
+//# sourceMappingURL=anchor.js.map

package/lib/module/schedule/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["getDateTimeFormat","isValidTimeZone","isZoneValid","lazyPeer","DEFAULT_ANCHORING_MODE","localizePeer","require","cause","createPlatformTimeZoneReader","localize","get","ok","module","getTimeZone","Intl","DateTimeFormat","resolvedOptions","timeZone","PARTS_OPTIONS","year","month","day","hour","minute","second","hour12","partsInZone","instant","zone","formatter","fields","part","formatToParts","Date","type","Number","parseInt","value","offsetAt","parts","asUtc","UTC","Math","floor","instantForParts","naive","candidate","rendered","gapStep","attempt","shifted","shiftedParts","anchorMoment","input","anchoring","resolvedAt","at","generation","planReAnchor","pending","currentZone","rewrites","unreadableGeneration","fromZone","entry","anchoringGeneration","undefined","push","id","originalParts","toZone","zoneChanged","length","isStaleAnchor"],"sourceRoot":"../../../src","sources":["schedule/anchor.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SACCA,iBAAiB,EACjBC,eAAe,IAAIC,WAAW,EAC9BC,QAAQ,QACF,wBAAwB;AAG/B,SAASC,sBAAsB,QAAQ,6BAA0B;;AAEjE;;AAGA,MAAMC,YAAY,GAAGF,QAAQ,CAAC,uBAAuB,EAAE,MAAM;EAC5D;EACA,IAAI;IACH,OAAOG,OAAO,CAAC,uBAAuB,CAAC;EACxC,CAAC,CAAC,OAAOC,KAAK,EAAE;IACf,MAAMA,KAAK;EACZ;AACD,CAAC,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,4BAA4BA,CAAA,EAAmB;EAC9D,OAAO,MAAM;IACZ,MAAMC,QAAQ,GAAGJ,YAAY,CAACK,GAAG,CAAC,CAAC;IACnC,IAAI;MACH,IAAID,QAAQ,CAACE,EAAE,EAAE,OAAOF,QAAQ,CAACG,MAAM,CAACC,WAAW,CAAC,CAAC;MACrD,OAAOC,IAAI,CAACC,cAAc,CAAC,CAAC,CAACC,eAAe,CAAC,CAAC,CAACC,QAAQ,IAAI,KAAK;IACjE,CAAC,CAAC,MAAM;MACP,IAAI;QACH,OAAOH,IAAI,CAACC,cAAc,CAAC,CAAC,CAACC,eAAe,CAAC,CAAC,CAACC,QAAQ,IAAI,KAAK;MACjE,CAAC,CAAC,MAAM;QACP,OAAO,KAAK;MACb;IACD;EACD,CAAC;AACF;;AAEA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAAShB,eAAeA,CAACgB,QAAgB,EAAW;EAC1D;EACA;EACA,OAAOf,WAAW,CAACe,QAAQ,CAAC;AAC7B;;AAEA;AACA,MAAMC,aAAa,GAAG;EACrBC,IAAI,EAAE,SAAS;EACfC,KAAK,EAAE,SAAS;EAChBC,GAAG,EAAE,SAAS;EACdC,IAAI,EAAE,SAAS;EACfC,MAAM,EAAE,SAAS;EACjBC,MAAM,EAAE,SAAS;EACjBC,MAAM,EAAE;AACT,CAAU;;AAEV;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAACC,OAAe,EAAEV,QAAgB,EAAkB;EAC9E,MAAMW,IAAI,GAAG3B,eAAe,CAACgB,QAAQ,CAAC,GAAGA,QAAQ,GAAG,KAAK;EACzD;EACA;EACA,MAAMY,SAAS,GAAG7B,iBAAiB,CAAC,OAAO,EAAE;IAAE,GAAGkB,aAAa;IAAED,QAAQ,EAAEW;EAAK,CAAC,CAAC;EAElF,MAAME,MAA8B,GAAG,CAAC,CAAC;EACzC,KAAK,MAAMC,IAAI,IAAIF,SAAS,CAACG,aAAa,CAAC,IAAIC,IAAI,CAACN,OAAO,CAAC,CAAC,EAAE;IAC9D,IAAII,IAAI,CAACG,IAAI,KAAK,SAAS,EAAE;MAC5BJ,MAAM,CAACC,IAAI,CAACG,IAAI,CAAC,GAAGC,MAAM,CAACC,QAAQ,CAACL,IAAI,CAACM,KAAK,EAAE,EAAE,CAAC;IACpD;EACD;EAEA,OAAO;IACNlB,IAAI,EAAEW,MAAM,CAACX,IAAI;IACjBC,KAAK,EAAEU,MAAM,CAACV,KAAK;IACnBC,GAAG,EAAES,MAAM,CAACT,GAAG;IACf;IACAC,IAAI,EAAEQ,MAAM,CAACR,IAAI,KAAK,EAAE,GAAG,CAAC,GAAGQ,MAAM,CAACR,IAAI;IAC1CC,MAAM,EAAEO,MAAM,CAACP,MAAM;IACrBC,MAAM,EAAEM,MAAM,CAACN;EAChB,CAAC;AACF;;AAEA;AACA,SAASc,QAAQA,CAACX,OAAe,EAAEV,QAAgB,EAAU;EAC5D,MAAMsB,KAAK,GAAGb,WAAW,CAACC,OAAO,EAAEV,QAAQ,CAAC;EAC5C,MAAMuB,KAAK,GAAGP,IAAI,CAACQ,GAAG,CACrBF,KAAK,CAACpB,IAAI,EACVoB,KAAK,CAACnB,KAAK,GAAG,CAAC,EACfmB,KAAK,CAAClB,GAAG,EACTkB,KAAK,CAACjB,IAAI,EACViB,KAAK,CAAChB,MAAM,EACZgB,KAAK,CAACf,MACP,CAAC;EACD,OAAOgB,KAAK,GAAGE,IAAI,CAACC,KAAK,CAAChB,OAAO,GAAG,IAAI,CAAC,GAAG,IAAI;AACjD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASiB,eAAeA,CAACL,KAAqB,EAAEtB,QAAgB,EAAU;EAChF,MAAM4B,KAAK,GAAGZ,IAAI,CAACQ,GAAG,CACrBF,KAAK,CAACpB,IAAI,EACVoB,KAAK,CAACnB,KAAK,GAAG,CAAC,EACfmB,KAAK,CAAClB,GAAG,EACTkB,KAAK,CAACjB,IAAI,EACViB,KAAK,CAAChB,MAAM,EACZgB,KAAK,CAACf,MACP,CAAC;EAED,IAAIsB,SAAS,GAAGD,KAAK,GAAGP,QAAQ,CAACO,KAAK,EAAE5B,QAAQ,CAAC;EACjD6B,SAAS,GAAGD,KAAK,GAAGP,QAAQ,CAACQ,SAAS,EAAE7B,QAAQ,CAAC;EAEjD,MAAM8B,QAAQ,GAAGrB,WAAW,CAACoB,SAAS,EAAE7B,QAAQ,CAAC;EAEjD,IAAI8B,QAAQ,CAACzB,IAAI,KAAKiB,KAAK,CAACjB,IAAI,IAAIyB,QAAQ,CAACxB,MAAM,KAAKgB,KAAK,CAAChB,MAAM,EAAE;IACrE;IACA;IACA,OAAOuB,SAAS;EACjB;;EAEA;EACA;EACA;EACA,MAAME,OAAO,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;EAC9B,KAAK,IAAIC,OAAO,GAAG,CAAC,EAAEA,OAAO,IAAI,CAAC,EAAEA,OAAO,IAAI,CAAC,EAAE;IACjD,MAAMC,OAAO,GAAGJ,SAAS,GAAGE,OAAO,GAAGC,OAAO;IAC7C,MAAME,YAAY,GAAGzB,WAAW,CAACwB,OAAO,EAAEjC,QAAQ,CAAC;IACnD,IAAIkC,YAAY,CAAC9B,GAAG,KAAKkB,KAAK,CAAClB,GAAG,IAAI8B,YAAY,CAAC7B,IAAI,GAAGiB,KAAK,CAACjB,IAAI,EAAE;MACrE,OAAO4B,OAAO;IACf;EACD;EAEA,OAAOJ,SAAS;AACjB;AAcA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASM,YAAYA,CAACC,KAAkB,EAAEpC,QAAgB,EAAkB;EAClF,MAAMqC,SAAS,GAAGD,KAAK,CAACC,SAAS,IAAIlD,sBAAsB;EAE3D,IAAIkD,SAAS,KAAK,UAAU,EAAE;IAC7B,OAAO;MAAEC,UAAU,EAAEF,KAAK,CAACG,EAAE;MAAEF;IAAU,CAAC;EAC3C;EAEA,OAAO;IAAEC,UAAU,EAAEF,KAAK,CAACG,EAAE;IAAEF,SAAS;IAAEG,UAAU,EAAExC;EAAS,CAAC;AACjE;AAkBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASyC,YAAYA,CAACC,OAAgC,EAAEC,WAAmB,EAAgB;EACjG,MAAMC,QAAuD,GAAG,EAAE;EAClE,MAAMC,oBAA8B,GAAG,EAAE;EACzC,IAAIC,QAA4B;EAEhC,KAAK,MAAMC,KAAK,IAAIL,OAAO,EAAE;IAC5B;IACA,IAAIK,KAAK,CAACV,SAAS,KAAK,UAAU,EAAE;IAEpC,MAAMG,UAAU,GAAGO,KAAK,CAACC,mBAAmB;IAC5C,IAAIR,UAAU,KAAKS,SAAS,IAAIT,UAAU,KAAKG,WAAW,EAAE;;IAE5D;IACA;IACA;IACA,IAAI,CAAC3D,eAAe,CAACwD,UAAU,CAAC,EAAE;MACjCK,oBAAoB,CAACK,IAAI,CAACH,KAAK,CAACI,EAAE,CAAC;MACnC;IACD;IAEAL,QAAQ,KAAKN,UAAU;;IAEvB;IACA,MAAMY,aAAa,GAAG3C,WAAW,CAACsC,KAAK,CAACT,UAAU,EAAEE,UAAU,CAAC;IAC/D,MAAMF,UAAU,GAAGX,eAAe,CAACyB,aAAa,EAAET,WAAW,CAAC;IAE9D,IAAIL,UAAU,KAAKS,KAAK,CAACT,UAAU,EAAE;MACpCM,QAAQ,CAACM,IAAI,CAAC;QAAEH,KAAK;QAAET;MAAW,CAAC,CAAC;IACrC;EACD;EAEA,OAAO;IACNM,QAAQ;IACRE,QAAQ;IACRO,MAAM,EAAEV,WAAW;IACnBW,WAAW,EAAEV,QAAQ,CAACW,MAAM,GAAG,CAAC,IAAIT,QAAQ,KAAKG,SAAS;IAC1DJ;EACD,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASW,aAAaA,CAACT,KAAmB,EAAEJ,WAAmB,EAAW;EAChF,OACCI,KAAK,CAACV,SAAS,KAAK,WAAW,IAC/BU,KAAK,CAACC,mBAAmB,KAAKC,SAAS,IACvCF,KAAK,CAACC,mBAAmB,KAAKL,WAAW;AAE3C","ignoreList":[]}

package/lib/module/schedule/index.js

@@ -0,0 +1,137 @@
+"use strict";
+
+/**
+ * The scheduling operations.
+ *
+ * Validation runs in a fixed order and completes entirely before any platform
+ * call: identifier, tags, content, moment shape, tone, actions, routing size.
+ * A caller therefore never sees a native-level error surface through the
+ * package, and a rejected request leaves the device untouched.
+ *
+ * Scheduling an identifier that already has a notification **replaces** it.
+ * That is the defined semantic rather than a side effect, which is what lets a
+ * caller stop tracking whether it has already scheduled something.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+import { MAX_ACTIONS_PER_NOTIFICATION, MAX_ROUTING_PAYLOAD_BYTES } from "../contract/interaction.js";
+import { validateIdentifier, validateOptionalTag } from "./validate-identifier.js";
+import { validateContent, byteLength } from "./validate-content.js";
+import { resolveMoment, validateMoment } from "./resolve-moment.js";
+import { anchorMoment } from "./anchor.js";
+import { idsForTag } from "./partition.js";
+import { createScheduleWriter } from "./writer.js";
+/** Validates a request completely, before the engine is touched at all. */
+export function validateRequest(request, resolveTone) {
+  validateIdentifier(request.id, 'id');
+  validateOptionalTag(request.ownerTag, 'ownerTag');
+  validateOptionalTag(request.groupTag, 'groupTag');
+  validateContent(request.content);
+  validateMoment(request.moment);
+  const tone = resolveTone(request.tone);
+  if (tone === undefined) {
+    throw new NotificationError(DIAGNOSTIC_CODES.UNDECLARED_TONE, `Tone "${request.tone}" was never declared in the package configuration. Declare it before scheduling against it.`, {
+      toneId: request.tone
+    });
+  }
+  if (request.actions !== undefined) {
+    if (request.actions.length > MAX_ACTIONS_PER_NOTIFICATION) {
+      throw new NotificationError(DIAGNOSTIC_CODES.TOO_MANY_ACTIONS, `A notification may carry at most ${MAX_ACTIONS_PER_NOTIFICATION} actions; ${request.actions.length} were supplied.`, {
+        count: request.actions.length,
+        limit: MAX_ACTIONS_PER_NOTIFICATION
+      });
+    }
+    for (const action of request.actions) {
+      validateIdentifier(action.id, 'actionId');
+    }
+  }
+  if (request.routing !== undefined) {
+    // Sized at schedule time rather than discovered as truncated at tap time,
+    // which is where an over-large payload would otherwise surface.
+    const size = byteLength(JSON.stringify(request.routing));
+    if (size > MAX_ROUTING_PAYLOAD_BYTES) {
+      throw new NotificationError(DIAGNOSTIC_CODES.ROUTING_PAYLOAD_TOO_LARGE, `Routing payload is ${size} bytes, over the ${MAX_ROUTING_PAYLOAD_BYTES}-byte limit.`, {
+        bytes: size,
+        limit: MAX_ROUTING_PAYLOAD_BYTES
+      });
+    }
+  }
+  return tone;
+}
+export function createScheduler(deps) {
+  const emit = deps.emit ?? (() => {});
+  const writer = createScheduleWriter(deps.engine);
+  const scheduleOne = async (request, options = {}) => {
+    const tone = validateRequest(request, deps.resolveTone);
+    const zone = deps.timeZone();
+    const anchored = anchorMoment(request.moment, zone);
+    const resolution = resolveMoment(anchored.resolvedAt, deps.now());
+
+    // Identifiers only where the engine can list them cheaply: reading every
+    // pending payload across the bridge just to answer "was this one already
+    // there" cost a full read per schedule (NOT-08).
+    const replaced = deps.engine.pendingIds ? (await deps.engine.pendingIds()).includes(request.id) : (await deps.engine.getPending()).some(entry => entry.id === request.id);
+
+    // Approximate mode is a degradation, not a refusal: the notification is
+    // still scheduled and the caller is told it may arrive late.
+    const approximate = !deps.canScheduleExactly();
+    if (approximate) {
+      emit(DIAGNOSTIC_CODES.EXACT_ALARM_UNAVAILABLE, 'Scheduled in approximate mode; delivery may be late.', {
+        id: request.id
+      });
+    }
+    await writer.write({
+      request,
+      resolvedAt: resolution.at,
+      tone,
+      // The zone this was anchored against, so `getPending` can report it and a
+      // consumer can detect a stale anchor (FR-007c). Absent for absolute
+      // moments, which are never anchored to a zone.
+      anchoringGeneration: anchored.generation,
+      approximate,
+      seriesId: options.seriesId,
+      pushCreated: options.pushCreated
+    });
+    return {
+      id: request.id,
+      resolvedAt: resolution.at,
+      anchoring: anchored.anchoring,
+      replaced,
+      deliveredImmediately: resolution.kind === 'immediate',
+      mayBeDelayed: approximate
+    };
+  };
+  return {
+    schedule: scheduleOne,
+    async cancel(id) {
+      validateIdentifier(id, 'id');
+      // A marker guarding a notification that no longer exists would fire
+      // against nothing. Harmless, but it holds platform capacity a real
+      // notification could use.
+      await writer.cancel(id);
+    },
+    async cancelByGroup(groupTag) {
+      validateIdentifier(groupTag, 'groupTag');
+      const ids = idsForTag(await deps.engine.getPending(), 'group', groupTag);
+      await deps.engine.cancelMany(ids);
+      const pass = writer.pass();
+      for (const id of ids) await pass.releaseStop(id);
+      return ids;
+    },
+    async cancelByOwner(ownerTag) {
+      validateIdentifier(ownerTag, 'ownerTag');
+      const ids = idsForTag(await deps.engine.getPending(), 'owner', ownerTag);
+      await deps.engine.cancelMany(ids);
+      const pass = writer.pass();
+      for (const id of ids) await pass.releaseStop(id);
+      return ids;
+    },
+    async cancelAll() {
+      await deps.engine.cancelAll();
+    },
+    async getPending() {
+      return deps.engine.getPending();
+    }
+  };
+}
+//# sourceMappingURL=index.js.map

package/lib/module/schedule/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DIAGNOSTIC_CODES","NotificationError","MAX_ACTIONS_PER_NOTIFICATION","MAX_ROUTING_PAYLOAD_BYTES","validateIdentifier","validateOptionalTag","validateContent","byteLength","resolveMoment","validateMoment","anchorMoment","idsForTag","createScheduleWriter","validateRequest","request","resolveTone","id","ownerTag","groupTag","content","moment","tone","undefined","UNDECLARED_TONE","toneId","actions","length","TOO_MANY_ACTIONS","count","limit","action","routing","size","JSON","stringify","ROUTING_PAYLOAD_TOO_LARGE","bytes","createScheduler","deps","emit","writer","engine","scheduleOne","options","zone","timeZone","anchored","resolution","resolvedAt","now","replaced","pendingIds","includes","getPending","some","entry","approximate","canScheduleExactly","EXACT_ALARM_UNAVAILABLE","write","at","anchoringGeneration","generation","seriesId","pushCreated","anchoring","deliveredImmediately","kind","mayBeDelayed","schedule","cancel","cancelByGroup","ids","cancelMany","pass","releaseStop","cancelByOwner","cancelAll"],"sourceRoot":"../../../src","sources":["schedule/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/schedule/partition.js

@@ -0,0 +1,53 @@
+"use strict";
+
+/**
+ * Owner-tag and group-tag partitioning.
+ *
+ * A tag is an opaque label the caller supplies and the package never
+ * interprets. That is deliberate: modelling identity would mean acquiring an
+ * opinion about it, and this package is forbidden from knowing anything about
+ * accounts, tenants, or users.
+ *
+ * What the tag buys is one call — "clear this account's notifications" — on a
+ * shared device, without the package ever learning what an account is.
+ */
+
+/** Selects entries carrying a tag. Comparison is exact; nothing is normalized. */
+export function selectByTag(entries, kind, tag) {
+  return entries.filter(entry => kind === 'owner' ? entry.ownerTag === tag : entry.groupTag === tag);
+}
+
+/** Identifiers to cancel for a tag. */
+export function idsForTag(entries, kind, tag) {
+  return selectByTag(entries, kind, tag).map(entry => entry.id);
+}
+
+/**
+ * Groups entries by a tag, keeping untagged entries under a distinct bucket.
+ *
+ * Untagged is not the same as any tag: an entry with no owner belongs to no
+ * account, and folding it into one would make a sign-out delete notifications
+ * that were never that account's.
+ */
+export function partition(entries, kind) {
+  const tagged = new Map();
+  const untagged = [];
+  for (const entry of entries) {
+    const tag = kind === 'owner' ? entry.ownerTag : entry.groupTag;
+    if (tag === undefined) {
+      untagged.push(entry);
+      continue;
+    }
+    const bucket = tagged.get(tag);
+    if (bucket === undefined) {
+      tagged.set(tag, [entry]);
+    } else {
+      bucket.push(entry);
+    }
+  }
+  return {
+    tagged,
+    untagged
+  };
+}
+//# sourceMappingURL=partition.js.map

package/lib/module/schedule/partition.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["selectByTag","entries","kind","tag","filter","entry","ownerTag","groupTag","idsForTag","map","id","partition","tagged","Map","untagged","undefined","push","bucket","get","set"],"sourceRoot":"../../../src","sources":["schedule/partition.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA,OAAO,SAASA,WAAWA,CAC1BC,OAAgC,EAChCC,IAAmB,EACnBC,GAAW,EACe;EAC1B,OAAOF,OAAO,CAACG,MAAM,CAACC,KAAK,IAC1BH,IAAI,KAAK,OAAO,GAAGG,KAAK,CAACC,QAAQ,KAAKH,GAAG,GAAGE,KAAK,CAACE,QAAQ,KAAKJ,GAChE,CAAC;AACF;;AAEA;AACA,OAAO,SAASK,SAASA,CACxBP,OAAgC,EAChCC,IAAmB,EACnBC,GAAW,EACS;EACpB,OAAOH,WAAW,CAACC,OAAO,EAAEC,IAAI,EAAEC,GAAG,CAAC,CAACM,GAAG,CAACJ,KAAK,IAAIA,KAAK,CAACK,EAAE,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,SAASA,CACxBV,OAAgC,EAChCC,IAAmB,EAIlB;EACD,MAAMU,MAAM,GAAG,IAAIC,GAAG,CAAyB,CAAC;EAChD,MAAMC,QAAwB,GAAG,EAAE;EAEnC,KAAK,MAAMT,KAAK,IAAIJ,OAAO,EAAE;IAC5B,MAAME,GAAG,GAAGD,IAAI,KAAK,OAAO,GAAGG,KAAK,CAACC,QAAQ,GAAGD,KAAK,CAACE,QAAQ;IAC9D,IAAIJ,GAAG,KAAKY,SAAS,EAAE;MACtBD,QAAQ,CAACE,IAAI,CAACX,KAAK,CAAC;MACpB;IACD;IACA,MAAMY,MAAM,GAAGL,MAAM,CAACM,GAAG,CAACf,GAAG,CAAC;IAC9B,IAAIc,MAAM,KAAKF,SAAS,EAAE;MACzBH,MAAM,CAACO,GAAG,CAAChB,GAAG,EAAE,CAACE,KAAK,CAAC,CAAC;IACzB,CAAC,MAAM;MACNY,MAAM,CAACD,IAAI,CAACX,KAAK,CAAC;IACnB;EACD;EAEA,OAAO;IAAEO,MAAM;IAAEE;EAAS,CAAC;AAC5B","ignoreList":[]}

package/lib/module/schedule/resolve-moment.js

@@ -0,0 +1,66 @@
+"use strict";
+
+/**
+ * Delivery moment resolution.
+ *
+ * Two rules, and they are two sides of one decision rather than a threshold:
+ * a moment more than the tolerance in the past is a caller error and is
+ * refused; a moment a few seconds in the past is a processing delay and is
+ * delivered promptly. Both outcomes are reported, so a caller never has to
+ * guess which happened.
+ *
+ * Sixty seconds is long enough to absorb reconciling a large desired set, cold
+ * start work, and clock skew, and short enough that a genuinely stale schedule
+ * is still caught rather than fired at the user minutes late with no
+ * explanation.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+export const PAST_TOLERANCE_MS = 60_000;
+/**
+ * Classifies a resolved instant against now.
+ *
+ * Takes an already-anchored instant: anchoring decides *which* instant a moment
+ * means, and this decides whether that instant is usable. Keeping them separate
+ * is what lets each be tested without the other.
+ */
+export function resolveMoment(resolvedAt, now) {
+  if (!Number.isFinite(resolvedAt)) {
+    throw new NotificationError(DIAGNOSTIC_CODES.MOMENT_IN_PAST, 'A delivery moment must be a finite epoch-millisecond timestamp.', {
+      received: String(resolvedAt)
+    });
+  }
+  if (resolvedAt >= now) {
+    return {
+      kind: 'future',
+      at: resolvedAt
+    };
+  }
+  const lateBy = now - resolvedAt;
+  if (lateBy <= PAST_TOLERANCE_MS) {
+    return {
+      kind: 'immediate',
+      at: now,
+      lateBy
+    };
+  }
+  throw new NotificationError(DIAGNOSTIC_CODES.MOMENT_IN_PAST, `Delivery moment is ${Math.round(lateBy / 1000)}s in the past, beyond the ${PAST_TOLERANCE_MS / 1000}s tolerance. ` + 'It was not scheduled, because handing it to the platform would fire it immediately without explanation.', {
+    lateByMs: lateBy,
+    toleranceMs: PAST_TOLERANCE_MS
+  });
+}
+
+/** Validates the shape of a caller-supplied moment before anchoring resolves it. */
+export function validateMoment(moment) {
+  if (typeof moment.at !== 'number' || !Number.isFinite(moment.at)) {
+    throw new NotificationError(DIAGNOSTIC_CODES.MOMENT_IN_PAST, 'A delivery moment must carry a finite epoch-millisecond `at` value.', {
+      received: typeof moment.at
+    });
+  }
+  if (moment.anchoring !== undefined && moment.anchoring !== 'wallClock' && moment.anchoring !== 'absolute') {
+    throw new NotificationError(DIAGNOSTIC_CODES.MOMENT_IN_PAST, 'Anchoring must be either "wallClock" or "absolute".', {
+      received: String(moment.anchoring)
+    });
+  }
+}
+//# sourceMappingURL=resolve-moment.js.map

package/lib/module/schedule/resolve-moment.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DIAGNOSTIC_CODES","NotificationError","PAST_TOLERANCE_MS","resolveMoment","resolvedAt","now","Number","isFinite","MOMENT_IN_PAST","received","String","kind","at","lateBy","Math","round","lateByMs","toleranceMs","validateMoment","moment","anchoring","undefined"],"sourceRoot":"../../../src","sources":["schedule/resolve-moment.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,gBAAgB,EAAEC,iBAAiB,QAAQ,uBAAoB;AAGxE,OAAO,MAAMC,iBAAiB,GAAG,MAAM;AAMvC;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAACC,UAAkB,EAAEC,GAAW,EAAoB;EAChF,IAAI,CAACC,MAAM,CAACC,QAAQ,CAACH,UAAU,CAAC,EAAE;IACjC,MAAM,IAAIH,iBAAiB,CAC1BD,gBAAgB,CAACQ,cAAc,EAC/B,iEAAiE,EACjE;MAAEC,QAAQ,EAAEC,MAAM,CAACN,UAAU;IAAE,CAChC,CAAC;EACF;EAEA,IAAIA,UAAU,IAAIC,GAAG,EAAE;IACtB,OAAO;MAAEM,IAAI,EAAE,QAAQ;MAAEC,EAAE,EAAER;IAAW,CAAC;EAC1C;EAEA,MAAMS,MAAM,GAAGR,GAAG,GAAGD,UAAU;EAE/B,IAAIS,MAAM,IAAIX,iBAAiB,EAAE;IAChC,OAAO;MAAES,IAAI,EAAE,WAAW;MAAEC,EAAE,EAAEP,GAAG;MAAEQ;IAAO,CAAC;EAC9C;EAEA,MAAM,IAAIZ,iBAAiB,CAC1BD,gBAAgB,CAACQ,cAAc,EAC/B,sBAAsBM,IAAI,CAACC,KAAK,CAACF,MAAM,GAAG,IAAI,CAAC,6BAA6BX,iBAAiB,GAAG,IAAI,eAAe,GAClH,yGAAyG,EAC1G;IAAEc,QAAQ,EAAEH,MAAM;IAAEI,WAAW,EAAEf;EAAkB,CACpD,CAAC;AACF;;AAEA;AACA,OAAO,SAASgB,cAAcA,CAACC,MAAsB,EAAQ;EAC5D,IAAI,OAAOA,MAAM,CAACP,EAAE,KAAK,QAAQ,IAAI,CAACN,MAAM,CAACC,QAAQ,CAACY,MAAM,CAACP,EAAE,CAAC,EAAE;IACjE,MAAM,IAAIX,iBAAiB,CAC1BD,gBAAgB,CAACQ,cAAc,EAC/B,qEAAqE,EACrE;MAAEC,QAAQ,EAAE,OAAOU,MAAM,CAACP;IAAG,CAC9B,CAAC;EACF;EAEA,IACCO,MAAM,CAACC,SAAS,KAAKC,SAAS,IAC9BF,MAAM,CAACC,SAAS,KAAK,WAAW,IAChCD,MAAM,CAACC,SAAS,KAAK,UAAU,EAC9B;IACD,MAAM,IAAInB,iBAAiB,CAC1BD,gBAAgB,CAACQ,cAAc,EAC/B,qDAAqD,EACrD;MAAEC,QAAQ,EAAEC,MAAM,CAACS,MAAM,CAACC,SAAS;IAAE,CACtC,CAAC;EACF;AACD","ignoreList":[]}

package/lib/module/schedule/validate-content.js

@@ -0,0 +1,95 @@
+"use strict";
+
+/**
+ * Content validation.
+ *
+ * The package passes content through **unchanged** and never truncates it.
+ * Display truncation is the platform's decision and differs between them; a
+ * library that pre-truncated would be guessing at a rule it does not own, and
+ * would corrupt content that would have displayed fine.
+ *
+ * What it does refuse is content over the platform's hard payload limit, where
+ * the alternative is not a shortened notification but a failed or undefined
+ * delivery. That is a real error and is reported as one, before any platform
+ * call.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+/**
+ * Hard payload ceilings.
+ *
+ * These are *not* display limits. A title longer than a phone shows is fine and
+ * is passed through; the README documents where each platform visually
+ * truncates so a caller can decide for itself.
+ *
+ * The total is deliberately lower than the sum of the parts, so it actually
+ * binds — a per-field check that can never be exceeded in aggregate would be
+ * dead code. It sits under the 4 KB payload budget both platforms enforce,
+ * leaving headroom for the routing payload that shares it.
+ */
+export const CONTENT_LIMITS = {
+  maxTitleBytes: 512,
+  maxBodyBytes: 3072,
+  maxSubtitleBytes: 512,
+  maxTotalBytes: 3584
+};
+
+/** UTF-8 byte length — the unit the platforms actually bound. */
+export function byteLength(value) {
+  let bytes = 0;
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code <= 0x7f) bytes += 1;else if (code <= 0x7ff) bytes += 2;else if (code <= 0xffff) bytes += 3;else bytes += 4;
+  }
+  return bytes;
+}
+function requireString(value, field) {
+  if (typeof value !== 'string') {
+    throw new NotificationError(DIAGNOSTIC_CODES.CONTENT_TOO_LARGE, `Notification content field "${field}" must be a string of resolved display text. The package performs no locale resolution.`, {
+      field,
+      received: typeof value
+    });
+  }
+  return value;
+}
+
+/**
+ * Validates content and returns it **byte-identical**.
+ *
+ * The return value is the same object reference where possible, so nothing
+ * downstream can mistake this for a transformation step.
+ */
+export function validateContent(content) {
+  const title = requireString(content.title, 'title');
+  const body = requireString(content.body, 'body');
+  const subtitle = content.subtitle === undefined ? undefined : requireString(content.subtitle, 'subtitle');
+  if (title.length === 0 && body.length === 0) {
+    throw new NotificationError(DIAGNOSTIC_CODES.CONTENT_TOO_LARGE, 'A notification must carry a title or a body; both were empty.', {
+      field: 'title+body'
+    });
+  }
+  const checks = [['title', title, CONTENT_LIMITS.maxTitleBytes], ['body', body, CONTENT_LIMITS.maxBodyBytes]];
+  if (subtitle !== undefined) {
+    checks.push(['subtitle', subtitle, CONTENT_LIMITS.maxSubtitleBytes]);
+  }
+  for (const [field, value, limit] of checks) {
+    const size = byteLength(value);
+    if (size > limit) {
+      throw new NotificationError(DIAGNOSTIC_CODES.CONTENT_TOO_LARGE, `Notification "${field}" is ${size} bytes, over the ${limit}-byte platform limit. ` + "It was refused rather than truncated, because the package does not decide where a caller's content should be cut.", {
+        field,
+        bytes: size,
+        limit
+      });
+    }
+  }
+  const total = byteLength(title) + byteLength(body) + (subtitle ? byteLength(subtitle) : 0);
+  if (total > CONTENT_LIMITS.maxTotalBytes) {
+    throw new NotificationError(DIAGNOSTIC_CODES.CONTENT_TOO_LARGE, `Notification content totals ${total} bytes, over the ${CONTENT_LIMITS.maxTotalBytes}-byte payload limit.`, {
+      field: 'total',
+      bytes: total,
+      limit: CONTENT_LIMITS.maxTotalBytes
+    });
+  }
+  return content;
+}
+//# sourceMappingURL=validate-content.js.map

package/lib/module/schedule/validate-content.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DIAGNOSTIC_CODES","NotificationError","CONTENT_LIMITS","maxTitleBytes","maxBodyBytes","maxSubtitleBytes","maxTotalBytes","byteLength","value","bytes","char","code","codePointAt","requireString","field","CONTENT_TOO_LARGE","received","validateContent","content","title","body","subtitle","undefined","length","checks","push","limit","size","total"],"sourceRoot":"../../../src","sources":["schedule/validate-content.ts"],"mappings":"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","ignoreList":[]}