slotlock 0.5.3 → 0.6.1

package/CHANGELOG.md

@@ -3,8 +3,127 @@
 All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and semantic
 versioning.
 
+## 0.6.1 - 2026-11-08
+
+### Changed
+
+- Dashboard: a new look on one set of design tokens, in light and dark. Calmer surfaces (hairline
+  borders, no drop shadows), a monospace label scale for table heads and stats, black primary
+  buttons, status pills with a dot, and empty states that name the one next step. Long names,
+  references, URLs and ids stay on one line with the whole value in a tooltip (and wrap on a
+  phone); table dates show the day, with the full UTC time on hover. On a phone the pages sit
+  under a top bar with a scrolling tab strip and a sign-out button. A skip link, a live region for
+  Copy, Escape and click-outside closing for Rotate, Revoke and Delete (whose button takes focus),
+  and reduced motion are respected. The key list names who created a key under its name instead
+  of in a column of its own. Routes, form fields, CSRF and origin checks, sessions and the
+  Content-Security-Policy are unchanged; the dashboard still loads only its own stylesheet and
+  script, and works without script.
+
+### Fixed
+
+- Dashboard: Rotate and Revoke on API keys, Delete on webhooks and Remove on the waitlist open
+  their confirmation in place, growing the row. It floated below the row inside the table's
+  scrolling box, which clipped it: on an account with one key, Revoke opened a button that could
+  not be pressed.
+
+## 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 +212,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)
+runs it for you, or you self-host it. 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,