@inquir/compute 0.4.1 → 0.4.4

package/README.md

@@ -1,256 +1,258 @@
-# @inquir/compute
-
-Workspace-first SDK for defining, discovering, generating, and running Inquir Compute assets.
-
-## Install
-
-Requires Node.js 22 or newer. Version 0.3 groups only long-lived container applications in projects; functions and pipelines remain separate assets.
-
-```bash
-npm install @inquir/compute zod@^3.23.8
-```
-
-> Release order: publish this SDK before the CLI that depends on it. CLI 0.4.0
-> needs SDK 0.4.0 (`isPromoteAccepted`, `getApplicationRollout`); the next CLI
-> needs SDK 0.4.1 (`listAppInstances`, `matchAppInstance`); see
-> `packages/cli/README.md`, "Publishing to npm".
-
-## What It Includes
-
-- `defineFunction()` and `definePipeline()` for code-first assets.
-- `loadConfig()` for `inquir.config.json`.
-- `discoverAssets()` for workspace asset scanning.
-- `generateCodegenArtifacts()` / `generateAndWriteCodegenArtifacts()` for typed client + `registry.json`.
-- `runLocally()` for local function execution/debug harness.
-- HTTP transport helpers (`createClient`, `invokeRemote`, deploy/list helpers).
-- Application project helpers (`listProjects`, `createProject`, `getProject`, `addProjectResource`) group long-lived containers: web services, APIs, databases, and workers. Project members use `kind: 'application'`; serverless functions are managed separately. `createApplication` accepts `projectId` (ID or slug); omitting it creates a project named after the application. Archiving a project also archives all its applications, including an application shared with another project. Removing a membership leaves it running. Project lifecycle actions require `projects:write` and `apps:promote`.
-
-## Pending synchronous invocations
-
-When the server admits a finite cold invocation, `invokeRemote()` submits once
-and follows only the authenticated invocation's `/resume` endpoint. Hot
-invocations keep their existing path. Save each handle from `onPending` if the
-caller must survive a restart:
-
-```ts
-import { invokeRemote, resumeRemoteInvocation, cancelRemoteInvocation,
-  RemoteInvocationObservationEndedError } from '@inquir/compute';
-
-try {
-  const result = await invokeRemote(client, 'my-function', event, {
-    timeoutMs: 120_000, signal, onPending: saveHandle,
-  });
-} catch (error) {
-  if (error instanceof RemoteInvocationObservationEndedError) {
-    saveHandle(error.pending); // PENDING/RECOVERY_HELD is not FAILED.
-    // Later: await resumeRemoteInvocation(client, error.pending);
-    // Explicit intent: await cancelRemoteInvocation(client, error.pending);
-  } else throw error;
-}
-```
-
-Abort/timeout stops observation, not execution. A cancellation receipt records
-intent, not a terminal outcome. If the initial POST reply is lost before a handle
-arrives, this adapter cannot recover an unknown server ID and never repeats that
-POST. Server admission remains independently gated; this client does not enable
-gateway, pipeline, durable or streaming finite execution.
-
-## Durable source commands
-
-Source execution uses an explicit operation instead of synchronous writable
-`/exec`. Save a lowercase UUID v4 before preparing, and atomically retain every
-record supplied by the callback in private storage. Records contain command/env
-secrets; they contain a credential hash rather than the credential itself.
-
-```ts
-import { createClient, prepareSourceCommand, restoreSourceCommand } from '@inquir/compute';
-
-const client = createClient({ baseUrl: apiUrl, apiKey, workspaceId });
-const operation = await prepareSourceCommand(client, {
-  function: 'my-function', requestId: savedUuid,
-  input: { command: 'npm install', timeoutMs: 60_000 },
-  retain: savePrivateRecordAtomically,
-});
-await operation.submit();                 // no automatic POST retry
-const state = await operation.status();   // GET only
-const publication = await operation.reconcile(); // explicit source publication
-// await operation.cancel();              // explicit cancellation intent
-const restored = await restoreSourceCommand(client, savedRecord, {
-  retain: savePrivateRecordAtomically,
-});                                      // no HTTP or submission
-```
-
-The retained API, credential hash, original workspace selector and resolved
-workspace/function IDs must match on restore. Later actions stay pinned to those
-IDs even if the client changes. A lost response keeps the same operation UUID;
-inspect status or explicitly retry the same action. Poll timeout/abort stops
-observation and does not cancel or publish. `EXITED` and `CANCEL_REQUESTED` do not
-prove physical removal or capacity release. A GET with `publication: null` does
-not prove that an earlier explicit publication never happened.
-
-Acceptance identity is retained before an action returns and after each poll
-response. If storage fails, further HTTP is blocked until the pending record is
-saved; `operation.persist()` retries storage without HTTP. Keep the updated
-record returned by `record()` for reloads. The server must enable the source
-command API after its activation gates; a 503 never falls back to writable exec.
-
-`result.logFailure` and `sourcePublicationState(outcome) === 'CAPTURE_FAILED'`
-mark unavailable log capture, preserving the real termination and exit code.
-Blank Base64 fields then mean unavailable capture rather than successful empty
-logs; workspace output is absent and cannot be published.
-
-## Concepts
-
-- **Function**: a single compute unit with typed input/output (Zod schemas). Created with `defineFunction()`. Discovered by file pattern, run locally via `runLocally()`, deployed and invoked remotely via the transport helpers.
-- **Pipeline**: a declarative DAG of functions created with `definePipeline()`. Included in the codegen registry; orchestration is handled server-side.
-- **Client**: the generated `client.ts` (from `generateAndWriteCodegenArtifacts()`). Provides a type-safe `createClient()` factory that wraps `invokeRemote()` with your asset's I/O types.
-- **Source of truth**: local files on disk. `registry.json` is derived — rebuild it with `generateAndWriteCodegenArtifacts()` whenever sources change.
-- **Local ↔ remote link**: remote functions store `linkedLocalName` (local asset name) and `sourceHash`. Compare hashes to detect drift.
-
-## Quick Example
-
-```ts
-import { defineFunction } from '@inquir/compute';
-import { z } from 'zod';
-
-export const hello = defineFunction(
-  {
-    name: 'hello',
-    input: z.object({ name: z.string().optional() }),
-    output: z.object({ message: z.string() }),
-  },
-  async (input) => ({ message: `Hello, ${input.name ?? 'world'}` })
-);
-```
-
-## Minimal Workspace Config
-
-Create `inquir.config.json`:
-
-```json
-{
-  "functionsDir": "inquir/functions",
-  "pipelinesDir": "inquir/pipelines",
-  "generatedDir": ".inquir/generated"
-}
-```
-
-## Discovery + Codegen
-
-```ts
-import { discoverAssets, generateAndWriteCodegenArtifacts, loadConfig } from '@inquir/compute';
-
-const config = loadConfig(process.cwd());
-const registry = await discoverAssets(config);
-await generateAndWriteCodegenArtifacts(config.absoluteGeneratedDir, registry);
-```
-
-This generates:
-
-- `.inquir/generated/client.ts`
-- `.inquir/generated/registry.json`
-
-`registry.json` includes stable metadata such as `name`, `kind`, `sourceHash`, and `assetRoot`.
-
-## Local Run
-
-```ts
-import { runLocally } from '@inquir/compute';
-
-const result = await runLocally(
-  {
-    kind: 'function',
-    name: 'hello',
-    filePath: '/abs/path/inquir/functions/hello/index.ts',
-    exportName: 'hello',
-  },
-  { name: 'World' }
-);
-```
-
-## Remote Invoke (Transport)
-
-```ts
-import { createClient, invokeRemote } from '@inquir/compute';
-
-const client = createClient({ baseUrl: 'http://localhost:3000', apiKey: process.env.INQUIR_API_KEY });
-const response = await invokeRemote(client, 'hello', { name: 'World' });
-```
-
-## Readonly published-release commands (scoped rollout)
-
-`prepareReleaseCommand` retains the caller's original UUID, workspace and command
-before the first HTTP submission. It uses the dedicated readonly release API;
-it does not invoke the writable source-command API or a function handler.
-
-```ts
-import { randomUUID } from 'node:crypto';
-import { prepareReleaseCommand, restoreReleaseCommand } from '@inquir/compute';
-
-const operation = await prepareReleaseCommand(client, {
-  functionId,
-  requestId: randomUUID(),
-  input: { command: 'cat package.json', timeoutMs: 60_000 },
-  retain: async record => saveCommandRecord(record), // Durable caller storage.
-});
-const first = await operation.submit(); // Submit once. Keep the retained record on a lost reply.
-const outcome = first.state === 'PENDING' || first.state === 'RECOVERY_HELD'
-  ? await restoreReleaseCommand(client, operation.record()).observe()
-  : first;
-```
-
-Observation resumes the same ID and never repeats the initial POST. An expired
-or aborted observer keeps that handle; `operation.cancel()` separately requests
-durable cancellation. Cancellation acknowledgement is an intent, while `REMOVED`
-is a validated terminal result after physical task/container cleanup. Scope or
-artifact uncertainty remains held rather than becoming a fabricated failure.
-`CANCELLED_WITHOUT_CONTAINER` separately proves an admitted reservation was
-cancelled and physically retired before CREATE; its `result` is `null` because
-no shell ran. `CANCELLED_BEFORE_ADMISSION` has no reservation to retire.
-
-This path is disabled by default. Each exact runtime image, readonly process,
-source/input mount, resource and network profile must receive native
-qualification before its scoped operator approval and rollout switches enable
-admission. The initial source tests do not constitute that qualification.
-
-## Application observability
-
-The SDK exposes resource and HTTP history, persisted runtime/HTTP logs and configurable app alerts. Every helper uses the client's credentials and workspace selector:
-
-```ts
-import {
-  createClient, getAppMetrics, getAppHttpMetrics, getAppLogHistory,
-  createAppAlertRule, updateAppAlertRule, listAppAlertIncidents,
-} from '@inquir/compute';
-
-const client = createClient({
-  baseUrl: 'https://inquir.org/api',
-  apiKey: process.env.INQUIR_TOKEN,
-  workspaceId: process.env.INQUIR_WORKSPACE,
-});
-const to = new Date().toISOString();
-const from = new Date(Date.now() - 60 * 60 * 1000).toISOString();
-const resources = await getAppMetrics(client, appId, { from, to });
-const http = await getAppHttpMetrics(client, appId, { from, to });
-const logs = await getAppLogHistory(client, appId, {
-  from, to, releaseId, allocationId, allocationFence: 4, level: 'error', limit: 100,
-});
-if (logs.nextCursor) {
-  const older = await getAppLogHistory(client, appId, {
-    from: logs.from, to: logs.to, releaseId, allocationId, allocationFence: 4,
-    level: 'error', limit: 100, cursor: logs.nextCursor,
-  });
-}
-
-const { rule } = await createAppAlertRule(client, appId, {
-  name: 'High RAM', enabled: true, metric: 'memory_percent',
-  threshold: 85, forSeconds: 120, recoveryThreshold: 65,
-  recoveryForSeconds: 60, noDataSeconds: 180, noData: 'alert', channels: [],
-});
-await updateAppAlertRule(client, appId, rule.id, { threshold: 90 });
-const { incidents } = await listAppAlertIncidents(client, appId, { limit: 25 });
-```
-
-`getAppHttpLogHistory`, `listAppAlertRules` and `deleteAppAlertRule` complete the API. Deletion disables the rule and resolves its active incidents; retained history is still available. Omit `channels` in a patch to preserve existing destinations, or pass an empty array to remove them. `webhook`/`slack` channel URLs are write-only; response types expose only channel id, type and configured status. Never log alert request inputs containing a secret URL.
-
-Resource and HTTP retention is 30 days; runtime logs are retained for 7 days. Runtime history is attributed to the exact release, allocation/fence, runner/epoch and container, including replaced containers. Paging is newest-first and requires an unchanged date window and filters. Resource history retains unavailable values as `null`; use `status`, `latestSampleAt` and `truncated` to detect stale or incomplete results. Network and block I/O rates are measured separately; block I/O is not volume space usage. CPU/RAM alert percentages are relative to enforced limits, and the continuous maximum across current production replicas determines threshold firing.
+# @inquir/compute
+
+Workspace-first SDK for defining, discovering, generating, and running Inquir Compute assets.
+
+## Install
+
+Requires Node.js 22 or newer. Version 0.3 groups only long-lived container applications in projects; functions and pipelines remain separate assets.
+
+```bash
+npm install @inquir/compute zod@^3.23.8
+```
+
+> Release order: publish this SDK before the CLI that depends on it. CLI 0.4.0
+> needs SDK 0.4.0 (`isPromoteAccepted`, `getApplicationRollout`); CLI 0.4.1
+> needs SDK 0.4.2 (`listAppInstances`, `matchAppInstance`, `createSourceArchive`,
+> `manifestBuildContext`, `getProductionReplacement`); the CLI after 0.4.1 needs SDK 0.4.3
+> (`addApplicationDomain(..., { acknowledgeWildcardRisks })`);
+> see `packages/cli/README.md`, "Publishing to npm".
+
+## What It Includes
+
+- `defineFunction()` and `definePipeline()` for code-first assets.
+- `loadConfig()` for `inquir.config.json`.
+- `discoverAssets()` for workspace asset scanning.
+- `generateCodegenArtifacts()` / `generateAndWriteCodegenArtifacts()` for typed client + `registry.json`.
+- `runLocally()` for local function execution/debug harness.
+- HTTP transport helpers (`createClient`, `invokeRemote`, deploy/list helpers).
+- Application project helpers (`listProjects`, `createProject`, `getProject`, `addProjectResource`) group long-lived containers: web services, APIs, databases, and workers. Project members use `kind: 'application'`; serverless functions are managed separately. `createApplication` accepts `projectId` (ID or slug); omitting it creates a project named after the application. Archiving a project also archives all its applications, including an application shared with another project. Removing a membership leaves it running. Project lifecycle actions require `projects:write` and `apps:promote`.
+
+## Pending synchronous invocations
+
+When the server admits a finite cold invocation, `invokeRemote()` submits once
+and follows only the authenticated invocation's `/resume` endpoint. Hot
+invocations keep their existing path. Save each handle from `onPending` if the
+caller must survive a restart:
+
+```ts
+import { invokeRemote, resumeRemoteInvocation, cancelRemoteInvocation,
+  RemoteInvocationObservationEndedError } from '@inquir/compute';
+
+try {
+  const result = await invokeRemote(client, 'my-function', event, {
+    timeoutMs: 120_000, signal, onPending: saveHandle,
+  });
+} catch (error) {
+  if (error instanceof RemoteInvocationObservationEndedError) {
+    saveHandle(error.pending); // PENDING/RECOVERY_HELD is not FAILED.
+    // Later: await resumeRemoteInvocation(client, error.pending);
+    // Explicit intent: await cancelRemoteInvocation(client, error.pending);
+  } else throw error;
+}
+```
+
+Abort/timeout stops observation, not execution. A cancellation receipt records
+intent, not a terminal outcome. If the initial POST reply is lost before a handle
+arrives, this adapter cannot recover an unknown server ID and never repeats that
+POST. Server admission remains independently gated; this client does not enable
+gateway, pipeline, durable or streaming finite execution.
+
+## Durable source commands
+
+Source execution uses an explicit operation instead of synchronous writable
+`/exec`. Save a lowercase UUID v4 before preparing, and atomically retain every
+record supplied by the callback in private storage. Records contain command/env
+secrets; they contain a credential hash rather than the credential itself.
+
+```ts
+import { createClient, prepareSourceCommand, restoreSourceCommand } from '@inquir/compute';
+
+const client = createClient({ baseUrl: apiUrl, apiKey, workspaceId });
+const operation = await prepareSourceCommand(client, {
+  function: 'my-function', requestId: savedUuid,
+  input: { command: 'npm install', timeoutMs: 60_000 },
+  retain: savePrivateRecordAtomically,
+});
+await operation.submit();                 // no automatic POST retry
+const state = await operation.status();   // GET only
+const publication = await operation.reconcile(); // explicit source publication
+// await operation.cancel();              // explicit cancellation intent
+const restored = await restoreSourceCommand(client, savedRecord, {
+  retain: savePrivateRecordAtomically,
+});                                      // no HTTP or submission
+```
+
+The retained API, credential hash, original workspace selector and resolved
+workspace/function IDs must match on restore. Later actions stay pinned to those
+IDs even if the client changes. A lost response keeps the same operation UUID;
+inspect status or explicitly retry the same action. Poll timeout/abort stops
+observation and does not cancel or publish. `EXITED` and `CANCEL_REQUESTED` do not
+prove physical removal or capacity release. A GET with `publication: null` does
+not prove that an earlier explicit publication never happened.
+
+Acceptance identity is retained before an action returns and after each poll
+response. If storage fails, further HTTP is blocked until the pending record is
+saved; `operation.persist()` retries storage without HTTP. Keep the updated
+record returned by `record()` for reloads. The server must enable the source
+command API after its activation gates; a 503 never falls back to writable exec.
+
+`result.logFailure` and `sourcePublicationState(outcome) === 'CAPTURE_FAILED'`
+mark unavailable log capture, preserving the real termination and exit code.
+Blank Base64 fields then mean unavailable capture rather than successful empty
+logs; workspace output is absent and cannot be published.
+
+## Concepts
+
+- **Function**: a single compute unit with typed input/output (Zod schemas). Created with `defineFunction()`. Discovered by file pattern, run locally via `runLocally()`, deployed and invoked remotely via the transport helpers.
+- **Pipeline**: a declarative DAG of functions created with `definePipeline()`. Included in the codegen registry; orchestration is handled server-side.
+- **Client**: the generated `client.ts` (from `generateAndWriteCodegenArtifacts()`). Provides a type-safe `createClient()` factory that wraps `invokeRemote()` with your asset's I/O types.
+- **Source of truth**: local files on disk. `registry.json` is derived — rebuild it with `generateAndWriteCodegenArtifacts()` whenever sources change.
+- **Local ↔ remote link**: remote functions store `linkedLocalName` (local asset name) and `sourceHash`. Compare hashes to detect drift.
+
+## Quick Example
+
+```ts
+import { defineFunction } from '@inquir/compute';
+import { z } from 'zod';
+
+export const hello = defineFunction(
+  {
+    name: 'hello',
+    input: z.object({ name: z.string().optional() }),
+    output: z.object({ message: z.string() }),
+  },
+  async (input) => ({ message: `Hello, ${input.name ?? 'world'}` })
+);
+```
+
+## Minimal Workspace Config
+
+Create `inquir.config.json`:
+
+```json
+{
+  "functionsDir": "inquir/functions",
+  "pipelinesDir": "inquir/pipelines",
+  "generatedDir": ".inquir/generated"
+}
+```
+
+## Discovery + Codegen
+
+```ts
+import { discoverAssets, generateAndWriteCodegenArtifacts, loadConfig } from '@inquir/compute';
+
+const config = loadConfig(process.cwd());
+const registry = await discoverAssets(config);
+await generateAndWriteCodegenArtifacts(config.absoluteGeneratedDir, registry);
+```
+
+This generates:
+
+- `.inquir/generated/client.ts`
+- `.inquir/generated/registry.json`
+
+`registry.json` includes stable metadata such as `name`, `kind`, `sourceHash`, and `assetRoot`.
+
+## Local Run
+
+```ts
+import { runLocally } from '@inquir/compute';
+
+const result = await runLocally(
+  {
+    kind: 'function',
+    name: 'hello',
+    filePath: '/abs/path/inquir/functions/hello/index.ts',
+    exportName: 'hello',
+  },
+  { name: 'World' }
+);
+```
+
+## Remote Invoke (Transport)
+
+```ts
+import { createClient, invokeRemote } from '@inquir/compute';
+
+const client = createClient({ baseUrl: 'http://localhost:3000', apiKey: process.env.INQUIR_API_KEY });
+const response = await invokeRemote(client, 'hello', { name: 'World' });
+```
+
+## Readonly published-release commands (scoped rollout)
+
+`prepareReleaseCommand` retains the caller's original UUID, workspace and command
+before the first HTTP submission. It uses the dedicated readonly release API;
+it does not invoke the writable source-command API or a function handler.
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { prepareReleaseCommand, restoreReleaseCommand } from '@inquir/compute';
+
+const operation = await prepareReleaseCommand(client, {
+  functionId,
+  requestId: randomUUID(),
+  input: { command: 'cat package.json', timeoutMs: 60_000 },
+  retain: async record => saveCommandRecord(record), // Durable caller storage.
+});
+const first = await operation.submit(); // Submit once. Keep the retained record on a lost reply.
+const outcome = first.state === 'PENDING' || first.state === 'RECOVERY_HELD'
+  ? await restoreReleaseCommand(client, operation.record()).observe()
+  : first;
+```
+
+Observation resumes the same ID and never repeats the initial POST. An expired
+or aborted observer keeps that handle; `operation.cancel()` separately requests
+durable cancellation. Cancellation acknowledgement is an intent, while `REMOVED`
+is a validated terminal result after physical task/container cleanup. Scope or
+artifact uncertainty remains held rather than becoming a fabricated failure.
+`CANCELLED_WITHOUT_CONTAINER` separately proves an admitted reservation was
+cancelled and physically retired before CREATE; its `result` is `null` because
+no shell ran. `CANCELLED_BEFORE_ADMISSION` has no reservation to retire.
+
+This path is disabled by default. Each exact runtime image, readonly process,
+source/input mount, resource and network profile must receive native
+qualification before its scoped operator approval and rollout switches enable
+admission. The initial source tests do not constitute that qualification.
+
+## Application observability
+
+The SDK exposes resource and HTTP history, persisted runtime/HTTP logs and configurable app alerts. Every helper uses the client's credentials and workspace selector:
+
+```ts
+import {
+  createClient, getAppMetrics, getAppHttpMetrics, getAppLogHistory,
+  createAppAlertRule, updateAppAlertRule, listAppAlertIncidents,
+} from '@inquir/compute';
+
+const client = createClient({
+  baseUrl: 'https://inquir.org/api',
+  apiKey: process.env.INQUIR_TOKEN,
+  workspaceId: process.env.INQUIR_WORKSPACE,
+});
+const to = new Date().toISOString();
+const from = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+const resources = await getAppMetrics(client, appId, { from, to });
+const http = await getAppHttpMetrics(client, appId, { from, to });
+const logs = await getAppLogHistory(client, appId, {
+  from, to, releaseId, allocationId, allocationFence: 4, level: 'error', limit: 100,
+});
+if (logs.nextCursor) {
+  const older = await getAppLogHistory(client, appId, {
+    from: logs.from, to: logs.to, releaseId, allocationId, allocationFence: 4,
+    level: 'error', limit: 100, cursor: logs.nextCursor,
+  });
+}
+
+const { rule } = await createAppAlertRule(client, appId, {
+  name: 'High RAM', enabled: true, metric: 'memory_percent',
+  threshold: 85, forSeconds: 120, recoveryThreshold: 65,
+  recoveryForSeconds: 60, noDataSeconds: 180, noData: 'alert', channels: [],
+});
+await updateAppAlertRule(client, appId, rule.id, { threshold: 90 });
+const { incidents } = await listAppAlertIncidents(client, appId, { limit: 25 });
+```
+
+`getAppHttpLogHistory`, `listAppAlertRules` and `deleteAppAlertRule` complete the API. Deletion disables the rule and resolves its active incidents; retained history is still available. Omit `channels` in a patch to preserve existing destinations, or pass an empty array to remove them. `webhook`/`slack` channel URLs are write-only; response types expose only channel id, type and configured status. Never log alert request inputs containing a secret URL.
+
+Resource and HTTP retention is 30 days; runtime logs are retained for 7 days. Runtime history is attributed to the exact release, allocation/fence, runner/epoch and container, including replaced containers. Paging is newest-first and requires an unchanged date window and filters. Resource history retains unavailable values as `null`; use `status`, `latestSampleAt` and `truncated` to detect stale or incomplete results. Network and block I/O rates are measured separately; block I/O is not volume space usage. CPU/RAM alert percentages are relative to enforced limits, and the continuous maximum across current production replicas determines threshold firing.

package/dist/apps.d.ts

@@ -394,6 +394,19 @@ export interface CreateReleaseResponse {
     previewUrl?: string;
     /** True when the release will take production by itself once healthy. */
     promoteOnReady?: boolean;
+    /**
+     * What the release took from inquir.yaml `services.web.env` (key names only):
+     * `applied` reached the release, `overridden` lost to an application variable
+     * of the same name, `ignored` means the platform has APPS_MANIFEST_ENV off.
+     * Absent when the build manifest declares no env, or from an older server.
+     */
+    manifestEnv?: {
+        applied: string[];
+        overridden: string[];
+        ignored?: true;
+    };
+    /** Advisory: e.g. a manifest env section that was not applied. */
+    warnings?: string[];
     statusUrl: string;
     logsUrl: string;
 }
@@ -582,6 +595,27 @@ export declare function listReleases(client: TransportClient, applicationId: str
     items: Release[];
 }>;
 export declare function getRelease(client: TransportClient, releaseId: string): Promise<Release>;
+/**
+ * A stop-first replacement of production (`apps redeploy`, `deploy
+ * --promote` of an eligible service): the current replica is stopped before
+ * the new release starts, so the new release reads PENDING throughout.
+ */
+export interface ProductionReplacementOperation {
+    id: string;
+    applicationId: string;
+    sourceReleaseId: string;
+    targetReleaseId: string;
+    /** RESERVED, STOPPING_SOURCE, STARTING_TARGET, ..., COMMITTED, ROLLED_BACK, CANCELLED. */
+    phase: string;
+    targetReplicas?: number;
+    createdAt: string;
+    phaseStartedAt: string;
+    lastError?: string;
+}
+/** The application's active production replacement, if any. */
+export declare function getProductionReplacement(client: TransportClient, applicationId: string): Promise<{
+    operation: ProductionReplacementOperation | null;
+}>;
 export interface PromoteResponse {
     previousReleaseId?: string;
     /** Absent for a service with no production hostname (pure TCP, or no suffix). */
@@ -686,7 +720,8 @@ export interface DomainVerificationInstructions {
 export interface AppDomain {
     hostname: string;
     kind: 'production' | 'preview';
-    url: string;
+    /** `https://{hostname}`; absent for a wildcard, which is a pattern, not an address. */
+    url?: string;
     activeReleaseId?: string;
     /** True for a tenant-bound hostname; false for the platform-generated one. */
     custom: boolean;
@@ -695,13 +730,25 @@ export interface AppDomain {
     verifiedAt?: string;
     /** Present while unverified. */
     verification?: DomainVerificationInstructions;
+    /**
+     * `*.example.com`: every one-label host under example.com (advanced, not
+     * recommended; the server needs APPS_WILDCARD_DOMAINS=on).
+     */
+    wildcard?: boolean;
+    /** Wildcards only: new certificates approved in the last 7 days, of the weekly limit. */
+    certificates?: {
+        issuedThisWeek: number;
+        weeklyLimit: number;
+    };
 }
 /**
  * Bind a custom hostname (always production). It starts unverified: publish
  * the returned TXT record and point the name at the platform, then call
  * `verifyApplicationDomain`.
  */
-export declare function addApplicationDomain(client: TransportClient, applicationId: string, hostname: string): Promise<AppDomain & {
+export declare function addApplicationDomain(client: TransportClient, applicationId: string, hostname: string, options?: {
+    acknowledgeWildcardRisks?: boolean;
+}): Promise<AppDomain & {
     verification: DomainVerificationInstructions;
 }>;
 export declare function verifyApplicationDomain(client: TransportClient, applicationId: string, hostname: string): Promise<AppDomain>;