@inquir/compute 0.4.0 → 0.4.2

package/README.md

@@ -1,255 +1,257 @@
-# @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`); 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`);
+> 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/app-observability.d.ts

@@ -42,6 +42,54 @@ export declare function getAppResourceRecommendation(client: TransportClient, ap
  * Read-only.
  */
 export declare function describeApp(client: TransportClient, appId: string): Promise<AppDescribeResponse>;
+/** One replica of an application, the pod analog (docs/design/REPLICA_SELECTION.md). */
+export interface AppInstance {
+    /** `<app>-<replicaIndex>-<allocationId[0..8]>`: stable for one attempt, new for a replacement. */
+    name: string;
+    /** Null only for a legacy (pre-allocation) single container. */
+    allocationId: string | null;
+    releaseId: string;
+    production: boolean;
+    replicaIndex: number;
+    incarnation: number;
+    /** Earlier attempts of this slot in this release. */
+    restarts: number;
+    state: string;
+    /** Serving production traffic right now. */
+    ready: boolean;
+    console: 'available' | 'remote_unsupported' | 'unavailable';
+    runner: {
+        id: string;
+        provider: string;
+        region: string | null;
+    } | null;
+    createdAt: string;
+    startedAt: string | null;
+    readyAt: string | null;
+    failure: string | null;
+    usage: {
+        cpuUsedCores: number | null;
+        cpuPercent: number | null;
+        memoryWorkingSetBytes: number | null;
+        memoryPercent: number | null;
+        sampledAt: string;
+    } | null;
+    conditions: AppDescribeResponse['application']['conditions'];
+}
+export interface AppInstancesResponse {
+    applicationId: string;
+    productionReleaseId: string | null;
+    generatedAt: string;
+    instances: AppInstance[];
+}
+/** The application's replicas: name, state, runner, readiness, restarts, CPU/memory now. */
+export declare function listAppInstances(client: TransportClient, appId: string): Promise<AppInstancesResponse>;
+/**
+ * Resolve a replica selector the way the server does: exact allocation id,
+ * instance name (`...-<index>-<id8>`), bare replica index (the ready one
+ * first), or a unique allocation-id prefix of at least 8 characters.
+ */
+export declare function matchAppInstance(selector: string, instances: readonly AppInstance[]): AppInstance | null;
 /** HTTP gateway observations; private TCP traffic is not HTTP request telemetry. */
 export declare function getAppHttpMetrics(client: TransportClient, appId: string, range?: AppObservationRange): Promise<AppHttpMetricsResponse>;
 /** One descending timestamp/id page of persisted runtime logs (7-day retention). */

package/dist/app-observability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-observability.d.ts","sourceRoot":"","sources":["../src/app-observability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-observability.d.ts","sourceRoot":"","sources":["../src/app-observability.ts"],"names":[],"mappings":"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"}