@camstack/system 1.2.315 → 1.2.317

package/dist/builtins/device-manager/mirror-row-writer.d.ts

@@ -4,6 +4,16 @@ import { MigrationRefusedError } from './migration-refused.js';
 import { RuntimeStatePolicyLookup } from './runtime-state-persist-gate.js';
 /** A device's row as it may reach disk: cap name → persistable slice (plus `$owned`). */
 export type PersistableRow = Record<string, Record<string, unknown>>;
+/** Which path wrote (or tried to write) a row — named on every line it logs. */
+export type RowWritePath = 'debounced' | 'shutdown-flush' | 'drain' | 'claim' | 'release';
+/**
+ * A write-through refused because the device's row could not be read first
+ * (D677). Nothing was written; the caller rolls its memory change back.
+ */
+export declare class RuntimeStateRowUnreadError extends Error {
+    readonly deviceId: number;
+    constructor(deviceId: number);
+}
 /**
  * The drain before a migration could not vouch for a device's row. Nothing has
  * moved yet, so it is a {@link MigrationRefusedError}: the migration refuses
@@ -25,10 +35,21 @@ export interface MirrorRowWriterDeps {
     readonly policyFor: RuntimeStatePolicyLookup;
     /** The device's row as memory holds it NOW — taken when a write RUNS. */
     readonly persistableFor: (deviceId: number) => PersistableRow;
+    /** The device's row was read into memory in this process (D677). */
+    readonly isRowRead: (deviceId: number) => boolean;
+    /**
+     * Read the row into memory — single-flight, `fill` (memory wins per cap).
+     * Rejects when the row cannot be read; memory is then unchanged.
+     */
+    readonly readRowFirst: (deviceId: number, settings: DeviceManagerSettings) => Promise<void>;
 }
 export declare class MirrorRowWriter {
     private readonly deps;
     static readonly RUNTIME_STATE_DEBOUNCE_MS = 1000;
+    /** Ceiling of the re-arm backoff while a device's row cannot be read (D677, D3). */
+    static readonly UNREAD_REARM_MAX_MS = 60000;
+    /** The re-arm delay after `refusals` consecutive unread refusals: 1 s, 2 s, 4 s … capped at 60 s. */
+    static unreadRearmDelayMs(refusals: number): number;
     /**
      * Per-device disk-write debouncer for runtime-state. `setCapSlice`
      * updates the in-memory mirror synchronously and emits the change
@@ -57,6 +78,8 @@ export declare class MirrorRowWriter {
      * that drops work silently reads as "never happened".
      */
     private readonly skippedSinceWrite;
+    /** Devices whose unreadable-row refusal is already logged — once per episode. */
+    private readonly rowUnreadLogged;
     constructor(deps: MirrorRowWriterDeps);
     /** What is believed to be on the device's row; undefined before any read or write. */
     persisted(deviceId: number): PersistableRow | undefined;
@@ -92,8 +115,43 @@ export declare class MirrorRowWriter {
     schedule(deviceId: number, settings: DeviceManagerSettings, changedCap: string): void;
     /** Arm the debounce timer; at fire, queue a write of the live blob unless disk already has it. */
     private armDiskWrite;
-    /** The debounced write itself: the blob as memory holds it NOW, behind the effective-change gate. Never rejects. */
+    /**
+     * Forget a removed device: cancel its armed write, await one in flight, and
+     * drop its baseline and counters — nothing writes its row after this.
+     */
+    forget(deviceId: number): Promise<void>;
+    /**
+     * The row is in memory, or is read now (D677). False when the read failed:
+     * the caller writes nothing. Logged once per episode, tagged; the episode
+     * ends at the next successful read.
+     */
+    private rowReadOrRefuse;
+    /**
+     * The ONE call of `writeDeviceRuntimeState`. A blob that lacks a cap the
+     * stored row holds is written (memory is the authority once the row was
+     * read) but never silently: the dropped caps are named at warn (D677).
+     * `$owned` is excluded — a release that empties it is the claim path's own
+     * logged business.
+     */
+    private writeRow;
+    /**
+     * A claim's write-through (D663): queued behind the device's writes, the row
+     * read first, the blob taken when it runs. Rejects with
+     * {@link RuntimeStateRowUnreadError} when the row cannot be read, or with the
+     * write's own error; resolves to what landed.
+     */
+    writeThroughRow(deviceId: number, settings: DeviceManagerSettings, path: RowWritePath): Promise<PersistableRow>;
+    /**
+     * The debounced write itself: the row read first (D677), then the blob as
+     * memory holds it NOW, behind the effective-change gate. Never rejects. An
+     * unreadable row writes nothing; the debounced path re-arms with a backoff
+     * (1 s doubling to 60 s — never a 1 Hz loop, D3), and the armed timer is
+     * what a migration drain sees as owed, so a row that has become readable
+     * drains normally. The shutdown flush does not re-arm.
+     */
     private writeLiveBlob;
+    /** Re-arm an unread refusal with its backoff, or remember it for `release` while held. */
+    private rearmAfterUnread;
     /**
      * Hold the debounced writer off these devices' rows while a migration swaps
      * them (D663 re-review N-6). Resolves once each device is DRAINED: a write

package/dist/builtins/doorbell/binding-mirror.d.ts

@@ -1,68 +1,4 @@
-/**
- * The virtual-doorbell wrapper's in-memory mirror of ONE durable fact per
- * camera: is this wrapper still the active `doorbell` binding for it?
- *
- * WHY A MIRROR AND NOT A READ. A doorbell press is a one-shot event: there
- * is no retry, no reconcile, nothing downstream that can notice it went
- * missing. The wrapper used to re-derive the binding on the ring path via
- * `deviceManager.getBindings` and treat ANY answer that omitted its own
- * activation as "the operator unbound this". On 2026-08-04/05 camera 615
- * rang zero times out of three real presses: the binding was persisted (a
- * same-day backup taken before the presses proves it, and the same process
- * later returned it correctly to a tRPC query), but the store answered
- * transiently without it — `getBindings` reads the device-manager addon
- * store, which is exactly the surface that can silently answer `{}` (D44,
- * `addon-registry.service.ts`). Three presses, three drops, at `debug`.
- *
- * WHY CORROBORATION AND NOT A BETTER DISCRIMINATOR. There isn't one. A
- * genuinely unbound pure-wrapper cap and a store answering from an empty
- * snapshot produce the SAME `getBindings` response — no `doorbell` entry,
- * with the camera's native entries (snapshot, motion, …) still present in
- * both cases because those come from the capability registry, not the
- * store. The response cannot be graded. What CAN be graded is repetition: a
- * real unbind is permanent and every later read agrees, a store blip does
- * not survive the next read. So a negative read ARMS the revocation and a
- * second consecutive negative applies it.
- *
- * ERRING. `undefined` (never read) and `unbind-pending` both ring. The cost
- * of erring open is a spurious ring on a camera whose wrapper is not bound
- * but which has trigger sources, for at most two reload cycles. The cost of
- * erring closed is the press.
- *
- * D655: a configured source is NO LONGER evidence of the binding. D49 leaned
- * on "a source can only be configured through this wrapper's own
- * binding-gated settings surface"; that surface is retired, and the
- * `doorbell-source` extension slot that replaced it is offered on every
- * camera, bound or not (D648). The erring-open window above is therefore
- * reachable by configuring sources on a never-bound camera, not only by
- * unbinding a configured one — still bounded by two reload cycles, and the
- * slot's card says `inactive` once the reads agree.
- *
- * ─────────────────────────────────────────────────────────────────────
- * 2026-08-07 (D72). The corroboration above was DEFEATED, and the reason
- * matters more than the fix. `refreshBindingMirror` matched the binding with
- * `entry.providerAddonId === this.ctx.id`. The two addon-context factories do
- * not spell `ctx.id` the same way: a forked addon gets `virtual-doorbell`, a
- * hub-main BUILTIN gets `addon:virtual-doorbell`. Every entry on the wire
- * carries the bare form. So for this builtin the comparison was false for
- * every entry, forever — not a blip. Corroboration only defends against a
- * TRANSIENT bad read; two systematically-wrong reads agree with each other,
- * and the mirror latched `unbound` with no way back except an operator
- * opening the settings page. A real press on camera 615 was dropped.
- *
- * Two things follow, and both are now load-bearing here:
- *
- *   1. The comparison goes through `isSameAddonId` ({@link entriesBindWrapper}),
- *      never a raw `===`.
- *   2. The DERIVED view (`deviceManager.getBindings`) is no longer the sole
- *      input. Before a negative is believed — and again on the ring path
- *      before a press is destroyed — the DURABLE authority is consulted
- *      directly ({@link readDurableWrapperBinding} over the `device-manager`
- *      addon store's `deviceBindings` map). That read carries a discriminator
- *      the derived view genuinely cannot offer: a store answering from an
- *      empty snapshot (D44) has no `deviceBindings` key at all, while a
- *      genuine unbind leaves the key present and merely omits the row.
- */
+import { WrapperActivationRead } from '@camstack/types';
 /**
  * `bound` — a read saw the wrapper's activation.
  * `unbind-pending` — one read did not; NOT yet believed, still rings.
@@ -75,7 +11,10 @@ export type DoorbellBindingState = 'bound' | 'unbind-pending' | 'unbound';
  * and must leave the mirror exactly as it was.
  */
 export declare function nextBindingState(previous: DoorbellBindingState | undefined, boundNow: boolean): DoorbellBindingState;
-/** May a ring proceed? Only a corroborated unbind stops one. */
+/**
+ * May a ring proceed on the mirror STATE alone? Only a corroborated unbind
+ * stops one. {@link needsDurableRead} adds the served-elsewhere case on top.
+ */
 export declare function allowsRing(state: DoorbellBindingState | undefined): boolean;
 /** True only when a read has positively confirmed the binding. */
 export declare function hasConfirmedBinding(state: DoorbellBindingState | undefined): boolean;
@@ -108,18 +47,24 @@ export declare function summariseEntries(entries: ReadonlyArray<BindingEntryView
  */
 export type DurableBindingVerdict = 'bound' | 'unbound' | 'unreadable';
 /**
- * Read the DURABLE authority — the `device-manager` addon store's
- * `deviceBindings` map — for "is `ownAddonId` the active wrapper of
- * `capName` on `deviceId`".
+ * The durable verdict for `ownAddonId`, from device-manager's STORED
+ * activation of this cap on this device (`deviceManager.getWrapperActivation`).
  *
- * This is the input the derived `getBindings` view is not: it is the row the
- * operator's toggle actually writes, with no registry resolution, no
- * `defaultActive` auto-binding and no cross-node cap folding in between. It
- * also grades its own trustworthiness, which `getBindings` cannot: the
- * absence of the `deviceBindings` KEY is the signature of a store answering
- * from an empty snapshot, whereas a genuine unbind leaves the key present.
+ * - `value` naming this wrapper → `bound`.
+ * - `value` naming another wrapper, or `null` — the operator's explicit "off"
+ *   marker (D62) — → `unbound`.
+ * - `missing` → `unbound`: the store ANSWERED and holds no activation, and the
+ *   doorbell cap is `defaultActive: false`, so a wrapper nobody activated is
+ *   not bound.
+ * - `failed` → `unreadable`: it carries no information and destroys nothing.
+ */
+export declare function durableVerdictOf(read: WrapperActivationRead, ownAddonId: string): DurableBindingVerdict;
+/**
+ * Who, other than this wrapper, the derived view says serves `capName` —
+ * `composer` on a camera whose doorbell was migrated to a composition (D671).
+ * Non-empty means a press this wrapper does not ring is still somebody's ring.
  */
-export declare function readDurableWrapperBinding(record: unknown, deviceId: number, capName: string, ownAddonId: string): DurableBindingVerdict;
+export declare function otherProvidersOf(entries: ReadonlyArray<BindingEntryView>, capName: string, ownAddonId: string): string[];
 /**
  * What a press on this camera would do right now.
  *
@@ -132,15 +77,34 @@ export declare function readDurableWrapperBinding(record: unknown, deviceId: num
  * store agrees with an unbound mirror: the only verdict that drops a press.
  */
 export type RingVerdict = 'rings' | 'rings-pending' | 'rings-unconfirmed' | 'unknown' | 'silent';
-/** Does this mirror state need the durable authority before a verdict? Only `unbound` does. */
-export declare function needsDurableRead(state: DoorbellBindingState | undefined): boolean;
 /**
- * THE decision — the ring gate (`fireDoorbell` / `ringsDespiteUnboundMirror`)
+ * What the ring gate and the card know about one camera without I/O: the
+ * mirror's state, and which OTHER providers the last successful bindings read
+ * said serve `doorbell` there (empty when none, or when no read has answered).
+ */
+export interface DoorbellMirrorRead {
+    readonly state: DoorbellBindingState | undefined;
+    readonly servedBy: readonly string[];
+}
+/**
+ * Does this camera need the durable authority before a verdict?
+ *
+ * An `unbound` mirror does (D72). So does any mirror short of `bound` on a
+ * camera whose doorbell another provider serves — the D671 cutover, where
+ * erring open means ringing ON TOP of the composer: after every restart the
+ * mirror starts `undefined` and spends a reload cycle at `unbind-pending`, and
+ * each press in that window was a duplicate ring. Two independent reads
+ * agreeing — the derived view naming another provider, the store naming no
+ * wrapper — is the D49 "second read agrees"; an unreadable store still rings.
+ */
+export declare function needsDurableRead(mirror: DoorbellMirrorRead): boolean;
+/**
+ * THE decision — the ring gate (`fireDoorbell` / `ringsAfterDurableRead`)
  * and the Extensions card's activation both call it, so what the card says
  * and what a press does cannot disagree. `durable` is `null` when it was not
- * read, which {@link needsDurableRead} allows for every state but `unbound`.
+ * read, which {@link needsDurableRead} allows only where it says so.
  * Pure: it reads nothing and writes nothing.
  */
-export declare function ringVerdict(state: DoorbellBindingState | undefined, durable: DurableBindingVerdict | null): RingVerdict;
+export declare function ringVerdict(mirror: DoorbellMirrorRead, durable: DurableBindingVerdict | null): RingVerdict;
 /** Whether a press proceeds under this verdict. */
 export declare function verdictRings(verdict: RingVerdict): boolean;

package/dist/builtins/doorbell/doorbell-extension-slot.d.ts

@@ -1,5 +1,5 @@
 import { ExtensionSlotActivation, IDeviceExtensionProvider, IScopedLogger } from '@camstack/types';
-import { DoorbellBindingState, DurableBindingVerdict, RingVerdict } from './binding-mirror.js';
+import { DoorbellMirrorRead, DurableBindingVerdict, RingVerdict } from './binding-mirror.js';
 import { DoorbellSource } from './doorbell-settings.js';
 /** The routing prefix of this owner's `slotRef`s. */
 export declare const VIRTUAL_DOORBELL_EXTENSION_SOURCE = "virtual-doorbell";
@@ -27,7 +27,7 @@ export interface DoorbellSlotDeps {
     /** Several devices in ONE read. Ids no device has are simply absent. */
     readonly listDevices: (deviceIds: readonly number[]) => Promise<readonly DoorbellSlotDevice[]>;
     /** The D49 mirror's verdict for this camera, or undefined when it has none. */
-    readonly readBindingMirror: (deviceId: number) => DoorbellBindingState | undefined;
+    readonly readBindingMirror: (deviceId: number) => DoorbellMirrorRead;
     /**
      * The DURABLE authority, read-only — the same read the ring gate makes
      * before it drops a press. Never throws: a store that cannot answer is
@@ -47,7 +47,8 @@ export declare function activationFromVerdict(verdict: RingVerdict): ExtensionSl
  * never writes it: the mirror gates the ring, and a view that could move it
  * would let a page refetch during a store blip silence a doorbell. The only
  * read the card may make is the durable authority, and only where the ring
- * gate would make it too (`needsDurableRead`: an `unbound` mirror). A camera
+ * gate would make it too (`needsDurableRead`: an `unbound` mirror, or one
+ * short of `bound` whose doorbell another provider serves). A camera
  * the mirror has never seen costs nothing — the ring path errs open there and
  * so does the card.
  */

package/dist/builtins/doorbell/virtual-doorbell.addon.d.ts

@@ -53,6 +53,24 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      * `binding-mirror.ts` for why a single negative read is not believed.
      */
     private readonly bindingMirror;
+    /**
+     * Per camera, the last NEGATIVE refresh this addon reported — its state,
+     * the authority's verdict and who else serves the doorbell. A refresh runs
+     * every reload cycle (about once a minute); the same answer repeated is not
+     * news, so it is reported once per change and forgotten on a positive read.
+     * Camera 615 logged the same WARN 607 times in 14 h after D671.
+     */
+    private readonly reportedNegative;
+    /** Cameras whose last durable-authority read THREW — reported once per outage. */
+    private readonly durableReadFailing;
+    /**
+     * Per camera, the OTHER providers of `doorbell` the last successful derived
+     * read named (the composer after D671). Written off the ring path with the
+     * mirror; read on it, to decide whether erring open would double a ring.
+     */
+    private readonly servedElsewhere;
+    /** Cameras whose store-over-derived disagreement has been reported, until a derived read agrees. */
+    private readonly reportedStoreOverride;
     constructor();
     protected onInitialize(): Promise<ProviderRegistration[]>;
     protected onShutdown(): Promise<void>;
@@ -76,9 +94,9 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      * (UI toast, notifier rules, exporters) is agnostic to the origin.
      *
      * The binding gate here is a pure in-memory read on the path that RINGS:
-     * an open mirror performs NO I/O and cannot fail. The mirror can only
-     * DESTROY a press through the one branch below, and that branch is not
-     * allowed to be the last word — see `ringsDespiteUnboundMirror`.
+     * a `bound` mirror, or an open one on a camera nobody else serves, performs
+     * NO I/O and cannot fail. Every other case asks the durable authority once
+     * before deciding — see `needsDurableRead` and `ringsAfterDurableRead`.
      *
      * `sourceDeviceId`/`capName` are the source that produced this rise —
      * carried through purely so the terminal `pressed` line can name it. Every
@@ -104,8 +122,10 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      */
     private readDerivedBinding;
     /**
-     * One read of the DURABLE authority: the `device-manager` addon store's
-     * `deviceBindings` map, straight from the settings DB.
+     * One read of the DURABLE authority: the wrapper activation device-manager
+     * STORED for this camera (`deviceManager.getWrapperActivation`, D675) — the
+     * row the operator's bindings toggle writes. `deviceManager.getBindings` is
+     * a VIEW derived from it plus the capability registry.
      *
      * This is deliberately NOT `getBindings`. The derived view folds the store
      * together with the capability registry, `defaultActive` auto-binding and
@@ -114,6 +134,9 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      * spelling mismatch) made it disagree *systematically* while looking
      * exactly like a genuine unbind. The raw row cannot: it is what the
      * bindings toggle wrote, and it grades its own trustworthiness (D44).
+     *
+     * A read that throws is reported when the outage STARTS and when it ends —
+     * never per read: this runs on every reload cycle.
      */
     private readDurableAuthority;
     /**
@@ -130,20 +153,39 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      * second consecutive one (D49).
      */
     private refreshBindingMirror;
+    /** The ring gate's in-memory input for one camera — no I/O. */
+    private mirrorRead;
+    /**
+     * Report a negative refresh ONCE per change of what it says (D391: a
+     * repeated identical line is noise that buries the next real one).
+     *
+     * The level follows what the answer MEANS:
+     *   - the durable store could not grade it (`unreadable`) — WARN: the
+     *     camera's ring now depends on erring open, and nobody can say whether
+     *     that is right;
+     *   - the store CONFIRMS the wrapper is not bound — an operator's unbind or
+     *     the D671 cutover to a composition. That is a state, not an anomaly:
+     *     INFO when it is believed (`unbound`), DEBUG for the first,
+     *     not-yet-believed read.
+     */
+    private reportNegativeRefresh;
     /**
-     * The mirror says `unbound` and a real press just arrived. Decide, with
-     * ONE read of the durable authority, whether to destroy it.
+     * A real press arrived on a camera the in-memory gate cannot clear on its
+     * own: the mirror is `unbound`, or it is short of `bound` while another
+     * provider serves the doorbell. Decide, with ONE read of the durable
+     * authority, whether this wrapper rings.
      *
      * D49 forbade I/O on the ring path because the read it would have made was
      * the same fallible derived read that caused the problem. This read is
      * different in both directions: it is the authority rather than a view of
-     * it, and it is paid ONLY on the branch that would otherwise drop a press —
-     * a ring is rare, one query is cheap, and a dropped ring has no retry, no
-     * reconcile and nothing downstream that notices.
+     * it, and it is paid ONLY where erring open could be wrong — a dropped ring
+     * (an `unbound` mirror) or a DOUBLED one (another provider rings this
+     * camera). A ring is rare and one query is cheap. An unreadable store still
+     * rings: it carries no information.
      *
      * Returns `true` when the ring must proceed.
      */
-    private ringsDespiteUnboundMirror;
+    private ringsAfterDurableRead;
     /**
      * Lazily (re)build the camera→source assignment set from every
      * camera's device store. TTL-bounded so devices/settings appearing