slotlock 0.1.1 → 0.3.0

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,22 @@ 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>.
+
+## Testing hosted Slotlock
+
+Hosted Slotlock (`slotlock-api.pylota.io` and `app.slotlock.pylota.io`, run by TREFT LTD) is in scope,
+under these rules, which its [Terms of Service](TERMS.md) and
+[Acceptable Use Policy](ACCEPTABLE-USE.md) refer to:
+
+- Test only against an account of your own, signed in with your own GitHub account.
+- Never read, change or keep another account's data. If a test reaches any, stop and report it at
+  once, and delete what you saw.
+- Run no denial of service, load test or automated scanning that sends more than the published
+  limits ([hosted service page](docs/hosted/README.md#limits)); run Slotlock yourself for that.
+- Report through private vulnerability reporting as above, and give us the time to fix it before
+  you disclose anything.
 
 ## Security model
 
@@ -28,6 +44,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
@@ -96,4 +122,43 @@ protected-resource metadata, when configured, only tells clients where to obtain
 embedder's `authenticate` must verify every token, including its audience. Embedders must provide
 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.
+authorization, rate-limit, or health callbacks. `slotlock serve`, its own embedder, limits requests
+per client address before any credential is looked up, then per key, per tenant and for the whole
+server, caps writes that expand a recurring series, maintenance runs and live-update streams per
+tenant, answers a full key-lookup queue as busy rather than unauthenticated, and logs counts of
+refusals with each client as a pseudonym (`SLOTLOCK_LIMITS`, `SLOTLOCK_TRUSTED_PROXY_HEADER`). A
+key that authenticated in the last 15 minutes waits in a lookup queue of its own, served first; a
+valid key that has not authenticated in the last 15 minutes (any key, after a restart) waits with
+made-up keys and may be answered busy (503 with `Retry-After`) while a flood of them lasts, never
+401. Its counts are one process's: several instances each limit alone.
+
+Write confirmation (MCP 2026-07-28 form elicitation) seals the pending write to the caller, the tool
+and its exact arguments, but the answer comes from the client: Slotlock relies on the MCP client to
+ask its person, and a key holder's own client can answer yes. It keeps an agent from writing unasked;
+it is not an authorization boundary. Scopes and `authorize` decide who may write.
+
+## 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. The
+repository's CodeQL configuration (`.github/codeql/codeql-config.yml`) drops that one query with
+this reason beside it, rather than dismissing its alerts one by one.
+
+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.

package/SPEC.md

@@ -1,7 +1,8 @@
 # Slotlock agent-calendar specification 1.0
 
-This document defines the interoperable scheduling semantics of Slotlock 0.1. Implementations may use
-different transports or persistence layers, but must preserve these rules when claiming compatibility.
+This document defines the interoperable scheduling semantics of Slotlock 0.2 and later.
+Implementations may use different transports or persistence layers, but must preserve these rules
+when claiming compatibility. Which of them may change between releases is in VERSIONING.md.
 
 ## Resource model
 
@@ -15,8 +16,71 @@ rule assumes a particular industry.
 - Availability rules use local wall time in the resource's IANA timezone.
 - Every interval is half-open `[start, end)`. `end` must be strictly after `start`.
 - Adjacent intervals do not conflict. Overlapping or touching availability windows may be merged.
-- Daylight-saving gaps move a nonexistent wall time forward by the gap. Ambiguous fall-back wall
-  times resolve to the first occurrence.
+- An event's time zone is an IANA name, kept in its canonical spelling (`europe/london` is stored
+  as `Europe/London`). A UTC offset such as `+05:00` is not a zone, and an event in one is refused.
+- An event time in an hour the clocks skip moves forward by the gap, and one in an hour they repeat
+  is its first instant (RFC 5545 §3.3.5), except where "Daylight-saving time" below says otherwise.
+- An availability window's edge in an hour the clocks skip stands where that hour ends, so a window
+  holds only the wall times it names that exist: in New York on 2027-03-14, [02:30, 03:30) is
+  03:00-03:30 EDT and [02:00, 02:30) is nothing. An edge in a repeated hour is its first instant.
+
+## Daylight-saving time
+
+An occurrence of a timed recurring event starts at its wall time read as above, and ends at the
+later of two readings:
+
+- its exact end: its start plus the series' exact length, DTEND − DTSTART as instants (RFC 5545
+  §3.8.5.3), or its DURATION, whose days and weeks are calendar days and whose hours, minutes and
+  seconds are exact (§3.3.6);
+- its wall-clock end: DTEND's wall time as written, carried to the occurrence's date (one written
+  in an hour the clocks skip is carried as written), the later instant where the clocks repeat
+  that hour. A stored series keeps its first occurrence as instants, and reads this end from its
+  end instant.
+
+It occupies `[start, later end)`, so whichever way people read an occurrence that the clocks
+change inside, none of the time they hold is offered as free. A stored series' first occurrence
+starts at the instant stored, which may be the second pass of a repeated hour. One-off events,
+overrides (moved occurrences) and PERIOD RDATEs occupy exactly the times they give. Display and
+export keep each event as written. Feeds, the trusted importer and the store read events this way
+in every zone, including zones whose rules changed in the past and zones a feed defines only by
+its VTIMEZONE.
+
+A series' occurrences never overlap each other. Where one ends after the next starts (24 exact
+hours from midnight run to 01:00 the night the clocks go forward, or an occurrence is longer than
+the series' period), it ends where the next starts, and the next ends at the later of the two ends.
+Together they hold the same time, and the store, which keeps each occurrence as a reservation
+under one EXCLUDE constraint, can hold them. Two that start at the same instant are left as they
+are. An all-day series occupies whole local days, from one local midnight to the next (a midnight
+the clocks skip moves forward).
+
+| Case | Example | Occupies |
+| --- | --- | --- |
+| The clocks go forward inside an occurrence | London, daily 00:00-06:00, 2027-03-28 | six exact hours, 00:00Z-06:00Z |
+| The clocks go back inside an occurrence | London, daily 00:00-06:00, 2026-10-25 | seven wall-clock hours, 2026-10-24 23:00Z-06:00Z |
+| The clocks go back, southern hemisphere | Santiago, daily 22:00-04:00, night of 2027-04-03 | seven hours, 2027-04-04 01:00Z-08:00Z |
+| The clocks go forward, southern hemisphere | Auckland, daily 00:00-06:00, 2027-09-26 | six hours, 2027-09-25 12:00Z-18:00Z |
+| A day long, the clocks go forward | London, daily 00:00-00:00 from 2027-03-26 | on 2027-03-28, 00:00Z-23:00Z, where the next day starts |
+| A week long, the clocks go forward | New York, weekly 00:00 for 168 hours from 2027-03-07 | the second week 2027-03-14 05:00Z to 03-21 04:00Z |
+| An all-day series | Santiago, daily from 2027-09-03 | on 2027-09-05, 04:00Z (01:00, midnight being skipped) to 09-06 03:00Z |
+| An occurrence starts in the skipped hour | Berlin, daily 02:30 for 75 minutes, 2027-03-28 | 75 exact minutes from 01:30Z (03:30 CEST) |
+| A half-hour change | Lord Howe, daily 02:00-02:45, 2027-10-03 | 45 minutes from 2027-10-02 15:30Z |
+| DTEND falls in the repeated hour | New York, daily 23:00-01:30 from 2026-10-31 | 2026-11-01 03:00Z to the later 01:30, 06:30Z |
+| DTEND falls in the skipped hour | New York, daily 01:00-02:30 from 2027-03-14 | the first 06:00Z-07:30Z, as written; later days 90 minutes, to the written 02:30 |
+| The first instance spans the change | Berlin, weekly 01:00-04:00 from 2027-03-28 | as written, 00:00Z-02:00Z; later weeks three hours |
+| An occurrence starts in the repeated hour | London, daily 01:15-01:45 from 2026-10-20 | on 2026-10-25, its first 01:15 (00:15Z) to the later 01:45 (01:45Z) |
+| A stored first occurrence in the repeated hour | London, stored from 2026-10-25 01:15Z | the second 01:15, as stored |
+| A length the clocks reduce to nothing | DTSTART and DTEND both in one skipped hour, the end at its close | refused |
+
+A series whose DTSTART the clocks skip is read from a feed (from the offset before the gap) but is
+not stored: no instant reads back as its wall time. The same holds for an all-day series whose
+first day's midnight the clocks skip (Santiago and Havana go forward at midnight). The trusted
+importer stores an all-day series as a timed one from local midnight to local midnight, which the
+union rule holds to its exact length too: where the clocks go forward on one of its days, or at the
+midnight its first occurrence ends, it may also hold the hour after a midnight that the feed's days
+do not, never less. The trusted importer does not store a timed series whose DTEND the clocks skip, or
+whose DURATION counts days or weeks outside UTC: kept as its first occurrence's instants, the first
+would hold an hour the feed does not on every later day, and the second on each day it spans that
+the clocks go forward.
 
 ## Availability
 
@@ -24,7 +88,7 @@ Availability is the intersection of explicit bookable windows and the complement
 No rule means no availability. Unsupported or invalid rules contribute no availability. A next-slot
 answer must fit wholly inside the resulting free set for the requested positive duration.
 
-Slotlock 0.1 supports weekly RRULE cadence with explicit `BYDAY`, interval 1, optional absolute
+Weekly availability supports RRULE cadence with explicit `BYDAY`, interval 1, optional absolute
 `UNTIL`, a local start minute, and a positive duration. Rules requiring an authored recurrence anchor
 such as `COUNT` or interval greater than 1 fail closed.
 
@@ -33,7 +97,9 @@ such as `COUNT` or interval greater than 1 fail closed.
 - The persistence layer is the final conflict arbiter; an application pre-check is not authority.
 - A live hold occupies the same range as a confirmed reservation until its database-clock expiry.
 - Confirm and release operations are atomic and idempotent for their expected retry cases.
-- A trailing buffer extends occupied time without changing the customer-visible end instant.
+- A hold lasts at most 7 days from its creation.
+- A trailing buffer extends occupied time without changing the customer-visible end instant. It is
+  at most 30 days, and holds and reservations alike respect it.
 - External commands use `(tenantRef, externalRef)` as stable identity and a strictly increasing
   positive revision. A replay with the same revision and payload is idempotent; drift is rejected.
 - Cancellation leaves a revisioned tombstone so delayed delivery cannot resurrect the identity.
@@ -58,6 +124,13 @@ the provider, map a connection to one resource, normalize status/transparency/re
 durable cursor and coverage window, and reconcile deletions. iCalendar parsing must remain bounded by
 input size, components, exceptions, occurrences, work, and expansion horizon.
 
+A feed's overrides occupy what the provider shows: one without DTEND or DURATION lasts its series'
+length, and one whose RECURRENCE-ID names no occurrence, or whose occurrence the series also
+EXDATEs, occupies its own time. The instances of a CalDAV-expanded series are each read, the first
+with or without a RECURRENCE-ID. An event with both DTEND and DURATION is refused (RFC 5545
+§3.6.1). A reader that can name refused series refuses one series at a time and reads the rest of
+the feed; one that cannot refuses the feed, so a refused series is never read as free time.
+
 Content not required for conflict decisions should be discarded before reaching an agent. Outbound
 iCalendar updates retain stable UID and monotonic sequence; cancellation is explicit.
 
@@ -71,12 +144,37 @@ the key with drift fails. Cancellation atomically removes derived occupation and
 tombstone; delayed create delivery cannot resurrect the UID.
 
 Events may carry organizer, attendees, roles, participation status, RSVP requests, display/email
-relative reminders, one RFC 5545 RRULE, and bounded recurrence exceptions. A materialization window is
-mandatory for recurring events, must not exceed 367 days, and may produce at most 2,000 occurrences
-under one 4,000-step work budget. Opaque occurrences are reservations under the same PostgreSQL EXCLUDE
-constraint as bookings and holds. Transparent occurrences remain queryable but occupy no resource.
-An event update replaces its materialized set transactionally, so an overlap rolls the entire mutation
-back and preserves the prior event.
+relative reminders, one RFC 5545 RRULE, and bounded recurrence exceptions. A materialization window
+is mandatory for recurring events, must not exceed 367 days, and may produce at most 2,000
+occurrences. Expansion is bounded by a count of work, never a clock, so an input is accepted or
+refused the same way however loaded the machine: each series may pass 4,000 occurrences from its
+start, and an expansion may take 50,000 steps for an event as it is written and 500,000 for a feed
+or a stored series as maintenance rolls it. A step of ical.js's search costs three, a weekday it
+compares one, a day it walks a fifth, a year it scans three and an eighth for each day that scan
+lists, and a weekday of a year it lists half. Each occurrence passed costs one, each conversion of a
+time in an IANA zone half (one and a half in a zone only a feed defines), and each instant Intl is
+asked for to read a zone's offsets five, charged the first time the expansion reads that day of the
+zone whatever was read before it. Each change listed when a feed's own zone is expanded costs four
+tenths. A zone written the way Outlook writes them, from 1601, costs about 6,000.
+
+A stored rule is daily or less frequent, follows RFC 5545 §3.3.10's grammar (every part known and
+given once, `COUNT` at least 1, never `COUNT` with `UNTIL`), and is of a shape the expander reads
+as RFC 5545 does: `BYWEEKNO`, a two-digit `BYDAY` ordinal, `BYSETPOS` other than with
+`FREQ=MONTHLY` and `BYDAY` alone, `BYMONTH` with `FREQ=MONTHLY`, a negative `BYMONTHDAY` other
+than with `FREQ=MONTHLY` and no `BYDAY`, `FREQ=YEARLY` with `BYMONTHDAY` but no `BYMONTH` or with a
+day none of its months has, with `COUNT` or `BYDAY` and a day one of its months can lack, with
+`BYYEARDAY` and `BYMONTH` or `BYMONTHDAY`, or with a numbered `BYDAY` and `BYMONTHDAY`, and time
+parts with `FREQ=MONTHLY` or `YEARLY` are refused, with a reason. A yearly day some years lack (29
+February, or a 31st with April) occurs only in the years that have it (RFC 5545 §3.3.10), so its
+rule must be its series' only source of occurrences, with no RDATE or second RRULE. A DATE `UNTIL`
+on a timed series includes its whole day on the series' clock.
+
+A recurrence exception names the occurrence it changes by that occurrence's instant, exported as a
+UTC `RECURRENCE-ID`; one that names no occurrence is refused. Opaque occurrences are reservations
+under the same PostgreSQL EXCLUDE constraint as bookings and holds. Transparent occurrences remain
+queryable but occupy no resource. An event update replaces its materialized set transactionally,
+so an overlap rolls the entire mutation back and preserves the prior event. An exported calendar
+holds a VTIMEZONE (RFC 5545 §3.6.5) for the zone its times name, written from the IANA rules.
 
 Full event content is accepted only by the explicit trusted parser. The provider-normalization parser's
 return type contains only identity, recurrence identity, interval, deletion, busy, and revision. A
@@ -89,7 +187,8 @@ contains the entire window. Any missing, stale, or partial source is returned by
 silently treated as free time.
 
 An event has a finite, positive duration. A one-off event may last up to 3,660 days and its
-occupation matches the event exactly; a recurring event's occurrences are materialized as above. An
+occupation matches the event exactly; a recurring event's occurrences are materialized as above,
+each occupying what "Daylight-saving time" says. An
 all-day (`VALUE=DATE`) iCalendar event covers whole local days of the calendar's timezone, from local
 midnight to local midnight, taken from the caller's calendar timezone, else the feed's
 `X-WR-TIMEZONE`; with neither the input is refused, never read in the server's zone. An all-day
@@ -129,19 +228,29 @@ event, an exhausted quota) is a result, not a protocol error:
 - A2A returns the agent's reply message with one `application/json` data part holding the result or
   `{"error":{"code":"…"}}`.
 
-Protocol errors stay in the protocol. MCP: an unknown tool is JSON-RPC `-32602`, a server fault
+A body must be `application/json`, compared without regard to case (RFC 9110 §8.3.1), or the request
+is HTTP 415; one longer than the server's limit is HTTP 413, refused as soon as it passes the limit,
+whether or not it declares a `Content-Length`.
+
+Protocol errors stay in the protocol. MCP: an unknown tool, or `arguments` that are not an object
+(left out or null is none), is JSON-RPC `-32602`, a server fault
 (including backend output that violates the declared schema) is `-32603` with HTTP 500, and a
 missing or unsupported `MCP-Protocol-Version` header is HTTP 400. A 2026-07-28 request is checked in
 that revision's order, each failure HTTP 400: a missing or malformed `_meta` field is `-32602`, an
 `MCP-Protocol-Version`, `Mcp-Method` or (Base64-sentinel-decoded) `Mcp-Name` that disagrees with the
 body is `-32020`, and an unimplemented revision is `-32022` naming the supported ones. An
 unimplemented method is HTTP 404 `-32601`; a rate-limited request is HTTP 429 `-31029`, outside the
-`-32020`..`-32099` range that revision reserves. A2A: every JSON-RPC error travels
-in an HTTP 200 envelope with a `google.rpc.ErrorInfo` detail; an `A2A-Version` other than `1.0`,
-including none (read as 0.3), is `VersionNotSupportedError` (`-32009`); push-notification methods are
+`-32020`..`-32099` range that revision reserves. A2A: every JSON-RPC error travels in an HTTP 200
+envelope (a body over the size limit is HTTP 413); A2A's own errors, below, carry a
+`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
-`{"skill": "<id>", "arguments": {…}}` is `-32602`. The server replies with messages and keeps no
+`{"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
 `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
@@ -195,8 +304,10 @@ that span changed, so the passage of time alone announces nothing. It ends a
 subscription gracefully, with the listen request's result, at its maximum duration, on shutdown, or
 when a re-read is refused as unauthenticated, unauthorized or not found; it closes the stream without
 a result after three consecutive failed re-reads or when the reader leaves more than 256 events
-unread. Open subscriptions, counted from the moment they start opening, are capped per principal and
-per server. A subscription that honors nothing ends right after its acknowledgment.
+unread. Open subscriptions, counted from the moment they start opening, are capped per principal,
+per tenant and per server. When the server is full, a listen from a tenant holding fewer than the
+tenant holding most, less one, ends that tenant's oldest open stream gracefully, as at shutdown,
+rather than being refused. A subscription that honors nothing ends right after its acknowledgment.
 
 ### Discovery and authorization
 
@@ -210,6 +321,32 @@ so each must be a canonical URL without credentials, query or fragment: `https`,
 when `allowInsecureLocalhost` is set. Publishing metadata grants nothing: the embedder's
 `authenticate` verifies every token, including its audience.
 
+### Scopes, API keys and the application API
+
+Every authenticated principal carries a tenant and scopes from `read`, `write` and `admin`. A read
+operation needs `read`; an event write needs `write`. The application API (resources, weekly hours,
+holds, reservations, coverage, every key's events, the tenant itself and maintenance, as REST under
+`/v1` beside the tools) needs `admin`. It is never an MCP tool or an A2A skill and never waits for a
+confirmation. Through it a tenant may cancel any of its events, whichever key wrote it, and, only
+where the server allows it and with its own reference as confirmation, erase itself; it never
+suspends itself or lifts a suspension, which only the deployment role does.
+
+An API key is a random secret, stored only as its SHA-256 digest and reached only through
+`SECURITY DEFINER` functions. It acts in the tenant it was created in, with the scopes it was given
+(`read` and `write` by default), until it expires (at most 3,650 days) or is revoked. A tenant holds
+at most 100 active keys and 1,000 in all. The digest of a rotated or erased key is kept, so that key
+is never valid again. A server's own bearer token is never `admin`.
+
+A dashboard signs a person in with GitHub, asking for no scope, to the tenant `github:<user id>`,
+and manages that tenant's keys, resources (at most 100) and weekly hours.
+
+### Maintenance
+
+Recurring events are materialized up to the rolling horizon. Maintenance extends each series to it
+and deletes commands and tombstones past the retention window, in bounded batches; a run that
+reaches its batch limit says so, and the next run continues. `slotlock serve` maintains each tenant
+it serves every hour; `slotlock maintain` and the application API run it on demand.
+
 ### Principal-scoped events, quotas and retention
 
 `createSlotlockStoreAgentBackend` is the canonical binding to the PostgreSQL kernel. It derives an
@@ -237,4 +374,7 @@ rejects absolute-form request targets, applies finite header/body/handler and co
 propagates disconnects through `AbortSignal`, and force-closes only after a bounded graceful-shutdown
 window. When it closes it first asks the target to end long-lived responses (the agent server's
 `shutdown()`), and closes keep-alive connections whose response finished during shutdown. It exposes
-sanitized transport failures and leaves public TLS termination to the deployment.
+sanitized transport failures and leaves public TLS termination to the deployment. A body the target
+stops reading (one past its size limit) does not abort the request: once the response is written,
+the rest is discarded as it arrives, within `requestTimeout`. Closing the adapter while it is still
+starting rejects the pending `listen()` with `listen_aborted`.

package/agent-server.d.ts

@@ -1,4 +1,5 @@
 import { type SlotlockTraceContext } from './mcp-modern.js';
+import { type SlotlockApplicationBackend, type SlotlockApplicationOperation } from './application-api.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';
 /**
@@ -125,7 +126,10 @@ export type SlotlockAgentWriteOperation = Extract<SlotlockAgentOperation, 'slotl
  * A listed write first answers `input_required` with a yes/no form describing the change; it runs
  * only when the client retries with the person's explicit acceptance and the sealed state it was
  * given. Where no confirmation is possible — the 2025 MCP revisions and A2A — a listed write fails
- * with `confirmation_required`, never silently runs.
+ * with `confirmation_required`, never silently runs. The acceptance comes from the client, which a
+ * key holder controls: confirmation keeps an agent from writing unasked, and is not an
+ * authorization boundary (scopes and `authorize` are). Off unless set; `slotlock serve` sets it only
+ * when SLOTLOCK_CONFIRM_WRITES opts in.
  */
 export interface SlotlockAgentConfirmationOptions {
     operations: readonly SlotlockAgentWriteOperation[];
@@ -154,6 +158,12 @@ export interface SlotlockAgentSubscriptionOptions {
     keepAliveMs?: number;
     /** Open subscriptions one principal may hold: 1-64, default 4. */
     maxPerPrincipal?: number;
+    /**
+     * Open subscriptions one tenant may hold across all its principals: 1-10,000, default `maxTotal`.
+     * Set it below `maxTotal` on a multi-tenant server, so a tenant with many keys cannot hold every
+     * slot.
+     */
+    maxPerTenant?: number;
     /** Open subscriptions across the server: 1-10,000, default 256. */
     maxTotal?: number;
 }
@@ -163,15 +173,36 @@ export type SlotlockAgentServerEvent = {
     operation: SlotlockAgentOperation;
     outcome: 'requested' | 'accepted' | 'declined' | 'cancelled' | 'expired' | 'refused' | 'unavailable';
 } | {
-    /** A REST call that reached an operation, and the HTTP status it answered. */
+    /**
+     * A REST call that named an operation, and the HTTP status it answered: run, or refused before
+     * it ran (a body that is not JSON, too large or not an object).
+     */
     type: 'rest';
-    operation: SlotlockAgentOperation;
+    operation: SlotlockAgentOperation | SlotlockApplicationOperation;
     status: number;
+    /** How long the call took from naming its operation, in milliseconds to a tenth. */
+    durationMs: number;
+    /** The W3C trace id of the call's valid `traceparent`, when it carried one. */
+    traceId?: string;
+} | {
+    /** An MCP `tools/call` or A2A `SendMessage` that named an operation, and how it ended. */
+    type: 'call';
+    protocol: 'mcp' | 'a2a';
+    operation: SlotlockAgentOperation;
+    /**
+     * `ok`, or the refusal's code (`overlap`, `forbidden`, `rate_limited`, …), or why the request
+     * was refused before the operation ran: `invalid_arguments` (MCP arguments that are not an
+     * object), `missing_capability` (a guarded write from a 2026-07-28 client without form
+     * elicitation), `invalid_message` or `invalid_message_parameters` (A2A).
+     */
+    outcome: string;
+    durationMs: number;
+    traceId?: string;
 } | {
     type: 'subscription';
     outcome: 'opened' | 'closed';
     /** Why a subscription closed. */
-    reason?: 'client' | 'duration' | 'shutdown' | 'revoked' | 'failed' | 'empty';
+    reason?: 'client' | 'duration' | 'shutdown' | 'revoked' | 'failed' | 'empty' | 'preempted';
     /** How many calendar resources it watched. */
     resources: number;
 };
@@ -204,6 +235,21 @@ export interface SlotlockAgentServerOptions {
      * to ask a person. Off unless set.
      */
     rest?: boolean;
+    /**
+     * Also serve the application API under `/v1` (application-api.ts): resources, bookable hours,
+     * holds, reservations, calendar coverage and maintenance, for the application around the agents,
+     * in any language. Needs `rest`. A principal whose `scopes` are set needs `admin`
+     * (SLOTLOCK_APPLICATION_SCOPE); then `authorize` decides. They are never MCP tools or A2A skills,
+     * and never wait for a confirmation. Off unless set.
+     */
+    application?: {
+        backend: SlotlockApplicationBackend;
+        authorize(args: {
+            principal: SlotlockAgentPrincipal;
+            operation: SlotlockApplicationOperation;
+            input: Record<string, unknown>;
+        }): Promise<boolean>;
+    };
     /** Require a person's confirmation before the listed writes run. Off unless set. */
     confirmation?: SlotlockAgentConfirmationOptions;
     /**
@@ -218,23 +264,24 @@ export interface SlotlockAgentServerOptions {
      */
     subscriptions?: SlotlockAgentSubscriptionOptions | false;
     /**
-     * Observe confirmations and subscriptions (counts and outcomes, no arguments or identities) for
-     * metrics or audit. It runs synchronously and whatever it throws is ignored.
+     * Observe calls, confirmations and subscriptions (counts and outcomes, no arguments or
+     * identities) for metrics or audit. It is not awaited, and whatever it throws, or its promise
+     * rejects with, is ignored.
      */
     onEvent?: (event: SlotlockAgentServerEvent) => void;
     /**
      * Called with a failure no client is told about: an operation's backend threw something other
      * than a `SlotlockAgentOperationError`, or returned a result outside the operation's schema. The
      * client gets `internal_error` and nothing more, so log it here to find out why. It receives the
-     * error and the operation, never the arguments or the request; it runs synchronously and whatever
-     * it throws is ignored.
+     * error and the operation, never the arguments or the request. It is not awaited, and whatever it
+     * throws, or its promise rejects with, is ignored.
      */
     onError?: (error: unknown, context: SlotlockAgentErrorContext) => void;
 }
 /** What `onError` is told about an unexpected failure besides the error itself. */
 export interface SlotlockAgentErrorContext {
     /** The operation that failed; `null` when the failure came before one was resolved. */
-    operation: SlotlockAgentOperation | null;
+    operation: SlotlockAgentOperation | SlotlockApplicationOperation | null;
 }
 export interface SlotlockAgentOperationDispatchOptions {
     backend: SlotlockAgentCalendarBackend;
@@ -309,10 +356,29 @@ export declare function slotlockMcpToolResult(outcome: {
     code: string;
     details?: Readonly<Record<string, string | number | boolean | null>>;
 }): SlotlockMcpToolResult;
+/** The application operations with their input and output as JSON Schema, as REST serves them. */
+export declare function slotlockApplicationOperations(): {
+    name: SlotlockApplicationOperation;
+    title: string;
+    description: string;
+    method: "DELETE" | "GET" | "POST" | "PUT";
+    path: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    outputSchema: Readonly<Record<string, unknown>>;
+}[];
+/**
+ * The OpenAPI 3.1 document of the REST API: what a server with `rest` (and `application`) serves at
+ * /openapi.json. Without `publicBaseUrl` the server URL is a variable, `{baseUrl}`, as in the
+ * repository's openapi.json, which client generators read.
+ */
+export declare function slotlockOpenApi(options?: {
+    publicBaseUrl?: string;
+    application?: boolean;
+}): Record<string, unknown>;
 export declare function slotlockAgentTools(): {
     name: "slotlock_create_event" | "slotlock_delete_event" | "slotlock_find_next_available" | "slotlock_get_event" | "slotlock_get_free_busy" | "slotlock_list_events" | "slotlock_list_resources" | "slotlock_update_event";
     title: "Create resource event" | "Delete resource event" | "Find next available interval" | "Get free-busy" | "Get resource event" | "List calendar resources" | "List resource events" | "Update resource event";
-    description: "Apply an expected-revision event patch and rematerialize occupancy atomically." | "Create an event of up to 3,660 days (a booking, lease or long rental); opaque occurrences use the database overlap arbiter." | "Find the earliest certain interval that satisfies the requested duration (up to the 367-day search window, so a multi-month rental slot can be found)." | "List bounded events intersecting a time window." | "List resources visible to the authenticated tenant principal." | "Read one tenant-scoped event by stable identifier." | "Return privacy-minimized busy intervals and explicit coverage certainty." | "Tombstone an event at an expected revision so stale sync cannot resurrect it.";
+    description: "Apply an expected-revision event patch and rematerialize occupancy atomically. With expected_resource_id, the resource you read the event on, an event since moved elsewhere is not found." | "Create an event of up to 3,660 days (a booking, lease or long rental); opaque occurrences use the database overlap arbiter." | "Find the earliest certain interval that satisfies the requested duration (up to the 367-day search window, so a multi-month rental slot can be found)." | "List bounded events intersecting a time window." | "List resources visible to the authenticated tenant principal." | "Read one tenant-scoped event by stable identifier." | "Return privacy-minimized busy intervals and explicit coverage certainty." | "Tombstone an event at an expected revision so stale sync cannot resurrect it.";
     inputSchema: Readonly<Record<string, unknown>>;
     outputSchema: Readonly<Record<string, unknown>>;
     annotations: {