ardent-cli-beta 0.0.20 → 0.1.1

package/README.md

@@ -39,6 +39,12 @@ omitting it preserves unrestricted ingress. `--print` remains accepted. The cred
 after exit. This uses `branch connect --print`'s lifecycle and requires a control
 plane that issues credentials while branches start (`docs/DECISIONS.md` section 17).
 
+For tokenized credentials, the CLI receives the database token once, keeps it
+in memory while waiting for readiness, and composes the delivered URL template
+locally. A lost one-time token requires revoking and issuing another credential;
+recovery records contain only request and issuance metadata, never that token
+(`docs/DECISIONS.md` section 20).
+
 Use `branch create <name> --to-env` or `branch connect --to-env` to write
 `DATABASE_URL` to `.env` in the
 current directory instead of printing the URL. The selected `--driver` still
@@ -66,17 +72,21 @@ only the libpq form opens psql. Otherwise the credential stays out of arguments
 variables ... and redacts the username, API key and password from both `script` output
 streams". It does not stop a user from printing a credential
 deliberately through SQL or a shell escape. A mode-0600 recovery
-file holds only request and issuance IDs, and any source role name, until revocation succeeds, and the next `branch connect`
+file holds only request and issuance IDs, and the source role name or access profile its request named, until revocation succeeds, and the next `branch connect`
 attempts to revoke every abandoned issuance before requesting another. A forced process kill
 can leave a credential active until that recovery runs. Failed cleanup retains
 the file and names the issuance ID for manual revocation.
 
-[openapi.json](openapi.json) ships in the npm package. It is a documentation snapshot of the control-plane
-specification as of 2026-09-24, from Ardent's private source revision
-`c8510ab3e2422756a93e1df09acf994cf6bac34d`, and not proof of deployed
-compatibility. It predates the branch credential endpoints used by `branch connect`, and the
-branch wake, suspend and recover operations used by those commands, and connector
-deletion; the source specification documents wake, suspend and recover, and
+[openapi.json](openapi.json) ships in the npm package. Its base is the
+2026-09-24 control-plane documentation snapshot from Ardent's private source
+revision `c8510ab3e2422756a93e1df09acf994cf6bac34d`. The branch-creation
+description, accepted source-position fields, and seed-origin description were
+selectively updated from the reviewed control-plane specification at revision
+`32da7390a` for ARD-2378. The rest was not refreshed, and this file is not
+proof of deployed compatibility. It still lacks the branch credential endpoints
+used by `branch connect`, the branch wake, suspend and recover operations used by
+those commands, and connector deletion; the source specification documents
+wake, suspend and recover, and
 refreshing this snapshot from a merged revision that carries them is owed.
 Documenting the credential and connector-deletion endpoints in the source
 specification is also owed. To refresh it, replace it with the reviewed
@@ -130,10 +140,14 @@ report source cleanup residue; the delete command warns about it and status
 preserves its code in text and JSON. A failed or interrupted wait retains local
 context and names the status command before retrying.
 
-Creation uses the connector's latest published snapshot. If that snapshot is
-unavailable, creation fails without choosing an older one. Names are unique within
+Creation asks the API for a branch at its recent applied source position. The
+API uses a published mark covering that position or requests one on demand; an
+accepted operation waits for that mark before materialization. Without recent
+source progress, the API refuses creation. Names are unique within
 a connector while the branch is not deleted. `branch delete` sends the connector
-and name to the API, which resolves the target. `branch list` fetches current state
+and name to the API, which resolves the target. When no branch has that name and
+the argument is the ID of a deleted branch whose erasure is unconfirmed, as a
+refused `connector delete` names one, it retries that erasure. `branch list` fetches current state
 and marks the locally selected branch with `●` in its `Selected` column; `branch switch` changes local
 context. Create and delete follow the operation in an interactive terminal;
 creation also waits outside a terminal and with `--json` so it can return a usable

package/dist/branches/client.d.ts

@@ -15,6 +15,9 @@ export interface BranchOperation {
 export declare function listBranches(token: string, connectorID: string): Promise<Branch[]>;
 export declare function createBranch(token: string, connectorID: string, name: string, allowedCIDRs?: string[]): Promise<BranchOperation>;
 export declare function deleteBranch(token: string, connectorID: string, name: string): Promise<BranchOperation>;
+export declare function isBranchID(value: string): boolean;
+export declare function loadDeletedBranch(token: string, connectorID: string, id: string): Promise<Branch>;
+export declare function retryBranchErasure(token: string, branch: Branch): Promise<BranchOperation>;
 export type BranchLifecycleAction = 'wake' | 'suspend' | 'recover';
 export declare function transitionBranch(token: string, connectorID: string, name: string, action: BranchLifecycleAction): Promise<BranchOperation>;
 export declare function waitForBranchOperation(token: string, workflowID: string, onStatus?: (status: string) => void, failedReads?: 'stop' | 'retry'): Promise<void>;

package/dist/branches/client.js

@@ -23,6 +23,50 @@ export async function deleteBranch(token, connectorID, name) {
     validateOperation(result, connectorID, name);
     return result;
 }
+// A deleted branch whose erasure no node has confirmed is in no branch list
+// and unreachable by name, yet keeps its connector from being deleted; that
+// refusal names it by ID. These two calls resolve such an ID and retry its
+// erasure by ID. docs/DECISIONS.md section 19 says why only a DELETED branch.
+export function isBranchID(value) {
+    return /^branch_[0-9A-Za-z_-]+$/.test(value);
+}
+export async function loadDeletedBranch(token, connectorID, id) {
+    const missing = `No branch ${terminalText(id)} in the selected connector.`;
+    let branch;
+    try {
+        branch = await request(token, `/branches/${encodeURIComponent(id)}`);
+    }
+    catch (error) {
+        if (error instanceof APIError && error.status === 404)
+            throw new Error(missing, { cause: error });
+        throw error;
+    }
+    if (!isBranch(branch, connectorID) || branch.id !== id)
+        throw new Error(missing);
+    if (branch.state !== 'DELETED')
+        throw new Error(`Branch ${terminalText(id)} is not deleted. Delete it by its name, ${terminalText(JSON.stringify(branch.name))}.`);
+    return branch;
+}
+export async function retryBranchErasure(token, branch) {
+    let operation;
+    try {
+        // branch list omits a deleted branch and no CLI command reads one, so the
+        // refresh is the read loadDeletedBranch made.
+        operation = await requestDurableMutation(token, `/branches/${encodeURIComponent(branch.id)}`, { method: 'DELETE' }, `an authenticated GET /branches/${terminalText(encodeURIComponent(branch.id))}`);
+    }
+    catch (error) {
+        // This route refuses in plain text, so the API's reason does not reach here.
+        if (error instanceof APIError && error.status === 409) {
+            throw new Error(`The Ardent API refused to retry the erasure of branch ${terminalText(branch.id)}. An erasure still running can be retried once it fails, an hour after it was requested; otherwise report the branch ID to Ardent support.`, { cause: error });
+        }
+        throw error;
+    }
+    if (!operation || typeof operation.operation_id !== 'string' || !operation.operation_id ||
+        typeof operation.workflow_id !== 'string' || !operation.workflow_id) {
+        throw new Error(`The Ardent API accepted the erasure retry of branch ${terminalText(branch.id)} but returned no valid operation; completion is unknown and work may still be running.`);
+    }
+    return { branch, operation };
+}
 // The control plane addresses these transitions by branch ID, so the command
 // resolves the name in the selected connector first and acts on exactly that
 // branch. The response is the operation alone; the resolved branch is returned

package/dist/branches/connection.d.ts

@@ -1,3 +1,4 @@
+import { type Unadmitted } from './credentials.js';
 import { type Driver } from './drivers.js';
 export interface BranchConnection {
     configDir: string;
@@ -17,5 +18,6 @@ export interface PrintedConnection {
     issuance_id: string;
     driver: Driver;
     connection_string: string;
+    unadmitted?: Unadmitted;
 }
 export declare function connectToBranch(connection: BranchConnection): Promise<PrintedConnection | void>;

package/dist/branches/connection.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { acknowledgeBranchCredential, CredentialIssueRefused, issueBranchCredential, revokeBranchCredential, waitForBranchCredential } from './credentials.js';
+import { acknowledgeBranchCredential, ALL_SCHEMAS_PROFILE, composeCredentialDelivery, CredentialIssueRefused, describeUnadmitted, issuedConnectKey, issueBranchCredential, revokeBranchCredential, waitForBranchCredential } from './credentials.js';
 import { CLIENT_REQUIREMENTS, connectionString } from './drivers.js';
 import { connectionEnvironment, runPsql } from './psql.js';
 import { CredentialRecoveryCleanupError, forgetCredentialRecovery, openCredentialWitness, rememberCredentialIssuance, rememberCredentialRequest } from './recovery.js';
@@ -11,10 +11,14 @@ import { terminalText } from '../terminal.js';
 export async function connectToBranch(connection) {
     const { token, branchID, sourceRole, print, driver, say, warn } = connection;
     const requestID = randomUUID();
+    // Without a source role, branch connect asks for every in-scope schema, and
+    // never retries with another profile: a refusal tells the user to choose.
+    const credential = sourceRole === undefined ? { accessProfile: ALL_SCHEMAS_PROFILE } : { sourceRole };
     const witness = await openCredentialWitness(requestID);
     try {
-        const recovery = await rememberCredentialRequest(connection.configDir, branchID, token, witness.port, requestID, sourceRole);
+        const recovery = await rememberCredentialRequest(connection.configDir, branchID, token, witness.port, requestID, credential);
         let issuanceID;
+        let connectKey;
         let issueRefused = false;
         // Set once a printed credential's recovery record is gone: the
         // credential is the user's from then on, and nothing here revokes it.
@@ -25,7 +29,10 @@ export async function connectToBranch(connection) {
         let failure;
         try {
             try {
-                issuanceID = await issueBranchCredential(token, branchID, requestID, sourceRole);
+                const issued = await issueBranchCredential(token, branchID, requestID, credential);
+                issuanceID = issued.issuanceID;
+                await rememberCredentialIssuance(recovery, issuanceID);
+                connectKey = issuedConnectKey(issued);
             }
             catch (error) {
                 if (error instanceof CredentialIssueRefused) {
@@ -42,8 +49,10 @@ export async function connectToBranch(connection) {
                 }
                 throw error;
             }
-            await rememberCredentialIssuance(recovery, issuanceID);
-            const delivery = await deliverWhenServing(token, issuanceID, connection.serving);
+            const delivery = composeCredentialDelivery(await deliverWhenServing(token, issuanceID, connection.serving), connectKey);
+            const unadmitted = describeUnadmitted(delivery.unadmitted);
+            if (unadmitted)
+                say(unadmitted);
             if (print) {
                 // Checked before acknowledgement, so a form that would not verify
                 // the server is revoked, never handed over.
@@ -71,7 +80,7 @@ export async function connectToBranch(connection) {
                     say(`The ${driver} form needs, in your client:\n${CLIENT_REQUIREMENTS[driver].map((requirement) => `  - ${requirement}`).join('\n')}`);
                 }
                 if (connection.json)
-                    return { issuance_id: issuanceID, driver, connection_string: value };
+                    return { issuance_id: issuanceID, driver, connection_string: value, ...(delivery.unadmitted ? { unadmitted: delivery.unadmitted } : {}) };
                 connection.log(value);
                 return;
             }

package/dist/branches/credentials.d.ts

@@ -1,18 +1,49 @@
 import { type ConnectionStrings } from './drivers.js';
-interface DeliveredCredential {
+export interface IssuedCredential {
+    issuanceID: string;
+    connectKey?: unknown;
+    connectKeyRequired?: unknown;
+}
+export interface Unadmitted {
+    count: number;
+    overflow: boolean;
+    schemas?: {
+        schema: string;
+        reason: string;
+    }[];
+    objects?: {
+        object: string;
+        kind: string;
+        reason: string;
+    }[];
+}
+export interface DeliveredCredential {
     issuance_id: string;
     delivery_id: string;
+    access_profile?: string;
     uri: string;
+    unadmitted?: Unadmitted;
     connection_strings?: ConnectionStrings;
+    connect_key_required?: boolean;
 }
 export declare class CredentialIssueRefused extends Error {
     readonly code?: string | undefined;
     constructor(message: string, code?: string | undefined);
 }
+export declare const ALL_SCHEMAS_PROFILE = "all_schemas_read_write_v1";
+export declare const PUBLIC_READ_WRITE_PROFILE = "public_read_write_v1";
+export type AccessProfile = typeof ALL_SCHEMAS_PROFILE | typeof PUBLIC_READ_WRITE_PROFILE;
+export type CredentialRequest = {
+    sourceRole: string;
+} | {
+    accessProfile: AccessProfile;
+};
 export declare function validSourceRole(role: string): boolean;
 export declare function refusedBeforeIssuance(error: unknown): boolean;
-export declare function issueBranchCredential(token: string, branchID: string, requestID: string, sourceRole?: string): Promise<string>;
+export declare function issueBranchCredential(token: string, branchID: string, requestID: string, credential: CredentialRequest): Promise<IssuedCredential>;
+export declare function issuedConnectKey(issued: IssuedCredential): string | undefined;
+export declare function composeCredentialDelivery(delivered: DeliveredCredential, connectKey?: string): DeliveredCredential;
 export declare function waitForBranchCredential(token: string, issuanceID: string, stop?: AbortSignal, served?: Promise<void>): Promise<DeliveredCredential>;
+export declare function describeUnadmitted(unadmitted: Unadmitted | undefined): string | undefined;
 export declare function acknowledgeBranchCredential(token: string, issuanceID: string, deliveryID: string): Promise<void>;
 export declare function revokeBranchCredential(token: string, issuanceID: string): Promise<void>;
-export {};

package/dist/branches/credentials.js

@@ -11,7 +11,19 @@ export class CredentialIssueRefused extends Error {
 }
 // The issuance refusals that come before any issuance is recorded: a request
 // refused with one of these left nothing to revoke.
-const sourceRoleIssueRefusals = new Set(['invalid_source_role', 'source_role_unsupported', 'source_role_held', 'source_role_revocation_pending']);
+const issueRefusals = new Set(['invalid_source_role', 'source_role_unsupported', 'source_role_held', 'source_role_revocation_pending', 'connect_key_unsupported',
+    'all_schemas_read_write_unsupported', 'all_schemas_read_write_unowned']);
+// The access profile branch connect asks for without --role, and the one an
+// earlier release of this CLI asked for, which a recovery record naming no
+// profile replays.
+export const ALL_SCHEMAS_PROFILE = 'all_schemas_read_write_v1';
+export const PUBLIC_READ_WRITE_PROFILE = 'public_read_write_v1';
+// What branch connect says when the API refuses the profile it asks for. The
+// CLI never retries with another profile: the user chooses one.
+const profileRefusals = {
+    all_schemas_read_write_unsupported: 'This branch\'s environment runs an Ardent release that cannot issue a credential covering every schema. Upgrade the environment, or connect as a source role with --role (for example --role postgres).',
+    all_schemas_read_write_unowned: 'This branch was created without restoring its source\'s owners, so Ardent cannot tell which of its schemas belong to the database platform and will not issue a credential covering every schema. Connect as a source role with --role (for example --role postgres).',
+};
 // sourceRolePattern is the name the API accepts for a source role: an
 // unquoted lower-case PostgreSQL identifier that begins with neither pg_ nor
 // ardent. The CLI checks it before it records or sends anything, so a mistyped
@@ -21,7 +33,7 @@ export function validSourceRole(role) {
     return sourceRolePattern.test(role);
 }
 export function refusedBeforeIssuance(error) {
-    return error instanceof CredentialIssueRefused && error.code !== undefined && sourceRoleIssueRefusals.has(error.code);
+    return error instanceof CredentialIssueRefused && error.code !== undefined && issueRefusals.has(error.code);
 }
 function credentialPath(issuanceID) {
     return `/branch-credentials/${encodeURIComponent(issuanceID)}`;
@@ -40,20 +52,76 @@ function safeRequest(token, path, init) {
         throw new Error('Branch credential request failed. Check the API connection and try again.');
     });
 }
-// sourceRole, when given, asks for a fresh branch-only password on that
-// source role instead of an issued public read/write role. A replay of the same
-// request must name the same role.
-export async function issueBranchCredential(token, branchID, requestID, sourceRole) {
-    const body = sourceRole === undefined
-        ? { request_id: requestID, access_profile: 'public_read_write_v1' }
-        : { request_id: requestID, source_role: sourceRole };
+// A source role request asks for a fresh branch-only password on that source
+// role; any other asks for an issued role under the access profile it names.
+// A replay of the same request must name the same.
+export async function issueBranchCredential(token, branchID, requestID, credential) {
+    const body = 'sourceRole' in credential
+        ? { request_id: requestID, source_role: credential.sourceRole }
+        : { request_id: requestID, access_profile: credential.accessProfile };
     const result = await safeRequest(token, `/branches/${encodeURIComponent(branchID)}/credentials`, {
         method: 'POST', body: JSON.stringify(body),
+    }).catch((error) => {
+        if (error instanceof CredentialIssueRefused && error.code !== undefined && profileRefusals[error.code] !== undefined) {
+            throw new CredentialIssueRefused(`${profileRefusals[error.code]} (${error.code})`, error.code);
+        }
+        throw error;
     });
     if (!result || typeof result.issuance_id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(result.issuance_id) || result.status !== 'pending') {
         throw new Error('Ardent API returned an invalid branch credential issuance.');
     }
-    return result.issuance_id;
+    // Return the identity before checking the one-time secret, so the caller
+    // records and revokes an issuance even when its secret is absent or malformed.
+    return { issuanceID: result.issuance_id, connectKey: result.connect_key, connectKeyRequired: result.connect_key_required };
+}
+export function issuedConnectKey(issued) {
+    if (issued.connectKeyRequired === undefined || issued.connectKeyRequired === false) {
+        if (issued.connectKey !== undefined)
+            throw new Error('Ardent API returned an unexpected database token. Revoke this credential and issue another.');
+        return undefined;
+    }
+    if (issued.connectKeyRequired !== true || typeof issued.connectKey !== 'string' ||
+        !/^bck_[a-z2-7]{16}_[A-Za-z0-9_-]{43}$/.test(issued.connectKey) ||
+        Buffer.from(issued.connectKey.slice(21), 'base64url').toString('base64url') !== issued.connectKey.slice(21)) {
+        throw new Error('The one-time database token was not received. Revoke this credential and issue another; the token cannot be recovered.');
+    }
+    return issued.connectKey;
+}
+// Tokenized delivery contains templates, never a recoverable database token.
+// Compose only the username field locally; neither password nor query settings
+// are interpolated. The ordinary driver checks still validate TLS afterwards.
+export function composeCredentialDelivery(delivered, connectKey) {
+    if (delivered.connect_key_required !== undefined && typeof delivered.connect_key_required !== 'boolean') {
+        throw new Error('Ardent API returned an invalid database token requirement.');
+    }
+    if (Boolean(connectKey) !== (delivered.connect_key_required === true)) {
+        throw new Error('Ardent API returned an inconsistent database token requirement.');
+    }
+    if (!connectKey)
+        return delivered;
+    const compose = (value, jdbc = false) => {
+        try {
+            if (jdbc && !value.startsWith('jdbc:postgresql://'))
+                throw new Error();
+            const url = new URL(jdbc ? value.slice('jdbc:'.length) : value);
+            const user = jdbc ? url.searchParams.get('user') : decodeURIComponent(url.username);
+            if (!user || !/^[a-z_][a-z0-9_]{0,62}\+<connect-key>$/.test(user) || (jdbc && url.searchParams.getAll('user').length !== 1))
+                throw new Error();
+            const username = `${user.slice(0, -'<connect-key>'.length)}${connectKey}`;
+            if (jdbc)
+                url.searchParams.set('user', username);
+            else
+                url.username = username;
+            return `${jdbc ? 'jdbc:' : ''}${url.toString()}`;
+        }
+        catch {
+            throw new Error('Ardent API returned an invalid database token template.');
+        }
+    };
+    const uri = compose(delivered.uri);
+    const strings = delivered.connection_strings;
+    const connectionStrings = strings && Object.fromEntries(DRIVERS.map((driver) => [driver, compose(strings[driver], driver === 'jdbc')]));
+    return { ...delivered, uri, connection_strings: connectionStrings };
 }
 // stop, when given, ends the wait with its abort reason: a caller that learns
 // the branch failed has no delivery left to wait for. served, when given,
@@ -133,12 +201,47 @@ export async function waitForBranchCredential(token, issuanceID, stop, served) {
             DRIVERS.every((driver) => typeof strings[driver] === 'string' && strings[driver] !== '') &&
             strings.libpq === delivered.uri);
         if (delivered.issuance_id !== issuanceID || typeof delivered.delivery_id !== 'string' || !delivered.delivery_id ||
-            typeof delivered.uri !== 'string' || !delivered.uri || !stringsValid)
+            typeof delivered.uri !== 'string' || !delivered.uri || !stringsValid ||
+            (delivered.access_profile !== undefined && typeof delivered.access_profile !== 'string') ||
+            (delivered.unadmitted !== undefined && !validUnadmitted(delivered.unadmitted)))
             throw new Error('Ardent API returned an invalid branch credential delivery.');
         return delivered;
     }
     throw new Error('Timed out waiting for a branch credential. Check branch status before trying again.');
 }
+// validUnadmitted holds a delivered unadmitted list to its shape: a positive
+// count, an overflow flag, and lists of non-empty strings when present, which
+// together name no more than count.
+function validUnadmitted(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const list = value;
+    const strings = (entry, keys) => typeof entry === 'object' && entry !== null &&
+        keys.every((key) => typeof entry[key] === 'string' && entry[key] !== '');
+    const entries = (field, keys) => field === undefined || (Array.isArray(field) && field.every((entry) => strings(entry, keys)));
+    if (!Number.isSafeInteger(list.count) || list.count < 1 || typeof list.overflow !== 'boolean' ||
+        !entries(list.schemas, ['schema', 'reason']) || !entries(list.objects, ['object', 'kind', 'reason']))
+        return false;
+    const named = (list.schemas?.length ?? 0) + (list.objects?.length ?? 0);
+    return named <= list.count;
+}
+// describeUnadmitted is what branch connect says about a delivered
+// credential's unadmitted list, or undefined when it leaves nothing out.
+export function describeUnadmitted(unadmitted) {
+    if (!unadmitted)
+        return undefined;
+    const lines = [
+        ...(unadmitted.schemas ?? []).map((entry) => `  schema ${terminalText(entry.schema)}: ${terminalText(entry.reason)}`),
+        ...(unadmitted.objects ?? []).map((entry) => `  ${entry.kind === 'm' ? 'materialized view' : 'view'} ${terminalText(entry.object)}: ${terminalText(entry.reason)}`),
+    ];
+    const head = `This credential has no access to ${unadmitted.count} schema(s) or view(s) on the branch that it would otherwise cover`;
+    if (lines.length === 0) {
+        return unadmitted.overflow
+            ? `${head}; the list is too long to report by name.`
+            : `${head}; its node has not reported which yet. The branch's credential_unadmitted in the Ardent API names them once it has.`;
+    }
+    return `${head}:\n${lines.join('\n')}\nConnect with --role to reach them as a source role.`;
+}
 export async function acknowledgeBranchCredential(token, issuanceID, deliveryID) {
     const deadline = Date.now() + 30_000;
     while (true) {

package/dist/branches/psql.js

@@ -26,7 +26,8 @@ export function connectionEnvironment(uri) {
     }
     const parameters = [...url.searchParams.entries()];
     const controls = /[\u0000-\u001f\u007f]/;
-    // A terminating environment's username is <role>+<api key>, which its node
+    // A terminating environment's username is <role>+<database token> (or a
+    // legacy API key), which its node
     // proxy splits; a passthrough environment's is the role alone, because no
     // proxy is there to split it. Either way neither half may be empty.
     const [role, ...apiKey] = user.split('+');
@@ -80,7 +81,7 @@ export async function checkPsql() {
     });
 }
 export async function runPsql(connection) {
-    // The API key is embedded in PGUSER. Neither the URI nor PGUSER reaches argv.
+    // The database token or legacy API key is in PGUSER. Neither it nor the URI reaches argv.
     const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('PG')));
     await new Promise((resolve, reject) => {
         const child = spawn('script', terminalCommand(['-X', '-v', 'PROMPT1=ardent=> ', '-v', 'PROMPT2=ardent-> ', '-v', 'PROMPT3=ardent>> ']), {

package/dist/branches/recovery.d.ts

@@ -1,9 +1,10 @@
+import { type CredentialRequest } from './credentials.js';
 export interface CredentialRecovery {
     file: string;
     branchID: string;
     requestID: string;
     issuanceID?: string;
-    sourceRole?: string;
+    credential: CredentialRequest;
 }
 export declare class CredentialRecoveryCleanupError extends Error {
     readonly stage: 'remove' | 'sync';
@@ -13,7 +14,7 @@ export declare function openCredentialWitness(requestID: string): Promise<{
     port: number;
     close: () => Promise<void>;
 }>;
-export declare function rememberCredentialRequest(directory: string, branchID: string, token: string, port: number, requestID: string, sourceRole?: string): Promise<CredentialRecovery>;
+export declare function rememberCredentialRequest(directory: string, branchID: string, token: string, port: number, requestID: string, credential: CredentialRequest): Promise<CredentialRecovery>;
 export declare function rememberCredentialIssuance(recovery: CredentialRecovery, issuanceID: string): Promise<void>;
 export declare function forgetCredentialRecovery(recovery: CredentialRecovery): Promise<void>;
 export declare function recoverBranchCredentials(directory: string, token: string): Promise<number>;

package/dist/branches/recovery.js

@@ -3,7 +3,11 @@ import { link, open, readFile, readdir, rename, unlink, writeFile } from 'node:f
 import { createConnection, createServer } from 'node:net';
 import { dirname, join } from 'node:path';
 import { API_URL } from '../api/client.js';
-import { issueBranchCredential, refusedBeforeIssuance, revokeBranchCredential, validSourceRole } from './credentials.js';
+import { ALL_SCHEMAS_PROFILE, issueBranchCredential, PUBLIC_READ_WRITE_PROFILE, refusedBeforeIssuance, revokeBranchCredential, validSourceRole } from './credentials.js';
+// recordedRequest is the record's fields for what a request named.
+function recordedRequest(credential) {
+    return 'sourceRole' in credential ? { source_role: credential.sourceRole } : { access_profile: credential.accessProfile };
+}
 export class CredentialRecoveryCleanupError extends Error {
     stage;
     constructor(stage, cause) {
@@ -103,14 +107,14 @@ async function writeRecord(file, record, replace) {
         });
     }
 }
-export async function rememberCredentialRequest(directory, branchID, token, port, requestID, sourceRole) {
+export async function rememberCredentialRequest(directory, branchID, token, port, requestID, credential) {
     const file = recoveryPath(directory, branchID, token, port, requestID);
-    await writeRecord(file, { request_id: requestID, ...(sourceRole === undefined ? {} : { source_role: sourceRole }) }, false);
-    return { file, branchID, requestID, sourceRole };
+    await writeRecord(file, { request_id: requestID, ...recordedRequest(credential) }, false);
+    return { file, branchID, requestID, credential };
 }
 export async function rememberCredentialIssuance(recovery, issuanceID) {
     recovery.issuanceID = issuanceID;
-    await writeRecord(recovery.file, { request_id: recovery.requestID, issuance_id: issuanceID, ...(recovery.sourceRole === undefined ? {} : { source_role: recovery.sourceRole }) }, true);
+    await writeRecord(recovery.file, { request_id: recovery.requestID, issuance_id: issuanceID, ...recordedRequest(recovery.credential) }, true);
 }
 // forgetCredentialRecovery removes a record and syncs its directory. A record
 // already removed, by an earlier attempt whose sync failed, is removed; the
@@ -165,7 +169,8 @@ export async function recoverBranchCredentials(directory, token) {
         }
         if (!record || typeof record !== 'object' || record.request_id !== requestID ||
             (record.issuance_id !== undefined && (typeof record.issuance_id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(record.issuance_id))) ||
-            (record.source_role !== undefined && (typeof record.source_role !== 'string' || !validSourceRole(record.source_role)))) {
+            (record.source_role !== undefined && (typeof record.source_role !== 'string' || !validSourceRole(record.source_role))) ||
+            (record.access_profile !== undefined && (record.source_role !== undefined || (record.access_profile !== ALL_SCHEMAS_PROFILE && record.access_profile !== PUBLIC_READ_WRITE_PROFILE)))) {
             failures.push(`Invalid branch credential recovery file ${name}.`);
             continue;
         }
@@ -180,12 +185,13 @@ export async function recoverBranchCredentials(directory, token) {
             failures.push(`Branch credential ${record.issuance_id ?? `request ${requestID}`} has a ${state === 'live' ? 'running session' : 'session whose state is unknown'}; finish or resolve that session before connecting again.`);
             continue;
         }
-        const recovery = { file, branchID, requestID, issuanceID: record.issuance_id, sourceRole: record.source_role };
+        const credential = record.source_role !== undefined ? { sourceRole: record.source_role } : { accessProfile: record.access_profile ?? PUBLIC_READ_WRITE_PROFILE };
+        const recovery = { file, branchID, requestID, issuanceID: record.issuance_id, credential };
         try {
             if (!recovery.issuanceID) {
                 let issuanceID;
                 try {
-                    issuanceID = await issueBranchCredential(token, branchID, requestID, recovery.sourceRole);
+                    issuanceID = (await issueBranchCredential(token, branchID, requestID, recovery.credential)).issuanceID;
                 }
                 catch (error) {
                     // The API refuses a source role before it records an issuance and

package/dist/commands/branch/delete.js

@@ -1,11 +1,12 @@
 import { Args, ux } from '@oclif/core';
+import { APIError } from '../../api/client.js';
 import { ArdentCommand } from '../../command.js';
-import { branchName, deleteBranch, waitForBranchOperation } from '../../branches/client.js';
+import { branchName, deleteBranch, isBranchID, loadDeletedBranch, retryBranchErasure, waitForBranchOperation } from '../../branches/client.js';
 import { replaceBranchCache } from '../../branches/context.js';
 import { requireConnector } from '../../connectors/context.js';
 import { terminalText } from '../../terminal.js';
 export default class BranchDelete extends ArdentCommand {
-    static args = { name: Args.string({ description: 'Branch name', required: true }) };
+    static args = { name: Args.string({ description: 'Branch name, or the ID of a deleted branch whose erasure to retry', required: true }) };
     static strict = false;
     static description = 'Delete a branch in the selected connector';
     static helpGroup = 'Branches';
@@ -20,7 +21,25 @@ export default class BranchDelete extends ArdentCommand {
         else if (!this.jsonEnabled())
             this.log(`Deleting branch ${target}...`);
         try {
-            const result = await deleteBranch(session.token, session.selectedConnector.id, name);
+            let result;
+            try {
+                result = await deleteBranch(session.token, session.selectedConnector.id, name);
+            }
+            catch (error) {
+                // A name that matches no branch may be the ID of a deleted branch
+                // whose erasure is unconfirmed (retryBranchErasure).
+                if (!(error instanceof APIError && error.status === 404 && error.code === 'branch_not_found' && isBranchID(name)))
+                    throw error;
+                const branch = await loadDeletedBranch(session.token, session.selectedConnector.id, name);
+                const retry = `Retrying the erasure of deleted branch ${terminalText(branch.name)} (${terminalText(branch.id)}) in connector ${terminalText(session.selectedConnector.name)}`;
+                if (interactive) {
+                    ux.action.stop('no branch has that name');
+                    ux.action.start(retry);
+                }
+                else if (!this.jsonEnabled())
+                    this.log(`${retry}...`);
+                result = await retryBranchErasure(session.token, branch);
+            }
             if (interactive) {
                 await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { ux.action.status = status; });
                 await replaceBranchCache(this.config.configDir, session, (session.branches ?? []).filter(({ id }) => id !== result.branch.id));

package/oclif.manifest.json

@@ -239,7 +239,7 @@
       "aliases": [],
       "args": {
         "name": {
-          "description": "Branch name",
+          "description": "Branch name, or the ID of a deleted branch whose erasure to retry",
           "name": "name",
           "required": true
         }
@@ -908,5 +908,5 @@
       ]
     }
   },
-  "version": "0.0.20"
+  "version": "0.1.1"
 }

package/openapi.json

@@ -980,7 +980,7 @@
           "Branches"
         ],
         "summary": "Create branch",
-        "description": "Requires environments.update in the connector organization. Uses the newest published snapshot and refuses an unavailable newest snapshot with 409 snapshot_unavailable. Caller-selected snapshots and other unknown fields are rejected. Names are unique within a connector while the branch is not deleted. One JSON object, at most 16 KiB. Poll operation.workflow_id; acceptance is not completion.",
+        "description": "Requires environments.update in the connector organization and a recent applied source position, or returns 409 source_progress_unavailable. Uses a published mark covering that position or accepts a branch waiting for an on-demand mark. A wait that does not bind a covering mark within 30 minutes fails the workflow as snapshot_unavailable and erases the reservation. Caller-selected snapshots and other unknown fields are rejected. Names are unique within a connector while the branch is not deleted. One JSON object, at most 16 KiB. Poll operation.workflow_id; acceptance is not completion.",
         "requestBody": {
           "required": true,
           "content": {
@@ -1662,6 +1662,19 @@
           "updated_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "target_source_lsn": {
+            "type": "string",
+            "description": "Writer-applied source LSN accepted as the minimum covered position for this branch request. The materialized mark can have a later cutpoint. Absent on older branches."
+          },
+          "target_source_lineage_id": {
+            "type": "string",
+            "description": "Source lineage to which target_source_lsn belongs."
+          },
+          "target_source_observed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the authenticated node reported target_source_lsn."
           }
         }
       },
@@ -1901,7 +1914,7 @@
             "enum": [
               "seed_origin_v1"
             ],
-            "description": "Optional birth ownership restoration at the selected latest mark only. Returns 409 source_ownership_unavailable unless that mark matches a supported installation seed origin. Credentials retain public_read_write_v1."
+            "description": "Optional birth ownership restoration at a published mark covering the accepted source position. An explicit seed_origin_v1 request is refused when that position is beyond the seed origin or its declaration is unavailable. Other mark-dependent refusals may fail the accepted workflow before materialization. Credentials retain public_read_write_v1."
           }
         },
         "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ardent-cli-beta",
-  "version": "0.0.20",
+  "version": "0.1.1",
   "description": "The Ardent command-line interface",
   "license": "Apache-2.0",
   "type": "module",