slotlock 0.5.3 → 0.6.0

package/ddl.js

@@ -11,7 +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_CHANGE_ORIGINS, legacyCoverageSourceDigestSql } 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);
@@ -75,9 +75,11 @@ $slotlock_restore_forced_row_security$;
 export const SLOTLOCK_SCHEMA_CONTROL_REFUSAL = 'Slotlock will not deploy into schema slotlock';
 /**
  * The version of the schema this release creates, recorded in `slotlock.schema_version` by every
- * migration. Releases up to 0.2 recorded nothing; 0.1 was version 1 and 0.2 version 2.
+ * migration. Releases up to 0.2 recorded nothing; 0.1 was version 1 and 0.2 version 2; 0.3 to 0.5
+ * recorded 3. 0.6 is 4, so a 0.5 release refuses it before it changes anything: its DDL would put
+ * back the trigger that names a coverage source by its guessable digest.
  */
-export const SLOTLOCK_SCHEMA_VERSION = 3;
+export const SLOTLOCK_SCHEMA_VERSION = 4;
 /** The start of the message with which the deployment DDL refuses a schema a newer release migrated. */
 export const SLOTLOCK_SCHEMA_NEWER_REFUSAL = 'Slotlock will not migrate a schema a newer release migrated';
 /** The oldest PostgreSQL the DDL runs on (`server_version_num`): it uses pg_input_is_valid. */
@@ -751,6 +753,12 @@ CREATE TABLE IF NOT EXISTS slotlock.schema_version (
 );
 ALTER TABLE slotlock.schema_version ENABLE ROW LEVEL SECURITY;
 REVOKE ALL ON slotlock.schema_version FROM PUBLIC;
+-- The rename of coverage changes earlier releases wrote (0.6, slotlockCoverageChangeRenameSql): the
+-- last outbox id a pass has read (null before the first), and whether it is done. A pass after the
+-- first that finds nothing to rename marks it done, and no migration reads the outbox for it again.
+ALTER TABLE slotlock.schema_version ADD COLUMN IF NOT EXISTS coverage_changes_renamed_through bigint;
+ALTER TABLE slotlock.schema_version
+  ADD COLUMN IF NOT EXISTS coverage_changes_renamed boolean NOT NULL DEFAULT false;
 
 -- NULL when no migration has recorded a version (a schema from 0.2 or earlier).
 CREATE OR REPLACE FUNCTION slotlock.installed_schema_version()
@@ -1664,6 +1672,29 @@ UPDATE slotlock.calendar_events
 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;
+-- How the feed names a source (0.6): \`src_\` and 32 random hex digits, made when the source is first
+-- recorded for the resource and kept until it is deleted, so nobody can confirm a guessed source
+-- against it (0.5.3 named it by an unkeyed digest of the tenant and the source). Added bare, its
+-- default set apart (a volatile default on ADD COLUMN would rewrite the table under the lock), the
+-- sources already there given one each, and its CHECK NOT VALID, validated after the migration
+-- commits. Only listCoverage gives the source beside it, to the tenant.
+ALTER TABLE slotlock.calendar_coverage ADD COLUMN IF NOT EXISTS source_id text;
+ALTER TABLE slotlock.calendar_coverage
+  ALTER COLUMN source_id SET DEFAULT 'src_' || pg_catalog.replace(pg_catalog.gen_random_uuid()::text, '-', '');
+UPDATE slotlock.calendar_coverage SET source_id = DEFAULT WHERE source_id IS NULL;
+DO $slotlock_coverage_source_id$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_catalog.pg_constraint
+     WHERE conrelid = 'slotlock.calendar_coverage'::regclass
+       AND conname = 'slotlock_calendar_coverage_source_id_valid'
+  ) THEN
+    ALTER TABLE slotlock.calendar_coverage
+      ADD CONSTRAINT slotlock_calendar_coverage_source_id_valid
+      CHECK (source_id IS NOT NULL AND source_id ~ '^src_[0-9a-f]{32}$') NOT VALID;
+  END IF;
+END
+$slotlock_coverage_source_id$;
 
 -- 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,
@@ -1743,7 +1774,7 @@ $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):
+-- takes its coverage with it and is its own change. The source is named by its random 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
@@ -1763,10 +1794,10 @@ BEGIN
   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')},
+    changed.source_id,
     jsonb_strip_nulls(jsonb_build_object(
       'resource_id', changed.resource_id,
-      'source_id', ${slotlockCoverageSourceIdSql('changed.tenant_ref', 'changed.source')},
+      'source_id', changed.source_id,
       '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)),
@@ -1814,6 +1845,32 @@ CREATE OR REPLACE TRIGGER 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();
+
+-- A coverage change an earlier release's server (0.3-0.5) still running writes, as it is inserted:
+-- named by its source's source_id (src_redacted for a source it cannot find), without the source or
+-- the error read from it. 0.5.2 and earlier wrote the source itself (an iCalendar URL with a token,
+-- an address) and its last error; 0.5.3 its guessable digest. This release's own rows are in shape
+-- and pass unchanged. It runs as the inserting role, under its tenant's RLS like the insert itself.
+CREATE OR REPLACE FUNCTION slotlock.outbox_coverage_in_shape()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY INVOKER
+SET search_path = pg_catalog, slotlock, pg_temp
+AS $slotlock_outbox_coverage_in_shape$
+DECLARE
+  named text;
+BEGIN
+  IF ${coverageChangeInShapeSql('NEW')} THEN RETURN NEW; END IF;
+  named := ${coverageChangeSourceIdSql('NEW')};
+  NEW.subject := named;
+  NEW.data := (NEW.data - 'source' - 'last_error') || pg_catalog.jsonb_build_object('source_id', named);
+  RETURN NEW;
+END
+$slotlock_outbox_coverage_in_shape$;
+CREATE OR REPLACE TRIGGER slotlock_outbox_coverage_in_shape
+  BEFORE INSERT ON slotlock.outbox
+  FOR EACH ROW WHEN (NEW.type LIKE 'coverage.%')
+  EXECUTE FUNCTION slotlock.outbox_coverage_in_shape();
 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();
@@ -3139,8 +3196,108 @@ CREATE INDEX IF NOT EXISTS slotlock_calendar_event_occurrences_resource_time_idx
 CREATE INDEX IF NOT EXISTS slotlock_reservations_calendar_event_idx
   ON slotlock.reservations (calendar_event_id) WHERE calendar_event_id IS NOT NULL;
 ${SLOTLOCK_OUTBOX_DDL}${SLOTLOCK_API_KEYS_DDL}${SLOTLOCK_DASHBOARD_DDL}${SLOTLOCK_TENANT_ADMIN_DDL}${DEPLOYMENT_RECORD_VERSION}`;
+/**
+ * Whether the outbox row `row` (a coverage change) is in this release's shape: named by a source_id
+ * or src_redacted, in `subject` and `data.source_id` alike, with no `source` or `last_error`.
+ */
+function coverageChangeInShapeSql(row) {
+    return `(${row}.subject ~ '^src_([0-9a-f]{32}|redacted)$'
+         AND ${row}.data ->> 'source_id' IS NOT DISTINCT FROM ${row}.subject
+         AND NOT ${row}.data ?| ARRAY['source', 'last_error'])`;
+}
+/**
+ * The source_id an earlier release's coverage change `row` names its source by: the source with
+ * its tenant and resource whose source (0.5.2 and earlier: the subject, or `data.source`) or 0.5.3
+ * digest (the subject) it carries, else src_redacted.
+ */
+function coverageChangeSourceIdSql(row) {
+    return `COALESCE((
+           SELECT coverage.source_id FROM slotlock.calendar_coverage coverage
+            WHERE coverage.tenant_ref = ${row}.tenant_ref
+              AND coverage.resource_id = ${row}.resource_id
+              AND coverage.source_id IS NOT NULL
+              AND (coverage.source = ${row}.subject
+                   OR coverage.source = ${row}.data ->> 'source'
+                   OR ${legacyCoverageSourceDigestSql('coverage.tenant_ref', 'coverage.source')} = ${row}.subject)
+            LIMIT 1), 'src_redacted')`;
+}
+/** Outbox ids one batch of the coverage-change rename reads (by primary key) in one transaction. */
+export const SLOTLOCK_COVERAGE_CHANGE_RENAME_BATCH = 5_000;
+/**
+ * One batch of the rename of coverage changes an earlier release wrote: of the outbox rows with ids
+ * after `after` up to `head` (SQL expressions, bigint), the first `batch` by id, each `coverage.*`
+ * one not yet in this release's shape gets its source's source_id as subject and `data.source_id`,
+ * and loses `source` and `last_error`. Before 0.5.3 coverage.stale carried the source itself (an
+ * iCalendar URL with a token, an address) and the error read from it; 0.5.3 named it by an unkeyed
+ * digest anyone could confirm a guess against. A source deleted since is `src_redacted`: nothing
+ * can match it any more, and a made-up id would look like a source the tenant could find. Selects
+ * the last id read (`last`, null when there was none) and how many it renamed (`renamed`), `INTO`
+ * `into` when given (PL/pgSQL). Rows in the new shape are left alone, so a batch run again changes
+ * nothing.
+ */
+export function slotlockCoverageChangeRenameSql(after, head, batch, into = '') {
+    return `WITH scanned AS MATERIALIZED (
+  SELECT id FROM slotlock.outbox
+   WHERE id > ${after} AND id <= ${head}
+   ORDER BY id
+   LIMIT ${batch}
+), earlier AS (
+  SELECT change.id, change.tenant_ref, change.resource_id, change.subject, change.data
+    FROM slotlock.outbox change
+   WHERE change.id IN (SELECT scanned.id FROM scanned)
+     AND change.type LIKE 'coverage.%'
+     AND NOT ${coverageChangeInShapeSql('change')}
+     FOR UPDATE OF change
+), named AS (
+  SELECT earlier.id, ${coverageChangeSourceIdSql('earlier')} AS source_id
+    FROM earlier
+), renamed AS (
+  UPDATE slotlock.outbox change
+     SET subject = named.source_id,
+         data = (change.data - 'source' - 'last_error') || jsonb_build_object('source_id', named.source_id)
+    FROM named
+   WHERE change.id = named.id
+  RETURNING change.id
+)
+SELECT (SELECT max(scanned.id) FROM scanned)::text AS last,
+       (SELECT count(*) FROM renamed)::integer AS renamed${into ? `
+  INTO ${into}` : ''}`;
+}
+// The rename for SLOTLOCK_CORE_DDL, run whole in its one transaction, while FORCE is lifted (the
+// structure has the outbox under ACCESS EXCLUSIVE for the whole transaction, so no change commits
+// in between). It goes on from where the last pass stopped, and is skipped once done. applySchema
+// runs it in batches after the structure commits instead, each its own short transaction.
+const DEPLOYMENT_RENAME_COVERAGE_CHANGES = `DO $slotlock_rename_coverage_changes$
+DECLARE
+  scan_after bigint;
+  scan_head bigint;
+  scan_last text;
+  scan_renamed integer;
+  renamed_total integer := 0;
+  first_pass boolean;
+BEGIN
+  IF (SELECT coverage_changes_renamed FROM slotlock.schema_version WHERE singleton) THEN
+    RETURN;
+  END IF;
+  SELECT coverage_changes_renamed_through INTO scan_after FROM slotlock.schema_version WHERE singleton;
+  first_pass := scan_after IS NULL;
+  scan_after := COALESCE(scan_after, 0);
+  SELECT COALESCE(max(id), 0) INTO scan_head FROM slotlock.outbox;
+  LOOP
+    ${slotlockCoverageChangeRenameSql('scan_after', 'scan_head', String(SLOTLOCK_COVERAGE_CHANGE_RENAME_BATCH), 'scan_last, scan_renamed')};
+    EXIT WHEN scan_last IS NULL;
+    scan_after := scan_last::bigint;
+    renamed_total := renamed_total + scan_renamed;
+  END LOOP;
+  UPDATE slotlock.schema_version
+     SET coverage_changes_renamed_through = GREATEST(scan_after, scan_head),
+         coverage_changes_renamed = NOT first_pass AND renamed_total = 0
+   WHERE singleton;
+END
+$slotlock_rename_coverage_changes$;
+`;
 /** The whole deployment DDL, run in one transaction: the schema, then its constraints validated. */
-export const SLOTLOCK_CORE_DDL = `${CORE_DDL_BODY}${DEPLOYMENT_VALIDATE_CONSTRAINTS}${DEPLOYMENT_RESTORE_FORCED_ROW_SECURITY}${DEPLOYMENT_SEARCH_PATH_RESTORE}`;
+export const SLOTLOCK_CORE_DDL = `${CORE_DDL_BODY}${DEPLOYMENT_RENAME_COVERAGE_CHANGES}${DEPLOYMENT_VALIDATE_CONSTRAINTS}${DEPLOYMENT_RESTORE_FORCED_ROW_SECURITY}${DEPLOYMENT_SEARCH_PATH_RESTORE}`;
 /**
  * SLOTLOCK_CORE_DDL without the validation, which applySchema runs as a step of its own after this
  * commits (SLOTLOCK_VALIDATION_DDL).

package/event-feed.d.ts

@@ -14,17 +14,34 @@ 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.
+ * The digest 0.5.3 named a coverage source by on the feed: `src_` and the first 24 hex digits of
+ * sha256(tenant, newline, source). Unkeyed, so anyone who knows the tenant could confirm a guessed
+ * source against it; 0.6 names a source by a random id instead (`calendar_coverage.source_id`), and
+ * the upgrade uses this only to find the changes 0.5.3 wrote and rename them. `tenant` and `source`
+ * are SQL expressions.
  */
-export declare function slotlockCoverageSourceIdSql(tenant: string, source: string): string;
+export declare function legacyCoverageSourceDigestSql(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.
+ * 0.5.3 worked out a source's id here: an unkeyed digest of the tenant and the source, which let
+ * anyone who saw a change confirm a guessed source. Since 0.6 a source's `source_id` is random and
+ * only the database knows it, so this throws (`coverage_source_id_unavailable`) rather than give a
+ * digest nothing carries any more.
+ *
+ * @deprecated Read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`). It may
+ * be removed in 0.7.0.
  */
-export declare function slotlockCoverageSourceId(tenantRef: string, source: string): string;
+export declare function slotlockCoverageSourceId(_tenantRef: string, _source: string): never;
+/**
+ * A change's subject and data as the feed serves them. A `coverage.*` change never carries its
+ * source (`source`) or the error read from it (`last_error`, which can quote it), and is named by a
+ * `source_id` of this release or `src_redacted`: an earlier release wrote both, and the upgrade
+ * renames those rows in batches after it commits, so a row it has not reached yet, or one an
+ * earlier release's server writes during a rolling upgrade, is served redacted.
+ */
+export declare function slotlockServedChange(type: string, subject: string, data: Record<string, unknown>): {
+    subject: string;
+    data: Record<string, unknown>;
+};
 /** 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. */

package/event-feed.js

@@ -2,7 +2,7 @@
 // endpoints it is delivered to. Rows are appended by triggers in the same transaction as the change
 // (ddl.ts, SLOTLOCK_OUTBOX_DDL). These are the store's methods for reading them and for keeping each
 // endpoint's delivery state; webhooks.ts signs and sends.
-import { createHash, randomBytes } from 'node:crypto';
+import { randomBytes } from 'node:crypto';
 /** A transaction on a client, or a savepoint inside the caller's (a tenant's, say). */
 async function inTransaction(sql, callback) {
     return ('begin' in sql ? sql.begin(callback) : sql.savepoint(callback));
@@ -65,20 +65,48 @@ export function isSlotlockChangeOrigin(value) {
     return typeof value === 'string' && SLOTLOCK_CHANGE_ORIGINS.includes(value);
 }
 /**
- * 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.
+ * The digest 0.5.3 named a coverage source by on the feed: `src_` and the first 24 hex digits of
+ * sha256(tenant, newline, source). Unkeyed, so anyone who knows the tenant could confirm a guessed
+ * source against it; 0.6 names a source by a random id instead (`calendar_coverage.source_id`), and
+ * the upgrade uses this only to find the changes 0.5.3 wrote and rename them. `tenant` and `source`
+ * are SQL expressions.
  */
-export function slotlockCoverageSourceIdSql(tenant, source) {
-    return `'src_' || left(encode(sha256(convert_to(${tenant} || E'\\n' || ${source}, 'UTF8')), 'hex'), 24)`;
+export function legacyCoverageSourceDigestSql(tenant, source) {
+    return `'src_' || pg_catalog.left(pg_catalog.encode(pg_catalog.sha256(pg_catalog.convert_to(${tenant} || E'\\n' || ${source}, 'UTF8')), 'hex'), 24)`;
 }
 /**
- * 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.
+ * 0.5.3 worked out a source's id here: an unkeyed digest of the tenant and the source, which let
+ * anyone who saw a change confirm a guessed source. Since 0.6 a source's `source_id` is random and
+ * only the database knows it, so this throws (`coverage_source_id_unavailable`) rather than give a
+ * digest nothing carries any more.
+ *
+ * @deprecated Read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`). It may
+ * be removed in 0.7.0.
  */
-export function slotlockCoverageSourceId(tenantRef, source) {
-    return `src_${createHash('sha256').update(`${tenantRef}\n${source}`, 'utf8').digest('hex').slice(0, 24)}`;
+export function slotlockCoverageSourceId(_tenantRef, _source) {
+    throw Object.assign(new Error("slotlockCoverageSourceId cannot work out a source's id since 0.6: it is random. Read sourceId from listCoverage (source_id of slotlock_get_coverage)"), { code: 'coverage_source_id_unavailable' });
+}
+/** What a coverage source's `source_id` is: `src_` and 32 random hex digits. */
+const SLOTLOCK_COVERAGE_SOURCE_ID = /^src_[0-9a-f]{32}$/;
+/**
+ * The `source_id` of a `coverage.*` change whose source could not be named any more: one an
+ * earlier release recorded by the source itself (or by its 0.5.3 digest) after the source was
+ * deleted, or one not yet renamed when it is read.
+ */
+const SLOTLOCK_REDACTED_SOURCE_ID = 'src_redacted';
+/**
+ * A change's subject and data as the feed serves them. A `coverage.*` change never carries its
+ * source (`source`) or the error read from it (`last_error`, which can quote it), and is named by a
+ * `source_id` of this release or `src_redacted`: an earlier release wrote both, and the upgrade
+ * renames those rows in batches after it commits, so a row it has not reached yet, or one an
+ * earlier release's server writes during a rolling upgrade, is served redacted.
+ */
+export function slotlockServedChange(type, subject, data) {
+    if (!type.startsWith('coverage.'))
+        return { subject, data };
+    const { source: _source, last_error: _lastError, ...rest } = data;
+    const sourceId = SLOTLOCK_COVERAGE_SOURCE_ID.test(subject) ? subject : SLOTLOCK_REDACTED_SOURCE_ID;
+    return { subject: sourceId, data: { ...rest, source_id: sourceId } };
 }
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
@@ -105,8 +133,7 @@ function toChange(row) {
         id: `msg_${row.id}`,
         type: row.type,
         resourceId: row.resource_id,
-        subject: row.subject,
-        data: row.data,
+        ...slotlockServedChange(row.type, row.subject, row.data),
         occurredAt: row.occurred_at,
         actor: row.actor,
         // One a later release added, read by this one: unknown here, so unrecorded, not a failed page.
@@ -453,7 +480,11 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
           FROM slotlock.outbox
          WHERE tenant_ref = ${params.tenantRef}
            AND (${params.resourceId ?? null}::uuid IS NULL OR resource_id = ${params.resourceId ?? null}::uuid)
-           AND (${params.subject ?? null}::text IS NULL OR subject = ${params.subject ?? null})
+           AND (${params.subject ?? null}::text IS NULL OR (
+                 subject = ${params.subject ?? null}
+                 -- A coverage change matches only by the name it is served under: one not renamed
+                 -- yet may still hold its source, and a guess must not find it.
+                 AND (type NOT LIKE 'coverage.%' OR subject ~ '^src_([0-9a-f]{32}|redacted)$')))
            AND (${before}::bigint IS NULL OR id < ${before}::bigint)
          ORDER BY id DESC
          LIMIT ${limit}`;

package/index.d.ts

@@ -12,7 +12,7 @@ export type { EmitVAvailabilityOptions, JSCalendarAlert, JSCalendarEvent, JSCale
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export type { LocalDateTime, TimeZoneConverter, ZonedCalendarDate, ZonedWallTime, } from './timezone.js';
 export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
-export type { SlotlockAgentCalendarBackend, SlotlockAgentConfirmationOptions, SlotlockAgentErrorContext, SlotlockAgentInvocationContext, SlotlockAgentOperation, SlotlockAgentOperationDispatchOptions, SlotlockAgentOperationDispatchResult, SlotlockAgentPrincipal, SlotlockAgentScope, SlotlockAgentServerEvent, SlotlockAgentServerOAuthOptions, SlotlockAgentServerOptions, SlotlockAgentSubscriptionOptions, SlotlockAgentWriteOperation, SlotlockMcpToolResult, SlotlockTraceContext, } from './agent-server.js';
+export type { SlotlockAgentCalendarBackend, SlotlockAgentConfirmationOptions, SlotlockAgentErrorContext, SlotlockAgentInvocationContext, SlotlockAgentOperation, SlotlockAgentOperationDispatchOptions, SlotlockAgentOperationDispatchResult, SlotlockAgentPrincipal, SlotlockAgentScope, SlotlockAgentServerEvent, SlotlockAgentServerOAuthOptions, SlotlockAgentServerOptions, SlotlockAgentSubscriptionOptions, SlotlockAgentWriteOperation, SlotlockArgumentIssue, SlotlockMcpToolResult, SlotlockTraceContext, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
 export type { SlotlockNodeListenOptions, SlotlockNodeServer, SlotlockNodeServerAddress, SlotlockNodeServerCloseResult, SlotlockNodeServerErrorPhase, SlotlockNodeServerFetchTarget, SlotlockNodeServerOptions, } from './node-server.js';
 export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';

package/openapi.json

@@ -9701,7 +9701,7 @@
       "get": {
         "operationId": "slotlock_get_coverage",
         "summary": "A resource's coverage and its health",
-        "description": "Each external calendar (source) that records coverage of a resource: the window it covers, when it was last read, its last error, and whether it is stale (not read for a day, so the time it covers is unproven, not free). A source that goes stale is also put on the change feed once, as coverage.stale, until it is read again. The feed names a source by its source_id, never the source itself.",
+        "description": "Each external calendar (source) that records coverage of a resource: the window it covers, when it was last read, its last error, and whether it is stale (not read for a day, so the time it covers is unproven, not free). A source that goes stale is also put on the change feed once, as coverage.stale, until it is read again. The feed names a source by its source_id (random, made when the source is first recorded for the resource and kept until it is deleted), never the source itself.",
         "tags": [
           "Application"
         ],
@@ -9739,7 +9739,7 @@
                           },
                           "source_id": {
                             "type": "string",
-                            "pattern": "^src_[0-9a-f]{24}$"
+                            "pattern": "^src_[0-9a-f]{32}$"
                           },
                           "start": {
                             "type": "string",
@@ -12134,6 +12134,31 @@
             "type": "string",
             "description": "An overlap: the end it refused."
           },
+          "issues": {
+            "type": "array",
+            "description": "`invalid_arguments` from argument validation: each field it refused (at most 20), by its path in the arguments, outermost first; `[]` is the arguments as a whole.",
+            "items": {
+              "type": "object",
+              "required": [
+                "path",
+                "message"
+              ],
+              "properties": {
+                "path": {
+                  "type": "array",
+                  "items": {
+                    "type": [
+                      "string",
+                      "integer"
+                    ]
+                  }
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          },
           "error": {
             "type": "object",
             "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "type": "module",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "license": "Apache-2.0",

package/rest-api.js

@@ -404,6 +404,18 @@ export function slotlockOpenApiDocument(args) {
                         resource_id: { type: 'string', description: 'An overlap: the resource it refused.' },
                         start: { type: 'string', description: 'An overlap: the start it refused.' },
                         end: { type: 'string', description: 'An overlap: the end it refused.' },
+                        issues: {
+                            type: 'array',
+                            description: '`invalid_arguments` from argument validation: each field it refused (at most 20), by its path in the arguments, outermost first; `[]` is the arguments as a whole.',
+                            items: {
+                                type: 'object',
+                                required: ['path', 'message'],
+                                properties: {
+                                    path: { type: 'array', items: { type: ['string', 'integer'] } },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
                         error: {
                             type: 'object',
                             required: ['code'],

package/self-host.js

@@ -390,8 +390,13 @@ export async function migrateSlotlock(config, log) {
     const owner = connect(config.migrateDatabaseUrl ?? config.databaseUrl, 1);
     try {
         const store = createSlotlockStore(owner);
-        await store.applySchema();
-        await store.applyTenantRls();
+        try {
+            await store.applySchema();
+            await store.applyTenantRls();
+        }
+        catch (error) {
+            throw await migrateRefusal(owner, config, error);
+        }
         log.info('schema_applied');
         if (config.migrateDatabaseUrl === undefined)
             return;
@@ -412,6 +417,36 @@ export async function migrateSlotlock(config, log) {
         await owner.end({ timeout: 5 });
     }
 }
+/**
+ * Migrate run as the serving role, with no SLOTLOCK_MIGRATE_DATABASE_URL, is refused: as
+ * `unsafe_slotlock_schema`, with one reason per object the role does not own, when a role that is
+ * not a superuser owns the schema, and with a permission error (42501) when a superuser does. Lead
+ * with the fix, and keep the code, the reasons and the database's message after it.
+ */
+async function migrateRefusal(sql, config, error) {
+    const code = error?.code;
+    if (config.migrateDatabaseUrl !== undefined ||
+        !(error instanceof Error) ||
+        (code !== 'unsafe_slotlock_schema' && code !== '42501')) {
+        return error;
+    }
+    let found;
+    try {
+        [found] = await sql `
+      SELECT current_user AS role, pg_catalog.pg_get_userbyid(ns.nspowner) AS owner
+        FROM pg_catalog.pg_namespace ns
+       WHERE ns.nspname = 'slotlock'`;
+    }
+    catch {
+        return error;
+    }
+    if (!found || found.role === found.owner)
+        return error;
+    return Object.assign(new Error(`set SLOTLOCK_MIGRATE_DATABASE_URL to the schema owner's URL: migrate connected as ${found.role} (DATABASE_URL), but ${found.owner} owns the slotlock schema, and only its owner can migrate it. DATABASE_URL stays the serving role's.\n${error.message}`, { cause: error }), {
+        code,
+        ...('reasons' in error ? { reasons: error.reasons } : {}),
+    });
+}
 async function databaseReachable(sql) {
     let timeout;
     try {
@@ -533,6 +568,19 @@ 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' });
         }
+        // Serving as the schema owner is allowed (one role can migrate and serve), but the owner can
+        // lift forced row-level security, drop the exclusion constraints and read any table that does
+        // not force it: say so once, at startup, rather than refuse.
+        const [owning] = await sql `
+      SELECT pg_catalog.pg_has_role(current_user, ns.nspowner, 'MEMBER') AS owns
+        FROM pg_catalog.pg_namespace ns
+       WHERE ns.nspname = 'slotlock'`;
+        if (owning?.owns) {
+            log.warn('serving_as_schema_owner', {
+                role: serving?.role,
+                message: "DATABASE_URL connects as the role that owns the slotlock schema. Row-level security does not confine its owner on tables that do not force it, and the owner can lift it: serve as a role that owns nothing (CREATE ROLE slotlock_app LOGIN PASSWORD '…' NOSUPERUSER NOBYPASSRLS) and set SLOTLOCK_MIGRATE_DATABASE_URL to the schema owner's URL so migrate grants it what it needs",
+            });
+        }
         // Migrated by another release: an older schema needs this release's migrate first, and a newer
         // one has tables and rules this release's code does not know.
         await assertSlotlockSchemaCurrent(sql);

package/slotlock.manifest.json

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

package/store.d.ts

@@ -897,7 +897,10 @@ export type CheckInReservationResult = {
 /** One source's coverage of a resource, with its health (listCoverage). */
 export interface SlotlockCoverageHealth {
     source: string;
-    /** How the change feed names the source (slotlockCoverageSourceId), never the source itself. */
+    /**
+     * How the change feed names the source, never the source itself: `src_` and 32 random hex
+     * digits, made when the source is first recorded for the resource and kept until it is deleted.
+     */
     sourceId: string;
     start: Date;
     end: Date;