slotlock 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,131 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.2.0 - 2026-10-23
+
+### Added
+
+- The application API: what an application does through the store, over REST from any language.
+  Create resources and set their weekly hours; hold, confirm and release time; book, move and cancel
+  reservations by reference and revision; record external calendar coverage; run maintenance. The
+  routes sit under `/v1` beside the tools, in the same OpenAPI document, and need an API key with the
+  new `admin` scope. They are never MCP tools or A2A skills. `createSlotlockStoreApplicationBackend`
+  serves them from the store; `createSlotlockAgentServer` takes them as `application`.
+- The `admin` API key scope: `slotlock key create <name> --scope read,write,admin`, or "Full" in the
+  dashboard. New keys still default to read and write, and `SLOTLOCK_AUTH_TOKEN` is never admin: it
+  is the token agents are given, and the application API asks no person before it writes.
+- Built-in maintenance. `slotlock serve` maintains every tenant it serves, hourly, one at a time,
+  under a per-tenant advisory lock, and logs the counts; `slotlock maintain` runs it once.
+  `maintainSlotlockTenant`, `startSlotlockMaintenance` and `withSlotlockMaintenanceLock` do the
+  same in a process of your own.
+- `confirmHold` and `releaseHold` take `{ tenantRef }`, so another tenant's hold is not found
+  whatever the connection's row-level security.
+- Clients for Python, Go, Rust, Java and .NET (`clients/`): one method per REST operation, the
+  application API included, generated from `openapi.json` with hand-written transports. Each runs
+  the same scenario against the server image in CI. They are not on their package registries yet.
+- `openapi.json`, the REST API's OpenAPI 3.1 document, in the repository and at
+  https://slotlock.pylota.io/openapi.json; `slotlockOpenApi()` builds it.
+- Property-based tests (fast-check) of the engine, time zones, iCalendar parsing and API keys.
+- A `call` event for each MCP `tools/call` and A2A `SendMessage` that names an operation: its
+  outcome, duration and W3C trace id. `rest` events carry the duration and trace id too, and
+  `slotlock serve` logs both.
+- Releases are opened and merged by a GitHub App once it is set up
+  (`node scripts/create-release-app.mjs`), so its checks run without a maintainer approving them.
+  Only the commit whose checks passed is merged.
+
+### Changed
+
+- `slotlock serve` serves REST by default; `SLOTLOCK_REST_API=off` turns it off.
+- `expandRules` and `findNextAvailableFor` refuse a search window longer than 367 days with
+  `invalid_window`, as free/busy already did, and skip a rule that lasts longer than a week, as the
+  hours validator refuses one. Fifty daily rules over a century were two million windows of
+  synchronous work.
+- Upgrading rebuilds the unique index on booking references
+  (`slotlock_reservations_booking_external_ref_key`) to leave calendar event rows out, and drops
+  the one it replaces after the new one is built.
+- A cursor 0.1 kept beside a stored series is not resumed if the series is zoned and ends (UNTIL):
+  0.1 read its occurrences as UTC beside the UNTIL, so the cursor may have stopped one occurrence
+  early (a booking could then take that time) or gone one past. The next roll searches such a series
+  from its start, within the same budget, and keeps a new cursor.
+- Upgrading widens the API key scope constraint in place, and replaces the reservations overlap
+  constraint with one that counts every row's turnaround buffer (below). Expired holds in a buffer's
+  way are removed; while a live hold or untenanted reservation is in one, migrate stops with their
+  ids and changes nothing.
+
+### Fixed
+
+- A calendar event's occupation could be freed or moved through the reservation commands
+  (`cancelExternalReservation`, `rescheduleExternalReservation`, and the application API's
+  reservation routes) by naming the reference the store derives for it: the event stayed active but
+  stopped occupying its time. Those commands now leave event rows out. An event freed this way
+  before upgrading occupies its time again once it is written again.
+- Maintenance replaced a series' stored window with the rolling horizon even when the stored window
+  ended later, deleting the occurrences past it.
+- Free/busy called a window complete when a series started inside it but was stored only from
+  later: those occurrences were reported as free time.
+- Upgrading as a non-superuser owner under forced row-level security failed with a raw error (or,
+  for some repairs, skipped them): the upgrade's data steps saw no rows. The upgrade now lifts FORCE
+  for those steps and records what it lifted, so an upgrade stopped part way is put right by the
+  next one, and `slotlock serve` refuses to start while a tenant table is left without FORCE.
+- `expandRules` without a time zone offered windows after the rule's UNTIL.
+- A delayed copy of a create, after the reservation had moved on, answered `idempotency_conflict`
+  instead of `stale_revision`.
+- A time zone a calendar names without a VTIMEZONE was read as floating, and compared with UTC
+  values as if it were UTC. East of UTC a series lost the occurrence its UNTIL names (in a stored
+  series, a booking could then take that time); west of it, a series ran hours past its UNTIL; an
+  EXDATE or a moved occurrence's RECURRENCE-ID written in UTC was not found. All-day series had the
+  same fault with a UTC UNTIL.
+- A feed with a PERIOD RDATE, or an event with no DTEND, was refused whole; a feed's event that
+  ended before it started was refused with `invalid_external_interval` instead of
+  `invalid_icalendar`; a document whose root is not a VCALENDAR read as an empty calendar.
+- The 4,000 occurrences a series may pass from its start were shared by every series in a feed, so
+  three daily series begun in 2023 refused it for good.
+- An EXDATE left its occurrence in when EXDATEs before it named no occurrence (ical.js passes them
+  one per occurrence), or when an RRULE and an RDATE both named it; such an instant was also
+  reported twice. A series of RDATEs with no RRULE left out its DTSTART, its first occurrence.
+- An occurrence starting in an hour the clocks skip ended as it started and was left out; it now
+  lasts its series' exact length, from its DTEND or its DURATION. Others still end on the wall clock.
+- ical.js matched exceptions and compared UNTIL and EXDATE values with a feed's own VTIMEZONE for an
+  IANA name, while Slotlock read the same times through Intl: under a stale definition, a moved
+  occurrence was found in the feed and lost from the series stored from it. Such a name is read
+  through Intl throughout.
+- A series with two RRULEs lost occurrences once either rule ended: ical.js dropped the rule after
+  an ended first one, or the one before any other.
+- A DATE EXDATE of a timed series excluded every occurrence that day from a feed and none from the
+  series stored from it; both now exclude the occurrence at the series' start time that day.
+- A floating UNTIL was read as UTC beside a zoned DTSTART. A RECURRENCE-ID written in another zone
+  than its series' DTSTART did not find its occurrence, and a `RANGE=THISANDFUTURE` one written in
+  UTC moved later occurrences by the wrong amount.
+- `parseTrustedICalendarEvents` did not read times as `parseICalendarChanges` does: a stored
+  all-day series kept an occurrence the feed's UTC EXDATE excludes. An event it cannot hold (no
+  length, say) is now `invalid_icalendar`, not `invalid_external_interval`.
+- A feed naming thousands of time zones it does not define (50,000 spellings of one zone took
+  seconds) is refused past 100, as one defining more than 100 is; a feed listing too many EXDATE
+  values is refused before they are read, not after.
+- A request body sent without `Content-Length` (chunked) was read whole before the size limit
+  applied, so any key holder could make the server hold gigabytes. It is refused as soon as it
+  passes `maxRequestBytes`. The Node adapter no longer aborts a request whose body the server stops
+  reading; it discards the rest once it has answered.
+- `close()` while the Node adapter was still starting left `listen()` pending forever.
+- On the Workers dashboard, `/dashboard/sign-in/` and `/dashboard/callback/` (with a trailing slash)
+  were outside the global sign-in rate limit.
+- The confirmation question for a create did not say that a transparent booking leaves the time
+  free, or name the other fields it sets.
+- `arguments` that were not an object (a string, an array) ran the operation with none; they are
+  now `-32602` on MCP and an invalid message on A2A. Left out or null is still none.
+- A rate-limited A2A request was answered with an MCP error over HTTP 429; it is now A2A's 200
+  envelope with a `RATE_LIMITED` ErrorInfo. `Content-Type` is matched without regard to case.
+- Calls refused before they ran (a client that cannot confirm, a malformed A2A message, a REST body
+  that is not JSON, too large or not an object) were not reported to `onEvent`. On MCP 2026-07-28
+  a confirmation was reported after the call it decided; it now comes first, as elsewhere.
+- An async `onEvent`, `onError` or maintenance `onPass` that rejected was an unhandled rejection,
+  which ends a Node process by default; an `onPass` that threw made a pass that ran count as failed.
+- A hold could take the time a reservation's `bufferAfterMs` keeps busy, and a buffered reservation
+  could be booked over a hold: the buffer bound only tenant-owned reservations to each other.
+- `confirmHold` with the id of a reservation that has an external reference answered as if it had
+  confirmed a hold, describing it without its reference, revision or buffer. It is now
+  `hold_not_found`.
+
 ## 0.1.1 - 2026-10-22
 
 ### Changed

package/CONTRIBUTING.md

@@ -16,7 +16,8 @@ npm test            # tests, build, then the packed-artifact verification
 ```
 
 Database suites (`*.integration.test.ts`) run when `DATABASE_URL` points at a PostgreSQL 16
-database whose connecting role can create roles and extensions, and are skipped otherwise:
+database whose connecting role can create roles, databases and extensions, and are skipped
+otherwise (the upgrade suite builds a database of its own and drops it):
 
 ```sh
 DATABASE_URL=postgresql://slotlock_dev:dev-only-password@localhost:5432/slotlock_test npm test
@@ -29,6 +30,11 @@ role named `slotlock` is the package's schema, which `"$user"` puts first on the
 command-line tool redacts the database password from everything it prints, so a short or
 product-like password rewrites the output the tests read.
 
+Property suites (`*.property.test.ts`) check the engine, time zones, iCalendar parsing and API
+keys on input [fast-check](https://fast-check.dev/) generates, with a new seed each run. A failure
+prints the seed and the shrunk counterexample; add `{ seed, path }` from it to that `fc.assert` to
+replay it, then keep the counterexample as an ordinary test once it is fixed.
+
 ## Sign off your commits
 
 Slotlock uses the [Developer Certificate of Origin](https://developercertificate.org/) instead of a
@@ -71,21 +77,24 @@ that section becomes the release notes.
 
 To release, run **Actions > Release a version** with the version (for example `0.1.1`). It sets the
 version in `package.json`, `package-lock.json`, `server.json` and `slotlock.manifest.json` and dates
-the `## Unreleased` heading (`scripts/prepare-release.sh`) and opens the pull request. GitHub holds
-the checks of a pull request a workflow opens until someone with write access approves them: open it
-and click **Approve workflows to run**. The run then merges it once CI and DCO pass on it, and starts
-`tag-release.yml`, which tags the release commit. The tag starts
-`release.yml` (the suite, then npm and the GitHub release) and `image.yml` (the image, then the MCP
-Registry). npm holds each staged version until a maintainer approves it with two-factor
-authentication (GOVERNANCE.md); the Release run's summary gives the command. A version merged to
-`main` by hand, with its heading dated, is released the same way. After a failed run, run it again
-with the same version: it keeps the release branch the failed run left when that already holds this
-release, so checks approved there still count, replaces it otherwise, and reuses its pull request
-(`scripts/open-release-pr.sh`).
-
-GitHub lets a workflow open pull requests only once an admin allows it (Settings > Actions >
-General > Workflow permissions); `scripts/configure-github.sh` sets it, and the run says so when it
-is off.
+the `## Unreleased` heading (`scripts/prepare-release.sh`), opens the pull request, merges it once CI
+and DCO pass on it, and `tag-release.yml` tags the release commit. The tag starts `release.yml` (the
+suite, then npm and the GitHub release) and `image.yml` (the image, then the MCP Registry). npm holds
+each staged version until a maintainer approves it with two-factor authentication (GOVERNANCE.md);
+the Release run's summary gives the command. A version merged to `main` by hand, with its heading
+dated, is released the same way. After a failed run, run it again with the same version: it keeps
+the release branch the failed run left when that already holds this release, so checks already run
+there still count, replaces it otherwise, and reuses its pull request (`scripts/open-release-pr.sh`).
+
+The pull request is opened and merged by the release app, a GitHub App that can only write this
+repository's contents and pull requests. An owner of the organization creates it once with
+`node scripts/create-release-app.mjs` (click **Create GitHub App**, then install it on `slotlock`
+only); the script checks the installation and stores the app's key in the `release-app` environment,
+which only `main` can use. Without the app, the workflow opens the pull request as
+github-actions[bot], whose checks GitHub holds until someone with write access approves them on the
+pull request (**Approve workflows to run**). GitHub lets a workflow open pull requests at all only
+once an admin allows it (Settings > Actions > General > Workflow permissions);
+`scripts/configure-github.sh` sets it, and the run says so when it is off.
 
 When a run needs a step npm or GitHub keeps for a person (the first npm version, the npm trusted
 publisher, the image's visibility, and the deploy key `tag-release.yml` pushes tags with), the

package/README.md

@@ -37,6 +37,7 @@ docker compose exec slotlock slotlock resource add vehicle-42 --timezone Europe/
 | --- | --- |
 | `http://localhost:8080/mcp` | MCP, with `Authorization: Bearer <SLOTLOCK_AUTH_TOKEN>` |
 | `http://localhost:8080/a2a` | A2A 1.0, same token; card at `/.well-known/agent-card.json` |
+| `http://localhost:8080/v1/…` | [REST](#rest-and-openapi): the tools, and the [application API](#application-api) for admin keys; described at `/openapi.json` |
 | `http://localhost:8080/healthz` | Readiness, including the database |
 
 - The server runs as a role that owns nothing and cannot bypass row-level security; a one-off
@@ -85,6 +86,7 @@ Give each agent its own key instead of sharing the server token:
 ```sh
 slotlock key create "Booking agent"
 slotlock key create "Availability bot" --scope read --expires-in-days 90
+slotlock key create "Booking site" --scope read,write,admin
 slotlock key list
 slotlock key rotate <id>
 slotlock key revoke <id>
@@ -92,8 +94,8 @@ 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. Default:
-  both.
+- `read` covers the five 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
   verify offline.
@@ -265,7 +267,8 @@ export const slot = findNextAvailable({
 // slot: 2026-09-14 10:00–12:00 UTC, the first two free hours after the busy one
 ```
 
-A rule `expandRules` cannot evaluate adds no availability; it never invents a slot.
+A rule `expandRules` cannot evaluate adds no availability; it never invents a slot. A search window
+may be 367 days at most (`invalid_window`), here and in `findNextAvailableFor`.
 
 ## Set up PostgreSQL
 
@@ -411,26 +414,29 @@ export async function scheduleWeeklyInspection(
 ```
 
 Occurrences are stored for a window of at most 367 days and 2,000 occurrences; maintenance rolls
-the window forward. Past it, free/busy reports the time as unproven.
+the window forward, never moving its end back. Outside it, before or after, free/busy reports the
+time as unproven.
 
 A rule is expanded within a budget: 50,000 steps and a second for a feed (the whole read, from its
 text), or for a stored series as maintenance rolls it; half of that for one event as it is written.
-A feed's own time zones (VTIMEZONE) count against the same budget. A feed may carry 100 time zones,
-1,000 of their observances and 2,000 RDATE values in them, and 20,000 RDATE and EXDATE values in
-its events; a property's name and parameters may take 8 KB and list 100. A SECONDLY to WEEKLY step,
-a `DURATION`, or an event's length may be a century at most. A calendar that needs more, such as a
-rule that never occurs (`FREQ=DAILY;BYMONTH=2;BYMONTHDAY=30`), is refused: `invalid_event` on a
-write, `invalid_icalendar` from a feed.
-
-A feed's rules are expanded from their start. A stored series keeps where its last expansion
-stopped, and the next one resumes there, so a daily series keeps rolling for as long as it runs:
-its budget goes on the window, not on the years before it. A write that changes a series searches
-from its start, and resumes from where it stopped only if that search is over the budget. A place
-serves only the rule, start and time zone it was kept for, read by the same version of ical.js, and
-never lies past an occurrence that could still reach the window (one within the event's length and
-a day of it, or one an exception moves into it). Otherwise the series is searched from its start,
-within the same budget. During maintenance, a stored series that outgrows the budget is counted as
-`refused` (its ids in `refusedEventIds`) and keeps its old coverage.
+A feed's own time zones (VTIMEZONE) count against the same budget. A feed may carry 100 time zones
+and name 100 it does not define, 1,000 observances and 2,000 RDATE values in the zones it carries,
+and 20,000 RDATE and EXDATE values in its events; a property's name and parameters may take 8 KB
+and list 100. A SECONDLY to WEEKLY step, a `DURATION`, or an event's length may be a century at
+most. A calendar that needs more, such as a rule that never occurs
+(`FREQ=DAILY;BYMONTH=2;BYMONTHDAY=30`), is refused: `invalid_event` on a write, `invalid_icalendar`
+from a feed.
+
+A feed's rules are expanded from their start, and each series may pass 4,000 occurrences on the way
+(a daily one, about 11 years) whatever the feed's other series take. A stored series keeps where
+its last expansion stopped, and the next one resumes there, so a daily series keeps rolling for as
+long as it runs: its budget goes on the window, not on the years before it. A write that changes a
+series searches from its start, and resumes from where it stopped only if that search is over the
+budget. A place serves only the rule, start and time zone it was kept for, read by the same version
+of ical.js, and never lies past an occurrence that could still reach the window (one within the
+event's length and a day of it, or one an exception moves into it). Otherwise the series is searched
+from its start, within the same budget. During maintenance, a stored series that outgrows the budget
+is counted as `refused` (its ids in `refusedEventIds`) and keeps its old coverage.
 
 ### External calendars
 
@@ -440,6 +446,24 @@ Slotlock gives them neutral boundaries:
 - `normalizeExternalCalendarChange` for webhook changes; `parseICalendarChanges` and `emitICalendar`
   for bounded iCalendar in and out; `emitITipCalendar` for invitations.
 - All-day events become whole local days in the calendar's time zone; a feed without one is refused.
+- A TZID Intl knows is read as that IANA zone, whether or not the feed defines it (a VTIMEZONE's
+  own rules for such a name are not used); one only the feed defines, such as a Windows name, is
+  read from its VTIMEZONE. A floating time is read in the calendar's zone. So an UNTIL, EXDATE,
+  RDATE or RECURRENCE-ID written in UTC or another zone names the occurrence it means, a floating
+  UNTIL is read on the series' own clock, and a `RANGE=THISANDFUTURE` exception moves every later
+  occurrence by its own shift.
+- An event with no length (a DATE-TIME DTSTART without DTEND or DURATION) occupies no time and is
+  left out. A PERIOD RDATE ends where its period does. A document whose root is not a VCALENDAR, or
+  an event that ends before it starts, is refused as `invalid_icalendar`.
+- A series' DTSTART is its first occurrence, with or without an RRULE; every RRULE is expanded; an
+  instant two of them, or an RRULE and an RDATE, name is one occurrence; every EXDATE excludes the
+  occurrence it names (RFC 5545 §3.8.5). A DATE EXDATE of a timed series names the occurrence at the
+  series' start time that day.
+- An occurrence ends on the wall clock, as calendars show it (00:30-02:30 lasts three hours the
+  night the clocks go back). One that starts in an hour the clocks skip lasts its series' exact
+  length instead, from the offset before the gap (RFC 5545 §3.3.5).
+- `parseTrustedICalendarEvents` reads times as `parseICalendarChanges` does, so a series stored from
+  it occupies what the feed reports.
 - `recordCalendarCoverage` marks how much of a feed is read. Pass the sources a resource depends on as
   `requiredSources`, and any coverage short of `complete` means the time is not proven free.
 
@@ -625,10 +649,10 @@ on stderr.
 
 | Where | Error |
 | --- | --- |
-| HTTP | `401` with `WWW-Authenticate`, `403` disallowed origin, `413`/`415` bad body, `429` rate limit |
-| MCP | `-32602` unknown tool or altered confirmation, `-32603` server fault, `-32601` unknown method |
+| 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 | `-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` streaming, `-32001` task not found (the server keeps no tasks) |
 
 ### Authentication and OAuth discovery
 
@@ -655,6 +679,8 @@ With `confirmation`, a listed write first asks the person a yes/no question that
 will change, such as `Book vehicle-42 for 2027-03-29 10:00–11:00 (Europe/London): "Vehicle
 handover".` Only an explicit yes runs the write.
 
+- A booking that leaves the time free (`transparency: 'transparent'`) says so, and a write names
+  the other fields it sets (`also description, attendees`) without quoting them.
 - Facts come first: the resource by its own reference, times in its own zone, and an event as it
   stands now, read through your backend's `describeResource` and `getEvent` when the caller may
   read them (within 2 seconds in all). Otherwise things are named by id, and each time carries its
@@ -685,10 +711,29 @@ returns busy time and coverage for the next `resourceWindowDays` (30). `subscrip
 2026-07-28 results carry cache hints: discovery and tool lists are public for an hour, free/busy is
 never cached. W3C `traceparent`, `tracestate` and `baggage` reach your backend as `context.trace`.
 
+`onEvent` hears about every call that names an operation, so you can count, time and correlate them:
+
+- `{ type: 'call', protocol, operation, outcome, durationMs, traceId? }` for an MCP `tools/call` or
+  A2A `SendMessage`; `outcome` is `ok`, the refusal's code (`overlap`, `rate_limited`, …), or why
+  it was refused before it ran: `invalid_arguments`, `missing_capability` (a guarded write from a
+  client that cannot confirm), `invalid_message` or `invalid_message_parameters` (A2A).
+- `{ type: 'rest', operation, status, durationMs, traceId? }` for a REST call, or one refused before
+  it ran: a body that is not JSON (415, 400), too large (413) or not an object (400).
+- `{ type: 'confirmation', operation, outcome }` for each confirmation, before the call it decides.
+- A request refused before its operation is read is not reported: a missing credential, the rate
+  limit, an `A2A-Version` other than 1.0, a JSON-RPC envelope that does not parse, a path no route
+  has.
+- `traceId` is the trace id of a valid `traceparent` from `_meta` or the header. Arguments, callers,
+  the parent span, `tracestate` and `baggage` are never reported, and an `onEvent` or `onError` that
+  throws, or returns a promise that rejects, changes nothing a client sees. Resource reads and
+  subscription polls are not reported.
+
+`slotlock serve` writes each as a JSON line (`"event":"call"`, `duration_ms`, `trace_id`).
+
 ### REST and OpenAPI
 
-`rest: true` (`SLOTLOCK_REST_API=on` for `slotlock serve`) also serves each tool as plain HTTP,
-described by an OpenAPI 3.1 document at `/openapi.json`:
+`rest: true` also serves each tool as plain HTTP, described by an OpenAPI 3.1 document at
+`/openapi.json`. `slotlock serve` has it on; `SLOTLOCK_REST_API=off` turns it off.
 
 | Request | Tool |
 | --- | --- |
@@ -706,14 +751,66 @@ curl "http://localhost:8080/v1/resources" -H "Authorization: Bearer $SLOTLOCK_AP
 ```
 
 - `GET` and `DELETE` take the tool's arguments as query parameters (a list repeats:
-  `resource_ids=a&resource_ids=b`); `POST` and `PATCH` take a JSON body. The event id is in the path.
+  `resource_ids=a&resource_ids=b`); `POST`, `PUT` and `PATCH` take a JSON body. Ids are in the path;
+  percent-encode one that holds `/`.
 - Keys, scopes, `authorize` and the rate limit apply as over MCP. The body is the tool's output, or
   `{"error":{"code":…}}` with the matching HTTP status.
 - REST cannot ask a person, so a write listed in `confirmation` answers `428 confirmation_required`.
 - There are no CORS headers: call it from a server, not a browser.
+- From Python, Go, Rust, Java or .NET, use the [clients](clients/README.md): one method per
+  operation, the application API included, each tested against the server in CI. For another
+  language, generate one from [`openapi.json`](openapi.json) (or a server's `/openapi.json`) with any
+  OpenAPI 3.1 generator.
+
+### Application API
+
+What the application around the agents does, from any language: the store's resource, hours, hold,
+reservation, coverage and maintenance calls, as REST beside the tools. It needs a key with the
+`admin` scope ("Full" in the dashboard); the server's own `SLOTLOCK_AUTH_TOKEN`, the token agents
+are given, reads and writes but is never admin. It is never an MCP tool or an A2A skill, and never
+waits for a confirmation.
+
+| Request | Does |
+| --- | --- |
+| `POST /v1/resources` | Create the resource with this `external_ref`, or update its `timezone` |
+| `GET /v1/resources/{resource_id}` | One resource, with its own weekly hours |
+| `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 |
+| `POST /v1/holds` | Hold a window for `ttl_seconds` (up to 7 days) |
+| `POST /v1/holds/{hold_id}/confirm` | Turn the hold into a reservation |
+| `DELETE /v1/holds/{hold_id}` | Release the hold |
+| `PUT /v1/reservations/{reservation_ref}` | Book (`revision: 1`) or move (the current revision plus 1) |
+| `DELETE /v1/reservations/{reservation_ref}?revision=…` | Cancel, at the current revision plus 1 |
+| `PUT /v1/resources/{resource_id}/coverage/{source}` | Record that `source`'s events are complete for a window |
+| `POST /v1/maintenance` | Run [maintenance](#operations) for the key's tenant |
+
+```sh
+curl -X PUT "http://localhost:8080/v1/reservations/BK-42" \
+  -H "Authorization: Bearer $SLOTLOCK_ADMIN_KEY" -H "Content-Type: application/json" \
+  -d '{"resource_id":"<id>","start":"2027-03-29T09:00:00Z","end":"2027-03-31T09:00:00Z",
+       "buffer_after_minutes":60,"revision":1}'
+```
+
+- A taken window answers `409 overlap`. `buffer_after_minutes` keeps the time after a reservation
+  busy for holds and other reservations alike.
+- Every write is safe to retry: the same reservation at its current revision answers
+  `replayed: true`, a confirmed hold confirms again, and a cancelled reference stays cancelled (a
+  late booking for it answers `409`). A late copy of a booking or a move that has since been
+  superseded answers `409 stale_revision`.
+- The time a calendar event occupies is the event's: reservation calls never find, move or cancel
+  it, whatever reference they name. Change the event instead.
+- The tenant is the key's. Another tenant's resource or hold is `404`, whatever the database role.
+- With the library, pass `application` beside `rest: true`:
+  `{ backend: createSlotlockStoreApplicationBackend(store, { maxTenantResources }), authorize }`.
+  A principal with `scopes` needs `admin`; then `authorize` decides.
 
 ## Connect an agent
 
+MCP and A2A are wire protocols, so an agent in any language connects with its own MCP or A2A client
+to `/mcp` or `/a2a`, the API key as a bearer token. The examples below use TypeScript. Code that
+calls Slotlock directly, without an agent, can use the [REST clients](clients/README.md) for
+Python, Go, Rust, Java and .NET.
+
 ### MCP (any client)
 
 <!-- example: examples/mcp-client.ts#mcp -->
@@ -878,62 +975,37 @@ and never writes.
 
 ## Operations
 
-Run this at least daily for every tenant:
+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 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
+  other's work; a pass that finds the lock taken does nothing.
+
+In a process of your own:
 
 <!-- example: examples/maintenance.ts#maintenance -->
 ```ts
-import {
-  type CalendarHorizonRollCursor,
-  type CalendarHorizonRollResult,
-  type SlotlockStore,
-  calendarEventRollingHorizon,
-} from 'slotlock';
-
-const MAX_BATCHES = 10;
+import { type SlotlockStore, maintainSlotlockTenant } from 'slotlock';
 
 export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
-  const window = calendarEventRollingHorizon();
-  let extended = 0;
-  let conflicts = 0;
-  let refused = 0;
-  let horizonCapped = true;
-  let after: CalendarHorizonRollCursor | null = null;
-  for (let batch = 0; batch < MAX_BATCHES; batch++) {
-    const from = after;
-    const roll: CalendarHorizonRollResult = await store.withTenant(tenantRef, (tenant) =>
-      tenant.rollCalendarEventHorizon({ tenantRef, window, ...(from ? { after: from } : {}) }),
-    );
-    extended += roll.extended;
-    conflicts += roll.conflicts;
-    refused += roll.refused;
-    after = roll.next;
-    if (!after) {
-      horizonCapped = false;
-      break;
-    }
-  }
-
-  let pruned = 0;
-  let retentionCapped = true;
-  for (let batch = 0; batch < MAX_BATCHES; batch++) {
-    const prune = await store.withTenant(tenantRef, (tenant) =>
-      tenant.pruneCalendarEventRetention({ tenantRef }),
-    );
-    pruned += prune.commandsDeleted + prune.tombstonesDeleted;
-    if (!prune.hasMore) {
-      retentionCapped = false;
-      break;
-    }
-  }
-  return { extended, conflicts, refused, pruned, capped: horizonCapped || retentionCapped };
+  // Extends recurring events to the rolling horizon, then prunes past the retention window, each in
+  // at most ten batches. `capped: true` means work was left: run another pass.
+  return maintainSlotlockTenant(store, tenantRef, { batches: 10 });
 }
 ```
 
-- **Run maintenance at least daily for every tenant.** Forced RLS hides other tenants from the
-  application role, so iterate your own tenant list.
-- **Page the roll with `next`.** Pass each batch's `next` as `after` to the next batch of the same
-  pass. A series left in conflict or refused keeps its place at the front of the order, so without
-  `after` every later batch would examine it again.
+- **Every tenant.** Forced RLS hides other tenants from the application role, so iterate your own
+  tenant list. `startSlotlockMaintenance({ store, sql, tenants, intervalMs })` is the scheduler
+  `serve` uses, lock included; `withSlotlockMaintenanceLock` is the lock alone.
+- **Capped passes.** A capped pass that extended and pruned nothing met only series it cannot extend
+  (counted in `conflicts` and `refused`): another pass would too, so wait for the next interval.
+- **Paging the roll yourself.** `rollCalendarEventHorizon` returns `next`; pass it as `after` to the
+  next batch of the same pass. A series left in conflict or refused keeps its place at the front of
+  the order, so without `after` every later batch would examine it again.
 - **Quotas.** Each agent principal may retain 1,000 event identities (active plus cancelled) and
   10,000 idempotency commands, of which 9,000 can be creates or updates, so a cancel always has
   room. Adjust with `agentOwnerEventQuota` and `agentOwnerCommandQuota` on `createSlotlockStore`.
@@ -964,6 +1036,10 @@ export async function maintainTenant(store: SlotlockStore, tenantRef: string) {
 8. Keep writes confirmation-gated wherever your policy needs a person.
 9. Size live updates: 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` checks health,
+    discovery, MCP, A2A, holds and reservations (in a resource named `slotlock-smoke`, 400 days
+    ahead, cancelled after) and the 401, 409, 413 and 415 refusals.
 
 ## Supported versions
 

package/SECURITY.md

@@ -7,9 +7,10 @@ documented breaking changes; security releases will identify the lowest safe ver
 
 ## Report a vulnerability
 
-Do not open a public issue. Report privately through GitHub's private vulnerability reporting on the
-repository that publishes the package: open its **Security** tab and choose **Report a
-vulnerability**. The maintainers listed in [MAINTAINERS.md](./MAINTAINERS.md) receive the report.
+Do not open a public issue. Report privately through GitHub's private vulnerability reporting:
+<https://github.com/PILOTAAI/slotlock/security/advisories/new> (the repository's **Security** tab,
+**Report a vulnerability**). The maintainers listed in
+[MAINTAINERS.md](https://github.com/PILOTAAI/slotlock/blob/main/MAINTAINERS.md) receive the report.
 Include:
 
 - the affected version and surface;
@@ -18,7 +19,8 @@ Include:
 - any known mitigations.
 
 Do not include real customer, credential, calendar, or booking data. We will acknowledge a report
-within three business days and coordinate disclosure after a fix is available.
+within three business days and coordinate disclosure after a fix is available. Fixed vulnerabilities
+are published as advisories at <https://github.com/PILOTAAI/slotlock/security/advisories>.
 
 ## Security model
 
@@ -28,6 +30,16 @@ PostgreSQL exclusion constraint. Tenant policies are forced and fail closed when
 context is missing. Embedding applications remain responsible for authentication, authorization,
 provider-secret storage, webhook verification, network egress, and erasure.
 
+Upgrading repairs data across tenants (expired holds in a turnaround buffer, duplicate resources,
+archives and event details from earlier versions), which forced policies would hide from the owning
+role. `applySchema` therefore lifts FORCE from the tables that have it for its data steps and puts
+it back on exactly those, inside its one locked transaction: a failure rolls the lift back with the
+rest. Run statement by statement instead (psql without `--single-transaction`), a refused step
+stops the run with FORCE lifted. The tables lifted are recorded in
+`slotlock.deployment_lifted_row_security`, so the next deployment, from any session, puts FORCE back
+on each of them, and until it does `slotlock serve` refuses to start (`row_security_lifted`). Run
+the deployment DDL through `applySchema` or `slotlock migrate`.
+
 Application traffic must use a role that cannot leave forced RLS. `grantApplicationRole` grants
 such a role schema usage and DML on the tenant tables, and first refuses the known ways out, whether
 the role holds them itself, through a role it belongs to, or through `PUBLIC`, and names the ones
@@ -97,3 +109,27 @@ embedder's `authenticate` must verify every token, including its audience. Embed
 bearer-token verification, per-principal authorization, distributed rate limiting, TLS termination,
 and a readiness check. Do not place provider credentials or raw calendar content in authentication,
 authorization, rate-limit, or health callbacks.
+
+## API keys and the application API
+
+An API key is `slk_`, 40 base62 characters from the operating system's random source (about 238
+bits) and a 6-character checksum, and the database keeps only its SHA-256. A slow password hash
+(bcrypt, scrypt, Argon2) defends a secret a person chose against offline guessing; nobody can guess
+238 random bits, so a fast hash
+loses nothing and lets every request look a key up by its digest in one indexed read. Code scanners
+that treat every secret as a password report this as weak hashing (CodeQL
+`js/insufficient-password-hash`); it is the design, as for GitHub's and Stripe's tokens.
+
+A key acts only in the tenant it was created for. `read` and `write` cover the agent tools; `admin`
+covers the application API (resources, hours, holds, reservations, coverage, maintenance), which is
+never offered to agents over MCP or A2A. Every application operation checks the tenant itself, not
+only through row-level security: another tenant's resource or hold is not found even on a connection
+that bypasses RLS.
+
+## Dependencies
+
+The published package depends on `ical.js`, `rrule` and `zod`, and on `postgres` as a peer; the
+image adds nothing else. The documentation site (`site/`) is built with Astro and Starlight, and
+those development dependencies never reach the package or the image. `braces`, which the site's
+`starlight-llms-txt` reaches through `micromatch`, has an open denial-of-service advisory with no fixed
+release; it only expands the site's own glob patterns at build time, so no outside input reaches it.