slotlock 0.5.2 → 0.5.3

package/ddl.js

@@ -11,6 +11,7 @@
 // the caller's search_path back at the end, so a caller that keeps going in the same transaction
 // resolves its own names as before. Apply it in one transaction: under autocommit every statement
 // is a transaction of its own, and the pin ends with the statement that sets it.
+import { SLOTLOCK_CHANGE_ORIGINS, slotlockCoverageSourceIdSql } from './event-feed.js';
 import { SLOTLOCK_MAX_AVAILABILITY_RULES } from './weekly-hours.js';
 const CALLER_SEARCH_PATH_SETTING = 'slotlock.caller_search_path';
 const DEPLOYMENT_SEARCH_PATH_PIN = `SELECT pg_catalog.set_config('${CALLER_SEARCH_PATH_SETTING}', pg_catalog.current_setting('search_path'), true);
@@ -550,6 +551,55 @@ AS $slotlock_erase_api_keys$
   SELECT count(*) FROM erased;
 $slotlock_erase_api_keys$;
 REVOKE ALL ON FUNCTION ${SLOTLOCK_API_KEY_FUNCTIONS[5]} FROM PUBLIC;
+
+-- A key created, given a new secret or revoked appends to its tenant's feed (key.created,
+-- key.rotated, key.revoked): its id, scopes and expiry, never its digest, prefix or name. Only the
+-- functions above write keys, as the schema's owner, which forced row-level security on the feed
+-- binds too: the row is appended under the tenant's name in every setting a policy reads, and the
+-- caller's values are put back after. Who did it is the caller's actor, else the key's creator.
+CREATE OR REPLACE FUNCTION slotlock.outbox_api_key_change()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_outbox_api_key$
+DECLARE
+  kind text;
+  setting text;
+  previous jsonb := '{}'::jsonb;
+BEGIN
+  IF TG_OP = 'INSERT' THEN
+    kind := 'key.created';
+  ELSIF OLD.revoked_at IS NULL AND NEW.revoked_at IS NOT NULL THEN
+    kind := 'key.revoked';
+  ELSIF OLD.secret_hash IS DISTINCT FROM NEW.secret_hash THEN
+    kind := 'key.rotated';
+  ELSE
+    RETURN NULL;
+  END IF;
+  FOR setting IN
+    SELECT DISTINCT contract.tenant_context_setting FROM slotlock.rls_policy_contracts contract
+  LOOP
+    previous := previous || jsonb_build_object(setting, current_setting(setting, true));
+    PERFORM set_config(setting, NEW.tenant_ref, true);
+  END LOOP;
+  INSERT INTO slotlock.outbox (tenant_ref, type, subject, data, actor)
+  VALUES (
+    NEW.tenant_ref, kind, NEW.id::text,
+    jsonb_build_object(
+      'id', NEW.id, 'scopes', to_jsonb(NEW.scopes), 'expires_at', NEW.expires_at,
+      'revoked_at', NEW.revoked_at),
+    COALESCE(NULLIF(current_setting('slotlock.actor', true), ''),
+             CASE WHEN TG_OP = 'INSERT' THEN NEW.created_by END)
+  );
+  FOR setting IN SELECT jsonb_object_keys(previous) LOOP
+    PERFORM set_config(setting, COALESCE(previous ->> setting, ''), true);
+  END LOOP;
+  RETURN NULL;
+END
+$slotlock_outbox_api_key$;
+CREATE OR REPLACE TRIGGER slotlock_outbox_api_key_change
+  AFTER INSERT OR UPDATE OF revoked_at, secret_hash ON slotlock.api_keys
+  FOR EACH ROW EXECUTE FUNCTION slotlock.outbox_api_key_change();
 `;
 // The dashboard's records (dashboard.ts), shared by every server on this database: a finished sign-in
 // (its callback works once), a sent form (it runs once) and a signed-out session (a copied cookie
@@ -875,6 +925,10 @@ BEGIN
   DELETE FROM slotlock.waitlist_entries WHERE tenant_ref = requested_tenant_ref;
   GET DIAGNOSTICS erased_rows = ROW_COUNT;
   RETURN NEXT;
+  erased_table := 'booking_rule_defaults';
+  DELETE FROM slotlock.booking_rule_defaults WHERE tenant_ref = requested_tenant_ref;
+  GET DIAGNOSTICS erased_rows = ROW_COUNT;
+  RETURN NEXT;
   erased_table := 'assistant_conversations';
   DELETE FROM slotlock.assistant_conversations WHERE tenant_ref = requested_tenant_ref;
   GET DIAGNOSTICS erased_rows = ROW_COUNT;
@@ -1194,6 +1248,36 @@ CREATE TABLE IF NOT EXISTS slotlock.outbox (
 );
 -- Who made the change (withTenant's actor: an API key, an agent), for the history.
 ALTER TABLE slotlock.outbox ADD COLUMN IF NOT EXISTS actor text;
+-- Where it came from (withTenant's origin: mcp, a2a, rest, application, dashboard,
+-- dashboard-assistant, maintenance, library) and the API key that made it (withTenant's keyId).
+-- Added bare, so the rows already there keep null (an earlier release) and nothing is scanned under
+-- the lock; the defaults then bind only new rows. A write that names no origin (code calling the
+-- store outside withTenant, or SQL of its own) is \`library\`.
+ALTER TABLE slotlock.outbox ADD COLUMN IF NOT EXISTS origin text;
+ALTER TABLE slotlock.outbox ADD COLUMN IF NOT EXISTS key_id uuid;
+ALTER TABLE slotlock.outbox
+  ALTER COLUMN origin SET DEFAULT COALESCE(NULLIF(current_setting('slotlock.origin', true), ''), 'library'),
+  ALTER COLUMN key_id SET DEFAULT NULLIF(current_setting('slotlock.key_id', true), '')::uuid;
+-- The origins the API reads, and no other. NOT VALID, so adding it scans nothing under the lock;
+-- DEPLOYMENT_VALIDATE_CONSTRAINTS validates it after the migration commits. Its comment is the list
+-- it was built from: a release that changes the list replaces it, so an upgraded database never
+-- keeps refusing an origin the release writes.
+DO $slotlock_outbox_origin$
+BEGIN
+  ALTER TABLE slotlock.outbox DROP CONSTRAINT IF EXISTS slotlock_outbox_origin_valid;
+  IF (
+    SELECT pg_catalog.obj_description(oid, 'pg_constraint') FROM pg_catalog.pg_constraint
+     WHERE conrelid = 'slotlock.outbox'::regclass AND conname = 'slotlock_outbox_origin_known'
+  ) IS DISTINCT FROM '${SLOTLOCK_CHANGE_ORIGINS.join(' ')}' THEN
+    ALTER TABLE slotlock.outbox DROP CONSTRAINT IF EXISTS slotlock_outbox_origin_known;
+    ALTER TABLE slotlock.outbox
+      ADD CONSTRAINT slotlock_outbox_origin_known
+      CHECK (origin IN (${SLOTLOCK_CHANGE_ORIGINS.map((origin) => `'${origin}'`).join(', ')})) NOT VALID;
+    COMMENT ON CONSTRAINT slotlock_outbox_origin_known ON slotlock.outbox
+      IS '${SLOTLOCK_CHANGE_ORIGINS.join(' ')}';
+  END IF;
+END
+$slotlock_outbox_origin$;
 CREATE INDEX IF NOT EXISTS slotlock_outbox_tenant_resource_idx
   ON slotlock.outbox (tenant_ref, resource_id, id) WHERE resource_id IS NOT NULL;
 CREATE INDEX IF NOT EXISTS slotlock_outbox_tenant_subject_idx
@@ -1248,6 +1332,10 @@ $slotlock_outbox_mark_pruned$;
 CREATE OR REPLACE TRIGGER slotlock_outbox_mark_pruned
   AFTER DELETE ON slotlock.outbox REFERENCING OLD TABLE AS pruned
   FOR EACH STATEMENT EXECUTE FUNCTION slotlock.outbox_mark_pruned();
+-- Live updates poll each tenant's feed (change-watch.ts). A pre-release build woke readers with a
+-- notification trigger here, which made every outbox commit take the cluster-wide notify lock: drop it.
+DROP TRIGGER IF EXISTS slotlock_outbox_notify ON slotlock.outbox;
+DROP FUNCTION IF EXISTS slotlock.outbox_notify();
 
 CREATE TABLE IF NOT EXISTS slotlock.webhook_endpoints (
   id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -1275,14 +1363,31 @@ CREATE TABLE IF NOT EXISTS slotlock.webhook_endpoints (
     AND octet_length(url) BETWEEN 1 AND 2048
     AND secret ~ '^whsec_[A-Za-z0-9+/]{43}=$'
   ),
-  CONSTRAINT slotlock_webhook_endpoints_types_valid CHECK (
-    event_types IS NULL OR cardinality(event_types) BETWEEN 1 AND 20
+  CONSTRAINT slotlock_webhook_endpoints_type_count_valid CHECK (
+    event_types IS NULL OR cardinality(event_types) BETWEEN 1 AND 64
   ),
   CONSTRAINT slotlock_webhook_endpoints_error_valid CHECK (
     last_error IS NULL OR char_length(last_error) <= 500
   )
 );
 ALTER TABLE slotlock.webhook_endpoints ADD COLUMN IF NOT EXISTS changes_pruned boolean NOT NULL DEFAULT false;
+-- 0.5 allowed a filter of at most 20 types, fewer than there are now. The wider CHECK admits every
+-- row the old one did, so it is added NOT VALID (no scan under the lock), and the old one dropped.
+DO $slotlock_webhook_type_count$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_catalog.pg_constraint
+     WHERE conrelid = 'slotlock.webhook_endpoints'::regclass
+       AND conname = 'slotlock_webhook_endpoints_type_count_valid'
+  ) THEN
+    ALTER TABLE slotlock.webhook_endpoints
+      ADD CONSTRAINT slotlock_webhook_endpoints_type_count_valid CHECK (
+        event_types IS NULL OR cardinality(event_types) BETWEEN 1 AND 64
+      ) NOT VALID;
+  END IF;
+  ALTER TABLE slotlock.webhook_endpoints DROP CONSTRAINT IF EXISTS slotlock_webhook_endpoints_types_valid;
+END
+$slotlock_webhook_type_count$;
 CREATE INDEX IF NOT EXISTS slotlock_webhook_endpoints_tenant_idx
   ON slotlock.webhook_endpoints (tenant_ref, created_at);
 
@@ -1321,6 +1426,23 @@ CREATE INDEX IF NOT EXISTS slotlock_waitlist_entries_queue_idx
 CREATE INDEX IF NOT EXISTS slotlock_waitlist_entries_tenant_idx
   ON slotlock.waitlist_entries (tenant_ref, starts_at);
 
+-- Default booking rules (booking-rules.ts), for the tenant (pool_ref '') or for one of its pools:
+-- a resource's rules are the tenant's, overlaid by its pool's, overlaid by its own.
+CREATE TABLE IF NOT EXISTS slotlock.booking_rule_defaults (
+  tenant_ref text NOT NULL,
+  pool_ref text NOT NULL DEFAULT '',
+  rules jsonb NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT statement_timestamp(),
+  CONSTRAINT slotlock_booking_rule_defaults_pkey PRIMARY KEY (tenant_ref, pool_ref),
+  CONSTRAINT slotlock_booking_rule_defaults_identity_valid CHECK (
+    octet_length(tenant_ref) BETWEEN 1 AND 500
+    AND (pool_ref = '' OR pool_ref ~ '^[a-z0-9][a-z0-9._-]{0,99}$')
+  ),
+  CONSTRAINT slotlock_booking_rule_defaults_rules_valid CHECK (
+    jsonb_typeof(rules) = 'object' AND octet_length(rules::text) <= 4096
+  )
+);
+
 -- The model a tenant's dashboard assistant uses (dashboard.ts, assistant.ts), one row a tenant.
 -- The API key is stored only sealed (AES-256-GCM under the deployment's SLOTLOCK_ASSISTANT_SECRET,
 -- bound to the tenant), with its last four characters to show.
@@ -1543,6 +1665,163 @@ ALTER TABLE slotlock.calendar_coverage ADD COLUMN IF NOT EXISTS last_error text;
 ALTER TABLE slotlock.calendar_coverage ADD COLUMN IF NOT EXISTS last_error_at timestamptz;
 ALTER TABLE slotlock.calendar_coverage ADD COLUMN IF NOT EXISTS stale_reported_at timestamptz;
 
+-- Configuration changes (RFC 0002 P1-6): a resource's own settings, the sources its coverage is
+-- read from, and the tenant's webhook endpoints. Each change that alters something appends one row,
+-- with what it was before and after for the fields it changed; writing the same value again appends
+-- none. Erasure is not reported, as above.
+CREATE OR REPLACE FUNCTION slotlock.outbox_erasing(owner text)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_outbox_erasing$
+  SELECT owner = current_setting('slotlock.erasing', true)
+     AND current_user = (SELECT pg_catalog.pg_get_userbyid(nspowner) FROM pg_catalog.pg_namespace
+                          WHERE nspname = 'slotlock');
+$slotlock_outbox_erasing$;
+
+CREATE OR REPLACE FUNCTION slotlock.outbox_resource_change()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_outbox_resource$
+DECLARE
+  changed slotlock.resources%ROWTYPE;
+  kind text;
+  before jsonb := '{}'::jsonb;
+  after jsonb := '{}'::jsonb;
+  details jsonb;
+BEGIN
+  changed := CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  IF changed.tenant_ref IS NULL OR slotlock.outbox_erasing(changed.tenant_ref) THEN RETURN NULL; END IF;
+  IF TG_OP = 'INSERT' THEN
+    kind := 'resource.created';
+    details := jsonb_build_object(
+      'timezone', NEW.timezone, 'visibility', NEW.visibility, 'pool', NEW.pool_ref,
+      'availability', NEW.availability_rules, 'booking_rules', NEW.booking_rules);
+  ELSIF TG_OP = 'DELETE' THEN
+    kind := 'resource.deleted';
+    details := '{}'::jsonb;
+  ELSIF (OLD.archived_at IS NULL) <> (NEW.archived_at IS NULL) THEN
+    kind := CASE WHEN NEW.archived_at IS NULL THEN 'resource.restored' ELSE 'resource.archived' END;
+    details := jsonb_build_object('archived_at', NEW.archived_at);
+  ELSE
+    -- Only what changed, under the names the API gives it; a null is kept (no pool, no rules).
+    IF OLD.external_ref IS DISTINCT FROM NEW.external_ref THEN
+      before := before || jsonb_build_object('reference', OLD.external_ref);
+      after := after || jsonb_build_object('reference', NEW.external_ref);
+    END IF;
+    IF OLD.timezone IS DISTINCT FROM NEW.timezone THEN
+      before := before || jsonb_build_object('timezone', OLD.timezone);
+      after := after || jsonb_build_object('timezone', NEW.timezone);
+    END IF;
+    IF OLD.pool_ref IS DISTINCT FROM NEW.pool_ref THEN
+      before := before || jsonb_build_object('pool', OLD.pool_ref);
+      after := after || jsonb_build_object('pool', NEW.pool_ref);
+    END IF;
+    IF OLD.availability_rules IS DISTINCT FROM NEW.availability_rules THEN
+      before := before || jsonb_build_object('availability', OLD.availability_rules);
+      after := after || jsonb_build_object('availability', NEW.availability_rules);
+    END IF;
+    IF OLD.booking_rules IS DISTINCT FROM NEW.booking_rules THEN
+      before := before || jsonb_build_object('booking_rules', OLD.booking_rules);
+      after := after || jsonb_build_object('booking_rules', NEW.booking_rules);
+    END IF;
+    IF after = '{}'::jsonb THEN RETURN NULL; END IF;
+    kind := 'resource.updated';
+    details := jsonb_build_object('before', before, 'after', after);
+  END IF;
+  INSERT INTO slotlock.outbox (tenant_ref, resource_id, type, subject, data, actor)
+  VALUES (
+    changed.tenant_ref, changed.id, kind, changed.id::text,
+    jsonb_build_object('id', changed.id, 'reference', changed.external_ref) || details,
+    NULLIF(current_setting('slotlock.actor', true), '')
+  );
+  RETURN NULL;
+END
+$slotlock_outbox_resource$;
+
+-- A source first recorded, and deleted. Reading it again (a new revision) is progress, not a change
+-- of what the resource is read from, and appends nothing; neither does a resource's deletion, which
+-- takes its coverage with it and is its own change. The source is named by its digest (source_id):
+-- it can be an iCalendar URL with a token in it, or an address.
+CREATE OR REPLACE FUNCTION slotlock.outbox_coverage_change()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_outbox_coverage$
+DECLARE
+  changed slotlock.calendar_coverage%ROWTYPE;
+BEGIN
+  changed := CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  IF slotlock.outbox_erasing(changed.tenant_ref) THEN RETURN NULL; END IF;
+  IF TG_OP = 'DELETE'
+     AND NOT EXISTS (SELECT 1 FROM slotlock.resources resource WHERE resource.id = OLD.resource_id) THEN
+    RETURN NULL;
+  END IF;
+  INSERT INTO slotlock.outbox (tenant_ref, resource_id, type, subject, data, actor)
+  VALUES (
+    changed.tenant_ref, changed.resource_id,
+    CASE WHEN TG_OP = 'DELETE' THEN 'coverage.deleted' ELSE 'coverage.recorded' END,
+    ${slotlockCoverageSourceIdSql('changed.tenant_ref', 'changed.source')},
+    jsonb_strip_nulls(jsonb_build_object(
+      'resource_id', changed.resource_id,
+      'source_id', ${slotlockCoverageSourceIdSql('changed.tenant_ref', 'changed.source')},
+      'start', CASE WHEN TG_OP = 'INSERT' THEN changed.starts_at END,
+      'end', CASE WHEN TG_OP = 'INSERT' THEN changed.ends_at END,
+      'revision', CASE WHEN TG_OP = 'INSERT' THEN changed.revision END)),
+    NULLIF(current_setting('slotlock.actor', true), '')
+  );
+  RETURN NULL;
+END
+$slotlock_outbox_coverage$;
+
+-- An endpoint added, enabled again or deleted (disabling is webhook.disabled, from the delivery that
+-- gave up). Its id and the types it takes, never its URL, which can carry a token, or its secret.
+CREATE OR REPLACE FUNCTION slotlock.outbox_webhook_change()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_outbox_webhook$
+DECLARE
+  changed slotlock.webhook_endpoints%ROWTYPE;
+  kind text;
+BEGIN
+  changed := CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  IF slotlock.outbox_erasing(changed.tenant_ref) THEN RETURN NULL; END IF;
+  IF TG_OP = 'INSERT' THEN
+    kind := 'webhook.created';
+  ELSIF TG_OP = 'DELETE' THEN
+    kind := 'webhook.deleted';
+  ELSIF OLD.disabled_at IS NOT NULL AND NEW.disabled_at IS NULL THEN
+    kind := 'webhook.enabled';
+  ELSE
+    RETURN NULL;
+  END IF;
+  INSERT INTO slotlock.outbox (tenant_ref, type, subject, data, actor)
+  VALUES (
+    changed.tenant_ref, kind, changed.id::text,
+    jsonb_build_object('id', changed.id, 'event_types', to_jsonb(changed.event_types)),
+    NULLIF(current_setting('slotlock.actor', true), '')
+  );
+  RETURN NULL;
+END
+$slotlock_outbox_webhook$;
+
+CREATE OR REPLACE TRIGGER slotlock_outbox_resource_change
+  AFTER INSERT OR UPDATE OR DELETE ON slotlock.resources
+  FOR EACH ROW EXECUTE FUNCTION slotlock.outbox_resource_change();
+CREATE OR REPLACE TRIGGER slotlock_outbox_coverage_change
+  AFTER INSERT OR DELETE ON slotlock.calendar_coverage
+  FOR EACH ROW EXECUTE FUNCTION slotlock.outbox_coverage_change();
+CREATE OR REPLACE TRIGGER slotlock_outbox_webhook_change
+  AFTER INSERT OR DELETE ON slotlock.webhook_endpoints
+  FOR EACH ROW EXECUTE FUNCTION slotlock.outbox_webhook_change();
+-- Only an update that sets disabled_at: leases and deliveries, which do not, cost nothing here.
+CREATE OR REPLACE TRIGGER slotlock_outbox_webhook_enabled
+  AFTER UPDATE OF disabled_at ON slotlock.webhook_endpoints
+  FOR EACH ROW EXECUTE FUNCTION slotlock.outbox_webhook_change();
+
 DROP TRIGGER IF EXISTS slotlock_outbox_reservation_change ON slotlock.reservations;
 CREATE TRIGGER slotlock_outbox_reservation_change
   AFTER INSERT OR UPDATE OR DELETE ON slotlock.reservations
@@ -1584,6 +1863,8 @@ CREATE TABLE IF NOT EXISTS slotlock.reservations (
   ends_at timestamptz NOT NULL,
   buffer_after_ms bigint NOT NULL DEFAULT 0,
   occupied_ends_at timestamptz,
+  buffer_before_ms bigint NOT NULL DEFAULT 0,
+  occupied_starts_at timestamptz,
   revision bigint NOT NULL DEFAULT 1,
   status text NOT NULL DEFAULT 'confirmed',
   expires_at timestamptz,
@@ -1604,6 +1885,15 @@ CREATE TABLE IF NOT EXISTS slotlock.reservations (
       AND occupied_ends_at = ends_at + buffer_after_ms * interval '1 millisecond'
     )
   ),
+  CONSTRAINT slotlock_reservations_buffer_before_valid CHECK (
+    buffer_before_ms >= 0 AND buffer_before_ms <= 86400000
+  ),
+  -- NULL only without a leading buffer: a NULL occupied start reads as the start itself.
+  CONSTRAINT slotlock_reservations_occupied_start_valid CHECK (
+    (occupied_starts_at IS NULL AND buffer_before_ms = 0)
+    OR (occupied_starts_at IS NOT NULL
+        AND occupied_starts_at = starts_at - buffer_before_ms * interval '1 millisecond')
+  ),
   CONSTRAINT slotlock_reservations_status_valid CHECK (status IN ('held', 'confirmed')),
   -- A hold must carry its expiry; a confirmed reservation must not (expiry is hold-only state).
   CONSTRAINT slotlock_reservations_expiry_shape CHECK (
@@ -1612,7 +1902,7 @@ CREATE TABLE IF NOT EXISTS slotlock.reservations (
   ),
   CONSTRAINT slotlock_reservations_no_overlap EXCLUDE USING gist (
     resource_id WITH =,
-    tstzrange(starts_at, COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
+    tstzrange(COALESCE(occupied_starts_at, starts_at), COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
   )
 );
 
@@ -1644,6 +1934,11 @@ ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS tenant_ref text;
 ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS external_ref text;
 ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS buffer_after_ms bigint NOT NULL DEFAULT 0;
 ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS occupied_ends_at timestamptz;
+-- The leading buffer a booking keeps before its start (its resource's bufferBeforeMinutes when it
+-- was made), and where its occupied time starts: its start less that buffer. A row written before
+-- leading buffers has none, so its occupied time starts at its start (NULL reads as starts_at).
+ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS buffer_before_ms bigint NOT NULL DEFAULT 0;
+ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS occupied_starts_at timestamptz;
 -- A keyed hold's holder (its principal) and the group of alternatives it was taken in: an agent
 -- releases or books only its own holds, and booking one releases the rest of its group.
 ALTER TABLE slotlock.reservations ADD COLUMN IF NOT EXISTS holder_ref text;
@@ -1681,6 +1976,31 @@ BEGIN
   END IF;
 END $$;
 
+-- The occupied start, materialized for the same reason as the occupied end.
+CREATE OR REPLACE FUNCTION slotlock.set_reservation_occupied_start()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $$
+BEGIN
+  NEW.occupied_starts_at := NEW.starts_at - NEW.buffer_before_ms * interval '1 millisecond';
+  RETURN NEW;
+END $$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_trigger
+     WHERE tgname = 'slotlock_reservations_set_occupied_start'
+       AND tgrelid = 'slotlock.reservations'::regclass
+       AND NOT tgisinternal
+  ) THEN
+    CREATE TRIGGER slotlock_reservations_set_occupied_start
+    BEFORE INSERT OR UPDATE OF starts_at, buffer_before_ms ON slotlock.reservations
+    FOR EACH ROW EXECUTE FUNCTION slotlock.set_reservation_occupied_start();
+  END IF;
+END $$;
+
 -- Cancellation is an idempotency fact, not the absence of a reservation. Keeping a tombstone
 -- prevents delayed at-least-once create delivery from resurrecting a cancelled booking key.
 CREATE TABLE IF NOT EXISTS slotlock.reservation_tombstones (
@@ -1975,6 +2295,34 @@ BEGIN
         buffer_after_ms >= 0 AND buffer_after_ms <= 2592000000
       ) NOT VALID;
   END IF;
+  -- Every existing row has no leading buffer, so both hold of it; added NOT VALID (no scan under
+  -- the lock) and validated after the migration commits.
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'slotlock_reservations_buffer_before_valid'
+       AND conrelid = 'slotlock.reservations'::regclass
+  ) THEN
+    ALTER TABLE slotlock.reservations
+      ADD CONSTRAINT slotlock_reservations_buffer_before_valid CHECK (
+        buffer_before_ms >= 0 AND buffer_before_ms <= 86400000
+      ) NOT VALID;
+  END IF;
+  -- A first form of this check let a NULL occupied start through with a leading buffer (the
+  -- comparison is NULL, which a CHECK passes): replaced wherever it lacks the IS NOT NULL guard.
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'slotlock_reservations_occupied_start_valid'
+       AND conrelid = 'slotlock.reservations'::regclass
+       AND pg_catalog.pg_get_constraintdef(oid) LIKE '%occupied_starts_at IS NOT NULL%'
+  ) THEN
+    ALTER TABLE slotlock.reservations DROP CONSTRAINT IF EXISTS slotlock_reservations_occupied_start_valid;
+    ALTER TABLE slotlock.reservations
+      ADD CONSTRAINT slotlock_reservations_occupied_start_valid CHECK (
+        (occupied_starts_at IS NULL AND buffer_before_ms = 0)
+        OR (occupied_starts_at IS NOT NULL
+            AND occupied_starts_at = starts_at - buffer_before_ms * interval '1 millisecond')
+      ) NOT VALID;
+  END IF;
 END $$;
 
 -- Every row occupies from its start to its occupied end: its end plus its turnaround buffer. Up to
@@ -2025,13 +2373,35 @@ BEGIN
     ALTER TABLE slotlock.reservations
       ADD CONSTRAINT slotlock_reservations_no_overlap EXCLUDE USING gist (
         resource_id WITH =,
-        tstzrange(starts_at, COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
+        tstzrange(COALESCE(occupied_starts_at, starts_at), COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
       );
   END IF;
   ALTER TABLE slotlock.reservations DROP CONSTRAINT IF EXISTS slotlock_reservations_buffered_no_overlap;
 END
 $slotlock_occupied_overlap$;
 
+-- A row occupies from its occupied start too: its start less its leading buffer. Every row an
+-- upgrade finds was written before leading buffers and keeps none, so its range is the one the old
+-- constraint already kept apart and none can conflict: the constraint is replaced in place, its
+-- index built once under the migration's lock.
+DO $slotlock_occupied_start_overlap$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conname = 'slotlock_reservations_no_overlap'
+       AND conrelid = 'slotlock.reservations'::regclass
+       AND pg_catalog.pg_get_constraintdef(oid) LIKE '%occupied_starts_at%'
+  ) THEN
+    ALTER TABLE slotlock.reservations DROP CONSTRAINT IF EXISTS slotlock_reservations_no_overlap;
+    ALTER TABLE slotlock.reservations
+      ADD CONSTRAINT slotlock_reservations_no_overlap EXCLUDE USING gist (
+        resource_id WITH =,
+        tstzrange(COALESCE(occupied_starts_at, starts_at), COALESCE(occupied_ends_at, ends_at), '[)') WITH &&
+      );
+  END IF;
+END
+$slotlock_occupied_start_overlap$;
+
 CREATE INDEX IF NOT EXISTS slotlock_reservations_resource_time_idx
   ON slotlock.reservations (resource_id, starts_at, ends_at);
 
@@ -2231,6 +2601,10 @@ ALTER TABLE slotlock.calendar_events ADD COLUMN IF NOT EXISTS recurrence_ends_by
 ALTER TABLE slotlock.calendar_events
   ADD COLUMN IF NOT EXISTS buffer_after_ms integer NOT NULL DEFAULT 0
   CONSTRAINT slotlock_calendar_events_buffer_valid CHECK (buffer_after_ms BETWEEN 0 AND 86400000);
+-- The leading buffer a booked event keeps before each occurrence, kept for a later roll alike.
+ALTER TABLE slotlock.calendar_events
+  ADD COLUMN IF NOT EXISTS buffer_before_ms integer NOT NULL DEFAULT 0
+  CONSTRAINT slotlock_calendar_events_buffer_before_valid CHECK (buffer_before_ms BETWEEN 0 AND 86400000);
 ALTER TABLE slotlock.calendar_events
   DROP CONSTRAINT IF EXISTS slotlock_calendar_events_recurrence_cursor_bounded;
 DO $slotlock_calendar_event_recurrence_cursor$
@@ -2796,6 +3170,7 @@ export const SLOTLOCK_TENANT_TABLES = Object.freeze([
     'outbox_pruned',
     'webhook_endpoints',
     'waitlist_entries',
+    'booking_rule_defaults',
     'assistant_settings',
     'assistant_conversations',
 ]);
@@ -2867,6 +3242,8 @@ ALTER TABLE slotlock.webhook_endpoints ENABLE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.webhook_endpoints FORCE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.waitlist_entries ENABLE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.waitlist_entries FORCE ROW LEVEL SECURITY;
+ALTER TABLE slotlock.booking_rule_defaults ENABLE ROW LEVEL SECURITY;
+ALTER TABLE slotlock.booking_rule_defaults FORCE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.assistant_settings ENABLE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.assistant_settings FORCE ROW LEVEL SECURITY;
 ALTER TABLE slotlock.assistant_conversations ENABLE ROW LEVEL SECURITY;
@@ -2900,6 +3277,7 @@ BEGIN
          'outbox_pruned',
          'webhook_endpoints',
          'waitlist_entries',
+         'booking_rule_defaults',
          'assistant_settings',
          'assistant_conversations'
        )
@@ -3113,6 +3491,16 @@ BEGIN
       WITH CHECK (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''));
   END IF;
 
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_policies
+     WHERE schemaname = 'slotlock' AND tablename = 'booking_rule_defaults'
+       AND policyname = 'tenant_isolation_v1'
+  ) THEN
+    CREATE POLICY tenant_isolation_v1 ON slotlock.booking_rule_defaults
+      USING (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''))
+      WITH CHECK (tenant_ref = NULLIF(current_setting('${tenantContextSetting}', true), ''));
+  END IF;
+
   IF NOT EXISTS (
     SELECT 1 FROM pg_policies
      WHERE schemaname = 'slotlock' AND tablename = 'assistant_settings'
@@ -3169,6 +3557,8 @@ COMMENT ON POLICY tenant_isolation_v1 ON slotlock.webhook_endpoints
   IS 'slotlock:tenant-context:${tenantContextSetting}';
 COMMENT ON POLICY tenant_isolation_v1 ON slotlock.waitlist_entries
   IS 'slotlock:tenant-context:${tenantContextSetting}';
+COMMENT ON POLICY tenant_isolation_v1 ON slotlock.booking_rule_defaults
+  IS 'slotlock:tenant-context:${tenantContextSetting}';
 COMMENT ON POLICY tenant_isolation_v1 ON slotlock.assistant_settings
   IS 'slotlock:tenant-context:${tenantContextSetting}';
 COMMENT ON POLICY tenant_isolation_v1 ON slotlock.assistant_conversations
@@ -3213,6 +3603,7 @@ WHERE schemaname = 'slotlock'
     'outbox_pruned',
     'webhook_endpoints',
     'waitlist_entries',
+    'booking_rule_defaults',
     'assistant_settings',
     'assistant_conversations'
   )

package/event-feed.d.ts

@@ -1,8 +1,30 @@
 import type { Sql, TransactionSql } from 'postgres';
 type SlotlockSql = Sql | TransactionSql;
 /** What a change can be, as the feed and a webhook's `event_types` name it. */
-export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled"];
+export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
 export type SlotlockChangeType = (typeof SLOTLOCK_CHANGE_TYPES)[number];
+/**
+ * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
+ * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
+ * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
+ * store itself (`library`). Never an address or anything else about a person.
+ */
+export declare const SLOTLOCK_CHANGE_ORIGINS: readonly ["mcp", "a2a", "rest", "application", "dashboard", "dashboard-assistant", "maintenance", "library"];
+export type SlotlockChangeOrigin = (typeof SLOTLOCK_CHANGE_ORIGINS)[number];
+/** Whether `value` is one of SLOTLOCK_CHANGE_ORIGINS. */
+export declare function isSlotlockChangeOrigin(value: unknown): value is SlotlockChangeOrigin;
+/**
+ * The SQL that names a coverage source on the feed (`coverage.recorded`, `.deleted`, `.stale`): a
+ * digest of the tenant and the source, stable for both, so the source itself (an iCalendar URL with
+ * a token, an address) never reaches a webhook or the history. `tenant` and `source` are SQL
+ * expressions; slotlockCoverageSourceId works out the same value.
+ */
+export declare function slotlockCoverageSourceIdSql(tenant: string, source: string): string;
+/**
+ * How the feed names a tenant's coverage source (`subject` and `data.source_id` of `coverage.*`
+ * changes; `source_id` of slotlock_get_coverage): `src_` and 24 hex digits.
+ */
+export declare function slotlockCoverageSourceId(tenantRef: string, source: string): string;
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export declare const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
@@ -20,6 +42,10 @@ export interface SlotlockChange {
     occurredAt: Date;
     /** Who made it (withTenant's `actor`: an API key, an agent), or null when unrecorded. */
     actor: string | null;
+    /** Where it came from (withTenant's `origin`), or null when unrecorded (before 0.6, say). */
+    origin: SlotlockChangeOrigin | null;
+    /** The API key that made it (withTenant's `keyId`), or null when no key did. */
+    keyId: string | null;
     /** Pass as `after` to read what follows this change. */
     position: string;
 }
@@ -150,9 +176,10 @@ export interface SlotlockEventFeed {
         };
     }): Promise<void>;
     /**
-     * History: the changes to one resource (`resourceId`) or one record (`subject`: a booking's
-     * reference, an event's or hold's id), newest first, `limit` (1-100) at a time, each with who
-     * made it and, for a change of an existing record, what it was before. Pass the last one's
+     * History: the changes to one resource (`resourceId`: its bookings and events, and its own
+     * configuration) or one record (`subject`: a booking's reference, an event's, hold's, webhook's or
+     * API key's id), newest first, `limit` (1-100) at a time, each with who made it (`actor`, `keyId`),
+     * where from (`origin`) and, for a change of an existing record, what it was before. Pass the last one's
      * `id` as `before` for the page after. Kept as long as the feed keeps changes.
      */
     listHistory(params: {
@@ -175,4 +202,10 @@ export declare function isWebhookUrl(value: unknown): value is string;
  * `retentionDays` (default SLOTLOCK_CHANGE_RETENTION_DAYS), and a cursor reaches back as far.
  */
 export declare function slotlockEventFeedMethods(sql: SlotlockSql, retentionDays?: number): SlotlockEventFeed;
+/**
+ * A position at or before every change that has not ended yet, so a reader that starts from it and
+ * follows `next` misses none still to come (it may read again some that ended just before). Live
+ * updates start here (agent-store-backend.ts, createSlotlockStoreChangeSource).
+ */
+export declare function slotlockChangeFeedHead(sql: SlotlockSql): Promise<string>;
 export {};