ardent-cli-beta 0.1.0 → 0.1.1

package/README.md

@@ -72,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
@@ -136,8 +140,10 @@ 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. When no branch has that name and
 the argument is the ID of a deleted branch whose erasure is unconfirmed, as a

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, composeCredentialDelivery, CredentialIssueRefused, issuedConnectKey, 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,9 +11,12 @@ 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;
@@ -26,7 +29,7 @@ export async function connectToBranch(connection) {
         let failure;
         try {
             try {
-                const issued = await issueBranchCredential(token, branchID, requestID, sourceRole);
+                const issued = await issueBranchCredential(token, branchID, requestID, credential);
                 issuanceID = issued.issuanceID;
                 await rememberCredentialIssuance(recovery, issuanceID);
                 connectKey = issuedConnectKey(issued);
@@ -47,6 +50,9 @@ export async function connectToBranch(connection) {
                 throw error;
             }
             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.
@@ -74,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

@@ -4,10 +4,25 @@ export interface IssuedCredential {
     connectKey?: unknown;
     connectKeyRequired?: unknown;
 }
-interface DeliveredCredential {
+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;
 }
@@ -15,12 +30,20 @@ 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<IssuedCredential>;
+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', 'connect_key_unsupported']);
+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,15 +52,20 @@ 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.');
@@ -184,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/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;
+                    issuanceID = (await issueBranchCredential(token, branchID, requestID, recovery.credential)).issuanceID;
                 }
                 catch (error) {
                     // The API refuses a source role before it records an issuance and

package/oclif.manifest.json

@@ -908,5 +908,5 @@
       ]
     }
   },
-  "version": "0.1.0"
+  "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.1.0",
+  "version": "0.1.1",
   "description": "The Ardent command-line interface",
   "license": "Apache-2.0",
   "type": "module",