<!-- source: https://docs.dreamlake.ai/dev/notes/standalone-catalog-transfer @ 0.1.192 b2f973b1 -->
# Standalone catalog transfer

This implementation stage is not advertised as released until its owning API
admission flag is enabled after compatible readers replace the old fleet.
Standalone Artifact transfers use `artifact-metadata-v1`; they do not use the
legacy Project RTC checkpoint executor.

## Qualification on 2026-10-25

The source audit used workspace `1265f6eb` and the installed CLI `0.86.1`.
Artifact, Env/Scene, Annotation and Pipeline have independent metadata adapters;
this is not a statement that every resource instance or admission flag is ready.
The current regression candidate passes 32 real-Mongo tests, including overlapping
catalog edits versus acceptance, transaction interruption, exact request replay,
receipt-bound old links, share-token revocation and indexed historical lookup.
The three new catalog race tests each exercise four independently created
resources. A write either commits before transfer and survives it, or fails with
`LOST_AUTHORITY`; a new write under the current destination then succeeds.

| Profile | Qualified source scope | Still unsupported |
| --- | --- | --- |
| Artifact | Private personal source; source owner also destination member; stable ID/storage/share token/visit grants | Organization source, public visibility, ordinary Project filings |
| Env/Scene | Private personal source; source owner also destination member; stable ID/storage/share token and both URL families | Organization source, public visibility, ordinary Project filings |
| Annotation | Private personal source; source owner also destination member; stable ID/storage/schema and authenticated old reads | Organization source, public visibility, ordinary Project filings |
| Pipeline | Personal source; source owner remains destination member; code/history/runtime rows retain identity | Organization source and ordinary Project filings |
| AssetLibrary | Reader binding only; the generation protocol remains a separate unmerged candidate | Ownership admission and efficient immutable delta publication |

External grant mounts require their explicit reviewed disposition. Rejecting an
unsupported resource leaves ownership unchanged; it must never silently remove
filings, widen visibility or drop an audience. Organization-source support must
retain live membership and revocation through the shared receipt-bound audience
grant model and audited per-type readers and writers before its admission expands.

The production canary for each enabled profile must use a disposable resource:
create it privately in the personal source, record its stable catalog ID and
storage binding, save a transfer review, overlap an edit with recipient acceptance,
then read the old and new links and inspect exact completed replay. Artifact and
Scene additionally exercise the same share token before and after transfer and
after revocation. Remove the test resource through its current canonical owner
and verify it is absent; do not move a real user resource as a qualification test.
Annotation currently lacks first-class CLI creation/edit/deletion commands; use
the audited HTTP resource API for those steps, rather than inventing commands.
All four transfers use `dl ownership transfer TYPE ID` with `--dry-run
--out`, followed by `--confirm --request-file --accept-if-authorized --wait`.

## Ready Artifact profile

A live private Artifact can move from a personal namespace when its owner is
also an active member of the destination namespace. The Artifact must have no
Project filings, pending storage mutation, hidden upload reservation, destination
name collision, or invalid ownership history. Unsupported cases fail explicitly;
there is no destructive detach, clone/delete, or legacy fallback.

Mounts admitted by an [external mount grant](/api/external-mounts/) are not
Project filings for this check. Artifact, Scene and Annotation transfers list
each such grant in the preview and require an explicit `reissue` or `revoke`
disposition in `policy.externalMounts`; without one they fail with
`EXTERNAL_MOUNT_DISPOSITION_REQUIRED`.

The accepted request retains the catalog ID, canonical Artifact name, all
content versions, share token, share-visit access, and original object storage
bucket/prefix. No object payload or Note/RTC history is read or copied. A new
namespace-qualified location points at the same pinned storage location.
Old namespace links resolve only through the completed accepted request and
its exact ID/history/epoch/storage receipt; the alias grants no access by itself.
A replacement Artifact created under the old name takes precedence.

## Concurrency and recovery

Acceptance revalidates current authority, the access preview, destination name
availability, catalog storage admission, and source-owner destination membership.
Membership mutation shares the organization authority write parent. Catalog
storage mutation and transfer share the catalog row CAS; an uncertain external
storage effect remains blocked. A new share visit participates in that same row
fence, preventing it from recreating access under the obsolete owner.

The owner update, pinned storage binding, share-visit relocation, lease epoch,
completion event and durable receipt commit in one MongoDB transaction. There
is no durable preparing interval or RTC handoff. Interruption before commit
rolls everything back; a lost response is handled by replaying the original
idempotency key or reading its completed operation. Recipient acceptance is
required; cancellation/rejection remain available while pending.

## Remaining stages

AssetLibrary, ordinary retained Project filings, public visibility and
organization-source catalog audiences require their own proof-aware readers
and access guarantees. They are not enabled by adding names to a registry.
The shared organization audience grant model is owned by the standalone Memo
stage and will be reused rather than creating a competing store.

## Prepared Scene/Env stage

The next independent default-off executor is `env-metadata-v1`. Its initial
profile matches the Artifact constraints: private personal source, source owner
still a destination member, no external filings or pending storage mutations.
It retains the same EnvCatalog ID/name, share token, every content version and
the exact original S3 storage binding. Both `/scenes` and legacy `/envs` GET
families resolve old links through a completed receipt and then check current
namespace authority. A replacement source name takes precedence; a revoked
share token remains revoked. Writes always use the current canonical namespace.

This reader floor requires the additive nonunique `EnvCatalog` index `{name:1, 'ownershipHistory.sourceNamespaceId':1}`
before rollout, so a missing canonical name does not introduce an unindexed
catalog scan. The schema adds nullable ownership history; the scoped workflow provisions this index;
no blob migration, secondary content copy or RTC work is involved. Provision
through the existing reviewed infrastructure/deployment process, then prove the
compatible fleet drained before enabling new Scene transfers.

## Prepared Annotation stage

`annotation-metadata-v1` is a separate default-off executor with the same
private personal-source, destination-member and unfiled admission profile.
It preserves the AnnotationCatalog ID/name, schema metadata and original bucket
and storage prefix without reading or copying annotation payloads. Detail and
`presign-read` requests to old namespace URLs require completed receipt proof,
then current destination authority. Presign admission performs that lookup and
catalog writer fence inside its existing transaction; an alias cannot authorize
an obsolete namespace or bypass a pending storage mutation.

This stage adds nullable AnnotationEntry ownership history and the nonunique
`AnnotationCatalog {name:1, 'ownershipHistory.sourceNamespaceId':1}` index. Provision that index before reader rollout,
verify with `verifyAnnotationTransferReadIndex(db)`, drain incompatible readers,
then enable the separate admission gate. Resource bodies and issued presigned
URLs keep their existing storage/TTL behavior; existing URL lifetimes are not
silently shortened or described as instant revocation.

The shared organization-audience stage and proof-aware retained Project filings
remain separate work. AssetLibrary additionally needs a stable storage binding
and durable external storage admission before an ownership executor can safely
be enabled; its namespace-derived object paths are not portable today.

## Catalog API integration and rollout

The Env and Annotation singleton protocols expose the same ownership endpoints
as Artifact: `GET /namespaces/:namespace/ownership/resources/<type>/:id/transfer-plan`,
then the shared preview/create and recipient decision endpoints. `<type>` is
`env` or `annotation`. Their plans return the stable resource ID, `resourceName`,
review version and `transferMode: metadata`. Scene detail/list responses expose
that same catalog `id`; Annotation detail/list already expose it.

Capabilities advertise separate `envTransfer` and `annotationTransfer` objects,
each `{apiVersion: 1, enabled, metadataOnly: true}`. New requests and pending
acceptance require their own default-false deployment variables:
`OWNERSHIP_ENV_METADATA_TRANSFER_ENABLED` and
`OWNERSHIP_ANNOTATION_METADATA_TRANSFER_ENABLED`. Disabling admission preserves
exact same-key request replay, operation history, old-link readers, rejection
and cancellation. Startup verifies the required index before allowing each type.

Before deploying the reader floor, run the scoped
`catalog-metadata-read-indexes.yml` workflow from merged `main`, first with
`mode=plan`. Apply only its fresh source/database-bound `plan_hash` with
`confirmation=CREATE_TWO_CATALOG_METADATA_READ_INDEXES_ONLY` and `mode=apply`.
It creates only the missing nonunique normal `{name:1, 'ownershipHistory.sourceNamespaceId':1}` indexes on EnvCatalog
and AnnotationCatalog, accepts equivalent indexes, refuses conflicting index
options, and never drops indexes or changes resource records. The existing ECS
deployment identity and noncancelling deployment concurrency group are reused;
there is no new IAM or infrastructure launch. Apply rechecks the production
service's database fingerprint and ten-minute plan window.

Keep both admission variables false while the compatible-reader API deploys.
After index verification, replacement fleet/runtime proof, old-writer drain and
concurrent-work canaries, enable only the independently accepted resource type.
The presence of an endpoint or green CI alone is not live transfer acceptance.

## AssetLibrary reader compatibility floor

The prepared reader-only stage adds an optional AssetLibraryCatalog
`storagePrefix`. Missing values keep the existing namespace/name object path;
there is no object copy, migration, upload protocol change, transfer admission
or background job in this stage. A later generation writer can pin a unique
`libraries/catalog/<catalog-id>/generations/<session-id>` binding.

Manifest, file, thumbnail, vector and merged cross-library search readers all
honor the pinned bucket/prefix. Manifest/vector cache identities include the
catalog ID and physical binding, so a reused display name or revision counter
cannot return another catalog's cached content. Existing private/share checks
remain in force; a storage locator is never an access grant.

Ship this compatibility floor before the separately gated upload-session and
retired-generation cleanup protocol. Library ownership transfers remain
unsupported until the storage writer floor, compatible CLI, crash/reclaim tests
and access-preserving transfer proof are independently accepted.
