slotlock 0.1.1 → 0.3.0

package/slotlock-manifest.schema.json

@@ -66,7 +66,12 @@
           "mcp-human-confirmation",
           "mcp-calendar-resources",
           "mcp-live-updates",
-          "trace-context-propagation"
+          "trace-context-propagation",
+          "rest-api",
+          "application-api",
+          "api-keys",
+          "dashboard",
+          "maintenance"
         ]
       }
     },

package/slotlock.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0",
   "name": "Slotlock",
   "package": "slotlock",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "intervalSemantics": {
     "boundary": "[)",
@@ -36,7 +36,12 @@
     "mcp-human-confirmation",
     "mcp-calendar-resources",
     "mcp-live-updates",
-    "trace-context-propagation"
+    "trace-context-propagation",
+    "rest-api",
+    "application-api",
+    "api-keys",
+    "dashboard",
+    "maintenance"
   ],
   "transportPolicy": "adapter-defined",
   "externalCalendarsAreAuthority": false

package/store.d.ts

@@ -1,12 +1,19 @@
 import type { Sql, TransactionSql } from 'postgres';
-import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventRetentionResult, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
-export declare const SLOTLOCK_CALENDAR_HORIZON_DAYS = 367;
+import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
+import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
+export { SLOTLOCK_CALENDAR_HORIZON_DAYS };
 /**
  * Longest one-off event the store accepts (ten years and some leap days): long enough for any lease
  * or long-term rental, short enough that a unit error cannot occupy a resource for ever. A recurring
  * series is bounded by its 367-day materialization window instead.
  */
 export declare const SLOTLOCK_MAX_EVENT_DURATION_DAYS = 3660;
+/**
+ * Longest window a recurring series is stored (materialized) for: the 367-day search window plus
+ * two days. The rolling horizon starts a day before the current UTC day and must reach 367 days
+ * past its end, so that a search of the full 367 days from any moment of the day is complete.
+ */
+export declare const SLOTLOCK_MATERIALIZATION_WINDOW_DAYS: number;
 /** Trusted provider/maintenance namespace used by backwards-compatible store callers. */
 export declare const SLOTLOCK_INTERNAL_EVENT_OWNER_REF = "internal";
 /** Default hard ceiling for retained active + tombstoned identities per agent principal. */
@@ -20,11 +27,39 @@ export declare const SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA = 10000;
 export declare const SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS = 30;
 /** Store-owned coverage source for bounded, locally materialized recurring events. */
 export declare const SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE = "slotlock:local-recurrence-materialization";
-/** Stable daily target shared by the event writer, maintenance worker, and readiness proof. */
+/**
+ * Stable daily target shared by the event writer, maintenance worker, and readiness proof: from a
+ * day before the current UTC day to 367 days past its end (SLOTLOCK_MATERIALIZATION_WINDOW_DAYS).
+ */
 export declare function calendarEventRollingHorizon(now?: Date): Interval;
 /** What `createSlotlockStore` accepts: a `postgres` client, or a transaction/savepoint from one. */
 export type SlotlockSql = Sql | TransactionSql;
 type StoreSql = SlotlockSql;
+/** How a migration (applySchema, applyTenantRls, grantApplicationRole) waits and how long it runs. */
+export interface SlotlockMigrationOptions {
+    /**
+     * The longest it waits for any one lock, in milliseconds (1-600,000; default 1,000). While a
+     * migration waits for a lock on a table, every query that comes after it on that table waits
+     * behind it; past this it gives up, lets them through, and tries again.
+     */
+    lockTimeoutMs?: number;
+    /** The longest any one of its statements runs, in milliseconds (1-86,400,000; default 900,000). */
+    statementTimeoutMs?: number;
+    /** How many times it tries in all (1-20; default 5) before refusing with `schema_lock_timeout`. */
+    attempts?: number;
+}
+/**
+ * The schema version recorded by the last migration, or `null` when there is none this role can
+ * read: no schema, a schema from 0.2 or earlier, or a role not yet granted the function (run
+ * `slotlock migrate`, which grants it).
+ */
+export declare function readSlotlockSchemaVersion(sql: SlotlockSql): Promise<number | null>;
+/**
+ * Refuse to serve a schema another release migrated: `schema_outdated` when it is older than this
+ * release (or unversioned), so `slotlock migrate` must run first; `schema_newer` when a newer release
+ * migrated it, whose schema this release's code does not know. Both carry `installed` and `expected`.
+ */
+export declare function assertSlotlockSchemaCurrent(sql: SlotlockSql): Promise<void>;
 export interface SlotlockStore {
     /**
      * Apply the Slotlock DDL (idempotent). Owns the `slotlock` schema on the connected DB. Refuses
@@ -32,16 +67,24 @@ export interface SlotlockStore {
      * connected one (superusers aside) owns or can create objects in, that holds an object such a
      * role owns (an extension included), or whose tables such a role may add triggers to or have a
      * trigger running a function such a role owns. Ownership through a group role counts as another
-     * role's: deploy as the owning role itself (`SET ROLE`).
+     * role's: deploy as the owning role itself (`SET ROLE`). Refuses (`schema_newer`) a schema a newer
+     * release migrated, changing nothing. Records SLOTLOCK_SCHEMA_VERSION. A schema this release
+     * already migrated, unchanged since, is left as it is without a lock on any table. Constraints an
+     * upgrade adds NOT VALID are validated in a second transaction, whose locks no serving read or
+     * write waits for (one inside a caller's transaction shares its locks until it ends); one that old
+     * rows still break stays NOT VALID, and each later migration validates it again. Each lock it
+     * waits for is bounded by `lockTimeoutMs`, after which it tries again (`schema_lock_timeout` once
+     * out of attempts).
      */
-    applySchema(): Promise<void>;
+    applySchema(options?: SlotlockMigrationOptions): Promise<void>;
     /**
      * Atomically enable forced tenant RLS using this store's configured context setting. Refuses the
-     * same `slotlock` schemas as `applySchema()`.
+     * same `slotlock` schemas as `applySchema()`. Tables already forced under exactly the policies it
+     * installs, bound to this setting, are left as they are without a lock on any table.
      */
     applyTenantRls(options?: {
         allowRebind?: boolean;
-    }): Promise<void>;
+    } & SlotlockMigrationOptions): Promise<void>;
     /**
      * Grant an existing application role exactly what the store needs at runtime: USAGE on the
      * `slotlock` schema and DML on its tables. Run as the deployment role after every `applySchema()`.
@@ -54,23 +97,30 @@ export interface SlotlockStore {
      * setting. The check runs when the grant is made, so a right added later is not
      * detected until it runs again, and it is not exhaustive (SECURITY.md lists what it does not read).
      */
-    grantApplicationRole(role: string): Promise<void>;
+    grantApplicationRole(role: string, options?: SlotlockMigrationOptions): Promise<void>;
     /**
-     * Run store operations with one transaction-local tenant context on the same connection. With
-     * `isolation: 'read committed'` the transaction is READ COMMITTED whatever the role's default (a
-     * capped `createResource` needs it); inside a caller's transaction of another level it refuses
-     * (`invalid_transaction_isolation`).
+     * Run store operations with one transaction-local tenant context on the same connection. On a
+     * client it opens a READ COMMITTED transaction, whatever the role's default. Inside a caller's
+     * transaction of another level its writes are refused (`invalid_transaction_isolation`), since
+     * that snapshot can miss a suspension, and its reads go on; with `isolation: 'read committed'`
+     * such a transaction is refused outright. The serving role needs EXECUTE on
+     * slotlock.tenant_suspended(text): without it this refuses with `application_role_not_granted`
+     * (grantApplicationRole grants it), and on a schema without it with `schema_outdated`. With the
+     * store's `maxTenantTransactions`, an aborted `signal` takes a call still waiting for its turn out
+     * of the line, refused with the signal's reason.
      */
     withTenant<T>(tenantRef: string, callback: (store: SlotlockTenantStore) => Promise<T>, options?: {
         isolation?: 'read committed';
+        signal?: AbortSignal;
     }): Promise<T>;
     /**
      * INVARIANT (erasure completeness): a tenant integration must use a stable, erasable business
      * identifier for externalRef and include this schema in its own data-erasure workflow.
      *
-     * With `maxTenantResources` (1-100,000, tenant-owned resources only) a new resource is refused
-     * (`resource_limit_reached`) once the tenant has that many; an existing `externalRef` is still
-     * updated. Capped creates for one tenant run one at a time under a database lock, so racing ones
+     * With `maxTenantResources` (1-100,000, tenant-owned resources only), or the store's `resources`
+     * limit (the lower of the two when both are set), a new resource of a tenant is refused
+     * (`resource_limit_reached`, with the `limit`) once the tenant has that many; an existing
+     * `externalRef` is still updated. Capped creates for one tenant run one at a time under a database lock, so racing ones
      * on any number of servers stop at the cap. The count needs READ COMMITTED: a capped create opens
      * one itself, and inside a caller's transaction of another level it refuses
      * (`invalid_transaction_isolation`). Uncapped creates do not wait for the lock and are not
@@ -81,12 +131,46 @@ export interface SlotlockStore {
         tenantRef?: string;
         timezone?: string;
         maxTenantResources?: number;
+        /**
+         * `shared` (the default) or `private`, which agents never see. Fixed at creation: creating an
+         * existing reference again with none named returns it as it is, and with another visibility is
+         * refused (`resource_visibility_conflict`).
+         */
+        visibility?: SlotlockResource['visibility'];
     }): Promise<SlotlockResource>;
-    /** Resolve one tenant-owned resource without revealing another tenant's matching id. */
+    /**
+     * Resolve one tenant-owned resource without revealing another tenant's matching id. An archived
+     * one is returned (with `archivedAt`); with `visibility`, only one of that visibility.
+     */
     getResource(params: {
         tenantRef: string;
         id: string;
+        visibility?: SlotlockResource['visibility'];
     }): Promise<SlotlockResource | null>;
+    /**
+     * Archive one of the tenant's resources: no list shows it and it takes no new booking, hold or
+     * event (`resource_archived`), while what is on it stays and can still be cancelled or released.
+     * Archiving it again keeps the first time. Null for an id that is not the tenant's.
+     */
+    archiveResource(params: {
+        tenantRef: string;
+        id: string;
+    }): Promise<SlotlockResource | null>;
+    /** Put an archived resource back in use. Null for an id that is not the tenant's. */
+    restoreResource(params: {
+        tenantRef: string;
+        id: string;
+    }): Promise<SlotlockResource | null>;
+    /**
+     * Delete one of the tenant's resources with its history (its past bookings, coverage and the
+     * occupation of cancelled events), freeing its place under the resource cap. Refused
+     * (`resource_in_use`) while a booking on it has not ended, a hold on it is live, or a calendar
+     * event (one-off not yet over, or recurring) is on it: cancel or move those first.
+     */
+    deleteResource(params: {
+        tenantRef: string;
+        id: string;
+    }): Promise<DeleteResourceResult>;
     /**
      * Set one resource's own weekly bookable hours, or clear them (`null`) so it uses the default;
      * `[]` makes it never bookable. Null for an id that is not the tenant's. Refuses rules Slotlock
@@ -107,20 +191,32 @@ export interface SlotlockStore {
         tenantRef: string;
         limit?: number;
         after?: string;
+        /** Only resources of this visibility; omitted, both. */
+        visibility?: SlotlockResource['visibility'];
+        /** Archived resources too; omitted, only those in use. */
+        includeArchived?: boolean;
     }): Promise<SlotlockResource[]>;
     /**
      * Insert a confirmed reservation with the EXCLUDE constraint as the overlap arbiter. Never
      * throws for the expected outcomes: an invalid window or a lost race come back structured.
      * Expired holds overlapping the window are lazily reaped in the same transaction — an
-     * expired-but-unpurged hold can never block (no cron required).
+     * expired-but-unpurged hold can never block (no cron required). On a tenant's resource the
+     * booking takes the tenant, and its own id as reference, so cancel and reschedule reach it. With
+     * `tenantRef`, only a resource of that tenant (`resource_not_found` otherwise, whatever the
+     * connection's row-level security).
      */
     createReservation(params: {
         resourceId: string;
         start: Date;
         end: Date;
         source?: string;
+        tenantRef?: string;
     }): Promise<CreateReservationResult>;
-    /** Idempotently create a tenant-owned booking reservation by its stable business identity. */
+    /**
+     * Idempotently create a tenant-owned booking reservation by its stable business identity. The
+     * rows a calendar event occupies are not bookings: here, in reschedule and in cancel their
+     * references answer as references no booking holds.
+     */
     createExternalReservation(params: ExternalReservationCommand): Promise<ExternalReservationResult>;
     /** Atomically move an existing tenant-owned booking; a conflict leaves its old range intact. */
     rescheduleExternalReservation(params: ExternalReservationCommand): Promise<ExternalReservationResult>;
@@ -133,6 +229,8 @@ export interface SlotlockStore {
     /**
      * Occupy a window WITHOUT committing: the hold blocks rivals under the same EXCLUDE arbiter
      * until `expiresAt` (DB clock — now() + ttl, never the app clock), then frees via lazy reap.
+     * With `tenantRef`, only a resource of that tenant (`resource_not_found` otherwise, whatever the
+     * connection's row-level security).
      */
     acquireHold(params: {
         resourceId: string;
@@ -140,13 +238,81 @@ export interface SlotlockStore {
         end: Date;
         ttlMs: number;
         source?: string;
+        tenantRef?: string;
+        /** Turnaround kept busy after `end`, 0 to 30 days; the confirmed booking keeps it. */
+        bufferAfterMs?: number;
+        /**
+         * A retry identity, 1-500 UTF-8 bytes, unique inside `tenantRef` and `principalRef` (both
+         * required with it): a request repeated with the same key and body answers the hold the first
+         * made (`idempotent: true`), and one with another body is `idempotency_conflict`. The answer is
+         * kept until the hold would have expired, released or confirmed; a retry after that makes a new
+         * hold.
+         */
+        idempotencyKey?: string;
+        /** Whose keys `idempotencyKey` is among, 1-500 UTF-8 bytes (an API key's subject, say). */
+        principalRef?: string;
     }): Promise<AcquireHoldResult>;
-    /** Flip an unexpired hold to a confirmed reservation (expiry cleared). */
-    confirmHold(holdId: string): Promise<ConfirmHoldResult>;
-    /** Delete a live hold; released=false when it was already gone (expired-reaped or confirmed). */
-    releaseHold(holdId: string): Promise<ReleaseHoldResult>;
-    /** Reservations overlapping `window` for one resource, as merged-ready half-open intervals. */
-    listBusy(resourceId: string, window: Interval): Promise<Interval[]>;
+    /** One of the tenant's live holds, or null (none, expired, confirmed, or another tenant's). */
+    getHold(params: {
+        tenantRef: string;
+        holdId: string;
+    }): Promise<SlotlockHold | null>;
+    /** The tenant's live holds on one resource, by start then id, keyset-paginated like events. */
+    listHolds(params: {
+        tenantRef: string;
+        resourceId: string;
+        limit?: number;
+        after?: {
+            start: Date;
+            id: string;
+        };
+    }): Promise<SlotlockHold[]>;
+    /**
+     * The tenant's booking with this reference as it now is (its current revision), or null: none,
+     * cancelled, or a calendar event's occupation, which is not a booking.
+     */
+    getReservation(params: {
+        tenantRef: string;
+        externalRef: string;
+    }): Promise<SlotlockReservation | null>;
+    /**
+     * The tenant's bookings on one resource whose occupied time meets `window` (at most 367 days),
+     * by start then id, keyset-paginated: pass the last one's `{ start, id }` as `after`.
+     */
+    listReservations(params: {
+        tenantRef: string;
+        resourceId: string;
+        window: Interval;
+        limit?: number;
+        after?: {
+            start: Date;
+            id: string;
+        };
+    }): Promise<SlotlockReservation[]>;
+    /**
+     * Flip an unexpired hold to a confirmed booking (expiry cleared). On a tenant's resource the
+     * booking takes the tenant, and the hold's id as its reference at revision 1, so cancel and
+     * reschedule reach it like any other (`reservation_cancelled` when a cancel of that reference
+     * came first). Confirming it again answers the booking as it now is. With `tenantRef`, only a
+     * hold on one of that tenant's resources counts: another tenant's is `hold_not_found` whatever
+     * the connection's row-level security.
+     */
+    confirmHold(holdId: string, options?: SlotlockHoldTenantOptions): Promise<ConfirmHoldResult>;
+    /**
+     * Delete a live hold; released=false when it was already gone (expired-reaped or confirmed). With
+     * `tenantRef`, only a hold on one of that tenant's resources, as for confirmHold.
+     */
+    releaseHold(holdId: string, options?: SlotlockHoldTenantOptions): Promise<ReleaseHoldResult>;
+    /**
+     * Reservations overlapping `window` for one resource, as merged-ready half-open intervals. With
+     * `tenantRef`, only a resource of that tenant (`resource_not_found` otherwise, whatever the
+     * connection's row-level security). An id the store never issues is `invalid_identity`. With
+     * `limit`, at most that many, the first by start.
+     */
+    listBusy(resourceId: string, window: Interval, options?: {
+        tenantRef?: string;
+        limit?: number;
+    }): Promise<Interval[]>;
     /** Create or revise one trusted event under expected-revision + tenant idempotency guards. */
     putCalendarEvent(params: PutCalendarEventCommand): Promise<PutCalendarEventResult>;
     /** Read one active event. A cancelled/tombstoned identity reads as absent. */
@@ -156,11 +322,24 @@ export interface SlotlockStore {
         ownerRef?: string;
         externalRef: string;
     }): Promise<SlotlockCalendarEvent | null>;
+    /**
+     * One of the tenant's active events by id, whichever owner (the tenant itself or an agent key)
+     * wrote it: null when there is none, it was cancelled, or it is another tenant's.
+     */
+    getCalendarEventById(params: {
+        tenantRef: string;
+        eventId: string;
+    }): Promise<SlotlockCalendarEvent | null>;
     /** List active events with at least one materialized occurrence intersecting the window. */
     listCalendarEvents(params: {
         tenantRef: string;
         /** Defaults to the trusted `internal` namespace. */
         ownerRef?: string;
+        /**
+         * Every owner's events, each with its `ownerRef`, so a tenant reaches what any of its keys
+         * booked, a revoked one's included. Not with `ownerRef`.
+         */
+        allOwners?: boolean;
         resourceId: string;
         window: Interval;
         limit?: number;
@@ -178,10 +357,34 @@ export interface SlotlockStore {
         externalRef: string;
         idempotencyKey: string;
         expectedRevision: number;
+        /**
+         * The resource the writer read the event on: `event_not_found` when the stored event is on
+         * another, checked under the event's lock.
+         */
+        expectedResourceId?: string;
+    }): Promise<CancelCalendarEventResult>;
+    /**
+     * The tenant's cancellation of one of its events by id, whichever owner wrote it: an agent key's
+     * included, after the key is revoked and when it has spent its command quota. The event's
+     * identity is cancelled (its tombstone is its owner's, so that key cannot re-create it), and the
+     * command is the tenant's own: its idempotency key is in the trusted `internal` namespace, where
+     * it replays. A cancelled event, an unknown id or another tenant's is `event_not_found`.
+     */
+    cancelCalendarEventById(params: {
+        tenantRef: string;
+        eventId: string;
+        idempotencyKey: string;
+        expectedRevision: number;
+        /** As for cancelCalendarEvent: `event_not_found` when the event is on another resource. */
+        expectedResourceId?: string;
     }): Promise<CancelCalendarEventResult>;
     /**
      * Atomically rematerialize due recurring masters into one rolling window without changing their
      * semantic revision. A collision rolls back that master and leaves its old coverage untouched.
+     * A master is rolled from the window's start through the later of its stored end and the
+     * window's, so its end never moves back. One that already covers the window, or whose end lies
+     * too far past it for the 367-day cap from the window's start, is not due: it is left as it is
+     * and not counted.
      */
     rollCalendarEventHorizon(params: {
         tenantRef: string;
@@ -205,6 +408,59 @@ export interface SlotlockStore {
         /** Replay window in whole days, 1-3650. Defaults to `SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS`. */
         retentionDays?: number;
     }): Promise<CalendarEventRetentionResult>;
+    /**
+     * Delete one bounded batch of a tenant's dead booking rows: holds past their expiry and the
+     * answers kept for keyed ones (at once), and references retired by a cancel no booking held,
+     * older than the retention window. A cancelled booking's tombstone is never deleted here (only by
+     * erasing the tenant), so its reference is never booked again. Rows another transaction holds
+     * are skipped, not waited on. It also gives a confirmed booking a 0.2 server wrote without its
+     * tenant the tenant and its own id as reference, as the migration does. Call until `hasMore` is
+     * false.
+     */
+    pruneBookingRetention(params: {
+        tenantRef: string;
+        /** Rows per class per call, 1-1000. Defaults to 100. */
+        limit?: number;
+        /**
+         * How long a stray retirement is kept, in whole days, 1-3650. Defaults to
+         * `SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS`.
+         */
+        retentionDays?: number;
+    }): Promise<BookingRetentionResult>;
+    /**
+     * Suspend a tenant: from when this returns, every withTenant transaction for it (as every server
+     * runs its requests) may read, and its writes are refused (`tenant_suspended`); one in flight is
+     * waited for. Its keys still authenticate, but it gets no new key or secret. Maintenance and
+     * erasure go on. True when it was not suspended already. Only the deployment role, which owns the
+     * schema, may suspend (`tenant_suspension_not_permitted` for another).
+     */
+    suspendTenant(params: {
+        tenantRef: string;
+        /** Why, for the operator: 1-500 characters without control characters. */
+        reason?: string;
+    }): Promise<{
+        suspended: boolean;
+    }>;
+    /** Lift a suspension; true when the tenant was suspended. The deployment role only. */
+    unsuspendTenant(params: {
+        tenantRef: string;
+    }): Promise<{
+        unsuspended: boolean;
+    }>;
+    /** Whether the tenant is suspended. */
+    isTenantSuspended(params: {
+        tenantRef: string;
+    }): Promise<boolean>;
+    /**
+     * Erase a tenant: delete every row it owns (resources, holds, bookings, events with their
+     * attendees and reminders, cancellations, idempotency records, coverage, API keys, and a personal
+     * tenant's dashboard records) in one transaction, waiting for its transactions in flight. API key
+     * digests are retired so no erased key works again; a suspension stays. Erasing again deletes
+     * nothing.
+     */
+    eraseTenant(params: {
+        tenantRef: string;
+    }): Promise<SlotlockTenantErasure>;
     /** Record the bounded, complete source window represented by a provider cursor/revision. */
     recordCalendarCoverage(params: CalendarCoverageCommand): Promise<CalendarCoverageResult>;
     /** Return merged busy intervals plus explicit completeness for caller-required provider sources. */
@@ -215,12 +471,27 @@ export interface SlotlockStore {
         requiredSources?: string[];
         coverageMaxAgeMs?: number;
     }): Promise<CalendarFreeBusy>;
-    /** Convenience composition: listBusy × expandRules (in the resource's stored timezone) → findNextAvailable. */
+    /**
+     * The first slot of `durationMs` inside the hours, whose time and turnaround buffer are free:
+     * getFreeBusy × expandRules (in the resource's stored timezone) → findNextAvailable. Null when no
+     * slot is free, and when one cannot be proven free: the coverage of the window (with the buffer's
+     * tail) is not complete, because a recurring series is not stored that far or a required provider
+     * calendar is not read that far. Another tenant's resource, an unknown id or one the store never
+     * issues is `resource_not_found`. A search window longer than 367 days is `invalid_window`.
+     */
     findNextAvailableFor(params: {
+        /** The resource's tenant; `null` for a resource that has none (the legacy namespace). */
+        tenantRef: string | null;
         resourceId: string;
-        rules: WeeklyAvailabilityRule[];
+        /** The hours to search; omitted, the resource's own (none: no slot). */
+        rules?: WeeklyAvailabilityRule[];
         searchWindow: Interval;
         durationMs: number;
+        /** Turnaround after the slot that must be free too (it may run past the hours), 0-30 days. */
+        bufferAfterMs?: number;
+        /** Provider sources that must prove complete coverage, as for getFreeBusy. */
+        requiredSources?: string[];
+        coverageMaxAgeMs?: number;
     }): Promise<Interval | null>;
 }
 export type SlotlockTenantStore = Omit<SlotlockStore, 'applySchema' | 'applyTenantRls' | 'grantApplicationRole' | 'withTenant'>;
@@ -231,6 +502,67 @@ export interface SlotlockStoreOptions {
     agentOwnerEventQuota?: number;
     /** Hard retained-command ceiling per non-internal owner. Defaults to 10,000; cannot be disabled. */
     agentOwnerCommandQuota?: number;
+    /**
+     * What one tenant may store, for a database tenants share (none by default). A write that would
+     * pass a limit is refused with it (`*_limit_reached`); what the tenant has can still be revised
+     * (a move adds no booking or event, so it is not refused), cancelled and released. Counted under
+     * a lock per tenant and limit, so racing writers never pass it, in READ COMMITTED transactions
+     * only (`invalid_transaction_isolation` otherwise). Bookings and events count while they are still
+     * to come, and for 30 days after they were made, whatever time they hold; history older than that
+     * does not count, and a count stops reading at the limit.
+     */
+    tenantLimits?: SlotlockTenantLimits;
+    /**
+     * How many withTenant transactions of one tenant run at once on this store (1-1,000; no limit by
+     * default). The rest wait in this process, in order, so one tenant's transactions waiting on its
+     * own locks hold at most this many of a pool's connections. Not counted inside a caller's
+     * transaction, which holds its connection already.
+     */
+    maxTenantTransactions?: number;
+    /**
+     * The longest a withTenant transaction waits for any one lock, in milliseconds (1-600,000; none by
+     * default). Past it the transaction is rolled back and refused with `lock_timeout`, which is safe
+     * to retry. Not set inside a caller's transaction.
+     */
+    tenantLockTimeoutMs?: number;
 }
+/** Per-tenant row limits, each a whole number from 1 to 10,000,000 (resources: to 100,000). */
+export interface SlotlockTenantLimits {
+    /** Resources, archived ones included; the lower of this and a call's `maxTenantResources`. */
+    resources?: number;
+    /**
+     * Holds on the tenant's resources, expired ones included until they are deleted. A keyed hold
+     * keeps its place until it would have expired, released or confirmed, while its answer is kept
+     * for retries. A hold at the limit first deletes the tenant's expired holds and forgets their
+     * answers, as maintenance does, so only live holds keep a new one out.
+     */
+    holds?: number;
+    /**
+     * Bookings still to come or made in the last 30 days, cancellations made in the last 30 days,
+     * and references a cancel retired with no booking until maintenance prunes them.
+     */
+    reservations?: number;
+    /**
+     * Calendar events of every owner still to come (a series until it is known to have ended) or made
+     * in the last 30 days, cancellations of every owner made in the last 30 days, and agent-owned
+     * cancellations until maintenance prunes them. Each event stores at most 2,000 occurrences.
+     */
+    events?: number;
+    /** Provider coverage rows: one per resource and source. */
+    coverage?: number;
+}
+export interface SlotlockHoldTenantOptions {
+    /** Only a hold on one of this tenant's resources: 1-500 UTF-8 bytes. */
+    tenantRef?: string;
+}
+/**
+ * At most `max` holders per tenant at once; the rest wait in order. An aborted signal takes a
+ * waiter out of the line, rejecting with its reason. Each holder calls the release it gets once.
+ */
+export declare function createTenantSlots(max: number): (tenantRef: string, signal?: AbortSignal) => Promise<() => void>;
 export declare function createSlotlockStore(sql: StoreSql, options?: SlotlockStoreOptions): SlotlockStore;
-export {};
+/**
+ * Every store method that writes for a tenant: what a suspended tenant's withTenant store refuses.
+ * Maintenance (rolling series, pruning, purging) and erasure are not among them.
+ */
+export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage"];