@sixb/pg 0.1.6 → 0.1.8

package/src/auth-storage/rows.ts

@@ -1,6 +1,7 @@
 import type { Principal } from "@sixb/core"
 import type {
   AccessTokenRecord,
+  DeviceAuthorizationRecord,
   GroupMembershipRecord,
   GroupMembershipSource,
   InvitationRecord,
@@ -150,6 +151,24 @@ export interface PgAuthOidcAttemptRow {
   readonly consumed_at: PgDate | null
 }
 
+export interface PgAuthDeviceAuthorizationRow {
+  readonly project_id: string
+  readonly id: string
+  readonly device_code_hash: string
+  readonly user_code: string
+  readonly client_name: string
+  readonly token_name: string
+  readonly token_expires_at: PgDate
+  readonly status: DeviceAuthorizationRecord["status"]
+  readonly approved_user_id: string | null
+  readonly approved_session_id: string | null
+  readonly created_at: PgDate
+  readonly expires_at: PgDate
+  readonly approved_at: PgDate | null
+  readonly denied_at: PgDate | null
+  readonly consumed_at: PgDate | null
+}
+
 export function rowToUserRecord(row: PgAuthUserRow): UserRecord {
   return {
     id: row.id,
@@ -304,6 +323,28 @@ export function rowToOidcAuthorizationAttemptRecord(
   }
 }
 
+export function rowToDeviceAuthorizationRecord(
+  row: PgAuthDeviceAuthorizationRow
+): DeviceAuthorizationRecord {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    deviceCodeHash: row.device_code_hash,
+    userCode: row.user_code,
+    clientName: row.client_name,
+    tokenName: row.token_name,
+    tokenExpiresAt: toDate(row.token_expires_at),
+    status: row.status,
+    approvedUserId: row.approved_user_id ?? undefined,
+    approvedSessionId: row.approved_session_id ?? undefined,
+    createdAt: toDate(row.created_at),
+    expiresAt: toDate(row.expires_at),
+    approvedAt: row.approved_at ? toDate(row.approved_at) : undefined,
+    deniedAt: row.denied_at ? toDate(row.denied_at) : undefined,
+    consumedAt: row.consumed_at ? toDate(row.consumed_at) : undefined,
+  }
+}
+
 export function serializeOptionalRecord(
   value: Readonly<Record<string, unknown>> | undefined
 ): string | null {

package/src/auth-storage/shared.ts

@@ -761,6 +761,7 @@ export function mapUniqueConstraintError(
   error: unknown,
   code:
     | "duplicate_access_token"
+    | "duplicate_device_authorization"
     | "duplicate_identity"
     | "duplicate_invitation"
     | "duplicate_magic_link"

package/src/index.ts

@@ -13,6 +13,7 @@ import { ProviderMaterializationTransactionLifecycle } from "@sixb/core/internal
 import {
   createAgentOperationScope,
   createAuthOperationScope,
+  createObjectOperationScope,
   createOntologyOperationScope,
   createOperationScopedFacade,
   createStorageOperationScope,
@@ -20,6 +21,7 @@ import {
 } from "@sixb/core/internal/storage-operation-scope"
 import {
   type AiCostStorage,
+  type AiLimitStorage,
   type AiUsageStorage,
   createTransactionStorageProxy,
   type ObjectStorage,
@@ -30,13 +32,14 @@ import { PgAgentStorage } from "./agents"
 import { PgAuthStorage } from "./auth-storage"
 import { PgConnectorConnectionStorage } from "./connector-connection-storage"
 import { createPostgresStorageMigrators, dropSchema } from "./migrations"
+import { PgObjectStorage } from "./objects"
 import { PgOntologyStorage, type PgOntologyTransactionContext } from "./ontology-storage"
 import { PgActionRunStorage } from "./pg-action-run-storage"
 import { PgAiCostStorage } from "./pg-ai-cost-storage"
+import { PgAiLimitStorage } from "./pg-ai-limit-storage"
 import { PgAiUsageStorage } from "./pg-ai-usage-storage"
 import { createPgClient, type SQL, type SQLClient } from "./pg-client"
 import { PgExecutionStorage } from "./pg-execution-storage"
-import { PgObjectStorage } from "./pg-object-storage"
 import { PgPipelineRunStorage } from "./pg-pipeline-run-storage"
 import { PgProjectionRunStorage } from "./pg-projection-run-storage"
 import { PgRulesStorage } from "./pg-rules-storage"
@@ -45,6 +48,8 @@ import { PgTimeseriesStorage } from "./pg-timeseries-storage"
 import { PgWebhookRunStorage } from "./pg-webhook-run-storage"
 import { PgWorkflowInterventionStorage } from "./pg-workflow-intervention-storage"
 import { PgWorkflowRunStorage } from "./pg-workflow-run-storage"
+import { PgShareGrantStorage } from "./share-grant-storage"
+import { PgShareSessionStorage } from "./share-session-storage"
 import { isRetryableTransactionConflict } from "./storage-errors"
 import { registerPostgresStorageTestingAdapter } from "./testing"
 import { type PgStoreClient, runPgTransaction } from "./transactions"
@@ -138,6 +143,7 @@ export class PostgresStorage implements MigrationCapableStorage {
   readonly agents: PgAgentStorage
   readonly aiUsage: AiUsageStorage
   readonly aiCosts: AiCostStorage
+  readonly aiLimits: AiLimitStorage
   readonly actionRuns: PgActionRunStorage
   readonly pipelineRuns: PgPipelineRunStorage
   readonly workflowRuns: PgWorkflowRunStorage
@@ -148,6 +154,8 @@ export class PostgresStorage implements MigrationCapableStorage {
   readonly webhookRuns: PgWebhookRunStorage
   readonly rules: PgRulesStorage
   readonly connectorConnections: PgConnectorConnectionStorage
+  readonly shareGrants: PgShareGrantStorage
+  readonly shareSessions: PgShareSessionStorage
   readonly migrators: readonly StorageMigrator[]
 
   private readonly sql: SQL
@@ -205,13 +213,14 @@ export class PostgresStorage implements MigrationCapableStorage {
       },
       () => this.assertRootOperationAvailable()
     )
-    this.objects = createOperationScopedFacade(stores.objects, scope)
+    this.objects = createObjectOperationScope(stores.objects, scope)
     this.ontology = createOntologyOperationScope(stores.ontology, scope)
     this.auth = createAuthOperationScope(stores.auth, scope)
     this.executions = createOperationScopedFacade(stores.executions, scope)
     this.agents = createAgentOperationScope(stores.agents, scope)
     this.aiUsage = createOperationScopedFacade(stores.aiUsage, scope)
     this.aiCosts = createOperationScopedFacade(stores.aiCosts, scope)
+    this.aiLimits = createOperationScopedFacade(stores.aiLimits, scope)
     this.actionRuns = createOperationScopedFacade(stores.actionRuns, scope)
     this.pipelineRuns = createOperationScopedFacade(stores.pipelineRuns, scope)
     this.workflowRuns = createWorkflowRunOperationScope(stores.workflowRuns, scope)
@@ -222,6 +231,8 @@ export class PostgresStorage implements MigrationCapableStorage {
     this.webhookRuns = createOperationScopedFacade(stores.webhookRuns, scope)
     this.rules = createOperationScopedFacade(stores.rules, scope)
     this.connectorConnections = createOperationScopedFacade(stores.connectorConnections, scope)
+    this.shareGrants = createOperationScopedFacade(stores.shareGrants, scope)
+    this.shareSessions = createOperationScopedFacade(stores.shareSessions, scope)
     registerPostgresStorageTestingAdapter(this, (durationMs) =>
       stores.connectorConnections.advanceTimeForTesting(durationMs)
     )
@@ -258,6 +269,7 @@ export class PostgresStorage implements MigrationCapableStorage {
             transactionContext.materializations.assertCommittable()
             return result
           } finally {
+            await txStorage.aiLimits.settleOperations()
             transactionContext.active = false
             txStorage.ontology.deactivateSessions()
             transactionContext.materializations.deactivate()
@@ -305,7 +317,7 @@ export class PostgresStorage implements MigrationCapableStorage {
   private createTransactionStorage(
     client: PgStoreClient,
     transactionContext: PgOntologyTransactionContext
-  ): Storage & { readonly ontology: PgOntologyStorage } {
+  ): Storage & { readonly ontology: PgOntologyStorage; readonly aiLimits: PgAiLimitStorage } {
     return {
       ...createPostgresStores(client, {
         runOntologyOperation: async (run) => run(client),
@@ -329,7 +341,9 @@ function createPostgresStores(
   }
 ): PostgresStoreSet {
   const auth = new PgAuthStorage({ sql })
-  const executions = new PgExecutionStorage(sql, auth)
+  const shareGrants = new PgShareGrantStorage(sql)
+  const shareSessions = new PgShareSessionStorage(sql)
+  const executions = new PgExecutionStorage(sql, auth, shareSessions)
   return {
     objects: new PgObjectStorage(sql),
     ontology: new PgOntologyStorage({
@@ -342,6 +356,7 @@ function createPostgresStores(
     agents: new PgAgentStorage({ sql, executions }),
     aiUsage: new PgAiUsageStorage(sql),
     aiCosts: new PgAiCostStorage(sql),
+    aiLimits: new PgAiLimitStorage(sql),
     actionRuns: new PgActionRunStorage(sql, executions),
     pipelineRuns: new PgPipelineRunStorage(sql, executions),
     workflowRuns: new PgWorkflowRunStorage(sql, executions),
@@ -352,6 +367,8 @@ function createPostgresStores(
     webhookRuns: new PgWebhookRunStorage(sql, executions),
     rules: new PgRulesStorage(sql),
     connectorConnections: new PgConnectorConnectionStorage(sql),
+    shareGrants,
+    shareSessions,
   }
 }
 
@@ -363,6 +380,7 @@ interface PostgresStoreSet {
   readonly agents: PgAgentStorage
   readonly aiUsage: PgAiUsageStorage
   readonly aiCosts: PgAiCostStorage
+  readonly aiLimits: PgAiLimitStorage
   readonly actionRuns: PgActionRunStorage
   readonly pipelineRuns: PgPipelineRunStorage
   readonly workflowRuns: PgWorkflowRunStorage
@@ -373,6 +391,8 @@ interface PostgresStoreSet {
   readonly webhookRuns: PgWebhookRunStorage
   readonly rules: PgRulesStorage
   readonly connectorConnections: PgConnectorConnectionStorage
+  readonly shareGrants: PgShareGrantStorage
+  readonly shareSessions: PgShareSessionStorage
 }
 
 function resolveTimeoutMillis(value: number | undefined, label: string): number | undefined {

package/src/migrations/029-model-accounting.sql

@@ -0,0 +1,24 @@
+-- Call-time model configuration and provider identity. Historical identity remains unknown.
+ALTER TABLE ai_model_call_usage
+  ADD COLUMN requested_reasoning JSONB
+  CHECK (
+    requested_reasoning IS NULL OR
+    jsonb_typeof(requested_reasoning) IN ('string', 'object')
+  );
+ALTER TABLE ai_model_call_usage ADD COLUMN provider_ids JSONB;
+
+-- Upgrade the shipped valuation reason while retaining the selected-cost projection.
+ALTER TABLE ai_model_call_valuations
+  DROP CONSTRAINT ai_model_call_valuations_reason_check;
+
+UPDATE ai_model_call_valuations SET reason = 'missingRateCard'
+  WHERE reason = 'missingCatalogEntry';
+
+ALTER TABLE ai_model_call_valuations ADD CONSTRAINT ai_model_call_valuations_reason_check
+  CHECK (reason IS NULL OR reason IN (
+    'missingBillingIdentity',
+    'missingRateCard',
+    'missingUsageMeter',
+    'unsupportedPricingDimension',
+    'invalidUsageForFormula'
+  ));

package/src/migrations/030-ai-usage-limits.sql

@@ -0,0 +1,94 @@
+CREATE TABLE ai_usage_limits (
+  project_id TEXT NOT NULL CHECK (length(btrim(project_id)) > 0),
+  id TEXT NOT NULL CHECK (length(btrim(id)) > 0),
+  subject_type TEXT NOT NULL CHECK (
+    subject_type IN ('project', 'group', 'user', 'serviceAccount')
+  ),
+  subject_id TEXT NOT NULL CHECK (
+    (subject_type = 'project' AND subject_id = '')
+    OR (subject_type <> 'project' AND length(btrim(subject_id)) > 0)
+  ),
+  meter TEXT NOT NULL CHECK (meter IN ('tokens.total', 'cost.catalogEstimated')),
+  currency TEXT NOT NULL CHECK (
+    (meter = 'tokens.total' AND currency = '')
+    OR (meter = 'cost.catalogEstimated' AND currency = 'USD')
+  ),
+  limit_amount NUMERIC(78, 0) NOT NULL CHECK (limit_amount >= 0),
+  period_kind TEXT NOT NULL CHECK (period_kind = 'calendarMonth'),
+  enabled BOOLEAN NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, id),
+  UNIQUE (project_id, subject_type, subject_id, meter, currency)
+);
+
+CREATE INDEX idx_ai_usage_limits_project_enabled
+  ON ai_usage_limits (project_id, enabled, subject_type, subject_id, meter, currency);
+
+CREATE TABLE ai_usage_limit_periods (
+  project_id TEXT NOT NULL CHECK (length(btrim(project_id)) > 0),
+  subject_type TEXT NOT NULL CHECK (
+    subject_type IN ('project', 'group', 'user', 'serviceAccount')
+  ),
+  subject_id TEXT NOT NULL CHECK (
+    (subject_type = 'project' AND subject_id = '')
+    OR (subject_type <> 'project' AND length(btrim(subject_id)) > 0)
+  ),
+  meter TEXT NOT NULL CHECK (meter IN ('tokens.total', 'cost.catalogEstimated')),
+  currency TEXT NOT NULL CHECK (
+    (meter = 'tokens.total' AND currency = '')
+    OR (meter = 'cost.catalogEstimated' AND currency = 'USD')
+  ),
+  period_start TIMESTAMPTZ NOT NULL,
+  period_end TIMESTAMPTZ NOT NULL,
+  actual_amount NUMERIC(78, 0) NOT NULL DEFAULT 0 CHECK (actual_amount >= 0),
+  reserved_amount NUMERIC(78, 0) NOT NULL DEFAULT 0 CHECK (reserved_amount >= 0),
+  unknown_amount NUMERIC(78, 0) NOT NULL DEFAULT 0 CHECK (unknown_amount >= 0),
+  accounting_status TEXT NOT NULL DEFAULT 'complete' CHECK (
+    accounting_status IN ('complete', 'unavailable')
+  ),
+  updated_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (
+    project_id, subject_type, subject_id, meter, currency, period_start
+  )
+);
+
+CREATE INDEX idx_ai_usage_limit_periods_subject_period
+  ON ai_usage_limit_periods (
+    project_id, subject_type, subject_id, period_start, period_end, meter, currency
+  );
+
+CREATE TABLE ai_model_call_reservations (
+  project_id TEXT NOT NULL CHECK (length(btrim(project_id)) > 0),
+  execution_id TEXT NOT NULL CHECK (length(btrim(execution_id)) > 0),
+  attempt BIGINT NOT NULL CHECK (attempt >= 1),
+  call_id TEXT NOT NULL CHECK (length(btrim(call_id)) > 0),
+  buckets JSONB NOT NULL CHECK (jsonb_typeof(buckets) = 'array'),
+  request_key TEXT NOT NULL,
+  period_start TIMESTAMPTZ NOT NULL,
+  period_end TIMESTAMPTZ NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('active', 'reconciled', 'unknown')),
+  usage_record_id TEXT,
+  reserved_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (project_id, execution_id, attempt, call_id),
+  FOREIGN KEY (project_id, execution_id)
+    REFERENCES executions(project_id, id)
+    ON DELETE RESTRICT,
+  FOREIGN KEY (project_id, usage_record_id)
+    REFERENCES ai_model_call_usage(project_id, id)
+    ON DELETE RESTRICT,
+  CHECK (
+    (
+      state = 'reconciled'
+      AND usage_record_id IS NOT NULL
+    )
+    OR (
+      state <> 'reconciled'
+      AND usage_record_id IS NULL
+    )
+  )
+);
+
+CREATE INDEX idx_ai_model_call_reservations_active
+  ON ai_model_call_reservations (project_id, state, period_end, execution_id, attempt, call_id);

package/src/migrations/031-subagent-runs.sql

@@ -0,0 +1,97 @@
+-- Agent executions may either use a managed service account or inherit their parent's exact
+-- credentialed-user / auth-disabled authority.
+ALTER TABLE executions
+  DROP CONSTRAINT executions_check3,
+  ADD CONSTRAINT executions_agent_authority_check CHECK (
+    (
+      executor_kind = 'request'
+      AND source_kind = 'http'
+      AND executor_id = source_id
+      AND (
+        (
+          authority_kind = 'principal'
+          AND requested_by_user_id IS NOT DISTINCT FROM authority_user_id
+          AND requested_by_service_account_id IS NOT DISTINCT FROM authority_service_account_id
+        )
+        OR (
+          authority_kind = 'disabled'
+          AND requested_by_user_id IS NULL
+          AND requested_by_service_account_id IS NULL
+        )
+      )
+    )
+    OR (
+      executor_kind IN ('action', 'pipeline', 'projection', 'rule', 'sync', 'webhook', 'workflow')
+      AND authority_kind = 'trustedPrimitive'
+      AND executor_kind = authority_primitive_kind
+    )
+    OR (
+      executor_kind = 'agent'
+      AND source_kind = 'execution'
+      AND (
+        (
+          authority_kind = 'principal'
+          AND authority_service_account_id IS NOT NULL
+          AND authority_session_id IS NULL
+          AND authority_access_token_id IS NULL
+        )
+        OR (
+          authority_kind = 'principal'
+          AND authority_user_id IS NOT NULL
+          AND num_nonnulls(authority_session_id, authority_access_token_id) = 1
+        )
+        OR authority_kind = 'disabled'
+      )
+    )
+    OR (executor_kind = 'kernel' AND authority_kind = 'kernel')
+  );
+
+ALTER TABLE agent_runs
+  ADD COLUMN kind TEXT NOT NULL DEFAULT 'conversation'
+    CHECK (kind IN ('conversation', 'subagent')),
+  ADD COLUMN parent_run_id TEXT,
+  ADD COLUMN spawn_key TEXT,
+  ADD COLUMN spec JSONB,
+  ADD COLUMN result JSONB,
+  ALTER COLUMN thread_id DROP NOT NULL,
+  ALTER COLUMN agent_id DROP NOT NULL,
+  ALTER COLUMN trigger_message_id DROP NOT NULL,
+  ADD CONSTRAINT fk_agent_runs_parent
+    FOREIGN KEY (project_id, parent_run_id)
+    REFERENCES agent_runs (project_id, id)
+    ON DELETE RESTRICT,
+  ADD CONSTRAINT agent_runs_kind_fields CHECK (
+    (
+      kind = 'conversation'
+      AND thread_id IS NOT NULL
+      AND agent_id IS NOT NULL
+      AND trigger_message_id IS NOT NULL
+      AND parent_run_id IS NULL
+      AND spawn_key IS NULL
+      AND spec IS NULL
+      AND result IS NULL
+    )
+    OR
+    (
+      kind = 'subagent'
+      AND thread_id IS NULL
+      AND agent_id IS NULL
+      AND trigger_message_id IS NULL
+      AND parent_run_id IS NOT NULL
+      AND spawn_key IS NOT NULL
+      AND spec IS NOT NULL
+    )
+  ),
+  ADD CONSTRAINT agent_runs_subagent_result CHECK (
+    kind <> 'subagent' OR status <> 'succeeded' OR result IS NOT NULL
+  ),
+  ADD CONSTRAINT uq_agent_runs_parent_spawn_key UNIQUE (project_id, parent_run_id, spawn_key);
+
+CREATE INDEX idx_agent_runs_project_parent_started
+  ON agent_runs (
+    project_id,
+    parent_run_id,
+    status,
+    COALESCE(started_at, created_at) DESC,
+    id DESC
+  );

package/src/migrations/032-conversation-run-spec.sql

@@ -0,0 +1,23 @@
+ALTER TABLE agent_runs
+  DROP CONSTRAINT agent_runs_kind_fields,
+  ADD CONSTRAINT agent_runs_kind_fields CHECK (
+    (
+      kind = 'conversation'
+      AND thread_id IS NOT NULL
+      AND agent_id IS NOT NULL
+      AND trigger_message_id IS NOT NULL
+      AND parent_run_id IS NULL
+      AND spawn_key IS NULL
+      AND result IS NULL
+    )
+    OR
+    (
+      kind = 'subagent'
+      AND thread_id IS NULL
+      AND agent_id IS NULL
+      AND trigger_message_id IS NULL
+      AND parent_run_id IS NOT NULL
+      AND spawn_key IS NOT NULL
+      AND spec IS NOT NULL
+    )
+  );

package/src/migrations/033-retire-agent-definitions.sql

@@ -0,0 +1,28 @@
+DROP INDEX IF EXISTS idx_agent_threads_project_agent_activity;
+ALTER TABLE workflow_agent_node_runs RENAME COLUMN agent_id TO actor_id;
+DROP INDEX IF EXISTS idx_agent_runs_project_agent_started;
+
+ALTER TABLE agent_threads DROP COLUMN agent_id;
+
+ALTER TABLE agent_runs
+  DROP CONSTRAINT agent_runs_kind_fields,
+  DROP COLUMN agent_id,
+  ADD CONSTRAINT agent_runs_kind_fields CHECK (
+    (
+      kind = 'conversation'
+      AND thread_id IS NOT NULL
+      AND trigger_message_id IS NOT NULL
+      AND parent_run_id IS NULL
+      AND spawn_key IS NULL
+      AND result IS NULL
+    )
+    OR
+    (
+      kind = 'subagent'
+      AND thread_id IS NULL
+      AND trigger_message_id IS NULL
+      AND parent_run_id IS NOT NULL
+      AND spawn_key IS NOT NULL
+      AND spec IS NOT NULL
+    )
+  );

package/src/migrations/034-device-authorizations.sql

@@ -0,0 +1,24 @@
+CREATE TABLE auth_device_authorizations (
+  project_id TEXT NOT NULL,
+  id TEXT NOT NULL,
+  device_code_hash TEXT NOT NULL,
+  user_code TEXT NOT NULL,
+  client_name TEXT NOT NULL,
+  token_name TEXT NOT NULL,
+  token_expires_at TIMESTAMPTZ NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'denied', 'consumed')),
+  approved_user_id TEXT,
+  approved_session_id TEXT,
+  created_at TIMESTAMPTZ NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  approved_at TIMESTAMPTZ,
+  denied_at TIMESTAMPTZ,
+  consumed_at TIMESTAMPTZ,
+  PRIMARY KEY (project_id, id),
+  UNIQUE (project_id, user_code),
+  FOREIGN KEY (project_id, approved_user_id) REFERENCES auth_users (project_id, id),
+  FOREIGN KEY (project_id, approved_session_id) REFERENCES auth_sessions (project_id, id)
+);
+
+CREATE INDEX idx_auth_device_authorizations_pending
+  ON auth_device_authorizations (project_id, status, expires_at DESC);

package/src/migrations/035-share-grants.sql

@@ -0,0 +1,57 @@
+CREATE TABLE share_grants (
+  project_id TEXT NOT NULL CHECK (length(trim(project_id)) > 0),
+  id TEXT NOT NULL CHECK (length(trim(id)) > 0),
+  definition_id TEXT NOT NULL CHECK (length(trim(definition_id)) > 0),
+  target_object_type_id TEXT NOT NULL CHECK (length(trim(target_object_type_id)) > 0),
+  target_primary_id TEXT NOT NULL CHECK (length(trim(target_primary_id)) > 0),
+  issued_by_type TEXT NOT NULL CHECK (issued_by_type IN ('user', 'serviceAccount')),
+  issued_by_id TEXT NOT NULL CHECK (length(trim(issued_by_id)) > 0),
+  authority_version INTEGER NOT NULL CHECK (authority_version > 0),
+  authority_snapshot JSONB NOT NULL CHECK (
+    jsonb_typeof(authority_snapshot) = 'object'
+    AND jsonb_typeof(authority_snapshot -> 'version') = 'number'
+    AND (authority_snapshot ->> 'version')::integer = authority_version
+    AND jsonb_typeof(authority_snapshot -> 'access') = 'object'
+  ),
+  authority_digest TEXT NOT NULL CHECK (authority_digest ~ '^[0-9a-f]{64}$'),
+  token_hash TEXT NOT NULL CHECK (token_hash ~ '^[0-9a-f]{64}$'),
+  destination_path TEXT NOT NULL CHECK (
+    left(destination_path, 1) = '/'
+    AND position('?' IN destination_path) = 0
+    AND position('#' IN destination_path) = 0
+    AND position(chr(92) IN destination_path) = 0
+  ),
+  created_at TIMESTAMPTZ NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  revoked_at TIMESTAMPTZ,
+  revoked_by_type TEXT CHECK (
+    revoked_by_type IS NULL OR revoked_by_type IN ('user', 'serviceAccount', 'system')
+  ),
+  revoked_by_id TEXT CHECK (
+    revoked_by_id IS NULL OR length(trim(revoked_by_id)) > 0
+  ),
+  PRIMARY KEY (project_id, id),
+  UNIQUE (project_id, token_hash),
+  CHECK (expires_at > created_at),
+  CHECK (revoked_at IS NULL OR revoked_at >= created_at),
+  CHECK (
+    (revoked_at IS NULL AND revoked_by_type IS NULL AND revoked_by_id IS NULL)
+    OR
+    (revoked_at IS NOT NULL AND revoked_by_type IS NOT NULL AND revoked_by_id IS NOT NULL)
+  )
+);
+
+CREATE INDEX idx_share_grants_project_created
+  ON share_grants (project_id, created_at DESC, id DESC);
+CREATE INDEX idx_share_grants_definition_target
+  ON share_grants (
+    project_id,
+    definition_id,
+    target_object_type_id,
+    target_primary_id,
+    created_at DESC,
+    id DESC
+  );
+CREATE INDEX idx_share_grants_expiry
+  ON share_grants (project_id, expires_at)
+  WHERE revoked_at IS NULL;