primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.10

package/dist/src/commands/collections.js

@@ -7,7 +7,9 @@ import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
 import { normalizeCliListEnvelope, wholeListEnvelope, } from "../lib/paginate.js";
 import { resolveOwnerUserId } from "../lib/resolve-owner.js";
-import { COLLECTION_EXPORT_FILENAME, COLLECTION_EXPORT_VERSION, duplicateNameSources, emptyImportSummary, grantDisposition, grantUpdateLine, groupTargetsByName, importExitCode, planCollection, readCollectionExportFile, serverReason, } from "../lib/collection-export.js";
+import { parseCustodianOrExit } from "../lib/custodian.js";
+import { parseCollectionPrincipal, parseCollectionRole } from "../lib/collection-principal.js";
+import { COLLECTION_EXPORT_FILENAME, COLLECTION_EXPORT_VERSION, duplicateNameSources, emptyImportSummary, grantDisposition, grantUpdateLine, sameGrantGroup, groupTargetsByName, importExitCode, planCollection, readCollectionExportFile, rowCustodian, custodianUserId, permissionForRole, serverReason, } from "../lib/collection-export.js";
 export function registerCollectionsCommands(program) {
     const collections = program
         .command("collections")
@@ -18,12 +20,14 @@ Examples:
   $ primitive collections create "Sprint 12"
   $ primitive collections create "Sprint 12" --owner user@example.com
   $ primitive collections get <collection-id>
+  $ primitive collections list --custodian user:<user-id>
+  $ primitive collections transfer <collection-id> user:<user-id>
   $ primitive collections documents list <collection-id>
   $ primitive collections documents add <collection-id> <document-id>
-  $ primitive collections access <collection-id>
-  $ primitive collections share <collection-id> --group team/engineering --permission read-write
   $ primitive collections members list <collection-id>
-  $ primitive collections members add <collection-id> <user-id> --permission reader
+  $ primitive collections members add <collection-id> <user-id> --role contributor
+  $ primitive collections members add <collection-id> group:<group-id> --role viewer
+  $ primitive collections members set-role <collection-id> <user-id> editor
   $ primitive collections for-document <document-id>
 `);
     // List collections
@@ -34,18 +38,26 @@ Examples:
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
         .option("--all", "List every collection in the app (admin-only). Default is collections you're a direct member of.")
+        .option("--custodian <custodian>", 'Only this custodian\'s collections: "app" or "user:<user-id>" (needs an admin token)')
         .addOption(pageLimitOption())
         .addOption(pageCursorOption())
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const limit = parsePageLimit(options.limit);
+        const custodian = options.custodian === undefined ? undefined : parseCustodianOrExit(options.custodian, "--custodian");
+        if (custodian && options.all) {
+            error("--custodian and --all are alternatives; pass one.");
+            process.exit(1);
+        }
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
             const params = { limit, cursor: options.cursor };
-            const page = normalizeCliListEnvelope(options.all
-                ? await client.listAllCollections(resolvedAppId, params)
-                : await client.listCollections(resolvedAppId, params));
+            const page = normalizeCliListEnvelope(custodian
+                ? await client.listCollectionsByCustodian(resolvedAppId, custodian, params)
+                : options.all
+                    ? await client.listAllCollections(resolvedAppId, params)
+                    : await client.listCollections(resolvedAppId, params));
             const list = page.items;
             if (options.json) {
                 json(page);
@@ -63,7 +75,10 @@ Examples:
                 { header: "CREATED", key: "createdAt", format: formatDate },
             ];
             // `permission` is only returned by the default list() endpoint
-            if (!options.all) {
+            if (custodian) {
+                columns.splice(2, 0, { header: "CUSTODIAN", key: "custodian" });
+            }
+            else if (!options.all) {
                 columns.splice(4, 0, { header: "PERMISSION", key: "permission", format: (v) => v || "—" });
             }
             console.log(formatTable(list, columns));
@@ -82,25 +97,21 @@ Examples:
     // Create collection
     collections
         .command("create")
-        .description("Create a new collection")
+        .description("Create a new collection, held by the caller or by --owner")
         .argument("<name>", "Collection name")
         .option("--description <description>", "Collection description")
-        .option("--initial-metadata <json>", "Create-time resource metadata as JSON, keyed by category name (issue #1420)")
+        .option("--initial-metadata <json>", "Create-time resource metadata as JSON, keyed by category name")
         .option("--app <app-id>", "App ID")
-        .option("--owner <userId-or-email>", "User ID or email to own the collection (super-admin or assigned-console-admin tokens only)")
+        .option("--owner <userId-or-email>", "The user who holds the collection (its custodian and owner); needs an admin token")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
-Ownership:
-  An app-user token — member, admin, or owner — always creates the collection
-  owned by the caller: the server ignores --owner for those tokens.
-  A super-admin token, or a console-admin token assigned to this app, acts
-  through an admin shadow app user — without --owner that shadow user owns the
-  collection, with --owner the named user does.
-  A console admin not assigned to this app has no access to the app at all.
-
-  The owner is the collection's creator, so under the default rules they — and
-  no other non-admin — can edit it, delete it, and manage its documents and
-  members.
+Custody:
+  Without --owner the caller holds the new collection: an app user's token
+  makes them its custodian and owner; a console admin's token gives the app
+  custody.
+  With --owner the collection is created through the admin API for that user,
+  who becomes its custodian and owner; this needs an admin token assigned to
+  the app.
 
   An email given to --owner is resolved to a user id before anything is
   created; a user who is not in the app fails the command without creating a
@@ -111,7 +122,7 @@ Ownership:
         const client = new ApiClient();
         // Resolve --owner to a userId through the one shared lookup (#2763),
         // before the create: an email nobody answers to must fail with nothing
-        // created, not leave a collection owned by the admin.
+        // created.
         let ownerUserId;
         if (options.owner) {
             try {
@@ -124,8 +135,6 @@ Ownership:
         }
         try {
             const data = { name };
-            if (ownerUserId)
-                data.createdBy = ownerUserId;
             if (options.description)
                 data.description = options.description;
             // Create-time per-category ResourceMetadata rows (issue #1420).
@@ -138,7 +147,9 @@ Ownership:
                     process.exit(1);
                 }
             }
-            const result = await client.createCollection(resolvedAppId, data);
+            const result = ownerUserId
+                ? await client.createCollectionAsAdmin(resolvedAppId, { ...data, custodian: `user:${ownerUserId}` })
+                : await client.createCollection(resolvedAppId, data);
             if (options.json) {
                 json(result);
                 return;
@@ -146,9 +157,8 @@ Ownership:
             success("Collection created.");
             keyValue("Collection ID", result.collectionId);
             keyValue("Name", result.name);
-            // Read back from the RESPONSE, not from --owner: whom the server
-            // credited is the answer, and for a non-admin token it is the caller.
-            keyValue("Owner", result.createdBy);
+            // Read back from the RESPONSE: who holds it is the server's answer.
+            keyValue("Custodian", result.custodian ?? "(none)");
             if (result.description)
                 keyValue("Description", result.description);
         }
@@ -184,6 +194,38 @@ Ownership:
             process.exit(1);
         }
     });
+    // Transfer collection
+    collections
+        .command("transfer")
+        .description("Transfer a collection to another user or to the app")
+        .argument("<collection-id>", "Collection ID")
+        .argument("<custodian>", '"user:<user-id>" (a member of the app) or "app"')
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .allowExcessArguments(false)
+        .addHelpText("after", `
+The custodian and the owner row move together: the new custodian holds the
+owner role, the previous owner stays as a manager (or, moving to the app,
+loses the owner row), and no other role changes.
+`)
+        .action(async (collectionId, custodianArg, options) => {
+        const to = parseCustodianOrExit(custodianArg, "custodian");
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.transferCollection(resolvedAppId, collectionId, to);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Collection ${collectionId} transferred.`);
+            printResult("Custodian", result.custodian);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Update collection
     collections
         .command("update")
@@ -259,130 +301,6 @@ Ownership:
             process.exit(1);
         }
     });
-    // ---- Access command ----
-    collections
-        .command("access")
-        .description("Combined view of the groups and members with access to a collection " +
-        "(members only: 'collections members list'; group grants: 'collections share'/'unshare')")
-        .argument("<collection-id>", "Collection ID")
-        .option("--app <app-id>", "App ID")
-        .option("--json", "Output as JSON")
-        .action(async (collectionId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.getCollectionAccess(resolvedAppId, collectionId);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            const groups = result.groups || [];
-            const members = result.members || [];
-            if (groups.length === 0 && members.length === 0) {
-                info("No groups or members have access to this collection.");
-                return;
-            }
-            if (groups.length > 0) {
-                console.log("\nGroups:");
-                console.log(formatTable(groups, [
-                    { header: "TYPE", key: "groupType" },
-                    { header: "ID", key: "groupId" },
-                    { header: "PERMISSION", key: "permission" },
-                    { header: "GRANTED", key: "grantedAt", format: formatDate },
-                ]));
-            }
-            if (members.length > 0) {
-                console.log("\nMembers:");
-                console.log(formatTable(members, [
-                    { header: "USER_ID", key: "userId", format: formatId },
-                    { header: "PERMISSION", key: "permission" },
-                ]));
-            }
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // ---- Share / unshare (group permissions) ----
-    collections
-        .command("share")
-        .description("Grant a group access to a collection")
-        .argument("<collection-id>", "Collection ID")
-        .requiredOption("--group <group>", "Group in format type/id (e.g. team/engineering)")
-        .requiredOption("--permission <permission>", "Permission level (reader or read-write)")
-        .option("--app <app-id>", "App ID")
-        .option("--json", "Output as JSON")
-        .action(async (collectionId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        const parts = options.group.split("/");
-        if (parts.length !== 2) {
-            error("Group must be in format type/id (e.g. team/engineering).");
-            process.exit(1);
-        }
-        const [groupType, groupId] = parts;
-        try {
-            const result = await client.grantCollectionGroupPermission(resolvedAppId, collectionId, {
-                groupType,
-                groupId,
-                permission: options.permission,
-            });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Granted ${options.permission} access to ${groupType}/${groupId} on collection.`);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    collections
-        .command("unshare")
-        .description("Revoke a group's access to a collection")
-        .argument("<collection-id>", "Collection ID")
-        .requiredOption("--group <group>", "Group in format type/id (e.g. team/engineering)")
-        .option("--app <app-id>", "App ID")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .option("--json", "Output as JSON")
-        .action(async (collectionId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const parts = options.group.split("/");
-        if (parts.length !== 2) {
-            error("Group must be in format type/id (e.g. team/engineering).");
-            process.exit(1);
-        }
-        const [groupType, groupId] = parts;
-        if (!options.yes) {
-            let confirm;
-            try {
-                confirm = await confirmPrompt(`Revoke ${groupType}/${groupId} access to collection ${collectionId}?`);
-            }
-            catch (err) {
-                error(err.message);
-                process.exit(1);
-            }
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            await client.revokeCollectionGroupPermission(resolvedAppId, collectionId, groupType, groupId);
-            if (options.json) {
-                json({ success: true, collectionId, groupType, groupId });
-                return;
-            }
-            success(`Revoked ${groupType}/${groupId} access from collection.`);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // ---- Documents subcommand group ----
     const documents = collections
         .command("documents")
@@ -526,18 +444,17 @@ Ownership:
         }
     });
     // ---- Members subcommand group ----
+    //
+    // The one home for who holds a role on a collection: users and groups,
+    // addressed as principals (`<user-id>`, `group:<group-id>`). Writes go
+    // through the admin API, as the console's do, so the owner row can be
+    // restored and demoted from here.
     const members = collections
         .command("members")
-        .description("Manage individual user access to a collection");
-    // List members
-    //
-    // The server has no GET /collections/:id/members route — membership is read
-    // from the access endpoint, which returns groups and members together. This
-    // command is the members half of it, so reading "who is on this collection"
-    // doesn't require knowing about a command named for neither (#2764).
+        .description("Manage a collection's members — users and groups — and their roles");
     members
         .command("list")
-        .description("List users with direct access to a collection")
+        .description("List a collection's members, users and groups, with their roles")
         .argument("<collection-id>", "Collection ID")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
@@ -545,21 +462,20 @@ Ownership:
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.getCollectionAccess(resolvedAppId, collectionId);
-            const list = result.members ?? [];
+            const { items } = await client.listCollectionMembers(resolvedAppId, collectionId);
             if (options.json) {
-                // The members half of the access payload, in the one list envelope
-                // (#3646) — the same shape `groups members list` prints (#2764).
-                json(wholeListEnvelope(list));
+                // The whole membership, in the one list envelope (#3646).
+                json(wholeListEnvelope(items));
                 return;
             }
-            if (list.length === 0) {
-                info("No members have direct access to this collection. Groups may still have access — see 'collections access'.");
+            if (items.length === 0) {
+                info("No user or group holds a role on this collection.");
                 return;
             }
-            console.log(formatTable(list, [
-                { header: "USER_ID", key: "userId", format: formatId },
-                { header: "PERMISSION", key: "permission" },
+            console.log(formatTable(items, [
+                { header: "PRINCIPAL", key: "principal" },
+                { header: "ROLE", key: "role" },
+                { header: "ADDED", key: "addedAt", format: formatDate },
             ]));
         }
         catch (err) {
@@ -567,49 +483,97 @@ Ownership:
             process.exit(1);
         }
     });
-    // Add member
     members
         .command("add")
-        .description("Add a user to a collection")
+        .description("Give a user or a group a role on a collection")
         .argument("<collection-id>", "Collection ID")
-        .argument("<user-id>", "User ID")
-        .requiredOption("--permission <permission>", "Permission level (reader or read-write)")
+        .argument("<principal>", "A user id, or group:<group-id>")
+        .requiredOption("--role <role>", "viewer, contributor, editor or manager (a group holds up to manager); owner restores the custodian's owner row")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
-        .action(async (collectionId, userId, options) => {
+        .allowExcessArguments(false)
+        .action(async (collectionId, principalArg, options) => {
+        let principal;
+        let role;
+        try {
+            principal = parseCollectionPrincipal(principalArg);
+            role = parseCollectionRole(options.role);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.addCollectionMember(resolvedAppId, collectionId, {
-                userId,
-                permission: options.permission,
-            });
+            const result = await client.addCollectionMember(resolvedAppId, collectionId, { ...principal, role: role });
             if (options.json) {
                 json(result);
                 return;
             }
-            success(`User ${userId} added to collection with ${options.permission} access.`);
+            success(`${principalArg} holds ${result.role ?? role} on collection ${collectionId}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    members
+        .command("set-role")
+        .description("Change a collection member's role")
+        .argument("<collection-id>", "Collection ID")
+        .argument("<principal>", "A user id, or group:<group-id>")
+        .argument("<role>", "owner, manager, editor, contributor or viewer")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .allowExcessArguments(false)
+        .action(async (collectionId, principalArg, roleArg, options) => {
+        let role;
+        try {
+            parseCollectionPrincipal(principalArg);
+            role = parseCollectionRole(roleArg);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.setCollectionMemberRole(resolvedAppId, collectionId, principalArg, role);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`${principalArg} is now ${result.role ?? role} on collection ${collectionId}.`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Remove member
     members
         .command("remove")
-        .description("Remove a user from a collection")
+        .description("Remove a user or a group from a collection")
         .argument("<collection-id>", "Collection ID")
-        .argument("<user-id>", "User ID")
+        .argument("<principal>", "A user id, or group:<group-id>")
         .option("--app <app-id>", "App ID")
         .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
-        .action(async (collectionId, userId, options) => {
+        .allowExcessArguments(false)
+        .action(async (collectionId, principalArg, options) => {
+        try {
+            parseCollectionPrincipal(principalArg);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
             let confirm;
             try {
-                confirm = await confirmPrompt(`Remove user ${userId} from collection ${collectionId}?`);
+                confirm = await confirmPrompt(`Remove ${principalArg} from collection ${collectionId}?`);
             }
             catch (err) {
                 error(err.message);
@@ -622,12 +586,12 @@ Ownership:
         }
         const client = new ApiClient();
         try {
-            await client.removeCollectionMember(resolvedAppId, collectionId, userId);
+            await client.removeCollectionMember(resolvedAppId, collectionId, principalArg);
             if (options.json) {
-                json({ success: true, collectionId, userId });
+                json({ success: true, collectionId, principal: principalArg });
                 return;
             }
-            success(`User ${userId} removed from collection.`);
+            success(`${principalArg} removed from collection.`);
         }
         catch (err) {
             error(err.message);
@@ -648,12 +612,13 @@ Ownership:
  * whole app. Owner and member identities travel as EMAILS wherever the server
  * can resolve one: users are app-scoped (`models.yaml`), so the same person is
  * a different userId in every app and a recorded source userId means nothing
- * in the target.
+ * in the target. Custody and roles travel as they are: `app` or the owner,
+ * and each member's and group's role.
  */
 function registerCollectionsExport(collections) {
     collections
         .command("export")
-        .description("Export every collection in an app (name, owner, members, documents, group grants)")
+        .description("Export every collection in an app (name, custodian, members and groups with roles, documents)")
         .option("--app <app-id>", "App ID")
         .option("--output <dir>", "Output directory", "./primitive-export")
         .option("--json", "Output as JSON")
@@ -665,6 +630,9 @@ that 'documents export-all' writes, so one directory is one app's migration.
 Import it with 'primitive collections import' AFTER 'documents import', which
 preserves document ids.
 
+The file records each collection's custodian (the app, or the user holding
+the owner row), its settings, and every member's and group's role.
+
 Owner and member identities are recorded as emails wherever the server can
 resolve one — users are app-scoped, so a source app's userId means nothing in
 the target. A userId with no resolvable email is recorded as-is and will only
@@ -750,30 +718,34 @@ async function exportCollections(client, appId, options) {
         const collectionId = row.collectionId;
         try {
             const documents = await readAllCollectionDocuments(client, appId, collectionId);
-            const access = await client.getCollectionAccess(appId, collectionId);
+            const roster = await client.listCollectionMembers(appId, collectionId);
             const members = [];
-            for (const m of access?.members ?? []) {
-                members.push({
-                    ...(await identity(m.userId)),
-                    permission: m.permission,
-                });
+            const groups = [];
+            for (const m of roster.items) {
+                // `permission` and `groupType` stay beside `role`: a CLI written
+                // before roles reads them, and a group written before the role model
+                // resolves only with its type.
+                const permission = m.permission ?? permissionForRole(m.role);
+                if (m.groupId) {
+                    // The server already leaves system groups out of the member list.
+                    groups.push({ groupType: m.groupType, groupId: m.groupId, permission, role: m.role });
+                }
+                else if (m.userId) {
+                    members.push({ ...(await identity(m.userId)), permission, role: m.role });
+                }
             }
-            const groups = (access?.groups ?? [])
-                // The server already filters system groups out of this response; a
-                // `_`-prefixed type could never be re-granted anyway (it is reserved).
-                .filter((g) => !String(g.groupType).startsWith("_"))
-                .map((g) => ({
-                groupType: g.groupType,
-                groupId: g.groupId,
-                permission: g.permission,
-            }));
+            // A row created before custody has none (null); its creator holds the
+            // owner row and is recorded as the owner.
+            const ownerUserId = custodianUserId(rowCustodian(row));
             exported.push({
                 collectionId,
                 name: row.name,
                 description: row.description ?? null,
                 collectionType: row.collectionType ?? null,
                 createdAt: row.createdAt ?? null,
-                owner: row.createdBy ? await identity(row.createdBy) : null,
+                custodian: typeof row.custodian === "string" && row.custodian ? row.custodian : null,
+                owner: ownerUserId ? await identity(ownerUserId) : null,
+                settings: row.settings ?? null,
                 documents,
                 members,
                 groups,
@@ -845,21 +817,34 @@ async function exportCollections(client, appId, options) {
  *      go first ON PURPOSE: `addDocument` materializes every existing grant
  *      onto a newly added document, so a fresh collection's access never
  *      depends on the grant's own fan-out over the document list (F4).
+ *
+ * A collection is created through the admin route with its custodian — the
+ * owner resolved by email, or the app — so the server writes the owner row;
+ * members and groups are then replayed by role through the admin member
+ * route (#4731).
  */
 function registerCollectionsImport(collections) {
     collections
         .command("import")
-        .description("Recreate collections from a collections.json export (owner, members, documents, group grants)")
+        .description("Recreate collections from a collections.json export (custodian, members and groups with roles, documents)")
         .argument("<path>", "Export directory holding collections.json, or the file itself")
         .option("--app <app-id>", "App ID")
-        .option("--owner <userId-or-email>", "Own every imported collection with this user, instead of the owner each one records")
+        .option("--owner <userId-or-email>", "Give every imported collection this user as custodian and owner, instead of the custodian each one records")
         .option("--overwrite", "Merge into a collection that already carries the same name")
         .option("--dry-run", "Show the plan and the problems without writing anything")
         .option("--json", "Output as JSON")
         .addHelpText("after", `
-For admin tokens. Assigning an owner is admin-only, so under an app-user token
-the server creates every collection owned by the caller and each one whose
-recorded owner is somebody else is reported as an 'owner' problem.
+Needs an admin token assigned to the app, checked before anything is read or
+written: each collection is created through the admin API with the custodian
+the file records — the app, or the owner, who holds the owner row — and
+members and groups are added at the role the file records, through the admin
+member routes. The custodian's own row follows the file too: a role below
+owner is replayed, and a newly created collection whose file records no row
+for its custodian has the owner row removed again. A member recorded as owner
+who is not the custodian (with --owner, the recorded owner) is reported as an
+'owner' problem and not imported. A file written before roles is read with
+reader as viewer and read-write as editor, and its owner's own read-write row
+as the owner row.
 
 Run 'primitive documents import' FIRST: it preserves document ids, which is
 what the collections file refers to.
@@ -869,16 +854,16 @@ app's userId means nothing here. A recorded userId is used only when the file
 came from this same app.
 
 Matching is by name. Without --overwrite a name already in the target is
-skipped; with it, the collection is merged — but only when its owner, type and
-context id match, since none of those can be changed after creation.
+skipped; with it, the collection is merged — but only when its custodian and
+type match, since neither can be changed by a merge.
 A name more than one collection in the target carries is ambiguous: that
 collection is refused as a 'collection' problem naming every matching id, with
 or without --overwrite, and nothing is written for it. A name repeated inside
 the file is refused for the second and later occurrences, since matching by
 name could not tell them apart.
 
-A group grant the target already holds at another level is UPDATED to the level
-the file records, and what the group can reach follows the change. On a
+A group or member the target already holds at another role is UPDATED to the
+role the file records, and what the group can reach follows the change. On a
 collection holding more than 200 documents the server refuses a collection-wide
 group change whole (COLLECTION_FANOUT_LIMIT): that is reported as a 'group'
 problem, and the rest of the collection is still merged.
@@ -905,8 +890,39 @@ Exit code 1 when any per-item problem was reported. A skip is not a problem.
 function isNotFound(err) {
     return err?.statusCode === 404;
 }
+/**
+ * The recorded type of a grant's group, sent beside its id: a group written
+ * before the role model carries no public id, and resolves only by its type.
+ */
+function groupTypeOf(grant) {
+    return grant.groupType ? { groupType: grant.groupType } : {};
+}
+/**
+ * The import's writes all go through the admin API, so an app user's token —
+ * the app owner's included — could apply only part of a file (a merge's
+ * documents through the app route, and nothing else). Refused before any read
+ * of the target app (E14). The probe is one row of an admin-API read on the
+ * app, behind the same app-assignment gate as the admin create.
+ */
+async function requireAdminAppAccess(client, appId) {
+    try {
+        await client.listGroupsByCustodian(appId, "app", { limit: 1 });
+    }
+    catch (err) {
+        const status = err?.statusCode;
+        if (status === 401 || status === 403 || status === 404) {
+            throw new Error(`collections import needs an admin token assigned to app ${appId}: it ` +
+                `creates collections and replays members through the admin API ` +
+                `(${serverReason(err)}). Log in as an admin of the app and re-run. ` +
+                `Nothing has been written.`);
+        }
+        throw new Error(`Checking admin access to app ${appId} failed: ${err?.message ?? err}. ` +
+            `Nothing has been written.`);
+    }
+}
 async function importCollections(client, appId, importPath, options) {
     const file = readCollectionExportFile(importPath);
+    await requireAdminAppAccess(client, appId);
     // A file exported before the platform removed collection `contextId` (#3926)
     // still carries it. Said once for the run, on stderr, and never sent: the
     // server refuses the key, and the binding belongs in a metadata category.
@@ -1033,7 +1049,9 @@ async function importCollections(client, appId, importPath, options) {
         };
         let ownerUserId = explicitOwnerUserId ?? null;
         let ownerReason;
-        if (!ownerUserId) {
+        // App custody needs no owner; `--owner` gives every collection one.
+        const appCustody = !explicitOwnerUserId && source.custodian === "app";
+        if (!ownerUserId && !appCustody) {
             try {
                 const resolved = await resolveIdentity(source.owner);
                 ownerUserId = resolved.userId;
@@ -1047,6 +1065,7 @@ async function importCollections(client, appId, importPath, options) {
         const row = planCollection(source, {
             ownerUserId,
             ownerReason,
+            appCustody,
             existing: matches.length === 1 ? matches[0] : null,
             ambiguousTargetIds: matches.length > 1 ? matches.map((m) => m.collectionId) : null,
             duplicateOfSourceId: duplicates.get(source.collectionId) ?? null,
@@ -1058,33 +1077,36 @@ async function importCollections(client, appId, importPath, options) {
             planned.push({ row, source, grants: [], members: [], documents: [] });
             continue;
         }
-        // What the target already grants, so a merge can compare levels.
+        // What the target already grants, so a merge can compare roles.
         let targetGrants = [];
         if (row.action === "merge" && row.targetCollectionId) {
             try {
-                const access = await client.getCollectionAccess(appId, row.targetCollectionId);
-                targetGrants = (access?.groups ?? []).map((g) => ({
-                    groupType: g.groupType,
-                    groupId: g.groupId,
-                    permission: g.permission,
+                const roster = await client.listCollectionMembers(appId, row.targetCollectionId);
+                targetGrants = roster.items
+                    .filter((m) => m.groupId)
+                    .map((m) => ({
+                    groupId: m.groupId,
+                    ...(m.groupType ? { groupType: m.groupType } : {}),
+                    role: m.role,
                 }));
             }
             catch (err) {
-                fatal(`the access of ${row.targetCollectionId}`, err);
+                fatal(`the members of ${row.targetCollectionId}`, err);
             }
         }
         const grants = [];
         for (const grant of source.groups ?? []) {
-            const label = `${grant.groupType}/${grant.groupId}`;
-            // The server reserves the `_` prefix for its own system groups; an
-            // export never writes one, and re-granting one is a 400.
-            if (String(grant.groupType).startsWith("_")) {
-                warn(`${source.name}: skipping the reserved group type ${grant.groupType} ` +
+            const label = `group:${grant.groupId}`;
+            // The server reserves the `_` group-type prefix for its own system
+            // groups; an export never writes one, and re-granting one is a 400. A
+            // group id may start with `_` (only the type is reserved).
+            if (String(grant.groupType ?? "").startsWith("_")) {
+                warn(`${source.name}: skipping the reserved group ${grant.groupType ? `type ${grant.groupType} ` : ""}` +
                     `(${label}); the server manages those itself.`);
                 continue;
             }
             try {
-                await client.getGroup(appId, grant.groupType, grant.groupId);
+                await client.getGroup(appId, grant.groupId, groupTypeOf(grant));
             }
             catch (err) {
                 if (isNotFound(err)) {
@@ -1094,14 +1116,16 @@ async function importCollections(client, appId, importPath, options) {
                 fatal(`group ${label}`, err);
             }
             const disposition = grantDisposition(grant, targetGrants);
-            const existing = targetGrants.find((g) => g.groupType === grant.groupType && g.groupId === grant.groupId);
+            const existing = targetGrants.find((g) => sameGrantGroup(g, grant));
             grants.push({
                 grant,
                 disposition,
-                ...(existing ? { existingPermission: existing.permission } : {}),
+                ...(existing ? { existingRole: existing.role } : {}),
             });
         }
+        const custodianUser = row.custodian ? custodianUserId(row.custodian) : null;
         const members = [];
+        let custodianRecorded = false;
         for (const member of source.members ?? []) {
             let resolved;
             try {
@@ -1115,8 +1139,32 @@ async function importCollections(client, appId, importPath, options) {
                 note("member", resolved.id, resolved.reason);
                 continue;
             }
-            members.push({ userId: resolved.userId, permission: member.permission });
+            if (resolved.userId === custodianUser) {
+                // The custodian's own row is replayed as the file records it: a role
+                // below owner demotes the owner row custody wrote, and on a merge an
+                // owner entry restores it. A create's owner entry is already written.
+                custodianRecorded = true;
+                if (row.action === "create" && member.role === "owner")
+                    continue;
+                members.push({ userId: resolved.userId, role: member.role });
+                continue;
+            }
+            if (member.role === "owner") {
+                // The owner row is the custodian's alone; anyone else recorded as
+                // owner is invalid data, reported rather than granted another role.
+                note("owner", resolved.id, `recorded as owner, but the owner row belongs to the custodian ` +
+                    `(${row.custodian}); not imported`);
+                continue;
+            }
+            members.push({ userId: resolved.userId, role: member.role });
         }
+        // A user custodian the file records no row for had it removed in the
+        // source; a create writes one, so it goes again. `--owner` names a new
+        // custodian the file cannot speak for, and a merge leaves rows it does not
+        // record alone.
+        const removeOwnerRowOf = row.action === "create" && custodianUser && !custodianRecorded && !explicitOwnerUserId
+            ? custodianUser
+            : undefined;
         const documents = [];
         for (const document of source.documents ?? []) {
             try {
@@ -1132,7 +1180,7 @@ async function importCollections(client, appId, importPath, options) {
             }
             documents.push(document.documentId);
         }
-        planned.push({ row, source, grants, members, documents });
+        planned.push({ row, source, grants, members, ...(removeOwnerRowOf ? { removeOwnerRowOf } : {}), documents });
     }
     // ── Apply phase ────────────────────────────────────────────────────────
     for (const entry of planned) {
@@ -1167,38 +1215,41 @@ async function importCollections(client, appId, importPath, options) {
                 summary.merged += 1;
                 info(`[dry-run] Would merge ${source.name} into ${row.targetCollectionId}`);
             }
-            for (const { grant, disposition, existingPermission } of entry.grants) {
+            for (const { grant, disposition, existingRole } of entry.grants) {
                 if (disposition === "already-applied")
                     continue;
-                const label = `${grant.groupType}/${grant.groupId}`;
+                const label = `group:${grant.groupId}`;
                 info(disposition === "update"
-                    ? `[dry-run] Would update ${grantUpdateLine(label, existingPermission, grant.permission)}`
-                    : `[dry-run] Would grant ${label} ${grant.permission}`);
+                    ? `[dry-run] Would update ${grantUpdateLine(label, existingRole, grant.role)}`
+                    : `[dry-run] Would grant ${label} ${grant.role}`);
                 summary.groupsGranted += 1;
             }
             summary.membersAdded += entry.members.length;
+            if (entry.removeOwnerRowOf) {
+                info(`[dry-run] Would remove the owner row of ${entry.removeOwnerRowOf} ` +
+                    `(the export records no membership for the custodian)`);
+            }
             summary.documentsAdded += entry.documents.length;
             continue;
         }
         let targetCollectionId = row.targetCollectionId;
         if (row.action === "create") {
             try {
-                const created = await client.createCollection(appId, {
+                const created = await client.createCollectionAsAdmin(appId, {
                     name: source.name,
                     ...(source.description ? { description: source.description } : {}),
                     ...(source.collectionType ? { collectionType: source.collectionType } : {}),
-                    createdBy: row.ownerUserId,
+                    custodian: row.custodian,
+                    ...(source.settings ? { settings: source.settings } : {}),
                 });
                 targetCollectionId = created.collectionId;
                 row.targetCollectionId = targetCollectionId;
                 summary.created += 1;
                 info(`Created ${source.name} as ${targetCollectionId}`);
-                // Whom the server CREDITED is the answer. A server predating #3641
-                // ignores the field, and so does any server for a non-admin token.
-                if (created.createdBy && created.createdBy !== row.ownerUserId) {
-                    note("owner", row.ownerUserId, `the server did not assign the owner (it credited ` +
-                        `${created.createdBy}); the token is not an admin one, or the ` +
-                        `server predates #3641`);
+                // The custodian the server RECORDED is the answer.
+                if (created.custodian && created.custodian !== row.custodian) {
+                    note("owner", row.custodian, `the server recorded ${created.custodian} as custodian, not ` +
+                        `${row.custodian}`);
                 }
             }
             catch (err) {
@@ -1210,21 +1261,21 @@ async function importCollections(client, appId, importPath, options) {
             summary.merged += 1;
             info(`Merged ${source.name} into ${targetCollectionId}`);
         }
-        for (const { grant, disposition, existingPermission } of entry.grants) {
+        for (const { grant, disposition, existingRole } of entry.grants) {
             if (disposition === "already-applied")
                 continue;
-            const label = `${grant.groupType}/${grant.groupId}`;
+            const label = `group:${grant.groupId}`;
             try {
-                await client.grantCollectionGroupPermission(appId, targetCollectionId, {
-                    groupType: grant.groupType,
+                await client.addCollectionMember(appId, targetCollectionId, {
                     groupId: grant.groupId,
-                    permission: grant.permission,
+                    ...groupTypeOf(grant),
+                    role: grant.role,
                 });
                 summary.groupsGranted += 1;
-                // A level change is worth saying out loud: it is the one grant write
+                // A role change is worth saying out loud: it is the one grant write
                 // that can take access away from people who already had it.
                 if (disposition === "update") {
-                    info(`Updated ${grantUpdateLine(label, existingPermission, grant.permission)}`);
+                    info(`Updated ${grantUpdateLine(label, existingRole, grant.role)}`);
                 }
             }
             catch (err) {
@@ -1235,10 +1286,9 @@ async function importCollections(client, appId, importPath, options) {
             try {
                 const result = await client.addCollectionMember(appId, targetCollectionId, {
                     userId: member.userId,
-                    permission: member.permission,
+                    role: member.role,
                 });
-                // `already_member` is the server saying it was already so — including
-                // the owner's own `_col-writer` enrolment, which every export records.
+                // `already_member` is the server saying it already held that role.
                 if (result?.status !== "already_member")
                     summary.membersAdded += 1;
             }
@@ -1246,6 +1296,16 @@ async function importCollections(client, appId, importPath, options) {
                 note("member", member.userId, serverReason(err));
             }
         }
+        if (entry.removeOwnerRowOf) {
+            try {
+                await client.removeCollectionMember(appId, targetCollectionId, entry.removeOwnerRowOf);
+                info(`Removed the owner row of ${entry.removeOwnerRowOf} from ${source.name}: ` +
+                    `the export records no membership for the custodian`);
+            }
+            catch (err) {
+                note("owner", entry.removeOwnerRowOf, serverReason(err));
+            }
+        }
         for (const documentId of entry.documents) {
             try {
                 await client.addCollectionDocument(appId, targetCollectionId, { documentId });