@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/base-classes/services/repositories/http-api/http-api-rest-operation-reference.backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-rest-operation-reference.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-rest-operation-reference.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Projecting a PROVIDER operation onto an ETL read-surface spec (S3a, #331).\n *\n * This is the executable half of the convergence recorded on\n * {@link HttpApiRestOperationReferenceSchema}: a binding names an operation in the provider's own\n * catalogue, and this turns that operation plus the binding's resource-shaped half into the\n * {@link HttpApiRestOperationSpec} every REST_JSON compiler already consumes. Nothing downstream\n * changes — the compilers never learn that a reference existed.\n *\n * A pure function over data, so the interesting refusals are testable without a provider.\n */\n\nimport {\n  HttpApiRestOperationMethod,\n  type HttpApiRestOperationReference,\n  type HttpApiRestOperationSpec,\n} from '@wildo-ai/saas-models/external-data';\nimport { ExternalOperation_Classification, API_HttpMethod } from '@wildo-ai/external-connectors-models';\nimport { ProviderRestPaginationStyle, ProviderRestParameterLocation, type ProviderRestOperation } from '@wildo-ai/external-connectors-models';\n\n/** Why a referenced provider operation cannot serve an ETL read member. */\nexport enum HttpApiRestOperationReferenceRefusalKind {\n  /** The operation MUTATES the vendor; a read surface may never reference one. */\n  OPERATION_IS_A_WRITE = 'OPERATION_IS_A_WRITE',\n  /** The operation's method is outside the read-surface vocabulary (GET/POST). */\n  METHOD_NOT_READABLE = 'METHOD_NOT_READABLE',\n  /** The reference and the operation disagree about the key: named/absent/unknown parameter. */\n  KEY_PARAMETER_INCOHERENT = 'KEY_PARAMETER_INCOHERENT',\n  /** The operation's path has a token the ETL has no value for. */\n  UNSATISFIED_PATH_TOKEN = 'UNSATISFIED_PATH_TOKEN',\n}\n\nexport class HttpApiRestOperationReferenceRefusal extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly kind: HttpApiRestOperationReferenceRefusalKind;\n      readonly providerRef: string;\n      readonly providerOperationId: string;\n      readonly member: string;\n    },\n  ) {\n    super(message);\n    this.name = 'HttpApiRestOperationReferenceRefusal';\n  }\n}\n\n/** The ETL's own token for \"this resource's synthesized key\", which every REST_JSON compiler fills. */\nconst ETL_KEY_TOKEN = '{key}';\nconst PATH_TOKEN = /\\{([^}]+)\\}/g;\n\nexport interface ProjectRestOperationReferenceInput {\n  reference: HttpApiRestOperationReference;\n  operation: ProviderRestOperation;\n  providerRef: string;\n  /** Which lifecycle member is being resolved — `read` is the only key-addressed one. */\n  member: 'read' | 'list' | 'count' | 'search';\n}\n\n/**\n * Build the read-surface spec a REST_JSON compiler consumes.\n *\n * Reads only what an ETL read can honour, and refuses the rest by NAME rather than degrading:\n * every refusal here is an authoring mistake somebody must fix, and a silently degraded read\n * surface (a filter quietly dropped, a write quietly performed) is the failure this whole lane is\n * built to make impossible.\n */\nexport function projectProviderOperationOntoReadSurface(\n  input: ProjectRestOperationReferenceInput,\n): HttpApiRestOperationSpec {\n  const { reference, operation, providerRef, member } = input;\n  const refuse = (kind: HttpApiRestOperationReferenceRefusalKind, message: string): never => {\n    throw new HttpApiRestOperationReferenceRefusal(message, {\n      kind, providerRef, providerOperationId: reference.providerOperationId, member,\n    });\n  };\n\n  // A read surface that could reference a WRITE would let a LIST call delete rows, and the\n  // repository's read-only stance (ETL D3) would rest on nobody having authored it that way.\n  if (operation.classification === ExternalOperation_Classification.WRITE) {\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.OPERATION_IS_A_WRITE,\n      `The '${member}' member references provider operation '${providerRef}.${operation.operationId}', which is classified WRITE. `\n      + 'A read surface may only reference READ operations — a LIST that could mutate the target is not a read.',\n    );\n  }\n\n  if (operation.method !== API_HttpMethod.GET && operation.method !== API_HttpMethod.POST) {\n    // POST is admitted for the same reason the inline vocabulary admits it: JSON-RPC and many\n    // enterprise search endpoints are POST-shaped even for reads.\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.METHOD_NOT_READABLE,\n      `The '${member}' member references provider operation '${providerRef}.${operation.operationId}', whose method is ${operation.method}. `\n      + 'A read-surface member speaks GET or POST only.',\n    );\n  }\n\n  // ── the key token ──────────────────────────────────────────────────────────\n  const declaredPathParameters = new Set(\n    (operation.parameters ?? [])\n      .filter((parameter) => parameter.in === ProviderRestParameterLocation.PATH)\n      .map((parameter) => parameter.name),\n  );\n\n  if (member === 'read' && reference.keyParameter === undefined) {\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.KEY_PARAMETER_INCOHERENT,\n      `The 'read' member references '${providerRef}.${operation.operationId}' and declares no keyParameter — a key-addressed read has a hole `\n      + \"only this resource's synthesized key can fill, and the provider's operation names that parameter in its own vocabulary.\",\n    );\n  }\n  if (member !== 'read' && reference.keyParameter !== undefined) {\n    // Refused rather than ignored: an author who wrote it believes it does something.\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.KEY_PARAMETER_INCOHERENT,\n      `The '${member}' member declares keyParameter '${reference.keyParameter}', which only a key-addressed 'read' can use.`,\n    );\n  }\n  if (reference.keyParameter !== undefined && !declaredPathParameters.has(reference.keyParameter)) {\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.KEY_PARAMETER_INCOHERENT,\n      `The '${member}' member names keyParameter '${reference.keyParameter}', and provider operation '${providerRef}.${operation.operationId}' `\n      + `declares no PATH parameter by that name (it declares: ${[...declaredPathParameters].join(', ') || 'none'}).`,\n    );\n  }\n\n  // Rewrite the operation's own key token into the ETL's, and refuse any OTHER token: the ETL has\n  // exactly one value to supply, so a second hole would be filled with the literal `{token}` and\n  // the target would answer a confident 404 nobody could explain.\n  const pathTemplate = operation.pathTemplate.replace(PATH_TOKEN, (match, token: string) => {\n    if (token === reference.keyParameter) return ETL_KEY_TOKEN;\n    const parameter = (operation.parameters ?? []).find(\n      (candidate) => candidate.in === ProviderRestParameterLocation.PATH && candidate.name === token,\n    );\n    if (parameter?.constantValue !== undefined) return encodeURIComponent(parameter.constantValue);\n    return refuse(\n      HttpApiRestOperationReferenceRefusalKind.UNSATISFIED_PATH_TOKEN,\n      `Provider operation '${providerRef}.${operation.operationId}' has the path token '${match}', and an ETL read has no value for it `\n      + '— declare it with a constantValue on the operation, or reference an operation whose path this resource can address.',\n    );\n  });\n\n  // ── paging ─────────────────────────────────────────────────────────────────\n  // Only OFFSET paging projects: the read surface's `pagingParams` is a (limit, offset) pair, and\n  // a cursor or link style has no representation in it. Absent means the member is unpaginated\n  // here — the honest answer, since inventing an offset over a cursor API silently re-reads page\n  // one forever.\n  const pagingParams = operation.pagination?.style === ProviderRestPaginationStyle.OFFSET\n    && operation.pagination.limitParam !== undefined\n    && operation.pagination.offsetParam !== undefined\n    ? { limitParam: operation.pagination.limitParam, offsetParam: operation.pagination.offsetParam }\n    : undefined;\n\n  return {\n    method: operation.method === API_HttpMethod.POST ? HttpApiRestOperationMethod.POST : HttpApiRestOperationMethod.GET,\n    pathTemplate,\n    ...(pagingParams ? { pagingParams } : {}),\n    ...(reference.filterParams ? { filterParams: reference.filterParams } : {}),\n    ...(reference.searchParam ? { searchParam: reference.searchParam } : {}),\n    ...(operation.resultPath ? { resultPath: operation.resultPath } : {}),\n    // `jsonRpcEnvelope` is deliberately NOT projected: a provider operation has no JSON-RPC\n    // concept, so a reference can never produce one. A JSON-RPC read surface stays inline.\n  };\n}\n"]}

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.d.ts

@@ -5,7 +5,8 @@
  * rate budget. Engine-independent by design (no DI, no ErrorBuilder): the adapter maps
  * {@link HttpApiTransportError} into its ordinary error projection.
  */
-import type { HttpApiErasureOperationMethod, HttpApiRemoteCallSemantics, HttpApiRestOperationMethod } from '@wildo-ai/saas-models/external-data';
+import type { API_HttpMethod } from '@wildo-ai/external-connectors-models';
+import type { HttpApiRemoteCallSemantics } from '@wildo-ai/saas-models/external-data';
 /**
  * How a transport attempt failed — each member names a DIFFERENT remedy: TIMEOUT/NETWORK are
  * environmental (retryable), REMOTE_ERROR carries the target's own final answer, INVALID_JSON is
@@ -18,33 +19,99 @@ export declare enum HttpApiTransportFailureKind {
     INVALID_JSON = "INVALID_JSON",
     RATE_BUDGET_EXHAUSTED = "RATE_BUDGET_EXHAUSTED"
 }
-/** Minimal fetch shape — injectable so unit tests run without a network. */
+/**
+ * Minimal fetch shape — injectable so unit tests run without a network.
+ *
+ * `body` widened beyond `string` for S3a (#331): a hand-authored provider operation may upload a
+ * file (`FormData`, so the platform picks the multipart boundary — a transport that wrote its own
+ * `Content-Type` would produce a boundary the body does not use) or send raw bytes.
+ */
 export type HttpApiFetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
-    body?: string;
+    body?: string | FormData | Uint8Array;
     signal?: AbortSignal;
 }) => Promise<{
     status: number;
     ok: boolean;
     text(): Promise<string>;
 }>;
+/**
+ * How a request body is encoded on the wire. Slice 1 needed JSON alone, because every ETL call is
+ * a read; a hand-authored WRITE reaches vendors that take form bodies and file uploads, so the
+ * encoding is carried on the request rather than inferred from the method.
+ */
+export declare enum HttpApiTransportBodyEncoding {
+    JSON = "json",
+    FORM_URLENCODED = "form-urlencoded",
+    /** `FormData`; the transport sends NO `Content-Type`, so the platform sets it with its boundary. */
+    MULTIPART = "multipart",
+    /** A raw text body under a caller-declared media type. */
+    TEXT = "text",
+    /** Raw bytes under a caller-declared media type. */
+    BINARY = "binary"
+}
+/** The request body, discriminated so each encoding carries exactly what it needs. */
+export type HttpApiTransportBody = {
+    encoding: HttpApiTransportBodyEncoding.JSON;
+    value: unknown;
+} | {
+    encoding: HttpApiTransportBodyEncoding.FORM_URLENCODED;
+    value: Readonly<Record<string, string>>;
+} | {
+    encoding: HttpApiTransportBodyEncoding.MULTIPART;
+    value: FormData;
+} | {
+    encoding: HttpApiTransportBodyEncoding.TEXT;
+    value: string;
+    contentType: string;
+} | {
+    encoding: HttpApiTransportBodyEncoding.BINARY;
+    value: Uint8Array;
+    contentType: string;
+};
+/** How the RESPONSE body is decoded. */
+export declare enum HttpApiTransportResponseDecoding {
+    /** Parse as JSON; a 2xx with an unparsable body is a contract failure at the target. */
+    JSON = "json",
+    /** Keep the raw text (a CSV export, an XML document); nothing is parsed. */
+    TEXT = "text",
+    /** Read nothing — for a write whose body carries no information (a 204). */
+    NONE = "none"
+}
 export interface HttpApiTransportRequest {
     /**
-     * Read-family methods, plus the erasure family's `DELETE` — the transport is deliberately
-     * method-agnostic plumbing; WHICH methods a caller may compile is governed one layer up (the
-     * read compilers speak GET/POST, only the stance-6b erasure door speaks DELETE).
+     * The transport is deliberately method-agnostic plumbing; WHICH methods a caller may compile is
+     * governed one layer up (the read compilers speak GET/POST, the stance-6b erasure door speaks
+     * DELETE, a provider operation speaks whatever it declares). The vocabulary is
+     * `API_HttpMethod` — the one named HTTP-method source this repository already has — rather than
+     * a third list beside the two read/erasure ones.
      */
-    method: `${HttpApiRestOperationMethod}` | `${HttpApiErasureOperationMethod}`;
+    method: `${API_HttpMethod}`;
     url: string;
     headers: Record<string, string>;
-    /** JSON body, serialized by the transport (POST-shaped reads: JSON-RPC, search endpoints). */
-    jsonBody?: unknown;
+    body?: HttpApiTransportBody;
+    /** Absent = {@link HttpApiTransportResponseDecoding.JSON}, which is what every caller did before S3a. */
+    responseDecoding?: HttpApiTransportResponseDecoding;
+    /**
+     * Whether re-sending this exact request is safe. REQUIRED, and deliberately not defaulted from
+     * the method.
+     *
+     * Before S3a every call through here was a read or a delete-by-key, so retrying a timeout was
+     * always right and the policy could stay implicit. The moment a hand-authored PUT/PATCH/POST
+     * write arrives, an implicit retry duplicates it — and a default derived from the method would
+     * be wrong in BOTH directions: it would stop retrying the POST-shaped reads the ETL depends on
+     * (JSON-RPC, search endpoints), and it would happily retry a POST that charges a card. So each
+     * caller answers, and the compiler makes every framing site answer.
+     */
+    retrySafe: boolean;
 }
 export interface HttpApiTransportResponse {
     status: number;
-    /** Parsed JSON body; `undefined` for an empty body. */
+    /** Parsed JSON body; `undefined` for an empty body or a non-JSON decoding. */
     json: unknown;
+    /** Raw body text, present for {@link HttpApiTransportResponseDecoding.TEXT}. */
+    text?: string;
 }
 /**
  * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal
@@ -83,11 +150,19 @@ export declare class HttpApiRateBudget {
     tryConsume(nowMs?: number): boolean;
 }
 /**
- * Execute one remote read-family call under the binding's semantics.
+ * Execute one remote call under the caller's semantics.
+ *
+ * Retry applies to a timeout, a network error, or a retryable status (429/502/503/504) — and ONLY
+ * when the request declares itself `retrySafe`. Any other non-2xx status is a terminal remote
+ * answer and is thrown on the first attempt: retrying a 400/401/403/404 re-asks a question whose
+ * answer is final.
  *
- * Retry policy applies to IDEMPOTENT failures only: a timeout, a network error, or a retryable
- * status (429/502/503/504). Any other non-2xx status is a terminal remote answer and is thrown
- * on the first attempt — retrying a 400/401/403/404 re-asks a question whose answer is final.
+ * The `retrySafe` gate arrived with S3a (#331). Every call before it was a read or a
+ * delete-by-key, so the policy could be "retry every transient" and be right; a hand-authored
+ * write makes that policy a duplicate-submission engine. Note a 429 is gated too, and that is
+ * deliberate rather than an oversight: a 429 means the vendor did not act, but a TIMEOUT on the
+ * same request means we do not know whether it acted, and one gate that is honest about both
+ * beats two that invite the reader to work out which case they are in.
  */
 export declare function executeHttpApiTransportCall(request: HttpApiTransportRequest, semantics: Pick<HttpApiRemoteCallSemantics, 'timeoutMs' | 'retry'>, fetchImpl: HttpApiFetchLike, rateBudget?: HttpApiRateBudget): Promise<HttpApiTransportResponse>;
 //# sourceMappingURL=http-api-transport.backend.d.ts.map

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-transport.backend.d.ts","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,qCAAqC,CAAC;AAE7C;;;;GAIG;AACH,oBAAY,2BAA2B;IACrC,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,qBAAqB,0BAA0B;CAChD;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,MAAM,EAAE,GAAG,0BAA0B,EAAE,GAAG,GAAG,6BAA6B,EAAE,CAAC;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,MAAM,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,gFAAgF;QAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;KAC5C;gBARD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,gFAAgF;QAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;KAC5C;CAKJ;AAID;;;;;GAKG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAFlD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;gBAEd,oBAAoB,CAAC,EAAE,MAAM;IAE1D,mGAAmG;IACnG,UAAU,CAAC,KAAK,GAAE,MAAmB,GAAG,OAAO;CAUhD;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,uBAAuB,EAChC,SAAS,EAAE,IAAI,CAAC,0BAA0B,EAAE,WAAW,GAAG,OAAO,CAAC,EAClE,SAAS,EAAE,gBAAgB,EAC3B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAmFnC"}
+{"version":3,"file":"http-api-transport.backend.d.ts","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"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"}

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.js

@@ -18,6 +18,32 @@ export var HttpApiTransportFailureKind;
     HttpApiTransportFailureKind["INVALID_JSON"] = "INVALID_JSON";
     HttpApiTransportFailureKind["RATE_BUDGET_EXHAUSTED"] = "RATE_BUDGET_EXHAUSTED";
 })(HttpApiTransportFailureKind || (HttpApiTransportFailureKind = {}));
+/**
+ * How a request body is encoded on the wire. Slice 1 needed JSON alone, because every ETL call is
+ * a read; a hand-authored WRITE reaches vendors that take form bodies and file uploads, so the
+ * encoding is carried on the request rather than inferred from the method.
+ */
+export var HttpApiTransportBodyEncoding;
+(function (HttpApiTransportBodyEncoding) {
+    HttpApiTransportBodyEncoding["JSON"] = "json";
+    HttpApiTransportBodyEncoding["FORM_URLENCODED"] = "form-urlencoded";
+    /** `FormData`; the transport sends NO `Content-Type`, so the platform sets it with its boundary. */
+    HttpApiTransportBodyEncoding["MULTIPART"] = "multipart";
+    /** A raw text body under a caller-declared media type. */
+    HttpApiTransportBodyEncoding["TEXT"] = "text";
+    /** Raw bytes under a caller-declared media type. */
+    HttpApiTransportBodyEncoding["BINARY"] = "binary";
+})(HttpApiTransportBodyEncoding || (HttpApiTransportBodyEncoding = {}));
+/** How the RESPONSE body is decoded. */
+export var HttpApiTransportResponseDecoding;
+(function (HttpApiTransportResponseDecoding) {
+    /** Parse as JSON; a 2xx with an unparsable body is a contract failure at the target. */
+    HttpApiTransportResponseDecoding["JSON"] = "json";
+    /** Keep the raw text (a CSV export, an XML document); nothing is parsed. */
+    HttpApiTransportResponseDecoding["TEXT"] = "text";
+    /** Read nothing — for a write whose body carries no information (a 204). */
+    HttpApiTransportResponseDecoding["NONE"] = "none";
+})(HttpApiTransportResponseDecoding || (HttpApiTransportResponseDecoding = {}));
 /**
  * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal
  * names the remote reality instead of a generic network error. Never carries the request
@@ -59,11 +85,46 @@ export class HttpApiRateBudget {
     }
 }
 /**
- * Execute one remote read-family call under the binding's semantics.
+ * Frame one request body: the wire bytes and the `Content-Type` that describes them.
+ *
+ * MULTIPART deliberately contributes NO header — `FormData` carries a boundary the platform
+ * generates while serializing, and a `Content-Type` written here would name a different one, so
+ * the target would parse zero parts from a body that looks well formed.
+ */
+function frameBody(body) {
+    if (body === undefined)
+        return {};
+    switch (body.encoding) {
+        case HttpApiTransportBodyEncoding.JSON:
+            return { payload: JSON.stringify(body.value), contentType: 'application/json' };
+        case HttpApiTransportBodyEncoding.FORM_URLENCODED:
+            return { payload: new URLSearchParams(body.value).toString(), contentType: 'application/x-www-form-urlencoded' };
+        case HttpApiTransportBodyEncoding.MULTIPART:
+            return { payload: body.value };
+        case HttpApiTransportBodyEncoding.TEXT:
+            return { payload: body.value, contentType: body.contentType };
+        case HttpApiTransportBodyEncoding.BINARY:
+            return { payload: body.value, contentType: body.contentType };
+        default: {
+            const exhaustiveCheck = body;
+            return exhaustiveCheck;
+        }
+    }
+}
+/**
+ * Execute one remote call under the caller's semantics.
+ *
+ * Retry applies to a timeout, a network error, or a retryable status (429/502/503/504) — and ONLY
+ * when the request declares itself `retrySafe`. Any other non-2xx status is a terminal remote
+ * answer and is thrown on the first attempt: retrying a 400/401/403/404 re-asks a question whose
+ * answer is final.
  *
- * Retry policy applies to IDEMPOTENT failures only: a timeout, a network error, or a retryable
- * status (429/502/503/504). Any other non-2xx status is a terminal remote answer and is thrown
- * on the first attempt — retrying a 400/401/403/404 re-asks a question whose answer is final.
+ * The `retrySafe` gate arrived with S3a (#331). Every call before it was a read or a
+ * delete-by-key, so the policy could be "retry every transient" and be right; a hand-authored
+ * write makes that policy a duplicate-submission engine. Note a 429 is gated too, and that is
+ * deliberate rather than an oversight: a 429 means the vendor did not act, but a TIMEOUT on the
+ * same request means we do not know whether it acted, and one gate that is honest about both
+ * beats two that invite the reader to work out which case they are in.
  */
 export async function executeHttpApiTransportCall(request, semantics, fetchImpl, rateBudget) {
     if (rateBudget && !rateBudget.tryConsume()) {
@@ -78,23 +139,33 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
         const abort = new AbortController();
         const timeout = setTimeout(() => abort.abort(), semantics.timeoutMs);
         try {
+            const framed = frameBody(request.body);
             const response = await fetchImpl(request.url, {
                 method: request.method,
-                headers: request.jsonBody === undefined
+                // The caller's own headers win: a provider that must send its own `Content-Type` for a
+                // text body has already declared it, and the framing default must not overwrite it.
+                headers: framed.contentType === undefined
                     ? request.headers
-                    : { 'Content-Type': 'application/json', ...request.headers },
-                body: request.jsonBody === undefined ? undefined : JSON.stringify(request.jsonBody),
+                    : { 'Content-Type': framed.contentType, ...request.headers },
+                body: framed.payload,
                 signal: abort.signal,
             });
             const bodyText = await response.text();
             if (!response.ok) {
                 const error = new HttpApiTransportError(`HTTP-API remote answered ${response.status} for ${request.method} ${request.url}`, { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.REMOTE_ERROR });
-                if (RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {
+                if (request.retrySafe && RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {
                     lastError = error;
                     continue;
                 }
                 throw error;
             }
+            const decoding = request.responseDecoding ?? HttpApiTransportResponseDecoding.JSON;
+            if (decoding === HttpApiTransportResponseDecoding.NONE) {
+                return { status: response.status, json: undefined };
+            }
+            if (decoding === HttpApiTransportResponseDecoding.TEXT) {
+                return { status: response.status, json: undefined, text: bodyText };
+            }
             if (bodyText.length === 0) {
                 return { status: response.status, json: undefined };
             }
@@ -108,7 +179,7 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
         }
         catch (error) {
             if (error instanceof HttpApiTransportError) {
-                if (error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {
+                if (request.retrySafe && error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {
                     lastError = error;
                     continue;
                 }
@@ -118,7 +189,7 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
             const transportError = new HttpApiTransportError(isAbort
                 ? `HTTP-API call timed out after ${semantics.timeoutMs}ms: ${request.method} ${request.url}`
                 : `HTTP-API network failure for ${request.method} ${request.url}: ${error instanceof Error ? error.message : String(error)}`, { url: request.url, method: request.method, attempts: attempt, kind: isAbort ? HttpApiTransportFailureKind.TIMEOUT : HttpApiTransportFailureKind.NETWORK });
-            if (attempt < maxAttempts) {
+            if (request.retrySafe && attempt < maxAttempts) {
                 lastError = transportError;
                 continue;
             }
@@ -128,7 +199,9 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
             clearTimeout(timeout);
         }
     }
-    // Unreachable while the loop throws on its last attempt; kept for control-flow honesty.
+    // Unreachable: every path in the loop either returns or throws — a non-retry-safe request
+    // throws on its first attempt, and a retry-safe one throws on its last. Kept for control-flow
+    // honesty, and because a future edit that adds a `continue` should land somewhere honest.
     throw lastError ?? new HttpApiTransportError(`HTTP-API call failed for ${request.method} ${request.url}`, { url: request.url, method: request.method, attempts: maxAttempts, kind: HttpApiTransportFailureKind.NETWORK });
 }
 function delay(ms) {

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-transport.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP transport for the HTTP-API resource repository — the ONE place a remote call leaves the\n * process, carrying the binding's declared remote-call semantics (ETL decision D10 / R15):\n * per-call timeout, bounded retry for idempotent read-family calls only, and an optional local\n * rate budget. Engine-independent by design (no DI, no ErrorBuilder): the adapter maps\n * {@link HttpApiTransportError} into its ordinary error projection.\n */\n\nimport type {\n  HttpApiErasureOperationMethod,\n  HttpApiRemoteCallSemantics,\n  HttpApiRestOperationMethod,\n} from '@wildo-ai/saas-models/external-data';\n\n/**\n * How a transport attempt failed — each member names a DIFFERENT remedy: TIMEOUT/NETWORK are\n * environmental (retryable), REMOTE_ERROR carries the target's own final answer, INVALID_JSON is\n * a contract breach at the target, RATE_BUDGET_EXHAUSTED is the binding's own local ceiling.\n */\nexport enum HttpApiTransportFailureKind {\n  TIMEOUT = 'TIMEOUT',\n  NETWORK = 'NETWORK',\n  REMOTE_ERROR = 'REMOTE_ERROR',\n  INVALID_JSON = 'INVALID_JSON',\n  RATE_BUDGET_EXHAUSTED = 'RATE_BUDGET_EXHAUSTED',\n}\n\n/** Minimal fetch shape — injectable so unit tests run without a network. */\nexport type HttpApiFetchLike = (\n  url: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n    body?: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  status: number;\n  ok: boolean;\n  text(): Promise<string>;\n}>;\n\nexport interface HttpApiTransportRequest {\n  /**\n   * Read-family methods, plus the erasure family's `DELETE` — the transport is deliberately\n   * method-agnostic plumbing; WHICH methods a caller may compile is governed one layer up (the\n   * read compilers speak GET/POST, only the stance-6b erasure door speaks DELETE).\n   */\n  method: `${HttpApiRestOperationMethod}` | `${HttpApiErasureOperationMethod}`;\n  url: string;\n  headers: Record<string, string>;\n  /** JSON body, serialized by the transport (POST-shaped reads: JSON-RPC, search endpoints). */\n  jsonBody?: unknown;\n}\n\nexport interface HttpApiTransportResponse {\n  status: number;\n  /** Parsed JSON body; `undefined` for an empty body. */\n  json: unknown;\n}\n\n/**\n * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal\n * names the remote reality instead of a generic network error. Never carries the request\n * headers (they hold credentials).\n */\nexport class HttpApiTransportError extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly url: string;\n      readonly method: string;\n      /** HTTP status of the LAST attempt; undefined when no response was received. */\n      readonly status?: number;\n      readonly attempts: number;\n      readonly kind: HttpApiTransportFailureKind;\n    },\n  ) {\n    super(message);\n    this.name = 'HttpApiTransportError';\n  }\n}\n\nconst RETRYABLE_STATUS = new Set([429, 502, 503, 504]);\n\n/**\n * A per-binding local rate budget (`maxRequestsPerMinute`) — a sliding-window counter, not a\n * fairness scheduler. When the window is full the call REFUSES immediately rather than queueing:\n * queueing inside a request lifecycle turns a rate problem into a latency problem the caller\n * cannot see (scope-down paper: refusal is the honest failure mode).\n */\nexport class HttpApiRateBudget {\n  private readonly timestamps: number[] = [];\n\n  constructor(private readonly maxRequestsPerMinute?: number) {}\n\n  /** Returns true when the call may proceed (and records it); false when the budget is exhausted. */\n  tryConsume(nowMs: number = Date.now()): boolean {\n    if (this.maxRequestsPerMinute === undefined) return true;\n    const windowStart = nowMs - 60_000;\n    while (this.timestamps.length > 0 && this.timestamps[0] <= windowStart) {\n      this.timestamps.shift();\n    }\n    if (this.timestamps.length >= this.maxRequestsPerMinute) return false;\n    this.timestamps.push(nowMs);\n    return true;\n  }\n}\n\n/**\n * Execute one remote read-family call under the binding's semantics.\n *\n * Retry policy applies to IDEMPOTENT failures only: a timeout, a network error, or a retryable\n * status (429/502/503/504). Any other non-2xx status is a terminal remote answer and is thrown\n * on the first attempt — retrying a 400/401/403/404 re-asks a question whose answer is final.\n */\nexport async function executeHttpApiTransportCall(\n  request: HttpApiTransportRequest,\n  semantics: Pick<HttpApiRemoteCallSemantics, 'timeoutMs' | 'retry'>,\n  fetchImpl: HttpApiFetchLike,\n  rateBudget?: HttpApiRateBudget,\n): Promise<HttpApiTransportResponse> {\n  if (rateBudget && !rateBudget.tryConsume()) {\n    throw new HttpApiTransportError(\n      `HTTP-API rate budget exhausted for ${request.method} ${request.url}`,\n      { url: request.url, method: request.method, attempts: 0, kind: HttpApiTransportFailureKind.RATE_BUDGET_EXHAUSTED },\n    );\n  }\n\n  const maxAttempts = semantics.retry.maxAttempts;\n  let lastError: HttpApiTransportError | undefined;\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {\n    if (attempt > 1) {\n      await delay(semantics.retry.backoffMs * (attempt - 1));\n    }\n\n    const abort = new AbortController();\n    const timeout = setTimeout(() => abort.abort(), semantics.timeoutMs);\n    try {\n      const response = await fetchImpl(request.url, {\n        method: request.method,\n        headers: request.jsonBody === undefined\n          ? request.headers\n          : { 'Content-Type': 'application/json', ...request.headers },\n        body: request.jsonBody === undefined ? undefined : JSON.stringify(request.jsonBody),\n        signal: abort.signal,\n      });\n      const bodyText = await response.text();\n\n      if (!response.ok) {\n        const error = new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.REMOTE_ERROR },\n        );\n        if (RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n\n      if (bodyText.length === 0) {\n        return { status: response.status, json: undefined };\n      }\n      try {\n        return { status: response.status, json: JSON.parse(bodyText) };\n      } catch {\n        // A 2xx with unparsable JSON is a CONTRACT failure, not a transient — never retried.\n        throw new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} with a non-JSON body for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.INVALID_JSON },\n        );\n      }\n    } catch (error) {\n      if (error instanceof HttpApiTransportError) {\n        if (error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n      const isAbort = error instanceof Error && error.name === 'AbortError';\n      const transportError = new HttpApiTransportError(\n        isAbort\n          ? `HTTP-API call timed out after ${semantics.timeoutMs}ms: ${request.method} ${request.url}`\n          : `HTTP-API network failure for ${request.method} ${request.url}: ${error instanceof Error ? error.message : String(error)}`,\n        { url: request.url, method: request.method, attempts: attempt, kind: isAbort ? HttpApiTransportFailureKind.TIMEOUT : HttpApiTransportFailureKind.NETWORK },\n      );\n      if (attempt < maxAttempts) {\n        lastError = transportError;\n        continue;\n      }\n      throw transportError;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n\n  // Unreachable while the loop throws on its last attempt; kept for control-flow honesty.\n  throw lastError ?? new HttpApiTransportError(\n    `HTTP-API call failed for ${request.method} ${request.url}`,\n    { url: request.url, method: request.method, attempts: maxAttempts, kind: HttpApiTransportFailureKind.NETWORK },\n  );\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}
+{"version":3,"file":"http-api-transport.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP transport for the HTTP-API resource repository — the ONE place a remote call leaves the\n * process, carrying the binding's declared remote-call semantics (ETL decision D10 / R15):\n * per-call timeout, bounded retry for idempotent read-family calls only, and an optional local\n * rate budget. Engine-independent by design (no DI, no ErrorBuilder): the adapter maps\n * {@link HttpApiTransportError} into its ordinary error projection.\n */\n\nimport type { API_HttpMethod } from '@wildo-ai/external-connectors-models';\nimport type { HttpApiRemoteCallSemantics } from '@wildo-ai/saas-models/external-data';\n\n/**\n * How a transport attempt failed — each member names a DIFFERENT remedy: TIMEOUT/NETWORK are\n * environmental (retryable), REMOTE_ERROR carries the target's own final answer, INVALID_JSON is\n * a contract breach at the target, RATE_BUDGET_EXHAUSTED is the binding's own local ceiling.\n */\nexport enum HttpApiTransportFailureKind {\n  TIMEOUT = 'TIMEOUT',\n  NETWORK = 'NETWORK',\n  REMOTE_ERROR = 'REMOTE_ERROR',\n  INVALID_JSON = 'INVALID_JSON',\n  RATE_BUDGET_EXHAUSTED = 'RATE_BUDGET_EXHAUSTED',\n}\n\n/**\n * Minimal fetch shape — injectable so unit tests run without a network.\n *\n * `body` widened beyond `string` for S3a (#331): a hand-authored provider operation may upload a\n * file (`FormData`, so the platform picks the multipart boundary — a transport that wrote its own\n * `Content-Type` would produce a boundary the body does not use) or send raw bytes.\n */\nexport type HttpApiFetchLike = (\n  url: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n    body?: string | FormData | Uint8Array;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  status: number;\n  ok: boolean;\n  text(): Promise<string>;\n}>;\n\n/**\n * How a request body is encoded on the wire. Slice 1 needed JSON alone, because every ETL call is\n * a read; a hand-authored WRITE reaches vendors that take form bodies and file uploads, so the\n * encoding is carried on the request rather than inferred from the method.\n */\nexport enum HttpApiTransportBodyEncoding {\n  JSON = 'json',\n  FORM_URLENCODED = 'form-urlencoded',\n  /** `FormData`; the transport sends NO `Content-Type`, so the platform sets it with its boundary. */\n  MULTIPART = 'multipart',\n  /** A raw text body under a caller-declared media type. */\n  TEXT = 'text',\n  /** Raw bytes under a caller-declared media type. */\n  BINARY = 'binary',\n}\n\n/** The request body, discriminated so each encoding carries exactly what it needs. */\nexport type HttpApiTransportBody =\n  | { encoding: HttpApiTransportBodyEncoding.JSON; value: unknown }\n  | { encoding: HttpApiTransportBodyEncoding.FORM_URLENCODED; value: Readonly<Record<string, string>> }\n  | { encoding: HttpApiTransportBodyEncoding.MULTIPART; value: FormData }\n  | { encoding: HttpApiTransportBodyEncoding.TEXT; value: string; contentType: string }\n  | { encoding: HttpApiTransportBodyEncoding.BINARY; value: Uint8Array; contentType: string };\n\n/** How the RESPONSE body is decoded. */\nexport enum HttpApiTransportResponseDecoding {\n  /** Parse as JSON; a 2xx with an unparsable body is a contract failure at the target. */\n  JSON = 'json',\n  /** Keep the raw text (a CSV export, an XML document); nothing is parsed. */\n  TEXT = 'text',\n  /** Read nothing — for a write whose body carries no information (a 204). */\n  NONE = 'none',\n}\n\nexport interface HttpApiTransportRequest {\n  /**\n   * The transport is deliberately method-agnostic plumbing; WHICH methods a caller may compile is\n   * governed one layer up (the read compilers speak GET/POST, the stance-6b erasure door speaks\n   * DELETE, a provider operation speaks whatever it declares). The vocabulary is\n   * `API_HttpMethod` — the one named HTTP-method source this repository already has — rather than\n   * a third list beside the two read/erasure ones.\n   */\n  method: `${API_HttpMethod}`;\n  url: string;\n  headers: Record<string, string>;\n  body?: HttpApiTransportBody;\n  /** Absent = {@link HttpApiTransportResponseDecoding.JSON}, which is what every caller did before S3a. */\n  responseDecoding?: HttpApiTransportResponseDecoding;\n  /**\n   * Whether re-sending this exact request is safe. REQUIRED, and deliberately not defaulted from\n   * the method.\n   *\n   * Before S3a every call through here was a read or a delete-by-key, so retrying a timeout was\n   * always right and the policy could stay implicit. The moment a hand-authored PUT/PATCH/POST\n   * write arrives, an implicit retry duplicates it — and a default derived from the method would\n   * be wrong in BOTH directions: it would stop retrying the POST-shaped reads the ETL depends on\n   * (JSON-RPC, search endpoints), and it would happily retry a POST that charges a card. So each\n   * caller answers, and the compiler makes every framing site answer.\n   */\n  retrySafe: boolean;\n}\n\nexport interface HttpApiTransportResponse {\n  status: number;\n  /** Parsed JSON body; `undefined` for an empty body or a non-JSON decoding. */\n  json: unknown;\n  /** Raw body text, present for {@link HttpApiTransportResponseDecoding.TEXT}. */\n  text?: string;\n}\n\n/**\n * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal\n * names the remote reality instead of a generic network error. Never carries the request\n * headers (they hold credentials).\n */\nexport class HttpApiTransportError extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly url: string;\n      readonly method: string;\n      /** HTTP status of the LAST attempt; undefined when no response was received. */\n      readonly status?: number;\n      readonly attempts: number;\n      readonly kind: HttpApiTransportFailureKind;\n    },\n  ) {\n    super(message);\n    this.name = 'HttpApiTransportError';\n  }\n}\n\nconst RETRYABLE_STATUS = new Set([429, 502, 503, 504]);\n\n/**\n * A per-binding local rate budget (`maxRequestsPerMinute`) — a sliding-window counter, not a\n * fairness scheduler. When the window is full the call REFUSES immediately rather than queueing:\n * queueing inside a request lifecycle turns a rate problem into a latency problem the caller\n * cannot see (scope-down paper: refusal is the honest failure mode).\n */\nexport class HttpApiRateBudget {\n  private readonly timestamps: number[] = [];\n\n  constructor(private readonly maxRequestsPerMinute?: number) {}\n\n  /** Returns true when the call may proceed (and records it); false when the budget is exhausted. */\n  tryConsume(nowMs: number = Date.now()): boolean {\n    if (this.maxRequestsPerMinute === undefined) return true;\n    const windowStart = nowMs - 60_000;\n    while (this.timestamps.length > 0 && this.timestamps[0] <= windowStart) {\n      this.timestamps.shift();\n    }\n    if (this.timestamps.length >= this.maxRequestsPerMinute) return false;\n    this.timestamps.push(nowMs);\n    return true;\n  }\n}\n\n/**\n * Frame one request body: the wire bytes and the `Content-Type` that describes them.\n *\n * MULTIPART deliberately contributes NO header — `FormData` carries a boundary the platform\n * generates while serializing, and a `Content-Type` written here would name a different one, so\n * the target would parse zero parts from a body that looks well formed.\n */\nfunction frameBody(body: HttpApiTransportBody | undefined): { payload?: string | FormData | Uint8Array; contentType?: string } {\n  if (body === undefined) return {};\n  switch (body.encoding) {\n    case HttpApiTransportBodyEncoding.JSON:\n      return { payload: JSON.stringify(body.value), contentType: 'application/json' };\n    case HttpApiTransportBodyEncoding.FORM_URLENCODED:\n      return { payload: new URLSearchParams(body.value as Record<string, string>).toString(), contentType: 'application/x-www-form-urlencoded' };\n    case HttpApiTransportBodyEncoding.MULTIPART:\n      return { payload: body.value };\n    case HttpApiTransportBodyEncoding.TEXT:\n      return { payload: body.value, contentType: body.contentType };\n    case HttpApiTransportBodyEncoding.BINARY:\n      return { payload: body.value, contentType: body.contentType };\n    default: {\n      const exhaustiveCheck: never = body;\n      return exhaustiveCheck;\n    }\n  }\n}\n\n/**\n * Execute one remote call under the caller's semantics.\n *\n * Retry applies to a timeout, a network error, or a retryable status (429/502/503/504) — and ONLY\n * when the request declares itself `retrySafe`. Any other non-2xx status is a terminal remote\n * answer and is thrown on the first attempt: retrying a 400/401/403/404 re-asks a question whose\n * answer is final.\n *\n * The `retrySafe` gate arrived with S3a (#331). Every call before it was a read or a\n * delete-by-key, so the policy could be \"retry every transient\" and be right; a hand-authored\n * write makes that policy a duplicate-submission engine. Note a 429 is gated too, and that is\n * deliberate rather than an oversight: a 429 means the vendor did not act, but a TIMEOUT on the\n * same request means we do not know whether it acted, and one gate that is honest about both\n * beats two that invite the reader to work out which case they are in.\n */\nexport async function executeHttpApiTransportCall(\n  request: HttpApiTransportRequest,\n  semantics: Pick<HttpApiRemoteCallSemantics, 'timeoutMs' | 'retry'>,\n  fetchImpl: HttpApiFetchLike,\n  rateBudget?: HttpApiRateBudget,\n): Promise<HttpApiTransportResponse> {\n  if (rateBudget && !rateBudget.tryConsume()) {\n    throw new HttpApiTransportError(\n      `HTTP-API rate budget exhausted for ${request.method} ${request.url}`,\n      { url: request.url, method: request.method, attempts: 0, kind: HttpApiTransportFailureKind.RATE_BUDGET_EXHAUSTED },\n    );\n  }\n\n  const maxAttempts = semantics.retry.maxAttempts;\n  let lastError: HttpApiTransportError | undefined;\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {\n    if (attempt > 1) {\n      await delay(semantics.retry.backoffMs * (attempt - 1));\n    }\n\n    const abort = new AbortController();\n    const timeout = setTimeout(() => abort.abort(), semantics.timeoutMs);\n    try {\n      const framed = frameBody(request.body);\n      const response = await fetchImpl(request.url, {\n        method: request.method,\n        // The caller's own headers win: a provider that must send its own `Content-Type` for a\n        // text body has already declared it, and the framing default must not overwrite it.\n        headers: framed.contentType === undefined\n          ? request.headers\n          : { 'Content-Type': framed.contentType, ...request.headers },\n        body: framed.payload,\n        signal: abort.signal,\n      });\n      const bodyText = await response.text();\n\n      if (!response.ok) {\n        const error = new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.REMOTE_ERROR },\n        );\n        if (request.retrySafe && RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n\n      const decoding = request.responseDecoding ?? HttpApiTransportResponseDecoding.JSON;\n      if (decoding === HttpApiTransportResponseDecoding.NONE) {\n        return { status: response.status, json: undefined };\n      }\n      if (decoding === HttpApiTransportResponseDecoding.TEXT) {\n        return { status: response.status, json: undefined, text: bodyText };\n      }\n      if (bodyText.length === 0) {\n        return { status: response.status, json: undefined };\n      }\n      try {\n        return { status: response.status, json: JSON.parse(bodyText) };\n      } catch {\n        // A 2xx with unparsable JSON is a CONTRACT failure, not a transient — never retried.\n        throw new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} with a non-JSON body for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.INVALID_JSON },\n        );\n      }\n    } catch (error) {\n      if (error instanceof HttpApiTransportError) {\n        if (request.retrySafe && error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n      const isAbort = error instanceof Error && error.name === 'AbortError';\n      const transportError = new HttpApiTransportError(\n        isAbort\n          ? `HTTP-API call timed out after ${semantics.timeoutMs}ms: ${request.method} ${request.url}`\n          : `HTTP-API network failure for ${request.method} ${request.url}: ${error instanceof Error ? error.message : String(error)}`,\n        { url: request.url, method: request.method, attempts: attempt, kind: isAbort ? HttpApiTransportFailureKind.TIMEOUT : HttpApiTransportFailureKind.NETWORK },\n      );\n      if (request.retrySafe && attempt < maxAttempts) {\n        lastError = transportError;\n        continue;\n      }\n      throw transportError;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n\n  // Unreachable: every path in the loop either returns or throws — a non-retry-safe request\n  // throws on its first attempt, and a retry-safe one throws on its last. Kept for control-flow\n  // honesty, and because a future edit that adds a `continue` should land somewhere honest.\n  throw lastError ?? new HttpApiTransportError(\n    `HTTP-API call failed for ${request.method} ${request.url}`,\n    { url: request.url, method: request.method, attempts: maxAttempts, kind: HttpApiTransportFailureKind.NETWORK },\n  );\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}

package/dist/esm/base-classes/services/repositories/http-api/odata-query-compiler.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"odata-query-compiler.backend.d.ts","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/odata-query-compiler.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAEV,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,UAAU,iBAAiB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC/C;AAgDD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,GACjB,MAAM,CASR;AAED,0CAA0C;AAC1C,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,GACjB,oBAAoB,CAKtB;AAoCD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,sBAAsB,EAC7B,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,oBAAoB,CA8CtB;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,iBAAiB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAClD,OAAO,EAAE;IACP,iFAAiF;IACjF,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,yFAAyF;IACzF,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,oBAAoB,CAYtB;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,sBAAsB,GAC5B,oBAAoB,CAQtB"}
+{"version":3,"file":"odata-query-compiler.backend.d.ts","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/odata-query-compiler.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAEV,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,UAAU,iBAAiB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC/C;AAgDD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,GACjB,MAAM,CASR;AAED,0CAA0C;AAC1C,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,GACjB,oBAAoB,CAKtB;AAoCD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,sBAAsB,EAC7B,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,oBAAoB,CA8CtB;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,iBAAiB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAClD,OAAO,EAAE;IACP,iFAAiF;IACjF,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,yFAAyF;IACzF,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,oBAAoB,CA4BtB;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,sBAAsB,GAC5B,oBAAoB,CAQtB"}

package/dist/esm/base-classes/services/repositories/http-api/odata-query-compiler.backend.js

@@ -161,8 +161,24 @@ export function compileODataCollectionRead(binding, query, options) {
  * per run.
  */
 export function compileODataExtractionFirstPage(binding, options) {
+    // `$orderby` on the KEY components, ascending, is not decoration — it is what makes the paged
+    // extraction drift-safe, and following `@odata.nextLink` alone does NOT provide it.
+    //
+    // Dataverse builds its paging cookie from the LAST ROW of the previous page under the query's
+    // own order, and its documentation is explicit that without a deterministic order "the same
+    // record can appear in more than one page" — it recommends ordering on the primary key, which is
+    // exactly what a binding's `keyFields` are. A duplicated row would be re-upserted (harmless), but
+    // a SKIPPED one is silently absent from a COMPLETE pass, and a complete pass is what authorizes
+    // the orphan stage — so a skip does not merely lose a row, it can orphan a live one.
+    // spec-cite: Microsoft Learn, "Page results using OData from Microsoft Dataverse Web API" —
+    // "Deterministic ordering is important" / "Without proper ordering, the same record can appear in
+    // more than one page."
+    //
+    // Key components are ordered as DECLARED: the schema already fixes their order for the composite
+    // key predicate, so reusing it keeps one source for "the key's component order".
     const params = {
         $select: [...new Set(options.selectRemoteFields)].join(','),
+        $orderby: binding.keyFields.map((keyField) => `${keyField.remoteField} asc`).join(','),
         $top: String(options.pageSize),
     };
     const filterFragments = Object.entries(options.sourceFilter ?? {}).map(([remoteField, value]) => `${remoteField} eq ${odataScalarLiteral(value)}`);

package/dist/esm/base-classes/services/repositories/http-api/odata-query-compiler.backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"odata-query-compiler.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/odata-query-compiler.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * OData v4 compiler: {@link HttpApiTranslatedQuery} + binding → URL path + query parameters.\n *\n * One generic implementation for every OData target (SAP S/4HANA, Dataverse — ETL decision D0).\n * Purely mechanical: every predicate arriving here is ALREADY admitted by the T-set translation;\n * this module never widens or narrows a query, it only spells it.\n *\n * Key-literal spelling follows the component CODEC declared on the binding (paper A): string\n * components are quoted with doubled single-quotes, integer/guid/datetime components are\n * unquoted — the OData v4 primitive-literal forms.\n */\n\nimport {\n  resolveHttpApiKeyComponents,\n} from '@wildo-ai/saas-models';\nimport {\n  HttpApiKeyComponentCodec,\n  type HttpApiKeyField,\n  type HttpApiFieldMapping,\n} from '@wildo-ai/saas-models/external-data';\n\nimport type {\n  HttpApiQueryScalar,\n  HttpApiTranslatedQuery,\n} from './http-api-query.backend';\n\nexport interface ODataCompiledRequest {\n  /** Path relative to the provider base URL, starting with '/'. */\n  path: string;\n  /** Query parameters, unencoded values (the transport URL-encodes once). */\n  params: Record<string, string>;\n}\n\ninterface ODataBindingShape {\n  entityRef: string;\n  keyFields: readonly HttpApiKeyField[];\n  fieldMappings: readonly HttpApiFieldMapping[];\n}\n\nfunction remoteFieldFor(binding: ODataBindingShape, localField: string): string {\n  const mapping = binding.fieldMappings.find((entry) => entry.localField === localField);\n  return mapping ? mapping.remoteField : localField;\n}\n\n/** OData string literal: single quotes doubled, wrapped in single quotes. */\nfunction odataStringLiteral(value: string): string {\n  return `'${value.replace(/'/g, \"''\")}'`;\n}\n\nfunction odataScalarLiteral(value: HttpApiQueryScalar): string {\n  if (typeof value === 'string') return odataStringLiteral(value);\n  if (value instanceof Date) return value.toISOString();\n  return String(value);\n}\n\nfunction odataKeyComponentLiteral(codec: HttpApiKeyComponentCodec, value: string | number): string {\n  switch (codec) {\n    case HttpApiKeyComponentCodec.STRING:\n      return odataStringLiteral(String(value));\n    case HttpApiKeyComponentCodec.INTEGER:\n    case HttpApiKeyComponentCodec.GUID:\n    case HttpApiKeyComponentCodec.DATETIME_ISO:\n      // OData v4 spells guid and datetimeoffset literals UNQUOTED in key predicates.\n      return String(value);\n  }\n}\n\n/**\n * Percent-encode the characters that break a URL PATH segment, leaving the predicate's\n * structural characters (`( ) = , '`) intact. `%` first, or the encoding re-encodes itself.\n * Applied to the finished predicate because these characters are never structural in one.\n * (The transport encodes QUERY params separately — this function must not run on `$filter`\n * fragments, or values would be double-encoded.)\n */\nfunction encodeODataPathPredicate(predicate: string): string {\n  return predicate\n    .replace(/%/g, '%25')\n    .replace(/ /g, '%20')\n    .replace(/\\?/g, '%3F')\n    .replace(/#/g, '%23')\n    .replace(/&/g, '%26')\n    .replace(/\\+/g, '%2B')\n    .replace(/\\//g, '%2F');\n}\n\n/**\n * The canonical key predicate for ONE row, from its synthesized id: `(K1=lit,K2=lit)` — or the\n * single-component short form `(lit)` when the binding declares one key field. PATH-encoded:\n * this predicate is only ever used as a URL path segment (the id-set `$filter` spelling lives in\n * `compileIdSetFilter`, which the transport's query-param encoding covers).\n */\nexport function compileODataKeyPredicate(\n  binding: ODataBindingShape,\n  resourceId: string,\n): string {\n  const components = resolveHttpApiKeyComponents(binding, resourceId);\n  if (binding.keyFields.length === 1) {\n    return encodeODataPathPredicate(`(${odataKeyComponentLiteral(binding.keyFields[0].codec, components[0])})`);\n  }\n  const parts = binding.keyFields.map(\n    (keyField, index) => `${keyField.remoteField}=${odataKeyComponentLiteral(keyField.codec, components[index])}`,\n  );\n  return encodeODataPathPredicate(`(${parts.join(',')})`);\n}\n\n/** Single-row read: `/EntitySet(key)`. */\nexport function compileODataKeyAddressedRead(\n  binding: ODataBindingShape,\n  resourceId: string,\n): ODataCompiledRequest {\n  return {\n    path: `/${binding.entityRef}${compileODataKeyPredicate(binding, resourceId)}`,\n    params: {},\n  };\n}\n\n/**\n * The id-set predicate (T2): a disjunction of full key predicates. Spelled as an `or`-chain of\n * per-component conjunctions — portable across OData v4.0 targets (`in` is 4.01-only, and only\n * expresses single-property membership anyway).\n */\nfunction compileIdSetFilter(binding: ODataBindingShape, ids: readonly string[]): string {\n  const perId = ids.map((id) => {\n    const components = resolveHttpApiKeyComponents(binding, id);\n    const conjuncts = binding.keyFields.map(\n      (keyField, index) => `${keyField.remoteField} eq ${odataKeyComponentLiteral(keyField.codec, components[index])}`,\n    );\n    return conjuncts.length === 1 ? conjuncts[0] : `(${conjuncts.join(' and ')})`;\n  });\n  return perId.length === 1 ? perId[0] : `(${perId.join(' or ')})`;\n}\n\nfunction compileSearchFilter(\n  binding: ODataBindingShape,\n  search: NonNullable<HttpApiTranslatedQuery['search']>,\n): string {\n  const branches = search.localFields.map((localField) => {\n    const remoteField = remoteFieldFor(binding, localField);\n    if (search.fullMatchOnly) {\n      return search.caseSensitive\n        ? `${remoteField} eq ${odataStringLiteral(search.query)}`\n        : `tolower(${remoteField}) eq ${odataStringLiteral(search.query.toLowerCase())}`;\n    }\n    return search.caseSensitive\n      ? `contains(${remoteField},${odataStringLiteral(search.query)})`\n      : `contains(tolower(${remoteField}),${odataStringLiteral(search.query.toLowerCase())})`;\n  });\n  return branches.length === 1 ? branches[0] : `(${branches.join(' or ')})`;\n}\n\n/**\n * Collection read (LIST/SEARCH/COUNT): `/EntitySet?$filter=…&$orderby=…&$top=…&$skip=…`.\n *\n * `matchNothing` MUST be short-circuited by the caller before compiling — compiling it is a\n * defect, and this module throws rather than spelling a query that could accidentally match.\n */\nexport function compileODataCollectionRead(\n  binding: ODataBindingShape,\n  query: HttpApiTranslatedQuery,\n  options?: { count?: boolean },\n): ODataCompiledRequest {\n  if (query.matchNothing) {\n    throw new Error(\n      'A match-nothing query must be answered locally with an empty page — compiling it into OData risks matching rows.',\n    );\n  }\n\n  const filterFragments: string[] = [];\n  if (query.scope) {\n    filterFragments.push(`${query.scope.remoteField} eq ${odataStringLiteral(query.scope.value)}`);\n  }\n  if (query.idIn) {\n    filterFragments.push(compileIdSetFilter(binding, query.idIn));\n  }\n  for (const equals of query.fieldEquals) {\n    filterFragments.push(`${remoteFieldFor(binding, equals.localField)} eq ${odataScalarLiteral(equals.value)}`);\n  }\n  for (const range of query.dateRanges) {\n    const remoteField = remoteFieldFor(binding, range.localField);\n    if (range.gte) filterFragments.push(`${remoteField} ge ${range.gte.toISOString()}`);\n    if (range.lte) filterFragments.push(`${remoteField} le ${range.lte.toISOString()}`);\n  }\n  if (query.search) {\n    filterFragments.push(compileSearchFilter(binding, query.search));\n  }\n\n  const params: Record<string, string> = {};\n  if (filterFragments.length > 0) {\n    params.$filter = filterFragments.join(' and ');\n  }\n  if (query.sort.length > 0) {\n    params.$orderby = query.sort\n      .map((key) => `${remoteFieldFor(binding, key.localField)}${key.direction === -1 ? ' desc' : ''}`)\n      .join(',');\n  }\n  if (query.pagination) {\n    params.$top = String(query.pagination.limit);\n    if (query.pagination.offset > 0) {\n      params.$skip = String(query.pagination.offset);\n    }\n  }\n  if (options?.count) {\n    params.$count = 'true';\n  }\n\n  return { path: `/${binding.entityRef}`, params };\n}\n\n/**\n * The ETL extraction FIRST page (partial-resource paper, D-P10 / PR-5): `$select` confined to\n * exactly the fields the pipeline maps (data minimization by construction — un-mapped personal\n * data never enters the process), an optional declared equality filter, `$top` as the page bound.\n * Subsequent pages are NOT compiled locally — the extraction follows the server's own\n * `@odata.nextLink` (drift-safe server-driven paging), so this function is only ever called once\n * per run.\n */\nexport function compileODataExtractionFirstPage(\n  binding: ODataBindingShape & { entityRef: string },\n  options: {\n    /** REMOTE field names to select — the mapped fields plus every key component. */\n    selectRemoteFields: readonly string[];\n    /** Declared REMOTE-field equality conjunction (`sourceFilter`), already remote-named. */\n    sourceFilter?: Readonly<Record<string, string | number | boolean>>;\n    pageSize: number;\n  },\n): ODataCompiledRequest {\n  const params: Record<string, string> = {\n    $select: [...new Set(options.selectRemoteFields)].join(','),\n    $top: String(options.pageSize),\n  };\n  const filterFragments = Object.entries(options.sourceFilter ?? {}).map(\n    ([remoteField, value]) => `${remoteField} eq ${odataScalarLiteral(value)}`,\n  );\n  if (filterFragments.length > 0) {\n    params.$filter = filterFragments.join(' and ');\n  }\n  return { path: `/${binding.entityRef}`, params };\n}\n\n/** COUNT-only read: `/EntitySet/$count?$filter=…` — the body is the bare number. */\nexport function compileODataCountRead(\n  binding: ODataBindingShape,\n  query: HttpApiTranslatedQuery,\n): ODataCompiledRequest {\n  const collection = compileODataCollectionRead(binding, query);\n  const params = { ...collection.params };\n  delete params.$orderby;\n  delete params.$top;\n  delete params.$skip;\n  delete params.$count;\n  return { path: `${collection.path}/$count`, params };\n}\n"]}
+{"version":3,"file":"odata-query-compiler.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/odata-query-compiler.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * OData v4 compiler: {@link HttpApiTranslatedQuery} + binding → URL path + query parameters.\n *\n * One generic implementation for every OData target (SAP S/4HANA, Dataverse — ETL decision D0).\n * Purely mechanical: every predicate arriving here is ALREADY admitted by the T-set translation;\n * this module never widens or narrows a query, it only spells it.\n *\n * Key-literal spelling follows the component CODEC declared on the binding (paper A): string\n * components are quoted with doubled single-quotes, integer/guid/datetime components are\n * unquoted — the OData v4 primitive-literal forms.\n */\n\nimport {\n  resolveHttpApiKeyComponents,\n} from '@wildo-ai/saas-models';\nimport {\n  HttpApiKeyComponentCodec,\n  type HttpApiKeyField,\n  type HttpApiFieldMapping,\n} from '@wildo-ai/saas-models/external-data';\n\nimport type {\n  HttpApiQueryScalar,\n  HttpApiTranslatedQuery,\n} from './http-api-query.backend';\n\nexport interface ODataCompiledRequest {\n  /** Path relative to the provider base URL, starting with '/'. */\n  path: string;\n  /** Query parameters, unencoded values (the transport URL-encodes once). */\n  params: Record<string, string>;\n}\n\ninterface ODataBindingShape {\n  entityRef: string;\n  keyFields: readonly HttpApiKeyField[];\n  fieldMappings: readonly HttpApiFieldMapping[];\n}\n\nfunction remoteFieldFor(binding: ODataBindingShape, localField: string): string {\n  const mapping = binding.fieldMappings.find((entry) => entry.localField === localField);\n  return mapping ? mapping.remoteField : localField;\n}\n\n/** OData string literal: single quotes doubled, wrapped in single quotes. */\nfunction odataStringLiteral(value: string): string {\n  return `'${value.replace(/'/g, \"''\")}'`;\n}\n\nfunction odataScalarLiteral(value: HttpApiQueryScalar): string {\n  if (typeof value === 'string') return odataStringLiteral(value);\n  if (value instanceof Date) return value.toISOString();\n  return String(value);\n}\n\nfunction odataKeyComponentLiteral(codec: HttpApiKeyComponentCodec, value: string | number): string {\n  switch (codec) {\n    case HttpApiKeyComponentCodec.STRING:\n      return odataStringLiteral(String(value));\n    case HttpApiKeyComponentCodec.INTEGER:\n    case HttpApiKeyComponentCodec.GUID:\n    case HttpApiKeyComponentCodec.DATETIME_ISO:\n      // OData v4 spells guid and datetimeoffset literals UNQUOTED in key predicates.\n      return String(value);\n  }\n}\n\n/**\n * Percent-encode the characters that break a URL PATH segment, leaving the predicate's\n * structural characters (`( ) = , '`) intact. `%` first, or the encoding re-encodes itself.\n * Applied to the finished predicate because these characters are never structural in one.\n * (The transport encodes QUERY params separately — this function must not run on `$filter`\n * fragments, or values would be double-encoded.)\n */\nfunction encodeODataPathPredicate(predicate: string): string {\n  return predicate\n    .replace(/%/g, '%25')\n    .replace(/ /g, '%20')\n    .replace(/\\?/g, '%3F')\n    .replace(/#/g, '%23')\n    .replace(/&/g, '%26')\n    .replace(/\\+/g, '%2B')\n    .replace(/\\//g, '%2F');\n}\n\n/**\n * The canonical key predicate for ONE row, from its synthesized id: `(K1=lit,K2=lit)` — or the\n * single-component short form `(lit)` when the binding declares one key field. PATH-encoded:\n * this predicate is only ever used as a URL path segment (the id-set `$filter` spelling lives in\n * `compileIdSetFilter`, which the transport's query-param encoding covers).\n */\nexport function compileODataKeyPredicate(\n  binding: ODataBindingShape,\n  resourceId: string,\n): string {\n  const components = resolveHttpApiKeyComponents(binding, resourceId);\n  if (binding.keyFields.length === 1) {\n    return encodeODataPathPredicate(`(${odataKeyComponentLiteral(binding.keyFields[0].codec, components[0])})`);\n  }\n  const parts = binding.keyFields.map(\n    (keyField, index) => `${keyField.remoteField}=${odataKeyComponentLiteral(keyField.codec, components[index])}`,\n  );\n  return encodeODataPathPredicate(`(${parts.join(',')})`);\n}\n\n/** Single-row read: `/EntitySet(key)`. */\nexport function compileODataKeyAddressedRead(\n  binding: ODataBindingShape,\n  resourceId: string,\n): ODataCompiledRequest {\n  return {\n    path: `/${binding.entityRef}${compileODataKeyPredicate(binding, resourceId)}`,\n    params: {},\n  };\n}\n\n/**\n * The id-set predicate (T2): a disjunction of full key predicates. Spelled as an `or`-chain of\n * per-component conjunctions — portable across OData v4.0 targets (`in` is 4.01-only, and only\n * expresses single-property membership anyway).\n */\nfunction compileIdSetFilter(binding: ODataBindingShape, ids: readonly string[]): string {\n  const perId = ids.map((id) => {\n    const components = resolveHttpApiKeyComponents(binding, id);\n    const conjuncts = binding.keyFields.map(\n      (keyField, index) => `${keyField.remoteField} eq ${odataKeyComponentLiteral(keyField.codec, components[index])}`,\n    );\n    return conjuncts.length === 1 ? conjuncts[0] : `(${conjuncts.join(' and ')})`;\n  });\n  return perId.length === 1 ? perId[0] : `(${perId.join(' or ')})`;\n}\n\nfunction compileSearchFilter(\n  binding: ODataBindingShape,\n  search: NonNullable<HttpApiTranslatedQuery['search']>,\n): string {\n  const branches = search.localFields.map((localField) => {\n    const remoteField = remoteFieldFor(binding, localField);\n    if (search.fullMatchOnly) {\n      return search.caseSensitive\n        ? `${remoteField} eq ${odataStringLiteral(search.query)}`\n        : `tolower(${remoteField}) eq ${odataStringLiteral(search.query.toLowerCase())}`;\n    }\n    return search.caseSensitive\n      ? `contains(${remoteField},${odataStringLiteral(search.query)})`\n      : `contains(tolower(${remoteField}),${odataStringLiteral(search.query.toLowerCase())})`;\n  });\n  return branches.length === 1 ? branches[0] : `(${branches.join(' or ')})`;\n}\n\n/**\n * Collection read (LIST/SEARCH/COUNT): `/EntitySet?$filter=…&$orderby=…&$top=…&$skip=…`.\n *\n * `matchNothing` MUST be short-circuited by the caller before compiling — compiling it is a\n * defect, and this module throws rather than spelling a query that could accidentally match.\n */\nexport function compileODataCollectionRead(\n  binding: ODataBindingShape,\n  query: HttpApiTranslatedQuery,\n  options?: { count?: boolean },\n): ODataCompiledRequest {\n  if (query.matchNothing) {\n    throw new Error(\n      'A match-nothing query must be answered locally with an empty page — compiling it into OData risks matching rows.',\n    );\n  }\n\n  const filterFragments: string[] = [];\n  if (query.scope) {\n    filterFragments.push(`${query.scope.remoteField} eq ${odataStringLiteral(query.scope.value)}`);\n  }\n  if (query.idIn) {\n    filterFragments.push(compileIdSetFilter(binding, query.idIn));\n  }\n  for (const equals of query.fieldEquals) {\n    filterFragments.push(`${remoteFieldFor(binding, equals.localField)} eq ${odataScalarLiteral(equals.value)}`);\n  }\n  for (const range of query.dateRanges) {\n    const remoteField = remoteFieldFor(binding, range.localField);\n    if (range.gte) filterFragments.push(`${remoteField} ge ${range.gte.toISOString()}`);\n    if (range.lte) filterFragments.push(`${remoteField} le ${range.lte.toISOString()}`);\n  }\n  if (query.search) {\n    filterFragments.push(compileSearchFilter(binding, query.search));\n  }\n\n  const params: Record<string, string> = {};\n  if (filterFragments.length > 0) {\n    params.$filter = filterFragments.join(' and ');\n  }\n  if (query.sort.length > 0) {\n    params.$orderby = query.sort\n      .map((key) => `${remoteFieldFor(binding, key.localField)}${key.direction === -1 ? ' desc' : ''}`)\n      .join(',');\n  }\n  if (query.pagination) {\n    params.$top = String(query.pagination.limit);\n    if (query.pagination.offset > 0) {\n      params.$skip = String(query.pagination.offset);\n    }\n  }\n  if (options?.count) {\n    params.$count = 'true';\n  }\n\n  return { path: `/${binding.entityRef}`, params };\n}\n\n/**\n * The ETL extraction FIRST page (partial-resource paper, D-P10 / PR-5): `$select` confined to\n * exactly the fields the pipeline maps (data minimization by construction — un-mapped personal\n * data never enters the process), an optional declared equality filter, `$top` as the page bound.\n * Subsequent pages are NOT compiled locally — the extraction follows the server's own\n * `@odata.nextLink` (drift-safe server-driven paging), so this function is only ever called once\n * per run.\n */\nexport function compileODataExtractionFirstPage(\n  binding: ODataBindingShape & { entityRef: string },\n  options: {\n    /** REMOTE field names to select — the mapped fields plus every key component. */\n    selectRemoteFields: readonly string[];\n    /** Declared REMOTE-field equality conjunction (`sourceFilter`), already remote-named. */\n    sourceFilter?: Readonly<Record<string, string | number | boolean>>;\n    pageSize: number;\n  },\n): ODataCompiledRequest {\n  // `$orderby` on the KEY components, ascending, is not decoration — it is what makes the paged\n  // extraction drift-safe, and following `@odata.nextLink` alone does NOT provide it.\n  //\n  // Dataverse builds its paging cookie from the LAST ROW of the previous page under the query's\n  // own order, and its documentation is explicit that without a deterministic order \"the same\n  // record can appear in more than one page\" — it recommends ordering on the primary key, which is\n  // exactly what a binding's `keyFields` are. A duplicated row would be re-upserted (harmless), but\n  // a SKIPPED one is silently absent from a COMPLETE pass, and a complete pass is what authorizes\n  // the orphan stage — so a skip does not merely lose a row, it can orphan a live one.\n  // spec-cite: Microsoft Learn, \"Page results using OData from Microsoft Dataverse Web API\" —\n  // \"Deterministic ordering is important\" / \"Without proper ordering, the same record can appear in\n  // more than one page.\"\n  //\n  // Key components are ordered as DECLARED: the schema already fixes their order for the composite\n  // key predicate, so reusing it keeps one source for \"the key's component order\".\n  const params: Record<string, string> = {\n    $select: [...new Set(options.selectRemoteFields)].join(','),\n    $orderby: binding.keyFields.map((keyField) => `${keyField.remoteField} asc`).join(','),\n    $top: String(options.pageSize),\n  };\n  const filterFragments = Object.entries(options.sourceFilter ?? {}).map(\n    ([remoteField, value]) => `${remoteField} eq ${odataScalarLiteral(value)}`,\n  );\n  if (filterFragments.length > 0) {\n    params.$filter = filterFragments.join(' and ');\n  }\n  return { path: `/${binding.entityRef}`, params };\n}\n\n/** COUNT-only read: `/EntitySet/$count?$filter=…` — the body is the bare number. */\nexport function compileODataCountRead(\n  binding: ODataBindingShape,\n  query: HttpApiTranslatedQuery,\n): ODataCompiledRequest {\n  const collection = compileODataCollectionRead(binding, query);\n  const params = { ...collection.params };\n  delete params.$orderby;\n  delete params.$top;\n  delete params.$skip;\n  delete params.$count;\n  return { path: `${collection.path}/$count`, params };\n}\n"]}