@chipmobilesdk/rn-notification 0.6.0 → 0.7.0

package/lib/commonjs/initialize.js

@@ -0,0 +1,187 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.initialize = initialize;
+exports.resolveLookahead = resolveLookahead;
+exports.validateConfig = validateConfig;
+var _rnCore = require("@chipmobilesdk/rn-core");
+var _recurrence = require("./contract/recurrence.js");
+var _errors = require("./contract/errors.js");
+var _events = require("./diagnostics/events.js");
+var _cycle = require("./maintenance/cycle.js");
+var _toggle = require("./maintenance/toggle.js");
+var _record = require("./state/record.js");
+var _seriesLedger = require("./state/series-ledger.js");
+var _migrate = require("./channel/migrate.js");
+var _anchor = require("./schedule/anchor.js");
+/**
+ * Package initialization.
+ *
+ * Composes the parts that must be in place before the first schedule call:
+ * validate configuration, load persisted state, apply tone declarations, run
+ * any pending channel migration, and start the maintenance registry.
+ *
+ * Budgeted at 100 ms of app startup, which is why state loading is synchronous
+ * and tone declaration is the only platform round-trip.
+ *
+ * Automatic maintenance is started here too: whatever steps are registered on
+ * `runtime.registry` run when the app returns to the foreground, with the
+ * trigger reported as `timeZoneChange` when the device zone moved meanwhile.
+ * Until 0.4.0 nothing ever called `runAutomatic`, so "automatic" maintenance
+ * only ran when the app invoked it by hand.
+ */
+
+/** The slice of React Native's `AppState` the lifecycle observer uses. */
+
+/** rn-core's shared lifecycle port in the observer's shape: one native subscription for every package (PERF-07). */
+const sharedLifecycle = {
+  addEventListener: (_type, listener) => ({
+    remove: (0, _rnCore.appLifecycle)().subscribe(state => listener(state))
+  })
+};
+
+/** Everything assembled at initialization, shared by the operation modules. */
+
+/**
+ * Clamps the lookahead into its documented bounds.
+ *
+ * Bounded on adjustment because the platform ceiling is not negotiable: a
+ * consumer asking for a five-year window would silently exhaust the 64-entry
+ * iOS ceiling on the first frequent series.
+ */
+function resolveLookahead(partial) {
+  const days = partial?.days ?? _recurrence.DEFAULT_LOOKAHEAD.days;
+  const occurrencesPerSeries = partial?.occurrencesPerSeries ?? _recurrence.DEFAULT_LOOKAHEAD.occurrencesPerSeries;
+  return {
+    days: Math.min(Math.max(days, _recurrence.LOOKAHEAD_BOUNDS.minDays), _recurrence.LOOKAHEAD_BOUNDS.maxDays),
+    occurrencesPerSeries: Math.min(Math.max(occurrencesPerSeries, _recurrence.LOOKAHEAD_BOUNDS.minOccurrences), _recurrence.LOOKAHEAD_BOUNDS.maxOccurrences)
+  };
+}
+
+/** Fails before any platform call, so a bad configuration never half-applies. */
+function validateConfig(config) {
+  if (config.tones.length === 0) {
+    throw new _errors.NotificationError(_errors.DIAGNOSTIC_CODES.UNDECLARED_TONE, 'At least one tone must be declared before notifications can be scheduled.');
+  }
+  const seen = new Set();
+  for (const tone of config.tones) {
+    if (seen.has(tone.id)) {
+      throw new _errors.NotificationError(_errors.DIAGNOSTIC_CODES.UNDECLARED_TONE, `Tone "${tone.id}" is declared more than once.`, {
+        toneId: tone.id
+      });
+    }
+    seen.add(tone.id);
+    if (!Number.isInteger(tone.version) || tone.version < 1) {
+      throw new _errors.NotificationError(_errors.DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED, `Tone "${tone.id}" must carry an integer version of 1 or greater, because a channel configuration change is a migration rather than an assignment.`, {
+        toneId: tone.id,
+        version: tone.version
+      });
+    }
+  }
+  const groupIds = new Set((config.channelGroups ?? []).map(group => group.id));
+  for (const tone of config.tones) {
+    if (tone.groupId !== undefined && !groupIds.has(tone.groupId)) {
+      throw new _errors.NotificationError(_errors.DIAGNOSTIC_CODES.UNDECLARED_TONE, `Tone "${tone.id}" references undeclared channel group "${tone.groupId}".`, {
+        toneId: tone.id,
+        groupId: tone.groupId
+      });
+    }
+  }
+}
+async function initialize(config, deps) {
+  const now = deps.now ?? (() => Date.now());
+  const startedAt = now();
+  validateConfig(config);
+  const emitter = new _events.DiagnosticEmitter({
+    sink: config.eventSink,
+    verbose: config.verboseDiagnostics,
+    now
+  });
+  const state = new _record.StateManager({
+    store: deps.store,
+    now,
+    emit: event => emitter.emit(event.code, describeStateEvent(event.code), event.context)
+  });
+  const channels = (0, _migrate.createChannels)({
+    engine: deps.engine,
+    state,
+    now,
+    // The channel module emits only DIAGNOSTIC_CODES values; its port types the
+    // code as a string so it stays usable without the emitter.
+    emit: (code, message, context) => emitter.emit(code, message, context)
+  });
+  // Declares groups and tones, and runs any version migration. An unchanged
+  // configuration costs no platform work, so doing this on every launch is free.
+  const applied = await channels.apply(config.tones, config.channelGroups ?? []);
+  const registry = new _cycle.MaintenanceRegistry({
+    clock: now
+  });
+  const maintenance = new _toggle.MaintenanceController({
+    registry,
+    now,
+    // Occurrence identifiers, not series identifiers. Maintenance cancels
+    // occurrences, so a set of series ids made every legitimate cancel look
+    // like a scope violation.
+    ownedIds: async () => (0, _seriesLedger.ownedIdentifiers)(state, (await deps.engine.getPending()).map(entry => entry.id)),
+    enabled: config.automaticMaintenance ?? true
+  });
+  const timeZone = deps.timeZone ?? (0, _anchor.createPlatformTimeZoneReader)();
+  let lastZone = timeZone();
+  let lastAutomatic;
+  const onAppState = next => {
+    if (next !== 'active') return;
+    const zone = timeZone();
+    const trigger = zone !== lastZone ? 'timeZoneChange' : 'foreground';
+    lastZone = zone;
+    maintenance.runAutomatic(trigger).then(result => {
+      if (result !== undefined) lastAutomatic = result;
+    }, error => {
+      // Nothing awaits an automatic cycle, so a failure is reported here or
+      // not at all.
+      emitter.emit(_errors.DIAGNOSTIC_CODES.MAINTENANCE_FAILED, `Automatic maintenance (${trigger}) failed: ${error instanceof Error ? error.name : 'unknown error'}.`, {
+        trigger
+      });
+    });
+  };
+  const subscription = (deps.appState ?? sharedLifecycle).addEventListener('change', onAppState);
+  const runtime = {
+    engine: deps.engine,
+    state,
+    emitter,
+    registry,
+    maintenance,
+    channels,
+    lookahead: resolveLookahead(config.lookahead),
+    config,
+    now,
+    lastAutomaticMaintenance: () => lastAutomatic,
+    dispose: () => subscription.remove()
+  };
+  return {
+    runtime,
+    result: {
+      tonesApplied: config.tones.length,
+      migrationsRun: applied.migrated.length,
+      stateRebuilt: state.health().rebuilt,
+      automaticMaintenance: maintenance.isEnabled,
+      durationMs: now() - startedAt
+    }
+  };
+}
+function describeStateEvent(code) {
+  switch (code) {
+    case _errors.DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT:
+      return 'Persisted state was unreadable and has been rebuilt. Deduplication history and buffered interactions from before the loss are gone; scheduled notifications are unaffected.';
+    case _errors.DIAGNOSTIC_CODES.STATE_WRITE_FAILED:
+      return 'Persisted state could not be written. The affected guarantee degrades to this session only.';
+    case _errors.DIAGNOSTIC_CODES.STATE_CAP_EVICTED:
+      return 'A persisted collection reached its cap and the oldest entries were evicted.';
+    case _errors.DIAGNOSTIC_CODES.INTERACTION_BUFFER_EVICTED:
+      return 'Buffered interactions were evicted at the cap or retention limit.';
+    default:
+      return 'Persisted state event.';
+  }
+}
+//# sourceMappingURL=initialize.js.map

package/lib/commonjs/initialize.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_rnCore","require","_recurrence","_errors","_events","_cycle","_toggle","_record","_seriesLedger","_migrate","_anchor","sharedLifecycle","addEventListener","_type","listener","remove","appLifecycle","subscribe","state","resolveLookahead","partial","days","DEFAULT_LOOKAHEAD","occurrencesPerSeries","Math","min","max","LOOKAHEAD_BOUNDS","minDays","maxDays","minOccurrences","maxOccurrences","validateConfig","config","tones","length","NotificationError","DIAGNOSTIC_CODES","UNDECLARED_TONE","seen","Set","tone","has","id","toneId","add","Number","isInteger","version","CHANNEL_MIGRATION_REQUIRED","groupIds","channelGroups","map","group","groupId","undefined","initialize","deps","now","Date","startedAt","emitter","DiagnosticEmitter","sink","eventSink","verbose","verboseDiagnostics","StateManager","store","emit","event","code","describeStateEvent","context","channels","createChannels","engine","message","applied","apply","registry","MaintenanceRegistry","clock","maintenance","MaintenanceController","ownedIds","ownedIdentifiers","getPending","entry","enabled","automaticMaintenance","timeZone","createPlatformTimeZoneReader","lastZone","lastAutomatic","onAppState","next","zone","trigger","runAutomatic","then","result","error","MAINTENANCE_FAILED","Error","name","subscription","appState","runtime","lookahead","lastAutomaticMaintenance","dispose","tonesApplied","migrationsRun","migrated","stateRebuilt","health","rebuilt","isEnabled","durationMs","STATE_CORRUPT_REBUILT","STATE_WRITE_FAILED","STATE_CAP_EVICTED","INTERACTION_BUFFER_EVICTED"],"sourceRoot":"../../src","sources":["initialize.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/interaction/index.js

@@ -0,0 +1,120 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createInteractions = createInteractions;
+var _errors = require("../contract/errors.js");
+var _interactionBuffer = require("../state/interaction-buffer.js");
+/**
+ * Interaction routing.
+ *
+ * One handler covers foreground, background, and cold start. The hard case is
+ * the last one: the tap happens before any JavaScript exists to receive it, so
+ * the event has to wait — durably — until a handler registers.
+ *
+ * Events are delivered in occurrence order and never dropped for want of a
+ * listener. After delivery the notification leaves the tray, because a
+ * notification the user has already acted on sitting there is noise.
+ */
+
+function createInteractions(deps) {
+  const emit = deps.emit ?? (() => {});
+  let handlers = [];
+  let engineSubscription;
+  /** Serializes delivery so rapid interactions arrive in order, never interleaved. */
+  let deliveryChain = Promise.resolve();
+  const deliver = event => {
+    deliveryChain = deliveryChain.then(async () => {
+      for (const handler of handlers) {
+        try {
+          await handler(event);
+        } catch {
+          // A consumer's handler failing must not stop the next event, or one
+          // bad tap would silently swallow every tap after it.
+        }
+      }
+
+      // Acted on, so it leaves the tray and stops making noise.
+      if (event.kind !== 'dismiss') {
+        await deps.engine.cancel(event.notificationId).catch(() => undefined);
+      }
+    });
+  };
+  const route = event => {
+    if (handlers.length === 0) {
+      (0, _interactionBuffer.buffer)(deps.state, event);
+      return;
+    }
+    deliver(event);
+  };
+  const ensureSubscribed = () => {
+    engineSubscription ??= deps.engine.subscribeToInteractions(route);
+  };
+
+  // Subscribing immediately rather than on first handler registration: an
+  // interaction arriving in the gap would otherwise be lost entirely, which is
+  // the exact failure the buffer exists to prevent.
+  ensureSubscribed();
+  return {
+    /**
+     * Registers a handler and immediately drains anything that was waiting.
+     *
+     * The drain is what makes a cold-start tap work: the event was persisted
+     * before this handler existed, possibly before this process existed.
+     */
+    onInteraction(handler) {
+      handlers.push(handler);
+      for (const event of (0, _interactionBuffer.drain)(deps.state)) {
+        deliver(event);
+      }
+      return () => {
+        handlers = handlers.filter(h => h !== handler);
+      };
+    },
+    /**
+     * Collects the interaction that launched the app, if any.
+     *
+     * Called once during startup. If no handler exists yet the event is
+     * buffered rather than discarded.
+     */
+    async collectInitial() {
+      const initial = await deps.engine.takeInitialInteraction();
+      if (initial === undefined) return;
+      route(initial);
+    },
+    /**
+     * Signals that a routing target no longer exists.
+     *
+     * The consumer chooses its own fallback screen. No platform error is ever
+     * shown to the user for this — a notification pointing at deleted data is
+     * an ordinary condition, not a crash.
+     */
+    reportTargetMissing(signal) {
+      emit(_errors.DIAGNOSTIC_CODES.TARGET_MISSING, 'The routing target no longer exists. The consumer chooses a fallback; no platform error is shown to the user.', {
+        notificationId: signal.notificationId
+      });
+    },
+    /** Reports that a background action exceeded the platform's execution window. */
+    reportBackgroundTimeout(notificationId, windowMs) {
+      emit(_errors.DIAGNOSTIC_CODES.BACKGROUND_WINDOW_EXCEEDED, `A background action exceeded the platform's ${windowMs} ms execution window and was cut short.`, {
+        notificationId,
+        windowMs
+      });
+    },
+    /** How many interactions are waiting for a handler. */
+    pendingCount() {
+      return (0, _interactionBuffer.bufferedCount)(deps.state);
+    },
+    /** Settles outstanding deliveries. Exists for tests and orderly shutdown. */
+    async flush() {
+      await deliveryChain;
+    },
+    dispose() {
+      engineSubscription?.();
+      engineSubscription = undefined;
+      handlers = [];
+    }
+  };
+}
+//# sourceMappingURL=index.js.map

package/lib/commonjs/interaction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","_interactionBuffer","createInteractions","deps","emit","handlers","engineSubscription","deliveryChain","Promise","resolve","deliver","event","then","handler","kind","engine","cancel","notificationId","catch","undefined","route","length","buffer","state","ensureSubscribed","subscribeToInteractions","onInteraction","push","drain","filter","h","collectInitial","initial","takeInitialInteraction","reportTargetMissing","signal","DIAGNOSTIC_CODES","TARGET_MISSING","reportBackgroundTimeout","windowMs","BACKGROUND_WINDOW_EXCEEDED","pendingCount","bufferedCount","flush","dispose"],"sourceRoot":"../../../src","sources":["interaction/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/maintenance/cycle.js

@@ -0,0 +1,108 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MaintenanceScopeViolation = exports.MaintenanceRegistry = void 0;
+/**
+ * The automatic maintenance cycle.
+ *
+ * Covers exactly what only the package can know — window refresh, recurrence
+ * expansion, wall-clock re-anchoring, pending-set verification, permission
+ * re-reads. Full desired-set reconciliation is never automatic, because only
+ * the consumer knows what its data implies and a package that guessed would
+ * cancel notifications it does not understand.
+ *
+ * Steps register themselves here rather than being wired in a fixed order. That
+ * is what lets scheduling, reconciliation, recurrence, and permissions each
+ * contribute a step without importing one another.
+ *
+ * The rule that makes automatic work safe: a step may act only on notifications
+ * the package owns, and may never cancel anything else. It is enforced here
+ * rather than trusted to each step.
+ */
+
+class MaintenanceScopeViolation extends Error {
+  constructor(step, offendingIds) {
+    super(`Maintenance step "${step}" attempted to cancel ${offendingIds.length} notification(s) it does not own. ` + 'Automatic maintenance may never cancel a directly-scheduled notification.');
+    this.name = 'MaintenanceScopeViolation';
+    this.step = step;
+    this.offendingIds = offendingIds;
+    Object.setPrototypeOf(this, MaintenanceScopeViolation.prototype);
+  }
+}
+exports.MaintenanceScopeViolation = MaintenanceScopeViolation;
+class MaintenanceRegistry {
+  steps = [];
+  inFlight = null;
+  constructor(options = {}) {
+    this.clock = options.clock ?? (() => Date.now());
+  }
+  register(step) {
+    this.steps.push(step);
+    this.steps.sort((a, b) => a.order - b.order);
+    return () => {
+      this.steps = this.steps.filter(s => s !== step);
+    };
+  }
+  get registered() {
+    return this.steps.map(s => s.name);
+  }
+
+  /**
+   * Runs every registered step in order.
+   *
+   * Overlapping cycles are joined rather than queued or dropped: a second
+   * caller arriving mid-cycle wants the work the running cycle is already
+   * doing, so it waits for that cycle and gets its result. It used to get an
+   * empty result at once. Since `initialize` started running a cycle on every
+   * foreground, an app that ran maintenance and then reconciled on the same
+   * event got that empty result and reconciled while the window refresh was
+   * still writing: a reminder the reconcile cancelled could be scheduled again.
+   */
+  run(context) {
+    if (this.inFlight) {
+      return this.inFlight;
+    }
+    const cycle = this.runSteps(context).finally(() => {
+      if (this.inFlight === cycle) this.inFlight = null;
+    });
+    this.inFlight = cycle;
+    return cycle;
+  }
+  async runSteps(context) {
+    const started = context.now;
+    const clockStart = this.clock();
+    const aggregate = {
+      windowRefreshed: false,
+      occurrencesScheduled: 0,
+      reAnchored: 0,
+      timeZoneChanged: false,
+      permissionChanged: false,
+      operationCount: 0
+    };
+    let discrepancy;
+    for (const step of this.steps) {
+      const outcome = await step.run(context);
+      const offending = (outcome.cancelledIds ?? []).filter(id => !context.ownedIds.has(id));
+      if (offending.length > 0) {
+        throw new MaintenanceScopeViolation(step.name, offending);
+      }
+      aggregate.windowRefreshed ||= outcome.windowRefreshed ?? false;
+      aggregate.occurrencesScheduled += outcome.occurrencesScheduled ?? 0;
+      aggregate.reAnchored += outcome.reAnchored ?? 0;
+      aggregate.timeZoneChanged ||= outcome.timeZoneChanged ?? false;
+      aggregate.permissionChanged ||= outcome.permissionChanged ?? false;
+      aggregate.operationCount += outcome.operationCount ?? 0;
+      discrepancy ??= outcome.discrepancy;
+    }
+    return {
+      ranAt: started,
+      ...aggregate,
+      discrepancy,
+      durationMs: this.clock() - clockStart
+    };
+  }
+}
+exports.MaintenanceRegistry = MaintenanceRegistry;
+//# sourceMappingURL=cycle.js.map

package/lib/commonjs/maintenance/cycle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["MaintenanceScopeViolation","Error","constructor","step","offendingIds","length","name","Object","setPrototypeOf","prototype","exports","MaintenanceRegistry","steps","inFlight","options","clock","Date","now","register","push","sort","a","b","order","filter","s","registered","map","run","context","cycle","runSteps","finally","started","clockStart","aggregate","windowRefreshed","occurrencesScheduled","reAnchored","timeZoneChanged","permissionChanged","operationCount","discrepancy","outcome","offending","cancelledIds","id","ownedIds","has","ranAt","durationMs"],"sourceRoot":"../../../src","sources":["maintenance/cycle.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/maintenance/permission-refresh.js

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PERMISSION_REFRESH_ORDER = void 0;
+exports.createPermissionRefreshStep = createPermissionRefreshStep;
+/**
+ * The permission re-read maintenance step.
+ *
+ * The user can change permission in system settings while the app is
+ * backgrounded, and the platform does not tell anyone. Re-reading on foreground
+ * is the only way a consumer's interface avoids showing a stale answer.
+ *
+ * Runs last (order 30): permission state does not affect what the earlier steps
+ * expand or re-anchor, and reading it after they have run means the report
+ * reflects the device as the cycle leaves it.
+ */
+
+const PERMISSION_REFRESH_ORDER = exports.PERMISSION_REFRESH_ORDER = 30;
+function createPermissionRefreshStep(deps) {
+  return {
+    name: 'permission-refresh',
+    order: PERMISSION_REFRESH_ORDER,
+    async run(_context) {
+      const {
+        changed
+      } = await deps.permissions.refresh();
+      return {
+        // Reading permission is not a platform mutation, so it never counts
+        // toward the zero-operation guarantee.
+        operationCount: 0,
+        permissionChanged: changed,
+        cancelledIds: []
+      };
+    }
+  };
+}
+//# sourceMappingURL=permission-refresh.js.map

package/lib/commonjs/maintenance/permission-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["PERMISSION_REFRESH_ORDER","exports","createPermissionRefreshStep","deps","name","order","run","_context","changed","permissions","refresh","operationCount","permissionChanged","cancelledIds"],"sourceRoot":"../../../src","sources":["maintenance/permission-refresh.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKO,MAAMA,wBAAwB,GAAAC,OAAA,CAAAD,wBAAA,GAAG,EAAE;AAMnC,SAASE,2BAA2BA,CAACC,IAAmC,EAAmB;EACjG,OAAO;IACNC,IAAI,EAAE,oBAAoB;IAC1BC,KAAK,EAAEL,wBAAwB;IAE/B,MAAMM,GAAGA,CAACC,QAA4B,EAAwB;MAC7D,MAAM;QAAEC;MAAQ,CAAC,GAAG,MAAML,IAAI,CAACM,WAAW,CAACC,OAAO,CAAC,CAAC;MAEpD,OAAO;QACN;QACA;QACAC,cAAc,EAAE,CAAC;QACjBC,iBAAiB,EAAEJ,OAAO;QAC1BK,YAAY,EAAE;MACf,CAAC;IACF;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/maintenance/reanchor.js

@@ -0,0 +1,99 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.RE_ANCHOR_ORDER = void 0;
+exports.createReAnchorStep = createReAnchorStep;
+var _anchor = require("../schedule/anchor.js");
+var _writer = require("../schedule/writer.js");
+/**
+ * The re-anchoring maintenance step.
+ *
+ * Registers itself with the maintenance registry rather than being wired into
+ * a fixed sequence, which is what keeps scheduling independent of
+ * reconciliation, recurrence, and permissions despite all four contributing a
+ * step.
+ *
+ * Runs early (order 10) because verification compares firing instants: if
+ * verification ran first it would compare against instants re-anchoring is
+ * about to rewrite, and report discrepancies that do not exist.
+ */
+
+const RE_ANCHOR_ORDER = exports.RE_ANCHOR_ORDER = 10;
+function createReAnchorStep(deps) {
+  // Through the shared writer so a repeating alert's stop marker moves with it;
+  // written directly, the marker kept the old instant and cut the alert short
+  // or let it run past its bound.
+  const writer = (0, _writer.createScheduleWriter)(deps.engine);
+  return {
+    name: 'reanchor',
+    order: RE_ANCHOR_ORDER,
+    async run(_context) {
+      const zone = deps.timeZone();
+      const pending = await deps.engine.getPending();
+      const plan = (0, _anchor.planReAnchor)(pending, zone);
+
+      // The no-change path costs one comparison per entry and issues zero
+      // platform operations. That is what makes re-anchoring idempotent.
+      if (plan.rewrites.length === 0) {
+        return {
+          operationCount: 0,
+          reAnchored: 0,
+          timeZoneChanged: false
+        };
+      }
+      deps.emit?.('REANCHOR', `Device time zone changed from ${plan.fromZone ?? 'unknown'} to ${plan.toZone}; re-anchoring ${plan.rewrites.length} wall-clock notification(s).`, {
+        from: plan.fromZone,
+        to: plan.toZone,
+        count: plan.rewrites.length
+      });
+      let operationCount = 0;
+      for (const {
+        entry,
+        resolvedAt
+      } of plan.rewrites) {
+        const tone = deps.resolveTone(entry.tone);
+        if (tone === undefined) {
+          // A tone that no longer exists means this entry belongs to a
+          // configuration the app has since dropped. Leaving it alone is
+          // correct: re-anchoring must never repair, only preserve.
+          continue;
+        }
+        await writer.write({
+          request: {
+            id: entry.id,
+            content: entry.content,
+            tone: entry.tone,
+            moment: {
+              at: resolvedAt,
+              anchoring: 'wallClock'
+            },
+            routing: entry.routing,
+            actions: entry.actions,
+            ownerTag: entry.ownerTag,
+            groupTag: entry.groupTag
+          },
+          resolvedAt,
+          tone,
+          // Re-anchored against the zone the device is in now — this is the
+          // value that stops the entry being reported as stale next time.
+          anchoringGeneration: zone,
+          approximate: !deps.canScheduleExactly(),
+          seriesId: entry.seriesId,
+          pushCreated: entry.pushCreated
+        });
+        operationCount += 1;
+      }
+      return {
+        operationCount,
+        reAnchored: operationCount,
+        timeZoneChanged: true,
+        // Re-anchoring replaces in place and cancels nothing, so it can never
+        // touch a notification outside what it was handed.
+        cancelledIds: []
+      };
+    }
+  };
+}
+//# sourceMappingURL=reanchor.js.map

package/lib/commonjs/maintenance/reanchor.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_anchor","require","_writer","RE_ANCHOR_ORDER","exports","createReAnchorStep","deps","writer","createScheduleWriter","engine","name","order","run","_context","zone","timeZone","pending","getPending","plan","planReAnchor","rewrites","length","operationCount","reAnchored","timeZoneChanged","emit","fromZone","toZone","from","to","count","entry","resolvedAt","tone","resolveTone","undefined","write","request","id","content","moment","at","anchoring","routing","actions","ownerTag","groupTag","anchoringGeneration","approximate","canScheduleExactly","seriesId","pushCreated","cancelledIds"],"sourceRoot":"../../../src","sources":["maintenance/reanchor.ts"],"mappings":";;;;;;;AAgBA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AAjBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBO,MAAME,eAAe,GAAAC,OAAA,CAAAD,eAAA,GAAG,EAAE;AAE1B,SAASE,kBAAkBA,CAACC,IAA8B,EAAmB;EACnF;EACA;EACA;EACA,MAAMC,MAAM,GAAG,IAAAC,4BAAoB,EAACF,IAAI,CAACG,MAAM,CAAC;EAEhD,OAAO;IACNC,IAAI,EAAE,UAAU;IAChBC,KAAK,EAAER,eAAe;IAEtB,MAAMS,GAAGA,CAACC,QAA4B,EAAwB;MAC7D,MAAMC,IAAI,GAAGR,IAAI,CAACS,QAAQ,CAAC,CAAC;MAC5B,MAAMC,OAAO,GAAG,MAAMV,IAAI,CAACG,MAAM,CAACQ,UAAU,CAAC,CAAC;MAC9C,MAAMC,IAAI,GAAG,IAAAC,oBAAY,EAACH,OAAO,EAAEF,IAAI,CAAC;;MAExC;MACA;MACA,IAAII,IAAI,CAACE,QAAQ,CAACC,MAAM,KAAK,CAAC,EAAE;QAC/B,OAAO;UAAEC,cAAc,EAAE,CAAC;UAAEC,UAAU,EAAE,CAAC;UAAEC,eAAe,EAAE;QAAM,CAAC;MACpE;MAEAlB,IAAI,CAACmB,IAAI,GACR,UAAU,EACV,iCAAiCP,IAAI,CAACQ,QAAQ,IAAI,SAAS,OAAOR,IAAI,CAACS,MAAM,kBAAkBT,IAAI,CAACE,QAAQ,CAACC,MAAM,8BAA8B,EACjJ;QAAEO,IAAI,EAAEV,IAAI,CAACQ,QAAQ;QAAEG,EAAE,EAAEX,IAAI,CAACS,MAAM;QAAEG,KAAK,EAAEZ,IAAI,CAACE,QAAQ,CAACC;MAAO,CACrE,CAAC;MAED,IAAIC,cAAc,GAAG,CAAC;MAEtB,KAAK,MAAM;QAAES,KAAK;QAAEC;MAAW,CAAC,IAAId,IAAI,CAACE,QAAQ,EAAE;QAClD,MAAMa,IAAI,GAAG3B,IAAI,CAAC4B,WAAW,CAACH,KAAK,CAACE,IAAI,CAAC;QACzC,IAAIA,IAAI,KAAKE,SAAS,EAAE;UACvB;UACA;UACA;UACA;QACD;QAEA,MAAM5B,MAAM,CAAC6B,KAAK,CAAC;UAClBC,OAAO,EAAE;YACRC,EAAE,EAAEP,KAAK,CAACO,EAAE;YACZC,OAAO,EAAER,KAAK,CAACQ,OAAO;YACtBN,IAAI,EAAEF,KAAK,CAACE,IAAI;YAChBO,MAAM,EAAE;cAAEC,EAAE,EAAET,UAAU;cAAEU,SAAS,EAAE;YAAY,CAAC;YAClDC,OAAO,EAAEZ,KAAK,CAACY,OAAO;YACtBC,OAAO,EAAEb,KAAK,CAACa,OAAO;YACtBC,QAAQ,EAAEd,KAAK,CAACc,QAAQ;YACxBC,QAAQ,EAAEf,KAAK,CAACe;UACjB,CAAC;UACDd,UAAU;UACVC,IAAI;UACJ;UACA;UACAc,mBAAmB,EAAEjC,IAAI;UACzBkC,WAAW,EAAE,CAAC1C,IAAI,CAAC2C,kBAAkB,CAAC,CAAC;UACvCC,QAAQ,EAAEnB,KAAK,CAACmB,QAAQ;UACxBC,WAAW,EAAEpB,KAAK,CAACoB;QACpB,CAAC,CAAC;QACF7B,cAAc,IAAI,CAAC;MACpB;MAEA,OAAO;QACNA,cAAc;QACdC,UAAU,EAAED,cAAc;QAC1BE,eAAe,EAAE,IAAI;QACrB;QACA;QACA4B,YAAY,EAAE;MACf,CAAC;IACF;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/maintenance/toggle.js

@@ -0,0 +1,50 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MaintenanceController = void 0;
+/**
+ * The automatic-maintenance switch.
+ *
+ * A package that acts on its own must offer a way to stop it — and a consumer
+ * that takes control must not lose a feature as the price. Disabling automatic
+ * maintenance leaves every operation explicitly invocable through
+ * `runMaintenance()`, producing identical device state.
+ */
+
+class MaintenanceController {
+  constructor(options) {
+    this.registry = options.registry;
+    this.now = options.now;
+    this.ownedIds = options.ownedIds;
+    this.enabled = options.enabled ?? true;
+  }
+  get isEnabled() {
+    return this.enabled;
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+
+  /** Called by lifecycle observers. A no-op when automatic maintenance is off. */
+  async runAutomatic(trigger) {
+    if (!this.enabled) return undefined;
+    return this.execute(trigger);
+  }
+
+  /** Always runs, regardless of the switch. This is what preserves capability parity. */
+  async runExplicit() {
+    return this.execute('explicit');
+  }
+  async execute(trigger) {
+    const context = {
+      trigger,
+      now: this.now(),
+      ownedIds: await this.ownedIds()
+    };
+    return this.registry.run(context);
+  }
+}
+exports.MaintenanceController = MaintenanceController;
+//# sourceMappingURL=toggle.js.map

package/lib/commonjs/maintenance/toggle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["MaintenanceController","constructor","options","registry","now","ownedIds","enabled","isEnabled","setEnabled","runAutomatic","trigger","undefined","execute","runExplicit","context","run","exports"],"sourceRoot":"../../../src","sources":["maintenance/toggle.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBO,MAAMA,qBAAqB,CAAC;EAMlCC,WAAWA,CAACC,OAAqC,EAAE;IAClD,IAAI,CAACC,QAAQ,GAAGD,OAAO,CAACC,QAAQ;IAChC,IAAI,CAACC,GAAG,GAAGF,OAAO,CAACE,GAAG;IACtB,IAAI,CAACC,QAAQ,GAAGH,OAAO,CAACG,QAAQ;IAChC,IAAI,CAACC,OAAO,GAAGJ,OAAO,CAACI,OAAO,IAAI,IAAI;EACvC;EAEA,IAAIC,SAASA,CAAA,EAAY;IACxB,OAAO,IAAI,CAACD,OAAO;EACpB;EAEAE,UAAUA,CAACF,OAAgB,EAAQ;IAClC,IAAI,CAACA,OAAO,GAAGA,OAAO;EACvB;;EAEA;EACA,MAAMG,YAAYA,CACjBC,OAAgD,EACP;IACzC,IAAI,CAAC,IAAI,CAACJ,OAAO,EAAE,OAAOK,SAAS;IACnC,OAAO,IAAI,CAACC,OAAO,CAACF,OAAO,CAAC;EAC7B;;EAEA;EACA,MAAMG,WAAWA,CAAA,EAA+B;IAC/C,OAAO,IAAI,CAACD,OAAO,CAAC,UAAU,CAAC;EAChC;EAEA,MAAcA,OAAOA,CAACF,OAA2B,EAA8B;IAC9E,MAAMI,OAA2B,GAAG;MACnCJ,OAAO;MACPN,GAAG,EAAE,IAAI,CAACA,GAAG,CAAC,CAAC;MACfC,QAAQ,EAAE,MAAM,IAAI,CAACA,QAAQ,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAACF,QAAQ,CAACY,GAAG,CAACD,OAAO,CAAC;EAClC;AACD;AAACE,OAAA,CAAAhB,qBAAA,GAAAA,qBAAA","ignoreList":[]}