@atomicmemory/core 1.0.0

package/dist/storage/providers/filecoin/metadata.js

@@ -0,0 +1,137 @@
+/**
+ * @file Filecoin provider-internal metadata allowlist + denylist.
+ *
+ * The public projector lives in
+ * `src/storage/filecoin-public-metadata.ts` so routes / services
+ * don't have to import `providers/filecoin/*` directly. What
+ * remains here is provider-internal:
+ *
+ *   - `buildFilecoinMetadata(input)` produces the closed-shape
+ *     Synapse piece-metadata envelope upload calls may pass through.
+ *     Synapse's `METADATA_LIMITS.MAX_KEYS_PER_PIECE`
+ *     is 5 (per docs.filecoin.cloud/reference/filoz/synapse-core/
+ *     utils/variables/metadata_limits/); this builder enforces the
+ *     cap so an over-allowed envelope cannot reach Synapse and
+ *     fail mid-upload. Key length is also capped at the documented
+ *     32 chars and string values at 128 chars.
+ *   - The allowlist, denylist, and reserved-prefix constants the
+ *     upload + central config validators share (config.ts's
+ *     DATA_SET_METADATA validation reads from the same constants
+ *     and applies the dataset-side limits 10 / 32 / 128).
+ *
+ * Upload-side safety rule: this module NEVER lets private keys,
+ * wallet addresses, payment-rail state, signed requests, auth
+ * headers, UCAN proofs, raw Synapse responses, or any other key on
+ * the denylist reach the provider. Reserved prefixes
+ * (`atomicmemory.`, `synapse.`, `filecoin.`, `_`) are rejected as
+ * caller-supplied keys.
+ *
+ * Read-side projection — what survives onto the public wire when
+ * reading `raw_documents.raw_storage_metadata.filecoin` back — is
+ * the shared module's job (`projectFilecoinPublicMetadata`). The
+ * internal `copies: [{ provider_id, status }]` shape flattens to
+ * scalar `copy_count` / `provider_ids` / `copy_statuses` over
+ * there.
+ */
+export const ALLOWED_FILECOIN_METADATA_KEYS = [
+    'artifact_id',
+    'storage_profile_id',
+    'content_type',
+    'stored_hash',
+    'codec_name',
+    'codec_version',
+    'codec_key_id',
+    'source_kind',
+];
+/**
+ * Closed denylist — keys / shapes `buildFilecoinMetadata` MUST
+ * reject if a caller (or a stray test fixture) tries to push them
+ * onto a Filecoin upload. The list pins items that, if leaked
+ * through `provider_metadata` or `data_set_metadata`, would expose
+ * secrets or sensitive operational state.
+ */
+export const FILECOIN_METADATA_DENYLIST = [
+    'private_key',
+    'wallet_address',
+    'payment_rail',
+    'rail_id',
+    'signed_request',
+    'authorization',
+    'auth_header',
+    'ucan_proof',
+    'synapse_response',
+    'raw_synapse_payload',
+];
+export const FILECOIN_METADATA_RESERVED_PREFIXES = [
+    'atomicmemory.',
+    'synapse.',
+    'filecoin.',
+    '_',
+];
+const ALLOWED_KEY_SET = new Set(ALLOWED_FILECOIN_METADATA_KEYS);
+const DENY_KEY_SET = new Set(FILECOIN_METADATA_DENYLIST);
+/**
+ * Mirrored from Synapse's `METADATA_LIMITS` (per
+ * docs.filecoin.cloud/reference/filoz/synapse-core/utils/variables/
+ * metadata_limits/). The dataset-side limits (10 keys) live in
+ * `./config.ts`; the piece-side limits (5 keys) live here because
+ * `buildFilecoinMetadata` produces the per-piece envelope.
+ */
+const MAX_PIECE_METADATA_KEYS = 5;
+const MAX_PIECE_METADATA_KEY_LENGTH = 32;
+const MAX_PIECE_METADATA_VALUE_LENGTH = 128;
+/**
+ * Project caller-supplied metadata down to the allowlisted closed
+ * envelope, enforcing Synapse's per-piece limits (≤5 entries, ≤32
+ * char keys, ≤128 char string values). Throws on denylisted keys,
+ * reserved-prefix keys, non-scalar values, over-long strings, or
+ * an output that would exceed the 5-key cap. Unknown (non-
+ * allowlisted, non-denylisted) keys are silently dropped — fail-
+ * open on inputs we don't understand would surface secrets on a
+ * future contributor's keystroke.
+ */
+export function buildFilecoinMetadata(input) {
+    const out = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(input)) {
+        rejectReservedOrDeniedKey(key);
+        if (!ALLOWED_KEY_SET.has(key))
+            continue;
+        if (key.length > MAX_PIECE_METADATA_KEY_LENGTH) {
+            throw new Error(`Filecoin metadata key '${key}' exceeds Synapse MAX_KEY_LENGTH ` +
+                `(${MAX_PIECE_METADATA_KEY_LENGTH}).`);
+        }
+        if (count >= MAX_PIECE_METADATA_KEYS) {
+            throw new Error(`Filecoin piece metadata would exceed Synapse MAX_KEYS_PER_PIECE ` +
+                `(${MAX_PIECE_METADATA_KEYS}). Drop entries before calling buildFilecoinMetadata.`);
+        }
+        out[key] = coerceLeaf(key, value);
+        count += 1;
+    }
+    return out;
+}
+function rejectReservedOrDeniedKey(key) {
+    for (const prefix of FILECOIN_METADATA_RESERVED_PREFIXES) {
+        if (key.startsWith(prefix)) {
+            throw new Error(`Filecoin metadata key '${key}' uses reserved prefix '${prefix}'.`);
+        }
+    }
+    if (DENY_KEY_SET.has(key.toLowerCase())) {
+        throw new Error(`Filecoin metadata key '${key}' is denylisted.`);
+    }
+}
+function coerceLeaf(key, value) {
+    if (typeof value === 'string') {
+        if (value.length > MAX_PIECE_METADATA_VALUE_LENGTH) {
+            throw new Error(`Filecoin metadata value for '${key}' exceeds Synapse ` +
+                `MAX_VALUE_LENGTH (${MAX_PIECE_METADATA_VALUE_LENGTH}, got ${value.length}).`);
+        }
+        return value;
+    }
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    throw new Error(`Filecoin metadata value for '${key}' must be a scalar ` +
+        '(string, finite number, or boolean).');
+}

package/dist/storage/providers/filecoin/piece-cid.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file Synapse-SDK-backed PieceCID parser for the provider
+ * boundary.
+ *
+ * The shared validator (`src/storage/filecoin-cid-validation.ts`)
+ * is intentionally a structural-shape regex with no codec
+ * awareness. It exists so the public-projection seam can silently
+ * drop adversarial JSONB without dynamically loading the Filecoin
+ * SDK at startup (the eager-import path runs even when
+ * `RAW_STORAGE_PROVIDER !== 'filecoin'`).
+ *
+ * The provider boundary is the OPPOSITE trust seam: anything that
+ * crosses `parsePieceUri` / `formatPieceUri` /
+ * `FilecoinRawContentStore.put` must match the real PieceCIDv2
+ * grammar the rest of the Synapse pipeline operates on — CIDv1,
+ * raw codec (0x55), multihash code 0x1011
+ * (`fr32-sha2-256-trunc254-padded-binary-tree` from
+ * `@web3-storage/data-segment`). A string that merely "looks like"
+ * a PieceCID but cannot round-trip through the SDK would be
+ * persisted only to fail downstream at `head` / `get` / `delete`
+ * with a vendor-shaped error that callers can't sanitize.
+ *
+ * This module sits inside the provider directory and is reached
+ * only through the lazy provider-load graph established in Phase
+ * 2 — importing it does NOT pull the Synapse SDK into a non-
+ * Filecoin-provider startup. The wrapper is intentionally
+ * minimal: it just translates the SDK's `asPieceCID(...) | null`
+ * contract into a typed `FilecoinProviderError('invalid_piece_cid',
+ * ...)` with a sanitized message (no value echo) so callers
+ * never surface vendor stack traces.
+ */
+/**
+ * Returns the SDK's canonical string form of `value` as a
+ * PieceCIDv2, or throws `FilecoinProviderError('invalid_piece_cid',
+ * ...)` with a sanitized message when the value is not a string,
+ * not a parsable CID, or is a CID that does not satisfy
+ * `isPieceCID` (codec/multihash/version).
+ *
+ * Used at trust seams where a malformed value must NOT be
+ * persisted (URI parser, URI formatter, upload result mapper).
+ * `context` is a short noun-phrase that names the seam the
+ * caller is guarding (e.g. `"upload result"`, `"storage URI"`).
+ * The value itself is NEVER echoed into the error message —
+ * malformed CIDs may encode adversarial bytes worth keeping out
+ * of log streams. The closed-set `errorCode` is the diagnostic
+ * surface.
+ */
+export declare function requirePieceCid(value: unknown, context: string): string;

package/dist/storage/providers/filecoin/piece-cid.js

@@ -0,0 +1,57 @@
+/**
+ * @file Synapse-SDK-backed PieceCID parser for the provider
+ * boundary.
+ *
+ * The shared validator (`src/storage/filecoin-cid-validation.ts`)
+ * is intentionally a structural-shape regex with no codec
+ * awareness. It exists so the public-projection seam can silently
+ * drop adversarial JSONB without dynamically loading the Filecoin
+ * SDK at startup (the eager-import path runs even when
+ * `RAW_STORAGE_PROVIDER !== 'filecoin'`).
+ *
+ * The provider boundary is the OPPOSITE trust seam: anything that
+ * crosses `parsePieceUri` / `formatPieceUri` /
+ * `FilecoinRawContentStore.put` must match the real PieceCIDv2
+ * grammar the rest of the Synapse pipeline operates on — CIDv1,
+ * raw codec (0x55), multihash code 0x1011
+ * (`fr32-sha2-256-trunc254-padded-binary-tree` from
+ * `@web3-storage/data-segment`). A string that merely "looks like"
+ * a PieceCID but cannot round-trip through the SDK would be
+ * persisted only to fail downstream at `head` / `get` / `delete`
+ * with a vendor-shaped error that callers can't sanitize.
+ *
+ * This module sits inside the provider directory and is reached
+ * only through the lazy provider-load graph established in Phase
+ * 2 — importing it does NOT pull the Synapse SDK into a non-
+ * Filecoin-provider startup. The wrapper is intentionally
+ * minimal: it just translates the SDK's `asPieceCID(...) | null`
+ * contract into a typed `FilecoinProviderError('invalid_piece_cid',
+ * ...)` with a sanitized message (no value echo) so callers
+ * never surface vendor stack traces.
+ */
+import { asPieceCID } from '@filoz/synapse-core/piece';
+import { FilecoinProviderError } from './errors.js';
+/**
+ * Returns the SDK's canonical string form of `value` as a
+ * PieceCIDv2, or throws `FilecoinProviderError('invalid_piece_cid',
+ * ...)` with a sanitized message when the value is not a string,
+ * not a parsable CID, or is a CID that does not satisfy
+ * `isPieceCID` (codec/multihash/version).
+ *
+ * Used at trust seams where a malformed value must NOT be
+ * persisted (URI parser, URI formatter, upload result mapper).
+ * `context` is a short noun-phrase that names the seam the
+ * caller is guarding (e.g. `"upload result"`, `"storage URI"`).
+ * The value itself is NEVER echoed into the error message —
+ * malformed CIDs may encode adversarial bytes worth keeping out
+ * of log streams. The closed-set `errorCode` is the diagnostic
+ * surface.
+ */
+export function requirePieceCid(value, context) {
+    if (typeof value === 'string') {
+        const parsed = asPieceCID(value);
+        if (parsed !== null)
+            return parsed.toString();
+    }
+    throw new FilecoinProviderError('invalid_piece_cid', `Filecoin ${context} carries a value that is not a valid PieceCIDv2.`);
+}

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

@@ -0,0 +1,234 @@
+/**
+ * @file Filecoin provider-client interface — the seam between the
+ * `RawContentStore` adapter and any vendor-specific Filecoin client.
+ *
+ * The interface admits two drivers today (`FilecoinDriverName =
+ * 'synapse' | 'filecoin_pin'`). The default is `'synapse'`,
+ * backed by `@filoz/synapse-sdk` directly; the Phase 5 opt-in
+ * `'filecoin_pin'` driver is backed by `filecoin-pin/core/upload`
+ * and composes the Synapse client for non-CAR-first operations.
+ * The closed-union type forces every new driver to be a literal-
+ * by-literal addition; never widen it to plain `string`.
+ *
+ * Boundary rules:
+ *
+ * - The wrapper `backend.ts` is the ONLY caller of these methods.
+ *   The reconciler, the route layer, and the service layer never
+ *   talk to a `FilecoinProviderClient` directly.
+ * - Inputs and outputs are AtomicMemory-shaped, NOT Synapse-shaped.
+ *   Mapping happens inside the concrete client
+ *   (`synapse-client.ts`); vendor types never escape
+ *   `providers/filecoin/`.
+ * - Sanitization (see `errors.ts`): any vendor error a client
+ *   catches must be replaced with a `FilecoinProviderError` whose
+ *   `errorCode` is one of the documented stable codes. Raw vendor
+ *   messages do not escape.
+ */
+export interface FilecoinCopySnapshot {
+    /** SP identifier (stringified bigint — JSON cannot carry bigint). */
+    readonly providerId: string;
+    /** Data-set identifier this copy lives in (stringified bigint). */
+    readonly dataSetId: string;
+    /**
+     * Piece-id within the data set (stringified positive decimal
+     * bigint). OMITTED when the underlying driver returned a
+     * sentinel/non-positive value: filecoin-pin's `executeUpload`
+     * can return `pieceId === 0n` for copies that have been stored
+     * at the SP but not yet confirmed at the data-set, and writing
+     * the raw `'0'` into the sidecar would later trip the hint
+     * reader's positive-decimal-bigint validator and emit a
+     * spurious `filecoin.hint.malformed` diagnostic on every
+     * delete. Absent is silently skipped; only positive values are
+     * carried.
+     */
+    readonly pieceId?: string;
+    /** `'primary'` (uploaded direct) or `'secondary'` (pulled SP→SP). */
+    readonly role: 'primary' | 'secondary';
+}
+export interface FilecoinFailedAttempt {
+    readonly providerId: string;
+    readonly role: 'primary' | 'secondary';
+    /** Sanitized error code; never the raw vendor message. */
+    readonly errorCode: string;
+    /** Whether the caller explicitly pinned the provider (no retry). */
+    readonly explicit: boolean;
+}
+export interface FilecoinPutInput {
+    /**
+     * Storage-key prefix the upload pipeline computed (PII-safe HMAC).
+     * The Synapse client does not consume this directly — the SDK
+     * routes by data set, not key — but the adapter still propagates
+     * it for shared observability/metrics with the immediate
+     * providers.
+     */
+    readonly key: string;
+    /** Bytes to upload. The Synapse SDK accepts `Uint8Array | ReadableStream`. */
+    readonly body: Buffer;
+    readonly contentType?: string;
+    /**
+     * Optional sanitized per-piece metadata produced by
+     * `metadata.ts:buildFilecoinMetadata`. Caller is responsible for
+     * staying under Synapse's `MAX_KEYS_PER_PIECE` cap. The adapter
+     * passes this through to `StorageManager.upload`'s
+     * `pieceMetadata` option as string-only entries.
+     */
+    readonly pieceMetadata?: Readonly<Record<string, string>>;
+    /** Per-call timeout (ms); the adapter wires this to an `AbortSignal`. */
+    readonly timeoutMs?: number;
+}
+export interface FilecoinPutResult {
+    /** PieceCID stringified for stable serialization across logs/storage. */
+    readonly pieceCid: string;
+    /**
+     * Canonical storage URI persisted on the row, of the form
+     * `filecoin://piece/<pieceCid>`.
+     */
+    readonly storageUri: string;
+    /** Bytes the SDK reported as stored (post-padding). */
+    readonly sizeBytes: number;
+    /** Successful copies reported by `UploadResult.copies`. */
+    readonly copies: ReadonlyArray<FilecoinCopySnapshot>;
+    /** Sanitized failed attempts from `UploadResult.failedAttempts`. */
+    readonly failedAttempts: ReadonlyArray<FilecoinFailedAttempt>;
+    /** `true` iff every requested copy succeeded. */
+    readonly complete: boolean;
+    /** Copy count the caller requested (echoed from the SDK). */
+    readonly requestedCopies: number;
+    /**
+     * Optional IPFS / CAR-root CID (CIDv1, any IPLD codec) the
+     * driver derived alongside the PieceCID. The live Synapse
+     * driver leaves this `undefined` today; the filecoin-pin
+     * driver (Phase 5) is expected to populate it so consumers
+     * can resolve content via IPFS gateways without re-deriving
+     * the CID from bytes. The adapter validates the value via
+     * `requireIpfsCid` (real `multiformats/cid` parse), persists
+     * the canonical multibase form under
+     * `raw_storage_metadata.filecoin.ipfs_cid`, and projects it
+     * publicly as `ipfs_cid`. The canonical AtomicMemory storage
+     * URI stays `filecoin://piece/<canonicalPieceCid>` regardless —
+     * `ipfsCid` does NOT change row identity.
+     */
+    readonly ipfsCid?: string;
+}
+export interface FilecoinGetInput {
+    readonly storageUri: string;
+    readonly timeoutMs?: number;
+}
+export interface FilecoinGetResult {
+    readonly body: Buffer;
+    /**
+     * Bounded provider metadata that survived public projection. The
+     * adapter does NOT echo the full SDK download result back — it
+     * only carries the piece identity for the reconciler.
+     */
+    readonly providerMetadata: Record<string, unknown>;
+}
+export interface FilecoinHeadInput {
+    readonly storageUri: string;
+    /**
+     * Optional hint for which data set holds the piece. When omitted
+     * the adapter consults `StorageManager.findDataSets` to locate
+     * the right context.
+     */
+    readonly dataSetId?: string;
+}
+export interface FilecoinHeadResult {
+    readonly exists: boolean;
+    /**
+     * `true` once the piece is retrievable AND the data set's most
+     * recent proof has been accepted. Bounded so the reconciler can
+     * promote `blob_pending → blob_available` without exposing the
+     * full PDP cycle state on the public wire.
+     */
+    readonly proven: boolean;
+    readonly providerMetadata: Record<string, unknown>;
+}
+export interface FilecoinDeleteInput {
+    readonly storageUri: string;
+    readonly dataSetId?: string;
+    /**
+     * Positive decimal bigint string carrying the per-copy
+     * `piece_id` Synapse assigned at upload time (see
+     * `UploadResult.copies[].pieceId` and the sidecar
+     * `raw_storage_metadata.filecoin.copies[].piece_id`). When
+     * supplied, the Synapse driver issues
+     * `deletePiece({ piece: BigInt(pieceId) })` against the
+     * resolved data-set context. This bypasses the SDK's
+     * CID→active-piece lookup, which cannot resolve freshly
+     * uploaded pieces before PDP proof lands — the lookup path
+     * is the failure mode the live calibration smoke surfaced.
+     */
+    readonly pieceId?: string;
+}
+export interface FilecoinDeleteResult {
+    readonly deleted: boolean;
+    readonly semantics: 'tombstone' | 'unpin' | 'delete';
+    /**
+     * Hex transaction hash of the scheduled-removal tx, when the
+     * provider returned one. `undefined` is reported as
+     * `already-scheduled` semantics.
+     */
+    readonly txHash?: string;
+}
+export interface FilecoinVerifyInput {
+    readonly storageUri: string;
+    readonly expectedContentHash: string;
+    readonly timeoutMs?: number;
+}
+export interface FilecoinVerifyResult {
+    readonly verified: boolean;
+    readonly reason?: string;
+}
+export type FilecoinReadinessNetwork = 'calibration' | 'mainnet';
+export type FilecoinReadinessStatus = 'passed' | 'failed' | 'unknown';
+/**
+ * Closed-shape readiness probe entry. Errors are reported via the
+ * opaque `errorCode` from a documented stable set — raw vendor
+ * messages, wallet addresses, allowances, and provider auth
+ * payloads do NOT cross this boundary.
+ */
+export interface FilecoinReadinessCheck {
+    readonly name: string;
+    readonly status: FilecoinReadinessStatus;
+    readonly errorCode?: string;
+}
+/**
+ * Closed union of accepted driver names. New drivers MUST be added
+ * to this union literal-by-literal so exhaustive `switch (driver)`
+ * coverage stays compiler-enforced. NEVER widen this to plain
+ * `string` — that would forfeit the exhaustiveness invariant the
+ * harvest plan §Virtues 1 calls out. Adding a new value here is a
+ * type-level capability gate; runtime acceptance is gated
+ * separately by `parseFilecoinProviderConfig` in `config.ts`.
+ */
+export type FilecoinDriverName = 'synapse' | 'filecoin_pin';
+export interface FilecoinProviderClient {
+    readonly provider: 'filecoin';
+    readonly driver: FilecoinDriverName;
+    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>;
+    /**
+     * Non-mutating readiness probe used by the factory and (later)
+     * the reconciler. The provider client owns the probe — the
+     * adapter, route layer, and document service never call into
+     * the SDK for readiness. Every check carries a stable
+     * `errorCode` from the documented enum so log consumers and
+     * tests can rely on the shape regardless of how the SDK
+     * reports the underlying condition.
+     */
+    checkReadiness(network: FilecoinReadinessNetwork): Promise<ReadonlyArray<FilecoinReadinessCheck>>;
+    /**
+     * Non-mutating SDK read of the provider's advertised minimum
+     * upload size in bytes. Used by preflight/sizing callers
+     * (live calibration smoke + future direct-upload sizing) to
+     * size payloads against the provider's real contract rather
+     * than a baked-in constant. Lookup failures throw a typed
+     * `FilecoinProviderError` (errorCode `filecoin_storage_info_failed`
+     * on Synapse; per-driver code on other implementations); they
+     * never resolve to `null` or silently degrade.
+     */
+    getServiceMinUploadBytes(): Promise<number>;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * @file Filecoin provider-client interface — the seam between the
+ * `RawContentStore` adapter and any vendor-specific Filecoin client.
+ *
+ * The interface admits two drivers today (`FilecoinDriverName =
+ * 'synapse' | 'filecoin_pin'`). The default is `'synapse'`,
+ * backed by `@filoz/synapse-sdk` directly; the Phase 5 opt-in
+ * `'filecoin_pin'` driver is backed by `filecoin-pin/core/upload`
+ * and composes the Synapse client for non-CAR-first operations.
+ * The closed-union type forces every new driver to be a literal-
+ * by-literal addition; never widen it to plain `string`.
+ *
+ * Boundary rules:
+ *
+ * - The wrapper `backend.ts` is the ONLY caller of these methods.
+ *   The reconciler, the route layer, and the service layer never
+ *   talk to a `FilecoinProviderClient` directly.
+ * - Inputs and outputs are AtomicMemory-shaped, NOT Synapse-shaped.
+ *   Mapping happens inside the concrete client
+ *   (`synapse-client.ts`); vendor types never escape
+ *   `providers/filecoin/`.
+ * - Sanitization (see `errors.ts`): any vendor error a client
+ *   catches must be replaced with a `FilecoinProviderError` whose
+ *   `errorCode` is one of the documented stable codes. Raw vendor
+ *   messages do not escape.
+ */
+export {};

package/dist/storage/providers/filecoin/readiness.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @file Filecoin readiness — INTERNAL-only.
+ *
+ * The check types (`FilecoinReadinessCheck`,
+ * `FilecoinReadinessStatus`, `FilecoinReadinessNetwork`) live on
+ * `provider-client.ts` because they are part of the
+ * `FilecoinProviderClient.checkReadiness` boundary. This module
+ * carries:
+ *
+ *   - `FilecoinReadiness` — the aggregate shape consumers see.
+ *   - `aggregateFilecoinReadiness` — pure aggregator (closed,
+ *     fail-closed on empty input).
+ *   - `checkFilecoinReadiness(client, network)` — thin wrapper
+ *     that delegates to `client.checkReadiness(network)` and
+ *     builds the aggregate.
+ *   - `FILECOIN_READINESS_REQUIRED_CHECKS` — documented required
+ *     probe names.
+ *
+ * The aggregate is INTERNAL to `src/storage/providers/filecoin/`
+ * in v1. It is NOT exposed on any public HTTP route, NOT
+ * projected into the SDK, and NOT included in the OpenAPI schema.
+ * The factory exposes the helper so the document-upload pipeline
+ * and (later) the reconciler can gate work on a successful probe
+ * without re-implementing the SDK contract.
+ *
+ * Sanitization rule: the readiness object NEVER carries wallet
+ * addresses, balances, allowances, provider auth payloads, or
+ * raw vendor messages. The only public fields are the check
+ * `name`, status enum, and an opaque `errorCode` string from the
+ * closed set documented at the bottom of this file.
+ */
+import type { FilecoinDriverName, FilecoinProviderClient, FilecoinReadinessCheck, FilecoinReadinessNetwork } from './provider-client.js';
+export type { FilecoinDriverName, FilecoinReadinessCheck, FilecoinReadinessNetwork, FilecoinReadinessStatus, } from './provider-client.js';
+export interface FilecoinReadiness {
+    readonly provider: 'filecoin';
+    readonly driver: FilecoinDriverName;
+    readonly network: FilecoinReadinessNetwork;
+    readonly ready: boolean;
+    readonly checks: ReadonlyArray<FilecoinReadinessCheck>;
+}
+/**
+ * Documented required-check names. Callers may treat any
+ * name not in this list as advisory; everything in it must be
+ * `'passed'` for `ready === true`.
+ */
+export declare const FILECOIN_READINESS_REQUIRED_CHECKS: readonly ["network_reachable", "key_loadable", "account_on_expected_network", "payment_covers_minimum_upload", "provider_ids_reachable", "data_set_available", "retrieval_available", "upload_size_bounds_compatible"];
+/**
+ * Pure aggregator: `ready === true` iff (1) the supplied checks
+ * list is non-empty AND (2) every supplied check has
+ * `status === 'passed'`. An empty list fails CLOSED — a future
+ * wiring bug that hands this function an empty array must NOT
+ * mark Filecoin ready.
+ */
+export declare function aggregateFilecoinReadiness(checks: ReadonlyArray<FilecoinReadinessCheck>): boolean;
+/**
+ * Delegate to the underlying provider client's
+ * `checkReadiness(network)` probe and wrap the result in the
+ * documented aggregate shape. The test client returns all-
+ * `'unknown'` checks; the real Synapse client issues
+ * non-mutating SDK reads.
+ */
+export declare function checkFilecoinReadiness(client: FilecoinProviderClient, network: FilecoinReadinessNetwork): Promise<FilecoinReadiness>;

package/dist/storage/providers/filecoin/readiness.js

@@ -0,0 +1,85 @@
+/**
+ * @file Filecoin readiness — INTERNAL-only.
+ *
+ * The check types (`FilecoinReadinessCheck`,
+ * `FilecoinReadinessStatus`, `FilecoinReadinessNetwork`) live on
+ * `provider-client.ts` because they are part of the
+ * `FilecoinProviderClient.checkReadiness` boundary. This module
+ * carries:
+ *
+ *   - `FilecoinReadiness` — the aggregate shape consumers see.
+ *   - `aggregateFilecoinReadiness` — pure aggregator (closed,
+ *     fail-closed on empty input).
+ *   - `checkFilecoinReadiness(client, network)` — thin wrapper
+ *     that delegates to `client.checkReadiness(network)` and
+ *     builds the aggregate.
+ *   - `FILECOIN_READINESS_REQUIRED_CHECKS` — documented required
+ *     probe names.
+ *
+ * The aggregate is INTERNAL to `src/storage/providers/filecoin/`
+ * in v1. It is NOT exposed on any public HTTP route, NOT
+ * projected into the SDK, and NOT included in the OpenAPI schema.
+ * The factory exposes the helper so the document-upload pipeline
+ * and (later) the reconciler can gate work on a successful probe
+ * without re-implementing the SDK contract.
+ *
+ * Sanitization rule: the readiness object NEVER carries wallet
+ * addresses, balances, allowances, provider auth payloads, or
+ * raw vendor messages. The only public fields are the check
+ * `name`, status enum, and an opaque `errorCode` string from the
+ * closed set documented at the bottom of this file.
+ */
+/**
+ * Documented required-check names. Callers may treat any
+ * name not in this list as advisory; everything in it must be
+ * `'passed'` for `ready === true`.
+ */
+export const FILECOIN_READINESS_REQUIRED_CHECKS = [
+    'network_reachable',
+    'key_loadable',
+    'account_on_expected_network',
+    'payment_covers_minimum_upload',
+    'provider_ids_reachable',
+    'data_set_available',
+    'retrieval_available',
+    'upload_size_bounds_compatible',
+];
+/**
+ * Pure aggregator: `ready === true` iff (1) the supplied checks
+ * list is non-empty AND (2) every supplied check has
+ * `status === 'passed'`. An empty list fails CLOSED — a future
+ * wiring bug that hands this function an empty array must NOT
+ * mark Filecoin ready.
+ */
+export function aggregateFilecoinReadiness(checks) {
+    if (checks.length === 0)
+        return false;
+    for (const check of checks) {
+        if (check.status !== 'passed')
+            return false;
+    }
+    return true;
+}
+/**
+ * Delegate to the underlying provider client's
+ * `checkReadiness(network)` probe and wrap the result in the
+ * documented aggregate shape. The test client returns all-
+ * `'unknown'` checks; the real Synapse client issues
+ * non-mutating SDK reads.
+ */
+export async function checkFilecoinReadiness(client, network) {
+    const checks = await client.checkReadiness(network);
+    // `driver` reflects the boundary's actual driver — never a
+    // hardcoded literal. Production: the live Synapse client →
+    // `'synapse'`. Tests / a future filecoin-pin client → that
+    // driver's literal. Hardcoding here would lie for non-Synapse
+    // implementations and undermine the driver-agnostic invariant
+    // the harvest plan establishes.
+    return {
+        provider: 'filecoin',
+        driver: client.driver,
+        network,
+        ready: aggregateFilecoinReadiness(checks),
+        checks,
+    };
+}