slotlock 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -3,8 +3,104 @@
 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
@@ -93,11 +189,11 @@ versioning.
 
 ### Changed
 
-- The feed now also records configuration changes, so a reader or webhook with no `event_types`
-  filter receives them too; filter by type to keep only bookings.
-- `coverage.stale` names its source by `source_id`, as `subject` and in `data`, in place of `source`,
-  and no longer carries `last_error`: a source can be an iCalendar URL with a token or an address,
-  and an error can quote it. `slotlock_get_coverage` still shows both to the tenant, with the
+- 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.
 

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.
@@ -192,10 +154,11 @@ slotlock rules clear --resource vehicle-42
 
 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
@@ -228,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
@@ -596,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.
@@ -648,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 -->
@@ -994,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` |
@@ -1186,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 |
@@ -1253,9 +1262,12 @@ webhook URLs or secrets.
   and check-in rules, pool, bookable hours, time zone or reference, with `before` and `after` of
   only the fields that changed), `resource.archived`, `.restored`, `.deleted`; `coverage.recorded`
   (a source's first read; reading it again is not a change) and `coverage.deleted`. A `coverage.*`
-  change names its source by `source_id` (also its `subject`), a digest of the tenant and the source
-  that `slotlock_get_coverage` and `slotlockCoverageSourceId` give too, never the source itself,
-  which can be an iCalendar URL with a token or an address;
+  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.
@@ -1615,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).
 

package/SECURITY.md

@@ -22,19 +22,12 @@ Do not include real customer, credential, calendar, or booking data. We will ack
 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
 
-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.
+The hosted service is not open; self-hosting is the only supported path today. Do not test
+`slotlock-api.pylota.io` or `app.slotlock.pylota.io`: they are not in scope until this section
+says the service is open and gives the rules for testing it. Test Slotlock by running it yourself,
+and report what you find as above.
 
 ## Security model
 
@@ -84,7 +77,10 @@ earlier, `PUBLIC` may still hold `CREATE` on `public`; the check then refuses ev
 a lock that blocks other tenants: that is availability, not isolation. `slotlock serve` checks the
 role it connects as before it serves, and refuses to start as a superuser or a `BYPASSRLS` role
 (`unsafe_serving_role`); it does not repeat the rest of this check, so that a single owning role can
-still migrate and serve (`serve --migrate` without `SLOTLOCK_MIGRATE_DATABASE_URL`).
+still migrate and serve (`serve --migrate` without `SLOTLOCK_MIGRATE_DATABASE_URL`). Row-level
+security does not confine the owner on tables that do not force it, and the owner can lift it, so
+`serve` logs a `serving_as_schema_owner` warning at startup when its role owns the `slotlock`
+schema: serve as a role that owns nothing in production.
 
 Schema changes run under a separate deployment role, which must own the `slotlock` schema and every
 object in it (`applySchema` creates the schema when it is missing). The deployment writes rows into
@@ -105,6 +101,23 @@ as the deployment role or a superuser, or trust its owner as much. `SLOTLOCK_COR
 caller's `search_path` at their end; apply each in one transaction (`psql --single-transaction`),
 since under autocommit the pin ends with the statement that sets it.
 
+The change feed, the history and webhooks name a coverage source by its `source_id`, never the
+source itself, which can be an iCalendar URL with a token or an address. The id is random (`src_` and
+32 hex digits from `gen_random_uuid()`), stored with the source when it is first recorded and kept
+until it is deleted, so someone who sees a change and knows the tenant cannot confirm a guessed
+source against it (0.5.3's id was an unkeyed digest of the tenant and the source, and could be).
+The tenant reads the id beside the source from `listCoverage`. Upgrading renames the coverage
+changes earlier releases wrote, which carried the source, its last error or that digest, and a
+trigger on the outbox puts one an earlier release's server (0.3-0.5) still running writes after the
+upgrade in the same shape as it is inserted, so none is stored with its source. Every read path serves a `coverage.*` change without `source` and `last_error`, named
+`src_redacted` when its subject is not such an id, and history by subject never matches a coverage
+change by any other name. What was already sent stays sent: a webhook receiver keeps an earlier
+delivery, so rotate a token that an earlier release delivered in a `coverage.stale` change. A
+0.5.3 `source_id` already forwarded (a webhook delivery, a feed reader's copy, a log) still reveals
+its source to anyone who guesses the source and knows the tenant, as it did then; the rename changes
+only the copies in the outbox. `slotlockCoverageSourceId`, which worked that digest out, throws
+since 0.6.
+
 The privacy-minimised provider parser cannot return summaries, locations, notes, organizers or
 attendees. Full event parsing is a separate trusted API and must only receive authenticated content.
 Event command rows retain payload digests and stable results, never duplicate event content. Event

package/agent-server.d.ts

@@ -374,6 +374,12 @@ export interface SlotlockAgentOperationDispatchOptions {
     /** As `SlotlockAgentServerOptions.onError`: a failure the result reports only as internal. */
     onError?: (error: unknown, context: SlotlockAgentErrorContext) => void;
 }
+/** One reason `invalid_arguments` refused a call: where in the arguments, and what is wrong there. */
+export interface SlotlockArgumentIssue {
+    /** The field's path in the arguments, outermost first (`["rules", 0, "rrule"]`); `[]` is the arguments as a whole. */
+    path: (string | number)[];
+    message: string;
+}
 export type SlotlockAgentOperationDispatchResult = {
     ok: true;
     data: Record<string, unknown>;
@@ -382,6 +388,8 @@ export type SlotlockAgentOperationDispatchResult = {
     status: number;
     code: string;
     details?: Readonly<Record<string, string>>;
+    /** With `invalid_arguments` from argument validation: the fields it refused. */
+    issues?: readonly SlotlockArgumentIssue[];
 };
 /** Runtime type guard for the current operation names (legacy dotted names are not included). */
 export declare function isSlotlockAgentOperation(name: unknown): name is SlotlockAgentOperation;
@@ -419,6 +427,7 @@ export declare function slotlockMcpToolResult(outcome: {
     ok: false;
     code: string;
     details?: Readonly<Record<string, string | number | boolean | null>>;
+    issues?: readonly SlotlockArgumentIssue[];
 }): SlotlockMcpToolResult;
 /** The application operations with their input and output as JSON Schema, as REST serves them. */
 export declare function slotlockApplicationOperations(): {

package/agent-server.js

@@ -380,6 +380,21 @@ export class SlotlockAgentOperationError extends Error {
             this.details = Object.freeze(Object.fromEntries(kept));
     }
 }
+/** At most this many issues are returned, each message cut to {@link MAX_ISSUE_MESSAGE} characters. */
+const MAX_ISSUES = 20;
+const MAX_ISSUE_MESSAGE = 200;
+/** Argument validation's refusal: 400 `invalid_arguments` with the fields zod refused. */
+function invalidArguments(error) {
+    return {
+        ok: false,
+        status: 400,
+        code: 'invalid_arguments',
+        issues: error.issues.slice(0, MAX_ISSUES).map((issue) => ({
+            path: issue.path.map((key) => (typeof key === 'number' ? key : String(key))),
+            message: issue.message.slice(0, MAX_ISSUE_MESSAGE),
+        })),
+    };
+}
 const EXAMPLE_RESOURCE_ID = '0f8b6c1e-2d4a-4c7e-9b1a-3e5f7a9c2d4b';
 const EXAMPLE_EVENT_ID = 'agent:5e8ff9bf55ba3508199d22e984129be6b5b6a8a7e3e5f1f0d2b9ba0c4a6f7e21';
 const EXAMPLE_WINDOW = { start: '2027-03-01T00:00:00Z', end: '2027-03-08T00:00:00Z' };
@@ -845,6 +860,8 @@ export function slotlockMcpToolResult(outcome) {
         if (key !== 'code')
             error[key] = value;
     }
+    if (outcome.issues)
+        error.issues = outcome.issues;
     return { content: [{ type: 'text', text: JSON.stringify({ error }) }], isError: true };
 }
 /** The agent tools as REST serves them: each with the scope it needs. */
@@ -1152,7 +1169,7 @@ export async function invokeSlotlockAgentOperation(args) {
         }
         const parsed = operation.input.safeParse(args.input ?? {});
         if (!parsed.success)
-            return { ok: false, status: 400, code: 'invalid_arguments' };
+            return invalidArguments(parsed.error);
         if (!(await args.options.authorize({
             principal,
             operation: operation.name,
@@ -3145,7 +3162,7 @@ export function createSlotlockAgentServer(options) {
             }
             const parsed = definition.input.safeParse(given);
             if (!parsed.success)
-                return { ok: false, status: 400, code: 'invalid_arguments' };
+                return invalidArguments(parsed.error);
             if (!(await served.authorize({ principal, operation: definition.name, input: parsed.data }))) {
                 return { ok: false, status: 403, code: 'forbidden' };
             }
@@ -3309,6 +3326,7 @@ export function createSlotlockAgentServer(options) {
         return refuse(status, outcome.code, {}, {
             ...(outcome.code === 'overlap' ? refusedInterval(given) : {}),
             ...outcome.details,
+            ...(outcome.issues ? { issues: outcome.issues } : {}),
         });
     }
     return {
@@ -3685,7 +3703,15 @@ export function createSlotlockAgentServer(options) {
                 if (!outcome.ok && INTERNAL_FAILURES.has(outcome.code)) {
                     return json(200, rpcError(id, -32603, 'Internal error'));
                 }
-                return reply(outcome.ok ? outcome.data : { error: { ...outcome.details, code: outcome.code } });
+                return reply(outcome.ok
+                    ? outcome.data
+                    : {
+                        error: {
+                            ...outcome.details,
+                            code: outcome.code,
+                            ...(outcome.issues ? { issues: outcome.issues } : {}),
+                        },
+                    });
             }
             catch {
                 return json(200, rpcError(id, -32603, 'Internal error'));

package/application-api.js

@@ -757,7 +757,7 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
     {
         name: 'slotlock_get_coverage',
         title: "A resource's coverage and its health",
-        description: "Each external calendar (source) that records coverage of a resource: the window it covers, when it was last read, its last error, and whether it is stale (not read for a day, so the time it covers is unproven, not free). A source that goes stale is also put on the change feed once, as coverage.stale, until it is read again. The feed names a source by its source_id, never the source itself.",
+        description: "Each external calendar (source) that records coverage of a resource: the window it covers, when it was last read, its last error, and whether it is stale (not read for a day, so the time it covers is unproven, not free). A source that goes stale is also put on the change feed once, as coverage.stale, until it is read again. The feed names a source by its source_id (random, made when the source is first recorded for the resource and kept until it is deleted), never the source itself.",
         method: 'GET',
         path: '/v1/resources/{resource_id}/coverage',
         input: z.object({ resource_id: RESOURCE_ID }).strict(),
@@ -767,8 +767,11 @@ export const SLOTLOCK_APPLICATION_OPERATIONS = Object.freeze([
                 .array(z
                 .object({
                 source: SOURCE,
-                /** How the change feed names the source (coverage.recorded, .deleted, .stale). */
-                source_id: z.string().regex(/^src_[0-9a-f]{24}$/),
+                /**
+                 * How the change feed names the source (coverage.recorded, .deleted, .stale): random,
+                 * made when it is first recorded for the resource, kept until it is deleted.
+                 */
+                source_id: z.string().regex(/^src_[0-9a-f]{32}$/),
                 start: DATE_TIME,
                 end: DATE_TIME,
                 revision: REVISION,

package/ddl.d.ts

@@ -2,9 +2,11 @@
 export declare const SLOTLOCK_SCHEMA_CONTROL_REFUSAL = "Slotlock will not deploy into schema slotlock";
 /**
  * The version of the schema this release creates, recorded in `slotlock.schema_version` by every
- * migration. Releases up to 0.2 recorded nothing; 0.1 was version 1 and 0.2 version 2.
+ * migration. Releases up to 0.2 recorded nothing; 0.1 was version 1 and 0.2 version 2; 0.3 to 0.5
+ * recorded 3. 0.6 is 4, so a 0.5 release refuses it before it changes anything: its DDL would put
+ * back the trigger that names a coverage source by its guessable digest.
  */
-export declare const SLOTLOCK_SCHEMA_VERSION = 3;
+export declare const SLOTLOCK_SCHEMA_VERSION = 4;
 /** The start of the message with which the deployment DDL refuses a schema a newer release migrated. */
 export declare const SLOTLOCK_SCHEMA_NEWER_REFUSAL = "Slotlock will not migrate a schema a newer release migrated";
 /**
@@ -12,7 +14,7 @@ export declare const SLOTLOCK_SCHEMA_NEWER_REFUSAL = "Slotlock will not migrate
  * when they find nothing to change: that no other role controls the schema, then the server version
  * and the schema version. Run with search_path pinned, as the DDL pins it.
  */
-export declare const SLOTLOCK_DEPLOYMENT_CHECKS = "DO $slotlock_schema_control$\nDECLARE\n  refusals text[];\nBEGIN\n  SELECT pg_catalog.array_agg(refusal.reason ORDER BY refusal.reason)\n    INTO refusals\n    FROM (\n      SELECT 'schema slotlock is owned by ' || owned_by.rolname AS reason\n        FROM pg_catalog.pg_namespace ns\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = ns.nspowner\n       WHERE ns.nspname = 'slotlock'\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n      UNION\n      SELECT COALESCE(grantee_role.rolname, 'PUBLIC') || ' can create objects in schema slotlock'\n        FROM pg_catalog.pg_namespace ns\n       CROSS JOIN LATERAL pg_catalog.aclexplode(ns.nspacl) acl\n        LEFT JOIN pg_catalog.pg_roles grantee_role ON grantee_role.oid = acl.grantee\n       WHERE ns.nspname = 'slotlock'\n         AND acl.privilege_type = 'CREATE'\n         AND acl.grantee <> ns.nspowner\n         AND (acl.grantee = 0\n              OR (grantee_role.rolname <> CURRENT_USER AND NOT grantee_role.rolsuper))\n      UNION\n      SELECT ident.type || ' ' || ident.identity || ' is owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_shdepend owned\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = owned.refobjid\n       CROSS JOIN LATERAL pg_catalog.pg_identify_object(owned.classid, owned.objid, owned.objsubid) ident\n       WHERE owned.dbid = (SELECT db.oid FROM pg_catalog.pg_database db\n                            WHERE db.datname = pg_catalog.current_database())\n         AND owned.deptype = 'o'\n         AND owned.refclassid = 'pg_catalog.pg_authid'::pg_catalog.regclass\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n         AND ident.schema = 'slotlock'\n      UNION\n      SELECT 'trigger ' || trg.tgname || ' on slotlock.' || rel.relname || ' runs '\n             || trg.tgfoid::pg_catalog.regprocedure::pg_catalog.text\n             || ', owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_trigger trg\n        JOIN pg_catalog.pg_class rel ON rel.oid = trg.tgrelid\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace\n        JOIN pg_catalog.pg_proc fn ON fn.oid = trg.tgfoid\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = fn.proowner\n       WHERE ns.nspname = 'slotlock'\n         AND NOT trg.tgisinternal\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n      UNION\n      SELECT COALESCE(grantee_role.rolname, 'PUBLIC') || ' can create triggers on slotlock.'\n             || rel.relname\n        FROM pg_catalog.pg_class rel\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace\n       CROSS JOIN LATERAL pg_catalog.aclexplode(rel.relacl) acl\n        LEFT JOIN pg_catalog.pg_roles grantee_role ON grantee_role.oid = acl.grantee\n       WHERE ns.nspname = 'slotlock'\n         AND acl.privilege_type = 'TRIGGER'\n         AND acl.grantee <> rel.relowner\n         AND (acl.grantee = 0\n              OR (grantee_role.rolname <> CURRENT_USER AND NOT grantee_role.rolsuper))\n      UNION\n      SELECT 'extension ' || ext.extname || ' in schema slotlock is owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_extension ext\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = ext.extnamespace\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = ext.extowner\n       WHERE ns.nspname = 'slotlock'\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n    ) refusal;\n  IF refusals IS NOT NULL THEN\n    RAISE EXCEPTION 'Slotlock will not deploy into schema slotlock: another role controls it'\n      USING ERRCODE = 'insufficient_privilege',\n            DETAIL = pg_catalog.to_jsonb(refusals)::pg_catalog.text,\n            HINT = 'The deployment role must own schema slotlock and every object in it, and no other role may create objects in it.';\n  END IF;\nEND\n$slotlock_schema_control$;\nDO $slotlock_schema_preconditions$\nDECLARE\n  installed integer;\nBEGIN\n  IF pg_catalog.current_setting('server_version_num')::integer < 160000 THEN\n    RAISE EXCEPTION 'Slotlock needs PostgreSQL 16 or later; this server is %',\n      pg_catalog.current_setting('server_version')\n      USING ERRCODE = 'feature_not_supported';\n  END IF;\n  IF pg_catalog.to_regclass('slotlock.schema_version') IS NOT NULL THEN\n    EXECUTE 'SELECT version FROM slotlock.schema_version WHERE singleton' INTO installed;\n    IF installed > 3 THEN\n      RAISE EXCEPTION 'Slotlock will not migrate a schema a newer release migrated (version %; this release is version 3)', installed\n        USING ERRCODE = 'object_not_in_prerequisite_state',\n              HINT = 'Migrate and serve it with the release that migrated it, or a later one.';\n    END IF;\n  END IF;\nEND\n$slotlock_schema_preconditions$;\n";
+export declare const SLOTLOCK_DEPLOYMENT_CHECKS = "DO $slotlock_schema_control$\nDECLARE\n  refusals text[];\nBEGIN\n  SELECT pg_catalog.array_agg(refusal.reason ORDER BY refusal.reason)\n    INTO refusals\n    FROM (\n      SELECT 'schema slotlock is owned by ' || owned_by.rolname AS reason\n        FROM pg_catalog.pg_namespace ns\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = ns.nspowner\n       WHERE ns.nspname = 'slotlock'\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n      UNION\n      SELECT COALESCE(grantee_role.rolname, 'PUBLIC') || ' can create objects in schema slotlock'\n        FROM pg_catalog.pg_namespace ns\n       CROSS JOIN LATERAL pg_catalog.aclexplode(ns.nspacl) acl\n        LEFT JOIN pg_catalog.pg_roles grantee_role ON grantee_role.oid = acl.grantee\n       WHERE ns.nspname = 'slotlock'\n         AND acl.privilege_type = 'CREATE'\n         AND acl.grantee <> ns.nspowner\n         AND (acl.grantee = 0\n              OR (grantee_role.rolname <> CURRENT_USER AND NOT grantee_role.rolsuper))\n      UNION\n      SELECT ident.type || ' ' || ident.identity || ' is owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_shdepend owned\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = owned.refobjid\n       CROSS JOIN LATERAL pg_catalog.pg_identify_object(owned.classid, owned.objid, owned.objsubid) ident\n       WHERE owned.dbid = (SELECT db.oid FROM pg_catalog.pg_database db\n                            WHERE db.datname = pg_catalog.current_database())\n         AND owned.deptype = 'o'\n         AND owned.refclassid = 'pg_catalog.pg_authid'::pg_catalog.regclass\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n         AND ident.schema = 'slotlock'\n      UNION\n      SELECT 'trigger ' || trg.tgname || ' on slotlock.' || rel.relname || ' runs '\n             || trg.tgfoid::pg_catalog.regprocedure::pg_catalog.text\n             || ', owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_trigger trg\n        JOIN pg_catalog.pg_class rel ON rel.oid = trg.tgrelid\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace\n        JOIN pg_catalog.pg_proc fn ON fn.oid = trg.tgfoid\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = fn.proowner\n       WHERE ns.nspname = 'slotlock'\n         AND NOT trg.tgisinternal\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n      UNION\n      SELECT COALESCE(grantee_role.rolname, 'PUBLIC') || ' can create triggers on slotlock.'\n             || rel.relname\n        FROM pg_catalog.pg_class rel\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace\n       CROSS JOIN LATERAL pg_catalog.aclexplode(rel.relacl) acl\n        LEFT JOIN pg_catalog.pg_roles grantee_role ON grantee_role.oid = acl.grantee\n       WHERE ns.nspname = 'slotlock'\n         AND acl.privilege_type = 'TRIGGER'\n         AND acl.grantee <> rel.relowner\n         AND (acl.grantee = 0\n              OR (grantee_role.rolname <> CURRENT_USER AND NOT grantee_role.rolsuper))\n      UNION\n      SELECT 'extension ' || ext.extname || ' in schema slotlock is owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_extension ext\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = ext.extnamespace\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = ext.extowner\n       WHERE ns.nspname = 'slotlock'\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n    ) refusal;\n  IF refusals IS NOT NULL THEN\n    RAISE EXCEPTION 'Slotlock will not deploy into schema slotlock: another role controls it'\n      USING ERRCODE = 'insufficient_privilege',\n            DETAIL = pg_catalog.to_jsonb(refusals)::pg_catalog.text,\n            HINT = 'The deployment role must own schema slotlock and every object in it, and no other role may create objects in it.';\n  END IF;\nEND\n$slotlock_schema_control$;\nDO $slotlock_schema_preconditions$\nDECLARE\n  installed integer;\nBEGIN\n  IF pg_catalog.current_setting('server_version_num')::integer < 160000 THEN\n    RAISE EXCEPTION 'Slotlock needs PostgreSQL 16 or later; this server is %',\n      pg_catalog.current_setting('server_version')\n      USING ERRCODE = 'feature_not_supported';\n  END IF;\n  IF pg_catalog.to_regclass('slotlock.schema_version') IS NOT NULL THEN\n    EXECUTE 'SELECT version FROM slotlock.schema_version WHERE singleton' INTO installed;\n    IF installed > 4 THEN\n      RAISE EXCEPTION 'Slotlock will not migrate a schema a newer release migrated (version %; this release is version 4)', installed\n        USING ERRCODE = 'object_not_in_prerequisite_state',\n              HINT = 'Migrate and serve it with the release that migrated it, or a later one.';\n    END IF;\n  END IF;\nEND\n$slotlock_schema_preconditions$;\n";
 /** Active (unrevoked, unexpired) API keys one tenant may hold. */
 export declare const SLOTLOCK_API_KEY_ACTIVE_LIMIT = 100;
 /** API keys one tenant may hold in all, revoked and expired ones included, so lists stay bounded. */
@@ -63,6 +65,21 @@ export declare const SLOTLOCK_DEFINER_TABLES: readonly ("api_key_retired_digests
 export declare function slotlockTenantLockKey(tenantRef: string): string;
 /** The constraint validation applySchema runs after the rest of SLOTLOCK_CORE_DDL has committed. */
 export declare const SLOTLOCK_VALIDATION_DDL: string;
+/** Outbox ids one batch of the coverage-change rename reads (by primary key) in one transaction. */
+export declare const SLOTLOCK_COVERAGE_CHANGE_RENAME_BATCH = 5000;
+/**
+ * One batch of the rename of coverage changes an earlier release wrote: of the outbox rows with ids
+ * after `after` up to `head` (SQL expressions, bigint), the first `batch` by id, each `coverage.*`
+ * one not yet in this release's shape gets its source's source_id as subject and `data.source_id`,
+ * and loses `source` and `last_error`. Before 0.5.3 coverage.stale carried the source itself (an
+ * iCalendar URL with a token, an address) and the error read from it; 0.5.3 named it by an unkeyed
+ * digest anyone could confirm a guess against. A source deleted since is `src_redacted`: nothing
+ * can match it any more, and a made-up id would look like a source the tenant could find. Selects
+ * the last id read (`last`, null when there was none) and how many it renamed (`renamed`), `INTO`
+ * `into` when given (PL/pgSQL). Rows in the new shape are left alone, so a batch run again changes
+ * nothing.
+ */
+export declare function slotlockCoverageChangeRenameSql(after: string, head: string, batch: string, into?: string): string;
 /** The whole deployment DDL, run in one transaction: the schema, then its constraints validated. */
 export declare const SLOTLOCK_CORE_DDL: string;
 /**