@atomicmemory/core 1.0.0

package/dist/storage/providers/filecoin/filecoin-pin-client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @file `FilecoinProviderClient` implementation backed by the
+ * `filecoin-pin` package (the Filecoin Project's reference CAR-
+ * first upload pipeline).
+ *
+ * Composition strategy: this client OWNS the `put`, `get`, and
+ * `verify` paths (the three seams where the CAR-first wrapper
+ * differs from direct Synapse) and DELEGATES every other method
+ * to a `SynapseFilecoinProviderClient` instance built off the
+ * same `Synapse` handle. `head`, `delete`, `checkReadiness`,
+ * and `getServiceMinUploadBytes` reach Synapse SDK calls that the
+ * direct driver already implements correctly — re-implementing
+ * them here would duplicate code and risk drifting semantics.
+ *
+ * Sibling helpers split the implementation along three seams:
+ *
+ *   - `filecoin-pin-vendor.ts` — vendor minimal types +
+ *     `loadExecuteUpload` / `loadCarReader` dynamic-import
+ *     loaders + `noopLogger`. Owns the
+ *     `optionalDependencies`-safe vendor boundary.
+ *   - `filecoin-pin-timeout.ts` — `makeTimeoutHandle` (cancellable
+ *     timeout sentinel for `put`'s `Promise.race`).
+ *   - `filecoin-pin-mapping.ts` — `buildCarOrThrow`,
+ *     `buildUploadOptions`, `mapCopies` / `mapFailedAttempts` /
+ *     `mapPutResult` / `mapPutFailure`. Vendor→provider-neutral
+ *     wire-shape translation.
+ *
+ * Why delegate `head`/`delete` to the direct driver:
+ *   - `filecoin-pin` does not ship a dedicated head/delete
+ *     surface. Both the direct and CAR-first paths ultimately
+ *     call the same Synapse SDK primitives (`pieceStatus`,
+ *     `deletePiece`), so delegation preserves the Phase 3/4
+ *     contracts (canonical PieceCID identity, sanitized errors,
+ *     piece-id hinted delete) without copy-paste.
+ *   - Delete semantics: the Synapse delegate returns the existing
+ *     provider tombstone behaviour. The plan calls for "weaker
+ *     semantics" if the new driver cannot match — it CAN match,
+ *     so we return the same `tombstone` value the direct driver
+ *     produces.
+ *
+ * Why `put`/`get`/`verify` are owned here:
+ *   - `put` builds a UnixFS DAG from the input bytes, serialises
+ *     to a CAR, and hands the CAR to filecoin-pin's
+ *     `executeUpload`. The IPFS root CID is captured and surfaced
+ *     as the optional Phase 4 `ipfsCid` field — that is the
+ *     concrete value-add of the filecoin-pin path over direct
+ *     Synapse.
+ *   - `get` reverses the wrapper: download the CAR via the same
+ *     Synapse retrieval path the delegate uses, require the CAR
+ *     to declare exactly one root (a multi-root CAR is malformed
+ *     for our put-side contract and is rejected as
+ *     `filecoin_pin_car_ambiguous_roots`; a stale sidecar must
+ *     not redirect retrieval either), and walk the UnixFS DAG to
+ *     recover the original bytes. The wire-level `get` contract
+ *     still says "return the bytes that were put".
+ *   - `verify` overrides the delegate's `verify` because the
+ *     Synapse-side path would hash CAR bytes, but the upload
+ *     pipeline recorded a plaintext SHA-256. The override runs
+ *     through THIS client's `get` and hashes the extracted
+ *     plaintext. `input.timeoutMs` flows through to the
+ *     retrieval so verify stays bounded the same way direct
+ *     Synapse verify is bounded.
+ *
+ * Vendor isolation: every static value/type import of an
+ * optional package lives behind the helpers above. The
+ * `filecoin-pin-lazy-boundary.test.ts` static-import scan asserts
+ * NO production source file in `providers/filecoin/` statically
+ * imports `filecoin-pin/*`, `@helia/*`, `@ipld/car`,
+ * `blockstore-core`, or `pino`. `tsc -p tsconfig.build.json`
+ * passes against a synapse-only install (`npm ci
+ * --legacy-peer-deps --omit=optional`).
+ */
+import type { Synapse } from '@filoz/synapse-sdk';
+import { type FilecoinPinClientOptions } from './filecoin-pin-mapping.js';
+import type { SynapseFilecoinProviderClient } from './synapse-client.js';
+import type { FilecoinDeleteInput, FilecoinDeleteResult, FilecoinGetInput, FilecoinGetResult, FilecoinHeadInput, FilecoinHeadResult, FilecoinProviderClient, FilecoinPutInput, FilecoinPutResult, FilecoinReadinessCheck, FilecoinVerifyInput, FilecoinVerifyResult } from './provider-client.js';
+export type { FilecoinPinClientOptions } from './filecoin-pin-mapping.js';
+export declare class FilecoinPinFilecoinProviderClient implements FilecoinProviderClient {
+    private readonly synapse;
+    private readonly synapseDelegate;
+    private readonly options;
+    readonly provider: "filecoin";
+    readonly driver: "filecoin_pin";
+    constructor(synapse: Synapse, synapseDelegate: SynapseFilecoinProviderClient, options?: FilecoinPinClientOptions);
+    put(input: FilecoinPutInput): Promise<FilecoinPutResult>;
+    get(input: FilecoinGetInput): Promise<FilecoinGetResult>;
+    head(input: FilecoinHeadInput): Promise<FilecoinHeadResult>;
+    delete(input: FilecoinDeleteInput): Promise<FilecoinDeleteResult>;
+    verify(input: FilecoinVerifyInput): Promise<FilecoinVerifyResult>;
+    checkReadiness(network: 'calibration' | 'mainnet'): Promise<ReadonlyArray<FilecoinReadinessCheck>>;
+    getServiceMinUploadBytes(): Promise<number>;
+}

package/dist/storage/providers/filecoin/filecoin-pin-client.js

@@ -0,0 +1,199 @@
+/**
+ * @file `FilecoinProviderClient` implementation backed by the
+ * `filecoin-pin` package (the Filecoin Project's reference CAR-
+ * first upload pipeline).
+ *
+ * Composition strategy: this client OWNS the `put`, `get`, and
+ * `verify` paths (the three seams where the CAR-first wrapper
+ * differs from direct Synapse) and DELEGATES every other method
+ * to a `SynapseFilecoinProviderClient` instance built off the
+ * same `Synapse` handle. `head`, `delete`, `checkReadiness`,
+ * and `getServiceMinUploadBytes` reach Synapse SDK calls that the
+ * direct driver already implements correctly — re-implementing
+ * them here would duplicate code and risk drifting semantics.
+ *
+ * Sibling helpers split the implementation along three seams:
+ *
+ *   - `filecoin-pin-vendor.ts` — vendor minimal types +
+ *     `loadExecuteUpload` / `loadCarReader` dynamic-import
+ *     loaders + `noopLogger`. Owns the
+ *     `optionalDependencies`-safe vendor boundary.
+ *   - `filecoin-pin-timeout.ts` — `makeTimeoutHandle` (cancellable
+ *     timeout sentinel for `put`'s `Promise.race`).
+ *   - `filecoin-pin-mapping.ts` — `buildCarOrThrow`,
+ *     `buildUploadOptions`, `mapCopies` / `mapFailedAttempts` /
+ *     `mapPutResult` / `mapPutFailure`. Vendor→provider-neutral
+ *     wire-shape translation.
+ *
+ * Why delegate `head`/`delete` to the direct driver:
+ *   - `filecoin-pin` does not ship a dedicated head/delete
+ *     surface. Both the direct and CAR-first paths ultimately
+ *     call the same Synapse SDK primitives (`pieceStatus`,
+ *     `deletePiece`), so delegation preserves the Phase 3/4
+ *     contracts (canonical PieceCID identity, sanitized errors,
+ *     piece-id hinted delete) without copy-paste.
+ *   - Delete semantics: the Synapse delegate returns the existing
+ *     provider tombstone behaviour. The plan calls for "weaker
+ *     semantics" if the new driver cannot match — it CAN match,
+ *     so we return the same `tombstone` value the direct driver
+ *     produces.
+ *
+ * Why `put`/`get`/`verify` are owned here:
+ *   - `put` builds a UnixFS DAG from the input bytes, serialises
+ *     to a CAR, and hands the CAR to filecoin-pin's
+ *     `executeUpload`. The IPFS root CID is captured and surfaced
+ *     as the optional Phase 4 `ipfsCid` field — that is the
+ *     concrete value-add of the filecoin-pin path over direct
+ *     Synapse.
+ *   - `get` reverses the wrapper: download the CAR via the same
+ *     Synapse retrieval path the delegate uses, require the CAR
+ *     to declare exactly one root (a multi-root CAR is malformed
+ *     for our put-side contract and is rejected as
+ *     `filecoin_pin_car_ambiguous_roots`; a stale sidecar must
+ *     not redirect retrieval either), and walk the UnixFS DAG to
+ *     recover the original bytes. The wire-level `get` contract
+ *     still says "return the bytes that were put".
+ *   - `verify` overrides the delegate's `verify` because the
+ *     Synapse-side path would hash CAR bytes, but the upload
+ *     pipeline recorded a plaintext SHA-256. The override runs
+ *     through THIS client's `get` and hashes the extracted
+ *     plaintext. `input.timeoutMs` flows through to the
+ *     retrieval so verify stays bounded the same way direct
+ *     Synapse verify is bounded.
+ *
+ * Vendor isolation: every static value/type import of an
+ * optional package lives behind the helpers above. The
+ * `filecoin-pin-lazy-boundary.test.ts` static-import scan asserts
+ * NO production source file in `providers/filecoin/` statically
+ * imports `filecoin-pin/*`, `@helia/*`, `@ipld/car`,
+ * `blockstore-core`, or `pino`. `tsc -p tsconfig.build.json`
+ * passes against a synapse-only install (`npm ci
+ * --legacy-peer-deps --omit=optional`).
+ */
+import { createHash } from 'node:crypto';
+import { CID } from 'multiformats/cid';
+import { FilecoinProviderError } from './errors.js';
+import { extractFileFromCar } from './filecoin-pin-car.js';
+import { buildCarOrThrow, buildUploadOptions, mapPutFailure, mapPutResult, } from './filecoin-pin-mapping.js';
+import { makeTimeoutHandle } from './filecoin-pin-timeout.js';
+import { loadCarReader, loadExecuteUpload } from './filecoin-pin-vendor.js';
+export class FilecoinPinFilecoinProviderClient {
+    synapse;
+    synapseDelegate;
+    options;
+    provider = 'filecoin';
+    driver = 'filecoin_pin';
+    constructor(synapse, synapseDelegate, options = {}) {
+        this.synapse = synapse;
+        this.synapseDelegate = synapseDelegate;
+        this.options = options;
+    }
+    async put(input) {
+        const built = await buildCarOrThrow(input.body);
+        const timeoutMs = input.timeoutMs ?? this.options.uploadTimeoutMs;
+        const aborter = timeoutMs !== undefined && timeoutMs > 0 ? new AbortController() : null;
+        const uploadOptions = buildUploadOptions(this.options, input, aborter);
+        const executeUpload = await loadExecuteUpload();
+        const uploadPromise = executeUpload(this.synapse, built.carBytes, built.rootCid, uploadOptions);
+        const timeoutHandle = aborter !== null && timeoutMs !== undefined
+            ? makeTimeoutHandle(timeoutMs, aborter)
+            : null;
+        try {
+            const result = timeoutHandle !== null
+                ? await Promise.race([uploadPromise, timeoutHandle.promise])
+                : await uploadPromise;
+            return mapPutResult(result, built);
+        }
+        catch (err) {
+            throw mapPutFailure(err, aborter, timeoutMs);
+        }
+        finally {
+            timeoutHandle?.cancel();
+        }
+    }
+    async get(input) {
+        const carResult = await this.synapseDelegate.get(input);
+        let rootCid;
+        try {
+            const reader = await loadCarReader(carResult.body);
+            const roots = await reader.getRoots();
+            if (roots.length === 0) {
+                throw new FilecoinProviderError('filecoin_pin_car_no_root', 'Retrieved CAR carries no root CID; cannot extract the original file.');
+            }
+            if (roots.length > 1) {
+                // `buildCarFromBytes` emits exactly one root. A retrieved
+                // CAR declaring multiple roots is either malformed or a
+                // crafted payload trying to redirect retrieval — refuse to
+                // silently pick the first.
+                throw new FilecoinProviderError('filecoin_pin_car_ambiguous_roots', 'Retrieved CAR declares multiple roots; filecoin-pin uploads emit exactly one.');
+            }
+            // Re-parse the root string through the canonical
+            // `multiformats/cid` so we hand the unixfs walker an
+            // instance with the prototype methods it expects (the
+            // `@ipld/car`-nested multiformats and the top-level one
+            // structurally match at runtime but are TS-distinct types).
+            rootCid = CID.parse(roots[0].toString());
+        }
+        catch (err) {
+            if (err instanceof FilecoinProviderError)
+                throw err;
+            throw new FilecoinProviderError('filecoin_pin_car_parse_failed', 'filecoin-pin driver could not parse the retrieved CAR.');
+        }
+        let bytes;
+        try {
+            bytes = await extractFileFromCar(carResult.body, rootCid);
+        }
+        catch {
+            throw new FilecoinProviderError('filecoin_pin_car_extract_failed', 'filecoin-pin driver could not extract the file from the retrieved CAR.');
+        }
+        return {
+            body: bytes,
+            providerMetadata: { ...carResult.providerMetadata, ipfs_cid: rootCid.toString() },
+        };
+    }
+    async head(input) {
+        return this.synapseDelegate.head(input);
+    }
+    async delete(input) {
+        return this.synapseDelegate.delete(input);
+    }
+    async verify(input) {
+        // Phase 5 blocker fix: the Synapse delegate's `verify` hashes
+        // whatever bytes Synapse returned for the PieceCID. Under
+        // filecoin-pin those bytes are CAR bytes, NOT the original
+        // plaintext, so the delegate's hash would always mismatch
+        // `expectedContentHash` (which is the plaintext SHA-256
+        // computed at upload time). Run `verify` through THIS client's
+        // `get` — that unwraps the CAR and hashes the extracted
+        // plaintext, matching the upload-side hash contract.
+        // `input.timeoutMs` flows through to the retrieval so verify
+        // stays bounded the same way the direct Synapse verify is
+        // bounded.
+        let body;
+        try {
+            const fetched = await this.get({
+                storageUri: input.storageUri,
+                ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+            });
+            body = fetched.body;
+        }
+        catch (err) {
+            // Surface retrieval/parse failures as a typed `verify`
+            // outcome rather than a raw throw; the reconciler relies
+            // on `verified=false + reason` to drive retries.
+            const reason = err instanceof FilecoinProviderError ? err.errorCode : 'filecoin_pin_verify_get_failed';
+            return { verified: false, reason };
+        }
+        const actual = createHash('sha256').update(body).digest('hex');
+        if (actual !== input.expectedContentHash) {
+            return { verified: false, reason: 'content_hash_mismatch' };
+        }
+        return { verified: true };
+    }
+    async checkReadiness(network) {
+        return this.synapseDelegate.checkReadiness(network);
+    }
+    async getServiceMinUploadBytes() {
+        return this.synapseDelegate.getServiceMinUploadBytes();
+    }
+}

package/dist/storage/providers/filecoin/filecoin-pin-mapping.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Result-shape mapping + option builder for the
+ * filecoin-pin driver's `put` path.
+ *
+ * Lifted out of `filecoin-pin-client.ts` to keep the client
+ * focused on the `FilecoinProviderClient` implementation and
+ * this file focused on the wire-shape translation between the
+ * vendor's `MinimalUploadResult` and our provider-neutral
+ * `FilecoinPutResult`. The closed set of helpers here:
+ *
+ *   - `buildCarOrThrow` — sanitised wrapper around `buildCarFromBytes`.
+ *   - `buildUploadOptions` — assemble the `executeUpload`
+ *     option bag with explicit conditional spreads so each
+ *     field is either present-with-meaning or absent (no
+ *     `undefined`-valued slots).
+ *   - `mapCopies` / `mapFailedAttempts` — vendor→provider-neutral
+ *     copy/failure shape, omitting non-positive piece IDs.
+ *   - `mapPutResult` — build the `FilecoinPutResult` shape from
+ *     the vendor `MinimalUploadResult` + built CAR.
+ *   - `mapPutFailure` — classify a `put`-path error into the
+ *     closed set of typed `FilecoinProviderError`s.
+ *
+ * No vendor module is statically imported here; the file
+ * type-checks under the production build path even when the
+ * `optionalDependencies` graph is absent.
+ */
+import type { CID } from 'multiformats/cid';
+import { FilecoinProviderError } from './errors.js';
+import type { MinimalUploadOptions, MinimalUploadResult } from './filecoin-pin-vendor.js';
+import type { FilecoinPutInput, FilecoinPutResult } from './provider-client.js';
+export interface FilecoinPinClientOptions {
+    readonly copies?: number;
+    readonly providerIds?: ReadonlyArray<string>;
+    readonly dataSetMetadata?: Record<string, string>;
+    readonly uploadTimeoutMs?: number;
+    readonly retrievalTimeoutMs?: number;
+    readonly minUploadBytes?: number | null;
+    readonly maxUploadBytes?: number | null;
+}
+export declare function buildCarOrThrow(body: Buffer): Promise<{
+    carBytes: Buffer;
+    rootCid: CID;
+}>;
+/**
+ * Assemble the option bag we hand to `executeUpload`. The bag is
+ * built with explicit conditional spreads so each field is either
+ * present-with-meaning or absent — no `undefined`-valued slots
+ * that would force the SDK to apply defaults differently from how
+ * the direct driver applies them. IPNI announcement validation is
+ * always disabled here: `put` returns once the CAR is stored, and
+ * the IPNI lookup is a separate network-side concern.
+ */
+export declare function buildUploadOptions(options: FilecoinPinClientOptions, input: FilecoinPutInput, aborter: AbortController | null): MinimalUploadOptions;
+export declare function mapPutResult(result: MinimalUploadResult, built: {
+    carBytes: Buffer;
+    rootCid: CID;
+}): FilecoinPutResult;
+export declare function mapPutFailure(err: unknown, aborter: AbortController | null, timeoutMs: number | undefined): FilecoinProviderError;

package/dist/storage/providers/filecoin/filecoin-pin-mapping.js

@@ -0,0 +1,103 @@
+/**
+ * @file Result-shape mapping + option builder for the
+ * filecoin-pin driver's `put` path.
+ *
+ * Lifted out of `filecoin-pin-client.ts` to keep the client
+ * focused on the `FilecoinProviderClient` implementation and
+ * this file focused on the wire-shape translation between the
+ * vendor's `MinimalUploadResult` and our provider-neutral
+ * `FilecoinPutResult`. The closed set of helpers here:
+ *
+ *   - `buildCarOrThrow` — sanitised wrapper around `buildCarFromBytes`.
+ *   - `buildUploadOptions` — assemble the `executeUpload`
+ *     option bag with explicit conditional spreads so each
+ *     field is either present-with-meaning or absent (no
+ *     `undefined`-valued slots).
+ *   - `mapCopies` / `mapFailedAttempts` — vendor→provider-neutral
+ *     copy/failure shape, omitting non-positive piece IDs.
+ *   - `mapPutResult` — build the `FilecoinPutResult` shape from
+ *     the vendor `MinimalUploadResult` + built CAR.
+ *   - `mapPutFailure` — classify a `put`-path error into the
+ *     closed set of typed `FilecoinProviderError`s.
+ *
+ * No vendor module is statically imported here; the file
+ * type-checks under the production build path even when the
+ * `optionalDependencies` graph is absent.
+ */
+import { FilecoinProviderError } from './errors.js';
+import { buildCarFromBytes } from './filecoin-pin-car.js';
+import { noopLogger } from './filecoin-pin-vendor.js';
+export async function buildCarOrThrow(body) {
+    try {
+        return await buildCarFromBytes(body);
+    }
+    catch {
+        throw new FilecoinProviderError('filecoin_pin_car_build_failed', 'filecoin-pin driver failed to wrap upload bytes into a CAR.');
+    }
+}
+/**
+ * Assemble the option bag we hand to `executeUpload`. The bag is
+ * built with explicit conditional spreads so each field is either
+ * present-with-meaning or absent — no `undefined`-valued slots
+ * that would force the SDK to apply defaults differently from how
+ * the direct driver applies them. IPNI announcement validation is
+ * always disabled here: `put` returns once the CAR is stored, and
+ * the IPNI lookup is a separate network-side concern.
+ */
+export function buildUploadOptions(options, input, aborter) {
+    const providerIds = options.providerIds?.map((id) => BigInt(id));
+    return {
+        logger: noopLogger(),
+        ...(options.copies !== undefined ? { copies: options.copies } : {}),
+        ...(providerIds !== undefined && providerIds.length > 0 ? { providerIds } : {}),
+        ...(options.dataSetMetadata !== undefined ? { metadata: options.dataSetMetadata } : {}),
+        ...(input.pieceMetadata !== undefined ? { pieceMetadata: { ...input.pieceMetadata } } : {}),
+        ...(aborter !== null ? { signal: aborter.signal } : {}),
+        ipniValidation: { enabled: false },
+    };
+}
+function mapCopies(copies) {
+    return copies.map((c) => ({
+        providerId: c.providerId.toString(),
+        dataSetId: c.dataSetId.toString(),
+        // Only carry a positive bigint as the piece-id hint —
+        // filecoin-pin's `executeUpload` returns `0n` for copies
+        // accepted at the SP but not yet confirmed at the data-set,
+        // and persisting `'0'` would trip the hint reader's
+        // positive-decimal-bigint validator. Omitting the field
+        // routes delete through the CID-lookup fallback cleanly.
+        ...(c.pieceId > 0n ? { pieceId: c.pieceId.toString() } : {}),
+        role: c.role,
+    }));
+}
+function mapFailedAttempts(attempts) {
+    // Sanitisation: NEVER pipe the raw vendor `error` string into
+    // the public shape. The closed `errorCode` is what surfaces;
+    // the original message stays inside the driver.
+    return attempts.map((a) => ({
+        providerId: a.providerId.toString(),
+        role: a.role,
+        errorCode: 'filecoin_pin_copy_failed',
+        explicit: a.explicit,
+    }));
+}
+export function mapPutResult(result, built) {
+    return {
+        pieceCid: result.pieceCid,
+        storageUri: `filecoin://piece/${result.pieceCid}`,
+        sizeBytes: built.carBytes.length,
+        copies: mapCopies(result.copies),
+        failedAttempts: mapFailedAttempts(result.failedAttempts),
+        complete: result.complete,
+        requestedCopies: result.requestedCopies,
+        ipfsCid: built.rootCid.toString(),
+    };
+}
+export function mapPutFailure(err, aborter, timeoutMs) {
+    if (err instanceof FilecoinProviderError)
+        return err;
+    if (aborter?.signal.aborted) {
+        return new FilecoinProviderError('filecoin_pin_upload_timeout', `filecoin-pin driver aborted CAR upload after ${timeoutMs} ms.`);
+    }
+    return new FilecoinProviderError('filecoin_pin_upload_failed', 'filecoin-pin driver failed to upload the CAR to Synapse.');
+}

package/dist/storage/providers/filecoin/filecoin-pin-timeout.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Cancellable timeout sentinel for the filecoin-pin
+ * driver's `put` path.
+ *
+ * Lifted out of `filecoin-pin-client.ts` so the client stays
+ * focused on the `FilecoinProviderClient` implementation and
+ * this file owns the (subtle) timer-lifetime contract.
+ *
+ * Contract:
+ *   - `promise` rejects with `FilecoinProviderError(
+ *     'filecoin_pin_upload_timeout', …)` after `timeoutMs` AND
+ *     aborts the supplied controller (cooperative cancel for a
+ *     signal-aware vendor).
+ *   - `cancel()` clears the underlying `setTimeout` AND swallows
+ *     the rejection so the loser of `Promise.race` does not
+ *     surface as `unhandledRejection`.
+ *
+ * Callers MUST invoke `cancel()` in a `finally` block — a
+ * successful upload that does not call `cancel()` would leak the
+ * pending timer and later abort the (now-dead) controller. The
+ * companion fake-timer test in
+ * `__tests__/filecoin-pin-client-options.test.ts` pins both the
+ * timeout-fires and the success-path-no-leak halves of the
+ * contract.
+ */
+export interface TimeoutHandle {
+    readonly promise: Promise<never>;
+    cancel(): void;
+}
+export declare function makeTimeoutHandle(timeoutMs: number, aborter: AbortController): TimeoutHandle;

package/dist/storage/providers/filecoin/filecoin-pin-timeout.js

@@ -0,0 +1,53 @@
+/**
+ * @file Cancellable timeout sentinel for the filecoin-pin
+ * driver's `put` path.
+ *
+ * Lifted out of `filecoin-pin-client.ts` so the client stays
+ * focused on the `FilecoinProviderClient` implementation and
+ * this file owns the (subtle) timer-lifetime contract.
+ *
+ * Contract:
+ *   - `promise` rejects with `FilecoinProviderError(
+ *     'filecoin_pin_upload_timeout', …)` after `timeoutMs` AND
+ *     aborts the supplied controller (cooperative cancel for a
+ *     signal-aware vendor).
+ *   - `cancel()` clears the underlying `setTimeout` AND swallows
+ *     the rejection so the loser of `Promise.race` does not
+ *     surface as `unhandledRejection`.
+ *
+ * Callers MUST invoke `cancel()` in a `finally` block — a
+ * successful upload that does not call `cancel()` would leak the
+ * pending timer and later abort the (now-dead) controller. The
+ * companion fake-timer test in
+ * `__tests__/filecoin-pin-client-options.test.ts` pins both the
+ * timeout-fires and the success-path-no-leak halves of the
+ * contract.
+ */
+import { FilecoinProviderError } from './errors.js';
+export function makeTimeoutHandle(timeoutMs, aborter) {
+    let cancelled = false;
+    let timer = null;
+    const promise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            if (cancelled)
+                return;
+            aborter.abort();
+            reject(new FilecoinProviderError('filecoin_pin_upload_timeout', `filecoin-pin driver aborted CAR upload after ${timeoutMs} ms.`));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    // Silently absorb the rejection if the race already returned a
+    // result — otherwise Node logs `unhandledRejection` when the
+    // sentinel loses.
+    promise.catch(() => undefined);
+    return {
+        promise,
+        cancel() {
+            cancelled = true;
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+        },
+    };
+}

package/dist/storage/providers/filecoin/filecoin-pin-vendor.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @file Vendor-boundary helpers for the filecoin-pin driver.
+ *
+ * Encapsulates the surface that crosses from our code into
+ * `filecoin-pin/core/upload` + `@ipld/car`. The split exists so
+ * `filecoin-pin-client.ts` stays focused on the
+ * `FilecoinProviderClient` implementation while this file owns:
+ *
+ *   - The closed minimal type aliases that mirror just the bits
+ *     of the vendor shapes we consume.
+ *   - The runtime dynamic-import helpers
+ *     (`loadExecuteUpload` / `loadCarReader`).
+ *   - The noop `Logger`-shaped object we hand to
+ *     `executeUpload`'s required `logger` option (so we don't
+ *     pull `pino` into the production type graph).
+ *
+ * Source-build invariant. The production build path
+ * (`tsc -p tsconfig.build.json` / `npm run build`) compiles WITHOUT
+ * the `optionalDependencies` graph present. Two patterns enforce
+ * that here:
+ *
+ *   1. **Local minimal types.** We do NOT `import type { ... }`
+ *      from any optional package. Every shape we consume is
+ *      defined locally so `tsc` never has to resolve the vendor
+ *      type declarations.
+ *
+ *   2. **Non-literal dynamic-import specifiers.** Each
+ *      `await import(...)` call site uses a `VENDOR_*`
+ *      `const`-stored specifier. `tsc` does not statically
+ *      resolve a non-literal `import(specifier)` argument, so a
+ *      synapse-only install
+ *      (`npm ci --legacy-peer-deps --omit=optional`) successfully
+ *      runs `tsc -p tsconfig.build.json` even though the optional
+ *      modules are absent.
+ *
+ * The dev-mode `tsc --noEmit` (against `tsconfig.json`) still
+ * requires the optional packages because TEST files in
+ * `providers/filecoin/__tests__/` import them directly (e.g.
+ * `@ipld/car` for a hand-rolled multi-root CAR fixture). Tests
+ * never run on omit-optional production installs;
+ * `tsconfig.build.json` excludes `__tests__`. See
+ * `filecoin-pin-lazy-boundary.test.ts` for the static-import
+ * invariant that pins this split.
+ */
+import type { Synapse } from '@filoz/synapse-sdk';
+import type { CID } from 'multiformats/cid';
+/** A single SP-side copy result emitted by `executeUpload`. */
+export interface MinimalUploadCopy {
+    readonly providerId: bigint;
+    readonly dataSetId: bigint;
+    readonly pieceId: bigint;
+    readonly role: 'primary' | 'secondary';
+}
+/** A single failed-attempt entry emitted by `executeUpload`. */
+export interface MinimalUploadFailure {
+    readonly providerId: bigint;
+    readonly role: 'primary' | 'secondary';
+    readonly error: string;
+    readonly explicit: boolean;
+}
+/** The closed subset of `UploadExecutionResult` the driver consumes. */
+export interface MinimalUploadResult {
+    readonly pieceCid: string;
+    readonly copies: ReadonlyArray<MinimalUploadCopy>;
+    readonly failedAttempts: ReadonlyArray<MinimalUploadFailure>;
+    readonly complete: boolean;
+    readonly requestedCopies: number;
+}
+/** The closed subset of `UploadExecutionOptions` the driver passes. */
+export interface MinimalUploadOptions {
+    readonly logger: unknown;
+    readonly copies?: number;
+    readonly providerIds?: ReadonlyArray<bigint>;
+    readonly metadata?: Record<string, string>;
+    readonly pieceMetadata?: Record<string, string>;
+    readonly signal?: AbortSignal;
+    readonly ipniValidation?: {
+        readonly enabled: boolean;
+    };
+}
+/** Local signature of `filecoin-pin/core/upload.executeUpload`. */
+export type ExecuteUploadFn = (synapse: Synapse, carData: Uint8Array, rootCid: CID, options: MinimalUploadOptions) => Promise<MinimalUploadResult>;
+/** Closed subset of `@ipld/car.CarReader` the get-side consumes. */
+export interface MinimalCarReader {
+    getRoots(): Promise<ReadonlyArray<{
+        toString(): string;
+    }>>;
+}
+/**
+ * Lazy-load `executeUpload` from `filecoin-pin/core/upload`. The
+ * package is in `optionalDependencies`; if a synapse-only build
+ * was installed via `npm ci --legacy-peer-deps --omit=optional`,
+ * this resolution fails only when an operator selects
+ * `RAW_STORAGE_FILECOIN_DRIVER=filecoin_pin` — the intended
+ * failure mode.
+ */
+export declare function loadExecuteUpload(): Promise<ExecuteUploadFn>;
+/** Lazy-load `CarReader.fromBytes` from `@ipld/car`. */
+export declare function loadCarReader(carBytes: Uint8Array): Promise<MinimalCarReader>;
+/**
+ * Pino-shape silent logger used to satisfy `executeUpload`'s
+ * required `logger` option without taking on `pino` as a runtime
+ * dep. The `MinimalUploadOptions.logger` field is `unknown` by
+ * design so we don't drag pino into the production type graph;
+ * the shape below mirrors the closed set of methods filecoin-pin's
+ * `executeUpload` actually invokes. If a future filecoin-pin
+ * upgrade widens that surface, the runtime call site fails with
+ * a clear vendor-side error rather than producing silent test
+ * passes against a stale shape.
+ */
+export declare function noopLogger(): unknown;