@chipmobilesdk/rn-notification 0.6.0 → 0.7.0

package/lib/module/interaction/index.js

@@ -0,0 +1,116 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { DIAGNOSTIC_CODES } from "../contract/errors.js";
+import { buffer, bufferedCount, drain } from "../state/interaction-buffer.js";
+export 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) {
+      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 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(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(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 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/module/interaction/index.js.map

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

package/lib/module/maintenance/cycle.js

@@ -0,0 +1,102 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+export 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);
+  }
+}
+export 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
+    };
+  }
+}
+//# sourceMappingURL=cycle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["MaintenanceScopeViolation","Error","constructor","step","offendingIds","length","name","Object","setPrototypeOf","prototype","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/module/maintenance/permission-refresh.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+export const PERMISSION_REFRESH_ORDER = 30;
+export 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/module/maintenance/permission-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["PERMISSION_REFRESH_ORDER","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;;AAKA,OAAO,MAAMA,wBAAwB,GAAG,EAAE;AAM1C,OAAO,SAASC,2BAA2BA,CAACC,IAAmC,EAAmB;EACjG,OAAO;IACNC,IAAI,EAAE,oBAAoB;IAC1BC,KAAK,EAAEJ,wBAAwB;IAE/B,MAAMK,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/module/maintenance/reanchor.js

@@ -0,0 +1,94 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { planReAnchor } from "../schedule/anchor.js";
+import { createScheduleWriter } from "../schedule/writer.js";
+export const RE_ANCHOR_ORDER = 10;
+export 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 = 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 = 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/module/maintenance/reanchor.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["planReAnchor","createScheduleWriter","RE_ANCHOR_ORDER","createReAnchorStep","deps","writer","engine","name","order","run","_context","zone","timeZone","pending","getPending","plan","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":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA,SAASA,YAAY,QAA6B,uBAAoB;AACtE,SAASC,oBAAoB,QAAQ,uBAAoB;AAUzD,OAAO,MAAMC,eAAe,GAAG,EAAE;AAEjC,OAAO,SAASC,kBAAkBA,CAACC,IAA8B,EAAmB;EACnF;EACA;EACA;EACA,MAAMC,MAAM,GAAGJ,oBAAoB,CAACG,IAAI,CAACE,MAAM,CAAC;EAEhD,OAAO;IACNC,IAAI,EAAE,UAAU;IAChBC,KAAK,EAAEN,eAAe;IAEtB,MAAMO,GAAGA,CAACC,QAA4B,EAAwB;MAC7D,MAAMC,IAAI,GAAGP,IAAI,CAACQ,QAAQ,CAAC,CAAC;MAC5B,MAAMC,OAAO,GAAG,MAAMT,IAAI,CAACE,MAAM,CAACQ,UAAU,CAAC,CAAC;MAC9C,MAAMC,IAAI,GAAGf,YAAY,CAACa,OAAO,EAAEF,IAAI,CAAC;;MAExC;MACA;MACA,IAAII,IAAI,CAACC,QAAQ,CAACC,MAAM,KAAK,CAAC,EAAE;QAC/B,OAAO;UAAEC,cAAc,EAAE,CAAC;UAAEC,UAAU,EAAE,CAAC;UAAEC,eAAe,EAAE;QAAM,CAAC;MACpE;MAEAhB,IAAI,CAACiB,IAAI,GACR,UAAU,EACV,iCAAiCN,IAAI,CAACO,QAAQ,IAAI,SAAS,OAAOP,IAAI,CAACQ,MAAM,kBAAkBR,IAAI,CAACC,QAAQ,CAACC,MAAM,8BAA8B,EACjJ;QAAEO,IAAI,EAAET,IAAI,CAACO,QAAQ;QAAEG,EAAE,EAAEV,IAAI,CAACQ,MAAM;QAAEG,KAAK,EAAEX,IAAI,CAACC,QAAQ,CAACC;MAAO,CACrE,CAAC;MAED,IAAIC,cAAc,GAAG,CAAC;MAEtB,KAAK,MAAM;QAAES,KAAK;QAAEC;MAAW,CAAC,IAAIb,IAAI,CAACC,QAAQ,EAAE;QAClD,MAAMa,IAAI,GAAGzB,IAAI,CAAC0B,WAAW,CAACH,KAAK,CAACE,IAAI,CAAC;QACzC,IAAIA,IAAI,KAAKE,SAAS,EAAE;UACvB;UACA;UACA;UACA;QACD;QAEA,MAAM1B,MAAM,CAAC2B,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,EAAEhC,IAAI;UACzBiC,WAAW,EAAE,CAACxC,IAAI,CAACyC,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/module/maintenance/toggle.js

@@ -0,0 +1,45 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+export 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);
+  }
+}
+//# sourceMappingURL=toggle.js.map

package/lib/module/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"],"sourceRoot":"../../../src","sources":["maintenance/toggle.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA,OAAO,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","ignoreList":[]}

package/lib/module/maintenance/verify.js

@@ -0,0 +1,65 @@
+"use strict";
+
+/**
+ * Pending-set verification.
+ *
+ * Engine boot restoration coverage varies by manufacturer, so after a restart
+ * the device may hold fewer notifications than the package expects. This step
+ * notices that.
+ *
+ * It **detects and reports only**. It never re-registers, cancels, or repairs
+ * anything — the package deliberately does not persist a desired set, so it
+ * cannot tell a restoration gap from an intentional consumer change. Guessing
+ * would mean either resurrecting notifications the user cancelled or deleting
+ * ones they still want. Repair is consumer-invoked reconciliation.
+ *
+ * Runs at order 20, after re-anchoring (order 10): re-anchoring rewrites firing
+ * instants, and verifying first would compare against instants that are about
+ * to change.
+ */
+
+import { DIAGNOSTIC_CODES } from "../contract/errors.js";
+export const VERIFY_ORDER = 20;
+export function createVerifyStep(deps) {
+  return {
+    name: 'verify',
+    order: VERIFY_ORDER,
+    async run(context) {
+      const expected = deps.expectedIds();
+
+      // No recorded expectation is not the same as expecting an empty device.
+      // Reporting every pending entry as "unrecognized" on a fresh install
+      // would be noise, not a finding.
+      if (expected === undefined) {
+        return {
+          operationCount: 0
+        };
+      }
+      const pending = await deps.engine.getPending();
+      const actual = new Set(pending.map(entry => entry.id));
+      const missing = [...expected].filter(id => !actual.has(id)).sort();
+      const unrecognized = [...actual].filter(id => !expected.has(id)).sort();
+      if (missing.length === 0 && unrecognized.length === 0) {
+        return {
+          operationCount: 0
+        };
+      }
+      const discrepancy = {
+        missing,
+        unrecognized,
+        detectedAt: context.now
+      };
+      deps.emit?.(DIAGNOSTIC_CODES.PENDING_SET_DISCREPANCY, `Pending set differs from expectation: ${missing.length} expected but absent, ${unrecognized.length} present but unrecognized. ` + 'Reported only — run reconciliation to repair, since the package cannot distinguish a restoration gap from an intentional change.', {
+        missing: missing.length,
+        unrecognized: unrecognized.length
+      });
+      return {
+        operationCount: 0,
+        discrepancy,
+        // Verification repairs nothing, so it cancels nothing.
+        cancelledIds: []
+      };
+    }
+  };
+}
+//# sourceMappingURL=verify.js.map

package/lib/module/maintenance/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DIAGNOSTIC_CODES","VERIFY_ORDER","createVerifyStep","deps","name","order","run","context","expected","expectedIds","undefined","operationCount","pending","engine","getPending","actual","Set","map","entry","id","missing","filter","has","sort","unrecognized","length","discrepancy","detectedAt","now","emit","PENDING_SET_DISCREPANCY","cancelledIds"],"sourceRoot":"../../../src","sources":["maintenance/verify.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA,SAASA,gBAAgB,QAAQ,uBAAoB;AAErD,OAAO,MAAMC,YAAY,GAAG,EAAE;AAa9B,OAAO,SAASC,gBAAgBA,CAACC,IAA4B,EAAmB;EAC/E,OAAO;IACNC,IAAI,EAAE,QAAQ;IACdC,KAAK,EAAEJ,YAAY;IAEnB,MAAMK,GAAGA,CAACC,OAA2B,EAAwB;MAC5D,MAAMC,QAAQ,GAAGL,IAAI,CAACM,WAAW,CAAC,CAAC;;MAEnC;MACA;MACA;MACA,IAAID,QAAQ,KAAKE,SAAS,EAAE;QAC3B,OAAO;UAAEC,cAAc,EAAE;QAAE,CAAC;MAC7B;MAEA,MAAMC,OAAO,GAAG,MAAMT,IAAI,CAACU,MAAM,CAACC,UAAU,CAAC,CAAC;MAC9C,MAAMC,MAAM,GAAG,IAAIC,GAAG,CAACJ,OAAO,CAACK,GAAG,CAACC,KAAK,IAAIA,KAAK,CAACC,EAAE,CAAC,CAAC;MAEtD,MAAMC,OAAO,GAAG,CAAC,GAAGZ,QAAQ,CAAC,CAACa,MAAM,CAACF,EAAE,IAAI,CAACJ,MAAM,CAACO,GAAG,CAACH,EAAE,CAAC,CAAC,CAACI,IAAI,CAAC,CAAC;MAClE,MAAMC,YAAY,GAAG,CAAC,GAAGT,MAAM,CAAC,CAACM,MAAM,CAACF,EAAE,IAAI,CAACX,QAAQ,CAACc,GAAG,CAACH,EAAE,CAAC,CAAC,CAACI,IAAI,CAAC,CAAC;MAEvE,IAAIH,OAAO,CAACK,MAAM,KAAK,CAAC,IAAID,YAAY,CAACC,MAAM,KAAK,CAAC,EAAE;QACtD,OAAO;UAAEd,cAAc,EAAE;QAAE,CAAC;MAC7B;MAEA,MAAMe,WAA+B,GAAG;QACvCN,OAAO;QACPI,YAAY;QACZG,UAAU,EAAEpB,OAAO,CAACqB;MACrB,CAAC;MAEDzB,IAAI,CAAC0B,IAAI,GACR7B,gBAAgB,CAAC8B,uBAAuB,EACxC,yCAAyCV,OAAO,CAACK,MAAM,yBAAyBD,YAAY,CAACC,MAAM,6BAA6B,GAC/H,kIAAkI,EACnI;QAAEL,OAAO,EAAEA,OAAO,CAACK,MAAM;QAAED,YAAY,EAAEA,YAAY,CAACC;MAAO,CAC9D,CAAC;MAED,OAAO;QACNd,cAAc,EAAE,CAAC;QACjBe,WAAW;QACX;QACAK,YAAY,EAAE;MACf,CAAC;IACF;EACD,CAAC;AACF","ignoreList":[]}

package/lib/module/maintenance/window-refresh.js

@@ -0,0 +1,48 @@
+"use strict";
+
+/**
+ * The window-refresh maintenance step.
+ *
+ * Runs at order 15 — after re-anchoring (10) so it expands against corrected
+ * instants, before verification (20) so verification sees the refreshed set
+ * rather than reporting occurrences the refresh was about to add.
+ *
+ * This step is the reason automatic maintenance exists at all: only the package
+ * knows when a series' horizon has moved, and it can act on that without ever
+ * needing a desired set from the consumer.
+ */
+
+export const WINDOW_REFRESH_ORDER = 15;
+export function createWindowRefreshStep(deps) {
+  return {
+    name: 'window-refresh',
+    order: WINDOW_REFRESH_ORDER,
+    async run(_context) {
+      const rules = deps.registeredRules();
+      if (rules.length === 0) {
+        return {
+          operationCount: 0,
+          windowRefreshed: false
+        };
+      }
+      let scheduled = 0;
+      const cancelled = [];
+      for (const rule of rules) {
+        const result = await deps.recurrence.refreshSeries(rule);
+        scheduled += result.scheduled;
+        cancelled.push(...(result.cancelled ?? []));
+      }
+      return {
+        operationCount: scheduled + cancelled.length,
+        occurrencesScheduled: scheduled,
+        // A refresh that found nothing to add still ran; reporting it as
+        // refreshed distinguishes "nothing due" from "step never executed".
+        windowRefreshed: true,
+        // Only stale occurrences of series the package owns; reported so the
+        // registry's scope guard checks them rather than taking it on trust.
+        cancelledIds: cancelled
+      };
+    }
+  };
+}
+//# sourceMappingURL=window-refresh.js.map

package/lib/module/maintenance/window-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["WINDOW_REFRESH_ORDER","createWindowRefreshStep","deps","name","order","run","_context","rules","registeredRules","length","operationCount","windowRefreshed","scheduled","cancelled","rule","result","recurrence","refreshSeries","push","occurrencesScheduled","cancelledIds"],"sourceRoot":"../../../src","sources":["maintenance/window-refresh.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA,OAAO,MAAMA,oBAAoB,GAAG,EAAE;AAetC,OAAO,SAASC,uBAAuBA,CAACC,IAA+B,EAAmB;EACzF,OAAO;IACNC,IAAI,EAAE,gBAAgB;IACtBC,KAAK,EAAEJ,oBAAoB;IAE3B,MAAMK,GAAGA,CAACC,QAA4B,EAAwB;MAC7D,MAAMC,KAAK,GAAGL,IAAI,CAACM,eAAe,CAAC,CAAC;MACpC,IAAID,KAAK,CAACE,MAAM,KAAK,CAAC,EAAE;QACvB,OAAO;UAAEC,cAAc,EAAE,CAAC;UAAEC,eAAe,EAAE;QAAM,CAAC;MACrD;MAEA,IAAIC,SAAS,GAAG,CAAC;MACjB,MAAMC,SAAmB,GAAG,EAAE;MAE9B,KAAK,MAAMC,IAAI,IAAIP,KAAK,EAAE;QACzB,MAAMQ,MAAM,GAAG,MAAMb,IAAI,CAACc,UAAU,CAACC,aAAa,CAACH,IAAI,CAAC;QACxDF,SAAS,IAAIG,MAAM,CAACH,SAAS;QAC7BC,SAAS,CAACK,IAAI,CAAC,IAAIH,MAAM,CAACF,SAAS,IAAI,EAAE,CAAC,CAAC;MAC5C;MAEA,OAAO;QACNH,cAAc,EAAEE,SAAS,GAAGC,SAAS,CAACJ,MAAM;QAC5CU,oBAAoB,EAAEP,SAAS;QAC/B;QACA;QACAD,eAAe,EAAE,IAAI;QACrB;QACA;QACAS,YAAY,EAAEP;MACf,CAAC;IACF;EACD,CAAC;AACF","ignoreList":[]}