@artblocks/abx-sdk 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/service.d.ts

@@ -11,13 +11,87 @@
 import type { Hex } from 'viem';
 import type { OpenSeaAttribute } from './traits.js';
 export declare const WELL_KNOWN_SERVICE_PATH = "/.well-known/abx-service";
-/** Versioned interface ids a service declares in its descriptor. Versions ride these ids
- *  (they track the `/v1` path prefix); the descriptor has no separate format version. */
+/**
+ * Versioned interface ids a service declares in its descriptor. Versions ride these ids
+ * (they track the `/v1` path prefix); the descriptor has no separate format version.
+ *
+ * There are exactly two, and they are **all-or-nothing**: declaring one asserts every route it names
+ * answers per the spec. The artifact-registry routes ride {@link CONTROL_PLANE_INTERFACE} rather
+ * than an id of their own — once referenced output is locator-only, accepting a registration is a
+ * database insert, so a separate capability flag would describe a distinction that doesn't exist.
+ * A service that won't take a given caller's artifacts refuses on the credential (`403`), which is
+ * the honest axis: interfaces describe wire grammar, tokens describe permission.
+ */
 export declare const TOKEN_API_INTERFACE = "abx-token-api/v1";
 export declare const CONTROL_PLANE_INTERFACE = "abx-control-plane/v1";
-export declare const EFFECTS_PUBLISH_INTERFACE = "abx-effects-publish/v1";
+/**
+ * Why this locator can't be accepted for a referenced artifact, or `null` if it passes.
+ *
+ * A locator is a **reachability** claim, not a durability one: it must resolve for a third party
+ * with no producer credentials and no private-network assumption. The protocol deliberately has
+ * **no preference among schemes** — `https://` (S3/R2, a producer's own public base, a chosen
+ * IPFS/Arweave gateway), `ipfs://` and `ar://` are peers, because derived output is re-creatable and
+ * a producer with an opinion about which gateway serves its content is making an operational call the
+ * protocol has no standing to override.
+ *
+ * Reachability can't be *proved* without fetching, and fetching a third-party URL while handling an
+ * authed write is byte custody through the back door plus an SSRF surface. So this checks the two
+ * things that are decidable from the string alone and are always wrong:
+ *   - a private / loopback host — resolvable only from the producer's own network;
+ *   - a presigned, expiring URL — resolvable now, dead later, which is the worst failure shape
+ *     (it passes every check at publish time and rots silently).
+ */
+export declare function locatorRejectionReason(locator: string): string | null;
+/**
+ * The indexing lifecycle a registration moves through, closed and provider-neutral
+ * (specs/self-host-toolkit/remote-services.md → The indexing lifecycle). One vocabulary for a
+ * managed provider and for your own node — the reference resolver stamps these too.
+ *
+ *   queued       registered + accepted; catch-up hasn't started
+ *   backfilling  actively catching up (initial sync or a forced replay); may already serve partial state
+ *   live         caught up to head; tracking head incrementally
+ *   stale        was live, now lagging (watcher behind, or transient RPC trouble) — still serving
+ *   failed       catch-up errored; carries `error`; will be retried
+ *
+ * Observability, never a source of truth: token resolution never consults it, and a project
+ * reconstructs from chain regardless.
+ */
+export type IndexStatus = 'queued' | 'backfilling' | 'live' | 'stale' | 'failed';
+/** Statuses a caller can stop waiting on — see {@link AbxServiceClient.awaitIndexed}. */
+export declare const TERMINAL_INDEX_STATUSES: readonly IndexStatus[];
+/**
+ * Why catch-up failed, as a closed machine class — never free-form prose the client must parse.
+ * Deliberately NOT extended with a reorg class: the protocol defines no reorg detection (the repair
+ * is the deterministic full replay), so no implementation could emit one honestly.
+ */
+export type IndexErrorClass = 
+/** The RPC didn't answer (down, timing out, network). Retryable — nothing is wrong with the add. */
+'rpc_unavailable'
+/** The RPC answered "too many requests". Retryable, slower — the usual cause of a long backfill. */
+ | 'rpc_rate_limited'
+/** The address doesn't look like an ABX contract on this chain. NOT emitted by the reference
+ *  (it indexes what its operator tells it); a provider that validates clone-ness SHOULD refuse
+ *  synchronously at register instead of accepting and failing here. */
+ | 'not_abx_contract'
+/** Anything else. Carries no detail — the service logs the cause. */
+ | 'internal';
+/** A catch-up failure as it crosses the wire: a machine class plus a short, CREDENTIAL-FREE hint.
+ *  Messages come from a closed set (see {@link classifyIndexError}) rather than from a scrubber, so
+ *  "no RPC URL can leak through here" is checkable by reading the code. */
+export interface IndexError {
+    class: IndexErrorClass;
+    message?: string;
+}
+/** Map a catch-up failure to its wire form. Sniffs the underlying error's shape only to CHOOSE a
+ *  class — nothing from it reaches the returned message. */
+export declare function classifyIndexError(err: unknown): IndexError;
 /** Machine error codes every conforming service uses — clients key off these, never off prose. */
 export type ServiceErrorCode = 'invalid_request' | 'unsupported_chain' | 'unauthorized' | 'forbidden' | 'not_registered' | 'disabled'
+/** 404 — this node serves no route at that path AT ALL (as opposed to a known route whose shape
+ *  was wrong, which is a 400 `invalid_request` carrying the correct template). The pair exists so
+ *  a client can tell "I built the wrong URL" from "this project isn't indexed here" from "this
+ *  node is older than the route I want" — a bare 404 conflates all three and reads as an outage. */
+ | 'unknown_route'
 /** 500 — an unexpected server-side failure. Never carries internal detail (it could embed the
  *  operator's own credentials); the node logs the cause. Retryable. */
  | 'internal_error';
@@ -75,8 +149,11 @@ export interface RegisterProjectBody {
     /** Force a full replay even on a re-POST. */
     full?: boolean;
 }
-export interface RegisterProjectResult {
+/** `200` — catch-up finished inside the request; the counts are facts. */
+export interface RegisterProjectSummary {
     ok: boolean;
+    /** Discriminator. Normalized from the HTTP status by {@link AbxServiceClient.registerProject}. */
+    accepted: false;
     mode: 'full' | 'incremental';
     elapsedMs: number;
     project: {
@@ -85,8 +162,30 @@ export interface RegisterProjectResult {
         eventCount: number;
         tokenCount: number;
         mintedCount: number;
+        /** Sum of every token's current supply — ERC-1155 editions only; absent for a 721 project. */
+        copies?: string;
+        status?: IndexStatus;
     };
 }
+/** `202` — the registration is durable and catch-up is deferred; there are no counts yet. Poll
+ *  {@link AbxServiceClient.projectStatus} (or {@link AbxServiceClient.awaitIndexed}) for progress. */
+export interface RegisterProjectAccepted {
+    ok: boolean;
+    accepted: true;
+    project: {
+        address: string;
+        name?: string | null;
+        status: IndexStatus;
+    };
+}
+/**
+ * `POST /v1/projects` answers in one of two shapes and **the HTTP status code is the discriminator**
+ * (200 = done, 202 = accepted). Both are conformant; a client MUST handle both, which is why this is
+ * a union rather than a shape with everything optional. Narrow with {@link isAccepted}.
+ */
+export type RegisterProjectResult = RegisterProjectSummary | RegisterProjectAccepted;
+/** Narrow a register response to the deferred-catch-up branch. */
+export declare function isAccepted(r: RegisterProjectResult): r is RegisterProjectAccepted;
 /** One row of `GET /v1/projects` — the projects visible to this token. */
 export interface RemoteProjectSummary {
     chainId: number;
@@ -96,18 +195,38 @@ export interface RemoteProjectSummary {
     eventCount?: number;
     tokenCount?: number;
     mintedCount?: number;
+    /** Sum of every token's current supply — ERC-1155 editions only; absent for a 721 project. */
+    copies?: string;
     reconstructedAt?: string | null;
+    /** Where this project is in the indexing lifecycle — so a list renders "3 live, 1 backfilling,
+     *  1 failed" with no per-project round trip. */
+    status?: IndexStatus;
+    /** Present on `stale`/`failed` — the class only; the full hint lives on the status route. */
+    error?: {
+        class: IndexErrorClass;
+    };
 }
-/** `GET /v1/projects/{chainId}/{address}/status` — indexing freshness. */
+/** `GET /v1/projects/{chainId}/{address}/status` — indexing freshness + lifecycle. */
 export interface RemoteProjectStatus {
     chainId: number;
     address: string;
+    /** Where this project is in the lifecycle. */
+    status: IndexStatus;
     fromBlock: string;
     toBlock: string | null;
+    /** Chain head as the service last saw it — so a client computes lag / % complete without knowing
+     *  anything about the service's watcher. `null` when the service can't say. */
+    headBlock?: string | null;
     eventCount: number;
     tokenCount: number;
     mintedCount: number;
+    /** Sum of every token's current supply — ERC-1155 editions only; absent for a 721 project. */
+    copies?: string;
     reconstructedAt: string | null;
+    /** Present on `stale`/`failed`. Credential-free by contract. */
+    error?: IndexError;
+    /** Catch-up attempts since the last success. */
+    attempts?: number;
     watcher?: {
         watching: boolean;
         pollAt: string | null;
@@ -115,6 +234,21 @@ export interface RemoteProjectStatus {
         intervalMs?: number;
     };
 }
+/**
+ * How far along a BACKFILL is, from a status read — `null` when there is no meaningful ratio.
+ *
+ * Deliberately `null` for anything but `backfilling`, because `toBlock` measures two different things
+ * depending on the state. During an initial sync it advances monotonically, so `toBlock` vs head IS
+ * progress. Once a project is `live` it only moves when that project has *events* — so a perfectly
+ * current project on a busy chain sits at a tiny fraction of head, and rendering that as "3%" reads
+ * as broken when nothing is wrong. Same reason the reference measures staleness against its watcher's
+ * watermark rather than a project's `toBlock`.
+ */
+export declare function indexProgress(s: RemoteProjectStatus): {
+    done: bigint;
+    total: bigint;
+    percent: number;
+} | null;
 /** `POST /v1/effect-artifacts` — a render producer publishes one output (locator or bytes). */
 export interface PublishEffectArtifactBody {
     chainId: number;
@@ -125,9 +259,19 @@ export interface PublishEffectArtifactBody {
     output?: string;
     effectKey?: string;
     contentType?: string;
-    /** A durable `ipfs://` / `ar://` / `https://` pointer — the service stores it and redirects. */
+    /**
+     * REFERENCED outputs (`render/image`, a video, a model — anything the service doesn't stitch):
+     * an `https://` / `ipfs://` / `ar://` pointer, reachable without the producer's credentials. The
+     * service records it and 302-redirects; it never fetches or proxies the bytes. Required for this
+     * class — sending {@link bytes_base64} instead is a `400`.
+     */
     locator?: string;
-    /** The raw output, stored in the service's own byte custody (what traits use). */
+    /**
+     * BOUND outputs only (`render/traits` — content that stitches into the metadata JSON): the raw
+     * output, ≤{@link BOUND_ARTIFACT_MAX_BYTES}, held by the service beside the artifact row. Sending
+     * a {@link locator} for a bound output is a `400` — the content is assembled into `tokenURI`, so a
+     * pointer there would be recorded and then never stitch.
+     */
     bytes_base64?: string;
 }
 /** `POST /v1/effect-status` — a producer reports one run's transient state. */
@@ -147,12 +291,30 @@ export declare class AbxServiceError extends Error {
     readonly status: number;
     readonly code?: ServiceErrorCode;
     readonly url: string;
+    /** The failure CLASS when the service volunteered one (a credential-free hint about *why* — an
+     *  exhausted RPC reads very differently from a broken service). Optional on the wire. */
+    readonly class?: IndexErrorClass;
     constructor(message: string, opts: {
         status: number;
         code?: ServiceErrorCode;
         url: string;
+        class?: IndexErrorClass;
     });
 }
+/** Waiting for a project to reach a terminal status ran out of time. The registration is durable —
+ *  this is "still working", never "the add failed". */
+export declare class AbxIndexTimeoutError extends Error {
+    readonly last?: RemoteProjectStatus;
+    constructor(message: string, last?: RemoteProjectStatus);
+}
+export interface AwaitIndexedOptions {
+    /** Give up after this long (default 5 min). The registration stays durable regardless. */
+    timeoutMs?: number;
+    /** Poll cadence (default 3s). */
+    intervalMs?: number;
+    /** Called on every poll — drive a progress line from it. */
+    onProgress?: (status: RemoteProjectStatus) => void;
+}
 export interface ServiceClientOptions {
     baseUrl: string;
     /** Bearer token for the control plane. Omit for descriptor-only use. */
@@ -170,8 +332,23 @@ export declare class AbxServiceClient {
     constructor(opts: ServiceClientOptions);
     /** The public service descriptor — no auth, safe to fetch before trusting a provider. */
     descriptor(): Promise<ServiceDescriptor>;
-    /** Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). */
+    /**
+     * Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). Returns the
+     * completed summary (HTTP 200) or the accepted-and-still-working shape (HTTP 202) — narrow with
+     * {@link isAccepted}, and follow a 202 with {@link awaitIndexed}.
+     *
+     * A timed-out register is NOT retried blind. A conforming service persists the registration before
+     * it starts catching up, so a timeout usually means "it's in there, still working" — and re-POSTing
+     * would kick off a *second* full reconstruct against the RPC that was already too slow to answer.
+     * So we ask the status route whether it landed, and if it did we return the async shape instead.
+     */
     registerProject(body: RegisterProjectBody): Promise<RegisterProjectResult>;
+    /**
+     * Poll a project's status until it reaches a terminal lifecycle state (`live` or `failed`) — the
+     * one implementation of the wait loop, so the CLI, the effects runner, and any hosted agent all
+     * behave identically against any provider. `stale` keeps polling: it means lagging, not caught up.
+     */
+    awaitIndexed(chainId: number, address: string, opts?: AwaitIndexedOptions): Promise<RemoteProjectStatus>;
     /** The projects this token may see. */
     listProjects(): Promise<RemoteProjectSummary[]>;
     /** Deregister (remote `abx forget`). `not_registered` means "already gone" — reported, not
@@ -179,7 +356,8 @@ export declare class AbxServiceClient {
     removeProject(chainId: number, address: string): Promise<{
         removed: boolean;
     }>;
-    /** Nudge a re-index. */
+    /** Nudge a re-index. Answers in the same two shapes as {@link registerProject} — a full replay is
+     *  the *most* likely call to outlive one HTTP request. */
     reindexProject(chainId: number, address: string): Promise<RegisterProjectResult>;
     /** Indexing freshness for one project. */
     projectStatus(chainId: number, address: string): Promise<RemoteProjectStatus>;
@@ -192,5 +370,6 @@ export declare class AbxServiceClient {
     /** Report a run's transient state for the artifact key it is producing. */
     reportEffectStatus(body: ReportEffectStatusBody): Promise<void>;
     private request;
+    private requestWithStatus;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

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

package/dist/service.js

@@ -8,24 +8,155 @@
  * credential resolution is the caller's concern (the CLI's named-remote convention lives in
  * packages/cli/src/remote.ts).
  */
+import { linearBackoffDelay, sleep } from './util.js';
 export const WELL_KNOWN_SERVICE_PATH = '/.well-known/abx-service';
-/** Versioned interface ids a service declares in its descriptor. Versions ride these ids
- *  (they track the `/v1` path prefix); the descriptor has no separate format version. */
+/**
+ * Versioned interface ids a service declares in its descriptor. Versions ride these ids
+ * (they track the `/v1` path prefix); the descriptor has no separate format version.
+ *
+ * There are exactly two, and they are **all-or-nothing**: declaring one asserts every route it names
+ * answers per the spec. The artifact-registry routes ride {@link CONTROL_PLANE_INTERFACE} rather
+ * than an id of their own — once referenced output is locator-only, accepting a registration is a
+ * database insert, so a separate capability flag would describe a distinction that doesn't exist.
+ * A service that won't take a given caller's artifacts refuses on the credential (`403`), which is
+ * the honest axis: interfaces describe wire grammar, tokens describe permission.
+ */
 export const TOKEN_API_INTERFACE = 'abx-token-api/v1';
 export const CONTROL_PLANE_INTERFACE = 'abx-control-plane/v1';
-export const EFFECTS_PUBLISH_INTERFACE = 'abx-effects-publish/v1';
+/**
+ * Why this locator can't be accepted for a referenced artifact, or `null` if it passes.
+ *
+ * A locator is a **reachability** claim, not a durability one: it must resolve for a third party
+ * with no producer credentials and no private-network assumption. The protocol deliberately has
+ * **no preference among schemes** — `https://` (S3/R2, a producer's own public base, a chosen
+ * IPFS/Arweave gateway), `ipfs://` and `ar://` are peers, because derived output is re-creatable and
+ * a producer with an opinion about which gateway serves its content is making an operational call the
+ * protocol has no standing to override.
+ *
+ * Reachability can't be *proved* without fetching, and fetching a third-party URL while handling an
+ * authed write is byte custody through the back door plus an SSRF surface. So this checks the two
+ * things that are decidable from the string alone and are always wrong:
+ *   - a private / loopback host — resolvable only from the producer's own network;
+ *   - a presigned, expiring URL — resolvable now, dead later, which is the worst failure shape
+ *     (it passes every check at publish time and rots silently).
+ */
+export function locatorRejectionReason(locator) {
+    const trimmed = locator.trim();
+    if (!/^(https?|ipfs|ar):/i.test(trimmed)) {
+        return `unsupported scheme — use https://, ipfs:// or ar://`;
+    }
+    if (/^https?:/i.test(trimmed)) {
+        let url;
+        try {
+            url = new URL(trimmed);
+        }
+        catch {
+            return 'not a parseable URL';
+        }
+        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+        const privateHost = host === 'localhost' ||
+            host.endsWith('.localhost') ||
+            host === '::1' ||
+            host === '0.0.0.0' ||
+            /^127\./.test(host) ||
+            /^10\./.test(host) ||
+            /^192\.168\./.test(host) ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+            /^169\.254\./.test(host) ||
+            /^f[cd][0-9a-f]{2}:/.test(host);
+        if (privateHost) {
+            return `'${url.hostname}' is a loopback/private host — a locator must resolve for anyone, not just from the producer's network`;
+        }
+        const q = url.searchParams;
+        if (q.has('X-Amz-Signature') || q.has('Signature') || q.has('X-Goog-Signature') || q.has('sig') || q.has('Expires') || q.has('X-Amz-Expires')) {
+            return 'looks like a presigned/expiring URL — it would resolve now and rot later; publish a durable public URL instead';
+        }
+    }
+    return null;
+}
+/** Statuses a caller can stop waiting on — see {@link AbxServiceClient.awaitIndexed}. */
+export const TERMINAL_INDEX_STATUSES = ['live', 'failed'];
+/** The one message per class. Fixed strings — an upstream error is never interpolated, because a
+ *  keyed RPC URL *is* a credential and upstream messages routinely embed one. */
+const INDEX_ERROR_MESSAGES = {
+    rpc_unavailable: 'upstream RPC unavailable; will retry',
+    rpc_rate_limited: 'upstream RPC rate-limited; will retry',
+    not_abx_contract: 'address emits no ABX event spine on this chain',
+    internal: 'indexing failed; see the service operator’s logs',
+};
+/** Map a catch-up failure to its wire form. Sniffs the underlying error's shape only to CHOOSE a
+ *  class — nothing from it reaches the returned message. */
+export function classifyIndexError(err) {
+    const raw = err instanceof Error ? `${err.name} ${err.message}` : String(err);
+    const text = raw.toLowerCase();
+    let cls = 'internal';
+    if (/rate.?limit|too many requests|\b429\b|quota|exceeded .*(?:compute|cu)|throttl/.test(text)) {
+        cls = 'rpc_rate_limited';
+    }
+    else if (/timeout|timed out|econnrefused|econnreset|enotfound|eai_again|socket hang up|fetch failed|network|502|503|504|http request failed/.test(text)) {
+        cls = 'rpc_unavailable';
+    }
+    return { class: cls, message: INDEX_ERROR_MESSAGES[cls] };
+}
+/** Narrow a register response to the deferred-catch-up branch. */
+export function isAccepted(r) {
+    return r.accepted === true;
+}
+/**
+ * How far along a BACKFILL is, from a status read — `null` when there is no meaningful ratio.
+ *
+ * Deliberately `null` for anything but `backfilling`, because `toBlock` measures two different things
+ * depending on the state. During an initial sync it advances monotonically, so `toBlock` vs head IS
+ * progress. Once a project is `live` it only moves when that project has *events* — so a perfectly
+ * current project on a busy chain sits at a tiny fraction of head, and rendering that as "3%" reads
+ * as broken when nothing is wrong. Same reason the reference measures staleness against its watcher's
+ * watermark rather than a project's `toBlock`.
+ */
+export function indexProgress(s) {
+    if (s.status !== 'backfilling')
+        return null;
+    if (!s.headBlock || !s.toBlock)
+        return null;
+    try {
+        const from = BigInt(s.fromBlock);
+        const to = BigInt(s.toBlock);
+        const head = BigInt(s.headBlock);
+        if (head <= from || to < from)
+            return null;
+        const total = head - from;
+        const done = (to > head ? head : to) - from;
+        return { done, total, percent: Number((done * 100n) / total) };
+    }
+    catch {
+        return null;
+    }
+}
 /** A non-2xx control-plane response (or an unreachable service, after retries). `code` is the
  *  spec's machine code when the service sent one — key behavior off it, never off `message`. */
 export class AbxServiceError extends Error {
     status;
     code;
     url;
+    /** The failure CLASS when the service volunteered one (a credential-free hint about *why* — an
+     *  exhausted RPC reads very differently from a broken service). Optional on the wire. */
+    class;
     constructor(message, opts) {
         super(message);
         this.name = 'AbxServiceError';
         this.status = opts.status;
         this.code = opts.code;
         this.url = opts.url;
+        this.class = opts.class;
+    }
+}
+/** Waiting for a project to reach a terminal status ran out of time. The registration is durable —
+ *  this is "still working", never "the add failed". */
+export class AbxIndexTimeoutError extends Error {
+    last;
+    constructor(message, last) {
+        super(message);
+        this.name = 'AbxIndexTimeoutError';
+        this.last = last;
     }
 }
 /**
@@ -51,11 +182,48 @@ export class AbxServiceClient {
     }
     /** The public service descriptor — no auth, safe to fetch before trusting a provider. */
     async descriptor() {
-        return (await this.request('GET', WELL_KNOWN_SERVICE_PATH, undefined, DESCRIPTOR_ATTEMPTS));
+        return (await this.request('GET', WELL_KNOWN_SERVICE_PATH, undefined, { attempts: DESCRIPTOR_ATTEMPTS }));
     }
-    /** Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). */
+    /**
+     * Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). Returns the
+     * completed summary (HTTP 200) or the accepted-and-still-working shape (HTTP 202) — narrow with
+     * {@link isAccepted}, and follow a 202 with {@link awaitIndexed}.
+     *
+     * A timed-out register is NOT retried blind. A conforming service persists the registration before
+     * it starts catching up, so a timeout usually means "it's in there, still working" — and re-POSTing
+     * would kick off a *second* full reconstruct against the RPC that was already too slow to answer.
+     * So we ask the status route whether it landed, and if it did we return the async shape instead.
+     */
     async registerProject(body) {
-        return (await this.request('POST', '/v1/projects', body));
+        const landed = async () => {
+            const st = await this.projectStatus(body.chainId, body.address).catch(() => null);
+            if (!st)
+                return undefined; // not there (or the service is truly unreachable) — keep retrying
+            return { ok: true, accepted: true, project: { address: body.address, status: st.status } };
+        };
+        const { status, body: out } = await this.requestWithStatus('POST', '/v1/projects', body, { onTimeout: landed });
+        return normalizeRegisterResult(status, out, body.address);
+    }
+    /**
+     * Poll a project's status until it reaches a terminal lifecycle state (`live` or `failed`) — the
+     * one implementation of the wait loop, so the CLI, the effects runner, and any hosted agent all
+     * behave identically against any provider. `stale` keeps polling: it means lagging, not caught up.
+     */
+    async awaitIndexed(chainId, address, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 300_000;
+        const intervalMs = opts.intervalMs ?? 3_000;
+        const deadline = Date.now() + timeoutMs;
+        let last;
+        for (;;) {
+            last = await this.projectStatus(chainId, address);
+            opts.onProgress?.(last);
+            if (TERMINAL_INDEX_STATUSES.includes(last.status))
+                return last;
+            if (Date.now() + intervalMs > deadline) {
+                throw new AbxIndexTimeoutError(`${address} was still '${last.status}' after ${Math.round(timeoutMs / 1000)}s — the registration is durable and the service keeps working; check back with \`abx status ${address} --remote\``, last);
+            }
+            await sleep(intervalMs);
+        }
     }
     /** The projects this token may see. */
     async listProjects() {
@@ -75,9 +243,16 @@ export class AbxServiceClient {
             throw err;
         }
     }
-    /** Nudge a re-index. */
+    /** Nudge a re-index. Answers in the same two shapes as {@link registerProject} — a full replay is
+     *  the *most* likely call to outlive one HTTP request. */
     async reindexProject(chainId, address) {
-        return (await this.request('POST', `/v1/projects/${chainId}/${address}/reindex`));
+        const { status, body } = await this.requestWithStatus('POST', `/v1/projects/${chainId}/${address}/reindex`, undefined, {
+            onTimeout: async () => {
+                const st = await this.projectStatus(chainId, address).catch(() => null);
+                return st ? { ok: true, accepted: true, project: { address, status: st.status } } : undefined;
+            },
+        });
+        return normalizeRegisterResult(status, body, address);
     }
     /** Indexing freshness for one project. */
     async projectStatus(chainId, address) {
@@ -91,7 +266,11 @@ export class AbxServiceClient {
     async reportEffectStatus(body) {
         await this.request('POST', '/v1/effect-status', body);
     }
-    async request(method, path, body, attempts = ATTEMPTS) {
+    async request(method, path, body, opts) {
+        return (await this.requestWithStatus(method, path, body, opts)).body;
+    }
+    async requestWithStatus(method, path, body, opts) {
+        const attempts = opts?.attempts ?? ATTEMPTS;
         const url = this.baseUrl + path;
         const headers = {};
         if (this.token)
@@ -101,6 +280,7 @@ export class AbxServiceClient {
         let lastFailure = '';
         let lastStatus = 0;
         let lastCode;
+        let lastClass;
         for (let attempt = 1; attempt <= attempts; attempt++) {
             let resp;
             try {
@@ -114,13 +294,21 @@ export class AbxServiceClient {
             catch (err) {
                 lastFailure = err.message;
                 lastStatus = 0;
+                // "We waited the full timeout" and "nothing is listening" are different failures, and for a
+                // mutating POST the difference decides whether retrying is safe: the request may still be
+                // running on the service. Let the caller check before we hammer it again.
+                if (opts?.onTimeout && err.name === 'TimeoutError') {
+                    const resolved = await opts.onTimeout();
+                    if (resolved !== undefined)
+                        return { status: 202, body: resolved };
+                }
                 if (attempt < attempts)
-                    await sleep(this.retryDelayMs * attempt);
+                    await sleep(linearBackoffDelay(attempt, this.retryDelayMs));
                 continue;
             }
             if (resp.ok) {
                 const text = await resp.text();
-                return text ? JSON.parse(text) : {};
+                return { status: resp.status, body: text ? JSON.parse(text) : {} };
             }
             if (resp.status >= 500 || resp.status === 429) {
                 // Retryable — but KEEP the service's own words. A 5xx body carries the actual cause (an
@@ -129,9 +317,10 @@ export class AbxServiceClient {
                 const said = await bodyMessage(resp);
                 lastStatus = resp.status;
                 lastCode = said.code;
+                lastClass = said.class;
                 lastFailure = said.error ? `${resp.status} ${said.error}` : `${resp.status} ${resp.statusText}`;
                 if (attempt < attempts)
-                    await sleep(this.retryDelayMs * attempt);
+                    await sleep(linearBackoffDelay(attempt, this.retryDelayMs));
                 continue;
             }
             // A genuine 4xx is an answer, not weather — surface the service's own words + code.
@@ -139,6 +328,7 @@ export class AbxServiceClient {
             throw new AbxServiceError(`${method} ${url}: ${resp.status} ${detail.error ?? resp.statusText}`, {
                 status: resp.status,
                 code: detail.code,
+                class: detail.class,
                 url,
             });
         }
@@ -147,20 +337,40 @@ export class AbxServiceClient {
         const summary = lastStatus
             ? `service failed after ${attempts} attempt(s) — last response ${lastFailure}`
             : `nothing responded after ${attempts} attempt(s) (${lastFailure})`;
-        throw new AbxServiceError(`${method} ${url}: ${summary}`, { status: lastStatus, code: lastCode, url });
+        throw new AbxServiceError(`${method} ${url}: ${summary}`, { status: lastStatus, code: lastCode, class: lastClass, url });
+    }
+}
+/** Normalize a register/reindex response: the HTTP status is the authoritative discriminator, and
+ *  the `accepted` flag is derived from it so callers switch on one field even against a service that
+ *  doesn't send it. */
+function normalizeRegisterResult(status, out, fallbackAddress) {
+    if (status === 202) {
+        const r = out;
+        return {
+            ok: r.ok ?? true,
+            accepted: true,
+            project: {
+                address: r.project?.address ?? fallbackAddress,
+                name: r.project?.name ?? null,
+                status: r.project?.status ?? 'backfilling',
+            },
+        };
     }
+    return { ...out, accepted: false };
 }
-/** The service's own `{error, code}` from a non-2xx body (never throws — a body may be empty/HTML). */
+/** The service's own `{error, code, class?}` from a non-2xx body (never throws — a body may be
+ *  empty/HTML). `class` is the optional credential-free failure hint. */
 async function bodyMessage(resp) {
     try {
         const parsed = (await resp.json());
-        return { error: parsed.error, code: parsed.code };
+        return {
+            error: parsed.error,
+            code: parsed.code,
+            class: parsed.class,
+        };
     }
     catch {
         return {};
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 //# sourceMappingURL=service.js.map