slotlock 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,200 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.6.0 - 2026-10-29
+
+### Added
+
+- `invalid_arguments` from argument validation names the fields it refused: `issues`, up to 20
+  `{path, message}` (the field's path in the arguments, outermost first; `[]` is the arguments as a
+  whole). REST adds it to the problem details beside `code` (documented in openapi.json's `Error`),
+  MCP and A2A to `error`. Additive: `code` and the status are unchanged.
+  `invokeSlotlockAgentOperation` returns it too (`SlotlockArgumentIssue`).
+- `slotlock serve` logs one `serving_as_schema_owner` warning at startup when its role owns the
+  `slotlock` schema: row-level security does not confine the owner on tables that do not force
+  it. It still serves.
+
+### Fixed
+
+- Security: a coverage source's `source_id` could be confirmed by guessing. 0.5.3 named a source on the feed
+  by `src_` and 24 hex digits of an unkeyed SHA-256 of the tenant and the source, so anyone who saw
+  a change or a webhook and knew the tenant could test a guessed source offline: an address such as
+  `google:alice.smith@example.com`, say. A source's `source_id` is now random (`src_` and 32 hex
+  digits, 122 bits from `gen_random_uuid()`), stored with the source in
+  `calendar_coverage.source_id` when it is first recorded for the resource and kept until it is
+  deleted. Nothing outside the database can work it out; the tenant reads it beside the source from
+  `listCoverage` and `slotlock_get_coverage`.
+- Security: changes an earlier release wrote still carried the source. Before 0.5.3 `coverage.stale` had the
+  source itself as `subject` and `data.source` (an iCalendar URL with its token) and the error read
+  from it as `data.last_error`, and `listChanges`, the history and webhooks that had not received it
+  served it until it was pruned. The upgrade renames every `coverage.*` change not in this release's
+  shape: `subject` and `data.source_id` become the source's new id, `source` and `last_error` are
+  removed. A change about a source deleted since is named `src_redacted`: nothing can match it any
+  more, and a made-up id would look like a source the tenant could find. A change an earlier
+  release's server (0.3-0.5) still running writes after the upgrade is put in the same shape as it
+  is inserted, by a trigger on the outbox (`slotlock.outbox_coverage_in_shape`), so none is stored
+  with its source. The read path redacts too: `listChanges`, `listRecentChanges`, `listHistory`,
+  webhook deliveries and `slotlockCloudEvent` never serve a `coverage.*` change with `source` or
+  `last_error`, and name one whose subject is not a `source_id` of this release `src_redacted`;
+  history by `subject` never finds a coverage change by any other name, so it cannot confirm a
+  guessed source either.
+
+### Changed
+
+- **Breaking:** every `source_id` changes, and its shape is `src_` and 32 hex digits (was 24). A
+  reader that stored `source_id`s or `subject`s of `coverage.*` changes matches them again from
+  `listCoverage` / `GET /v1/resources/{id}/coverage`. The same source recorded for two resources,
+  or deleted and recorded again, has a different id each time.
+- **Breaking:** changes already on the feed about coverage are rewritten in place by the upgrade, as
+  above; their positions and ids (`webhook-id`) do not change, so a webhook that already received
+  one is not sent it again, and one that has not receives the new shape.
+
+- **Breaking:** `slotlockCoverageSourceId` throws (`coverage_source_id_unavailable`) instead of
+  returning 0.5.3's digest, which nothing carries any more and which would confirm a guessed source:
+  read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`) instead.
+- `slotlock migrate` (and `serve --migrate`) run as a role that does not own the schema, with no
+  `SLOTLOCK_MIGRATE_DATABASE_URL`, now fail with a first line that says to set
+  `SLOTLOCK_MIGRATE_DATABASE_URL` to the schema owner's URL, then the database's refusal.
+- The README no longer opens with the 0.2.0 known issues: they are in
+  `docs/release/0.2.0-known-issues.md`, linked under "Supported versions".
+- The hosted service page, its site page and SECURITY.md say the hosted service is not open and
+  that self-hosting is the only supported path today; SECURITY.md no longer invites testing it.
+
+### Deprecated
+
+- `slotlockCoverageSourceId`, which now only throws. It may be removed in 0.7.0.
+
+### Upgrading
+
+- **Breaking:** the schema is version 4. A 0.5 release refuses to migrate it ("Slotlock will not
+  migrate a schema a newer release migrated") and its server refuses to serve it, since its DDL would
+  put back the trigger that names a source by its guessable digest. Rolling back to 0.5.x needs a
+  restore of a backup taken before the upgrade.
+- The migration adds `calendar_coverage.source_id` without rewriting the table (the column bare, its
+  random default set apart), gives each existing source an id under the migration's lock
+  (`calendar_coverage` is one row per source and resource), and adds its CHECK NOT VALID, validated
+  after the migration commits.
+- Changes written from the upgrade on are put in shape as they are inserted. Those written before
+  it: once the structure commits, `applySchema` renames them in batches of 5,000 outbox ids by
+  primary key, each its own transaction, up to the last change when the pass started, read in a
+  short transaction of its own once the outbox writes in flight have ended. Where it got to is saved
+  with each batch (`schema_version.coverage_changes_renamed_through`): an interrupted pass goes on
+  from there, and the next migration reads only what was written since, until a pass after the
+  upgrade's finds nothing to rename and marks it done (`coverage_changes_renamed`). After that no
+  migration reads the outbox for it again.
+- Locks: under a deployment role that forced RLS binds, each batch lifts FORCE from
+  `calendar_coverage` and `outbox` and puts it back before it commits, holding ACCESS EXCLUSIVE on
+  both for that batch (one range of 5,000 ids: milliseconds), so writes to either table wait that
+  long, once per batch, for every batch of the outbox on the upgrade and for the rows written since
+  on the passes after it. A superuser or BYPASSRLS role holds SHARE ROW EXCLUSIVE on the outbox
+  for the short transaction that reads the head (writes wait, reads do not), then only the row
+  locks of the rows it renames. `SLOTLOCK_CORE_DDL`, applied with psql, renames in its one transaction instead, with
+  the outbox under ACCESS EXCLUSIVE for the whole of it: a scan of the whole outbox on the upgrade.
+- A migration step ended as a deadlock's victim (a caller's transaction that took the outbox, then a
+  coverage row, while a rename batch took them in the other order, say) is retried like one that
+  waited past its lock timeout, up to `attempts`, instead of failing.
+
+## 0.5.3 - 2026-10-28
+
+0.5.3 shipped breaking changes in a patch release, contrary to [VERSIONING.md](VERSIONING.md): the
+two marked "Breaking" under **Changed**. Breaking changes will be minor releases from now on.
+
+### 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
+
+- Breaking: 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.
+- Breaking: `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

package/README.md

@@ -5,44 +5,6 @@ reservable, answers "when is this free?" from weekly availability rules, and let
 double bookings, however many writers race. Agents call it over MCP or A2A; your code calls it as a
 TypeScript library.
 
-## Known issues in 0.2.0
-
-Slotlock 0.2.0 can occupy less time than an event was written with, so another booking can take the
-rest: around daylight-saving changes, in any time zone that has them, and at the end of some series.
-The library and `slotlock serve` are both affected (the last case below is in the library's
-iCalendar readers only); the 0.1 releases are older still and unsupported. 0.3.0, released on
-2026-10-27, fixes all six cases: upgrade (`npm install slotlock@0.3.0` or
-`ghcr.io/pilotaai/slotlock:0.3.0`, then `slotlock migrate`, as the [changelog](CHANGELOG.md) says).
-While you run 0.2.0, do not rely on it alone to refuse bookings in them.
-
-- A recurring event whose first occurrence spans a daylight-saving change gets that occurrence an
-  hour short: in spring, an hour of the written time is free to book.
-- Recurring events written through the store (the agent tools and the application API) lose the
-  repeated hour of an autumn change: times in it move an hour early, and a series whose first
-  occurrence spans it can store no occurrences, so all of its time is free.
-- A stored recurring series cannot cancel or move an occurrence that falls in the skipped hour of a
-  spring change; the time it was moved to stays free.
-- An occurrence that starts in the skipped hour and lasts longer than the skipped hour is cut short:
-  a 75-minute occurrence occupies 15 minutes.
-- A timed recurring series with a date-only `UNTIL` ends at midnight UTC, so it can lose its last
-  day.
-- An event read from iCalendar (`parseICalendarChanges`, `parseTrustedICalendarEvents` or the
-  worker pool) whose `DURATION` counts hours loses an hour across a spring change, whether it is a
-  single event, a series, an `RDATE` period or a moved occurrence: `DURATION:PT48H` occupies 47
-  hours.
-
-0.1.0, 0.1.1 and 0.2.0 also pin zod 4.6.5 exactly, which has a high advisory
-([GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5): validating an oversized
-array can exhaust memory), which `npm audit` reports. While you run one of them, add this to your
-application's `package.json` and run `npm install`:
-
-```json
-"overrides": {"zod": "4.6.7"}
-```
-
-The full notice, with the versions affected, is in
-[docs/release/0.2.0-known-issues.md](https://github.com/PILOTAAI/slotlock/blob/main/docs/release/0.2.0-known-issues.md).
-
 ## Why it is built for agents
 
 - Resources own calendars, not users, and the tenant comes only from the authenticated caller.
@@ -155,6 +117,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,17 +133,32 @@ 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
 
 With Node.js 22.12+ and PostgreSQL 16 or newer, run each command as `npx slotlock` after
 `npm install slotlock postgres`, or from a clone, built once, as `node dist/cli.js` (a clone does not
-put `slotlock` on your `PATH`). Use two roles, as Compose does:
-the server connects as a role that owns nothing and cannot bypass row-level security, and `migrate`
-connects as the database owner and grants that role what it needs. `serve` refuses to start as a
-superuser or a `BYPASSRLS` role, which row-level security does not confine.
+put `slotlock` on your `PATH`). Use two roles, as Compose does, so two URLs: `serve` connects as
+`DATABASE_URL`, a role that owns nothing and cannot bypass row-level security, and `migrate`
+connects as `SLOTLOCK_MIGRATE_DATABASE_URL`, the schema owner, and grants that role what it needs.
+`serve` refuses to start as a superuser or a `BYPASSRLS` role, which row-level security does not
+confine, and warns (`serving_as_schema_owner`) when its role owns the schema.
 
 ```sh
 npm ci && npm run build
@@ -212,7 +191,7 @@ slotlock key revoke <id>
 
 - A key (`slk_…`) is shown once and stored only as a SHA-256. Send it as `Authorization: Bearer`.
 - It acts in the tenant it was created for (`SLOTLOCK_TENANT`), so one server serves many tenants.
-- `read` covers the five tools that only look; `write` covers create, update and delete; `admin`
+- `read` covers the seven tools that only look; `write` covers create, update and delete; `admin`
   covers the [application API](#application-api), which no agent needs. Default: read and write.
 - `rotate` keeps the key's id, scopes and bookings; `revoke` stops it on its next request.
 - A tenant may hold 100 active keys. The last six characters are a checksum secret scanners can
@@ -580,6 +559,9 @@ export async function bookHandover(store: SlotlockStore, tenantRef: string) {
 }
 ```
 
+Run every store method inside `withTenant`. A call outside it is not refused: it runs with no tenant
+context, so as the application role forced row-level security shows it no rows.
+
 `withTenant` validates the tenant, sets the context transaction-locally on the one connection every
 callback call uses, supports nested savepoints, and restores the previous context. Do not issue a
 standalone `set_config(..., true)` through a pool: its transaction ends before the next call.
@@ -632,6 +614,49 @@ Writing rules:
   reference for a genuinely new event.
 - `listCalendarEvents` and `listResources` return at most 1,000 rows and page with keyset cursors.
 
+### Holds, external bookings and the feed
+
+<!-- example: examples/store.ts#holds -->
+```ts
+export async function holdBookAndFollow(store: SlotlockStore, tenantRef: string, resourceId: string) {
+  // Inside withTenant: outside it the application role's row-level security shows no rows.
+  const booked = await store.withTenant(tenantRef, async (tenant) => {
+    // Hold a window for ten minutes while the customer pays, then turn it into a booking.
+    const held = await tenant.acquireHold({
+      tenantRef,
+      resourceId,
+      start: new Date('2027-04-05T09:00:00Z'),
+      end: new Date('2027-04-05T10:00:00Z'),
+      ttlMs: 10 * 60_000,
+    });
+    if (!held.ok) throw new Error(`not held: ${held.code}`);
+    const confirmed = await tenant.confirmHold(held.hold.id, { tenantRef });
+    if (!confirmed.ok) throw new Error(`hold not confirmed: ${confirmed.code}`);
+
+    // A booking your own system already has, by its reference there: revision 1 creates it.
+    const imported = await tenant.createExternalReservation({
+      tenantRef,
+      externalRef: 'BK-43',
+      resourceId,
+      start: new Date('2027-04-05T11:00:00Z'),
+      end: new Date('2027-04-05T12:00:00Z'),
+      bufferAfterMs: 15 * 60_000,
+      revision: 1,
+    });
+    if (!imported.ok) throw new Error(`BK-43 not booked: ${imported.code}`);
+    return { booking: confirmed.reservation, imported: imported.reservation };
+  });
+
+  // What changed, oldest first, once committed: so in a withTenant of its own. Poll again with
+  // `after: feed.next`.
+  const feed = await store.withTenant(tenantRef, (tenant) =>
+    tenant.listChanges({ tenantRef, limit: 100 }),
+  );
+  if (!feed.ok) throw new Error(`feed not read: ${feed.code}`);
+  return { ...booked, feed };
+}
+```
+
 ### Recurring events
 
 <!-- example: examples/store.ts#recurring -->
@@ -834,8 +859,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',
@@ -849,6 +876,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>;
@@ -869,7 +898,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 },
@@ -957,7 +987,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.
@@ -971,7 +1003,7 @@ A refusal is a result the model can act on:
 
 | Code | Meaning |
 | --- | --- |
-| `invalid_arguments` | Input failed the schema, or a window is inverted or longer than 367 days |
+| `invalid_arguments` | Input failed the schema, or a window is inverted or longer than 367 days. A schema failure adds `issues`, up to 20 `{"path":[…],"message":"…"}`, each naming a field by its path in the arguments (`["rules",0,"start_minutes"]`; `[]` is the arguments as a whole): in `error` on MCP and A2A, beside `code` in REST's problem details |
 | `forbidden` | `authorize` refused the call |
 | `rate_limited` | `consumeRateLimit` refused the call |
 | `not_found`, `resource_not_found`, `event_not_found` | Not visible to this caller, or no such id: a resource id is the `id` `slotlock_list_resources` returns, not its `external_ref` |
@@ -998,7 +1030,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
 
@@ -1049,8 +1081,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
@@ -1153,8 +1195,8 @@ waits for a confirmation.
 | `POST /v1/resources/{resource_id}/archive` | Take it out of use; `…/restore` puts it back |
 | `DELETE /v1/resources/{resource_id}` | Delete it with its history (`409 resource_in_use` while anything on it is live) |
 | `GET /v1/resources/{resource_id}/busy?start=…&end=…` | Its occupied time, private resources included |
-| `PUT /v1/resources/{resource_id}/availability` | Its own weekly hours; `[]` never bookable, `null` the server's |
-| `PUT /v1/availability` | Every resource's weekly hours at once |
+| `PUT /v1/resources/{resource_id}/availability` | `{"rules":[…]}`: its own weekly hours; `"rules":[]` never bookable, `"rules":null` the server's |
+| `PUT /v1/availability` | `{"rules":[…]}`: every resource's weekly hours at once |
 | `POST /v1/holds` | Hold a window for `ttl_seconds` (up to 7 days) |
 | `GET /v1/holds/{hold_id}` | One live hold; `GET /v1/resources/{resource_id}/holds` lists them |
 | `POST /v1/holds/{hold_id}/confirm` | Turn the hold into a reservation |
@@ -1208,12 +1250,40 @@ 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`), never the source itself, which can
+  be an iCalendar URL with a token or an address: `src_` and 32 random hex digits, made when the
+  source is first recorded for the resource and kept until it is deleted, so it cannot be worked
+  out from the source. `slotlock_get_coverage` (`listCoverage`) gives it beside the source, to
+  match a change to its source. A change about a source deleted before 0.6 named it is
+  `src_redacted`;
+  `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
@@ -1224,7 +1294,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`,
@@ -1234,11 +1304,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
@@ -1247,7 +1320,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
@@ -1421,6 +1495,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
@@ -1506,7 +1589,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
@@ -1517,7 +1602,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
@@ -1536,13 +1627,15 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
 | PostgreSQL | 16, 17 and 18 (CI runs the database suites on each; Compose ships 18) |
 | postgres (peer) | ^3.4.5 |
 
+0.2.0 and older can double-book around daylight-saving changes: [known issues](https://github.com/PILOTAAI/slotlock/blob/main/docs/release/0.2.0-known-issues.md#the-known-issues).
+
 ## Project status and boundaries
 
 Slotlock is availability maths, holds and reservations, events with recurrence, coverage-aware
 free/busy, tenant isolation, iCalendar interchange, MCP and A2A with human confirmation and live
 updates, an MCP Apps view, REST with the application API, scoped API keys, a GitHub sign-in
-dashboard, maintenance, and clients for five languages. [Hosted Slotlock](docs/hosted/README.md),
-not open yet, will run it for you. Provider sync (Google, Microsoft, CalDAV), notifications to people, and a human
+dashboard, maintenance, and clients for five languages. [Hosted Slotlock](docs/hosted/README.md)
+is not open; self-hosting is the only supported path today. Provider sync (Google, Microsoft, CalDAV), notifications to people, and a human
 calendar app are yours to build around it. What each version promises is in
 [VERSIONING.md](VERSIONING.md).