Proposal: developer-facing project, collection, and stream interface

[syaheer]

Summary

Define a simpler, developer_facing Android SDK interface around three concepts__

_ Project — identifies one app or product owned by the developer.
_ Collection — a logical searchable index inside that project.
_ Stream — a source or grouping inside the collection.

This interface should hide the backend's current two_level collection/sub_collection structure.

Motivation

Backend_oriented names such as tenant_id and end_userid are difficult to apply consistently across different mobile applications. Not every app has an end_user_specific index; some apps need one global index, while others need an isolated index per end user.

Developers should be able to organize VModal data according to their application's domain without needing to understand the backend storage layout.

Proposed public terminology

| SDK concept | Meaning | Examples |
| ___ | ___ | ___ |
| projectId | Developer_owned app or product | food_app, shopping_app |
| collectionName | Logical searchable index | global, user_123, product_catalog |
| streamName | Source/group within a collection | uploads, camera, favorites |

projectId is intentionally different from userId__ in a mobile SDK, userId normally means the app's end user. Authentication identity fields can remain internal/separate from this content_organization interface.

Proposed Kotlin interface

Illustrative developer_facing API__

VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
)

VModal.setCollection("user_123")
VModal.setStream("favorites")

The current selection is then used by upload, indexing, and search operations__

VModal.upload(video)
VModal.search("birthday dinner")

An equivalent immutable/scoped API is acceptable if it is safer for concurrent Android work, provided the developer_facing terminology and usage remain simple__

val vmodal = VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
)

val favorites = vmodal.scope(
    collectionName = "user_123",
    streamName = "favorites",
)

favorites.upload(video)
favorites.search("birthday dinner")

This avoids one process_wide mutable collection when multiple users, workers, or simultaneous operations are active.

Internal API mapping

Enforce rules inside the SDK

collection_name __   only a_z A_Z 0_9 `_` characters.          and 80 characters max
stream_name __        only a_z A_Z 0_9 `_` characters.          and 80 characters max

enforce those rules and raise error if developper input wrong ones.

The backend currently supports only two hierarchy levels. The SDK should synthesize the project level by prefixing the collection__

## SDK__
  projectId      = "food_app"
  collectionName = "user_123"
  streamName     = "favorites"

## Backend/API__
  ## aggregate by 2 `_`  __  `__`  underscore ...
  collection_name = "food_app__user_123"
  stream_name     = "favorites"

Conceptually__

projectId + "__" + collectionName _> backend collection
streamName                       _> backend sub_collection/stream

The encoding must be centralized inside the SDK so callers never construct the composite name themselves. The implementation should either reject the reserved separator in project/collection names or use an escaping scheme to prevent collisions.

Reference use cases

1. Global search index

A Google Search_style app has one central index containing all searchable videos/assets__

val search = VModal.configure(
    projectId = "video_search",
    apiKey = apiKey,
).scope(
    collectionName = "global",
    streamName = "uploads",
)

search.upload(video)
search.search("red bicycle near a bridge")

Backend collection__ video_search__global

2. Private index per end user

Each app user has an isolated searchable index__

val personal = VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
).scope(
    collectionName = "user__$endUserId",
    streamName = "personal_videos",
)

personal.upload(video)
personal.search("pasta recipe")

Backend collection example__ food_app__user_123

The end_user identifier is an application concern expressed through collectionName; it is not a mandatory SDK concept.

3. Multiple streams for one user

One user collection can separate assets by source or purpose__

val app = VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
)

val camera = app.scope("user_123", "camera")
val favorites = app.scope("user_123", "favorites")
val uploads = app.scope("user_123", "uploads")

All three use backend collection food_app__user_123, with different stream_name values.

4. Product catalog

A commerce app can organize indexes by business domain rather than by end user__

val catalog = VModal.configure(
    projectId = "shopping_app",
    apiKey = apiKey,
).scope(
    collectionName = "product_catalog",
    streamName = "merchant_uploads",
)

Backend collection__ shopping_app__product_catalog

5. Multiple developer projects

The same developer can use separate project IDs for different apps__

val foodApp = VModal.configure("food_app", foodAppApiKey)
val shoppingApp = VModal.configure("shopping_app", shoppingAppApiKey)

Their logical collection names may be identical without colliding because the project ID is included in the backend collection name.

Behavioral expectations

_ projectId is required when configuring the SDK.
_ collectionName is required for collection_bound upload, indexing, and search operations.
_ streamName has an explicitly documented default or is required; it must not silently vary between operations.
_ Values are trimmed and validated consistently.
_ The SDK constructs the backend collection name in one internal helper.
_ Upload, indexing, search, listing, and deletion use the same mapping.
_ Public errors and documentation use project/collection/stream terminology.
_ Authentication identity remains separate from project/content organization.
_ The design works safely when multiple scopes or users are active concurrently.
_ Existing APIs receive a documented migration/deprecation path.

Open implementation decisions

_ Choose the final class/facade name__ VModal versus the existing Client.
_ Choose a stateful setter interface versus an immutable scope(...) interface. The scoped form is preferable for thread safety, but both examples document the intended developer experience.
_ Define allowed characters and maximum lengths for all three names.
_ Decide whether streamName should default to a stable value such as "default".
_ Define how listing APIs remove the projectId__ prefix before returning collection names to SDK callers.

Acceptance criteria

_ [ ] Public API specification is agreed for project, collection, and stream selection.
_ [ ] projectId + collectionName maps deterministically to the backend collection_name.
_ [ ] streamName maps to the backend stream/sub_collection level.
_ [ ] Callers never need to build or parse projectId__collectionName.
_ [ ] Global_index, per_user_index, multi_stream, catalog, and multi_project use cases are covered.
_ [ ] Naming validation and separator collision behavior are documented.
_ [ ] Authentication identity and content organization are kept conceptually separate.
_ [ ] A backward_compatibility/deprecation plan is documented before implementation.

[arita37]

API Surface List

The following is the required high-level public surface. Exact option and
response model field lists should reuse the existing SDK models where
possible, but organization fields must come only from VModalScope.

Public API	Purpose	Organization behavior
VModal.configure(projectId, apiKey, ...)	Create a project client	Trims and validates projectId; keeps auth separate
VModalProject.projectId	Return the normalized public project ID	Never returns a backend composite name
VModalProject.scope(collectionName, streamName)	Create an immutable operation scope	Validates both names and computes the backend collection internally
VModalProject.listCollections(...)	List logical collections for this project	Filters by the exact project prefix and removes it from results
VModalScope.projectId	Return the normalized project ID	Public value only
VModalScope.collectionName	Return the normalized collection name	Public value only
VModalScope.streamName	Return the normalized stream name	Public value only
VModalScope.upload(source, options)	Upload and index an asset	Uses the scope's encoded collection and stream
VModalScope.uploadEvents(source, options)	Upload with progress as a cold Flow	Uses the same mapping as upload
VModalScope.uploadMetadata(part, options)	Upload collection metadata	Uses the same mapping as search and upload
VModalScope.search(query, options)	Search the selected scope	Callers cannot override collection or stream in options
VModalScope.addAssets(collectionId, assetIds, options)	Add existing assets	Injects the scope's encoded collection and stream
VModalScope.updateAsset(filename, changes)	Update asset description/tags	Injects the scope's encoded collection and stream
VModalScope.createIndex(options)	Create an index job	Injects the scope's encoded collection and stream
VModalScope.listIndexJobs(options)	List jobs for the selected collection	Filters with the encoded collection; stream filtering is used only if supported by the backend
VModalScope.indexStatus(jobId)	Read one index job	Does not accept alternate organization fields
VModalScope.deleteIndex(version, options)	Delete an index version	Injects the scope's encoded collection
VModalScope.deleteCollection(options)	Delete the logical collection	Deletes the full encoded collection; requires existing dry-run/confirm safeguards

[arita37]

Project, collection, and stream API surface

Date: 2026-07-24
Version: 1.0
Status: Proposed

Summary

Define a simpler developer-facing Android SDK interface around three concepts:

• Project — one app or product owned by the developer.
• Collection — one logical searchable index inside that project.
• Stream — one source or grouping inside the collection.

The public interface must hide the backend's current two-level
collection/sub-collection structure. The SDK synthesizes the project level by
encoding projectId and collectionName into the backend collection name.

This specification chooses an immutable scope(...) API. A scope can be
shared safely by Android UI, coroutine, and WorkManager code without changing
process-wide mutable state.

Motivation

Backend-oriented names such as tenantId, userId, groupName, and
subCollectionName are difficult to apply consistently across mobile
applications. Not every app has an end-user-specific index:

• Some apps use one global index.
• Some apps isolate one index per end user.
• Some apps organize indexes by catalog, workspace, channel, or another
  business concept.
• One collection can contain multiple streams such as camera captures,
  uploads, and favorites.

Developers should organize VModal data according to their application's domain
without understanding the backend storage layout. Authentication identity and
content organization must remain separate concepts.

Scope

This change adds a high-level Kotlin facade over the existing Android SDK:

• Configure one developer project.
• Create immutable collection/stream scopes.
• Validate and encode organization names in one internal component.
• Apply the same encoded names to upload, metadata, indexing, search, listing,
  update, and deletion operations.
• Decode project collection names returned by listing operations.
• Preserve the existing Client API during a documented migration period.
• Reuse the existing coroutine transport, models, upload engine, response
  types, retry behavior, and SdkError hierarchy.

Out of scope:

• Adding a third hierarchy level to the backend.
• Changing authentication or deriving projectId from an end-user identity.
• Requiring every application to have an end user.
• Replacing backend routes or response contracts.
• Adding process-wide mutable collection or stream selection.
• Removing the existing Client API in the first release.

Proposed public terminology

SDK concept	Meaning	Examples
projectId	Developer-owned app or product	food_app, shopping_app
collectionName	Logical searchable index	global, user_123, product_catalog
streamName	Source or group within a collection	uploads, camera, favorites

projectId is intentionally different from userId. In a mobile SDK,
userId normally means the app's end user. Authentication identity fields
remain internal to, or separate from, this content-organization API.

Public KDoc, examples, validation errors, and new model properties must use
project, collection, and stream. They must not require developers to
understand tenant, group, or sub_collection.

Public API decision

Use VModal as the high-level facade and keep Client as the existing
advanced/compatibility API.

VModal.configure(...) returns an immutable project client. Calling
scope(...) returns an immutable collection/stream client. Configuration and
scope creation perform no network I/O.

val app = VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
)

val favorites = app.scope(
    collectionName = "user_123",
    streamName = "favorites",
)

val upload = favorites.upload(video)
val results = favorites.search("birthday dinner")

The facade uses suspend functions for operations that perform network I/O.
Upload progress uses the existing cold Flow behavior. The caller continues
to own its CoroutineScope, lifecycle, and WorkManager lifetime.

No setCollection(...) or setStream(...) method is added. Mutable setters
would make concurrent work dependent on call order and could route an
operation to another user's scope.

API Surface List

The following is the required high-level public surface. Exact option and
response model field lists should reuse the existing SDK models where
possible, but organization fields must come only from VModalScope.

Public API	Purpose	Organization behavior
VModal.configure(projectId, apiKey, ...)	Create a project client	Trims and validates projectId; keeps auth separate
VModalProject.projectId	Return the normalized public project ID	Never returns a backend composite name
VModalProject.scope(collectionName, streamName)	Create an immutable operation scope	Validates both names and computes the backend collection internally
VModalProject.listCollections(...)	List logical collections for this project	Filters by the exact project prefix and removes it from results
VModalScope.projectId	Return the normalized project ID	Public value only
VModalScope.collectionName	Return the normalized collection name	Public value only
VModalScope.streamName	Return the normalized stream name	Public value only
VModalScope.upload(source, options)	Upload and index an asset	Uses the scope's encoded collection and stream
VModalScope.uploadEvents(source, options)	Upload with progress as a cold Flow	Uses the same mapping as upload
VModalScope.uploadMetadata(part, options)	Upload collection metadata	Uses the same mapping as search and upload
VModalScope.search(query, options)	Search the selected scope	Callers cannot override collection or stream in options
VModalScope.addAssets(collectionId, assetIds, options)	Add existing assets	Injects the scope's encoded collection and stream
VModalScope.updateAsset(filename, changes)	Update asset description/tags	Injects the scope's encoded collection and stream
VModalScope.createIndex(options)	Create an index job	Injects the scope's encoded collection and stream
VModalScope.listIndexJobs(options)	List jobs for the selected collection	Filters with the encoded collection; stream filtering is used only if supported by the backend
VModalScope.indexStatus(jobId)	Read one index job	Does not accept alternate organization fields
VModalScope.deleteIndex(version, options)	Delete an index version	Injects the scope's encoded collection
VModalScope.deleteCollection(options)	Delete the logical collection	Deletes the full encoded collection; requires existing dry-run/confirm safeguards

Illustrative Kotlin declarations:

object VModal {
    fun configure(
        projectId: String,
        apiKey: String,
        baseUrl: String = PUBLIC_GATEWAY_URL,
        timeoutMillis: Int = 30_000,
        maxRetries: Int = 1,
    ): VModalProject
}

class VModalProject internal constructor(...) {
    val projectId: String

    fun scope(
        collectionName: String,
        streamName: String,
    ): VModalScope

    suspend fun listCollections(
        mode: String? = null,
    ): List<String>
}

class VModalScope internal constructor(...) {
    val projectId: String
    val collectionName: String
    val streamName: String

    suspend fun upload(
        source: UploadSource,
        options: ScopedUploadOptions = ScopedUploadOptions(),
    ): VideoUploadResponse

    fun uploadEvents(
        source: UploadSource,
        options: ScopedUploadOptions = ScopedUploadOptions(),
    ): Flow<VideoUploadEvent>

    suspend fun search(
        query: String,
        options: ScopedSearchOptions = ScopedSearchOptions(),
    ): SearchResponse
}

The full implementation may add overloads for existing file and request
types. It must not add overloads that let a caller supply groupName,
collectionName, subCollectionName, or streamName for a scoped operation.

Scoped option models must omit organization fields. Reusing an existing
request model that contains groupName or streamName is allowed only
internally, after the facade overwrites those fields from the scope. A public
scoped method must never accept a conflicting value and silently choose one.

Name validation contract

The SDK enforces the following rules before any transport call:

Field	Required	Allowed characters	Maximum length	Additional rule
projectId	Yes	A-Z, a-z, 0-9, _	80 characters	Must not contain reserved separator __
collectionName	Yes	A-Z, a-z, 0-9, _	80 characters	Must not contain reserved separator __
streamName	Yes	A-Z, a-z, 0-9, _	80 characters	No implicit default

Validation order:

1. Trim leading and trailing whitespace.
2. Reject an empty value.
3. Reject a value longer than 80 characters.
4. Reject characters outside [A-Za-z0-9_].
5. Reject __ in projectId or collectionName.
6. Encode the backend collection and reject it if the complete encoded value
   exceeds the backend's 80-character collection_name limit.

The effective composite constraint is:

projectId.length + 2 + collectionName.length <= 80

Although each public field has an individual 80-character limit, a project
and collection pair must also satisfy the backend collection limit.

Invalid developer input throws the existing ValidationFailed error before
network or file I/O. Error messages use the public field name and the failed
rule, for example:

projectId must contain only letters, digits, and underscore
collectionName must not contain the reserved separator "__"
projectId and collectionName must encode to at most 80 characters
streamName must be at most 80 characters

Validation must be locale-independent and centralized. It must not be
reimplemented separately in upload, search, or index code.

Internal API mapping

The backend currently supports only two hierarchy levels. The SDK synthesizes
the project level by prefixing the collection:

SDK
  projectId      = "food_app"
  collectionName = "user_123"
  streamName     = "favorites"

Backend/API
  collection_name = "food_app__user_123"
  stream_name     = "favorites"

Conceptually:

projectId + "__" + collectionName  -> backend collection
streamName                          -> backend sub-collection/stream

The existing Android implementation calls the backend collection slot
groupName in several models and resources. The facade maps the encoded
collection to that slot until the lower-level API is renamed:

public collectionName
        |
        v
encode(projectId, collectionName)
        |
        v
existing groupName / wire group_name / backend collection_name

This terminology adapter is internal. New public facade signatures and KDoc
must not expose groupName.

The separator is exactly two ASCII underscores, __. Because the SDK rejects
that sequence in projectId and collectionName, encoding is collision-free:

encode("a", "b_c")  = "a__b_c"
encode("a_b", "c")  = "a_b__c"

Callers never construct or parse a composite name. One internal value object
or helper owns all behavior:

internal data class ContentScope(
    val projectId: String,
    val collectionName: String,
    val streamName: String,
) {
    val backendCollectionName: String
}

The helper is the sole source of truth for trimming, validation, encoding, and
project-prefix decoding.

Operation mapping

Every operation that identifies content must use the same scope:

Operation	Backend collection value	Backend stream value
Video/file upload	Encoded project + collection	Scope stream
Metadata upload	Encoded project + collection	Scope stream
Search	Encoded project + collection	Scope stream
Add assets	Encoded project + collection	Scope stream
Update asset description/tags	Encoded project + collection	Scope stream
Create index	Encoded project + collection	Scope stream
List index jobs	Encoded project + collection filter	Stream filter when supported
Delete index	Encoded project + collection	Existing index-version fields
Delete collection	Encoded project + collection	Not sent because the backend deletes the whole collection

deleteCollection(...) is collection-wide even though it is called from a
VModalScope. Its KDoc and confirmation result must explicitly say that all
streams in collectionName are affected. It must retain the existing
dryRun/confirm behavior.

Listing and decoding contract

VModalProject.listCollections() delegates to the existing collection-list
operation and returns only collections belonging to the configured project.

For project food_app:

1. Build the exact prefix food_app__.
2. Ignore backend collection names that do not start with that exact prefix.
3. Strip the prefix exactly once.
4. Validate the decoded collection name using the public collection rules.
5. Return the logical names, such as global and user_123.
6. Preserve backend order and remove duplicate logical names by keeping the
   first occurrence.

The public result must never contain food_app__user_123. A malformed encoded
name belonging to the current project is a response-contract failure and must
raise MalformedResponse; it must not be returned as a partially decoded
name.

Listing a project's streams is not part of the first surface unless the
backend provides a reliable stream-list contract. Do not infer streams from
unrelated search or index responses.

Reference use cases

1. Global search index

A search application has one central index containing all searchable assets:

val search = VModal.configure(
    projectId = "video_search",
    apiKey = apiKey,
).scope(
    collectionName = "global",
    streamName = "uploads",
)

search.upload(video)
search.search("red bicycle near a bridge")

Backend collection: video_search__global

2. Private index per end user

Each app user has an isolated searchable index:

val personal = VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
).scope(
    collectionName = "user_$endUserId",
    streamName = "personal_videos",
)

personal.upload(video)
personal.search("pasta recipe")

For endUserId = "123", the backend collection is
food_app__user_123.

The end-user identifier is an application concern expressed through
collectionName; it is not a mandatory SDK concept. The application must
normalize an external end-user identifier to the allowed character set before
creating the scope.

3. Multiple streams for one user

One user collection can separate assets by source or purpose:

val app = VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
)

val camera = app.scope("user_123", "camera")
val favorites = app.scope("user_123", "favorites")
val uploads = app.scope("user_123", "uploads")

All three scopes use backend collection food_app__user_123, with different
stream_name values.

4. Product catalog

A commerce app can organize indexes by business domain rather than end user:

val catalog = VModal.configure(
    projectId = "shopping_app",
    apiKey = apiKey,
).scope(
    collectionName = "product_catalog",
    streamName = "merchant_uploads",
)

Backend collection: shopping_app__product_catalog

5. Multiple developer projects

The same developer can configure separate projects for different apps:

val foodApp = VModal.configure("food_app", foodAppApiKey)
val shoppingApp = VModal.configure("shopping_app", shoppingAppApiKey)

Their logical collection names may be identical without colliding because
projectId is part of the backend collection name.

Authentication and configuration

apiKey configures bearer authentication through the existing SDK
configuration and provider mechanism. It does not become a content hierarchy
field.

• projectId does not replace the authenticated account, tenant, or end-user
  identity.
• The SDK must not derive projectId from userId, tenantId, email, token
  claims, or API-key text.
• The SDK must not derive collectionName from the authenticated user.
• API-key rotation through the existing provider remains supported.
• Authentication errors remain existing typed SDK errors.
• Public facade errors and KDoc must not describe auth identity as the content
  collection owner.

Concurrency and lifecycle

VModalProject and VModalScope are immutable after construction.

• Each scope stores its own normalized names and encoded backend collection.
• Operations read only from that scope.
• Two scopes may run concurrently without changing each other's target.
• The facade owns no Android Context, CoroutineScope, lifecycle, worker, or
  global mutable selection.
• uploadEvents(...) remains a cold flow: each collection starts one upload.
• Coroutine cancellation and typed error behavior remain identical to the
  current coroutine facade.
• The underlying configured transport may be shared when it is already safe to
  share.

Error behavior

The facade reuses the existing public error hierarchy.

Condition	Error
Invalid project, collection, or stream input	ValidationFailed
Invalid composite length	ValidationFailed
Authentication failure	Existing AuthError or ApiError behavior
Backend/API failure	Existing typed ApiError behavior
Invalid encoded listing response	MalformedResponse
Coroutine cancellation	Unchanged CancellationException

Errors from an operation should include public scope terminology when adding
context. Do not rewrite or hide a useful underlying status code, request ID,
or typed error.

Backward compatibility and deprecation

The new facade is additive.

Phase 1:

• Add VModal, VModalProject, VModalScope, scoped option models, and the
  internal mapping helper.
• Keep all existing Client, blocking resource, coroutine resource, request,
  and upload APIs working.
• Document VModal as the preferred entry point for new Android apps.

Phase 2, only after operation parity:

• Deprecate developer-facing overloads that require repeated groupName,
  collectionName, subCollectionName, or streamName values.
• Deprecation messages point to VModal.configure(...).scope(...).
• Keep Client available for advanced operations not yet represented by the
  facade.

Phase 3:

• Remove deprecated APIs only in a future major version and only after a
  separately approved compatibility review.

Example migration:

// Existing
client.coroutines().searches.searchVideo(
    queryText = "pasta recipe",
    groupName = "food_app__user_123",
    streamName = "personal_videos",
)

// Preferred
VModal.configure(
    projectId = "food_app",
    apiKey = apiKey,
).scope(
    collectionName = "user_123",
    streamName = "personal_videos",
).search("pasta recipe")

No automatic migration should interpret an existing unprefixed groupName as
a project or collection. Existing stored names require an explicit application
migration decision.

Implementation locations

Expected production changes:

• src/main/kotlin/com/vmodal/sdk/ — add the facade, immutable scope, scoped
  option models, and internal mapping helper.
• src/main/kotlin/com/vmodal/sdk/CoroutineClient.kt — reuse or minimally
  extend coroutine delegates needed by the facade.
• src/main/kotlin/com/vmodal/sdk/Models.kt — add only scoped public models
  that cannot safely reuse existing backend-oriented models.
• src/main/kotlin/com/vmodal/sdk/CollectionUploads.kt and
  CoroutineUploads.kt — delegate upload and progress behavior without
  duplicating the upload engine.
• docs/ and generated SDK reference inputs — document the facade and
  migration after implementation.

Tests should follow the Android module's existing Kotlin regression style and
cover the public facade without real network calls by using injected
transports.

Test cases

Validation

• Accept minimum valid names such as a.
• Accept letters, digits, and single underscores.
• Trim leading and trailing whitespace before storing a name.
• Reject blank names.
• Reject hyphens, spaces inside a name, dots, slashes, Unicode letters, and
  other characters outside [A-Za-z0-9_].
• Reject names longer than 80 characters.
• Reject __ in projectId and collectionName.
• Allow __ in streamName, because it is not part of the composite encoding.
• Reject a project/collection pair whose encoded backend name exceeds 80
  characters.
• Prove all validation failures occur before transport invocation.

Mapping

• Map food_app, user_123, favorites to backend collection
  food_app__user_123 and stream favorites.
• Verify upload, upload progress, metadata, search, add-assets, update, create
  index, job listing, delete index, and delete collection use the same encoded
  collection.
• Verify no scoped public option can override collection or stream.
• Verify two concurrent scopes keep independent backend values.

Listing

• Strip only the configured project's exact prefix.
• Exclude collections from other projects.
• Preserve order and remove duplicate decoded names.
• Reject malformed names carrying the current project's prefix.
• Never return an encoded composite name publicly.

Compatibility

• Existing Client blocking and coroutine tests continue to pass unchanged.
• Existing upload progress, cancellation, retry, and typed-error behavior is
  unchanged.
• New facade examples compile.
• API compatibility checks record the additive public declarations.

Behavioral expectations

• projectId is required when configuring the facade.
• collectionName and streamName are required when creating a scope.
• No operation silently changes or defaults a stream.
• Values are trimmed and validated consistently.
• One internal helper constructs and decodes backend collection names.
• Upload, indexing, search, listing, update, and deletion use the same mapping.
• Public errors and documentation use project/collection/stream terminology.
• Authentication identity remains separate from content organization.
• Multiple scopes and users can operate safely at the same time.
• Existing APIs have an additive migration and major-version deprecation path.

Critical invariants

1. ContentScope is the source of truth for normalized public names and the
   derived backend collection name.
2. The backend composite is derived data and is never accepted from a facade
   caller.
3. A scoped operation cannot accept a second collection or stream value.
4. Authentication identity never determines content organization implicitly.
5. Existing lower-level clients are delegates; the facade must not duplicate
   route, transport, retry, upload, or response parsing logic.
6. No mutable global or singleton collection selection is introduced.

Acceptance criteria

• The public API is agreed for project, collection, and stream selection.
• VModal.configure(...) returns an immutable project client.
• scope(collectionName, streamName) returns an immutable operation scope.
• projectId + collectionName maps deterministically to backend
  collection_name.
• streamName maps to the backend stream/sub-collection level.
• Callers never build or parse projectId__collectionName.
• Global-index, per-user-index, multi-stream, catalog, and multi-project
  use cases are covered.
• Allowed characters, lengths, trimming, composite limits, and separator
  collisions are documented and tested.
• Invalid names raise ValidationFailed before transport.
• Upload, indexing, search, listing, update, and deletion use one mapping.
• Listing removes the project prefix and never leaks composite names.
• Authentication identity and content organization remain separate.
• Concurrent scopes cannot change each other's selection.
• Existing Client APIs continue to work.
• A backward-compatibility and deprecation plan is approved before
  implementation.