@artblocks/abx-sdk 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/script-chunks.js

@@ -0,0 +1,158 @@
+/**
+ * On-chain program chunks — the writer-side twin of {@link AbxGenerator}'s `_escapedScript`.
+ *
+ * The generator (and the resolver) join `scriptChunk(i)` with a single `'\n'` between chunks. A
+ * fixed-size byte slice that ignores that join inserts a newline in the middle of a token — `mass`
+ * becomes `ma\nss`, which is invalid JavaScript — and `abx verify` still goes green because it
+ * never parses the reassembled program. Splitting AT an existing newline (and dropping it, because
+ * the join puts it back) makes `chunks.join('\n') === source`. A 22 kB+ span with no newline is
+ * refused: there is no honest split that matches the on-chain join.
+ *
+ * This module also carries the write-side counterpart to that split (`prepareSetScriptChunk` /
+ * `prepareRemoveLastScriptChunk`, wrapping `OnChainScript.sol`'s `setScriptChunk`/
+ * `removeLastScriptChunk` — contracts/src/extensions/onchain-script/OnChainScript.sol) and the
+ * SAFE-REPLACEMENT planning + verification pair (`planScriptReplace` / `verifyScriptReplace`) that
+ * `abx replace-script` is built on (packages/cli/src/ownerops.ts). Both take a small reader
+ * interface rather than a viem client — the same shape `resume.ts` uses — so the diff and the
+ * post-write verification are testable with a fake chain, no RPC, no signer.
+ */
+import { encodeFunctionData, hexToBytes } from 'viem';
+import { seriesCodeAbi } from './abi/index.js';
+const ZERO_VALUE = '0x0';
+/** SSTORE2 data-contract code limit is 24576 bytes (EIP-170) minus STOP; stay conservative. */
+export const DEFAULT_SCRIPT_CHUNK_SIZE = 22_000;
+/** The byte the on-chain generator inserts between script chunks. Must stay in lockstep with
+ *  `AbxGenerator._escapedScript` and the resolver's `.join('\n')`. */
+export const SCRIPT_CHUNK_JOIN = '\n';
+const NL = 0x0a;
+/**
+ * Split a program so the generator's newline-join reconstitutes it byte-for-byte.
+ * Empty source → no chunks (nothing to store). A single chunk that already fits is stored as-is
+ * (the generator inserts no join when `n === 1`).
+ */
+export function splitScriptChunks(source, chunkSize = DEFAULT_SCRIPT_CHUNK_SIZE) {
+    if (chunkSize < 1)
+        throw new Error('chunkSize must be ≥ 1');
+    const bytes = new TextEncoder().encode(source);
+    if (bytes.length === 0)
+        return [];
+    if (bytes.length <= chunkSize)
+        return [bytes];
+    const chunks = [];
+    let i = 0;
+    while (i < bytes.length) {
+        const remaining = bytes.length - i;
+        if (remaining <= chunkSize) {
+            chunks.push(bytes.subarray(i));
+            break;
+        }
+        // Last newline in the window. The generator will put it back between this chunk and the next,
+        // so the chunk itself excludes it.
+        let split = -1;
+        for (let j = i + chunkSize - 1; j >= i; j--) {
+            if (bytes[j] === NL) {
+                split = j;
+                break;
+            }
+        }
+        if (split < i) {
+            throw new Error(`script has a ${chunkSize}+ byte span with no newline — the on-chain generator joins ` +
+                `chunks with a newline, so a split here would insert a byte and can break the program ` +
+                `(a 22 kB minified line has been observed to turn \`mass\` into \`ma\\nss\`). ` +
+                `Insert a line break, or shrink the file.`);
+        }
+        chunks.push(bytes.subarray(i, split));
+        i = split + 1;
+    }
+    return chunks;
+}
+/** Inverse of {@link splitScriptChunks}: the join the generator performs on chain. */
+export function joinScriptChunks(chunks) {
+    const dec = new TextDecoder();
+    return chunks.map((c) => dec.decode(c)).join(SCRIPT_CHUNK_JOIN);
+}
+// ── writes: OnChainScript.sol's setScriptChunk / removeLastScriptChunk ────────
+// No `prepare*` wrapper existed for either before this — every caller (deploy-code's setup
+// multicall, its --resume leg) hand-encoded `encodeFunctionData` inline. These mirror
+// `prepareSetDependency`/`prepareRemoveLastDependency` (ops.ts) exactly: same `PreparedTx` shape,
+// same "one index-addressed setter + one pop-the-tail remover" split.
+/** Owner writes/replaces the on-chain program chunk at `index` (`index === count` appends) —
+ *  `OnChainScript.setScriptChunk`. Content should come from {@link splitScriptChunks} so the
+ *  generator's newline-join reassembles the exact source. Signer must be the owner. */
+export function prepareSetScriptChunk(args) {
+    const index = BigInt(args.index);
+    const bytes = (args.chunk.length - 2) / 2;
+    // EVM code deposit is 200 gas/byte — the same physics-backed floor the code-setup multicall
+    // computes for its script-chunk legs (ops.ts). Restated per-chunk here so a caller that assembles
+    // its own multicall (`replace-script`) can sum an honest `gasFloor` instead of trusting
+    // `eth_estimateGas` against a target too fresh for the estimator to see (see PreparedTx.gasFloor's
+    // own doc for why a wrong estimate must be DETECTED, not silently replaced).
+    const gasFloor = bytes > 0 ? `0x${(bytes * 200).toString(16)}` : undefined;
+    return {
+        op: 'set-script-chunk',
+        to: args.contract,
+        data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setScriptChunk', args: [index, args.chunk] }),
+        value: ZERO_VALUE,
+        chainId: args.chainId,
+        summary: `Set script chunk [${index}] (${bytes} byte${bytes === 1 ? '' : 's'})`,
+        fields: { contract: args.contract, index: index.toString(), bytes: String(bytes) },
+        ...(gasFloor === undefined ? {} : { gasFloor }),
+    };
+}
+/** Remove the LAST on-chain program chunk (the list stays dense; order is load-bearing) —
+ *  `OnChainScript.removeLastScriptChunk`. There is no "remove N": shrinking by more than one chunk
+ *  is this call, repeated. Signer must be the owner. */
+export function prepareRemoveLastScriptChunk(args) {
+    return {
+        op: 'remove-last-script-chunk',
+        to: args.contract,
+        data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'removeLastScriptChunk', args: [] }),
+        value: ZERO_VALUE,
+        chainId: args.chainId,
+        summary: 'Remove the last script chunk (the list stays dense)',
+        fields: { contract: args.contract },
+    };
+}
+/**
+ * Diff a replacement program's chunks against what a contract holds NOW, so `replace-script` sends
+ * only what actually changed. Mirrors `resume.ts`'s script-chunk leg (`planCoreLegs`) exactly —
+ * content, not count, decides "present" — the difference being that a resume leg is checked
+ * present/absent as a GROUP (the setup multicall is atomic, so partial-content-mismatch never
+ * legitimately happens), while a replacement is expected to change SOME indices and not others, so
+ * each index is diffed and reported independently.
+ */
+export async function planScriptReplace(read, next) {
+    const currentCount = await read.scriptChunkCount();
+    const toWrite = [];
+    for (let i = 0; i < next.length; i++) {
+        const stored = i < currentCount ? await read.scriptChunk(i) : null;
+        if (stored !== null && stored.toLowerCase() === next[i].toLowerCase())
+            continue;
+        toWrite.push({ index: i, hex: next[i] });
+    }
+    const toRemove = Math.max(0, currentCount - next.length);
+    return { toWrite, toRemove, currentCount, targetCount: next.length, noop: toWrite.length === 0 && toRemove === 0 };
+}
+/**
+ * Read the completed script back from chain and confirm it reassembles EXACTLY to `expectedSource`
+ * — the safety property that justifies `replace-script` existing at all. A transaction not
+ * reverting is proof the EVM accepted each call; it is NOT proof the final program is what was
+ * intended (a stale RPC view, a concurrent write racing the same contract, or a bug in the ordering
+ * of writes-vs-removes could all leave a script that "sent fine" and reassembles to garbage). This
+ * is the check that turns "the multicall didn't revert" into "the program is provably correct" —
+ * run it BEFORE reporting success, never after.
+ */
+export async function verifyScriptReplace(read, expectedSource) {
+    const chunkCount = await read.scriptChunkCount();
+    const chunks = [];
+    for (let i = 0; i < chunkCount; i++) {
+        const hex = await read.scriptChunk(i);
+        // `scriptChunkCount()` and `scriptChunk(i)` are two separate reads against (hopefully) the same
+        // block; a `null` here means they disagree, which is itself the failure this function exists to
+        // catch — report it as a verification miss rather than silently reassembling a gap.
+        chunks.push(hex === null ? new Uint8Array(0) : hexToBytes(hex));
+    }
+    const reassembled = joinScriptChunks(chunks);
+    return { ok: reassembled === expectedSource, reassembled, chunkCount };
+}
+//# sourceMappingURL=script-chunks.js.map

package/dist/script-chunks.js.map

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

package/dist/service.d.ts

@@ -1,6 +1,6 @@
 /**
  * The remote-service client — the SDK's one HTTP surface, speaking the provider-neutral
- * control plane pinned by specs/self-host-toolkit/remote-services.md. A client is bound to an
+ * control plane pinned by site/content/docs/using-abx/remote-services.mdx. A client is bound to an
  * endpoint + an injected bearer token, never to a brand: the reference CLI, the effects runner,
  * and any hosted agent drive a self-hosted node and a managed provider through this same class.
  *
@@ -10,15 +10,45 @@
  */
 import type { Hex } from 'viem';
 import type { OpenSeaAttribute } from './traits.js';
+import type { ContractGenerationSummary } from './contract-generations.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 three optional interface families, 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";
+/** Provider-specific feedback discovery, submission, and account history at `/feedback`. Core ABX
+ *  feedback is deliberately not this interface: it belongs to the ABX team, not a remote provider. */
+export declare const SERVICE_FEEDBACK_INTERFACE = "abx-service-feedback/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
+ * (site/content/docs/using-abx/remote-services.mdx → 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
@@ -61,11 +91,30 @@ export interface IndexError {
 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'
+/** The report belongs at a different feedback target; the response carries its canonical URL. */
+ | 'feedback_target_moved'
 /** 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'
+/**
+ * **410** — this token id existed and is permanently gone (an ERC-721 burn). A statement about the
+ * TOKEN, which is why `not_registered` could not carry it: that one is a statement about the
+ * *contract* ("this node doesn't index it"), so it cannot truthfully describe a destroyed id.
+ *
+ * `410`, not `404`, and the rule generalizes: **a resolver answers what the contract's own URI
+ * getter answers.** A burned 721's `tokenURI` reverts `NonexistentToken`, so composing metadata
+ * for it would put a node in direct contradiction with the contract it speaks for — while `404`
+ * reads as "wrong URL / not indexed yet" and invites a retry that can never succeed. It is worse
+ * than cosmetic on the image route, which answers an unknown-but-in-cap id with a warming
+ * placeholder: for a destroyed id that says "still loading" forever.
+ *
+ * **ERC-1155 editions never answer this.** `uri(id)` has no existence gate there, a zero-supply id
+ * still resolves, and it can mint again — nothing is permanently gone, so `410` would be a lie.
+ * Serve the document with `supply: 0`.
+ */
+ | 'burned'
 /** 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';
@@ -80,8 +129,10 @@ export interface ServiceDescriptor {
     interfaces: string[];
     /** EIP-155 chain ids served; the control plane rejects others with `unsupported_chain`. */
     chains: number[];
-    /** Present iff the control plane is enabled. `signupUrl`/`docsUrl` are for humans —
-     *  where a customer gets a key. */
+    /** Contract generations this implementation understands, with operation-specific policy. */
+    contractGenerations?: ContractGenerationSummary[];
+    /** Present iff the control plane is enabled. `signupUrl` is provider-specific human
+     * onboarding/recovery and `docsUrl` is provider documentation; OAuth discovery is separate. */
     auth?: {
         scheme: 'bearer';
         signupUrl?: string;
@@ -102,6 +153,69 @@ export interface ServiceDescriptor {
     /** The public base this node believes it serves — a sanity echo for misconfig detection. */
     baseUrl?: string;
 }
+export declare const FEEDBACK_KINDS: readonly ["bug", "friction", "gap", "confusion", "praise", "other"];
+export type FeedbackKind = (typeof FEEDBACK_KINDS)[number];
+export declare const FEEDBACK_SEVERITIES: readonly ["blocker", "major", "minor"];
+export type FeedbackSeverity = (typeof FEEDBACK_SEVERITIES)[number];
+export declare const ABX_FEEDBACK_AREAS: readonly ["protocol", "contracts", "cli", "sdk", "skills", "docs", "other"];
+export type AbxFeedbackArea = (typeof ABX_FEEDBACK_AREAS)[number];
+/** Optional evidence carried with a report. Providers may accept extra keys; credentials and
+ *  private source never belong here. */
+export interface FeedbackContext {
+    command?: string;
+    chainId?: number;
+    address?: string;
+    txHashes?: string[];
+    addresses?: string[];
+    cliVersion?: string;
+    sdkVersion?: string;
+    skill?: string;
+    sessionId?: string;
+    serviceUrl?: string;
+    [key: string]: unknown;
+}
+export interface FeedbackFields {
+    kind: FeedbackKind;
+    summary: string;
+    detail?: string;
+    severity?: FeedbackSeverity;
+    via?: 'agent' | 'human';
+    context?: FeedbackContext;
+}
+export interface AbxFeedbackReport extends FeedbackFields {
+    area: AbxFeedbackArea;
+}
+export interface ServiceFeedbackReport extends FeedbackFields {
+    /** Provider-defined component name; omit when uncertain. */
+    component?: string;
+}
+export type FeedbackReport = AbxFeedbackReport | ServiceFeedbackReport;
+export interface FeedbackRecord extends FeedbackFields {
+    id: string;
+    target?: 'abx' | 'service';
+    tenantId?: string | null;
+    area?: string;
+    component?: string;
+    createdAt: string;
+    processedAt?: string | null;
+}
+export interface FeedbackListFilters {
+    area?: string;
+    component?: string;
+    kind?: FeedbackKind;
+    limit?: number;
+}
+/** The server is authoritative for its current schema; clients keep this extensible. */
+export interface FeedbackInstructions {
+    target?: string;
+    what?: string;
+    authentication?: string;
+    yourReports?: string;
+    fields?: Record<string, unknown>;
+    guidance?: string[];
+    example?: unknown;
+    [key: string]: unknown;
+}
 /** `POST /v1/projects` — the off-chain bridge: everything the host can't derive from chain. */
 export interface RegisterProjectBody {
     chainId: number;
@@ -136,6 +250,10 @@ export interface RegisterProjectSummary {
         eventCount: number;
         tokenCount: number;
         mintedCount: number;
+        /** Official generation, once the indexed factory and on-chain core version agree. */
+        contractGeneration?: ContractGenerationSummary;
+        /** Sum of every token's current supply — ERC-1155 editions only; absent for a 721 project. */
+        copies?: string;
         status?: IndexStatus;
     };
 }
@@ -167,6 +285,10 @@ export interface RemoteProjectSummary {
     eventCount?: number;
     tokenCount?: number;
     mintedCount?: number;
+    /** Official generation, once the indexed factory and on-chain core version agree. */
+    contractGeneration?: ContractGenerationSummary;
+    /** 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. */
@@ -190,6 +312,10 @@ export interface RemoteProjectStatus {
     eventCount: number;
     tokenCount: number;
     mintedCount: number;
+    /** Official generation, once the indexed factory and on-chain core version agree. */
+    contractGeneration?: ContractGenerationSummary;
+    /** 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;
@@ -227,9 +353,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. */
@@ -290,6 +426,16 @@ export declare class AbxServiceClient {
     constructor(opts: ServiceClientOptions);
     /** The public service descriptor — no auth, safe to fetch before trusting a provider. */
     descriptor(): Promise<ServiceDescriptor>;
+    /** Public, machine-readable provider feedback instructions (`abx-service-feedback/v1`). */
+    feedbackInstructions(): Promise<FeedbackInstructions>;
+    /** File one report. Callers own the human-consent boundary before invoking this write. */
+    submitFeedback(report: FeedbackReport): Promise<{
+        ok: boolean;
+        id: string;
+        createdAt: string;
+    }>;
+    /** Reports visible to this credential at this target. */
+    listFeedback(filters?: FeedbackListFilters): Promise<FeedbackRecord[]>;
     /**
      * 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

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,MAAM,CAAC;AAC9B,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;yFACyF;AACzF,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AACtD,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAC9D,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjF,yFAAyF;AACzF,eAAO,MAAM,uBAAuB,EAAE,SAAS,WAAW,EAAuB,CAAC;AAElF;;;;GAIG;AACH,MAAM,MAAM,eAAe;AACzB,oGAAoG;AAClG,iBAAiB;AACnB,oGAAoG;GAClG,kBAAkB;AACpB;;uEAEuE;GACrE,kBAAkB;AACpB,qEAAqE;GACnE,UAAU,CAAC;AAEf;;2EAE2E;AAC3E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAWD;4DAC4D;AAC5D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAc3D;AAED,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,mBAAmB,GACnB,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,UAAU;AACZ;;;oGAGoG;GAClG,eAAe;AACjB;uEACuE;GACrE,gBAAgB,CAAC;AAErB,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,OAAO,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;IAC5C,mFAAmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2FAA2F;IAC3F,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;uCACmC;IACnC,IAAI,CAAC,EAAE;QAAC,MAAM,EAAE,QAAQ,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;IAChE;sFACkF;IAClF,MAAM,CAAC,EAAE;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,KAAK,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,KAAK,CAAC;gBAAC,GAAG,EAAE,MAAM,CAAC;gBAAC,QAAQ,EAAE,MAAM,CAAA;aAAC,CAAC,CAAA;SAAC,CAAC,GAAG,IAAI,CAAA;KAAC,CAAC;IACpH,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+FAA+F;AAC/F,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,qHAAqH;IACrH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sGAAsG;IACtG,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC;yGACqG;IACrG,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACrD;mGAC+F;IAC/F,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,kGAAkG;IAClG,QAAQ,EAAE,KAAK,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC;CACH;AAED;sGACsG;AACtG,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,IAAI,CAAC;IACf,OAAO,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAC,CAAC;CACvE;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,uBAAuB,CAAC;AAErF,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,IAAI,uBAAuB,CAEjF;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;oDACgD;IAChD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6FAA6F;IAC7F,KAAK,CAAC,EAAE;QAAC,KAAK,EAAE,eAAe,CAAA;KAAC,CAAC;CAClC;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;mFAC+E;IAC/E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gEAAgE;IAChE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;CAChG;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,mBAAmB,GAAG;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAc3G;AAED,+FAA+F;AAC/F,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,UAAU,EAAE,GAAG,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;gGACgG;AAChG,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;6FACyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,eAAe,CAAA;KAAC;CAQnH;AAED;uDACuD;AACvD,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC;gBACxB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB;CAKxD;AAED,MAAM,WAAW,mBAAmB;IAClC,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAcD,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,IAAI,EAAE,oBAAoB;IAOtC,yFAAyF;IACnF,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAI9C;;;;;;;;;OASG;IACG,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAUhF;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAmBlH,uCAAuC;IACjC,YAAY,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAKrD;qGACiG;IAC3F,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAC,CAAC;IAUlF;8DAC0D;IACpD,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAUtF,0CAA0C;IACpC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAInF,iGAAiG;IAC3F,qBAAqB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;QAAC,GAAG,EAAE,GAAG,CAAA;KAAC,CAAC;IAIzH,2EAA2E;IACrE,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;YAIvD,OAAO;YAIP,iBAAiB;CAsEhC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -1,6 +1,6 @@
 /**
  * The remote-service client — the SDK's one HTTP surface, speaking the provider-neutral
- * control plane pinned by specs/self-host-toolkit/remote-services.md. A client is bound to an
+ * control plane pinned by site/content/docs/using-abx/remote-services.mdx. A client is bound to an
  * endpoint + an injected bearer token, never to a brand: the reference CLI, the effects runner,
  * and any hosted agent drive a self-hosted node and a managed provider through this same class.
  *
@@ -8,12 +8,75 @@
  * 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 three optional interface families, 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';
+/** Provider-specific feedback discovery, submission, and account history at `/feedback`. Core ABX
+ *  feedback is deliberately not this interface: it belongs to the ABX team, not a remote provider. */
+export const SERVICE_FEEDBACK_INTERFACE = 'abx-service-feedback/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
@@ -38,6 +101,9 @@ export function classifyIndexError(err) {
     }
     return { class: cls, message: INDEX_ERROR_MESSAGES[cls] };
 }
+export const FEEDBACK_KINDS = ['bug', 'friction', 'gap', 'confusion', 'praise', 'other'];
+export const FEEDBACK_SEVERITIES = ['blocker', 'major', 'minor'];
+export const ABX_FEEDBACK_AREAS = ['protocol', 'contracts', 'cli', 'sdk', 'skills', 'docs', 'other'];
 /** Narrow a register response to the deferred-catch-up branch. */
 export function isAccepted(r) {
     return r.accepted === true;
@@ -122,7 +188,36 @@ 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, { attempts: DESCRIPTOR_ATTEMPTS }));
+        return (await this.request('GET', WELL_KNOWN_SERVICE_PATH, undefined, {
+            attempts: DESCRIPTOR_ATTEMPTS,
+            authenticated: false,
+        }));
+    }
+    /** Public, machine-readable provider feedback instructions (`abx-service-feedback/v1`). */
+    async feedbackInstructions() {
+        return (await this.request('GET', '/feedback', undefined, {
+            attempts: DESCRIPTOR_ATTEMPTS,
+            authenticated: false,
+        }));
+    }
+    /** File one report. Callers own the human-consent boundary before invoking this write. */
+    async submitFeedback(report) {
+        return (await this.request('POST', '/feedback', report));
+    }
+    /** Reports visible to this credential at this target. */
+    async listFeedback(filters = {}) {
+        const query = new URLSearchParams();
+        if (filters.area)
+            query.set('area', filters.area);
+        if (filters.component)
+            query.set('component', filters.component);
+        if (filters.kind)
+            query.set('kind', filters.kind);
+        if (filters.limit !== undefined)
+            query.set('limit', String(filters.limit));
+        const suffix = query.size ? `?${query}` : '';
+        const out = (await this.request('GET', `/feedback/mine${suffix}`));
+        return out.feedback ?? [];
     }
     /**
      * Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). Returns the
@@ -213,7 +308,7 @@ export class AbxServiceClient {
         const attempts = opts?.attempts ?? ATTEMPTS;
         const url = this.baseUrl + path;
         const headers = {};
-        if (this.token)
+        if (this.token && opts?.authenticated !== false)
             headers['authorization'] = `Bearer ${this.token}`;
         if (body !== undefined)
             headers['content-type'] = 'application/json';
@@ -243,7 +338,7 @@ export class AbxServiceClient {
                         return { status: 202, body: resolved };
                 }
                 if (attempt < attempts)
-                    await sleep(this.retryDelayMs * attempt);
+                    await sleep(linearBackoffDelay(attempt, this.retryDelayMs));
                 continue;
             }
             if (resp.ok) {
@@ -260,7 +355,7 @@ export class AbxServiceClient {
                 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.
@@ -313,7 +408,4 @@ async function bodyMessage(resp) {
         return {};
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 //# sourceMappingURL=service.js.map