facturas 0.11.0 → 0.12.1

package/dist/{chunk-LOWV7IF6.mjs → chunk-2PYF5JFG.mjs}

@@ -11,7 +11,7 @@ import {
   normalizeWsfeDateInput,
   normalizeWsfeVoucherInput,
   serializeArcaExchangeRate
-} from "./chunk-5KCTRQJX.mjs";
+} from "./chunk-QHYJ424J.mjs";
 import {
   ARCA_CURRENCY_IDS,
   ARCA_DOCUMENT_TYPES,
@@ -23,7 +23,7 @@ import {
 } from "./chunk-GX5ERXT6.mjs";
 import {
   createWsmtxcaService
-} from "./chunk-ALH5IPSY.mjs";
+} from "./chunk-D5ZWXTCV.mjs";
 import {
   ArcaConfigurationError,
   ArcaError,
@@ -278,6 +278,15 @@ import { createHash } from "crypto";
 function attemptKey(environment, taxId, key) {
   return `arca:v1:attempt:${environment}:${taxId}:${key}`;
 }
+function sequenceKey(environment, taxId, salesPoint, voucherType) {
+  return `arca:v1:sequence:${environment}:${taxId}:${salesPoint}:${voucherType}`;
+}
+function sequenceLockKey(environment, taxId, salesPoint, voucherType) {
+  return `arca:v1:lock:sequence:${environment}:${taxId}:${salesPoint}:${voucherType}`;
+}
+function settledKey(environment, taxId, key) {
+  return `arca:v1:settled:${environment}:${taxId}:${key}`;
+}
 function canonicalHash(input) {
   return createHash("sha256").update(JSON.stringify(canonical(input))).digest("hex");
 }
@@ -723,6 +732,27 @@ function isWsaaCredentialValid(credentials) {
 import { createHash as createHash2 } from "crypto";
 import forge from "node-forge";
 
+// src/internal/abort.ts
+function abortedError(signal) {
+  return new ArcaTransportError("The ARCA call was aborted", {
+    cause: signal?.reason
+  });
+}
+function abortable(promise, signal) {
+  if (!signal) {
+    return promise;
+  }
+  if (signal.aborted) {
+    promise.catch(() => void 0);
+    return Promise.reject(abortedError(signal));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortedError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
 // src/internal/http.ts
 import https from "https";
 var defaultAgent = new https.Agent({
@@ -743,7 +773,8 @@ async function postXmlWithMetadata({
   retryDelay = 500,
   logger,
   service,
-  operation
+  operation,
+  signal
 }) {
   const totalAttempts = retries + 1;
   for (let attempt = 1; attempt <= totalAttempts; attempt += 1) {
@@ -754,13 +785,14 @@ async function postXmlWithMetadata({
         contentType,
         soapAction,
         useLegacyTlsSecurityLevel0,
-        timeout
+        timeout,
+        signal
       });
     } catch (error) {
       if (!(error instanceof ArcaTransportError)) {
         throw error;
       }
-      if (attempt >= totalAttempts) {
+      if (attempt >= totalAttempts || signal?.aborted) {
         logger?.error("ARCA transport request failed", {
           service,
           operation,
@@ -794,10 +826,16 @@ async function postXmlOnce({
   contentType,
   soapAction,
   useLegacyTlsSecurityLevel0,
-  timeout
+  timeout,
+  signal
 }) {
   const endpoint = new URL(url);
   const requestBody = Buffer.from(body, "utf8");
+  if (signal?.aborted) {
+    throw new ArcaTransportError("ARCA HTTP request was aborted", {
+      cause: signal.reason
+    });
+  }
   return await new Promise((resolve, reject) => {
     let settled = false;
     const settleResolve = (response) => {
@@ -908,6 +946,15 @@ async function postXmlOnce({
         })
       );
     });
+    const abort = () => {
+      const cause = new Error("ARCA HTTP request was aborted");
+      settleReject(
+        new ArcaTransportError("ARCA HTTP request was aborted", { cause })
+      );
+      request.destroy(cause);
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    request.on("close", () => signal?.removeEventListener("abort", abort));
     request.write(requestBody);
     request.end();
   });
@@ -1143,34 +1190,37 @@ function createWsaaAuthModule(options) {
   }
   return {
     login(service, authOptions = {}) {
-      const sessionKey = buildWsaaSessionKey(options.config, service);
-      const cacheKey = serializeWsaaSessionKey(sessionKey);
-      if (authOptions.forceRefresh) {
-        const runningForced2 = forcedInFlight.get(cacheKey);
-        if (runningForced2) {
-          return runningForced2;
-        }
-        const runningOrdinary2 = ordinaryInFlight.get(cacheKey);
-        return trackLogin(forcedInFlight, cacheKey, async () => {
-          await runningOrdinary2?.catch(() => void 0);
-          return await performLogin(service, sessionKey, cacheKey, true);
-        });
-      }
-      const runningOrdinary = ordinaryInFlight.get(cacheKey);
-      if (runningOrdinary) {
-        return runningOrdinary;
-      }
-      const runningForced = forcedInFlight.get(cacheKey);
-      if (runningForced) {
-        return runningForced;
-      }
-      return trackLogin(
-        ordinaryInFlight,
-        cacheKey,
-        () => performLogin(service, sessionKey, cacheKey, false)
-      );
+      return abortable(runLogin(service, authOptions), authOptions.signal);
     }
   };
+  function runLogin(service, authOptions) {
+    const sessionKey = buildWsaaSessionKey(options.config, service);
+    const cacheKey = serializeWsaaSessionKey(sessionKey);
+    if (authOptions.forceRefresh) {
+      const runningForced2 = forcedInFlight.get(cacheKey);
+      if (runningForced2) {
+        return runningForced2;
+      }
+      const runningOrdinary2 = ordinaryInFlight.get(cacheKey);
+      return trackLogin(forcedInFlight, cacheKey, async () => {
+        await runningOrdinary2?.catch(() => void 0);
+        return await performLogin(service, sessionKey, cacheKey, true);
+      });
+    }
+    const runningOrdinary = ordinaryInFlight.get(cacheKey);
+    if (runningOrdinary) {
+      return runningOrdinary;
+    }
+    const runningForced = forcedInFlight.get(cacheKey);
+    if (runningForced) {
+      return runningForced;
+    }
+    return trackLogin(
+      ordinaryInFlight,
+      cacheKey,
+      () => performLogin(service, sessionKey, cacheKey, false)
+    );
+  }
 }
 async function requestCredentials(config, service, options) {
   const loginTicketRequestXml = buildLoginTicketRequest(service);
@@ -2094,6 +2144,7 @@ function createWsmtxcaIssuanceService(wsmtxca) {
     issue: (input) => wsmtxca.issue({
       representedTaxId: input.representedTaxId,
       forceRefresh: input.forceRefresh,
+      signal: input.signal,
       data: wsmtxcaRequest(input.data, input.voucherNumber)
     }),
     lookupVoucher: async (input) => {
@@ -2821,7 +2872,8 @@ function createVouchersService(wsfe, context, wsmtxca) {
       input,
       options ?? {},
       context,
-      "debitNote"
+      "debitNote",
+      select
     ),
     previewCreditNote: async (input, options) => previewNote(
       select(options),
@@ -2842,7 +2894,9 @@ function createVouchersService(wsfe, context, wsmtxca) {
         select(options),
         input,
         options === void 0 ? {} : options,
-        context
+        context,
+        "creditNote",
+        select
       );
       return result;
     },
@@ -2851,7 +2905,8 @@ function createVouchersService(wsfe, context, wsmtxca) {
         select(options),
         input,
         options === void 0 ? {} : options,
-        context
+        context,
+        select
       );
       return result;
     },
@@ -2904,8 +2959,8 @@ function toPreview(prepared, options) {
     ...options.service === "wsmtxca" ? { service: "wsmtxca" } : {}
   };
 }
-async function issueInvoice(wsfe, input, inputOptions, context) {
-  const options = structuredClone(inputOptions);
+async function issueInvoice(wsfe, input, inputOptions, context, select) {
+  const options = cloneOptions(inputOptions);
   validateOptions(options);
   validateKeyStore(options, context);
   const prepared = prepareInvoice(input, options);
@@ -2916,19 +2971,18 @@ async function issueInvoice(wsfe, input, inputOptions, context) {
     () => Promise.resolve(prepared),
     options,
     context,
-    prepared.amounts
+    prepared.amounts,
+    select
   );
 }
-async function runOperation(wsfe, operation, input, prepare, options, context, replayAmounts) {
-  const store = context?.store;
-  if (options.idempotencyKey === void 0 || !store || !context) {
+async function runOperation(wsfe, operation, input, prepare, options, context, replayAmounts, select) {
+  if (options.idempotencyKey === void 0 || !context?.store) {
     return runAuthorization(wsfe, await prepare(), options);
   }
-  const key = attemptKey(
-    context.environment,
-    context.taxId,
-    options.idempotencyKey
-  );
+  const store = context.store;
+  const { environment, taxId } = context;
+  const idempotencyKey = options.idempotencyKey;
+  const key = attemptKey(environment, taxId, idempotencyKey);
   const representedTaxId = options.representedTaxId === void 0 ? void 0 : String(options.representedTaxId);
   const inputHash = canonicalHash({
     input,
@@ -2936,37 +2990,107 @@ async function runOperation(wsfe, operation, input, prepare, options, context, r
     ...options.service === "wsmtxca" ? { service: "wsmtxca" } : {},
     ...options.number === void 0 ? {} : { number: options.number }
   });
+  const settled = settledKey(environment, taxId, idempotencyKey);
   const existing = await storeCall(() => store.get(key));
   if (existing !== null) {
-    return replay(existing);
+    return await replay(existing);
   }
   const prepared = await prepare();
-  const number = await nextNumber(wsfe, prepared.data, options);
-  const service = options.service ?? "wsfe";
-  const versioned = service === "wsmtxca" || prepared.data.details !== void 0;
-  const record = {
-    v: versioned ? 2 : 1,
-    operation,
-    ...versioned ? { service } : {},
-    representedTaxId,
-    inputHash,
-    number,
-    salesPoint: prepared.data.salesPoint,
-    voucherType: prepared.data.voucherType,
-    sent: prepared.data,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  const sequence = {
+    coordinates: {
+      salesPoint: prepared.data.salesPoint,
+      voucherType: prepared.data.voucherType
+    },
+    // The sequence belongs to the taxpayer whose numbering ARCA advances.
+    taxId: String(options.representedTaxId ?? context.taxId)
   };
-  if (await storeCall(() => store.add(key, JSON.stringify(record)))) {
-    return runAuthorization(wsfe, prepared, options, number);
+  const sequenceRecord = sequenceKey(
+    environment,
+    sequence.taxId,
+    sequence.coordinates.salesPoint,
+    sequence.coordinates.voucherType
+  );
+  if (!store.withLock) {
+    return await claim();
+  }
+  return await store.withLock(
+    sequenceLockKey(
+      environment,
+      sequence.taxId,
+      sequence.coordinates.salesPoint,
+      sequence.coordinates.voucherType
+    ),
+    async () => {
+      const barrier = await runSequenceBarrier({
+        store,
+        environment,
+        taxId,
+        sequence: sequenceRecord,
+        coordinates: sequence.coordinates,
+        select: select ?? (() => wsfe),
+        options,
+        supersededBy: idempotencyKey,
+        readNext: () => nextNumber(wsfe, prepared.data, options)
+      });
+      return "blocked" in barrier ? barrier.blocked : await claim(barrier.reserved);
+    }
+  );
+  function reservation(number) {
+    const service = options.service ?? "wsfe";
+    const versioned = service === "wsmtxca" || prepared.data.details !== void 0;
+    return {
+      v: versioned ? 2 : 1,
+      operation,
+      ...versioned ? { service } : {},
+      representedTaxId,
+      inputHash,
+      number,
+      salesPoint: prepared.data.salesPoint,
+      voucherType: prepared.data.voucherType,
+      sent: prepared.data,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
   }
-  const winner = await storeCall(() => store.get(key));
-  if (winner === null) {
-    throw new ArcaConfigurationError(
-      "ARCA reservation disappeared after atomic creation lost."
-    );
+  async function claim(reserved) {
+    const coordinated = store.withLock !== void 0;
+    const prior = coordinated ? await storeCall(() => store.get(key)) : null;
+    if (prior !== null) {
+      return await replay(prior, true);
+    }
+    const number = options.number ?? reserved ?? await nextNumber(wsfe, prepared.data, options);
+    const record = reservation(number);
+    const claimed = {
+      v: 1,
+      key: idempotencyKey,
+      number,
+      claimedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (coordinated) {
+      await storeCall(() => store.set(sequenceRecord, JSON.stringify(claimed)));
+    }
+    if (await storeCall(() => store.add(key, JSON.stringify(record)))) {
+      const outcome = await settle(
+        runAuthorization(wsfe, prepared, options, number)
+      );
+      if (coordinated && outcome.kind !== "indeterminate") {
+        await storeCall(
+          () => store.set(
+            sequenceRecord,
+            JSON.stringify({ ...claimed, resolvedAt: (/* @__PURE__ */ new Date()).toISOString() })
+          )
+        );
+      }
+      return outcome;
+    }
+    const winner = await storeCall(() => store.get(key));
+    if (winner === null) {
+      throw new ArcaConfigurationError(
+        "ARCA reservation disappeared after atomic creation lost."
+      );
+    }
+    return await replay(winner, true);
   }
-  return replay(winner);
-  function replay(json) {
+  async function replay(json, locked = false) {
     const stored = readRecord(json);
     if ((stored.service ?? "wsfe") !== (options.service ?? "wsfe") || stored.operation !== operation || stored.inputHash !== inputHash || stored.representedTaxId !== representedTaxId) {
       throw new ArcaInputError(
@@ -2977,17 +3101,107 @@ async function runOperation(wsfe, operation, input, prepare, options, context, r
         }
       );
     }
-    return runAuthorization(
-      wsfe,
-      {
-        ...preparedFromRecord(stored),
-        ...replayAmounts ? { amounts: replayAmounts } : {}
-      },
-      options,
-      stored.number,
-      true
+    const consult = async () => {
+      const recorded = await storeCall(() => store.get(settled));
+      if (recorded !== null) {
+        return await settledOutcome(
+          select ?? (() => wsfe),
+          stored,
+          readSettledRecord(recorded),
+          options
+        );
+      }
+      return await settle(
+        runAuthorization(
+          wsfe,
+          {
+            ...preparedFromRecord(stored),
+            ...replayAmounts ? { amounts: replayAmounts } : {}
+          },
+          options,
+          stored.number,
+          true
+        )
+      );
+    };
+    if (locked || !store.withLock) {
+      return await consult();
+    }
+    return await store.withLock(
+      sequenceLockKey(
+        environment,
+        stored.representedTaxId ?? taxId,
+        stored.salesPoint,
+        stored.voucherType
+      ),
+      consult
     );
   }
+  async function settle(running) {
+    return await recordConflict(store, settled, await running);
+  }
+}
+async function recordConflict(store, key, outcome) {
+  if (outcome.kind !== "conflict") {
+    return outcome;
+  }
+  const record = {
+    v: 1,
+    kind: "conflict",
+    number: outcome.attempted.number,
+    found: Object.fromEntries(
+      Object.entries(outcome.found).filter(([field]) => field !== "raw")
+    ),
+    settledAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await storeCall(() => store.add(key, JSON.stringify(record)));
+  return outcome;
+}
+function readSettledRecord(json) {
+  try {
+    const record = JSON.parse(json);
+    if (!record || record.v !== 1 || !Number.isSafeInteger(record.number) || (record.kind === "conflict" ? !record.found || typeof record.found !== "object" : record.kind !== "superseded" || typeof record.by !== "string")) {
+      throw new Error("Invalid settled structure");
+    }
+    return record;
+  } catch (cause) {
+    throw new ArcaConfigurationError(
+      "Invalid ARCA settled record; preserve it for reconciliation.",
+      { cause }
+    );
+  }
+}
+async function settledOutcome(select, reservation, settled, options) {
+  if (settled.kind === "conflict") {
+    return settledConflict(settled, reservation);
+  }
+  const outcome = await consultReservation(select, reservation, options, true);
+  if (outcome.kind === "indeterminate" && outcome.lookup.kind === "not_found") {
+    return {
+      kind: "indeterminate",
+      attempted: {
+        salesPoint: reservation.salesPoint,
+        voucherType: reservation.voucherType,
+        number: settled.number
+      },
+      attempt: replayEvidence(reservation.service),
+      lookup: { kind: "superseded", by: settled.by }
+    };
+  }
+  return outcome;
+}
+function settledConflict(settled, reservation) {
+  return {
+    kind: "conflict",
+    attempted: {
+      salesPoint: reservation.salesPoint,
+      voucherType: reservation.voucherType,
+      number: settled.number
+    },
+    attempt: replayEvidence(reservation.service),
+    found: settled.found,
+    reason: "This key already recorded another voucher at the reserved number. Reconcile before issuing under a new key."
+  };
 }
 function validateKeyStore(options, context) {
   if (options.idempotencyKey === void 0) {
@@ -3043,6 +3257,7 @@ async function nextNumber(wsfe, data, options) {
   const number = await wsfe.getNextVoucherNumber({
     representedTaxId: options.representedTaxId,
     forceRefresh: options.forceRefresh,
+    ...options.signal === void 0 ? {} : { signal: options.signal },
     salesPoint: data.salesPoint,
     voucherType: data.voucherType
   });
@@ -3060,7 +3275,8 @@ async function nextNumber(wsfe, data, options) {
 async function runAuthorization(wsfe, { data, voucherClass, amounts }, options, reservedNumber, replay = false) {
   const auth = {
     representedTaxId: options.representedTaxId,
-    forceRefresh: options.forceRefresh
+    forceRefresh: options.forceRefresh,
+    ...options.signal === void 0 ? {} : { signal: options.signal }
   };
   const includeRaw = options.include?.raw === true;
   const includeExact = options.include?.exactInput === true;
@@ -3099,7 +3315,7 @@ async function runAuthorization(wsfe, { data, voucherClass, amounts }, options,
         kind: "indeterminate",
         attempted,
         attempt: attempt2,
-        lookup: { kind: "failed", error: toArcaSafeErrorMetadata(error) }
+        lookup: options.signal?.aborted ? { kind: "aborted" } : { kind: "failed", error: toArcaSafeErrorMetadata(error) }
       };
     }
     if (lookup.kind === "found") {
@@ -3121,32 +3337,13 @@ async function runAuthorization(wsfe, { data, voucherClass, amounts }, options,
     };
   }
   if (authorization.kind === "rejected") {
-    if (options.idempotencyKey !== void 0 && (options.service === "wsmtxca" || [...authorization.errors, ...authorization.observations].some(
-      (issue) => issue.code === "10016"
-    ))) {
-      const recovered = await recoverInvoice({
-        ...recovery,
-        attempt: projectEvidence(
-          {
-            ...authorization,
-            kind: "indeterminate",
-            reason: "contradictory_response"
-          },
-          includeRaw
-        )
-      });
-      if (recovered.kind === "authorized" || recovered.kind === "conflict") {
-        return recovered;
-      }
-    }
-    return {
-      kind: "rejected",
-      attempted,
-      issues: [...authorization.errors, ...authorization.observations].map(
-        projectIssue
-      ),
-      authorization: projectEvidence(authorization, includeRaw)
-    };
+    return await resolveRejection(
+      authorization,
+      recovery,
+      options,
+      includeRaw,
+      replay
+    );
   }
   const uncertain = authorization.kind === "indeterminate" ? authorization : {
     ...authorization,
@@ -3166,6 +3363,33 @@ async function runAuthorization(wsfe, { data, voucherClass, amounts }, options,
     voucher
   });
 }
+async function resolveRejection(authorization, recovery, options, includeRaw, replay) {
+  const issues = [...authorization.errors, ...authorization.observations];
+  const consult = options.idempotencyKey !== void 0 && (options.service === "wsmtxca" || issues.some((issue) => issue.code === "10016"));
+  if (consult) {
+    const recovered = await recoverInvoice({
+      ...recovery,
+      attempt: projectEvidence(
+        {
+          ...authorization,
+          kind: "indeterminate",
+          reason: "contradictory_response"
+        },
+        includeRaw
+      ),
+      strangerAtNumber: !replay
+    });
+    if (recovered.kind === "authorized" || recovered.kind === "conflict") {
+      return recovered;
+    }
+  }
+  return {
+    kind: "rejected",
+    attempted: recovery.attempted,
+    issues: issues.map(projectIssue),
+    authorization: projectEvidence(authorization, includeRaw)
+  };
+}
 async function recoverInvoice({
   wsfe,
   auth,
@@ -3176,8 +3400,17 @@ async function recoverInvoice({
   exact,
   voucher,
   lookup: suppliedLookup,
-  service
+  service,
+  strangerAtNumber = false
 }) {
+  if (suppliedLookup === void 0 && auth.signal?.aborted) {
+    return {
+      kind: "indeterminate",
+      attempted,
+      attempt,
+      lookup: { kind: "aborted" }
+    };
+  }
   let lookup;
   try {
     lookup = suppliedLookup ?? await wsfe.lookupVoucher({ ...auth, ...attempted });
@@ -3186,7 +3419,7 @@ async function recoverInvoice({
       kind: "indeterminate",
       attempted,
       attempt,
-      lookup: { kind: "failed", error: toArcaSafeErrorMetadata(error) }
+      lookup: auth.signal?.aborted ? { kind: "aborted" } : { kind: "failed", error: toArcaSafeErrorMetadata(error) }
     };
   }
   const raw = includeRaw ? { raw: lookup.raw } : {};
@@ -3198,6 +3431,15 @@ async function recoverInvoice({
       lookup: { kind: "not_found", ...raw }
     };
   }
+  if (strangerAtNumber) {
+    return {
+      kind: "conflict",
+      attempted,
+      attempt,
+      found: { ...toVoucherSummary(lookup.voucher), ...raw },
+      reason: "ARCA refused the number this call reserved and another voucher occupies it"
+    };
+  }
   const detailsMatch = service === "wsmtxca" ? matchWsmtxcaDetails(data, attempted.number, lookup.voucher.raw) : void 0;
   const matched = detailsMatch === void 0 ? matchWsfeVoucherIdentity(data, attempted.number, lookup.voucher) : detailsMatch === "match" && lookup.voucher.cae && lookup.voucher.caeExpiry ? { matches: true } : {
     matches: false,
@@ -3281,6 +3523,14 @@ function projectEvidence(evidence, includeRaw) {
   }
   return projected;
 }
+function cloneOptions(options) {
+  assertIssueObject(options, "options");
+  const { signal, ...rest } = options;
+  return {
+    ...structuredClone(rest),
+    ...signal === void 0 ? {} : { signal }
+  };
+}
 function validateOptions(options) {
   assertIssueObject(options, "options");
   assertIssueKeys(
@@ -3291,10 +3541,17 @@ function validateOptions(options) {
       "include",
       "idempotencyKey",
       "service",
-      "number"
+      "number",
+      "signal"
     ],
     "options"
   );
+  if (options.signal !== void 0 && (typeof options.signal !== "object" || options.signal === null || typeof options.signal.aborted !== "boolean" || typeof options.signal.addEventListener !== "function")) {
+    throw new ArcaInputError("options.signal must be an AbortSignal.", {
+      code: "ARCA_INPUT_INVALID_VALUE",
+      field: "options.signal"
+    });
+  }
   if (options.service !== void 0 && options.service !== "wsfe" && options.service !== "wsmtxca") {
     throw new ArcaInputError("Unknown fiscal service", {
       code: "ARCA_INPUT_INVALID_VALUE",
@@ -3348,8 +3605,8 @@ function replayEvidence(service = "wsfe") {
     observations: []
   };
 }
-async function issueCreditNote(wsfe, input, inputOptions, context, kind = "creditNote") {
-  const options = structuredClone(inputOptions);
+async function issueCreditNote(wsfe, input, inputOptions, context, kind = "creditNote", select) {
+  const options = cloneOptions(inputOptions);
   validateOptions(options);
   validateKeyStore(options, context);
   assertIssueObject(input, "input");
@@ -3366,7 +3623,9 @@ async function issueCreditNote(wsfe, input, inputOptions, context, kind = "credi
     note,
     () => prepareNote(wsfe, note, options, context, kind),
     options,
-    context
+    context,
+    void 0,
+    select
   );
 }
 async function previewNote(wsfe, input, inputOptions, context, kind) {
@@ -3467,11 +3726,11 @@ function exactEvidence(data, number, options, include) {
   } : {};
 }
 async function recoverOperation(select, key, inputOptions, context) {
-  const options = structuredClone(inputOptions);
+  const options = cloneOptions(inputOptions);
   assertIssueObject(options, "options");
   assertIssueKeys(
     options,
-    ["representedTaxId", "forceRefresh", "include"],
+    ["representedTaxId", "forceRefresh", "include", "signal"],
     "options"
   );
   validateOptions(options);
@@ -3492,28 +3751,52 @@ async function recoverOperation(select, key, inputOptions, context) {
     });
   }
   const record = readRecord(json);
+  const store = context.store;
+  const settled = settledKey(
+    context.environment,
+    context.taxId,
+    key
+  );
   if (options.representedTaxId !== void 0 && String(options.representedTaxId) !== (record.representedTaxId ?? context?.taxId)) {
     throw new ArcaInputError(
       "Reservation belongs to another represented taxpayer",
       { code: "ARCA_INPUT_IDEMPOTENCY_MISMATCH" }
     );
   }
+  const recorded = await storeCall(() => store.get(settled));
+  if (recorded !== null) {
+    return await settledOutcome(
+      select,
+      record,
+      readSettledRecord(recorded),
+      options
+    );
+  }
+  return await recordConflict(
+    store,
+    settled,
+    await consultReservation(select, record, options)
+  );
+}
+function consultReservation(select, record, options, strangerAtNumber = false) {
   const storedOptions = {
     ...options,
     service: record.service ?? "wsfe",
     representedTaxId: record.representedTaxId
   };
   const prepared = preparedFromRecord(record);
+  const attempted = {
+    salesPoint: record.salesPoint,
+    voucherType: record.voucherType,
+    number: record.number
+  };
   return recoverInvoice({
     wsfe: select(storedOptions),
     service: storedOptions.service,
     auth: storedOptions,
     data: prepared.data,
-    attempted: {
-      salesPoint: record.salesPoint,
-      voucherType: record.voucherType,
-      number: record.number
-    },
+    strangerAtNumber,
+    attempted,
     attempt: replayEvidence(storedOptions.service),
     includeRaw: options.include?.raw === true,
     exact: exactEvidence(
@@ -3523,9 +3806,7 @@ async function recoverOperation(select, key, inputOptions, context) {
       options.include?.exactInput === true
     ),
     voucher: (cae, caeExpiry) => ({
-      salesPoint: record.salesPoint,
-      voucherType: record.voucherType,
-      number: record.number,
+      ...attempted,
       voucherClass: prepared.voucherClass,
       date: prepared.data.voucherDate,
       amounts: prepared.amounts,
@@ -3534,6 +3815,90 @@ async function recoverOperation(select, key, inputOptions, context) {
     })
   });
 }
+async function runSequenceBarrier({
+  store,
+  environment,
+  taxId,
+  sequence,
+  coordinates,
+  select,
+  options,
+  supersededBy,
+  readNext
+}) {
+  const json = await storeCall(() => store.get(sequence));
+  if (json === null) {
+    return {};
+  }
+  const claimed = readSequenceRecord(json);
+  if (claimed.resolvedAt !== void 0) {
+    return {};
+  }
+  const settled = settledKey(environment, taxId, claimed.key);
+  if (await storeCall(() => store.get(settled)) !== null) {
+    return {};
+  }
+  const reservation = await storeCall(
+    () => store.get(attemptKey(environment, taxId, claimed.key))
+  );
+  if (reservation === null) {
+    return {};
+  }
+  const record = readRecord(reservation);
+  const blocked = {
+    blocked: {
+      kind: "indeterminate",
+      attempted: { ...coordinates, number: record.number },
+      attempt: replayEvidence(options.service),
+      lookup: { kind: "blocked", by: claimed.key }
+    }
+  };
+  const outcome = await recordConflict(
+    store,
+    settled,
+    await consultReservation(select, record, {
+      forceRefresh: options.forceRefresh,
+      ...options.signal === void 0 ? {} : { signal: options.signal }
+    })
+  );
+  if (outcome.kind === "authorized" || outcome.kind === "conflict") {
+    return {};
+  }
+  if (outcome.kind !== "indeterminate" || outcome.lookup.kind !== "not_found") {
+    return blocked;
+  }
+  const next = await readNext();
+  if (next !== record.number) {
+    return blocked;
+  }
+  await storeCall(
+    () => store.add(
+      settled,
+      JSON.stringify({
+        v: 1,
+        kind: "superseded",
+        number: record.number,
+        by: supersededBy,
+        settledAt: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    )
+  );
+  return { reserved: next };
+}
+function readSequenceRecord(json) {
+  try {
+    const record = JSON.parse(json);
+    if (!record || record.v !== 1 || typeof record.key !== "string" || !Number.isSafeInteger(record.number)) {
+      throw new Error("Invalid sequence structure");
+    }
+    return record;
+  } catch (cause) {
+    throw new ArcaConfigurationError(
+      "Invalid ARCA sequence record; delete the sequence key to resume.",
+      { cause }
+    );
+  }
+}
 
 // src/soap/index.ts
 function createSoapTransport(options) {
@@ -3572,7 +3937,8 @@ function createSoapTransport(options) {
           retryDelay: options.config.retryDelay,
           logger: options.logger,
           service: request.service,
-          operation: request.operation
+          operation: request.operation,
+          signal: request.signal
         });
         options.logger?.debug("Received ARCA SOAP response", {
           service: request.service,
@@ -3688,9 +4054,56 @@ function createArcaClient(config = {}) {
 }
 
 // src/store/file.ts
-import { createHash as createHash3, randomUUID } from "crypto";
-import { mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "crypto";
+import {
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  unlink,
+  writeFile
+} from "fs/promises";
 import { join } from "path";
+
+// src/store/lock.ts
+import { randomUUID } from "crypto";
+var ARCA_LEASE_MS = 6e4;
+var RENEW_MS = 2e4;
+var POLL_MS = 50;
+var MAX_WAIT_MS = 2 * ARCA_LEASE_MS;
+async function withLease(key, driver, fn) {
+  const owner = randomUUID();
+  const deadline = Date.now() + MAX_WAIT_MS;
+  let held = await driver.acquire(owner);
+  while (!held) {
+    if (Date.now() >= deadline) {
+      throw new ArcaConfigurationError(
+        `ARCA store lock ${key} stayed held; no work was attempted.`
+      );
+    }
+    await delay2(POLL_MS + Math.floor(Math.random() * POLL_MS));
+    held = await driver.acquire(owner);
+  }
+  const renewal = setInterval(() => {
+    driver.renew(owner).catch(() => void 0);
+  }, RENEW_MS);
+  renewal.unref?.();
+  try {
+    return await fn();
+  } finally {
+    clearInterval(renewal);
+    await driver.release(owner).catch(() => void 0);
+  }
+}
+function delay2(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+// src/store/file.ts
 function createFileStore(directory) {
   const path = (key) => join(directory, createHash3("sha256").update(key).digest("hex"));
   const ensure = () => mkdir(directory, { recursive: true, mode: 448 });
@@ -3707,7 +4120,7 @@ function createFileStore(directory) {
     }),
     set: (key, value) => storeCall(async () => {
       await ensure();
-      const temporary = `${path(key)}.${randomUUID()}.tmp`;
+      const temporary = `${path(key)}.${randomUUID2()}.tmp`;
       try {
         await writeFile(temporary, value, { mode: 384, flag: "wx" });
         await rename(temporary, path(key));
@@ -3735,9 +4148,85 @@ function createFileStore(directory) {
           throw error;
         }
       }
+    }),
+    withLock: (key, fn) => (
+      // A lock directory: mkdir is the atomic claim on every POSIX filesystem
+      // and on Windows, and the holder file inside carries the lease.
+      withLease(key, fileLease(`${path(key)}.lock`, ensure), fn)
+    )
+  };
+}
+function fileLease(directory, ensure) {
+  const holder = join(directory, "holder");
+  const claim = (owner) => JSON.stringify({
+    owner,
+    expiresAt: new Date(Date.now() + ARCA_LEASE_MS).toISOString()
+  });
+  const read = async () => {
+    try {
+      return JSON.parse(await readFile(holder, "utf8"));
+    } catch {
+      return null;
+    }
+  };
+  return {
+    acquire: (owner) => storeCall(async () => {
+      await ensure();
+      if (!await createDirectory(directory)) {
+        if (await stillHeld(directory, await read())) {
+          return false;
+        }
+        await rm(directory, { recursive: true, force: true });
+        if (!await createDirectory(directory)) {
+          return false;
+        }
+      }
+      return await writeHolder(holder, claim(owner));
+    }),
+    renew: (owner) => storeCall(async () => {
+      if ((await read())?.owner === owner) {
+        await writeFile(holder, claim(owner), { mode: 384 });
+      }
+    }),
+    release: (owner) => storeCall(async () => {
+      if ((await read())?.owner === owner) {
+        await rm(directory, { recursive: true, force: true });
+      }
     })
   };
 }
+async function createDirectory(directory) {
+  try {
+    await mkdir(directory);
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function writeHolder(holder, value) {
+  try {
+    await writeFile(holder, value, { mode: 384, flag: "wx" });
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function stillHeld(directory, holder) {
+  if (holder) {
+    return Date.parse(holder.expiresAt) > Date.now();
+  }
+  try {
+    return (await stat(directory)).mtimeMs + ARCA_LEASE_MS > Date.now();
+  } catch {
+    return false;
+  }
+}
 
 export {
   ARCA_ENVIRONMENTS,
@@ -3753,6 +4242,8 @@ export {
   createWsaaAuthModule,
   createWsaaStoreAdapter,
   createArcaClient,
+  ARCA_LEASE_MS,
+  withLease,
   createFileStore
 };
-//# sourceMappingURL=chunk-LOWV7IF6.mjs.map
+//# sourceMappingURL=chunk-2PYF5JFG.mjs.map