@ours.network/notifications 0.3.1-nightly.7 → 1.0.1

package/README.md

@@ -50,17 +50,22 @@ Responses are never cached. User and producer credentials have separate scopes.
 
 | Method/path | Credential | Request/result |
 | --- | --- | --- |
-| GET `/api/v1/push/config` | User | Public VAPID key |
+| GET `/api/v1/push/config` | User | Public VAPID key and `capabilities` (`push-only`, `mission-ownership`, `preferences`) |
+| GET/POST `/api/v1/preferences` | User | `{ "ownMissionRoomMessages": false }`; default `true`. OFF is refused with 409 `mission_rooms_registering` unless the current bootstrap run is complete; the response includes `missionRoomsReady` |
 | POST `/api/v1/devices` | User | `{ "subscription": PushSubscriptionJSON }` → device `id` |
 | POST `/api/v1/devices/delete` | User | `{ "id": "device-id" }`, only that user's device |
 | GET `/api/v1/devices/status?id=...` | User | `{ "active": true }` |
 | GET `/api/v1/inbox?limit=50&before=...` | User | Items, shared unread count, revision, next cursor |
-| GET `/api/v1/summary` | User | Shared unread count, revision, per-chat source/identity/count, and `sections: {chats, tasks}` |
+| GET `/api/v1/unread-evidence?target=TARGET_JSON[&target=ALIAS_JSON]&revision=OBSERVED_REVISION&limit=100&after=...` | User | Capability `unread-evidence/1`: one conversation's records created at or before the observed revision and still unread, oldest first (limit 1-200). A record read since that revision is absent, so a caller comparing with that revision's count sees it as incomplete. Items omit title and body. A cursor whose record was deleted, or that this scope and revision could not have returned, answers 409. Services without the route answer 404 |
+| GET `/api/v1/summary` | User | Shared unread count, revision, per-chat source/identity/count, and `sections: {chats, tasks}`; mission-associated rows (task and room targets, or any row with a `taskId`) count under `chats`, agent rows without a `taskId` field count in neither section (as before), and `tasks` is always 0 (kept for compatibility) |
 | POST `/api/v1/read-target` | User | `{ "target": { "kind": "agent", "agentId": "agent" }, "revision": OBSERVED_REVISION }`, reads only this chat up to the revision captured before its history load |
 | POST `/api/v1/read` | User | `{ "ids": ["notification-id"] }`, idempotent shared read |
 | POST `/api/v1/delete` | User | `{ "ids": ["notification-id"] }` → `{ "removed": COUNT }`; persistently removes only this user’s entries and queued deliveries after the client has confirmed target absence |
 | POST `/api/v1/delete-target` | Producer | `{ "target": { "kind": "agent", "agentId": "agent" } }` → `{ "removed": COUNT }`; only its credential’s user/source and exact canonical conversation, ignoring message anchors |
-| POST `/api/v1/send` | Producer | `{ "eventId": "stable-event-id", "title": "Agent completed", "body": "Open the chat", "target": { "kind": "agent", "agentId": "agent" } }` |
+| POST `/api/v1/send` | Producer | `{ "eventId": "stable-event-id", "title": "Agent completed", "body": "Open the chat", "target": { "kind": "agent", "agentId": "agent" } }`, optional `"delivery": "inbox" \| "push-only"` |
+| POST `/api/v1/missions/associate` | Producer with `mission-ownership` | `{ "taskId": "T", "revision": 2, "contactIds": ["ROOM-CID"] }` → retained rooms and revision |
+| POST `/api/v1/missions/delete` | Producer with `mission-ownership` | `{ "taskId": "T", "contactIds": ["ROOM-CID"] }` → `{ "removed": COUNT }` |
+| POST `/api/v1/missions/bootstrap` | Producer with `mission-ownership` | `{ "generation": 3, "complete": false }` starts a registration run of existing mission rooms; the same generation with `"complete": true` finishes it. Older generations get 409; a completed run cannot reopen |
 
 Inbox admission and queued delivery are one fsynced atomic snapshot. The service
 deduplicates by user/source/event ID; replay must retain identical title/body, typed target/anchor and task association
@@ -92,6 +97,30 @@ Limits are 32 devices/user, 10,000 inbox entries/user, 20,000 queued deliveries,
 returns 503 so durable producers can retain/retry events. This first version
 requires operator archival/reset after inbox capacity is reached.
 
+## Mission ownership, push-only delivery and preferences
+
+`delivery: "push-only"` admits a row that is born read: it is pushed to every device but never counts as
+unread. Reading never cancels its pending push; reading any other row still does. An admitted event keeps
+its delivery mode: a retry may omit `delivery` (older producers) but a different explicit mode returns 409.
+
+Only a producer credential configured with `capabilities: ["mission-ownership"]` (Fleet) may use the
+`/api/v1/missions/*` routes, and only for its own credential user. An association lists the room contacts
+the producer proved belong to one task. Revisions only advance; rooms are only added, so a removed room stays
+attributable. `missions/delete` persists a tombstone and, in one durable revision, removes every row of that
+user from any source whose task association or task/room target is the task, or whose contact is one of its
+rooms, together with their queued pushes. Receipts stay. A later or replayed event for the mission records
+its receipt and returns `200 { "id", "dropped": "deleted" }`; producers acknowledge it and nothing returns.
+Repeating the deletion with more rooms merges and removes those too. Associations for a tombstoned task are
+refused (409). Rows lacking both a task association and a proven room are never inferred from names or times.
+
+`ownMissionRoomMessages: false` stops admitting messages from proven own mission rooms (receipt only,
+`dropped: "suppressed"`), and in the same commit marks that user's existing unread own-room rows read and
+removes their pushes. This is notification state only: conversation read receipts are not touched. Other
+contacts and rooms, agent completions and push-only rows are unaffected, and switching back on never replays
+suppressed events. Before every provider call the drain re-reads the job from the store, so a read,
+deletion or preference change during an earlier send stops all later copies; a provider request already
+started cannot be withdrawn, and an OS notification already shown cannot be removed by the service.
+
 ## Producers and PWA
 
 Fleet web and Messenger use `OURS_NOTIFICATIONS_ORIGIN` and their distinct
@@ -176,7 +205,7 @@ Notifications carry domain identifiers, never frontend URLs. `target` is one of
 
 Deploy producers, service, and App/worker together. Summary `chats` contains `{target,count}` conversation rows; anchors do not affect identity, 64-hex contact CIDs compare case-insensitively, and agent/task/room identities remain distinct. The App supplies its trusted workspace binding and encodes browser addresses. Send/read-target/delete-target accept only the typed contract; no old URL decoding or conversion is provided.
 
-The state file records its format version. This release reads only its own version 2 state: a state file from an earlier release, or one with any record outside the typed contract, is refused at startup and left unchanged. A missing state file starts empty.
+The state file records its format version. This release reads version 3 and strictly validated version 2 state; any other version, or any record outside the typed contract, is refused at startup and left unchanged. A missing state file starts empty. Version 2 is upgraded on load and written at once as version 3 under a strictly newer revision (row IDs, fingerprints and `createdRevision` unchanged; reopening does not bump again). Stored task lifecycle rows become read push-only rows and keep their valid pending pushes. A `task-deleted` row proves its task deleted: the task is tombstoned and every row it owns (lifecycle, task-associated agent and room rows) is removed with its pushes, so late events stay dropped.
 
 ## Full-resource qualification
 

package/dist/mission.d.ts

@@ -0,0 +1,50 @@
+/** Producer capability that may assert mission room ownership and retire a mission's notifications. */
+export declare const MISSION_OWNERSHIP = "mission-ownership";
+/** Advertised service capabilities; producers use new semantics only when listed. */
+export declare const CAPABILITIES: readonly ["push-only", "mission-ownership", "preferences"];
+/** Accumulated rooms one mission may retain; admission refuses beyond it, so stored state always reloads. */
+export declare const MAX_MISSION_ROOMS = 10000;
+/**
+ * Rooms one producer proved to belong to one of its user's missions. Contact IDs only grow:
+ * a removed room stays listed so its notifications remain attributable for deletion.
+ * A tombstone dominates every later association and admission for the mission.
+ */
+export interface Mission {
+    userId: string;
+    source: string;
+    taskId: string;
+    revision: number;
+    contactIds: string[];
+    tombstone?: {
+        at: string;
+    };
+}
+export interface Preference {
+    userId: string;
+    ownMissionRoomMessages: boolean;
+    bootstrap: {
+        generation: number;
+        complete: boolean;
+    } | null;
+}
+export declare const contactKey: (id: string) => string;
+export declare function taskId(value: unknown): string;
+export declare function associationInput(value: Record<string, unknown>): {
+    taskId: string;
+    revision: number;
+    contactIds: string[];
+};
+export declare function deletionInput(value: Record<string, unknown>): {
+    taskId: string;
+    contactIds: string[];
+};
+export declare function preferenceInput(value: Record<string, unknown>): {
+    ownMissionRoomMessages: boolean;
+};
+export declare function bootstrapInput(value: Record<string, unknown>): {
+    generation: number;
+    complete: boolean;
+};
+/** Persisted-state validation for the mission records of a version 3 state file. */
+export declare function validMissions(value: unknown): Mission[];
+export declare function validPreferences(value: unknown): Preference[];

package/dist/mission.js

@@ -0,0 +1,94 @@
+import { HttpError, fields, object, text } from './validation.js';
+/** Producer capability that may assert mission room ownership and retire a mission's notifications. */
+export const MISSION_OWNERSHIP = 'mission-ownership';
+/** Advertised service capabilities; producers use new semantics only when listed. */
+export const CAPABILITIES = ['push-only', MISSION_OWNERSHIP, 'preferences'];
+const MAX_CONTACTS = 64;
+/** Accumulated rooms one mission may retain; admission refuses beyond it, so stored state always reloads. */
+export const MAX_MISSION_ROOMS = 10_000;
+export const contactKey = (id) => /^[a-f0-9]{64}$/i.test(id) ? id.toUpperCase() : id;
+export function taskId(value) {
+    const id = text(value, 120);
+    if (!/^[A-Za-z0-9_-]+$/.test(id))
+        throw new HttpError(400, 'invalid task identity');
+    return id;
+}
+function contactIds(value) {
+    if (!Array.isArray(value) || value.length > MAX_CONTACTS)
+        throw new HttpError(400, 'invalid contact identities');
+    return [...new Set(value.map(id => {
+            const contact = text(id, 512);
+            if (/[\x00-\x1f\x7f\/\\]/.test(contact) || contact === '.' || contact === '..')
+                throw new HttpError(400, 'invalid contact identity');
+            return contactKey(contact);
+        }))];
+}
+export function associationInput(value) {
+    fields(value, ['taskId', 'revision', 'contactIds']);
+    if (!Number.isSafeInteger(value.revision) || value.revision < 1)
+        throw new HttpError(400, 'invalid association revision');
+    return { taskId: taskId(value.taskId), revision: value.revision, contactIds: contactIds(value.contactIds) };
+}
+export function deletionInput(value) {
+    fields(value, ['taskId', 'contactIds']);
+    return { taskId: taskId(value.taskId), contactIds: contactIds(value.contactIds ?? []) };
+}
+export function preferenceInput(value) {
+    fields(value, ['ownMissionRoomMessages']);
+    if (typeof value.ownMissionRoomMessages !== 'boolean')
+        throw new HttpError(400, 'invalid preference');
+    return { ownMissionRoomMessages: value.ownMissionRoomMessages };
+}
+export function bootstrapInput(value) {
+    fields(value, ['generation', 'complete']);
+    if (!Number.isSafeInteger(value.generation) || value.generation < 1 || typeof value.complete !== 'boolean')
+        throw new HttpError(400, 'invalid bootstrap');
+    return { generation: value.generation, complete: value.complete };
+}
+/** Persisted-state validation for the mission records of a version 3 state file. */
+export function validMissions(value) {
+    if (!Array.isArray(value))
+        throw new Error();
+    const keys = new Set();
+    for (const item of value) {
+        const m = object(item);
+        if (Object.keys(m).some(k => !['userId', 'source', 'taskId', 'revision', 'contactIds', 'tombstone'].includes(k)))
+            throw new Error();
+        if (typeof m.userId !== 'string' || !m.userId || typeof m.source !== 'string' || !m.source)
+            throw new Error();
+        taskId(m.taskId);
+        if (!Number.isSafeInteger(m.revision) || m.revision < 0)
+            throw new Error();
+        // Persisted rooms obey the same identity rules as admission: canonical, unique, no blanks, controls, paths or dot segments.
+        if (!Array.isArray(m.contactIds) || new Set(m.contactIds).size !== m.contactIds.length || m.contactIds.length > MAX_MISSION_ROOMS
+            || m.contactIds.some(id => typeof id !== 'string' || !id.trim() || id.length > 512 || /[\x00-\x1f\x7f\/\\]/.test(id)
+                || id === '.' || id === '..' || contactKey(id) !== id))
+            throw new Error();
+        if (m.tombstone !== undefined && (typeof object(m.tombstone).at !== 'string' || Object.keys(m.tombstone).length !== 1))
+            throw new Error();
+        const key = JSON.stringify([m.userId, m.source, m.taskId]);
+        if (keys.has(key))
+            throw new Error();
+        keys.add(key);
+    }
+    return value;
+}
+export function validPreferences(value) {
+    if (!Array.isArray(value))
+        throw new Error();
+    const users = new Set();
+    for (const item of value) {
+        const p = object(item);
+        if (Object.keys(p).sort().join() !== 'bootstrap,ownMissionRoomMessages,userId')
+            throw new Error();
+        if (typeof p.userId !== 'string' || !p.userId || users.has(p.userId) || typeof p.ownMissionRoomMessages !== 'boolean')
+            throw new Error();
+        if (p.bootstrap !== null) {
+            const b = object(p.bootstrap);
+            if (Object.keys(b).sort().join() !== 'complete,generation' || !Number.isSafeInteger(b.generation) || b.generation < 1 || typeof b.complete !== 'boolean')
+                throw new Error();
+        }
+        users.add(p.userId);
+    }
+    return value;
+}

package/dist/server.d.ts

@@ -4,7 +4,8 @@ import { Store } from './store.js';
 export interface Credential {
     token: string;
     userId: string;
-    source?: string;
+    source?: string; /** Producer capabilities, e.g. `mission-ownership` for Fleet. */
+    capabilities?: string[];
 }
 export interface Config {
     host?: string;

package/dist/server.js

@@ -5,6 +5,7 @@ import { attachPresence } from './presence.js';
 import { Store } from './store.js';
 import { NotificationViews } from './resource-views.js';
 import { HttpError, object, subscription, target, anchor, conversationTarget, fields, text } from './validation.js';
+import { CAPABILITIES, MISSION_OWNERSHIP, associationInput, bootstrapInput, deletionInput, preferenceInput } from './mission.js';
 const same = (a, b) => {
     const x = Buffer.from(a), y = Buffer.from(b);
     return x.length === y.length && timingSafeEqual(x, y);
@@ -28,10 +29,17 @@ async function body(req) {
 export function createNotificationService(config, send) {
     const tokens = [...config.users, ...config.producers];
     if (!tokens.length || tokens.some(c => typeof c.token !== 'string' || c.token.length < 32 || !c.userId || c.userId.length > 256)
-        || new Set(tokens.map(c => c.token)).size !== tokens.length || config.producers.some(c => !c.source))
+        || new Set(tokens.map(c => c.token)).size !== tokens.length || config.producers.some(c => !c.source)
+        || tokens.some(c => c.capabilities !== undefined && (!Array.isArray(c.capabilities) || c.capabilities.some(v => typeof v !== 'string'))))
         throw new Error('invalid scoped credentials');
     webpush.setVapidDetails(config.vapid.subject, config.vapid.publicKey, config.vapid.privateKey);
-    const store = new Store(config.stateFile);
+    // Trust is per (user, source) pair. A pair whose credentials disagree on mission ownership is refused: its typed task
+    // events would otherwise be push-only or inbox depending on which token sent them.
+    const trusted = (c) => !!c.capabilities?.includes(MISSION_OWNERSHIP);
+    for (const c of config.producers)
+        if (config.producers.some(o => o.userId === c.userId && o.source === c.source && trusted(o) !== trusted(c)))
+            throw new Error('invalid scoped credentials: one producer has credentials with and without mission ownership');
+    const store = new Store(config.stateFile, { lifecycleProducers: config.producers.filter(trusted).map(c => ({ userId: c.userId, source: c.source })) });
     const views = new NotificationViews(store);
     const deliver = send ?? ((sub, payload) => webpush.sendNotification(sub, payload, { TTL: 3600, timeout: 10_000,
         vapidDetails: config.vapid, contentEncoding: 'aes128gcm' }));
@@ -46,11 +54,15 @@ export function createNotificationService(config, send) {
             if (req.headers.origin || req.headers.cookie || req.headers['sec-fetch-site'])
                 throw new HttpError(403, 'use authenticated gateway');
             const url = new URL(req.url ?? '/', 'http://localhost');
-            const producerRoute = ['/api/v1/send', '/api/v1/delete-target'].includes(url.pathname);
+            const missionRoute = url.pathname.startsWith('/api/v1/missions/');
+            const producerRoute = ['/api/v1/send', '/api/v1/delete-target'].includes(url.pathname) || missionRoute;
             const authorization = req.headers.authorization ?? '';
             const credential = (producerRoute ? config.producers : config.users).find(c => same(authorization, `Bearer ${c.token}`));
             if (!credential)
                 throw new HttpError(401, 'authentication required');
+            // Cross-source mission cleanup is reserved to the producer trusted with mission ownership, for its own user.
+            if (missionRoute && !credential.capabilities?.includes(MISSION_OWNERSHIP))
+                throw new HttpError(403, 'mission ownership capability required');
             const key = credential.token;
             let rate = rates.get(key);
             if (!rate || rate.until <= Date.now()) {
@@ -94,7 +106,26 @@ export function createNotificationService(config, send) {
             }
             let result;
             if (req.method === 'GET' && url.pathname === '/api/v1/push/config')
-                result = { publicKey: config.vapid.publicKey };
+                result = { publicKey: config.vapid.publicKey, capabilities: CAPABILITIES };
+            else if (req.method === 'GET' && url.pathname === '/api/v1/preferences')
+                result = store.preference(user);
+            else if (req.method === 'POST' && url.pathname === '/api/v1/preferences')
+                result = store.setPreference(user, preferenceInput(await body(req)).ownMissionRoomMessages);
+            else if (req.method === 'POST' && url.pathname === '/api/v1/missions/associate') {
+                const value = await body(req);
+                if ('userId' in value || 'source' in value)
+                    throw new HttpError(400, 'recipient and source are credential scoped');
+                result = store.associateMission(user, credential.source, associationInput(value));
+            }
+            else if (req.method === 'POST' && url.pathname === '/api/v1/missions/delete') {
+                const value = await body(req);
+                if ('userId' in value || 'source' in value)
+                    throw new HttpError(400, 'recipient and source are credential scoped');
+                result = store.deleteMission(user, credential.source, deletionInput(value));
+            }
+            else if (req.method === 'POST' && url.pathname === '/api/v1/missions/bootstrap') {
+                result = store.missionBootstrap(user, bootstrapInput(await body(req)));
+            }
             else if (req.method === 'GET' && url.pathname === '/api/v1/delivery/status')
                 result = store.deliveryStatus(user);
             else if (req.method === 'GET' && url.pathname === '/api/v1/summary')
@@ -105,6 +136,26 @@ export function createNotificationService(config, send) {
                     throw new HttpError(400, 'invalid limit');
                 result = store.inbox(user, url.searchParams.get('before') ?? undefined, limit);
             }
+            else if (req.method === 'GET' && url.pathname === '/api/v1/unread-evidence') {
+                // Capability `unread-evidence/1`: a separate route, so a service without it answers
+                // 404 instead of ignoring the scope and returning the global inbox.
+                const targets = url.searchParams.getAll('target');
+                if (targets.length < 1 || targets.length > 2)
+                    throw new HttpError(400, 'expected one or two conversation targets');
+                const scope = targets.map(value => { try {
+                    return conversationTarget(JSON.parse(value));
+                }
+                catch (error) {
+                    throw error instanceof HttpError ? error : new HttpError(400, 'invalid conversation target');
+                } });
+                const limit = Number(url.searchParams.get('limit') ?? 100);
+                if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+                    throw new HttpError(400, 'invalid limit');
+                if (!url.searchParams.has('revision'))
+                    throw new HttpError(400, 'invalid observed revision');
+                const revision = Number(url.searchParams.get('revision'));
+                result = { capability: 'unread-evidence/1', targets: scope, ...store.unreadEvidence(user, scope, revision, url.searchParams.get('after') ?? undefined, limit) };
+            }
             else if (req.method === 'GET' && url.pathname === '/api/v1/devices/status')
                 result = { active: store.deviceStatus(user, url.searchParams.get('id') ?? '') };
             else if (req.method === 'POST' && url.pathname === '/api/v1/devices') {
@@ -142,18 +193,20 @@ export function createNotificationService(config, send) {
                 const value = await body(req);
                 if ('userId' in value || 'source' in value)
                     throw new HttpError(400, 'recipient and source are credential scoped');
-                fields(value, ['eventId', 'title', 'body', 'target', 'anchor', 'taskId']);
+                fields(value, ['eventId', 'title', 'body', 'target', 'anchor', 'taskId', 'delivery']);
+                if (value.delivery !== undefined && value.delivery !== 'inbox' && value.delivery !== 'push-only')
+                    throw new HttpError(400, 'invalid delivery');
                 const destination = target(value.target);
                 const messageAnchor = value.anchor === undefined ? undefined : anchor(value.anchor, destination);
                 const taskId = value.taskId === undefined ? undefined : value.taskId === null ? null : text(value.taskId, 120);
                 if (typeof taskId === 'string' && !/^[A-Za-z0-9_-]+$/.test(taskId))
                     throw new HttpError(400, 'invalid task identity');
-                result = store.produce({ ...(taskId === undefined ? {} : { taskId }), userId: user, source: credential.source, eventId: text(value.eventId, 512),
+                result = store.produce({ ...(taskId === undefined ? {} : { taskId }), ...(value.delivery === undefined ? {} : { pushOnly: value.delivery === 'push-only' }), userId: user, source: credential.source, eventId: text(value.eventId, 512),
                     title: text(value.title, 160), body: text(value.body, 512), target: destination, ...(messageAnchor === undefined ? {} : { anchor: messageAnchor }) });
             }
             else
                 throw new HttpError(404, 'route not found');
-            if (req.method === 'POST' && ['/api/v1/send', '/api/v1/read', '/api/v1/read-target', '/api/v1/delete', '/api/v1/delete-target'].includes(url.pathname))
+            if (req.method === 'POST' && (missionRoute || ['/api/v1/send', '/api/v1/read', '/api/v1/read-target', '/api/v1/delete', '/api/v1/delete-target', '/api/v1/preferences'].includes(url.pathname)))
                 presence.notify(user);
             res.end(JSON.stringify(result));
         }
@@ -167,9 +220,15 @@ export function createNotificationService(config, send) {
     server.headersTimeout = 10_000;
     let draining;
     const drain = () => draining ??= (async () => {
-        for (const j of store.due(Date.now())) {
-            if (!j.device || !j.notification || j.notification.readAt) {
-                store.finish(j.id, 'sent', Date.now(), j.notification?.readAt ? 'read_cancelled' : 'missing_target');
+        // The due snapshot only nominates jobs. Each is re-read from the store right before its provider call, so a
+        // read, deletion, tombstone or preference change during an earlier send stops every later copy.
+        for (const due of store.due(Date.now())) {
+            const current = store.dispatchable(due.id);
+            if (!current)
+                continue;
+            const j = { ...current.job, device: current.device, notification: current.notification };
+            if (!j.device || !j.notification || current.cancelled) {
+                store.finish(j.id, 'sent', Date.now(), current.cancelled ? 'read_cancelled' : 'missing_target');
                 continue;
             }
             if (j.notification.target?.kind !== 'task' && j.notification.target?.kind !== 'task-deleted' && presence.online(j.device.userId, j.device.id)) {

package/dist/store.d.ts

@@ -14,12 +14,21 @@ export interface Notification {
     createdRevision?: number;
     readAt: string | null;
     taskId?: string | null;
+    /** Born read: delivered as push, never unread in the app. */
+    pushOnly?: true;
 }
 interface Device {
     id: string;
     userId: string;
     subscription: PushSubscription;
 }
+interface Job {
+    id: string;
+    notificationId: string;
+    deviceId: string;
+    attempts: number;
+    due: number;
+}
 export type DeliveryOutcome = 'provider_accepted' | 'foreground_suppressed' | 'endpoint_expired' | 'retry_scheduled' | 'read_cancelled' | 'missing_target' | 'no_device';
 interface Delivery {
     userId: string;
@@ -31,9 +40,16 @@ interface Delivery {
     statusCode?: number;
 }
 type Input = Omit<Notification, 'id' | 'createdAt' | 'readAt'>;
+export type Admission = Notification | {
+    id: string;
+    duplicate: true;
+} | {
+    id: string;
+    dropped: 'deleted' | 'suppressed';
+};
 /** The receipt fingerprint of a typed notification, as stored with it. */
 export declare const fingerprint: (value: Input) => string;
-/** Single-writer local service. Mutations commit a fsynced atomic snapshot before acknowledgement. */
+export declare const producerKey: (userId: string, source: string) => string;
 export declare class Store {
     private readonly file;
     private state;
@@ -42,7 +58,14 @@ export declare class Store {
     private readonly observers;
     /** Neutral committed observation; never enrolls a device or changes read state. */
     subscribe(committed: () => void, signal: AbortSignal): () => void;
-    constructor(file: string);
+    /** (user, source) pairs trusted with mission ownership, as `producerKey`; their typed task events are push-only. */
+    private readonly lifecycleProducers;
+    constructor(file: string, options?: {
+        lifecycleProducers?: ReadonlyArray<{
+            userId: string;
+            source: string;
+        }>;
+    });
     close(): void;
     private commit;
     ensureDevice(userId: string, subscription: PushSubscription): {
@@ -57,6 +80,34 @@ export declare class Store {
         revision: number;
         nextCursor: string | null | undefined;
     };
+    /**
+     * One conversation's unread evidence as of an observed revision, oldest first.
+     * Only records created at or before `revision` and still unread now are returned:
+     * the store keeps no prior read state, so a record read since `revision` is absent
+     * and the caller's count for that revision then stays unmet (incomplete), never
+     * silently satisfied. `after` resumes after a returned record; a cursor whose record
+     * was deleted, or that this scope and revision could not have returned, is stale (409)
+     * rather than restarting or skipping.
+     */
+    unreadEvidence(userId: string, targets: ChatTarget[], revision: number, after: string | undefined, limit: number): {
+        revision: number;
+        currentRevision: number;
+        items: {
+            id: string;
+            userId: string;
+            source: string;
+            eventId: string;
+            target: NotificationTarget;
+            anchor?: NotificationAnchor;
+            createdAt: string;
+            createdRevision?: number;
+            readAt: string | null;
+            taskId?: string | null;
+            /** Born read: delivered as push, never unread in the app. */
+            pushOnly?: true;
+        }[];
+        nextCursor: string | null;
+    };
     summary(userId: string): {
         unread: number;
         revision: number;
@@ -75,10 +126,61 @@ export declare class Store {
     deleteNotifications(userId: string, ids: string[]): number;
     /** A producer may retire only its own notifications for the canonical conversation. */
     deleteTarget(userId: string, source: string, value: unknown): number;
-    produce(value: Input): Notification | {
-        id: string;
-        duplicate: true;
+    /** `pushOnly` false is an explicit inbox delivery; omitted is a legacy producer that did not state one. */
+    produce(input: Omit<Input, 'pushOnly'> & {
+        pushOnly?: boolean;
+    }): Admission;
+    /** Rows of a tombstoned mission: its task association or targets, or any proven room of it. */
+    private tombstoned;
+    /** Own mission room messages while the user turned them off. External contacts never match: only proven rooms do. */
+    private suppressed;
+    private storedPreference;
+    preference(userId: string): {
+        userId: string;
+        ownMissionRoomMessages: boolean;
+        missionRoomsReady: boolean;
     };
+    /** Notification preference only: OFF marks existing own-room rows read and retires their pushes; conversations are untouched. */
+    setPreference(userId: string, ownMissionRoomMessages: boolean): {
+        userId: string;
+        ownMissionRoomMessages: boolean;
+        missionRoomsReady: boolean;
+    };
+    /**
+     * The ownership producer registers its existing mission rooms in numbered runs. A run starts (`complete: false`)
+     * and completes under the same generation; an older generation is stale and a completed run cannot reopen.
+     * OFF can be chosen only after a run completed, so no existing own room is unassociated while OFF.
+     */
+    missionBootstrap(userId: string, input: {
+        generation: number;
+        complete: boolean;
+    }): {
+        generation: number;
+        complete: boolean;
+    };
+    /** Proven rooms of one mission. Revisions only advance, rooms are only added, and a tombstone wins. */
+    associateMission(userId: string, source: string, value: {
+        taskId: string;
+        revision: number;
+        contactIds: string[];
+    }): {
+        contactIds: string[];
+        revision: number;
+    };
+    /** One durable revision: tombstone (merging newly proven rooms), then remove every matching row and its pushes from any source. */
+    deleteMission(userId: string, source: string, value: {
+        taskId: string;
+        contactIds: string[];
+    }): {
+        removed: number;
+    };
+    /** Immediately before a provider call: the job, its row and its device as currently persisted, or nothing if no longer deliverable. */
+    dispatchable(jobId: string): {
+        job: Job;
+        notification: Notification | undefined;
+        device: Device | undefined;
+        cancelled: boolean;
+    } | undefined;
     due(now: number): {
         device: Device | undefined;
         notification: Notification | undefined;

package/dist/store.js

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { HttpError, target, anchor, conversationTarget, subscription } from './validation.js';
+import { MAX_MISSION_ROOMS, associationInput, contactKey, deletionInput, validMissions, validPreferences } from './mission.js';
 /** The receipt fingerprint of a typed notification, as stored with it. */
 export const fingerprint = (value) => createHash('sha256').update(JSON.stringify([
     'domain-target-v1', value.userId, value.source, value.eventId, value.title, value.body,
@@ -19,12 +20,18 @@ const string = (value) => { if (typeof value !== 'string' || !value)
     throw new Error(); return value; };
 const count = (value) => { if (!Number.isSafeInteger(value) || value < 0)
     throw new Error(); return value; };
-/** Accepts only this release's persisted format: every record typed, consistent and closed. */
+/** Accepts version 3 state, or strict version 2 state upgraded explicitly; every record typed, consistent and closed. */
 function validState(value) {
     try {
-        const state = record(value, ['version', 'revision', 'devices', 'notifications', 'jobs', 'receipts', 'deliveries']);
-        if (state.version !== 2)
+        const version = record(value, ['version', 'revision', 'devices', 'notifications', 'jobs', 'receipts', 'deliveries', 'missions', 'preferences']).version;
+        const state = record(value, version === 3 ? ['version', 'revision', 'devices', 'notifications', 'jobs', 'receipts', 'deliveries', 'missions', 'preferences']
+            : ['version', 'revision', 'devices', 'notifications', 'jobs', 'receipts', 'deliveries']);
+        if (version !== 2 && version !== 3)
             throw new Error();
+        if (version === 3) {
+            validMissions(state.missions);
+            validPreferences(state.preferences);
+        }
         count(state.revision);
         for (const key of ['devices', 'notifications', 'jobs', 'receipts', 'deliveries'])
             if (!Array.isArray(state[key]))
@@ -38,7 +45,9 @@ function validState(value) {
             devices.set(d.id, string(d.userId));
         }
         for (const item of state.receipts) {
-            const r = record(item, ['userId', 'source', 'eventId', 'id', 'fingerprint']);
+            const r = record(item, version === 3 ? ['userId', 'source', 'eventId', 'id', 'fingerprint', 'pushOnly'] : ['userId', 'source', 'eventId', 'id', 'fingerprint']);
+            if (r.pushOnly !== undefined && r.pushOnly !== true)
+                throw new Error();
             const key = JSON.stringify([string(r.userId), string(r.source), string(r.eventId)]);
             string(r.id);
             if (receipts.has(key) || !/^[a-f0-9]{64}$/.test(string(r.fingerprint)))
@@ -46,7 +55,9 @@ function validState(value) {
             receipts.set(key, r);
         }
         for (const item of state.notifications) {
-            const n = record(item, ['id', 'userId', 'source', 'eventId', 'title', 'body', 'target', 'anchor', 'createdAt', 'createdRevision', 'readAt', 'taskId']);
+            const n = record(item, ['id', 'userId', 'source', 'eventId', 'title', 'body', 'target', 'anchor', 'createdAt', 'createdRevision', 'readAt', 'taskId', ...(version === 3 ? ['pushOnly'] : [])]);
+            if (n.pushOnly !== undefined && (n.pushOnly !== true || n.readAt === null))
+                throw new Error();
             for (const key of ['id', 'userId', 'source', 'eventId', 'title', 'body', 'createdAt'])
                 string(n[key]);
             const destination = target(n.target);
@@ -63,7 +74,7 @@ function validState(value) {
                 throw new Error();
             // Each notification's own receipt carries its typed fingerprint.
             const own = receipts.get(JSON.stringify([n.userId, n.source, n.eventId]));
-            if (!own || own.id !== n.id || own.fingerprint !== fingerprint(n) || notifications.has(n.id))
+            if (!own || own.id !== n.id || own.fingerprint !== fingerprint(n) || own.pushOnly !== n.pushOnly || notifications.has(n.id))
                 throw new Error();
             notifications.set(n.id, n.userId);
         }
@@ -89,13 +100,103 @@ function validState(value) {
             if (!outcomes.includes(d.outcome))
                 throw new Error();
         }
-        return state;
+        return version === 3 ? state : upgrade(state);
     }
     catch {
-        throw new Error('unsupported notification state: this release reads only its own version 2 state file');
+        throw new Error('unsupported notification state: this release reads only version 2 or 3 state files');
     }
 }
+/** Version 2 → 3. Stored task lifecycle rows become push-only and read: they never count as unread again, while
+ * a valid pending push for a live task still goes out. A `task-deleted` row proves its task deleted: the upgrade
+ * tombstones that task and removes every row it owns (lifecycle, task-associated agent and room rows) with their
+ * pushes, so neither stored nor late events of a deleted task stay or return. Receipts stay for dedupe. */
+function upgrade(v2) {
+    const missions = [];
+    for (const n of v2.notifications) {
+        if (n.target.kind !== 'task-deleted')
+            continue;
+        const taskId = n.target.taskId;
+        if (!missions.some(m => m.userId === n.userId && m.source === n.source && m.taskId === taskId))
+            missions.push({ userId: n.userId, source: n.source, taskId, revision: 0, contactIds: [], tombstone: { at: n.createdAt } });
+    }
+    const removed = new Set(v2.notifications.filter(n => missions.some(m => m.userId === n.userId && owns(m, n))).map(n => n.id));
+    const lifecycle = new Set(v2.notifications.filter(n => !removed.has(n.id) && n.target.kind === 'task').map(n => n.id));
+    const notifications = v2.notifications.filter(n => !removed.has(n.id))
+        .map(n => lifecycle.has(n.id) ? { ...n, readAt: n.readAt ?? n.createdAt, pushOnly: true } : n);
+    const receipts = v2.receipts.map(r => lifecycle.has(r.id) ? { ...r, pushOnly: true } : r);
+    return { ...v2, version: 3, notifications, receipts, jobs: v2.jobs.filter(j => !removed.has(j.notificationId)), missions, preferences: [] };
+}
+/**
+ * The trusted mission producer's typed task events (state transitions, Progress, To review) are push-only by contract.
+ * Proof: the row's own (user, producer source) pair is trusted with mission ownership, the target is a task, the event ID
+ * is scoped to that same task (`task:<taskId>:…`), and any explicit task association names the same task.
+ */
+const TASK_EVENT = /^task:([0-9a-z]{9}[0-9a-f]{8}):/;
+export const producerKey = (userId, source) => JSON.stringify([userId, source]);
+function lifecycleEvent(trusted, n) {
+    return trusted.has(producerKey(n.userId, n.source)) && n.target.kind === 'task' && TASK_EVENT.exec(n.eventId)?.[1] === n.target.taskId
+        && (n.taskId === undefined || n.taskId === n.target.taskId);
+}
+/**
+ * Durable repair on open. An earlier producer could still send those events without a delivery policy after the v2
+ * upgrade, so they became inbox rows. Such a row (proven by the predicate on its stored target) becomes push-only: an
+ * unread one is read at its creation time, and a read one keeps its read time. Its own receipt follows, so a later
+ * push-only retry matches the stored policy and returns the same row. A pending push stays eligible, as for every
+ * push-only row; a push already cancelled by a read was removed then and is not recreated. A receipt whose row is gone
+ * carries no target, so it is never repaired here; see the retry path in `produce`. Idempotent.
+ */
+/** Receipt mutations are bound to the exact (user, source, event ID, id) tuple, never to an id alone. */
+const receiptKey = (k) => JSON.stringify([k.userId, k.source, k.eventId, k.id]);
+const sameReceipt = (r, k) => receiptKey(r) === receiptKey(k);
+function lifecycleRepair(state, trusted) {
+    const repaired = state.notifications.filter(n => !n.pushOnly && lifecycleEvent(trusted, n));
+    const rows = new Set(repaired.map(n => n.id)), keys = new Set(repaired.map(receiptKey));
+    const receipts = new Set(state.receipts.filter(r => !r.pushOnly && keys.has(receiptKey(r))));
+    return { rows, receipts };
+}
+function applyLifecycleRepair(draft, trusted) {
+    const { rows, receipts } = lifecycleRepair(draft, trusted);
+    draft.notifications = draft.notifications.map(n => rows.has(n.id) ? { ...n, readAt: n.readAt ?? n.createdAt, pushOnly: true } : n);
+    draft.receipts = draft.receipts.map(r => receipts.has(r) ? { ...r, pushOnly: true } : r);
+}
 /** Single-writer local service. Mutations commit a fsynced atomic snapshot before acknowledgement. */
+/** Reading cancels a pending push, except for push-only rows, which are born read for exactly that delivery. */
+const cancelled = (n) => !!n?.readAt && !n.pushOnly;
+/** Does this row belong to the mission: its explicit task association, task/room target, or one of its proven rooms. */
+/** A mission's owner is a non-empty account and producer, as persisted validation requires. */
+function owner(userId, source, value) {
+    if (typeof userId !== 'string' || !userId || typeof source !== 'string' || !source)
+        throw new HttpError(400, 'invalid mission owner');
+    return value;
+}
+function owns(m, n) {
+    const t = n.target;
+    if (n.taskId === m.taskId)
+        return true;
+    if ((t.kind === 'task' || t.kind === 'task-deleted' || t.kind === 'room') && t.taskId === m.taskId)
+        return true;
+    return t.kind === 'contact' && m.contactIds.includes(contactKey(t.contactId));
+}
+/** A message from a live, proven own mission room. */
+function ownRoom(state, n) {
+    const t = n.target;
+    if (t.kind === 'room')
+        return state.missions.some(m => m.userId === n.userId && !m.tombstone && m.taskId === t.taskId);
+    if (t.kind !== 'contact')
+        return false;
+    const id = contactKey(t.contactId);
+    return state.missions.some(m => m.userId === n.userId && !m.tombstone && m.contactIds.includes(id));
+}
+/** With own-room messages off, existing unread rows from proven own rooms become read and lose their pending pushes. */
+function quiet(s, userId) {
+    if (s.preferences.find(p => p.userId === userId)?.ownMissionRoomMessages !== false)
+        return;
+    const at = new Date().toISOString();
+    for (const n of s.notifications)
+        if (n.userId === userId && !n.readAt && ownRoom(s, n))
+            n.readAt = at;
+    s.jobs = s.jobs.filter(j => !cancelled(s.notifications.find(n => n.id === j.notificationId)));
+}
 export class Store {
     file;
     state;
@@ -111,8 +212,11 @@ export class Store {
         }
         return dispose;
     }
-    constructor(file) {
+    /** (user, source) pairs trusted with mission ownership, as `producerKey`; their typed task events are push-only. */
+    lifecycleProducers;
+    constructor(file, options = {}) {
         this.file = file;
+        this.lifecycleProducers = new Set((options.lifecycleProducers ?? []).map(p => producerKey(p.userId, p.source)));
         mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
         const lock = file + '.lock';
         let lockFd;
@@ -131,8 +235,15 @@ export class Store {
         }
         try {
             // A missing state file starts empty; an existing one must be this release's format and is never rewritten to fit.
-            this.state = existsSync(file) ? validState(JSON.parse(readFileSync(file, 'utf8')))
-                : { version: 2, revision: 0, devices: [], notifications: [], jobs: [], receipts: [], deliveries: [] };
+            // Only a missing file starts empty; any existing contents, including null or other scalars, must validate.
+            const exists = existsSync(file), stored = exists ? JSON.parse(readFileSync(file, 'utf8')) : undefined;
+            this.state = exists ? validState(stored)
+                : { version: 3, revision: 0, devices: [], notifications: [], jobs: [], receipts: [], deliveries: [], missions: [], preferences: [] };
+            // Persist an upgrade at once under a strictly newer revision, so every client sees the changed unread state.
+            // The lifecycle repair is committed the same way, once; a repaired state has nothing left to repair.
+            const repair = lifecycleRepair(this.state, this.lifecycleProducers);
+            if (exists && (stored.version === 2 || repair.rows.size || repair.receipts.size))
+                this.commit(draft => applyLifecycleRepair(draft, this.lifecycleProducers));
         }
         catch (error) {
             this.close();
@@ -211,15 +322,56 @@ export class Store {
         return { items, unread: all.filter(n => !n.readAt).length, revision: this.state.revision,
             nextCursor: index > limit ? items.at(-1)?.id : null };
     }
+    /**
+     * One conversation's unread evidence as of an observed revision, oldest first.
+     * Only records created at or before `revision` and still unread now are returned:
+     * the store keeps no prior read state, so a record read since `revision` is absent
+     * and the caller's count for that revision then stays unmet (incomplete), never
+     * silently satisfied. `after` resumes after a returned record; a cursor whose record
+     * was deleted, or that this scope and revision could not have returned, is stale (409)
+     * rather than restarting or skipping.
+     */
+    unreadEvidence(userId, targets, revision, after, limit) {
+        if (!Number.isSafeInteger(revision) || revision < 0 || revision > this.state.revision)
+            throw new HttpError(400, 'invalid observed revision');
+        const keys = new Set(targets.map(chatKey));
+        const inScope = (n) => { const other = chatTarget(n.target); return !!other && keys.has(chatKey(other)); };
+        const all = this.state.notifications;
+        let start = 0;
+        if (after !== undefined) {
+            // The cursor must name a record this same scope and revision could have returned;
+            // having been read since keeps its position.
+            const index = all.findIndex(n => n.id === after);
+            const cursor = all[index];
+            if (!cursor || cursor.userId !== userId || (cursor.createdRevision ?? 0) > revision || !inScope(cursor))
+                throw new HttpError(409, 'stale evidence cursor');
+            start = index + 1;
+        }
+        // Collect one record past the page to know whether another page exists.
+        const items = [];
+        for (let index = start; index < all.length && items.length <= limit; index++) {
+            const n = all[index];
+            if (n.userId === userId && !n.readAt && (n.createdRevision ?? 0) <= revision && inScope(n))
+                items.push(n);
+        }
+        const more = items.length > limit;
+        if (more)
+            items.pop();
+        // Evidence carries identity, conversation, link and provenance; never the text.
+        return { revision, currentRevision: this.state.revision, items: items.map(({ title: _title, body: _body, ...rest }) => structuredClone(rest)),
+            nextCursor: more ? items.at(-1).id : null };
+    }
     summary(userId) {
         const unread = this.state.notifications.filter(n => n.userId === userId && !n.readAt);
         const groups = new Map();
         const sections = { chats: 0, tasks: 0 };
         for (const n of unread) {
             const destination = n.target;
-            if (destination.kind === 'task' || destination.kind === 'task-deleted' || destination.kind === 'room' || typeof n.taskId === 'string')
-                sections.tasks++;
-            else if (destination.kind === 'contact' || n.taskId === null)
+            // Mission-associated rows (task and room targets, or any row carrying a taskId string,
+            // including agent rows) count under chats with contacts; `tasks` stays 0 for wire
+            // compatibility. Agent rows without a taskId field keep their prior grouping: no section.
+            if (destination.kind === 'task' || destination.kind === 'task-deleted' || destination.kind === 'room' || typeof n.taskId === 'string'
+                || destination.kind === 'contact' || n.taskId === null)
                 sections.chats++;
             const conversation = chatTarget(destination);
             if (!conversation)
@@ -248,7 +400,7 @@ export class Store {
             for (const n of s.notifications)
                 if (n.userId === userId && chosen.has(n.id))
                     n.readAt ??= at;
-            s.jobs = s.jobs.filter(j => !s.notifications.find(n => n.id === j.notificationId)?.readAt);
+            s.jobs = s.jobs.filter(j => !cancelled(s.notifications.find(n => n.id === j.notificationId)));
         });
     }
     /** Delete only this user's confirmed stale entries and their pending deliveries. */
@@ -272,7 +424,10 @@ export class Store {
         })()).map(n => n.id);
         return this.deleteNotifications(userId, ids);
     }
-    produce(value) {
+    /** `pushOnly` false is an explicit inbox delivery; omitted is a legacy producer that did not state one. */
+    produce(input) {
+        const { pushOnly: explicit, ...rest } = input;
+        let value = { ...rest, ...(explicit ? { pushOnly: true } : {}) };
         const destination = target(value.target);
         if ('url' in value)
             throw new HttpError(400, 'unexpected field');
@@ -281,31 +436,164 @@ export class Store {
             throw new HttpError(400, 'invalid task identity');
         if ((destination.kind === 'task' || destination.kind === 'task-deleted' || destination.kind === 'room') && value.taskId !== undefined && value.taskId !== destination.taskId)
             throw new HttpError(400, 'conflicting task identity');
+        if (explicit !== undefined && typeof explicit !== 'boolean')
+            throw new HttpError(400, 'invalid delivery');
+        // A trusted typed task event is always push-only: without a stated policy it is admitted as if it had stated it, and
+        // an explicit inbox request is refused (the open-time repair would otherwise rewrite that row).
+        const lifecycle = lifecycleEvent(this.lifecycleProducers, value);
+        if (lifecycle && explicit === false)
+            throw new HttpError(400, 'task events from the mission producer are push-only');
+        const mode = lifecycle ? true : explicit;
+        if (mode)
+            value = { ...value, pushOnly: true };
         const receipt = this.state.receipts.find(r => r.userId === value.userId && r.source === value.source && r.eventId === value.eventId);
+        // An admitted event keeps its delivery policy: a retry may omit it (legacy producers) but never change it.
+        const policy = (r) => mode !== undefined && mode !== (r.pushOnly === true)
+            ? (() => { throw new HttpError(409, 'event id reused'); })() : undefined;
         if (receipt && receipt.fingerprint !== fingerprint(value))
             throw new HttpError(409, 'event id reused');
         const previous = this.state.notifications.find(n => n.userId === value.userId && n.source === value.source && n.eventId === value.eventId);
         if (previous) {
             if (fingerprint(previous) !== fingerprint(value))
                 throw new HttpError(409, 'event id reused');
+            policy(previous);
             return previous;
         }
-        if (receipt)
+        if (receipt) {
+            // An orphan receipt from an earlier producer's inbox admission: this authenticated typed task event has the same
+            // fingerprint (target, task and content), which proves the receipt was that event. Record its push-only policy.
+            if (lifecycle && !receipt.pushOnly) {
+                this.commit(s => { s.receipts = s.receipts.map(r => sameReceipt(r, receipt) ? { ...r, pushOnly: true } : r); });
+                return { id: receipt.id, duplicate: true };
+            }
+            policy(receipt);
             return { id: receipt.id, duplicate: true };
+        }
         // Explicit capacity failure instead of silently evicting unread history or dedupe records.
         if (this.state.receipts.filter(r => r.userId === value.userId).length >= 100_000 || this.state.notifications.filter(n => n.userId === value.userId).length >= 10_000 || this.state.jobs.length >= 20_000)
             throw new HttpError(503, 'notification capacity exceeded');
-        const n = { ...value, id: randomUUID(), createdAt: new Date().toISOString(), createdRevision: this.state.revision + 1, readAt: null };
+        const n = { ...value, id: randomUUID(), createdAt: new Date().toISOString(), createdRevision: this.state.revision + 1,
+            readAt: value.pushOnly ? new Date().toISOString() : null };
+        // A deleted mission or a suppressed own room keeps only the dedupe receipt: no row, no push, no unread.
+        const dropped = this.tombstoned(n) ? 'deleted' : this.suppressed(n) ? 'suppressed' : undefined;
         this.commit(s => {
+            s.receipts.push({ userId: n.userId, source: n.source, eventId: n.eventId, id: n.id, fingerprint: fingerprint(n), ...(n.pushOnly ? { pushOnly: true } : {}) });
+            if (dropped)
+                return;
             s.notifications.push(n);
-            s.receipts.push({ userId: n.userId, source: n.source, eventId: n.eventId, id: n.id, fingerprint: fingerprint(n) });
             if (!s.devices.some(d => d.userId === n.userId))
                 this.recordDelivery(s, { userId: n.userId, notificationId: n.id, at: n.createdAt, outcome: 'no_device', attempt: 0 });
             for (const d of s.devices)
                 if (d.userId === n.userId)
                     s.jobs.push({ id: randomUUID(), notificationId: n.id, deviceId: d.id, attempts: 0, due: Date.now() });
         });
-        return n;
+        return dropped ? { id: n.id, dropped } : n;
+    }
+    /** Rows of a tombstoned mission: its task association or targets, or any proven room of it. */
+    tombstoned(n, missions = this.state.missions) {
+        return missions.some(m => m.userId === n.userId && m.tombstone && owns(m, n));
+    }
+    /** Own mission room messages while the user turned them off. External contacts never match: only proven rooms do. */
+    suppressed(n, state = this.state) {
+        if (state.preferences.find(p => p.userId === n.userId)?.ownMissionRoomMessages !== false)
+            return false;
+        return ownRoom(state, n);
+    }
+    storedPreference(userId) {
+        return structuredClone(this.state.preferences.find(p => p.userId === userId) ?? { userId, ownMissionRoomMessages: true, bootstrap: null });
+    }
+    preference(userId) {
+        const p = this.storedPreference(userId);
+        return { userId, ownMissionRoomMessages: p.ownMissionRoomMessages, missionRoomsReady: !!p.bootstrap?.complete };
+    }
+    /** Notification preference only: OFF marks existing own-room rows read and retires their pushes; conversations are untouched. */
+    setPreference(userId, ownMissionRoomMessages) {
+        const current = this.storedPreference(userId);
+        if (!ownMissionRoomMessages && !current.bootstrap?.complete)
+            throw new HttpError(409, 'mission_rooms_registering');
+        if (current.ownMissionRoomMessages === ownMissionRoomMessages)
+            return this.preference(userId);
+        this.commit(s => {
+            s.preferences = [...s.preferences.filter(p => p.userId !== userId), { ...current, ownMissionRoomMessages }];
+            if (!ownMissionRoomMessages)
+                quiet(s, userId);
+        });
+        return this.preference(userId);
+    }
+    /**
+     * The ownership producer registers its existing mission rooms in numbered runs. A run starts (`complete: false`)
+     * and completes under the same generation; an older generation is stale and a completed run cannot reopen.
+     * OFF can be chosen only after a run completed, so no existing own room is unassociated while OFF.
+     */
+    missionBootstrap(userId, input) {
+        const current = this.storedPreference(userId), run = current.bootstrap;
+        if (run && input.generation < run.generation)
+            throw new HttpError(409, 'stale bootstrap generation');
+        if (run && input.generation === run.generation) {
+            if (run.complete === input.complete)
+                return run;
+            if (run.complete)
+                throw new HttpError(409, 'bootstrap generation already complete');
+        }
+        const bootstrap = { generation: input.generation, complete: input.complete };
+        this.commit(s => { s.preferences = [...s.preferences.filter(p => p.userId !== userId), { ...current, bootstrap }]; });
+        return bootstrap;
+    }
+    /** Proven rooms of one mission. Revisions only advance, rooms are only added, and a tombstone wins. */
+    associateMission(userId, source, value) {
+        // Write boundary: the store admits its own input with the API's parser (400 on invalid, room CIDs canonicalized), so whatever
+        // it commits satisfies the strict reload validation regardless of the caller.
+        const input = associationInput(owner(userId, source, value));
+        const existing = this.state.missions.find(m => m.userId === userId && m.source === source && m.taskId === input.taskId);
+        if (existing?.tombstone)
+            throw new HttpError(409, 'mission deleted');
+        if (existing && existing.revision > input.revision)
+            throw new HttpError(409, 'stale association');
+        const contactIds = [...new Set([...(existing?.contactIds ?? []), ...input.contactIds])];
+        if (existing && existing.revision === input.revision && contactIds.length === existing.contactIds.length)
+            return { contactIds, revision: existing.revision };
+        if (existing && existing.revision === input.revision)
+            throw new HttpError(409, 'conflicting association');
+        if (contactIds.length > MAX_MISSION_ROOMS)
+            throw new HttpError(503, 'mission room capacity exceeded');
+        if (!existing && this.state.missions.filter(m => m.userId === userId).length >= 10_000)
+            throw new HttpError(503, 'mission capacity exceeded');
+        this.commit(s => {
+            s.missions = [...s.missions.filter(m => m !== existing && !(m.userId === userId && m.source === source && m.taskId === input.taskId)),
+                { userId, source, taskId: input.taskId, revision: input.revision, contactIds }];
+            quiet(s, userId);
+        });
+        return { contactIds, revision: input.revision };
+    }
+    /** One durable revision: tombstone (merging newly proven rooms), then remove every matching row and its pushes from any source. */
+    deleteMission(userId, source, value) {
+        const input = deletionInput(owner(userId, source, value));
+        const existing = this.state.missions.find(m => m.userId === userId && m.source === source && m.taskId === input.taskId);
+        const contactIds = [...new Set([...(existing?.contactIds ?? []), ...input.contactIds])];
+        // Refuse rather than truncate: a dropped room could never be cleaned up.
+        if (contactIds.length > MAX_MISSION_ROOMS)
+            throw new HttpError(503, 'mission room capacity exceeded');
+        const mission = { userId, source, taskId: input.taskId, revision: existing?.revision ?? 0, contactIds, tombstone: existing?.tombstone ?? { at: new Date().toISOString() } };
+        const removed = new Set(this.state.notifications.filter(n => n.userId === userId && owns(mission, n)).map(n => n.id));
+        if (existing?.tombstone && existing.contactIds.length === contactIds.length && !removed.size)
+            return { removed: 0 };
+        if (!existing && this.state.missions.filter(m => m.userId === userId).length >= 10_000)
+            throw new HttpError(503, 'mission capacity exceeded');
+        this.commit(s => {
+            s.missions = [...s.missions.filter(m => !(m.userId === userId && m.source === source && m.taskId === input.taskId)), mission];
+            s.notifications = s.notifications.filter(n => !removed.has(n.id));
+            s.jobs = s.jobs.filter(j => !removed.has(j.notificationId));
+        });
+        return { removed: removed.size };
+    }
+    /** Immediately before a provider call: the job, its row and its device as currently persisted, or nothing if no longer deliverable. */
+    dispatchable(jobId) {
+        const j = this.state.jobs.find(j => j.id === jobId);
+        if (!j)
+            return undefined;
+        const notification = this.state.notifications.find(n => n.id === j.notificationId), device = this.state.devices.find(d => d.id === j.deviceId);
+        return { job: structuredClone(j), notification: notification && structuredClone(notification), device: device && structuredClone(device),
+            cancelled: cancelled(notification) };
     }
     due(now) {
         return this.state.jobs.filter(j => j.due <= now).slice(0, 32).map(j => ({ ...j,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/notifications",
-  "version": "0.3.1-nightly.7",
+  "version": "1.0.1",
   "description": "Authenticated web push delivery and shared notification inbox",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",