slotlock 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.6.3 - 2026-11-08
+
+### Added
+
+- `SLOTLOCK_TRUSTED_PROXY_SECRET`: with it set, `slotlock serve` believes
+  `SLOTLOCK_TRUSTED_PROXY_HEADER` only on a request whose `X-Slotlock-Proxy-Proof` carries that
+  exact value (compared in constant time), and counts any other by its connection's address. A
+  process that reaches the server without passing the proxy, such as another container on
+  kamal-proxy's network, can then no longer pick its own rate-limit bucket. Unset, nothing changes.
+  The `listening` line says `client_address_proof`.
+
+### Changed
+
+- Site: the landing page's Slotlock Cloud endpoints list only what an agent connects to (MCP, A2A,
+  REST, OpenAPI, the agent card). The dashboard row is gone: people reach it through Sign in.
+
+### Fixed
+
+- `slotlock serve` maintains every tenant with data every hour, not only the ones whose keys it has
+  served since it started: a tenant gone quiet has its expired holds, ended waitlist entries and
+  feed past retention deleted too. Tenants are listed by name in `slotlock.maintenance_tenants`
+  (owner only, filled by triggers as a tenant first writes, and from existing rows when `migrate`
+  creates it); the serving role reads the names through `slotlock.maintenance_tenants(text)` and
+  maintains each in its own tenant context. Run `slotlock migrate`.
+
+## 0.6.2 - 2026-11-08
+
+### Changed
+
+- Dashboard: pages use the width of a wide screen, up to 1600px, and centre past it, instead of
+  stopping at 1200px against the sidebar with empty space to their right.
+- SECURITY.md: the hosted service is open, and security research on it is welcome against your own
+  account, within the rules it gives (no load testing, no other accounts' data).
+
 ## 0.6.1 - 2026-11-08
 
 ### Changed

package/README.md

@@ -86,7 +86,11 @@ docker compose exec slotlock slotlock resource add vehicle-42 --timezone Europe/
   when such a field arrives without the setting. Behind two proxies, such as Cloudflare and then
   kamal-proxy, name the first one's field: the server reads the last address of a list field such
   as `X-Forwarded-For`, which the second proxy writes as Cloudflare's. A client can send that field
-  itself, so let nothing reach the server except through the proxy.
+  itself, so let nothing reach the server except through the proxy. Where something else can reach
+  it (another container on kamal-proxy's network), also set `SLOTLOCK_TRUSTED_PROXY_SECRET` and have
+  the proxy set `X-Slotlock-Proxy-Proof` to it on every request (a Cloudflare request header
+  transform rule): the field is then believed only beside that exact value, and any other request
+  is counted by its connection's address.
 - The server also bounds what one tenant may store, whichever key, agent or application writes
   it: 10,000 holds, and 100,000 each of bookings, calendar events and coverage rows, counted as
   the store's `tenantLimits` count them, besides 10,000 resources. A write past one answers 409
@@ -395,9 +399,10 @@ this one and read its session secret, which signs in as any tenant.
 - With organizations, set `SLOTLOCK_DASHBOARD_ORGS` on both the Worker and the server: the server
   takes an organization's keys only while its own list names it, whether or not it serves the
   dashboard.
-- The server checks a dashboard tenant against `SLOTLOCK_DASHBOARD_USERS` only when it serves the
-  dashboard itself. With the dashboard on Workers, removing a person from the Worker's list signs
-  them out of the dashboard; to stop their keys, revoke them or erase the tenant.
+- Set `SLOTLOCK_DASHBOARD_USERS` on both the Worker and the server too: the server takes a person's
+  keys only while its own list allows them, whether or not it serves the dashboard, so removing a
+  person from both lists signs them out and stops their keys. A server without it takes every
+  person's keys.
 - A missing or weak secret makes the Worker answer 503 and log which variable, never its value.
 
 ## Connect an MCP client
@@ -1527,8 +1532,10 @@ a 12h/24h switch.
 Every tenant needs maintenance at least daily: it extends recurring events to the rolling horizon
 and prunes what the retention window no longer needs, which is what returns agent quota.
 
-- `slotlock serve` maintains `SLOTLOCK_TENANT` when it starts and every tenant whose key it serves,
-  then each hourly, one tenant at a time. It logs a `maintenance` line with counts.
+- `slotlock serve` maintains `SLOTLOCK_TENANT` and every tenant with data when it starts (whether
+  or not its keys call), then each hourly, one tenant at a time. It logs a `maintenance` line with
+  counts. It finds the tenants through `slotlock.maintenance_tenants(text)`, which lists names
+  only; each pass runs in its own tenant's context, under row-level security.
 - `slotlock maintain` runs one tenant's maintenance now, for cron or after a bulk import. An admin
   key can call `POST /v1/maintenance`.
 - Each pass holds a per-tenant PostgreSQL advisory lock, so servers and cron jobs never repeat each

package/SECURITY.md

@@ -24,10 +24,21 @@ are published as advisories at <https://github.com/PILOTAAI/slotlock/security/ad
 
 ## Hosted Slotlock
 
-The hosted service is not open; self-hosting is the only supported path today. Do not test
-`slotlock-api.pylota.io` or `app.slotlock.pylota.io`: they are not in scope until this section
-says the service is open and gives the rules for testing it. Test Slotlock by running it yourself,
-and report what you find as above.
+The hosted service is open: any GitHub account can sign in at
+<https://app.slotlock.pylota.io/dashboard> and use `https://slotlock-api.pylota.io` with its own
+keys. Self-hosting stays fully supported. Security research on the hosted service is welcome within
+these rules:
+
+- Test only against an account you signed in with yourself, and only with its own keys. Stop as
+  soon as you reach another account's data, keep none of it, and report it.
+- No traffic meant to slow or stop the service: no floods, load tests, or recurrence rules written
+  to expand without end. A request over a limit gets `429`; do not try to get around the limits.
+  Run Slotlock yourself to load test it.
+- No social engineering, and no attacks on Pylota's people, offices, GitHub, Cloudflare, or other
+  providers.
+- Report privately as above, never in a public issue, and give us time to fix it before disclosure.
+
+The [Acceptable Use Policy](ACCEPTABLE-USE.md) permits research within these rules. Abuse of the service by others goes to [abuse@pylota.io](mailto:abuse@pylota.io).
 
 ## Security model
 

package/agent-server.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { SLOTLOCK_MCP_APPS_EXTENSION, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, clientSupportsSlotlockMcpApp, } from './mcp-app.js';
 import { MCP_META_PROTOCOL_VERSION, MCP_META_SERVER_INFO, MCP_META_SUBSCRIPTION_ID, MCP_MISSING_REQUIRED_CLIENT_CAPABILITY, canonicalJson, checkModernMcpRequest, isRecord, openMcpEventStream, openRequestState, principalTag, sealRequestState, sha256Hex, stateSecrets, traceContextFrom, } from './mcp-modern.js';
 import { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, slotlockApplicationOperation, } from './application-api.js';
-import { createSlotlockChangeReaders, } from './change-watch.js';
+import { createSlotlockChangeReaders, unref, } from './change-watch.js';
 import { SLOTLOCK_EVENT_OUTPUT as EVENT } from './event-schema.js';
 import { ignoreRejection } from './hooks.js';
 import { slotlockPackageVersion } from './package-version.js';
@@ -1539,10 +1539,6 @@ function parseSubscriptionFilter(value) {
     return { ok: true, resourceIds };
 }
 /** A timer that does not by itself keep a Node process alive (a no-op on other runtimes). */
-function unref(timer) {
-    timer.unref?.();
-    return timer;
-}
 /** Natural-language guidance `server/discover` gives the model on how to use these tools well. */
 const SLOTLOCK_MCP_INSTRUCTIONS = [
     'Slotlock is a tenant-isolated resource calendar (vehicles, rooms, equipment).',

package/agent-store-backend.d.ts

@@ -27,9 +27,8 @@ export declare function projectSlotlockCalendarEvent(event: SlotlockCalendarEven
 export declare function slotlockAgentErrorStatus(code: string): 400 | 404 | 409 | 429;
 /**
  * The store's change feed for live updates (`subscriptions.changes`): each tenant's changes read
- * under its row-level security, one indexed query per read. Readers poll it (change-watch.ts:
- * every `SLOTLOCK_FEED_BUSY_MS` after a read that found changes, backing off to
- * `SLOTLOCK_FEED_IDLE_MS`); `sql` is the store's client, used for the feed's head.
+ * under its RLS, one indexed query per read. Readers poll it (change-watch.ts); `sql` is the
+ * store's client, used for the feed's head.
  */
 export declare function createSlotlockStoreChangeSource(store: SlotlockStore, sql: Sql): SlotlockAgentChangeSource;
 /** Bind the protocol server to the production store without giving a request control of tenancy. */
@@ -50,8 +49,8 @@ export interface SlotlockStoreApplicationBackendOptions {
     tenantErasure?: boolean;
 }
 /**
- * Serve the application API (application-api.ts) from the production store, in the principal's
- * tenant. Every resource an operation names must be the tenant's, or it is not found; holds are
- * reservations under the tenant's row-level security, so another tenant's hold is not found either.
+ * Serve the application API (application-api.ts) from the store in the principal's tenant. Every
+ * resource named must be the tenant's, or it is not found; holds are under the tenant's RLS, so
+ * another tenant's is not found either.
  */
 export declare function createSlotlockStoreApplicationBackend(store: SlotlockStore, options?: SlotlockStoreApplicationBackendOptions): SlotlockApplicationBackend;

package/agent-store-backend.js

@@ -10,13 +10,12 @@ import { calendarEventRollingHorizon, } from './store.js';
 import { maintainSlotlockTenant } from './maintenance.js';
 import { parseAvailabilityRules } from './weekly-hours.js';
 /**
- * A write runs under READ COMMITTED whatever the role's default: a store given tenant limits (as
- * `slotlock serve`'s is) counts it against them under the tenant's lock, which needs that level,
- * and refuses it otherwise.
+ * Writes run under READ COMMITTED whatever the role's default: tenant limits are counted under a
+ * lock that needs that level.
  */
 const WRITE = { isolation: 'read committed' };
-// The UUIDs withTenant takes as a keyId (versions 1-5, as Slotlock's keys are): any other a custom
-// authenticator's principal carries is left out, not refused.
+// The UUIDs withTenant takes as a keyId (versions 1-5); any other from a custom authenticator is
+// left out, not refused.
 const KEY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 /** Who a call's changes are recorded as in the history: the principal's subject, kept short. */
 function actorOf(context) {
@@ -41,7 +40,6 @@ async function withTenant(store, context, callback, options) {
             signal: context.signal,
             ...(actor !== undefined ? { actor } : {}),
             ...(context.origin !== undefined ? { origin: context.origin } : {}),
-            // An authenticator's own principal may carry something else there: then it is left out.
             ...(typeof keyId === 'string' && KEY_ID.test(keyId) ? { keyId } : {}),
         });
     }
@@ -60,22 +58,18 @@ async function withTenant(store, context, callback, options) {
     return value;
 }
 /**
- * Busy intervals one free/busy read or search may gather across all the resources it names: as many
- * as the store reads for one resource. Without it, a request naming 100 resources at that limit, or
- * one resource 100 times, did 100 times the work of one.
+ * Busy intervals one free/busy read or search may gather across all its resources: as many as the
+ * store reads for one, so naming many resources cannot multiply the work.
  */
 const MAX_REQUEST_BUSY_INTERVALS = 10_000;
 /**
- * Bookable windows one search may expand from its resources' availability rules in all: five
- * resources of 50 daily rules over a year, or a hundred of two. Without it, a search of 100 such
- * resources over a year expanded 1.8 million windows and held the process for seven seconds.
+ * Bookable windows one search may expand from its resources' rules in all (five resources of 50
+ * daily rules over a year, or a hundred of two), so a broad search cannot hold the process.
  */
 const MAX_REQUEST_RULE_WINDOWS = 100_000;
-/** The resources a request names, each once, in the order first named. */
 function distinctResourceIds(input) {
     return [...new Set(input.resource_ids)];
 }
-/** Counts a request's busy intervals against MAX_REQUEST_BUSY_INTERVALS, refusing past it. */
 function busyBudget() {
     let left = MAX_REQUEST_BUSY_INTERVALS;
     return (intervals) => {
@@ -169,12 +163,12 @@ function agentOwnerRef(context) {
         .digest('hex')}`;
 }
 function agentExternalRef(context, idempotencyKey) {
-    // This format is already a stable client-visible identity; keep it unchanged.
+    // Already a stable client-visible identity; keep it unchanged.
     return `agent:${agentPrincipalDigest(context, idempotencyKey)}`;
 }
 function agentCommandIdempotencyKey(context, idempotencyKey) {
-    // Keep the principal in the digest too so this remains safe with older tenant-only stores.
-    // Hashing keeps the authenticated subject and caller's raw retry key out of durable command rows.
+    // The principal stays in the digest so this remains safe with older tenant-only stores; hashing
+    // keeps the subject and raw retry key out of durable rows.
     return `agent-command:${agentPrincipalDigest(context, idempotencyKey)}`;
 }
 function attendeeProjection(attendee) {
@@ -192,8 +186,8 @@ function attendeeProjection(attendee) {
  */
 export function projectSlotlockCalendarEvent(event) {
     return {
-        // External references are the stable tenant-visible identity. Internal UUIDs never become an
-        // unscoped lookup capability at the protocol boundary.
+        // External references are the tenant-visible identity: internal UUIDs never become an unscoped
+        // lookup at the protocol boundary.
         id: event.externalRef,
         resource_id: event.resourceId,
         starts_at: event.start.toISOString(),
@@ -247,19 +241,17 @@ const BOOKING_RULE_CODES = Object.freeze({
     uncertain: 'booking_rule_uncertain',
 });
 function operationError(refusal) {
-    // A broken booking rule is named in the code, which is all an agent's error carries.
     const code = typeof refusal === 'string'
         ? refusal
         : refusal.code === 'booking_rule_violated' && refusal.rule
             ? (BOOKING_RULE_CODES[refusal.rule] ?? refusal.code)
             : refusal.code;
     const status = slotlockAgentErrorStatus(code);
-    // A gone hold is named, so the agent holds again; it covers expired and another holder's alike.
+    // A gone hold (expired or another holder's) is named, so the agent holds again.
     return new SlotlockAgentOperationError(status === 404 && code !== 'hold_not_found' ? 'not_found' : code, status);
 }
 /** Resource and event ids: the UUIDs the store issues and validates. */
 const STORE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-/** A resource page's cursor is the last resource id of the previous page. */
 function parseResourceCursor(value) {
     if (value === undefined)
         return undefined;
@@ -299,12 +291,10 @@ function page(rows, limit) {
     return { shown, next: rows.length > limit && last ? encodeEventCursor(last) : null };
 }
 /**
- * The caller's resource with this id, or `resource_not_found`. The tools accept any id an agent may
- * send (an external reference such as `vehicle-42`, the nil UUID, a version 7 UUID). The store
- * issues version 4 UUIDs (gen_random_uuid) and refuses an id that is not a version 1 to 5 UUID as an
- * invalid identity, so such an id names no resource: it is not found, like a well-formed id that
- * names nothing or another tenant's resource. With `visibility`, a resource of the other is not
- * found either: agents ask for `shared`, so a private resource is invisible to them.
+ * The caller's resource with this id, or `resource_not_found`. Agents may send any id; one that is
+ * not a store-issued (v1-5) UUID names no resource and is not found, like another tenant's. With
+ * `visibility`, a resource of the other visibility is not found either, so private ones are
+ * invisible to agents.
  */
 async function requireResource(tenantStore, tenantRef, resourceId, visibility) {
     if (!STORE_ID_PATTERN.test(resourceId)) {
@@ -325,9 +315,8 @@ function requireAgentResource(tenantStore, tenantRef, resourceId) {
 }
 /**
  * The store's change feed for live updates (`subscriptions.changes`): each tenant's changes read
- * under its row-level security, one indexed query per read. Readers poll it (change-watch.ts:
- * every `SLOTLOCK_FEED_BUSY_MS` after a read that found changes, backing off to
- * `SLOTLOCK_FEED_IDLE_MS`); `sql` is the store's client, used for the feed's head.
+ * under its RLS, one indexed query per read. Readers poll it (change-watch.ts); `sql` is the
+ * store's client, used for the feed's head.
  */
 export function createSlotlockStoreChangeSource(store, sql) {
     return {
@@ -433,8 +422,8 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 const members = await tenantStore.listPoolMembers({ tenantRef, pool: input.pool, visibility: 'shared' });
                 if (members.length === 0)
                     throw new SlotlockAgentOperationError('pool_not_found', 404);
-                // Each member in turn, each try its own savepoint: a member that is taken or that the
-                // booking's rules refuse is passed over; the exclusion constraint still decides each one.
+                // Each member in turn, each in its own savepoint: one taken or refused by its rules is
+                // passed over; the exclusion constraint still decides.
                 for (const member of members) {
                     const result = await put(member.id);
                     if (result.ok)
@@ -457,7 +446,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 const members = await tenantStore.listPoolMembers({ tenantRef, pool, visibility: 'shared' });
                 if (members.length === 0)
                     throw new SlotlockAgentOperationError('pool_not_found', 404);
-                // Each member's busy time, as edges: a count of busy members that rises and falls.
+                // Busy time as edges: a count of busy members that rises and falls.
                 const edges = new Map([
                     [window.start.getTime(), 0],
                     [window.end.getTime(), 0],
@@ -477,9 +466,9 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     charge(freeBusy.busy.length);
                     if (freeBusy.coverage.state !== 'complete')
                         complete = false;
-                    // Not free either where its booking rules refuse a booking: before its notice, past how
-                    // far ahead it books, and, when it enforces them, outside its bookable hours. Its slot
-                    // step is not counted: it moves when a booking may start, not whether the member is free.
+                    // Also not free where its booking rules refuse a booking (notice, advance, enforced
+                    // hours). Its slot step is not counted: it moves when a booking may start, not whether
+                    // the member is free.
                     const rules = member.effectiveBookingRules;
                     const search = bookingSearch({ rules, timezone: member.timezone, window, now });
                     const latestStart = rules?.maxAdvanceDays !== undefined
@@ -524,7 +513,6 @@ export function createSlotlockStoreAgentBackend(store, options) {
                         break;
                     const free = members.length - busy;
                     const last = intervals.at(-1);
-                    // Parts with the same count are one.
                     if (last && last.free === free)
                         last.end = new Date(next).toISOString();
                     else
@@ -540,8 +528,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async bookTogether(context, rawInput) {
             const input = rawInput;
-            // In one order for every bundle, so two over the same resources wait on each other in turn
-            // and never deadlock.
+            // Sorted, so bundles over the same resources lock in one order and never deadlock.
             const resourceIds = [...new Set(input.resource_ids)].sort();
             if (resourceIds.length < 2)
                 throw new SlotlockAgentOperationError('invalid_arguments', 400);
@@ -582,7 +569,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                         materializationWindow: materializationWindow(content),
                         enforceBookingRules: true,
                     });
-                    // Thrown, so the whole transaction rolls back: the events already put go with it.
+                    // Thrown, so the whole transaction rolls back with the events already put.
                     if (!result.ok) {
                         const refusal = operationError(result);
                         throw new SlotlockAgentOperationError(refusal.code, refusal.status, { resource_id: resourceId });
@@ -635,7 +622,6 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 ...(resource.pool !== undefined ? { pool: resource.pool } : {}),
             });
             if (typeof input.pool === 'string') {
-                // A pool's members, in the order a pool booking tries them; at most 100, one page.
                 return withTenant(store, context, async (tenantStore) => ({
                     resources: (await tenantStore.listPoolMembers({
                         tenantRef: context.principal.tenantRef,
@@ -702,8 +688,7 @@ export function createSlotlockStoreAgentBackend(store, options) {
                 let incomplete = false;
                 for (const resourceId of resourceIds) {
                     const resource = await requireAgentResource(tenantStore, context.principal.tenantRef, resourceId);
-                    // Only what a booking made now may take: the resource's booking rules bound the search,
-                    // as they bound the write that follows it.
+                    // The resource's booking rules bound the search, as they bound the write that follows.
                     const search = bookingSearch({
                         rules: resource.effectiveBookingRules,
                         timezone: resource.timezone,
@@ -747,8 +732,8 @@ export function createSlotlockStoreAgentBackend(store, options) {
                         best = { resourceId, interval: candidate };
                     }
                 }
-                // A cross-resource answer is only certain when every requested resource is certain. A slot
-                // from one healthy calendar must not mask a stale provider or recurrence horizon on another.
+                // A cross-resource answer is only certain when every resource is: one healthy calendar must
+                // not mask a stale one.
                 const complete = !incomplete;
                 const certainBest = complete ? best : null;
                 return {
@@ -855,7 +840,6 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
         async updateEvent(context, rawInput) {
             const input = rawInput;
-            // No event is on a resource the store never issued (an external reference, say).
             if (input.expected_resource_id !== undefined &&
                 !STORE_ID_PATTERN.test(input.expected_resource_id)) {
                 throw new SlotlockAgentOperationError('event_not_found', 404);
@@ -929,8 +913,8 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     tenantRef: context.principal.tenantRef,
                     ownerRef: agentOwnerRef(context),
                     externalRef: current.externalRef,
-                    // The caller's fence when it sent one, checked under the event's lock; otherwise the
-                    // resource just read, so a move between that read and the write is not overwritten.
+                    // The caller's fence when sent, checked under the event's lock; otherwise the resource
+                    // just read, so a move in between is not overwritten.
                     expectedResourceId: input.expected_resource_id ?? current.resourceId,
                     resourceId,
                     expectedRevision: input.expected_revision,
@@ -952,7 +936,6 @@ export function createSlotlockStoreAgentBackend(store, options) {
                     throw new SlotlockAgentOperationError('store_inconsistent', 503);
                 return { event: projectSlotlockCalendarEvent(updated), replayed: result.idempotent };
             }, WRITE);
-            // A moved or shortened event may have freed the time it held.
             if (!moved.replayed)
                 await offerFreedTime(store, context.principal.tenantRef);
             return moved;
@@ -990,7 +973,6 @@ export function createSlotlockStoreAgentBackend(store, options) {
         },
     };
 }
-/** A store failure thrown with a `code` the caller may see, or the error itself to report. */
 function storeRefusal(error) {
     const code = error?.code;
     if (typeof code !== 'string')
@@ -1005,7 +987,6 @@ function storeRefusal(error) {
     }
     return error;
 }
-/** The status an application refusal answers with; the resource of another tenant is not found. */
 function applicationRefusal(code) {
     if (code === 'resource_tenant_mismatch') {
         return new SlotlockAgentOperationError('resource_not_found', 404);
@@ -1033,9 +1014,8 @@ function waitlistOutput(entry) {
     };
 }
 /**
- * Offer what a cancel or release just freed to the tenant's waitlist now, rather than at the next
- * maintenance pass. Best effort, after the freeing transaction committed: maintenance offers
- * whatever this misses.
+ * Offer what a cancel or release just freed to the waitlist now. Best effort, after commit:
+ * maintenance offers whatever this misses.
  */
 async function offerFreedTime(store, tenantRef) {
     try {
@@ -1085,7 +1065,6 @@ function rulesInput(value) {
         throw storeRefusal(error);
     }
 }
-/** Booking rules as the application API writes them, snake_case; `null` for none. */
 function bookingRulesOutput(rules) {
     if (!rules)
         return null;
@@ -1166,7 +1145,7 @@ function reservationOutput(reservation) {
         reservation_ref: reservation.externalRef,
         start: reservation.start.toISOString(),
         end: reservation.end.toISOString(),
-        // The store keeps milliseconds; a buffer set in seconds through the library still shows as busy.
+        // The store keeps milliseconds; round up so a sub-minute buffer still shows as busy.
         buffer_after_minutes: Math.ceil(reservation.bufferAfterMs / 60_000),
         revision: reservation.revision,
         source: reservation.source,
@@ -1193,9 +1172,9 @@ function applicationCommandKey(context, idempotencyKey) {
 /** The most busy intervals one slotlock_list_busy answers, as one free/busy request reads. */
 const MAX_LISTED_BUSY = MAX_REQUEST_BUSY_INTERVALS;
 /**
- * Serve the application API (application-api.ts) from the production store, in the principal's
- * tenant. Every resource an operation names must be the tenant's, or it is not found; holds are
- * reservations under the tenant's row-level security, so another tenant's hold is not found either.
+ * Serve the application API (application-api.ts) from the store in the principal's tenant. Every
+ * resource named must be the tenant's, or it is not found; holds are under the tenant's RLS, so
+ * another tenant's is not found either.
  */
 export function createSlotlockStoreApplicationBackend(store, options = {}) {
     const max = options.maxTenantResources;
@@ -1289,7 +1268,6 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
         },
         async deleteResource(context, input) {
             const id = input.resource_id;
-            // An id the store never issues names no resource: there is nothing to delete.
             if (!STORE_ID_PATTERN.test(id))
                 return { deleted: false };
             return withTenant(store, context, async (tenant) => {
@@ -1552,7 +1530,6 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
         },
         async releaseHold(context, input) {
             const id = input.hold_id;
-            // An id that is not one the store issues names no hold: there is nothing to release.
             if (!STORE_ID_PATTERN.test(id))
                 return { released: false };
             const released = await withTenant(store, context, async (tenant) => ({
@@ -1608,7 +1585,6 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                     throw applicationRefusal(result.code);
                 return { reservation: reservationOutput(result.reservation), replayed: result.idempotent };
             }, WRITE);
-            // A move frees the time the booking held.
             if (input.revision > 1 && !put.replayed) {
                 await offerFreedTime(store, tenantOf(context));
             }
@@ -1778,7 +1754,6 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
         async cancelTenantEvent(context, input) {
             const id = input.event_id;
             const expectedResourceId = input.expected_resource_id;
-            // An id the store never issues names no event, and no event is on a resource it never issued.
             if (!STORE_ID_PATTERN.test(id) ||
                 (expectedResourceId !== undefined && !STORE_ID_PATTERN.test(expectedResourceId))) {
                 throw new SlotlockAgentOperationError('event_not_found', 404);
@@ -1820,8 +1795,8 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
                 throw new SlotlockAgentOperationError('invalid_confirmation', 400);
             }
             return withTenant(store, context, async (tenant) => {
-                // Read under the tenant's lock, which a suspension waits for: a suspended tenant's data is
-                // kept for its operator, who erases it (slotlock tenant erase) when they decide to.
+                // Read under the tenant's lock: a suspended tenant's data is kept for its operator to
+                // erase.
                 if (await tenant.isTenantSuspended({ tenantRef: tenantOf(context) })) {
                     throw new SlotlockAgentOperationError('tenant_suspended', 403);
                 }
@@ -1879,7 +1854,6 @@ export function createSlotlockStoreApplicationBackend(store, options = {}) {
         async runMaintenance(context) {
             assertActive(context);
             try {
-                // A caller goes round again while `capped`; when to do so at once is the scheduler's.
                 const { rollPending: _, zoneShifts, staleSources, noShows, waitlistOffers, ...result } = await maintainSlotlockTenant(store, tenantOf(context), {
                     batches,
                     signal: context.signal,

package/api-keys.js

@@ -8,7 +8,7 @@
 // cannot reach another tenant's keys, read a digest, or bring back a revoked, rotated-out or erased
 // key.
 import { createHash, randomBytes } from 'node:crypto';
-import { SlotlockAgentOperationError, } from './agent-server.js';
+import { SlotlockAgentOperationError } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
 import { isSlotlockChangeOrigin } from './event-feed.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };

package/application-api.d.ts

@@ -16,9 +16,9 @@ export interface SlotlockApplicationInvocationContext {
 }
 type Handler = (context: SlotlockApplicationInvocationContext, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /**
- * What serves the application operations. Every method receives the input its operation's schema
- * accepted, and returns what its output schema describes; a refusal is a thrown
- * `SlotlockAgentOperationError`. The tenant is the principal's, never an argument.
+ * What serves the application operations: each method gets schema-valid input and returns what its
+ * output schema describes; refusals throw `SlotlockAgentOperationError`. The tenant is the
+ * principal's, never an argument.
  */
 export interface SlotlockApplicationBackend {
     createResource: Handler;

package/application-api.js

@@ -1,14 +1,13 @@
-// The application API: what an application, rather than an agent, does over HTTP that the TypeScript
-// store does in process. It creates resources and sets their bookable hours, holds and reserves time,
-// records how much of an external calendar it has read, reaches any of the tenant's events whichever
-// key wrote them, erases the tenant when allowed, and runs maintenance. Any language can call it.
+// The application API: what an application, rather than an agent, does over HTTP that the
+// TypeScript store does in process (resources and hours, holds and reservations, coverage, any of
+// the tenant's events, erasure when allowed, maintenance), for any language.
 //
-// The agent server serves these operations as REST under /v1, beside the agent tools, when it is
-// given an `application` backend and `rest` is on, and describes them in the same OpenAPI document.
-// They need the `admin` scope. They are never MCP tools or A2A skills: no agent is offered them.
+// Served as REST under /v1 beside the agent tools when the agent server has an `application`
+// backend and `rest` is on, in the same OpenAPI document. Needs the `admin` scope; never MCP tools
+// or A2A skills, so no agent is offered them.
 //
-// This module holds only the contract (names, schemas, routes); it imports nothing from the agent
-// server at runtime. The store-backed implementation is createSlotlockStoreApplicationBackend.
+// Contract only (names, schemas, routes); nothing from the agent server at runtime. The
+// store-backed implementation is createSlotlockStoreApplicationBackend.
 import { SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_TYPES } from './event-feed.js';
 import { z } from 'zod';
 import { SLOTLOCK_EVENT_OUTPUT } from './event-schema.js';
@@ -58,9 +57,8 @@ const CURSOR = z.string().min(1).max(500);
 const NEXT_CURSOR = z.string().max(500).nullable();
 const VISIBILITY = z.enum(['shared', 'private']);
 /**
- * A retry identity, as the `Idempotency-Key` request header or this field (the same value, if both
- * are sent): the same key with the same request answers what the first did, and with another
- * request is 422 idempotency_conflict.
+ * A retry identity, as the `Idempotency-Key` header or this field (the same value if both): the
+ * same key and request answer what the first did; another request is 422 idempotency_conflict.
  */
 const IDEMPOTENCY_KEY = IDENTITY.describe('A retry identity, also accepted as the Idempotency-Key header: the same key with the same request answers what the first did; with another request, 422 idempotency_conflict.');
 /** Minutes after the end kept busy as well, for turnaround: at most 30 days. */
@@ -104,8 +102,7 @@ const RESOURCE = z
     /** Its own booking rules; `null` when it has none. */
     booking_rules: BOOKING_RULES.nullable(),
     /**
-     * What a booking on it must satisfy: the tenant's default rules, overlaid by its pool's,
-     * overlaid by its own; `null` when no rule applies.
+     * Tenant defaults, overlaid by its pool's, overlaid by its own; `null` when no rule applies.
      */
     effective_booking_rules: BOOKING_RULES.nullable(),
     /** `private` resources are never shown to agents; fixed when the resource is created. */
@@ -208,11 +205,6 @@ const RESERVATION = z
     source: z.string().max(200).nullable(),
 })
     .strict();
-/**
- * Any of the tenant's events, whichever key wrote it: `id` is the store's id for it, which the
- * tenant-event routes take, `event_ref` the id its owner reads it by, and `owner_ref` who that is
- * (`internal` for the tenant's own code, `agent:<digest>` for an API key).
- */
 /** A JSCalendar Event (RFC 8984 §5.1); interop.ts's JSCalendarEvent names every property. */
 const JSCALENDAR_EVENT = z
     .object({
@@ -511,7 +503,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
                 .max(7 * 24 * 60 * 60),
             source: SOURCE.optional(),
             idempotency_key: IDEMPOTENCY_KEY.optional(),
-            // Last: a generated client's 0.2.0 positional arguments keep their places.
+            // Last, so a generated 0.2.0 client's positional arguments keep their places.
             buffer_after_minutes: BUFFER_AFTER_MINUTES.optional(),
         })
             .strict()
@@ -768,8 +760,8 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
                 .object({
                 source: SOURCE,
                 /**
-                 * How the change feed names the source (coverage.recorded, .deleted, .stale): random,
-                 * made when it is first recorded for the resource, kept until it is deleted.
+                 * How the change feed names the source: random, made when first recorded for the
+                 * resource, kept until deleted.
                  */
                 source_id: z.string().regex(/^src_[0-9a-f]{32}$/),
                 start: DATE_TIME,
@@ -870,8 +862,8 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
             event_id: EVENT_ID,
             expected_revision: REVISION,
             expected_resource_id: RESOURCE_ID.optional(),
-            // Required, so a client always sends it; the Idempotency-Key header may stand in for
-            // it, since the server reads the header into it before the schema checks the request.
+            // Required, so clients always send it; the Idempotency-Key header may stand in, since the
+            // server copies it in before validation.
             idempotency_key: IDEMPOTENCY_KEY,
         })
             .strict(),