Skip to content

V- Modal AI: Visual Video / Image Search - Flutter Video SDK

42.3 KB
Raw Blame
import 'dart:async';
import 'dart:convert';
import 'dart:math';
import 'dart:typed_data';

import 'package:crypto/crypto.dart';

import 'api_key_provider.dart';
import 'client.dart';
import 'collection_uploads.dart';
import 'config.dart';
import 'content_scope.dart';
import 'errors.dart';
import 'models.dart';
import 'session_guard.dart';
import 'transcode.dart';
import 'transport.dart';
import 'upload.dart';
import 'utils.dart';
import 'vmodal.dart';

/// Local permitted operations. These are client guardrails, not server grants.
enum UserAction {
  discover,
  search,
  upload,
  metadata,
  indexation,
  delete,
  media,
}

/// Explicit mapping representation; opaque selectors are never prefixed.
enum ScopeRepresentation { logical, opaque }

/// A live resource minted by a validated operation. It expires on session close.
final class SessionAsset {
  SessionAsset._(
    this._sessionId,
    this._scopeKey,
    this.assetId,
    this.fileName,
    this._media,
  );
  final String _sessionId;
  final String _scopeKey;
  final String? assetId;
  final String? fileName;
  final Map<String, Object?> _media;
}

/// Safe search data; media selectors and raw service capabilities stay private.
final class SessionSearchResponse extends SearchResponse {
  SessionSearchResponse._(super.raw, Iterable<SessionAsset> assets)
    : assets = List<SessionAsset>.unmodifiable(assets);
  final List<SessionAsset> assets;
}

/// Safe upload summary and its optional owner-bound asset handle.
final class SessionUploadResponse extends VideoUploadResponse {
  SessionUploadResponse._(super.raw, this.asset);
  final SessionAsset? asset;
}

/// Live job provenance, created or discovered within an exact allowed stream.
final class SessionJob extends IndexationSubmitResponse {
  SessionJob._(super.raw, this._sessionId, this._scopeKey, this._reference);
  final String _sessionId;
  final String _scopeKey;
  final DurableJobReference _reference;
  DurableJobReference toDurableReference() => _reference;
}

/// Serializable ownership metadata, never sufficient by itself to prove a job.
final class DurableJobReference {
  const DurableJobReference({
    required this.jobId,
    required this.ownerKey,
    required this.scopeKey,
    required this.policyRevision,
  });
  final String jobId;
  final String ownerKey;
  final String scopeKey;
  final String policyRevision;
}

/// A frozen host-authenticated mapping to one exact backend stream and mode.
final class ContentMapping {
  ContentMapping._({
    required this.representation,
    required this.collectionId,
    required this.streamName,
    required this.mode,
    required Set<UserAction> actions,
    required this.collectionWide,
    this.projectId,
    this.collectionName,
  }) : actions = Set<UserAction>.unmodifiable(actions);

  factory ContentMapping.logical({
    required String projectId,
    required String collectionName,
    required String streamName,
    String mode = 'vid_file',
    Set<UserAction> actions = const <UserAction>{UserAction.search},
    bool collectionWide = false,
  }) {
    final scope = ContentScope.create(projectId, collectionName, streamName);
    return ContentMapping._(
      representation: ScopeRepresentation.logical,
      collectionId: scope.backendCollectionName,
      projectId: scope.projectId,
      collectionName: scope.collectionName,
      streamName: scope.streamName,
      mode: strRequired(mode, 'mode'),
      actions: actions,
      collectionWide: collectionWide,
    );
  }

  factory ContentMapping.opaque({
    required String collectionId,
    required String streamName,
    String mode = 'vid_file',
    Set<UserAction> actions = const <UserAction>{UserAction.search},
    bool collectionWide = false,
  }) => ContentMapping._(
    representation: ScopeRepresentation.opaque,
    collectionId: strRequired(collectionId, 'collectionId'),
    streamName: strRequired(streamName, 'streamName'),
    mode: strRequired(mode, 'mode'),
    actions: actions,
    collectionWide: collectionWide,
  );

  final ScopeRepresentation representation;
  final String collectionId;
  final String streamName;
  final String mode;
  final String? projectId;
  final String? collectionName;
  final Set<UserAction> actions;
  final bool collectionWide;

  String get _selector => jsonEncode(<Object?>[
    representation.name,
    collectionId,
    streamName,
    mode,
  ]);

  List<Object?> get _policy => <Object?>[
    _selector,
    (actions.map((value) => value.name).toList()..sort()),
    collectionWide,
  ];
}

/// Identity and policy resolved by the host from its authenticated app user.
final class UserSessionPolicy {
  UserSessionPolicy({
    required this.tenantId,
    required this.appUserId,
    required Iterable<ContentMapping> allowedContentMapping,
    this.policyRevision,
  }) : allowedContentMapping = List<ContentMapping>.unmodifiable(
         allowedContentMapping,
       ) {
    strRequired(tenantId, 'tenantId');
    strRequired(appUserId, 'appUserId');
  }

  final String tenantId;
  final String appUserId;
  final List<ContentMapping> allowedContentMapping;
  final String? policyRevision;
}

/// Immutable ownership. Stable keys deliberately exclude credential versions.
final class SessionContext {
  SessionContext._(this.serviceNamespace, UserSessionPolicy policy)
    : tenantId = policy.tenantId,
      appUserId = policy.appUserId,
      allowedContentMapping = policy.allowedContentMapping,
      policyRevision = policy.policyRevision ?? _revision(policy),
      ownerKey = jsonEncode(<String>[
        serviceNamespace,
        policy.tenantId,
        policy.appUserId,
      ]);

  final String serviceNamespace;
  final String tenantId;
  final String appUserId;
  final String policyRevision;
  final String ownerKey;
  final List<ContentMapping> allowedContentMapping;

  String scopeKey(ContentMapping mapping) => jsonEncode(<String>[
    ownerKey,
    mapping.representation.name,
    mapping.collectionId,
    mapping.streamName,
    mapping.mode,
  ]);

  /// Canonical connection namespace, including the normalized gateway path.
  static String serviceNamespaceFor(SdkConfig config) {
    final uri = Uri.parse(config.normalizedBaseUrl);
    if (uri.hasQuery || uri.hasFragment) {
      throw const ValidationException(
        'User-session service URLs cannot contain a query or fragment',
      );
    }
    return uri
        .replace(scheme: uri.scheme.toLowerCase(), host: uri.host.toLowerCase())
        .normalizePath()
        .toString();
  }

  static String _revision(UserSessionPolicy policy) {
    final mappings = policy.allowedContentMapping.map((m) => m._policy).toList()
      ..sort((a, b) => jsonEncode(a).compareTo(jsonEncode(b)));
    return sha256.convert(utf8.encode(jsonEncode(mappings))).toString();
  }
}

/// One active application identity flow using a shared tenant credential.
final class UserSessionManager {
  UserSessionManager({
    required SdkConfig config,
    required SessionCredentialSource credentialSource,
    VmodalTransport Function(SdkConfig config)? transportFactory,
    SignedUploadTransport Function(SdkConfig config)?
    signedUploadTransportFactory,
    UploadSessionStore? uploadSessionStore,
    this.onInvalidated,
  }) : _config = config,
       _credentials = credentialSource,
       _uploadSessionStore = uploadSessionStore,
       _transportFactory = transportFactory ?? HttpVmodalTransport.new,
       _signedFactory =
           signedUploadTransportFactory ??
           ((config) => IoSignedUploadTransport(config.timeout)) {
    if (config.normalizedMode != 'gateway') {
      throw const ValidationException('User sessions require gateway mode');
    }
    if (credentialSource.serviceNamespace !=
        SessionContext.serviceNamespaceFor(config)) {
      throw const ValidationException(
        'Credential service binding does not match',
      );
    }
  }

  final SdkConfig _config;
  final SessionCredentialSource _credentials;
  final UploadSessionStore? _uploadSessionStore;
  final VmodalTransport Function(SdkConfig) _transportFactory;
  final SignedUploadTransport Function(SdkConfig) _signedFactory;
  final void Function(UserSession session)? onInvalidated;
  static final Expando<bool> _usedTransports = Expando<bool>(
    'session transports',
  );
  final List<Object> _cleanupErrors = <Object>[];
  List<Object> get cleanupErrors => List<Object>.unmodifiable(_cleanupErrors);
  UserSession? _current;
  int _ticket = 0;
  bool _closed = false;
  Future<void>? _closeFuture;

  UserSession? get current => _current?.isActive == true ? _current : null;

  Future<UserSession> openUserSession({
    required String tenantId,
    required String appUserId,
    required Iterable<ContentMapping> allowedContentMapping,
    String? policyRevision,
  }) {
    final policy = UserSessionPolicy(
      tenantId: tenantId,
      appUserId: appUserId,
      allowedContentMapping: allowedContentMapping,
      policyRevision: policyRevision,
    );
    return openResolvedSession(() async => policy);
  }

  /// Invalidates the outgoing user before resolving any new identity or policy.
  Future<UserSession> openResolvedSession(
    Future<UserSessionPolicy> Function() resolve,
  ) async {
    if (_closed) throw const OperationCanceled();
    final ticket = ++_ticket;
    final old = _current;
    _current = null;
    if (old != null) _observeClose(old.close());
    _checkTicket(ticket);
    final policy = await resolve();
    _checkTicket(ticket);
    if (policy.tenantId != _credentials.tenantId) {
      throw const ValidationException(
        'Credential tenant binding does not match',
      );
    }
    final context = SessionContext._(
      _credentials.projectId == null
          ? SessionContext.serviceNamespaceFor(_config)
          : jsonEncode(<String>[
              SessionContext.serviceNamespaceFor(_config),
              _credentials.projectId!,
            ]),
      policy,
    );
    final selectors = <String>{};
    for (final mapping in context.allowedContentMapping) {
      if (!selectors.add(mapping._selector)) {
        throw const ValidationException('Duplicate content mapping');
      }
    }
    final id = base64UrlEncode(
      List<int>.generate(24, (_) => Random.secure().nextInt(256)),
    );
    final guard = SessionGuard(id);
    final provider = _credentials.createProvider(
      isActive: () => guard.isActive,
    );
    final config = SdkConfig(
      baseUrl: _config.baseUrl,
      timeout: _config.timeout,
      idleTimeout: _config.idleTimeout,
      maxRetries: _config.maxRetries,
      apiKeyProvider: provider,
    );
    VmodalTransport? gateway;
    SignedUploadTransport? signed;
    try {
      gateway = _transportFactory(config);
      if (_usedTransports[gateway] == true) {
        gateway = null;
        throw const ValidationException('Session transports must be distinct');
      }
      _usedTransports[gateway] = true;
      _checkTicket(ticket);
      signed = _signedFactory(config);
      if (_usedTransports[signed] == true) {
        signed = null;
        throw const ValidationException('Session transports must be distinct');
      }
      _usedTransports[signed] = true;
      _checkTicket(ticket);
      final client = VmodalClient(
        config: config,
        transport: GuardedVmodalTransport(guard, gateway),
        signedUploadTransport: GuardedSignedUploadTransport(guard, signed),
      );
      final session = UserSession._(
        context,
        _credentials.expectedPrincipal,
        guard,
        provider,
        client,
        _uploadSessionStore,
        (session) {
          if (identical(_current, session) && ticket == _ticket) {
            _current = null;
          }
          onInvalidated?.call(session);
        },
      );
      _checkTicket(ticket);
      _current = session;
      return session;
    } on Object {
      guard.invalidate();
      provider.close();
      if (gateway != null) _observeClose(Future<void>.sync(gateway.close));
      if (signed != null) _observeClose(Future<void>.sync(signed.close));
      rethrow;
    }
  }

  Future<void> logout() {
    ++_ticket;
    final old = _current;
    _current = null;
    return old?.close() ?? Future<void>.value();
  }

  Future<void> close() {
    if (_closeFuture != null) return _closeFuture!;
    final done = Completer<void>();
    _closeFuture = done.future;
    _closed = true;
    unawaited(logout().then(done.complete, onError: done.completeError));
    return done.future;
  }

  void _checkTicket(int ticket) {
    if (_closed || ticket != _ticket) throw const OperationCanceled();
  }

  void _observeClose(Future<void> future) {
    unawaited(
      future.catchError((Object _) {
        _cleanupErrors.add(const TransportException());
      }),
    );
  }
}

/// Private resources and a fresh runtime lease for one app-user activation.
final class UserSession {
  UserSession._(
    this.context,
    this._expectedPrincipal,
    this._guard,
    this._provider,
    this._client,
    this._uploadStore,
    this._onInvalidated,
  );

  final SessionContext context;
  final String _expectedPrincipal;
  final SessionGuard _guard;
  final MutableApiKeyProvider _provider;
  final VmodalClient _client;
  final void Function(UserSession) _onInvalidated;
  final UploadSessionStore? _uploadStore;
  final Set<SessionAsset> _assets = <SessionAsset>{};
  final Set<SessionJob> _jobs = <SessionJob>{};
  final List<Object> _cleanupErrors = <Object>[];
  List<Object> get cleanupErrors => List<Object>.unmodifiable(_cleanupErrors);
  Future<void>? _closeFuture;

  String get sessionId => _guard.sessionId;
  bool get isActive => _guard.isActive;

  /// Resolves the tenant principal without turning it into app-user identity.
  Future<void> verifyPrincipal(
    String expectedPrincipal, {
    CancellationToken? cancellation,
  }) => _run((token) async {
    if (expectedPrincipal != _expectedPrincipal) {
      throw const ValidationException(
        'Tenant principal binding does not match',
      );
    }
    final profile = await _client.auth.me(cancellation: token);
    _guard.check();
    if (profile.userId != _expectedPrincipal) {
      throw const ValidationException('Tenant principal does not match');
    }
  }, cancellation: cancellation);

  /// Discovery returns mapping selectors only, with no tenant metadata or count.
  Future<List<ContentMapping>> listCollections({
    CancellationToken? cancellation,
  }) {
    _guard.check();
    final mapped = context.allowedContentMapping
        .where((m) => m.actions.contains(UserAction.discover))
        .toList();
    return _run((token) async {
      final response = await _client.collections.listGroups(
        cancellation: token,
      );
      _guard.check();
      return List<ContentMapping>.unmodifiable(
        mapped.where(
          (mapping) => response.data.any(
            (row) =>
                row.groupName == mapping.collectionId &&
                row.mode == mapping.mode,
          ),
        ),
      );
    }, cancellation: cancellation);
  }

  Future<T> _run<T>(
    Future<T> Function(CancellationToken) work, {
    CancellationToken? cancellation,
  }) => _guard.run(
    (token) => _safeWork(() => work(token)),
    cancellation: cancellation,
  );

  UserScope scope(ContentMapping requested) {
    _guard.check();
    final allowed = context.allowedContentMapping.where(
      (m) => m._selector == requested._selector,
    );
    if (allowed.isEmpty) {
      throw const ValidationException('Scope is not allowed');
    }
    return UserScope._(this, allowed.first);
  }

  /// Invalidates synchronously; callbacks and asynchronous disposal follow.
  Future<void> close() {
    if (_closeFuture != null) return _closeFuture!;
    final done = Completer<void>();
    _closeFuture = done.future;
    _guard.invalidate(
      beforeCancel: () {
        _provider.close();
        _assets.clear();
        _jobs.clear();
      },
    );
    _cleanupErrors.addAll(_guard.cleanupErrors);
    // Initiate captured resource disposal before notifying the host. The
    // callback may synchronously open a newer session or reenter close().
    final closing = Future<void>.sync(_client.close);
    try {
      _onInvalidated(this);
    } on Object {
      _cleanupErrors.add(
        const SdkException('Session notification cleanup failed'),
      );
    }
    unawaited(
      closing.then(
        done.complete,
        onError: (Object _, StackTrace _) {
          const failure = TransportException();
          _cleanupErrors.add(failure);
          done.completeError(failure);
        },
      ),
    );
    return done.future;
  }
}

/// An owner-bound host storage barrier, retired by logout or host deactivation.
/// Host code must capture its path/payload and check before publishing files.
final class SessionStorageLease {
  SessionStorageLease._(this._writer);
  final OwnerWriterLease _writer;
  String get sessionId => _writer.guard.sessionId;
  void check() => _writer.check();
  void retire() => _writer.retire();
  Future<T> run<T>(Future<T> Function() work) =>
      _writer.guard.run((_) => _writer.run(work));
}

/// Restricted operations bound to a frozen mapping and originating session.
final class UserScope {
  UserScope._(this._session, this.mapping);

  final UserSession _session;
  final ContentMapping mapping;
  late final OwnerUploadSessionStore _uploadStore = OwnerUploadSessionStore(
    guard: _session._guard,
    ownerKey: _session.context.ownerKey,
    scopeKey: scopeKey,
    policyRevision: _session.context.policyRevision,
    delegate: _session._uploadStore,
  );
  String get sessionId => _session.sessionId;
  String get scopeKey => _session.context.scopeKey(mapping);

  /// A captured owner barrier for host archive writes. It shares the session
  /// lifetime and never exposes a transport, credential or mutable guard.
  SessionStorageLease get storageLease {
    _session._guard.check();
    return SessionStorageLease._(
      OwnerCommitCoordinator.shared.open(
        'archive:${jsonEncode([_session.context.ownerKey, mapping.collectionId])}',
        _session._guard,
      ),
    );
  }

  void _allow(UserAction action, String mode) {
    _session._guard.check();
    if (!mapping.actions.contains(action) || mode != mapping.mode) {
      throw const ValidationException('Action or mode is not allowed');
    }
  }

  bool _matches(Map<String, Object?> row, {required bool requireSelectors}) {
    for (final field in <String, String>{
      'group_name': mapping.collectionId,
      'stream_name': mapping.streamName,
      'mode': mapping.mode,
    }.entries) {
      if (!row.containsKey(field.key)) {
        if (requireSelectors) return false;
      } else if (row[field.key] != field.value) {
        return false;
      }
    }
    return true;
  }

  SessionAsset _asset(Map<String, Object?> row) {
    _session._guard.check();
    final file =
        stringValueOrNull(row['video_filename']) ??
        stringValueOrNull(row['filename_sanitized']) ??
        stringValueOrNull(row['filename']) ??
        stringValueOrNull(row['file_name']);
    final safeFile =
        file != null &&
            !file.contains('/') &&
            !file.contains('\\') &&
            file != '.' &&
            file != '..'
        ? file
        : null;
    final asset = SessionAsset._(
      sessionId,
      scopeKey,
      stringValueOrNull(row['asset_id']),
      safeFile,
      _fields(row, const <String>{
        'modality',
        'ts_unix_13digits',
        'playback_offset_ms',
        'video_time_seconds',
        'timestamp_seconds',
      }),
    );
    _session._assets.add(asset);
    return asset;
  }

  SessionJob _job(Map<String, Object?> row) {
    _session._guard.check();
    final id = strRequired('${row['job_id'] ?? ''}', 'job_id');
    final job = SessionJob._(
      _fields(row, _jobFields),
      sessionId,
      scopeKey,
      DurableJobReference(
        jobId: id,
        ownerKey: _session.context.ownerKey,
        scopeKey: scopeKey,
        policyRevision: _session.context.policyRevision,
      ),
    );
    _session._jobs.add(job);
    return job;
  }

  void _checkAsset(SessionAsset asset) {
    _session._guard.check();
    if (asset._sessionId != sessionId ||
        asset._scopeKey != scopeKey ||
        !_session._assets.contains(asset)) {
      throw const ValidationException('Asset provenance does not match');
    }
  }

  /// Every batch member must come from this exact live scope before dispatch.
  Future<CollectionAddAssetsResponse> addAssets(
    List<SessionAsset> assets, {
    ScopedAddAssetsOptions options = const ScopedAddAssetsOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.metadata, options.mode);
    final captured = List<SessionAsset>.of(assets);
    for (final asset in captured) {
      _checkAsset(asset);
      if (asset.assetId == null) {
        throw const ValidationException('Asset has no stable identifier');
      }
    }
    return _session._run(
      (token) async => CollectionAddAssetsResponse(
        _fields(
          (await _session._client.collections.addAssets(
            collectionId: mapping.collectionId,
            assetIds: captured.map((a) => a.assetId!).toList(),
            mode: mapping.mode,
            groupName: mapping.collectionId,
            streamName: mapping.streamName,
            cancellation: token,
          )).raw,
          const <String>{'status', 'added', 'updated'},
        ),
      ),
      cancellation: cancellation,
    );
  }

  /// Mutates a filename minted by a scoped search or completed upload.
  Future<CollectionDescriptionUpdateResponse> updateAsset(
    SessionAsset asset, {
    required ScopedAssetChanges changes,
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.metadata, changes.mode);
    _checkAsset(asset);
    if (asset.fileName == null) {
      throw const FeatureDisabled('This asset has no validated filename');
    }
    final tags = changes.tags == null
        ? null
        : List<String>.unmodifiable(changes.tags!);
    return _session._run(
      (token) async => CollectionDescriptionUpdateResponse(
        _fields(
          (await _session._client.collections.updateDescription(
            groupName: mapping.collectionId,
            mode: mapping.mode,
            streamName: mapping.streamName,
            filenameSanitized: asset.fileName!,
            description: changes.description,
            tag: tags,
            cancellation: token,
          )).raw,
          const <String>{'status', 'updated'},
        ),
      ),
      cancellation: cancellation,
    );
  }

  /// The URL grant remains private and bytes are fenced through each phase.
  Future<Uint8List> imageBytes(
    SessionAsset asset, {
    int? maxBytes,
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.media, mapping.mode);
    _checkAsset(asset);
    if (asset.fileName == null) {
      throw const FeatureDisabled('This asset has no validated media selector');
    }
    final modality = switch (mapping.mode) {
      'img_file' => 'img_raw',
      'vid_file' || 'vid_stream_day' => 'vid_img',
      _ => throw const FeatureDisabled('Media is unavailable for this mode'),
    };
    final reported = asset._media['modality'];
    if (reported != null && reported != modality) {
      throw const ValidationException(
        'Media modality does not match the scope',
      );
    }
    Object? timestamp = asset._media['ts_unix_13digits'];
    // File-video frames are relative to their source video. Day-stream media
    // requires its real epoch timestamp and cannot use this offset fallback.
    if (timestamp == null && mapping.mode == 'vid_file') {
      timestamp = VideoSearchHit(asset._media).playbackOffsetMs;
    }
    String? ts13;
    if (timestamp != null) {
      final value = '$timestamp';
      if (!RegExp(r'^\d{1,13}$').hasMatch(value)) {
        throw const ValidationException('Media timestamp is invalid');
      }
      ts13 = value.padLeft(13, '0');
    }
    if (mapping.mode != 'img_file' && ts13 == null) {
      throw const FeatureDisabled(
        'This video asset has no validated frame time',
      );
    }
    return _session._run((token) async {
      final result = await _session._client.images.getUrl(
        mode: mapping.mode,
        groupName: mapping.collectionId,
        streamName: mapping.streamName,
        modality: modality,
        filename: asset.fileName!,
        tsUnix13digits: ts13,
        cancellation: token,
      );
      _session._guard.check();
      token.throwIfCanceled();
      if (!result.found || result.urlPreSigned.isEmpty) {
        throw const FeatureDisabled('Media is unavailable');
      }
      return _session._client.images.getImageFromUrl(
        result.urlPreSigned,
        maxBytes: maxBytes,
        cancellation: token,
      );
    }, cancellation: cancellation);
  }

  /// Tenant job lists are filtered by all selectors before minting provenance.
  Future<List<SessionJob>> listIndexJobs({
    ScopedIndexJobsOptions options = const ScopedIndexJobsOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.indexation, options.mode ?? mapping.mode);
    return _session._run((token) async {
      final response = await _session._client.indexes.jobsList(
        status: options.status,
        mode: mapping.mode,
        groupName: mapping.collectionId,
        limit: options.limit,
        cancellation: token,
      );
      _session._guard.check();
      return List<SessionJob>.unmodifiable(
        objectList(response.raw['data'])
            .where(
              (row) =>
                  _matches(row, requireSelectors: true) &&
                  stringValueOrNull(row['job_id']) != null,
            )
            .map(_job),
      );
    }, cancellation: cancellation);
  }

  Future<IndexationStatusResponse> indexStatus(
    SessionJob job, {
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.indexation, mapping.mode);
    if (job._sessionId != sessionId ||
        job._scopeKey != scopeKey ||
        !_session._jobs.contains(job)) {
      throw const ValidationException('Job provenance does not match');
    }
    return _session._run((token) async {
      final response = await _session._client.indexes.indexStatus(
        job.jobId,
        cancellation: token,
      );
      if (response.jobId != job.jobId ||
          !_matches(response.raw, requireSelectors: false)) {
        throw const MalformedResponse('Job result does not match');
      }
      return IndexationStatusResponse(_fields(response.raw, _jobFields));
    }, cancellation: cancellation);
  }

  /// Rebinding needs current policy and a fresh exact scoped discovery record.
  Future<SessionJob> rebindJob(
    DurableJobReference reference, {
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.indexation, mapping.mode);
    if (reference.ownerKey != _session.context.ownerKey ||
        reference.scopeKey != scopeKey ||
        reference.policyRevision != _session.context.policyRevision) {
      throw const ValidationException('Durable job ownership does not match');
    }
    return _session._run((token) async {
      final jobs = await listIndexJobs(
        options: ScopedIndexJobsOptions(mode: mapping.mode, limit: 1000),
        cancellation: token,
      );
      _session._guard.check();
      final matches = jobs.where((job) => job.jobId == reference.jobId);
      if (matches.isEmpty) {
        throw const FeatureDisabled(
          'Job has no current scoped ownership proof',
        );
      }
      return matches.first;
    }, cancellation: cancellation);
  }

  /// Backend index deletion affects the collection, including other streams.
  Future<IndexationDeleteResponse> deleteIndex(
    String version, {
    ScopedDeleteIndexOptions options = const ScopedDeleteIndexOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.delete, options.mode);
    if (!mapping.collectionWide) {
      throw const ValidationException('Collection-wide access is required');
    }
    final request = IndexationDeleteRequest(
      mode: mapping.mode,
      groupName: mapping.collectionId,
      version: version,
      modality: options.modality,
      dryRun: options.dryRun,
      confirm: options.confirm,
    );
    return _session._run(
      (token) async => IndexationDeleteResponse(
        _fields(
          (await _session._client.indexes.deleteIndex(
            request,
            cancellation: token,
          )).raw,
          const <String>{'status', 'deleted', 'dry_run'},
        ),
      ),
      cancellation: cancellation,
    );
  }

  /// Aggregate versions require collection-wide access or an exact stream row.
  Future<GroupItem?> collectionInfo({CancellationToken? cancellation}) {
    _allow(UserAction.discover, mapping.mode);
    return _session._run((token) async {
      final response = await _session._client.collections.listGroups(
        mode: mapping.mode,
        cancellation: token,
      );
      _session._guard.check();
      for (final row in response.data) {
        if (row.groupName != mapping.collectionId || row.mode != mapping.mode) {
          continue;
        }
        if (!mapping.collectionWide &&
            row.raw['stream_name'] != mapping.streamName) {
          continue;
        }
        return GroupItem(
          _fields(row.raw, const <String>{
            'group_name',
            'mode',
            'stream_name',
            'lancedb_versions',
          }),
        );
      }
      return null;
    }, cancellation: cancellation);
  }

  Future<int?> latestVersion({CancellationToken? cancellation}) =>
      _session._run(
        (token) async =>
            (await collectionInfo(cancellation: token))?.latestLancedbVersion,
        cancellation: cancellation,
      );

  Future<SessionSearchResponse> search(
    String query, {
    ScopedSearchOptions options = const ScopedSearchOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.search, options.mode);
    final request = SearchRequest(
      queryText: query,
      queryMetadata: options.queryMetadata == null
          ? null
          : _snapshot(options.queryMetadata!) as Map<String, Object?>,
      queryMetadataText: options.queryMetadataText,
      imageQuery: options.imageQuery,
      mode: mapping.mode,
      groupName: mapping.collectionId,
      streamName: mapping.streamName,
      searchSources: List<String>.unmodifiable(options.searchSources),
      searchCombineMode: options.searchCombineMode,
      startDate: options.startDate,
      endDate: options.endDate,
      offset: options.offset,
      limit: options.limit,
      textEmbScoreMin: options.textEmbScoreMin,
      imageEmbScoreMin: options.imageEmbScoreMin,
      versionLancedb: options.versionLancedb,
    );
    return _session._run((token) async {
      final result = await _session._client.searches.searchVideo(
        request,
        cancellation: token,
      );
      _session._guard.check();
      final rows = objectList(result.raw['data'])
          .where((row) => _matches(row, requireSelectors: false))
          .map((row) => _fields(row, _searchFields))
          .toList();
      final assets = rows.map(_asset).toList();
      return SessionSearchResponse._(
        _snapshot(<String, Object?>{
              'data': rows,
              'cnt_actual': rows.length,
              'cnt_total': rows.length,
            })
            as Map<String, Object?>,
        assets,
      );
    }, cancellation: cancellation);
  }

  Future<MetadataParquetUploadResponse> uploadMetadata(
    VmodalFilePart part, {
    ScopedMetadataOptions options = const ScopedMetadataOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.metadata, options.mode);
    return _session._run((token) async {
      // Existing metadata records must bind to live scoped asset provenance.
      // A bounded immutable snapshot prevents the opener changing after validation.
      final bytes = await readBounded(
        VmodalResponse(
          statusCode: 200,
          contentLength: part.contentLength,
          body: _session._guard.guardStream(part.open(), cancellation: token),
        ),
        8 * 1024 * 1024,
        cancellation: token,
      );
      _session._guard.check();
      token.throwIfCanceled();
      final lines = utf8
          .decode(bytes)
          .split('\n')
          .where((line) => line.trim().isNotEmpty);
      if (lines.isEmpty) throw const ValidationException('Metadata is empty');
      for (final line in lines) {
        final decoded = jsonDecode(line);
        if (decoded is! Map<String, Object?>) {
          throw const ValidationException('Metadata row must be an object');
        }
        const fields = <String>{
          'filename',
          'filename_sanitized',
          'asset_id',
          'description',
          'metadata_text',
          'tags',
          'tag',
        };
        if (decoded.keys.any((key) => !fields.contains(key))) {
          throw const ValidationException('Unsupported metadata field');
        }
        final id = stringValueOrNull(decoded['asset_id']);
        final filename =
            stringValueOrNull(decoded['filename_sanitized']) ??
            stringValueOrNull(decoded['filename']);
        if (id == null && filename == null) {
          throw const ValidationException('Metadata needs a proven asset');
        }
        final proven = _session._assets.any(
          (asset) =>
              asset._sessionId == sessionId &&
              asset._scopeKey == scopeKey &&
              (id == null || asset.assetId == id) &&
              (filename == null || asset.fileName == filename),
        );
        if (!proven ||
            decoded['filename'] != null &&
                decoded['filename_sanitized'] != null &&
                decoded['filename'] != decoded['filename_sanitized']) {
          throw const ValidationException(
            'Metadata asset provenance does not match',
          );
        }
        for (final value in decoded.values) {
          if (value is! String &&
              value is! List<String> &&
              !(value is List && value.every((v) => v is String))) {
            throw const ValidationException('Unsupported metadata value');
          }
        }
      }
      final captured = VmodalFilePart.bytes(
        fieldName: part.fieldName,
        fileName: part.fileName,
        contentType: part.contentType,
        bytes: bytes,
      );
      return MetadataParquetUploadResponse(
        _fields(
          (await _session._client.collections.uploadMetadataJsonl(
            captured,
            mode: mapping.mode,
            groupName: mapping.collectionId,
            streamName: mapping.streamName,
            writeMode: options.writeMode,
            allowOverlap: options.allowOverlap,
            cancellation: token,
          )).raw,
          const <String>{'status', 'accepted', 'written', 'uploaded'},
        ),
      );
    }, cancellation: cancellation);
  }

  UploadTask<SessionUploadResponse> upload(
    UploadSource source, {
    ScopedUploadOptions options = const ScopedUploadOptions(),
  }) {
    _allow(UserAction.upload, options.mode);
    if (options.uploadOptions.sessionStore != null) {
      throw const ValidationException(
        'Use only session-owned upload checkpoints',
      );
    }
    if (options.uploadOptions.transcoder.runtimeType !=
        PassthroughVideoTranscoder) {
      throw const ValidationException(
        'Custom transcoders are not session-owned',
      );
    }
    final captured = options.uploadOptions.copyWith(
      sessionStore: _uploadStore,
      metadataTags: options.uploadOptions.metadataTags == null
          ? null
          : List<String>.unmodifiable(options.uploadOptions.metadataTags!),
    );
    final operation = _session._guard.register();
    return _SessionUploadTask<SessionUploadResponse>(_session._guard, (
      cancel,
      emit,
    ) async {
      final remove = cancel.onCancel(operation.token.cancel);
      return operation.run(
        (token) => _safeWork(() async {
          final task = _session._client.collections.videoUpload(
            source,
            collectionName: mapping.collectionId,
            subCollectionName: mapping.streamName,
            mode: mapping.mode,
            modality: options.modality,
            ttl: options.ttl,
            options: captured,
          );
          final detach = token.onCancel(task.cancel);
          final subscription = _session._guard
              .guardStream(task.progress, cancellation: token)
              .listen(emit, onError: (Object _) {});
          try {
            final result = await task.result;
            operation.check();
            final done = objectMap(result.raw['upload_done']);
            if (!_matches(done, requireSelectors: false)) {
              throw const MalformedResponse(
                'Upload result scope does not match',
              );
            }
            final safe = _fields(<String, Object?>{
              ...result.raw,
              if (done['asset_id'] is String) 'asset_id': done['asset_id'],
            }, _uploadFields);
            final asset =
                stringValueOrNull(safe['asset_id']) != null ||
                    stringValueOrNull(safe['filename']) != null
                ? _asset(safe)
                : null;
            return SessionUploadResponse._(safe, asset);
          } finally {
            detach();
            remove();
            await subscription.cancel();
          }
        }),
      );
    });
  }

  Future<SessionJob> createIndex({
    ScopedCreateIndexOptions options = const ScopedCreateIndexOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.indexation, options.mode);
    final request = IndexationSubmitRequest(
      mode: mapping.mode,
      groupName: mapping.collectionId,
      streamName: mapping.streamName,
      indexType: options.indexType,
      modality: options.modality,
      insertMode: options.insertMode,
      createIndex: options.createIndex,
      version: options.version,
      startDate: options.startDate,
      endDate: options.endDate,
      embeddingModel: options.embeddingModel,
      reProcess: options.reProcess,
      dryRun: options.dryRun,
    );
    return _session._run((token) async {
      final result = await _session._client.indexes.createIndex(
        request,
        cancellation: token,
      );
      _session._guard.check();
      if (!_matches(result.raw, requireSelectors: false)) {
        throw const MalformedResponse('Index result scope does not match');
      }
      return _job(result.raw);
    }, cancellation: cancellation);
  }

  Future<DeleteCollectionResponse> deleteCollection({
    ScopedDeleteCollectionOptions options =
        const ScopedDeleteCollectionOptions(),
    CancellationToken? cancellation,
  }) {
    _allow(UserAction.delete, options.mode);
    if (!mapping.collectionWide) {
      throw const ValidationException('Collection-wide access is required');
    }
    return _session._run(
      (token) async => DeleteCollectionResponse(
        _fields(
          (await _session._client.collections.delete(
            groupName: mapping.collectionId,
            mode: mapping.mode,
            scope: options.scope,
            dryRun: options.dryRun,
            confirm: options.confirm,
            cancellation: token,
          )).raw,
          const <String>{'status', 'deleted', 'dry_run'},
        ),
      ),
      cancellation: cancellation,
    );
  }
}

// Fence the public task's stream too: its controller may buffer events while
// the caller pauses, after the upstream guarded subscription accepted them.
final class _SessionUploadTask<T> extends UploadTask<T> {
  _SessionUploadTask(this._guard, UploadRunner<T> runner) : super.start(runner);
  final SessionGuard _guard;
  late final Future<T> _guardedResult = _guard.run(
    (_) => super.result,
    cancellation: cancellation,
  );
  @override
  Future<T> get result => _guardedResult;
  @override
  Stream<UploadProgress> get progress =>
      _guard.guardStream(super.progress, cancellation: cancellation);
}

Object? _snapshot(Object? value) {
  if (value is Map) {
    if (value.keys.any((key) => key is! String)) {
      throw const ValidationException('Structured input keys must be strings');
    }
    return Map<String, Object?>.unmodifiable(
      value.map((k, v) => MapEntry(k as String, _snapshot(v))),
    );
  }
  if (value is List) return List<Object?>.unmodifiable(value.map(_snapshot));
  if (value == null || value is String || value is num || value is bool) {
    return value;
  }
  throw const ValidationException('Structured input must contain JSON values');
}

const _searchFields = <String>{
  'asset_id',
  'filename',
  'filename_sanitized',
  'file_name',
  'video_filename',
  'title',
  'description',
  'metadata_text',
  'tags',
  'playback_offset_ms',
  'video_time_seconds',
  'timestamp_seconds',
  'distance',
  'score',
  'ts_unix_13digits',
  'modality',
};
const _uploadFields = <String>{
  'asset_id',
  'filename',
  'size_bytes',
  'uploaded',
  'upload_strategy',
  'part_size_bytes',
  'part_count',
  'parts_uploaded',
  'resumed',
  'attempt_count',
  'video_filename',
  'start_datetime_user',
  'start_ts_unix_user_ms',
  'timestamp_source',
  'reduce_size',
  'source_size_bytes',
  'temporary_file_deleted',
  'temporary_file_reused',
};
const _jobFields = <String>{'job_id', 'status', 'version', 'progress'};

// Only documented scalar display fields or homogeneous scalar lists survive.
// Extension maps and nested records never inherit the outer row's provenance.
Map<String, Object?> _fields(Map<String, Object?> row, Set<String> allowed) {
  final safe = <String, Object?>{};
  for (final key in allowed) {
    final value = row[key];
    if (value is String || value is num || value is bool) {
      safe[key] = value;
    } else if (value is List &&
        value.every((v) => v is String || v is num || v is bool)) {
      safe[key] = List<Object?>.unmodifiable(value);
    }
  }
  return Map<String, Object?>.unmodifiable(safe);
}

// Restricted errors carry no raw tenant-wide body, signed grant or cause.
Future<T> _safeWork<T>(Future<T> Function() work) async {
  try {
    return await work();
  } on OperationCanceled {
    rethrow;
  } on FeatureDisabled {
    throw const FeatureDisabled('Operation is unavailable in this scope');
  } on ValidationException {
    throw const ValidationException('Operation validation failed');
  } on BackendAuthException {
    rethrow;
  } on AuthException {
    throw const TenantAuthException();
  } on ApiException catch (error) {
    throw ApiException('Scoped operation failed', statusCode: error.statusCode);
  } on ResponseTooLarge catch (error) {
    throw ResponseTooLarge(error.limitBytes, error.observedBytes);
  } on MalformedResponse {
    throw const MalformedResponse();
  } on FormatException {
    throw const ValidationException('Structured input is malformed');
  } on Object {
    throw const TransportException();
  }
}