slotlock 0.2.0 → 0.3.0

package/types.d.ts

@@ -21,14 +21,28 @@ export interface SlotlockResource {
      * uses the default (`SLOTLOCK_AVAILABILITY`, or the backend's `availabilityRules`).
      */
     availabilityRules?: WeeklyAvailabilityRule[];
+    /**
+     * `shared` resources are listed to agents and booked through them; `private` ones are invisible
+     * to agents and reached only by the tenant's own code. Fixed when the resource is created. The
+     * store always says which; a resource built elsewhere without it is shared.
+     */
+    visibility?: 'shared' | 'private';
+    /** When the tenant archived it: no longer listed or booked, its history kept. Absent in use. */
+    archivedAt?: Date;
 }
 /** A confirmed occupation of a resource. The DB EXCLUDE constraint is the overlap arbiter. */
 export interface SlotlockReservation {
     id: string;
     resourceId: string;
-    /** Null only for legacy, hold, and parity-shadow rows. */
+    /**
+     * Null only for live holds, rows on a resource that has no tenant (legacy), and parity-shadow rows.
+     * A booking made by confirming a hold, or by createReservation, on a tenant's resource has one.
+     */
     tenantRef: string | null;
-    /** Stable booking identity inside tenantRef; null for legacy, hold, and shadow rows. */
+    /**
+     * Stable booking identity inside tenantRef; null exactly when tenantRef is. A confirmed hold, and
+     * a createReservation booking, use their own id.
+     */
     externalRef: string | null;
     start: Date;
     end: Date;
@@ -82,6 +96,25 @@ export type ExternalReservationResult = {
 } | {
     ok: false;
     code: 'idempotency_conflict';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The tenant's bookings and retired references are at its `reservations` limit. */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
 } | {
     ok: false;
     code: 'overlap';
@@ -106,6 +139,15 @@ export type CancelExternalReservationResult = {
 } | {
     ok: false;
     code: 'revision_conflict';
+}
+/**
+ * Retiring a reference no booking holds would add a row past the tenant's `reservations` limit
+ * (cancelling a booking it has never does).
+ */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
 };
 /**
  * VAVAILABILITY-style bookable window (RFC 7953 semantics, weekly subset): a weekly-cadence RRULE
@@ -127,6 +169,30 @@ export type CreateReservationResult = {
 } | {
     ok: false;
     code: 'invalid_window';
+}
+/** No resource with that id, or (under tenant RLS or with `tenantRef`) not one of the tenant's. */
+ | {
+    ok: false;
+    code: 'resource_not_found';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The booking's tenant is at its `reservations` limit. */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
 } | {
     ok: false;
     code: 'overlap';
@@ -138,18 +204,60 @@ export interface SlotlockHold {
     resourceId: string;
     start: Date;
     end: Date;
+    /** Turnaround kept busy after `end`; the booking the hold is confirmed into keeps it. */
+    bufferAfterMs: number;
     expiresAt: Date;
     source: string | null;
 }
-export type AcquireHoldResult = {
+export type AcquireHoldResult = 
+/** `idempotent`: a retry of a keyed hold, answered with the hold the first request made. */
+{
     ok: true;
     hold: SlotlockHold;
+    idempotent: boolean;
 } | {
     ok: false;
     code: 'invalid_window';
 } | {
     ok: false;
     code: 'invalid_ttl';
+} | {
+    ok: false;
+    code: 'invalid_buffer';
+}
+/** A tenant, principal or idempotency key that is malformed, or a key without both of the others. */
+ | {
+    ok: false;
+    code: 'invalid_identity';
+}
+/** No resource with that id, or (under tenant RLS or with `tenantRef`) not one of the tenant's. */
+ | {
+    ok: false;
+    code: 'resource_not_found';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/** The idempotency key already made a hold with another resource, window, ttl, buffer or source. */
+ | {
+    ok: false;
+    code: 'idempotency_conflict';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The resource's tenant has as many holds as its `holds` limit, expired ones deleted. */
+ | {
+    ok: false;
+    code: 'hold_limit_reached';
+    limit: number;
 } | {
     ok: false;
     code: 'overlap';
@@ -164,6 +272,27 @@ export type ConfirmHoldResult = {
 } | {
     ok: false;
     code: 'hold_expired';
+}
+/** A cancellation of the hold's reference (its id) arrived first and retired it. */
+ | {
+    ok: false;
+    code: 'reservation_cancelled';
+}
+/** Another booking of the tenant already uses the hold's id as its reference. */
+ | {
+    ok: false;
+    code: 'idempotency_conflict';
+}
+/** The hold's resource was archived since: it takes no new booking. */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/** The tenant is at its `reservations` limit: the hold stays a hold. */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
 };
 export type ReleaseHoldResult = {
     ok: true;
@@ -241,6 +370,11 @@ export interface SlotlockCalendarEvent extends CalendarEventContent {
     updatedAt: Date;
 }
 export interface PutCalendarEventCommand extends CalendarEventContent {
+    /**
+     * The resource the writer read the event on: a revision is refused (`resource_tenant_mismatch`)
+     * when the stored event is on another, checked under the event's lock.
+     */
+    expectedResourceId?: string;
     tenantRef: string;
     /** Defaults to the trusted `internal` namespace. Agent callers must supply their owner digest. */
     ownerRef?: string;
@@ -281,9 +415,20 @@ export type PutCalendarEventResult = {
     ok: false;
     code: 'owner_command_quota_exceeded';
     limit: number;
+}
+/** A new event would pass the tenant's `events` limit (revising one it has never does). */
+ | {
+    ok: false;
+    code: 'event_limit_reached';
+    limit: number;
 } | {
     ok: false;
     code: 'resource_tenant_mismatch';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
 } | {
     ok: false;
     code: 'event_cancelled';
@@ -292,11 +437,30 @@ export type PutCalendarEventResult = {
     ok: false;
     code: 'revision_conflict';
     currentRevision: number;
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
 } | {
     ok: false;
     code: 'overlap';
     conflictingReservationId: string | null;
 };
+export type DeleteResourceResult = 
+/** `deleted`: false when the tenant has no resource with that id (deleted already, say). */
+{
+    ok: true;
+    deleted: boolean;
+}
+/** A future booking, a live hold, or a calendar event is still on it. */
+ | {
+    ok: false;
+    code: 'resource_in_use';
+};
 export type CancelCalendarEventResult = {
     ok: true;
     eventId: string;
@@ -324,8 +488,16 @@ export type CancelCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 };
-/** A place in the roll's order of due masters: the last one a batch examined. */
+/**
+ * A place in the roll's order of due masters: the last one a batch examined. The roll takes the
+ * masters it has never put back first, then those it has, longest waiting first.
+ */
 export interface CalendarHorizonRollCursor {
+    /**
+     * When the master was due to be examined again, if the roll had put it back; null (or, from a
+     * cursor of an earlier release, missing) when it had not.
+     */
+    rollRetryAt?: Date | null;
     materializedEndsAt: Date;
     eventId: string;
 }
@@ -338,11 +510,18 @@ export interface CalendarHorizonRollResult {
      * stored end and the window's: a roll never moves a series' end back.
      */
     extended: number;
-    /** Masters whose new occurrence collided; their previous coverage remains intact. */
+    /**
+     * Masters whose new occurrence collided; their previous coverage remains intact, and they wait an
+     * hour before a roll examines them again, behind every master it has not put back.
+     */
     conflicts: number;
+    /** The ids of those masters: what blocks each is a booking or hold on its new occurrences. */
+    conflictEventIds: string[];
     /**
      * Masters whose rule takes more than the expansion budget to reach the window (one that never
-     * occurs again, or almost never); their previous coverage remains intact.
+     * occurs again, or almost never), or whose roll failed for any other reason; their previous
+     * coverage remains intact, and they wait an hour
+     * before a roll examines them again, behind every master it has not put back.
      */
     refused: number;
     /** The ids of those masters, to find and fix them. */
@@ -350,9 +529,8 @@ export interface CalendarHorizonRollResult {
     /** True when more due masters remain beyond this bounded batch. */
     hasMore: boolean;
     /**
-     * Pass as `after` for the next batch of this pass, so the masters this batch left behind (in
-     * conflict or refused, which keep their place at the front of the order) are not examined again
-     * by every later batch. `null` when none remain.
+     * Pass as `after` for the next batch of this pass, so the masters this batch examined are not
+     * examined again by every later batch. `null` when none remain.
      */
     next: CalendarHorizonRollCursor | null;
 }
@@ -364,6 +542,26 @@ export interface CalendarEventRetentionResult {
     /** True when either class filled its batch, so more rows may already be eligible. */
     hasMore: boolean;
 }
+/** What erasing a tenant deleted. */
+export interface SlotlockTenantErasure {
+    /** Rows deleted, by table (every table the tenant owns rows in is named, with 0 for none). */
+    rows: Record<string, number>;
+    /** Rows deleted in all; 0 when the tenant had already been erased. */
+    total: number;
+}
+export interface BookingRetentionResult {
+    /** Holds past their expiry: they occupy nothing, and only a rival's write would reap them. */
+    expiredHoldsDeleted: number;
+    /** Keyed hold answers whose hold has expired: a retry with that key makes a new hold. */
+    holdCommandsDeleted: number;
+    /**
+     * References a cancel retired with no booking, older than the window: a create with one makes a
+     * new booking. A cancelled booking's reference stays retired.
+     */
+    tombstonesDeleted: number;
+    /** True when any class filled its batch, so more rows may already be eligible. */
+    hasMore: boolean;
+}
 export interface CalendarCoverageCommand {
     tenantRef: string;
     resourceId: string;
@@ -385,6 +583,12 @@ export type CalendarCoverageResult = {
 } | {
     ok: false;
     code: 'stale_revision' | 'revision_conflict' | 'idempotency_conflict';
+}
+/** A new source would pass the tenant's `coverage` limit (advancing one it has never does). */
+ | {
+    ok: false;
+    code: 'coverage_limit_reached';
+    limit: number;
 };
 export interface CalendarCoverageAssessment {
     state: 'complete' | 'partial' | 'unknown';