slotlock 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -3,6 +3,128 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.5.3 - 2026-10-28
+
+### Added
+
+- Configuration changes on the feed and in history (RFC 0002 P1-5, P1-6), each in the change's own
+  transaction, by trigger: `resource.created`, `resource.updated` (booking and check-in rules,
+  pool, bookable hours, time zone or reference, with `before` and `after` of the fields that
+  changed), `resource.archived`, `resource.restored`, `resource.deleted`, `coverage.recorded` (a
+  source's first read) and `coverage.deleted`, `webhook.created`, `webhook.enabled` and
+  `webhook.deleted`, and `key.created`, `key.rotated` and `key.revoked`. Writing a value that is
+  already there records nothing. Rows carry ids and states: never a webhook's URL or secret, nor an
+  API key, its digest, prefix or name, nor a coverage source, which `coverage.*` changes name by
+  `source_id` (`src_` and 24 hex digits, a digest of the tenant and the source; `subject` too).
+  `slotlock_get_coverage` and `listCoverage` give each source's `source_id`, and
+  `slotlockCoverageSourceId` works it out. A webhook's `event_types` takes any of them, up to every
+  type (it took at most 20).
+- Where a change came from: `withTenant` takes `origin` (`mcp`, `a2a`, `rest`, `application`,
+  `dashboard`, `dashboard-assistant`, `maintenance` or `library`, the default, also for a write
+  outside `withTenant`) and `keyId`, set by
+  each surface: the agent server per protocol, the application API, the dashboard and its
+  assistant, maintenance and webhook delivery. API key principals carry `keyId`, and the API key
+  store's `create`, `rotate` and `revoke` take `actor` and `origin`. The feed's new nullable
+  columns `origin` and `key_id` are in `listHistory` and `listChanges` (`origin`, `keyId`), the
+  history API (`origin`, `key_id`) and CloudEvents (extension attributes `slotlockorigin` and
+  `slotlockkeyid`). Rows written before keep null; an origin this release does not know reads as
+  null. `key_id` is pseudonymous and stays on a revoked key's changes for the retention. No address
+  or other personal data is recorded. The column's CHECK is added NOT VALID and validated after the
+  migration commits, so upgrading scans no rows under the table lock. An authenticator's key id
+  that is not a version 1-5 UUID is left out, as documented, rather than refusing the call.
+- Live updates from the change feed (RFC 0002 P1-5). With `subscriptions.changes`
+  (`createSlotlockStoreChangeSource(store, sql)`, which `slotlock serve` sets), MCP resource
+  subscriptions follow each tenant's change feed instead of re-reading every 10 seconds: one reader
+  per tenant per process, shared by its subscriptions, polls the feed by cursor (one indexed query,
+  every 250 ms while changes come, `SLOTLOCK_FEED_BUSY_MS`, backing off to 1 s when quiet,
+  `SLOTLOCK_FEED_IDLE_MS`) and re-reads only the subscriptions a change touches, each at most once a
+  second, so a booking is announced within about a second. Nothing is added to the write path: no
+  trigger, no `NOTIFY`. A cursor pruned past announces every watched resource once. The re-read every
+  `pollIntervalMs` stays as the fallback and revalidates the caller (15 s with a feed), and the
+  subscription caps are unchanged. `slotlockChangeFeedHead` is where a reader starts.
+- A2A streaming: the card declares `streaming`. `SendStreamingMessage` streams any skill's reply as
+  one message, and the `slotlock_watch_resources` skill streams a watch task with a status update
+  for each change to a watched resource's free/busy, from the same feed and caps as MCP
+  subscriptions, ending `TASK_STATE_COMPLETED` or, when access is withdrawn, `TASK_STATE_FAILED`.
+  Push notifications stay unsupported: webhooks deliver a tenant's changes to a URL.
+- Benchmarks on every release (RFC 0002, P2-1): once a tag's suite passes, release.yml runs
+  `scripts/bench.mjs` against a PostgreSQL 16 service container, attaches `bench.json` and
+  `bench.md` to the GitHub release and rebuilds the site, whose new Benchmarks page shows the newest
+  results with the method and caveats. The job is informational: nothing waits on it and its failure
+  fails no release. The script now also measures free/busy reads and the non-overlapping workload
+  with durable commits off, records the PostgreSQL version, CPU count, clients and duration, and
+  writes both files with `--out DIR`.
+- Booking rules: a leading buffer (`bufferBeforeMinutes`), the time kept free before each booking,
+  so two bookings stay the earlier one's trailing buffer plus the later one's leading buffer apart.
+  A reservation now occupies from `occupied_starts_at` (its start less `buffer_before_ms`, set by
+  a trigger) and the `slotlock_reservations_no_overlap` constraint keeps that time apart; free/busy,
+  searches, pool availability, holds and their reaping, coverage checks, series rolls and the
+  waitlist all read it.
+- Booking rules: a step offset (`stepOffsetMinutes`, 0 to the step less one): with a 30-minute step
+  and 15, bookings start on :15 and :45, local time in the resource's zone, on writes and searches.
+- Default booking rules for the tenant and for each pool (`setBookingRuleDefaults`,
+  `getBookingRuleDefaults`; `GET`/`PUT /v1/booking-rules`, `PUT /v1/pools/{pool}/booking-rules`):
+  a resource's rules as they apply (`effectiveBookingRules`, `effective_booking_rules`) are the
+  tenant's, overlaid by its pool's, overlaid by its own. A new tenant table under forced row-level
+  security, `booking_rule_defaults`, which erasure deletes. The dashboard's rules form has both new
+  rules and shows each inherited rule and where it comes from; an inherited on-or-off rule
+  (`enforceHours`, `requireCertain`) is a choice of default, on or off, so a resource can turn it
+  off. At most 1,000 pools a tenant have defaults (`pool_rules_limit_reached`). Merged rules are
+  read leniently: an offset under a shorter step applies modulo it, and an invalid field is ignored
+  and logged, never read as refusing every booking.
+- Pool availability counts a member busy over its bookings' occupied time, buffers included, not
+  the buffers a new booking would keep.
+
+### Upgrading
+
+- The migration adds `reservations.buffer_before_ms` and `occupied_starts_at` and
+  `calendar_events.buffer_before_ms` without rewriting a row (existing rows keep no leading buffer,
+  so their occupied time is unchanged), adds their checks NOT VALID and validates them after it
+  commits, and rebuilds `slotlock_reservations_no_overlap` once.
+- The rebuild holds an ACCESS EXCLUSIVE lock on `slotlock.reservations` for the whole index build,
+  about 15 seconds per million rows as measured in review: every read and write of reservations
+  waits until it ends. Schedule it, and for a very large table raise the migration's
+  `statementTimeoutMs` (`SlotlockMigrationOptions`, default 900,000 ms) so the build is not
+  cancelled.
+- `slotlock migrate` applies row-level security to the new table and grants it to the serving role.
+  A library user runs `applyTenantRls`, then `grantApplicationRole` right after `applySchema` and
+  before serving traffic: until then every booking fails with a permission error on
+  `booking_rule_defaults`, which every booking reads.
+
+### Changed
+
+- The feed now also records configuration changes, so a reader or webhook with no `event_types`
+  filter receives them too; filter by type to keep only bookings.
+- `coverage.stale` names its source by `source_id`, as `subject` and in `data`, in place of `source`,
+  and no longer carries `last_error`: a source can be an iCalendar URL with a token or an address,
+  and an error can quote it. `slotlock_get_coverage` still shows both to the tenant, with the
+  `source_id` to match a change to its source. Changes already on the feed keep the old payload
+  until they are pruned.
+
+## 0.5.2 - 2026-10-28
+
+### Added
+
+- The dashboard assistant: with `SLOTLOCK_ASSISTANT_SECRET`, an organization's owners connect a
+  model of their own in Settings (the Anthropic Messages API, or OpenAI-compatible chat
+  completions: OpenAI, OpenRouter, vLLM, Ollama, LM Studio), with a connection test, and every
+  member can operate Slotlock by chat on a new Assistant page. The server runs the tool loop (up to
+  8 model calls a message) with a fixed list of agent tools: reads run through the agent operation
+  boundary, and every write is a proposed change the member approves on a form before it runs once,
+  recorded as `dashboard-assistant:github:<user id>`, whose card shows the change in full under the
+  confirmation question's sentence. A proposal takes no series-write slot or rate token until it
+  runs, a message's reads share a budget, maintenance deletes every tenant's expired conversations
+  (`slotlock.sweep_assistant_conversations`, over the `assistant_tenants` list), and a new provider
+  or base URL takes the key again. The API key is sealed with AES-256-GCM, bound to the
+  tenant, and only its last four characters are shown. Two tenant tables under forced row-level
+  security, `assistant_settings` and `assistant_conversations`, which erasure deletes.
+  `createSlotlockRateLimiter` is the per-key token bucket it limits members' messages with, and
+  organization sessions now remember each organization's role (owners are admins). As webhooks
+  do, it refuses a model URL whose host is, or resolves to, a loopback, private, link-local, CGNAT,
+  unique-local or metadata address, when saved and at each connection (the resolved address is
+  checked as the socket connects, against DNS rebinding); `SLOTLOCK_ASSISTANT_PRIVATE_URLS=on`
+  allows them for a self-hosted model. `createSlotlockGuardedFetch` is that `fetch`.
+
 ## 0.5.1 - 2026-10-28
 
 ### Fixed

package/README.md

@@ -155,6 +155,8 @@ slotlock rules clear --resource vehicle-42
 | `minNoticeMinutes` | starts at least this far ahead |
 | `maxAdvanceDays` | starts at most this far ahead |
 | `slotStepMinutes` | starts on a step from local midnight in the resource's time zone |
+| `stepOffsetMinutes` | starts this far past each step (0 to the step less one): with a 30-minute step, 15 starts bookings on :15 and :45 |
+| `bufferBeforeMinutes` | keeps this long free before it: its leading buffer, which the database enforces |
 | `turnaroundMinutes` | keeps this long free after it: its trailing buffer, which the database enforces |
 | `enforceHours` | lies inside the resource's bookable hours |
 | `checkInMinutes` | is claimed (`checkInReservation`) this long after its start, or maintenance releases it |
@@ -169,8 +171,22 @@ slotlock rules clear --resource vehicle-42
   step and hours. Imported calendar events are not checked: they happened elsewhere.
 - Searches (`slotlock_find_next_available`, `slotlock_find_available_slots`, `findNextAvailableFor`)
   offer only slots the rules allow, so an offered slot is one the write accepts.
+- Two bookings stay at least the earlier one's trailing buffer plus the later one's leading buffer
+  apart: each occupies from its start less its leading buffer to its end plus its trailing one, and
+  the exclusion constraint keeps those apart. Free/busy reports that time as busy.
 - The REST application API sets them with `PUT /v1/resources/{resource_id}/booking-rules`, in
   snake_case; the store with `setResourceBookingRules`.
+- Defaults: rules for every resource of the tenant (`PUT /v1/booking-rules`) and for every member
+  of a pool (`PUT /v1/pools/{pool}/booking-rules`), read back with `GET /v1/booking-rules`; the
+  store's `setBookingRuleDefaults` and `getBookingRuleDefaults`. A resource's rules as they apply
+  (`effective_booking_rules`, `effectiveBookingRules`) are the tenant's defaults, overlaid by its
+  pool's, overlaid by its own: a rule set at a narrower level wins. `checkInMinutes` is a resource's
+  own only. The dashboard's resource page shows which rules a resource inherits, and from where.
+- With no rule set anywhere, nothing changes: every rule is opt-in.
+- A tenant has default rules for at most 1,000 pools (`pool_rules_limit_reached`, 409, for one
+  more). Merged rules are read leniently: a pool's `stepOffsetMinutes` under a resource's shorter
+  step applies modulo that step, and a field that is invalid on its own is ignored (and logged),
+  never read as refusing every booking.
 
 ### Without Docker
 
@@ -304,6 +320,59 @@ resources, so you can give each person API keys without running `slotlock key cr
   own on the hours page: two windows a day, overnight or all day, or closed. One form sets them
   for every resource at once.
 
+#### Assistant: operate Slotlock by chat
+
+With `SLOTLOCK_ASSISTANT_SECRET` set (32+ random characters, `openssl rand -hex 32`), the dashboard
+gains an Assistant page where every member chats with a model their organization connects, instead
+of clicking. Each organization brings its own model:
+
+- **Connect it** in Settings, Assistant (owners only; with personal tenants, each person): the
+  provider (`Anthropic Messages API`, or `OpenAI-compatible`, which covers OpenAI, OpenRouter,
+  vLLM, Ollama and LM Studio), the base URL (`https://api.anthropic.com`, or the one ending in
+  `/v1`: `https://api.openai.com/v1`, `http://localhost:11434/v1`; https, or http only on
+  `localhost` or `127.0.0.1`), the model name (`your-model`) and the API key, which a local model
+  may not need. As with webhooks, a URL whose host is, or resolves to, a loopback, private,
+  link-local, shared (CGNAT), unique-local or metadata address (`169.254.169.254`) is refused, when
+  it is saved and at each connection (the address the socket connects to is checked, so a name
+  rebound to one is refused too), and the page says why. For a self-hosted model on the server's
+  own machine or network (Ollama, vLLM), the operator sets `SLOTLOCK_ASSISTANT_PRIVATE_URLS=on`.
+  On Cloudflare Workers the literal check applies and names are not resolved: a Worker's fetch
+  reaches no private network. Changing the provider or the base URL takes the key again (decided in the
+  database write, so racing saves cannot get past it), so the stored key is only ever sent where it
+  was entered for, even on an origin that serves several accounts. **Test connection** makes one real request
+  and checks the model answers with one correct tool call. The organization's messages, and the bookings and resources the assistant
+  reads, are sent to the provider it configures.
+- **The key** is stored sealed with AES-256-GCM under a key derived from `SLOTLOCK_ASSISTANT_SECRET`,
+  bound to the organization, in `slotlock.assistant_settings` (forced row-level security, erased
+  with the tenant). The dashboard shows only that it is set and its last four characters. Changing
+  the secret makes stored keys unreadable: owners enter them again.
+- **Reads run, writes wait.** The server runs the tool loop, up to 8 model calls a message, with a
+  fixed list of the agent tools (the reads: resources, free-busy, next free time, slots, pool
+  availability, events; the writes: holds, bookings, pool and bundle bookings, changes and
+  cancellations). A read runs at once through the same operation boundary as an agent's. A write
+  never runs when the model asks: it appears as a proposed change the member approves (or
+  dismisses) with a form, and only then runs, once (its idempotency key is the dashboard's), with
+  the same booking rules, tenant limits and rate limits as an agent, recorded as
+  `dashboard-assistant:github:<user id>` (shown as "Assistant for @login"). The card leads with
+  the sentence a confirmation would ask (the resource by name, the times in its zone, and for a
+  change or cancellation the event's title, resource and time as it stands) and then shows every
+  argument in full; a change too large to show (16 KB of arguments) is not proposed, and a
+  conversation has at most 4 waiting. A proposal is only checked: the series-write slot and the
+  write's rate token are taken when the approved change runs. A message's reads share a budget of
+  16 calls and 400 resource-days. API keys, webhooks, booking rules, pools, erasure and
+  coverage are never offered; a tool the model names outside the list is refused.
+- Tool results and booking data are data to the model, never instructions, and the system prompt
+  says so; the tool list does not change with what the model says. A member may send 10 messages
+  a minute; each model call has 30 seconds and a message 90. Conversations are kept per member in
+  `slotlock.assistant_conversations` for 2 hours after the last message, then deleted: by
+  `serve`'s maintenance, which sweeps every tenant's expired conversations every quarter hour (a
+  tenant only the dashboard serves included), by `slotlock maintain`, and whenever the tenant's
+  conversations are read (so on Workers too). They are bounded in UTF-8 bytes; **New conversation** forgets one. On Workers, the
+  assistant's agent calls are capped at 24 a request and by `tenant_read` and `tenant_write` of
+  `SLOTLOCK_LIMITS` in each isolate. A provider's failure is shown as a plain message, never with
+  the key or the provider's answer.
+- It works as plain forms: no script is needed.
+
 ### Dashboard on Cloudflare Workers
 
 The same dashboard can run as a Cloudflare Worker at an origin of its own (`workers/dashboard`),
@@ -337,7 +406,8 @@ this one and read its session secret, which signs in as any tenant.
 3. Create the GitHub OAuth app as above, with the callback URL
    `<SLOTLOCK_PUBLIC_URL>/dashboard/callback` on the Worker's origin.
 4. Store the secrets on the Worker: `npx wrangler secret put` for `SLOTLOCK_GITHUB_CLIENT_ID`,
-   `SLOTLOCK_GITHUB_CLIENT_SECRET` and `SLOTLOCK_SESSION_SECRET`.
+   `SLOTLOCK_GITHUB_CLIENT_SECRET` and `SLOTLOCK_SESSION_SECRET`, and `SLOTLOCK_ASSISTANT_SECRET`
+   for the assistant.
 5. Deploy: `npm ci --omit=dev` at the repository root (the Worker bundles Slotlock's sources), then
    `npx wrangler deploy --config <your configuration>` in `workers/dashboard`.
 
@@ -780,8 +850,10 @@ import {
   type SlotlockStore,
   createSlotlockAgentServer,
   createSlotlockStoreAgentBackend,
+  createSlotlockStoreChangeSource,
 } from 'slotlock';
 import { createSlotlockNodeServer } from 'slotlock/node-server';
+import type { Sql } from 'postgres';
 
 const ALLOWED_OPERATIONS: ReadonlySet<SlotlockAgentOperation> = new Set([
   'slotlock_list_resources',
@@ -795,6 +867,8 @@ const ALLOWED_OPERATIONS: ReadonlySet<SlotlockAgentOperation> = new Set([
 
 export interface CalendarServerConfig {
   store: SlotlockStore;
+  /** The store's client: live updates read the change feed's head with it. */
+  sql: Sql;
   publicBaseUrl: string;
   port: number;
   verifyToken(token: string): Promise<SlotlockAgentPrincipal | null>;
@@ -815,7 +889,8 @@ export async function startCalendarServer(config: CalendarServerConfig) {
         }
       : {}),
     resourceWindowDays: 90,
-    subscriptions: { pollIntervalMs: 5_000 },
+    // Live updates follow each tenant's change feed: a booking is announced as it commits.
+    subscriptions: { changes: createSlotlockStoreChangeSource(config.store, config.sql) },
     backend: createSlotlockStoreAgentBackend(config.store, {
       availabilityRules: async () => [
         { rrule: 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR', startMinutes: 9 * 60, durationMinutes: 480 },
@@ -903,7 +978,9 @@ Rentals sell a class, not a plate. Put interchangeable resources in a pool
 members with `slotlock_list_resources` and `pool`, and book the class with `slotlock_book_pool`,
 which takes the first member that is free and allows the booking, in one transaction: a class of
 five sells exactly five for a time, however many race (`pool_full` after that). To see how many are
-free, `slotlock_get_pool_availability` splits a window where that number changes; to see which,
+free, `slotlock_get_pool_availability` splits a window where that number changes (counting each
+member busy over its bookings' occupied time, buffers included, but not the buffers a new booking
+would keep, so a member it counts free may still refuse a booking that abuts another); to see which,
 search the members with `slotlock_find_available_slots` and `require_free: 1`: each slot names the
 members free in `resource_ids`. `GET /v1/pools` lists the pools with their capacity. The older names `calendar.<verb>` and `calendar_<verb>` still work and
 are no longer advertised.
@@ -944,7 +1021,7 @@ on stderr.
 | HTTP | `401` with `WWW-Authenticate`, `403` disallowed origin, `413`/`415` bad body, `429` rate limit (MCP, REST) |
 | MCP | `-32602` unknown tool, `arguments` that are not an object, or altered confirmation; `-32603` server fault; `-32601` unknown method |
 | MCP 2026-07-28 | `-32020` header disagrees with body, `-32021` form elicitation not declared, `-32022` unsupported revision, `-31029` rate limit |
-| A2A | `-32602` malformed message or parameters, `-32029` rate limit (`RATE_LIMITED`, in the 200 envelope like every A2A error), `-32009` unsupported `A2A-Version`, `-32003` push notifications, `-32004` streaming, `-32001` task not found (the server keeps no tasks) |
+| A2A | `-32602` malformed message or parameters, `-32029` rate limit (`RATE_LIMITED`, in the 200 envelope like every A2A error), `-32009` unsupported `A2A-Version`, `-32003` push notifications, `-32004` task subscription or extended card, `-32001` task not found (the server keeps no tasks) |
 
 ### Authentication and OAuth discovery
 
@@ -995,8 +1072,18 @@ On MCP 2026-07-28 each resource is also an MCP resource, `slotlock://resources/{
 returns busy time and coverage for the next `resourceWindowDays` (30). `subscriptions/listen` streams
 `notifications/resources/updated` when a resource's free/busy changes.
 
-- Changes are found by re-reading through your backend every `subscriptions.pollIntervalMs` (10 s),
-  re-checking the caller each time.
+- With `subscriptions.changes` (`createSlotlockStoreChangeSource(store, sql)`; `slotlock serve`
+  sets it), changes come from the tenant's change feed: one reader per tenant per process, shared by
+  all its subscriptions, polls the feed by cursor, one indexed query per read, under the tenant's
+  row-level security. It reads again 250 ms after a read that found changes
+  (`SLOTLOCK_FEED_BUSY_MS`, also the least gap between two reads) and backs off to once a second
+  when quiet (`SLOTLOCK_FEED_IDLE_MS`), so a booking is announced within about a second. A change
+  re-reads the subscriptions watching its resource, at most once a second each however many
+  changes arrive, and each announces only what actually changed in its window. A cursor the feed
+  has pruned past announces every watched resource once, then follows from now.
+- Each subscription is also re-read every `pollIntervalMs` (15 s with a feed, 10 s without one,
+  which is then the only way changes are found), re-checking the caller each time, so a revoked key
+  or what the feed does not carry (bookable hours) is caught.
 - A subscription ends after `maxDurationMs` (15 minutes), on `shutdown()`, or when access is lost.
 - At most 4 open per caller and 256 per server (`maxPerPrincipal`, `maxTotal`). `maxPerTenant`
   caps one tenant's across all its callers (default `maxTotal`; `slotlock serve` sets 16), so a
@@ -1154,12 +1241,37 @@ curl -X PUT "http://localhost:8080/v1/reservations/BK-42" \
 
 ### Changes and webhooks
 
-Every committed change to a tenant's holds, bookings and calendar events is recorded in the same
-transaction (by a database trigger, so no write path skips it), and nothing is recorded that did
-not commit. A change carries ids, times and states, never titles, descriptions or attendees.
+Every committed change to a tenant's holds, bookings, calendar events and configuration is recorded
+in the same transaction (by a database trigger, so no write path skips it), and nothing is recorded
+that did not commit. A change carries ids, times and states, never titles, descriptions, attendees,
+webhook URLs or secrets.
+
+- The types: `hold.created`, `.updated`, `.confirmed`, `.released`, `.expired`;
+  `reservation.created`, `.updated`, `.cancelled`, `.checked_in`, `.no_show`; `event.created`,
+  `.updated`, `.cancelled`, `.timezone_shifted`, `.timezone_conflict`; `waitlist.offered`,
+  `.expired`; `coverage.stale`; and configuration: `resource.created`, `resource.updated` (booking
+  and check-in rules, pool, bookable hours, time zone or reference, with `before` and `after` of
+  only the fields that changed), `resource.archived`, `.restored`, `.deleted`; `coverage.recorded`
+  (a source's first read; reading it again is not a change) and `coverage.deleted`. A `coverage.*`
+  change names its source by `source_id` (also its `subject`), a digest of the tenant and the source
+  that `slotlock_get_coverage` and `slotlockCoverageSourceId` give too, never the source itself,
+  which can be an iCalendar URL with a token or an address;
+  `webhook.created`, `.enabled`, `.disabled`, `.deleted` (the id and `event_types`, never the URL);
+  `key.created`, `.rotated`, `.revoked` (the id, scopes and expiry, never the key, its digest,
+  prefix or name). `SLOTLOCK_CHANGE_TYPES` lists them.
+- Each change records who made it (`actor`: the API key or agent), the API key's id (`key_id`) when
+  a key made it, and where it came from (`origin`): `mcp`, `a2a`, `rest` (the REST agent routes),
+  `application` (the application API), `dashboard`, `dashboard-assistant`, `maintenance`, or
+  `library`: code calling the store itself, inside `withTenant` with no `origin` or outside it, and
+  any write that names none. Never an address or anything else about a person. A change an earlier
+  release recorded has neither (`null`).
+- `key_id` is pseudonymous: the key's id, never the key or its name. It stays on the changes the key
+  made after the key is revoked or deleted, for as long as the feed keeps them (the retention below,
+  and longer while an enabled webhook has still to receive them); erasing the tenant removes them.
 
 - `GET /v1/changes?cursor=…` lists them oldest first as [CloudEvents 1.0](https://cloudevents.io)
-  (`io.pylota.slotlock.hold.created`, `.reservation.cancelled`, `.event.updated`, …). Follow
+  (`io.pylota.slotlock.hold.created`, `.reservation.cancelled`, `.event.updated`, …), with the
+  extension attributes `slotlockorigin` and `slotlockkeyid` when the change records them. Follow
   `next_cursor`, which comes back even when nothing is new: it never skips a change, even one whose
   transaction commits after a later one's. Changes are kept 30 days (`SLOTLOCK_RETENTION_DAYS`,
   `retentionDays` in `createSlotlockStore`, 1-3,650, for `serve` and `maintain` alike); a cursor
@@ -1170,7 +1282,7 @@ not commit. A change carries ids, times and states, never titles, descriptions o
 - `POST /v1/webhooks` with an https `url` (and `event_types`, optionally) sends each change from
   then on as a [Standard Webhooks](https://www.standardwebhooks.com) request: `webhook-id` (the
   change's id, the same on every retry), `webhook-timestamp` and `webhook-signature`, keyed by the
-  `whsec_` secret the call returns once. Verify it with any Standard Webhooks library, and use
+  `whsec_` secret the call returns once. `event_types` takes any of the types above. Verify it with any Standard Webhooks library, and use
   `webhook-id` to drop a repeat: delivery is at least once.
 - Changes go to each webhook in order, one at a time, until one fails; that one is retried after
   5 seconds, 5 minutes, 30 minutes, 2, 5, then every 10 hours. After a day of failures, or a `410`,
@@ -1180,11 +1292,14 @@ not commit. A change carries ids, times and states, never titles, descriptions o
   an enabled webhook has still to receive, however old. At most 10 webhooks per tenant.
 - Each request has 15 seconds in all, and a tenant's pass 30 seconds; tenants are delivered 8 at
   a time, so a slow endpoint holds up only its own tenant.
-- History reads the same record backwards, with who made each change (the API key or agent) and,
-  for a change of an existing booking or event, what it was before:
-  `GET /v1/resources/{id}/history`, `GET /v1/reservations/{reference}/history`,
-  `GET /v1/tenant/events/{id}/history`, newest first, paged by `before`. In the library, pass
-  `actor` to `withTenant` and read `listHistory`. It is kept as long as the feed and erased with
+- History reads the same record backwards, with who made each change (`actor`, `key_id`), where
+  from (`origin`) and, for a change of an existing booking, event or resource, what it was before:
+  `GET /v1/resources/{id}/history` (its bookings, events and its own configuration),
+  `GET /v1/reservations/{reference}/history`, `GET /v1/tenant/events/{id}/history`, newest first,
+  paged by `before`. In the library, pass `actor`, `origin` and `keyId` to `withTenant` (`origin`
+  defaults to the enclosing call's, else `library`; `createSlotlockApiKeyAuthenticator` gives the
+  principal its `keyId`), and `actor` and `origin` to the API key store's `create`, `rotate` and
+  `revoke`; read `listHistory`. It is kept as long as the feed and erased with
   the tenant.
 - When time zone rules change (a new tzdata), a booking's instant and the wall time it was made for
   part: Winnipeg's 09:00 is no longer the instant stored. Slotlock keeps both, and maintenance finds
@@ -1193,7 +1308,8 @@ not commit. A change carries ids, times and states, never titles, descriptions o
   to `maintainSlotlockTenant` moves them instead, as a new revision, unless that overlaps another
   booking (`event.timezone_conflict`; it stays, for a person or an agent to decide). `/healthz`
   reports the `tzdata` the server runs.
-- Feed health: `GET /v1/resources/{id}/coverage` shows each source's window, when it was last read,
+- Feed health: `GET /v1/resources/{id}/coverage` shows each source (and its `source_id`, as the feed
+  names it), its window, when it was last read,
   its last error (`POST /v1/resources/{id}/coverage/{source}/failure` records one) and whether it is
   stale (not read for a day, so the time it covers is unproven, never free). A source that goes stale
   is put on the feed once, as `coverage.stale`, until it is read again. Retire a sync you have
@@ -1367,6 +1483,15 @@ export async function listResourcesOverA2a(baseUrl: string, token: string) {
 Send one `application/json` data part, `{"skill": "<id>", "arguments": {…}}`, with header
 `A2A-Version: 1.0`. Each skill in the agent card has an example; replies are synchronous.
 
+The card declares `streaming`. `SendStreamingMessage` with any skill streams its reply as one
+message. With `slotlock_watch_resources` (`{"resource_ids": [...]}`, up to 20) it streams a watch:
+a task in `TASK_STATE_WORKING` naming the resources it can see, then a status update
+`{"resource_id", "uri"}` each time one's free/busy changes, from the same feed and under the same
+caps as MCP subscriptions, until `TASK_STATE_COMPLETED` (its duration, shutdown) or
+`TASK_STATE_FAILED` (access withdrawn). Closing the stream ends it; the task is not kept, so
+`SubscribeToTask` and `GetTask` do not find it. Push notifications are not offered: a tenant's
+changes reach a URL as signed webhooks.
+
 ### MCP Apps
 
 Read-only tools link to `ui://slotlock/calendar`, a self-contained calendar view that hosts
@@ -1452,7 +1577,9 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
 7. Monitor conflicts, refused rules, sync lag, capped maintenance runs, quota errors and confirmation outcomes.
 8. Keep writes confirmation-gated wherever your policy needs a person (`slotlock serve`:
    `SLOTLOCK_CONFIRM_WRITES`, `none` by default).
-9. Size live updates: at most `maxTotal` backend reads per `pollIntervalMs`.
+9. Size live updates: one indexed feed query per second per tenant with an open subscription (four
+   a second while its feed is busy), at most one backend read a second per subscription a change
+   touches, and at most `maxTotal` backend reads per `pollIntervalMs`.
 10. Give each agent its own API key with the narrowest scope and an expiry.
 11. After each deployment, check it end to end with a short-lived admin key, then revoke the key:
     `SLOTLOCK_URL=https://… SLOTLOCK_ADMIN_KEY=… node scripts/smoke-deployment.mjs`, from a clone
@@ -1463,7 +1590,13 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
     server (`SLOTLOCK_LIMITS`); behind a proxy, set `SLOTLOCK_TRUSTED_PROXY_HEADER` and firewall
     the server so nothing reaches it except through that proxy. Embedding the
     agent server, give it a `consumeRateLimit`. Watch serve's `refusals` log line for floods.
-13. Bound how long a transaction may run. A store over your own transaction (a savepoint per call)
+13. On an upgrade, migrate first, then, as a library user, run `grantApplicationRole` again right
+    after `applySchema` and before serving traffic: a release that adds a table (the leading-buffer
+    release adds `booking_rule_defaults`, which every booking reads) fails every booking with a
+    permission error until the serving role is granted it. `slotlock migrate` does both. A migration
+    that rebuilds a constraint holds its table's lock for the whole build (see the CHANGELOG's
+    Upgrading notes).
+14. Bound how long a transaction may run. A store over your own transaction (a savepoint per call)
     keeps its locks and its snapshot for as long as yours runs, and a hold you confirm inside it is
     judged by the statement's clock, not the transaction's. On PostgreSQL 17 and later, give the
     serving role a `transaction_timeout` above your longest legitimate transaction

package/SPEC.md

@@ -245,13 +245,16 @@ envelope (a body over the size limit is HTTP 413); A2A's own errors, below, carr
 `google.rpc.ErrorInfo` detail and JSON-RPC's (`-32700`, `-32600`, `-32601`, `-32603`) none. An
 `A2A-Version` other than `1.0`, including none (read as 0.3), is `VersionNotSupportedError`
 (`-32009`); push-notification methods are
-`PushNotificationNotSupportedError` (`-32003`); streaming, task subscription and the extended card
-are `UnsupportedOperationError` (`-32004`); a message that is not exactly one data part
+`PushNotificationNotSupportedError` (`-32003`); task subscription and the extended card are
+`UnsupportedOperationError` (`-32004`); a message that is not exactly one data part
 `{"skill": "<id>", "arguments": {…}}` (`arguments` left out or null is none; any other value that is
 not an object is not arguments) is `-32602`, as is a `configuration` or `metadata` that is set but
 is not an object; a rate-limited request is `-32029` with the reason `RATE_LIMITED` and a null id,
-answered before its body is read. The server replies with messages and keeps no
-tasks, so the core task operations answer as for an unknown task: `GetTask` and `CancelTask` are
+answered before its body is read. `SendStreamingMessage` streams a skill's reply as one message;
+with `slotlock_watch_resources` it streams a watch task (TASK_STATE_WORKING, a status update per
+changed resource, then TASK_STATE_COMPLETED or TASK_STATE_FAILED) that lives only in its stream,
+under the MCP subscription caps; refused before it opens, it is the skill's reply. The server keeps
+no tasks, so the core task operations answer as for an unknown task: `GetTask` and `CancelTask` are
 `TaskNotFoundError` (`-32001`), `ListTasks` returns an empty page (`pageSize` 1-100, default 50).
 Their params are checked first, as `SendMessage`'s are: a field the method does not define, a
 `tenant` other than the caller's, a value of the wrong type (a `status` outside `TaskState`, say), a
@@ -364,9 +367,9 @@ with no remaining command; `internal` tombstones remain authoritative until tena
 command evaluated after its evidence is gone is decided afresh by the expected-revision guard.
 
 The protocol backend remains injectable so a deployment owns credential verification, policy, rate
-limits, and networking. The A2A binding is intentionally synchronous and advertises neither
-streaming nor push notifications; an embedder must not claim task lifecycle support unless it
-persists that lifecycle itself.
+limits, and networking. The A2A binding advertises streaming (a reply as one message, a watch as
+a task that lives only in its stream) and not push notifications; an embedder must not claim
+persisted task lifecycle support unless it persists that lifecycle itself.
 
 The optional Node HTTP adapter preserves the Fetch boundary rather than defining another protocol
 implementation. It constructs callback-visible request URLs from an explicit canonical origin,

package/agent-server.d.ts

@@ -1,5 +1,7 @@
 import { type SlotlockTraceContext } from './mcp-modern.js';
 import { type SlotlockApplicationBackend, type SlotlockApplicationOperation } from './application-api.js';
+import { type SlotlockAgentChangeSource } from './change-watch.js';
+import type { SlotlockChangeOrigin } from './event-feed.js';
 export type { SlotlockTraceContext } from './mcp-modern.js';
 export { clientSupportsSlotlockMcpApp, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, } from './mcp-app.js';
 /**
@@ -64,6 +66,11 @@ export interface SlotlockAgentPrincipal {
      * Unset, `authorize` alone decides.
      */
     scopes?: readonly string[];
+    /**
+     * The API key the credential is, by its id (a UUID), when it is one: the history records it with
+     * each change the principal makes (`createSlotlockApiKeyAuthenticator` sets it).
+     */
+    keyId?: string;
 }
 export interface SlotlockAgentInvocationContext {
     principal: SlotlockAgentPrincipal;
@@ -74,6 +81,11 @@ export interface SlotlockAgentInvocationContext {
      * backend's spans as its children to follow one agent action across services.
      */
     trace?: SlotlockTraceContext;
+    /**
+     * The surface the call came through (`mcp`, `a2a`, `rest`, `dashboard-assistant`), for a backend
+     * to record with its changes (withTenant's `origin`).
+     */
+    origin?: SlotlockChangeOrigin;
 }
 /** A bounded domain failure a backend may deliberately expose through a protocol tool result. */
 export declare class SlotlockAgentOperationError extends Error {
@@ -182,13 +194,27 @@ export interface SlotlockAgentConfirmationOptions {
 /**
  * Live calendar updates over MCP 2026-07-28 `subscriptions/listen`. A client subscribes to calendar
  * resource URIs (`slotlockCalendarResourceUri`) and receives `notifications/resources/updated` on the
- * response stream when a resource's free/busy changes. The server finds changes by re-reading each
- * open subscription's resources through the backend every `pollIntervalMs`, re-running `authenticate`
- * and `authorize` each time, so a revoked credential or permission ends the stream.
+ * response stream when a resource's free/busy changes. With `changes`, the server follows each
+ * tenant's change feed (one reader per tenant, shared by all its subscriptions) and re-reads a
+ * subscription's resources when a change touches one of them; without it, it re-reads them every
+ * `pollIntervalMs`. Each re-read runs `authenticate` and `authorize` again, so a revoked credential
+ * or permission ends the stream, and announces only the resources whose free/busy changed.
  */
 export interface SlotlockAgentSubscriptionOptions {
-    /** How often an open subscription re-reads its resources, in ms: 1,000-300,000, default 10,000. */
+    /**
+     * How often an open subscription re-reads its resources regardless, in ms: 1,000-300,000. Default
+     * 10,000, or 15,000 with `changes`, where it is the fallback for what the feed does not carry
+     * (bookable hours, a revoked key or permission) and for a feed that stopped.
+     */
     pollIntervalMs?: number;
+    /**
+     * The change feed to follow (createSlotlockStoreChangeSource, or your own over
+     * SlotlockEventFeed.listChanges), polled by one reader per tenant every SLOTLOCK_FEED_BUSY_MS to
+     * SLOTLOCK_FEED_IDLE_MS: a change is announced within about a second instead of at the next
+     * re-read. A subscription re-reads its resources at most once a second, however many changes
+     * touch them.
+     */
+    changes?: SlotlockAgentChangeSource;
     /** When the server ends a subscription gracefully, in ms: 60,000-86,400,000, default 900,000. */
     maxDurationMs?: number;
     /** How often a quiet stream carries an SSE keep-alive comment, in ms: 1,000-60,000, default 15,000. */
@@ -449,6 +475,8 @@ export declare function invokeSlotlockAgentOperation(args: {
     options: SlotlockAgentOperationDispatchOptions;
     /** Validated W3C trace context to hand the backend (see `SlotlockAgentInvocationContext.trace`). */
     trace?: SlotlockTraceContext;
+    /** The surface the call came through, handed to the backend (`SlotlockAgentInvocationContext.origin`). */
+    origin?: SlotlockChangeOrigin;
 }): Promise<SlotlockAgentOperationDispatchResult>;
 /**
  * Read an A2A `google.protobuf.Timestamp` in its JSON form, as `ListTasks.statusTimestampAfter`
@@ -464,6 +492,26 @@ export declare function parseSlotlockA2ATimestamp(value: unknown): Date | null;
 export declare const SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE = "slotlock://resources/{resource_id}";
 /** The MCP resource URI of one calendar resource: `SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE`, expanded. */
 export declare function slotlockCalendarResourceUri(resourceId: string): string;
+/**
+ * The sentence a person is asked to confirm for a write, as the confirmation flow words it: the
+ * resource by name and the times in its own zone, and for a change or deletion the event as it
+ * stands (its title, resource and time), each read as `principal` only where its scopes and
+ * `authorize` allow that read. The dashboard assistant shows it on a proposed change.
+ */
+export declare function describeSlotlockAgentWrite(args: {
+    backend: SlotlockAgentCalendarBackend;
+    authorize: SlotlockAgentServerOptions['authorize'];
+    principal: SlotlockAgentPrincipal;
+    operation: SlotlockAgentWriteOperation;
+    input: Record<string, unknown>;
+    signal: AbortSignal;
+}): Promise<string>;
+/**
+ * The A2A skill that watches calendars: `SendStreamingMessage` only. Its stream opens with a task
+ * in TASK_STATE_WORKING and carries a status update for each change to a watched resource's
+ * free/busy, from the same feed as MCP resource subscriptions, until the watch's duration is up.
+ */
+export declare const SLOTLOCK_A2A_WATCH_SKILL = "slotlock_watch_resources";
 export declare function createSlotlockAgentServer(options: SlotlockAgentServerOptions): {
     fetch(request: Request): Promise<Response>;
     manifest: Readonly<Record<string, unknown>>;