slotlock 0.6.2 → 0.7.0

package/event-feed.js

@@ -1,8 +1,8 @@
-// The event feed (RFC 0002 P1-5): what changed for a tenant, read by position, and the webhook
-// endpoints it is delivered to. Rows are appended by triggers in the same transaction as the change
-// (ddl.ts, SLOTLOCK_OUTBOX_DDL). These are the store's methods for reading them and for keeping each
-// endpoint's delivery state; webhooks.ts signs and sends.
-import { randomBytes } from 'node:crypto';
+// The event feed: what changed for a tenant, read by position, and the webhook endpoints it is
+// delivered to. Rows are appended by triggers in the changing transaction (ddl.ts,
+// SLOTLOCK_OUTBOX_DDL); webhooks.ts signs and sends.
+import { slotlockPlanReadRefusal } from './plans.js';
+import { createHash, randomBytes } from 'node:crypto';
 /** A transaction on a client, or a savepoint inside the caller's (a tenant's, say). */
 async function inTransaction(sql, callback) {
     return ('begin' in sql ? sql.begin(callback) : sql.savepoint(callback));
@@ -27,9 +27,15 @@ export const SLOTLOCK_CHANGE_TYPES = Object.freeze([
     'coverage.stale',
     'waitlist.offered',
     'waitlist.expired',
+    // A write waiting for a person (approval policies): requested, then granted, declined or expired.
+    'approval.requested',
+    'approval.granted',
+    'approval.declined',
+    'approval.expired',
     'webhook.disabled',
-    // Configuration: what a resource is and how it books, the sources it is read from, where the
-    // feed is delivered and the keys that reach the tenant. Ids and states, never a secret or a URL.
+    // A plan's monthly quota 80% or 100% used (quotas.ts): the metric, the share and the counts.
+    'usage.threshold_reached',
+    // Configuration changes: ids and states, never a secret or a URL.
     'resource.created',
     'resource.updated',
     'resource.archived',
@@ -45,10 +51,9 @@ export const SLOTLOCK_CHANGE_TYPES = Object.freeze([
     'key.revoked',
 ]);
 /**
- * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
- * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
- * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
- * store itself (`library`). Never an address or anything else about a person.
+ * Where a change came from (withTenant's `origin`): an agent protocol (`mcp`, `a2a`), the REST
+ * API's agent routes (`rest`) or application operations (`application`), the dashboard, its
+ * assistant, maintenance, or direct store calls (`library`). Never anything about a person.
  */
 export const SLOTLOCK_CHANGE_ORIGINS = Object.freeze([
     'mcp',
@@ -65,20 +70,16 @@ export function isSlotlockChangeOrigin(value) {
     return typeof value === 'string' && SLOTLOCK_CHANGE_ORIGINS.includes(value);
 }
 /**
- * The digest 0.5.3 named a coverage source by on the feed: `src_` and the first 24 hex digits of
- * sha256(tenant, newline, source). Unkeyed, so anyone who knows the tenant could confirm a guessed
- * source against it; 0.6 names a source by a random id instead (`calendar_coverage.source_id`), and
- * the upgrade uses this only to find the changes 0.5.3 wrote and rename them. `tenant` and `source`
- * are SQL expressions.
+ * The unkeyed digest 0.5.3 named a coverage source by (`src_` + 24 hex of sha256(tenant, newline,
+ * source)); anyone knowing the tenant could confirm a guess. Used only by the upgrade to find and
+ * rename those changes. `tenant` and `source` are SQL expressions.
  */
 export function legacyCoverageSourceDigestSql(tenant, source) {
     return `'src_' || pg_catalog.left(pg_catalog.encode(pg_catalog.sha256(pg_catalog.convert_to(${tenant} || E'\\n' || ${source}, 'UTF8')), 'hex'), 24)`;
 }
 /**
- * 0.5.3 worked out a source's id here: an unkeyed digest of the tenant and the source, which let
- * anyone who saw a change confirm a guessed source. Since 0.6 a source's `source_id` is random and
- * only the database knows it, so this throws (`coverage_source_id_unavailable`) rather than give a
- * digest nothing carries any more.
+ * Throws `coverage_source_id_unavailable`: since 0.6 a source's `source_id` is random and only the
+ * database knows it (0.5.3's unkeyed digest let anyone confirm a guessed source).
  *
  * @deprecated Read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`). It may
  * be removed in 0.7.0.
@@ -89,17 +90,15 @@ export function slotlockCoverageSourceId(_tenantRef, _source) {
 /** What a coverage source's `source_id` is: `src_` and 32 random hex digits. */
 const SLOTLOCK_COVERAGE_SOURCE_ID = /^src_[0-9a-f]{32}$/;
 /**
- * The `source_id` of a `coverage.*` change whose source could not be named any more: one an
- * earlier release recorded by the source itself (or by its 0.5.3 digest) after the source was
- * deleted, or one not yet renamed when it is read.
+ * The `source_id` of a `coverage.*` change whose source can no longer be named: an earlier
+ * release's change whose source was deleted, or one not yet renamed.
  */
 const SLOTLOCK_REDACTED_SOURCE_ID = 'src_redacted';
 /**
- * A change's subject and data as the feed serves them. A `coverage.*` change never carries its
- * source (`source`) or the error read from it (`last_error`, which can quote it), and is named by a
- * `source_id` of this release or `src_redacted`: an earlier release wrote both, and the upgrade
- * renames those rows in batches after it commits, so a row it has not reached yet, or one an
- * earlier release's server writes during a rolling upgrade, is served redacted.
+ * A change's subject and data as the feed serves them. A `coverage.*` change never carries `source`
+ * or `last_error` (which can quote it), and is named by a current `source_id` or `src_redacted`:
+ * rows an earlier release wrote are renamed in batches after upgrade, so one not reached yet is
+ * served redacted.
  */
 export function slotlockServedChange(type, subject, data) {
     if (!type.startsWith('coverage.'))
@@ -111,9 +110,13 @@ export function slotlockServedChange(type, subject, data) {
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
-export const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 10;
+export const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 25;
 /** After this long failing, an endpoint is disabled and the feed says so (`webhook.disabled`). */
 export const SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS = 24 * 60 * 60 * 1_000;
+/** Resources one webhook endpoint's filter may name. */
+export const SLOTLOCK_WEBHOOK_FILTER_RESOURCES = 100;
+/** Pools, locations or groups one webhook endpoint's filter may name, of each. */
+export const SLOTLOCK_WEBHOOK_FILTER_REFS = 20;
 function encodePosition(position) {
     return Buffer.from(`2:${position.txid}:${position.id}:${position.at}`).toString('base64url');
 }
@@ -136,14 +139,14 @@ function toChange(row) {
         ...slotlockServedChange(row.type, row.subject, row.data),
         occurredAt: row.occurred_at,
         actor: row.actor,
-        // One a later release added, read by this one: unknown here, so unrecorded, not a failed page.
+        // An origin a later release added: unrecorded here, not a failed page.
         origin: isSlotlockChangeOrigin(row.origin) ? row.origin : null,
         keyId: row.key_id,
         position: encodePosition({ txid: row.txid, id: row.id, at: row.occurred_at.getTime() }),
     };
 }
 function toEndpoint(row) {
-    return {
+    const endpoint = {
         id: row.id,
         url: row.url,
         eventTypes: row.event_types,
@@ -155,9 +158,85 @@ function toEndpoint(row) {
         disabledAt: row.disabled_at,
         disabledReason: row.disabled_reason,
     };
+    const filter = {};
+    if (row.filter_resource_ids)
+        filter.resourceIds = row.filter_resource_ids;
+    if (row.filter_pools)
+        filter.pools = row.filter_pools;
+    if (row.filter_locations)
+        filter.locations = row.filter_locations;
+    if (row.filter_groups)
+        filter.groups = row.filter_groups;
+    if (Object.keys(filter).length > 0)
+        endpoint.filter = filter;
+    return endpoint;
 }
 const ENDPOINT_COLUMNS = (sql) => sql `id, url, event_types, created_at, attempts, failing_since, last_status, last_error,
-      disabled_at, disabled_reason`;
+      disabled_at, disabled_reason, filter_resource_ids::text[], filter_pools, filter_locations,
+      filter_groups`;
+/** A pool's, location's or group's reference. */
+const GROUPING_REF = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+/**
+ * A webhook filter as it is stored, each list without repeats, or null when one is out of bounds.
+ * An empty filter, or empty lists, filter nothing.
+ */
+function parseWebhookFilter(filter) {
+    const list = (values, max, valid) => {
+        if (values === undefined)
+            return null;
+        if (!Array.isArray(values))
+            return false;
+        const kept = [...new Set(values)];
+        if (kept.length === 0)
+            return null;
+        if (kept.length > max || !kept.every((value) => typeof value === 'string' && valid(value)))
+            return false;
+        return kept.sort();
+    };
+    const resourceIds = list(filter?.resourceIds, SLOTLOCK_WEBHOOK_FILTER_RESOURCES, (value) => UUID.test(value));
+    const pools = list(filter?.pools, SLOTLOCK_WEBHOOK_FILTER_REFS, (value) => GROUPING_REF.test(value));
+    const locations = list(filter?.locations, SLOTLOCK_WEBHOOK_FILTER_REFS, (value) => GROUPING_REF.test(value));
+    const groups = list(filter?.groups, SLOTLOCK_WEBHOOK_FILTER_REFS, (value) => GROUPING_REF.test(value));
+    if (resourceIds === false || pools === false || locations === false || groups === false)
+        return null;
+    return {
+        resourceIds: resourceIds?.map((id) => id.toLowerCase()) ?? null,
+        pools,
+        locations,
+        groups,
+    };
+}
+/**
+ * Whether a change (`change`, a row of slotlock.outbox) passes an endpoint's filter (`due`, a row of
+ * slotlock.webhook_endpoints): no filter, or a resource it names, or one in a pool, at a location
+ * (or a location in it) or in a group it names, as the resource is now; or a change to a resource
+ * that says it was in one (resource.created, resource.deleted, or resource.updated's `before`),
+ * so an endpoint also learns of a resource deleted, or moved out of what it follows.
+ */
+const FILTER_MATCH = `(
+  (due.filter_resource_ids IS NULL AND due.filter_pools IS NULL
+   AND due.filter_locations IS NULL AND due.filter_groups IS NULL)
+  OR change.resource_id = ANY (due.filter_resource_ids)
+  OR EXISTS (
+    SELECT 1 FROM slotlock.resources held
+     WHERE held.tenant_ref = change.tenant_ref AND held.id = change.resource_id
+       AND (held.pool_ref = ANY (due.filter_pools)
+            OR (held.location_ref IS NOT NULL
+                AND slotlock.location_path(held.tenant_ref, held.location_ref) && due.filter_locations)
+            OR EXISTS (SELECT 1 FROM slotlock.resource_group_members member
+                        WHERE member.tenant_ref = held.tenant_ref AND member.resource_id = held.id
+                          AND member.group_ref = ANY (due.filter_groups))))
+  OR (change.type LIKE 'resource.%' AND (
+       (change.data ->> 'pool') = ANY (due.filter_pools)
+    OR (change.data #>> '{before,pool}') = ANY (due.filter_pools)
+    OR EXISTS (
+         SELECT 1 FROM unnest(ARRAY[change.data ->> 'location', change.data #>> '{before,location}']) was(ref)
+          WHERE was.ref IS NOT NULL
+            AND (was.ref = ANY (due.filter_locations)
+                 OR slotlock.location_path(change.tenant_ref, was.ref) && due.filter_locations))
+    OR (jsonb_typeof(change.data -> 'groups') = 'array' AND (change.data -> 'groups') ?| due.filter_groups)
+    OR (jsonb_typeof(change.data #> '{before,groups}') = 'array'
+        AND (change.data #> '{before,groups}') ?| due.filter_groups))))`;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function isIdentity(value) {
     return typeof value === 'string' && Buffer.byteLength(value) >= 1 && Buffer.byteLength(value) <= 500;
@@ -202,8 +281,7 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const after = params.after === undefined ? null : decodePosition(params.after);
             if (params.after !== undefined && !after)
                 return { ok: false, code: 'invalid_cursor' };
-            // One statement, so the pruned position and the page are read from one snapshot: a prune
-            // that commits meanwhile is either wholly seen or not at all.
+            // One statement, so the pruned position and the page share a snapshot.
             const rows = await sql `
         SELECT mark.txid::text AS pruned_txid, mark.id::text AS pruned_id,
                pg_snapshot_xmin(pg_current_snapshot())::text AS horizon,
@@ -227,9 +305,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const head = rows[0];
             if (!head)
                 throw new Error('slotlock: change page returned no row');
-            // Whichever server pruned it, and however long it keeps changes: reading on could skip one.
-            // A 0.4 cursor also by its date, as 0.4 did: 0.4 pruned by age, not in feed order, so the
-            // mark its changes started at does not cover every one it took.
+            // Pruned by any server: reading on could skip a change. A 0.4 cursor also expires by date,
+            // since 0.4 pruned by age, not feed order.
             if (after &&
                 ((head.pruned_txid !== null &&
                     (BigInt(head.pruned_txid) > BigInt(after.txid) ||
@@ -241,8 +318,8 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             }
             const changes = rows.flatMap((row) => (row.id === null ? [] : [toChange(row)]));
             const last = changes.at(-1);
-            // With nothing new the position stays, dated now: a reader that is up to date stays current.
-            // Before any change, every one still to come is after the oldest transaction still running.
+            // Nothing new: the position stays, dated now. Before any change, every one to come is after
+            // the oldest running transaction.
             const here = after ?? { txid: head.horizon, id: '0', at: 0 };
             return {
                 ok: true,
@@ -279,26 +356,60 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                     !types.every((type) => SLOTLOCK_CHANGE_TYPES.includes(type)))) {
                 return { ok: false, code: 'invalid_event_types' };
             }
+            const filter = parseWebhookFilter(params.filter);
+            if (filter === null)
+                return { ok: false, code: 'invalid_webhook_filter' };
+            const key = params.idempotencyKey;
+            if (key !== undefined && !isIdentity(key))
+                return { ok: false, code: 'invalid_identity' };
+            const payloadHash = key === undefined
+                ? null
+                : createHash('sha256')
+                    .update(JSON.stringify([params.url, types === null ? null : [...types].sort(), filter]))
+                    .digest('hex');
             const secret = `whsec_${randomBytes(32).toString('base64')}`;
             return inTransaction(sql, async (tx) => {
-                // One at a time per tenant, so racing creates stop at the limit.
                 await tx `SELECT pg_advisory_xact_lock(hashtextextended(${`slotlock:webhooks:${params.tenantRef}`}, 0))`;
+                if (key !== undefined) {
+                    // Under the tenant's webhook lock: a retry racing its first finds what the first made.
+                    const [earlier] = await tx `
+            SELECT ${ENDPOINT_COLUMNS(tx)}, secret, payload_hash FROM slotlock.webhook_endpoints
+             WHERE tenant_ref = ${params.tenantRef} AND idempotency_key = ${key}`;
+                    if (earlier) {
+                        if (earlier.payload_hash !== payloadHash)
+                            return { ok: false, code: 'idempotency_conflict' };
+                        return { ok: true, endpoint: toEndpoint(earlier), secret: earlier.secret, replayed: true };
+                    }
+                }
                 const [count] = await tx `
-          SELECT count(*)::int AS count FROM slotlock.webhook_endpoints
-           WHERE tenant_ref = ${params.tenantRef}`;
-                if ((count?.count ?? 0) >= SLOTLOCK_MAX_WEBHOOK_ENDPOINTS) {
-                    return { ok: false, code: 'webhook_limit_reached', limit: SLOTLOCK_MAX_WEBHOOK_ENDPOINTS };
+          SELECT count(*)::int AS count,
+                 (SELECT max_webhook_endpoints FROM slotlock.tenant_plan(${params.tenantRef}::text))
+                   AS planned
+            FROM slotlock.webhook_endpoints
+           WHERE tenant_ref = ${params.tenantRef}`.catch((error) => {
+                    throw slotlockPlanReadRefusal(error);
+                });
+                // The lower of the server's limit and the tenant's plan (plans.ts), when it has one.
+                const limit = Math.min(SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, count?.planned ?? SLOTLOCK_MAX_WEBHOOK_ENDPOINTS);
+                if ((count?.count ?? 0) >= limit) {
+                    return { ok: false, code: 'webhook_limit_reached', limit };
                 }
-                // From now on: every transaction that has not ended yet is at or after this position.
+                // From now on: every transaction not yet ended is at or after this position.
                 const [row] = await tx `
-          INSERT INTO slotlock.webhook_endpoints (tenant_ref, url, secret, event_types, cursor_txid)
+          INSERT INTO slotlock.webhook_endpoints (
+            tenant_ref, url, secret, event_types, cursor_txid,
+            filter_resource_ids, filter_pools, filter_locations, filter_groups,
+            idempotency_key, payload_hash
+          )
           VALUES (${params.tenantRef}, ${params.url}, ${secret}, ${types}::text[],
-                  pg_snapshot_xmin(pg_current_snapshot()))
+                  pg_snapshot_xmin(pg_current_snapshot()),
+                  ${filter.resourceIds}::uuid[], ${filter.pools}::text[], ${filter.locations}::text[],
+                  ${filter.groups}::text[], ${key ?? null}, ${payloadHash})
           RETURNING ${ENDPOINT_COLUMNS(tx)}`;
                 if (!row)
                     throw new Error('slotlock: webhook endpoint insert returned no row');
                 await tx `SELECT slotlock.register_webhook_tenant(${params.tenantRef}::text)`;
-                return { ok: true, endpoint: toEndpoint(row), secret };
+                return { ok: true, endpoint: toEndpoint(row), secret, replayed: false };
             });
         },
         async listWebhookEndpoints(params) {
@@ -323,7 +434,6 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                 const [left] = await tx `
           SELECT count(*)::int AS count FROM slotlock.webhook_endpoints
            WHERE tenant_ref = ${params.tenantRef}`;
-                // The tenant's last endpoint takes it off the list servers deliver for.
                 if ((left?.count ?? 0) === 0) {
                     await tx `SELECT slotlock.unregister_webhook_tenant(${params.tenantRef}::text)`;
                 }
@@ -357,6 +467,32 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             if (!(Number.isSafeInteger(params.batch) && params.batch >= 1 && params.batch <= 100)) {
                 throw new RangeError('Slotlock webhook batch must be 1-100 changes');
             }
+            // An endpoint that takes only some changes (by type or filter) moves past the ones it does
+            // not take, up to the last change that has ended, when none before it is for the endpoint:
+            // else its cursor would stay where it was made, keeping the whole feed from being pruned and
+            // every claim reading it all again. Not one being delivered (leased), nor one waiting to try
+            // again (it has a change for it).
+            await sql `
+        UPDATE slotlock.webhook_endpoints due
+           SET cursor_txid = head.txid, cursor_id = head.id
+          FROM (SELECT change.txid, change.id FROM slotlock.outbox change
+                 WHERE change.tenant_ref = ${params.tenantRef}
+                   AND change.txid < pg_snapshot_xmin(pg_current_snapshot())
+                 ORDER BY change.txid DESC, change.id DESC
+                 LIMIT 1) head
+         WHERE due.tenant_ref = ${params.tenantRef}
+           AND due.disabled_at IS NULL
+           AND (due.lease_until IS NULL OR due.lease_until <= now())
+           AND (due.event_types IS NOT NULL OR due.filter_resource_ids IS NOT NULL OR due.filter_pools IS NOT NULL
+                OR due.filter_locations IS NOT NULL OR due.filter_groups IS NOT NULL)
+           AND (head.txid, head.id) > (due.cursor_txid, due.cursor_id)
+           AND NOT EXISTS (
+             SELECT 1 FROM slotlock.outbox change
+              WHERE change.tenant_ref = due.tenant_ref
+                AND (change.txid, change.id) > (due.cursor_txid, due.cursor_id)
+                AND (change.txid, change.id) <= (head.txid, head.id)
+                AND (due.event_types IS NULL OR change.type = ANY (due.event_types))
+                AND ${sql.unsafe(FILTER_MATCH)})`;
             const endpoints = await sql `
         UPDATE slotlock.webhook_endpoints endpoint
            SET lease_until = now() + make_interval(secs => ${params.leaseMs / 1_000}),
@@ -373,6 +509,7 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                    AND change.txid < pg_snapshot_xmin(pg_current_snapshot())
                    AND (change.txid, change.id) > (due.cursor_txid, due.cursor_id)
                    AND (due.event_types IS NULL OR change.type = ANY (due.event_types))
+                   AND ${sql.unsafe(FILTER_MATCH)}
               )
             FOR UPDATE SKIP LOCKED
          )
@@ -381,14 +518,16 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const claims = [];
             for (const endpoint of endpoints) {
                 const rows = await sql `
-          SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
-               key_id::text
-            FROM slotlock.outbox
-           WHERE tenant_ref = ${params.tenantRef}
-             AND txid < pg_snapshot_xmin(pg_current_snapshot())
-             AND (txid, id) > (${endpoint.cursor_txid}::xid8, ${endpoint.cursor_id}::bigint)
-             AND (${endpoint.event_types}::text[] IS NULL OR type = ANY (${endpoint.event_types}::text[]))
-           ORDER BY txid, id
+          SELECT change.id::text, change.txid::text, change.type, change.resource_id, change.subject,
+                 change.data, change.occurred_at, change.actor, change.origin, change.key_id::text
+            FROM slotlock.outbox change, slotlock.webhook_endpoints due
+           WHERE due.id = ${endpoint.id}::uuid
+             AND change.tenant_ref = ${params.tenantRef}
+             AND change.txid < pg_snapshot_xmin(pg_current_snapshot())
+             AND (change.txid, change.id) > (${endpoint.cursor_txid}::xid8, ${endpoint.cursor_id}::bigint)
+             AND (${endpoint.event_types}::text[] IS NULL OR change.type = ANY (${endpoint.event_types}::text[]))
+             AND ${sql.unsafe(FILTER_MATCH)}
+           ORDER BY change.txid, change.id
            LIMIT ${params.batch}`;
                 claims.push({
                     endpoint: { id: endpoint.id, url: endpoint.url, secret: endpoint.secret, attempts: endpoint.attempts },
@@ -443,13 +582,12 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
              AND lease_token = ${params.leaseToken}::uuid
            RETURNING disabled_at IS NOT NULL AS disabled`;
                 if (settled?.disabled) {
-                    // The tenant hears of it on the feed, which every reader and other endpoint sees.
                     await tx `
             INSERT INTO slotlock.outbox (tenant_ref, type, subject, data)
             VALUES (${params.tenantRef}, 'webhook.disabled', ${params.endpointId},
                     ${tx.json({
-                        // The id alone: the feed goes to the tenant's other endpoints, and a URL can
-                        // carry a token.
+                        // The id alone: the feed reaches other endpoints, and a URL can carry a
+                        // token.
                         id: params.endpointId,
                         reason: failure?.gone === true ? 'gone' : 'failing',
                         last_status: failure?.status ?? null,
@@ -493,10 +631,9 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
         async pruneChanges(params) {
             if (!isIdentity(params.tenantRef))
                 throw identityError();
-            // Oldest first in feed order, and only up to the first change kept: a change still within the
-            // retention, one an enabled webhook has still to receive, or one of a transaction later than
-            // the oldest still running. So every change kept is after every change pruned (the trigger
-            // on the feed records how far), and a reader starting over reads on past the gap.
+            // Oldest first in feed order, and only up to the first change kept (within retention, still
+            // owed to an enabled webhook, or later than the oldest running transaction), so every kept
+            // change is after every pruned one and a reader starting over reads past the gap.
             const rows = await sql `
         WITH head AS MATERIALIZED (
           SELECT outbox.id, outbox.txid,

package/event-schema.js

@@ -1,22 +1,19 @@
-// A calendar event as the event tools return it, and as the application API returns any of a
-// tenant's events. Its own module because both the agent server and the application API describe
-// events with it, and the application API imports nothing from the agent server at runtime (the
-// agent server imports it, so the reverse would be a cycle).
+// A calendar event as the event tools and the application API return it. Its own module so the
+// application API need not import the agent server at runtime (that would be a cycle).
 import { z } from 'zod';
 const DATE_TIME = z.string().datetime({ offset: true });
 const RESOURCE_ID = z.string().trim().min(1).max(200);
 const EVENT_ID = z.string().trim().min(1).max(500);
 const REVISION = z.number().int().positive();
-// Output bounds mirror the trusted store's byte ceilings. A value admitted by a UTF-8 byte
-// ceiling can never exceed that many UTF-16 code units, so every valid stored/provider event is
-// serializable without truncating recurrence semantics or calendar identities.
+// Output bounds mirror the store's UTF-8 byte ceilings, which never exceed as many UTF-16 code
+// units, so every stored event serializes untruncated.
 const TRUSTED_SUMMARY_OUTPUT_MAX = 4_096;
 const TRUSTED_TEXT_OUTPUT_MAX = 16_384;
 const TRUSTED_PERSON_NAME_OUTPUT_MAX = 1_024;
 const TRUSTED_RECURRENCE_EXCEPTION_OUTPUT_MAX = 1_000;
 const TRUSTED_REMINDER_MINUTES_OUTPUT_MAX = 366 * 24 * 60;
-// The grammar the store keeps an address in (normalizeEmail in sync.ts), so every stored one can be
-// returned: an address from an imported feed need not be one z.email() takes (ops@localhost).
+// The grammar the store keeps an address in (sync.ts normalizeEmail): an imported address need not
+// pass z.email() (ops@localhost).
 const STORED_ADDRESS = z
     .string()
     .min(3)

package/hooks.d.ts

@@ -1,7 +1,5 @@
 /**
- * Let a hook's promise fail unseen. `onEvent` and `onError` are typed as returning nothing, but an
- * async one returns a promise, and its rejection, left alone, is an unhandled rejection: Node ends
- * the process on one by default. A hook that throws is caught where it is called; this is the same
- * for one that rejects.
+ * Let a hook's promise fail unseen: an async `onEvent` or `onError` returns a promise whose
+ * rejection would be unhandled, which ends a Node process by default.
  */
 export declare function ignoreRejection(result: unknown): void;

package/hooks.js

@@ -1,8 +1,6 @@
 /**
- * Let a hook's promise fail unseen. `onEvent` and `onError` are typed as returning nothing, but an
- * async one returns a promise, and its rejection, left alone, is an unhandled rejection: Node ends
- * the process on one by default. A hook that throws is caught where it is called; this is the same
- * for one that rejects.
+ * Let a hook's promise fail unseen: an async `onEvent` or `onError` returns a promise whose
+ * rejection would be unhandled, which ends a Node process by default.
  */
 export function ignoreRejection(result) {
     if ((typeof result === 'object' || typeof result === 'function') &&

package/ical-worker-thread.js

@@ -1,5 +1,5 @@
-// One worker of createICalendarWorkerPool: reads the feeds it is sent with the ordinary parsers and
-// posts back what they return, or the code of the CalendarContractError they throw.
+// One worker of createICalendarWorkerPool: runs the ordinary parsers and posts back their result or
+// CalendarContractError code.
 import { parentPort } from 'node:worker_threads';
 import { CalendarContractError, CalendarExpansionLimitError, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, } from './sync.js';
 const port = parentPort;
@@ -16,8 +16,7 @@ port.on('message', (request) => {
         reply = { id: request.id, ok: true, value };
     }
     catch (error) {
-        // The parsers turn every failure into a CalendarContractError; anything else is a fault, and
-        // ends this worker so the pool reports it.
+        // Anything but a CalendarContractError is a fault: end this worker so the pool reports it.
         if (!(error instanceof CalendarContractError))
             throw error;
         reply = {

package/ical-worker.d.ts

@@ -28,9 +28,9 @@ export interface ICalendarWorkerPoolOptions {
     /** Workers that may run at once, 1-64. Defaults to 2. */
     size?: number;
     /**
-     * How long one parse may run on its worker, in ms, before the worker is stopped and the feed
-     * refused (CalendarExpansionLimitError), 100-60,000. Defaults to 3,000: several times what the
-     * parser's step budget takes, with room for a new worker to start.
+     * How long one parse may run, in ms (100-60,000), before its worker is stopped and the feed
+     * refused (CalendarExpansionLimitError). Defaults to 3,000: several times the parser's step
+     * budget, with room for a worker to start.
      */
     deadlineMs?: number;
     /** Parses that may wait for a worker, 0-10,000; more are refused at once. Defaults to 64. */
@@ -38,8 +38,8 @@ export interface ICalendarWorkerPoolOptions {
     /** The heap one worker may use, in MB, 16-4,096. Defaults to 128. */
     maxHeapMb?: number;
     /**
-     * The module each worker runs. Defaults to `ical-worker-thread.js` beside this module, which the
-     * built package ships; Slotlock's own TypeScript sources cannot start it (tests pass a stand-in).
+     * The module each worker runs. Defaults to the built `ical-worker-thread.js` beside this module;
+     * Slotlock's TypeScript sources cannot start it (tests pass a stand-in).
      */
     entry?: URL;
 }
@@ -64,11 +64,9 @@ export declare class ICalendarWorkerPoolClosedError extends Error {
     constructor();
 }
 /**
- * A pool of worker threads that read untrusted iCalendar for the calling thread. Results and
- * errors are those of `parseICalendarChanges`, `parseICalendarFeed` and
- * `parseTrustedICalendarEvents` (the same
- * `CalendarContractError` codes), plus CalendarExpansionLimitError when a worker passes its
- * deadline or its heap, ICalendarWorkerBusyError when the queue is full, and
+ * A pool of worker threads reading untrusted iCalendar for the calling thread. Results and errors
+ * are the parsers' (same `CalendarContractError` codes), plus CalendarExpansionLimitError past a
+ * worker's deadline or heap, ICalendarWorkerBusyError when the queue is full, and
  * ICalendarWorkerPoolClosedError after `close()`. Idle workers do not keep the process alive.
  */
 export declare function createICalendarWorkerPool(options?: ICalendarWorkerPoolOptions): ICalendarWorkerPool;

package/ical-worker.js

@@ -30,11 +30,9 @@ function workerFailure(error) {
     return new Error('slotlock: an iCalendar worker failed', { cause: error });
 }
 /**
- * A pool of worker threads that read untrusted iCalendar for the calling thread. Results and
- * errors are those of `parseICalendarChanges`, `parseICalendarFeed` and
- * `parseTrustedICalendarEvents` (the same
- * `CalendarContractError` codes), plus CalendarExpansionLimitError when a worker passes its
- * deadline or its heap, ICalendarWorkerBusyError when the queue is full, and
+ * A pool of worker threads reading untrusted iCalendar for the calling thread. Results and errors
+ * are the parsers' (same `CalendarContractError` codes), plus CalendarExpansionLimitError past a
+ * worker's deadline or heap, ICalendarWorkerBusyError when the queue is full, and
  * ICalendarWorkerPoolClosedError after `close()`. Idle workers do not keep the process alive.
  */
 export function createICalendarWorkerPool(options = {}) {
@@ -100,8 +98,8 @@ export function createICalendarWorkerPool(options = {}) {
         nextId += 1;
         slot.id = nextId;
         slot.worker.ref();
-        // Past its deadline the feed is refused and its worker stopped: whatever ical.js is doing,
-        // terminate() ends it, and the next parse gets a new worker.
+        // Past its deadline the feed is refused and terminate() ends the worker, whatever ical.js is
+        // doing.
         slot.timer = setTimeout(() => retire(slot, new CalendarExpansionLimitError()), deadlineMs);
         slot.worker.postMessage({ ...job.request, id: slot.id });
     }
@@ -144,8 +142,8 @@ export function createICalendarWorkerPool(options = {}) {
         WorkerClass ??= (await threads).Worker;
         if (closed)
             throw new ICalendarWorkerPoolClosedError();
-        // After the await: parses that arrived together resume in order, each seeing the queue as the
-        // ones before it left it.
+        // After the await, parses that arrived together resume in order, each seeing the queue as the
+        // ones before left it.
         if (queue.length >= maxQueue && !hasIdleCapacity())
             throw new ICalendarWorkerBusyError();
         return new Promise((resolve, reject) => {