slotlock 0.1.0 → 0.2.0

package/self-host.d.ts

@@ -33,7 +33,10 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     availability: readonly WeeklyAvailabilityRule[];
     /** Set exactly when SLOTLOCK_GITHUB_CLIENT_ID is. */
     dashboard?: SlotlockServeDashboardConfig;
-    /** Serve the REST API under /v1 and its OpenAPI document (SLOTLOCK_REST_API=on). */
+    /**
+     * Serve the REST API under /v1, with the application API for admin keys, and its OpenAPI document
+     * (SLOTLOCK_REST_API: on unless off).
+     */
     restApi: boolean;
 }
 export declare function readSlotlockDatabaseConfig(env: SlotlockEnv): SlotlockDatabaseConfig;
@@ -84,7 +87,7 @@ export interface SlotlockRunningServer {
 }
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export declare function startSlotlockServer(config: SlotlockServeConfig, log: SlotlockLogger): Promise<SlotlockRunningServer>;
-export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP and A2A over HTTP (--migrate runs migrate first)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  key create <name> [--scope read|write|read,write] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry) and print it once; only its SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with every scope,\n                                 32+ random characters (serve); API keys work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve)\n  SLOTLOCK_CONFIRM_WRITES        all (default), none, or a comma-separated list of write tools\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on: also serve the tools as a REST API under /v1, described at\n                                 /openapi.json, with the same keys and confirmation (default off)\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
+export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with every scope,\n                                 32+ random characters (serve); API keys work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve)\n  SLOTLOCK_CONFIRM_WRITES        all (default), none, or a comma-separated list of write tools\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
 /**
  * Run one `slotlock` command and resolve to its exit code: 0 success, 1 failure, 2 a usage or
  * configuration error (nothing was started). `serve` resolves once `io.signal` aborts and it has

package/self-host.js

@@ -7,11 +7,13 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import postgres from 'postgres';
 import { createSlotlockAgentServer, slotlockAgentOperationScope, } from './agent-server.js';
-import { createSlotlockStoreAgentBackend } from './agent-store-backend.js';
-import { SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, slotlockBearerCredential, } from './api-keys.js';
+import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, } from './agent-store-backend.js';
+import { SLOTLOCK_API_KEY_DEFAULT_SCOPES, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, slotlockBearerCredential, } from './api-keys.js';
 import { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockDashboardState, } from './dashboard.js';
 import { SECRET_HINT, SlotlockConfigError, optional, readAvailability, readDashboardConfig, readSecret, readServerUrl, } from './config.js';
-import { SLOTLOCK_DASHBOARD_FUNCTIONS } from './ddl.js';
+import { SLOTLOCK_APPLICATION_SCOPE } from './application-api.js';
+import { SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_TENANT_TABLES } from './ddl.js';
+import { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 import { createSlotlockNodeServer, } from './node-server.js';
 import { slotlockPackageVersion } from './package-version.js';
 import { createSlotlockStore } from './store.js';
@@ -43,6 +45,15 @@ const SELF_HOST_SUBJECT = 'self-host';
 /** Who `key create` records as a key's creator. */
 const CLI_KEY_CREATOR = 'cli';
 const DAY_MS = 86_400_000;
+/**
+ * The most resources `serve` lets one tenant create through the application API. A dashboard open to
+ * every GitHub user gives each a tenant, so the cap keeps one from filling the database.
+ */
+const SERVE_MAX_TENANT_RESOURCES = 10_000;
+/** How often `serve` maintains each tenant it serves (README, Operations: at least daily). */
+const SERVE_MAINTENANCE_INTERVAL_MS = 60 * 60 * 1_000;
+/** Passes `slotlock maintain` runs at most, each as big as `serve`'s, until nothing is left. */
+const MAINTAIN_MAX_PASSES = 100;
 const WRITE_OPERATIONS = [
     'slotlock_create_event',
     'slotlock_update_event',
@@ -138,7 +149,7 @@ export function readSlotlockDatabaseConfig(env) {
     return config;
 }
 function readRestApi(env) {
-    const value = optional(env, 'SLOTLOCK_REST_API') ?? 'off';
+    const value = optional(env, 'SLOTLOCK_REST_API') ?? 'on';
     if (value !== 'on' && value !== 'off') {
         throw new SlotlockConfigError('SLOTLOCK_REST_API must be on or off');
     }
@@ -272,6 +283,13 @@ function describeError(error) {
     }
     return detail;
 }
+/** An agent server event's fields under the log's snake_case keys (`durationMs` → `duration_ms`). */
+function snakeCaseKeys(fields) {
+    return Object.fromEntries(Object.entries(fields).map(([key, value]) => [
+        key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`),
+        value,
+    ]));
+}
 function connect(url, max) {
     return postgres(url, { max, onnotice: () => { }, connect_timeout: 10 });
 }
@@ -358,6 +376,20 @@ export async function startSlotlockServer(config, log) {
         if (!schema?.present) {
             throw Object.assign(new Error('The slotlock schema is missing: run `slotlock migrate` or `slotlock serve --migrate`'), { code: 'schema_missing' });
         }
+        // A deployment run statement by statement lifts forced row-level security for its data steps
+        // and, stopped part way, leaves it lifted until the next one puts it back. The owning role then
+        // reads every tenant's rows: refuse to serve until then.
+        const lifted = await sql `
+      SELECT rel.relname AS name
+        FROM pg_catalog.pg_class rel
+        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace
+       WHERE ns.nspname = 'slotlock'
+         AND rel.relname IN ${sql(SLOTLOCK_TENANT_TABLES)}
+         AND rel.relrowsecurity AND NOT rel.relforcerowsecurity
+       ORDER BY rel.relname`;
+        if (lifted.length > 0) {
+            throw Object.assign(new Error(`Row-level security is enabled but not forced on ${lifted.map(({ name }) => `slotlock.${name}`).join(', ')}: a deployment stopped part way. Run \`slotlock migrate\` (or \`slotlock serve --migrate\`) to put it back`), { code: 'row_security_lifted' });
+        }
         if (config.dashboard) {
             for (const signature of SLOTLOCK_DASHBOARD_FUNCTIONS) {
                 const [granted] = await sql `
@@ -373,11 +405,15 @@ export async function startSlotlockServer(config, log) {
         const authenticateKey = createSlotlockApiKeyAuthenticator(createSlotlockApiKeyStore(sql));
         const authenticateToken = config.authToken === undefined
             ? undefined
-            : createSlotlockTokenAuthenticator(config.authToken, {
-                subject: SELF_HOST_SUBJECT,
-                tenantRef: config.tenantRef,
-                scopes: SLOTLOCK_API_KEY_SCOPES,
-            });
+            : // Read and write, never admin: this is the token the docs put in agents' configuration,
+                // and the application API's writes ask no person. An admin key is made for the purpose.
+                createSlotlockTokenAuthenticator(config.authToken, {
+                    subject: SELF_HOST_SUBJECT,
+                    tenantRef: config.tenantRef,
+                    scopes: SLOTLOCK_API_KEY_DEFAULT_SCOPES,
+                });
+        // Set once the listener is up; the authenticator tells it which tenants this server serves.
+        let maintenance;
         const agentServer = createSlotlockAgentServer({
             publicBaseUrl: config.publicUrl,
             // readPublicUrl admits plain HTTP only on a loopback host, which is all this permits anyway.
@@ -389,18 +425,32 @@ export async function startSlotlockServer(config, log) {
             // dashboard no longer allows loses their keys with their session.
             authenticate: async (request) => {
                 const principal = (await authenticateToken?.(request)) ?? (await authenticateKey(request));
-                return principal && dashboardAllows(config, principal.tenantRef) ? principal : null;
+                if (!principal || !dashboardAllows(config, principal.tenantRef))
+                    return null;
+                maintenance?.touch(principal.tenantRef);
+                return principal;
             },
             authorize: async ({ principal, operation }) => authorizeSlotlockServeOperation({ principal, operation }),
             health: async () => (await databaseReachable(sql))
                 ? { ready: true, checks: ['database'] }
                 : { ready: false, checks: ['database_unreachable'] },
             // Outcomes and counts only: the server never reports arguments or identities.
-            onEvent: ({ type, ...fields }) => log.info(type, fields),
+            onEvent: ({ type, ...fields }) => log.info(type, snakeCaseKeys(fields)),
             // What an agent sees only as internal_error: the operation and the error's message and code,
             // never the arguments or the request, with every configured secret redacted.
             onError: (error, { operation }) => log.error('agent_error', { operation, ...describeError(error) }),
-            ...(config.restApi ? { rest: true } : {}),
+            ...(config.restApi
+                ? {
+                    rest: true,
+                    // Resources, hours, holds, reservations, coverage and maintenance: admin keys only.
+                    application: {
+                        backend: createSlotlockStoreApplicationBackend(store, {
+                            maxTenantResources: SERVE_MAX_TENANT_RESOURCES,
+                        }),
+                        authorize: async ({ principal }) => principal.scopes?.includes(SLOTLOCK_APPLICATION_SCOPE) === true,
+                    },
+                }
+                : {}),
             ...(config.confirmationSecret !== undefined
                 ? {
                     confirmation: {
@@ -437,6 +487,15 @@ export async function startSlotlockServer(config, log) {
             onError: (error, phase) => log.error('http_error', { phase, ...describeError(error) }),
         });
         const address = await listener.listen({ host: config.host, port: config.port });
+        maintenance = startSlotlockMaintenance({
+            store,
+            sql,
+            tenants: [config.tenantRef],
+            intervalMs: SERVE_MAINTENANCE_INTERVAL_MS,
+            // Counts only, never the tenant.
+            onPass: (result) => log.info('maintenance', { ...result }),
+            onError: (error) => log.error('maintenance_failed', describeError(error)),
+        });
         log.info('listening', {
             address: address.origin,
             mcp: `${config.publicUrl}/mcp`,
@@ -446,11 +505,14 @@ export async function startSlotlockServer(config, log) {
             dashboard: dashboard ? `${config.publicUrl}/dashboard` : null,
             confirm_writes: config.confirmWrites,
             availability_rules: config.availability.length,
+            rest: config.restApi ? `${config.publicUrl}/openapi.json` : null,
+            maintenance_interval_minutes: SERVE_MAINTENANCE_INTERVAL_MS / 60_000,
         });
         return {
             address,
             async close() {
                 const result = await listener.close();
+                await maintenance?.close();
                 await sql.end({ timeout: 5 });
                 return result;
             },
@@ -579,17 +641,47 @@ function apiKeyLine(apiKey, key) {
         ...(key !== undefined ? { key } : {}),
     })}\n`;
 }
-/** `--scope`: read, write, or both comma-separated. */
+/** `--scope`: read, write and admin, comma-separated; read,write unless given. */
 function parseKeyScopes(value) {
     if (value === undefined)
-        return [...SLOTLOCK_API_KEY_SCOPES];
+        return [...SLOTLOCK_API_KEY_DEFAULT_SCOPES];
     const names = value.split(',').map((name) => name.trim());
     const scopes = SLOTLOCK_API_KEY_SCOPES.filter((scope) => names.includes(scope));
     if (names.length === 0 || names.some((name) => !scopes.includes(name))) {
-        throw new Error('--scope must be read, write or read,write');
+        throw new Error('--scope must be a comma-separated list of read, write and admin');
     }
     return scopes;
 }
+/**
+ * `maintain`: maintenance passes for the tenant until nothing is left, under the tenant's lock, so
+ * it never repeats what a server is doing. Null when another server holds the lock.
+ */
+async function maintainTenant(config) {
+    const sql = connect(config.databaseUrl, 2);
+    try {
+        const store = createSlotlockStore(sql);
+        const total = await withSlotlockMaintenanceLock(sql, config.tenantRef, async () => {
+            const sum = { extended: 0, conflicts: 0, refused: 0, pruned: 0, capped: true, passes: 0 };
+            while (sum.capped && sum.passes < MAINTAIN_MAX_PASSES) {
+                const pass = await maintainSlotlockTenant(store, config.tenantRef);
+                sum.passes += 1;
+                sum.extended += pass.extended;
+                sum.conflicts += pass.conflicts;
+                sum.refused += pass.refused;
+                sum.pruned += pass.pruned;
+                // A capped pass that got nowhere met only series it cannot extend: another would too.
+                sum.capped = pass.capped;
+                if (pass.capped && pass.extended + pass.pruned === 0)
+                    break;
+            }
+            return sum;
+        });
+        return total ?? null;
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
 /** `--expires-in-days`: a whole number of days up to the longest a key may live. */
 function parseKeyLifetime(value) {
     if (value === undefined)
@@ -632,7 +724,10 @@ export const SLOTLOCK_CLI_HELP = `Usage: slotlock <command> [options]
 Commands:
   migrate                  Apply the schema and row-level security, then grant the serving
                            role when SLOTLOCK_MIGRATE_DATABASE_URL names another role
-  serve [--migrate]        Serve MCP and A2A over HTTP (--migrate runs migrate first)
+  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);
+                           maintains each tenant it serves every hour
+  maintain                 Run maintenance for the tenant now: extend recurring events to the
+                           rolling horizon and prune past the retention window (for cron)
   resource add <ref> [--timezone <IANA zone>]
                            Create a calendar resource (a car, room, person or machine)
   resource list            Print the tenant's resources, one JSON object per line
@@ -642,9 +737,10 @@ Commands:
                            Give one resource, or every one, weekly hours of its own; [] closes
   hours clear (--resource <ref> | --all)
                            Hand one resource, or every one, back to the server's hours
-  key create <name> [--scope read|write|read,write] [--expires-in-days <n>]
+  key create <name> [--scope read,write,admin] [--expires-in-days <n>]
                            Create an API key for the tenant (default scope read,write, no
-                           expiry) and print it once; only its SHA-256 is stored
+                           expiry; admin adds the application API) and print it once; only its
+                           SHA-256 is stored
   key list                 Print the tenant's API keys, one JSON object per line
   key rotate <id>          Give an active key a new secret and print it once; the old one stops
                            working at once, and the key keeps its id and what it booked
@@ -666,8 +762,9 @@ Environment:
   SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)
   SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default "default")
   SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)
-  SLOTLOCK_REST_API              on: also serve the tools as a REST API under /v1, described at
-                                 /openapi.json, with the same keys and confirmation (default off)
+  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and
+                                 the application API for admin keys, described at /openapi.json;
+                                 off: MCP and A2A only
   SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID
                                  of a GitHub OAuth app with callback .../dashboard/callback
   SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)
@@ -715,6 +812,7 @@ export async function runSlotlockCli(argv, io) {
     const expectedOperands = {
         migrate: 0,
         serve: 0,
+        maintain: 0,
         healthcheck: 0,
         'resource add': 2,
         'resource list': 1,
@@ -797,6 +895,15 @@ export async function runSlotlockCli(argv, io) {
                 log.info('stopped', { forced });
                 return 0;
             }
+            case 'maintain': {
+                const result = await maintainTenant(readSlotlockDatabaseConfig(io.env));
+                if (!result) {
+                    io.stderr.write('slotlock: another server is maintaining this tenant now; nothing to do\n');
+                    return 0;
+                }
+                io.stdout.write(`${JSON.stringify(result)}\n`);
+                return 0;
+            }
             case 'resource add': {
                 const config = readSlotlockDatabaseConfig(io.env);
                 const resource = await addResource(config, operands[1], values.timezone ?? 'UTC');

package/slotlock.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0",
   "name": "Slotlock",
   "package": "slotlock",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "intervalSemantics": {
     "boundary": "[)",

package/store.d.ts

@@ -1,6 +1,7 @@
 import type { Sql, TransactionSql } from 'postgres';
+import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
 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;
+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
@@ -120,7 +121,11 @@ export interface SlotlockStore {
         end: Date;
         source?: 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>;
@@ -141,10 +146,17 @@ export interface SlotlockStore {
         ttlMs: number;
         source?: 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>;
+    /**
+     * Flip an unexpired hold to a confirmed reservation (expiry cleared). Confirming it again answers
+     * the same reservation. 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. */
     listBusy(resourceId: string, window: Interval): Promise<Interval[]>;
     /** Create or revise one trusted event under expected-revision + tenant idempotency guards. */
@@ -182,6 +194,10 @@ export interface SlotlockStore {
     /**
      * 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;
@@ -215,7 +231,10 @@ export interface SlotlockStore {
         requiredSources?: string[];
         coverageMaxAgeMs?: number;
     }): Promise<CalendarFreeBusy>;
-    /** Convenience composition: listBusy × expandRules (in the resource's stored timezone) → findNextAvailable. */
+    /**
+     * Convenience composition: listBusy × expandRules (in the resource's stored timezone) →
+     * findNextAvailable. A search window longer than 367 days is refused (`invalid_window`).
+     */
     findNextAvailableFor(params: {
         resourceId: string;
         rules: WeeklyAvailabilityRule[];
@@ -232,5 +251,8 @@ export interface SlotlockStoreOptions {
     /** Hard retained-command ceiling per non-internal owner. Defaults to 10,000; cannot be disabled. */
     agentOwnerCommandQuota?: number;
 }
+export interface SlotlockHoldTenantOptions {
+    /** Only a hold on one of this tenant's resources: 1-500 UTF-8 bytes. */
+    tenantRef?: string;
+}
 export declare function createSlotlockStore(sql: StoreSql, options?: SlotlockStoreOptions): SlotlockStore;
-export {};

package/store.js

@@ -4,7 +4,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { SLOTLOCK_CORE_DDL, SLOTLOCK_SCHEMA_CONTROL_REFUSAL, SLOTLOCK_TENANT_CONTEXT_SETTING, createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, } from './ddl.js';
 import { findNextAvailable, mergeIntervals } from './engine.js';
-import { expandRules } from './rules.js';
+import { SLOTLOCK_CALENDAR_HORIZON_DAYS, assertBoundedSearchWindow, expandRules, invalidWindowError, } from './rules.js';
 import { CalendarContractError, CalendarExpansionLimitError, expandCalendarEventSeries, normalizeCalendarEventContent, } from './sync.js';
 import { parseAvailabilityRules } from './weekly-hours.js';
 /** Postgres exclusion_violation — the EXCLUDE constraint fired. */
@@ -21,7 +21,7 @@ const SERIALIZATION_FAILURE = '40001';
 const MAX_HOLD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Turnaround cannot occupy a resource indefinitely because of a caller/unit error. */
 const MAX_BUFFER_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
-export const SLOTLOCK_CALENDAR_HORIZON_DAYS = 367;
+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
@@ -89,6 +89,19 @@ function resumeStoredSeries(event, window, found) {
 function seriesCursorJson(tx, cursor) {
     return cursor === null ? null : tx.json(cursor);
 }
+/**
+ * The window a roll to `horizon` gives a series stored for `stored`: from the horizon's start to
+ * the later of the two ends, so its end never moves back. `null` keeps the stored window: it covers
+ * the horizon already, or it ends so far past it that no window from the horizon's start to its end
+ * fits the 367-day cap (it rolls once the horizon is close enough).
+ */
+function rolledWindow(stored, horizon) {
+    if (stored.start <= horizon.start && stored.end >= horizon.end)
+        return null;
+    if (stored.end.getTime() - horizon.start.getTime() > MAX_CALENDAR_WINDOW_MS)
+        return null;
+    return { start: horizon.start, end: stored.end > horizon.end ? stored.end : horizon.end };
+}
 /** The roll's `after`, checked, or `undefined` for a pass's first batch. */
 function rollCursor(after) {
     if (after === undefined)
@@ -174,11 +187,6 @@ function isFiniteWindow(window) {
         Number.isFinite(window.end.getTime()) &&
         window.end.getTime() > window.start.getTime());
 }
-function invalidWindowError() {
-    return Object.assign(new Error('Slotlock window must contain two finite dates with end > start'), {
-        code: 'invalid_window',
-    });
-}
 function isValidIdentity(value) {
     return value !== undefined && value.trim().length > 0 && Buffer.byteLength(value, 'utf8') <= 500;
 }
@@ -721,6 +729,18 @@ async function overlapLoss(sql, resourceId, start, end, bufferAfterMs = 0, exclu
      LIMIT 1`;
     return { ok: false, code: 'overlap', conflictingReservationId: winners[0]?.id ?? null };
 }
+/** The tenant a hold call is limited to, or null for none; an invalid one is refused. */
+function holdTenantRef(options) {
+    const tenantRef = options.tenantRef;
+    if (tenantRef === undefined)
+        return null;
+    if (!isValidIdentity(tenantRef)) {
+        throw Object.assign(new Error('Slotlock tenantRef must be 1-500 UTF-8 bytes'), {
+            code: 'invalid_tenant_ref',
+        });
+    }
+    return tenantRef;
+}
 export function createSlotlockStore(sql, options = {}) {
     const configuredTenantSetting = options.tenantContextSetting ?? SLOTLOCK_TENANT_CONTEXT_SETTING;
     const configuredAgentOwnerEventQuota = options.agentOwnerEventQuota ?? SLOTLOCK_AGENT_OWNER_EVENT_QUOTA;
@@ -1077,14 +1097,22 @@ export function createSlotlockStore(sql, options = {}) {
                WHERE tenant_ref = ${params.tenantRef} AND external_ref = ${params.externalRef}`;
                         if (cancelled[0])
                             return { ok: false, code: 'reservation_cancelled' };
+                        // A calendar event's occupation carries a reference in this namespace too, but it is
+                        // not a booking: create, reschedule and cancel never read, replay, move or free it,
+                        // and answer as for a reference no booking holds. Bookings have their own unique index.
                         const existing = await tx `
               SELECT id, resource_id, tenant_ref, external_ref, starts_at, ends_at,
                      buffer_after_ms, revision, source
                 FROM slotlock.reservations
                WHERE tenant_ref = ${params.tenantRef} AND external_ref = ${params.externalRef}
+                 AND calendar_event_id IS NULL
                FOR UPDATE`;
                         const found = existing[0];
                         if (found) {
+                            // The booking has moved on since: a delayed create is stale, as a delayed move is.
+                            if (params.revision < Number(found.revision)) {
+                                return { ok: false, code: 'stale_revision' };
+                            }
                             if (!sameExternalPayload(found, params)) {
                                 return { ok: false, code: 'idempotency_conflict' };
                             }
@@ -1138,6 +1166,7 @@ export function createSlotlockStore(sql, options = {}) {
                      buffer_after_ms, revision, source
                 FROM slotlock.reservations
                WHERE tenant_ref = ${params.tenantRef} AND external_ref = ${params.externalRef}
+                 AND calendar_event_id IS NULL
                FOR UPDATE`;
                         const found = existing[0];
                         if (!found) {
@@ -1222,6 +1251,7 @@ export function createSlotlockStore(sql, options = {}) {
                 const existing = await tx `
           SELECT id, revision FROM slotlock.reservations
            WHERE tenant_ref = ${params.tenantRef} AND external_ref = ${params.externalRef}
+             AND calendar_event_id IS NULL
            FOR UPDATE`;
                 const found = existing[0];
                 if (found) {
@@ -1294,11 +1324,14 @@ export function createSlotlockStore(sql, options = {}) {
                 }
             }
         },
-        async confirmHold(holdId) {
+        async confirmHold(holdId, options = {}) {
+            const tenantRef = holdTenantRef(options);
             const rows = await sql `
         UPDATE slotlock.reservations
            SET status = 'confirmed', expires_at = NULL
          WHERE id = ${holdId} AND status = 'held' AND expires_at > now()
+           AND (${tenantRef}::text IS NULL
+                OR resource_id IN (SELECT id FROM slotlock.resources WHERE tenant_ref = ${tenantRef}))
          RETURNING id, resource_id, starts_at, ends_at, source`;
             const row = rows[0];
             if (row) {
@@ -1320,7 +1353,13 @@ export function createSlotlockStore(sql, options = {}) {
             const present = await sql `
         SELECT status, (status = 'held' AND expires_at <= now()) AS expired,
                resource_id, starts_at, ends_at, source
-          FROM slotlock.reservations WHERE id = ${holdId}`;
+          FROM slotlock.reservations
+         WHERE id = ${holdId}
+           -- A hold has no external identity, before or after it is confirmed; a booking that has
+           -- one is not a hold, and confirming it again would describe it wrongly.
+           AND tenant_ref IS NULL
+           AND (${tenantRef}::text IS NULL
+                OR resource_id IN (SELECT id FROM slotlock.resources WHERE tenant_ref = ${tenantRef}))`;
             const found = present[0];
             // Idempotent confirm: a retried confirm (network replay) of an already-confirmed hold is
             // SUCCESS — the booking exists; reporting failure would make callers double-book elsewhere.
@@ -1347,10 +1386,13 @@ export function createSlotlockStore(sql, options = {}) {
             // taken; both refusal codes are terminal for the caller.
             return { ok: false, code: 'hold_not_found' };
         },
-        async releaseHold(holdId) {
+        async releaseHold(holdId, options = {}) {
+            const tenantRef = holdTenantRef(options);
             const rows = await sql `
         DELETE FROM slotlock.reservations
          WHERE id = ${holdId} AND status = 'held'
+           AND (${tenantRef}::text IS NULL
+                OR resource_id IN (SELECT id FROM slotlock.resources WHERE tenant_ref = ${tenantRef}))
          RETURNING id`;
             return { ok: true, released: rows.length > 0 };
         },
@@ -1704,15 +1746,18 @@ export function createSlotlockStore(sql, options = {}) {
                 });
             }
             const after = rollCursor(params.after);
+            // Due: the masters rolledWindow rolls, which do not cover the window and end within the cap
+            // of its start.
             const candidates = await sql `
         SELECT id, materialized_ends_at
           FROM slotlock.calendar_events
          WHERE tenant_ref = ${params.tenantRef}
            AND recurrence_rule IS NOT NULL
            AND (
-             materialized_starts_at <> ${window.start}
+             materialized_starts_at > ${window.start}
              OR materialized_ends_at < ${window.end}
            )
+           AND materialized_ends_at <= ${new Date(window.start.getTime() + MAX_CALENDAR_WINDOW_MS)}
            AND (
              ${after?.materializedEndsAt ?? null}::timestamptz IS NULL
              OR (materialized_ends_at, id) >
@@ -1738,16 +1783,15 @@ export function createSlotlockStore(sql, options = {}) {
                   FROM slotlock.calendar_events
                  WHERE id = ${candidate.id} AND tenant_ref = ${params.tenantRef}
                  FOR UPDATE`;
-                            if (!row ||
-                                row.recurrence_rule === null ||
-                                (row.materialized_starts_at.getTime() === window.start.getTime() &&
-                                    row.materialized_ends_at >= window.end)) {
+                            if (!row || row.recurrence_rule === null)
+                                return false;
+                            const rolled = rolledWindow({ start: row.materialized_starts_at, end: row.materialized_ends_at }, window);
+                            if (!rolled)
                                 return false;
-                            }
                             const childMap = await loadCalendarEventChildren(tx, [row.id]);
                             const event = toCalendarEvent(row, childMap.get(row.id));
                             // From where its last expansion stopped, when that can be trusted; else its start.
-                            const { occurrences, cursor } = expandCalendarEventSeries(event, window, {
+                            const { occurrences, cursor } = expandCalendarEventSeries(event, rolled, {
                                 cursor: row.recurrence_cursor ?? null,
                                 stored: true,
                             });
@@ -1761,8 +1805,8 @@ export function createSlotlockStore(sql, options = {}) {
                             });
                             await tx `
                 UPDATE slotlock.calendar_events
-                   SET materialized_starts_at = ${window.start},
-                       materialized_ends_at = ${window.end},
+                   SET materialized_starts_at = ${rolled.start},
+                       materialized_ends_at = ${rolled.end},
                        recurrence_cursor = ${seriesCursorJson(tx, cursor)}
                  WHERE id = ${row.id} AND tenant_ref = ${params.tenantRef}`;
                             return true;
@@ -2157,19 +2201,16 @@ export function createSlotlockStore(sql, options = {}) {
              AND event.transparency = 'opaque'
         )
         SELECT count(*)::int AS source_count,
+               -- Complete when what is stored runs from where the series can first occur in the
+               -- window (its start, if that is later) to the window's end: a series stored only
+               -- from after its start leaves the occurrences before that unknown.
                bool_and(
                  materialized_ends_at >= ${window.end}
-                 AND (
-                   earliest_possible_at >= ${window.start}
-                   OR materialized_starts_at <= ${window.start}
-                 )
+                 AND materialized_starts_at <= GREATEST(earliest_possible_at, ${window.start})
                ) AS complete,
                bool_or(
                  materialized_ends_at > ${window.start}
-                 AND (
-                   earliest_possible_at >= ${window.start}
-                   OR materialized_starts_at < ${window.end}
-                 )
+                 AND materialized_starts_at < ${window.end}
                ) AS overlaps
           FROM recurring_sources
          WHERE earliest_possible_at < ${window.end}`;
@@ -2222,6 +2263,7 @@ export function createSlotlockStore(sql, options = {}) {
         async findNextAvailableFor(params) {
             if (!isFiniteWindow(params.searchWindow))
                 throw invalidWindowError();
+            assertBoundedSearchWindow(params.searchWindow);
             if (!Number.isFinite(params.durationMs) || params.durationMs <= 0)
                 return null;
             // Rules are authored in the resource's zone — expansion must honour it (DST-correct).