Scaffold the EFS SDK monorepo

.changeset/ambiguous-rpc-local-selection.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+Two correctness fixes: (1) ambiguous JSON-RPC send errors are no longer treated as proof that nothing was broadcast. `RpcError` is removed from the definite-refusal set — `-32000: already known`, `nonce too low`, and `replacement transaction underpriced` all mean the transaction (or a rival for its nonce) is already in the mempool and may mine, so they now surface as the UNKNOWN-send states (`WriteSendUnknownError` / `EasSendUnknown` / `OnchainSendUnknown` / `IndexSendUnknown`) instead of "not sent". Only wallet/provider refusal codes, decoded reverts, and the SDK's own pre-send guards remain definite. (2) List pagination derives its attester selection per request instead of mutating shared primed state — an attester-bound cursor on one `byPage()` call no longer moves a later unbound `byPage()`, `toArray()`, or iteration off the first-ranked candidate on the same `EfsList` handle.

.changeset/ancestor-tag-target-gate.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+Concrete `existingAncestorTagUIDs` are now validated before anything broadcasts: the builder shape-checks them (nonzero bytes32, both content kinds) and stamps them on the plan, and the submission boundary verifies each is an ANCHOR attestation. Their visibility TAGs sit in the LAST layer, so a well-shaped but nonexistent or non-anchor UID previously reverted only after the DATA, file anchor, metadata and placement had mined — a paid, half-applied write.

.changeset/anchor-definition-gate.md

@@ -0,0 +1,6 @@
+---
+"@efs/sdk": patch
+"@efs/solidity": patch
+---
+
+The placement gates now validate BOTH sides of the PIN: `efs.graph.pins.place` and Solidity `EFSLib.place` verify the definition is an ANCHOR attestation (`NotAnchorUID` on the Solidity side, a typed `InvalidArgument` on the TS side) — EdgeResolver accepts any existing attestation as a PIN definition, but path resolution discovers placements by resolving an ANCHOR and only then reading its PIN slot, so a PROPERTY/DATA (or nonexistent) definition confirmed a placement no reader could ever find. The TS check batches into the same `Promise.all` as the target read (multicall-coalesced).

.changeset/atomic-anchor-data-layer.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+The file-ANCHOR now mints in the SAME `multiAttest` layer as DATA (it depends only on the already-resolved parent — concrete, or the last `mkdir -p` folder from an earlier layer). Two `fs.write` calls racing for the same empty path both probe no-anchor; previously the loser's DATA layer mined before its anchor layer reverted `DuplicateFileName`, leaving paid storage plus an orphaned DATA graph with no file written. With the anchor in DATA's layer the slot collision rolls the whole layer back atomically — the loser lands nothing on the EAS side, its storage deploys ride the partial error's `storage` for reuse, and the retry resolves the winner's anchor into the overwrite path. (The Solidity `writeFile` is single-transaction and was already atomic.)

.changeset/attester-must-be-signer.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+The declared `attester` must be the account that actually signs. `submitEdgePlan`, `submitEdgePlanWithUID`, and `Tier1Submitter.submit` now reject a mismatch before broadcasting — previously a direct caller of these exported seams could pass an unrelated address, and the confirmed receipt would stamp it into `roles.author`/`signer`/`payer` (and, on the submitter seam, `DataRef.resolvedBy`), attributing on-chain attestations to an address that never authored them and making later reads through that ref resolve under the wrong lens. Rejected rather than silently corrected: a divergent attester means the caller's model of who is writing is wrong. Relayer/paymaster role divergence still rides `roles`, which is unaffected.

.changeset/bigint-json-and-anchoruid-brand.md

@@ -0,0 +1,11 @@
+---
+"@efs/sdk": patch
+---
+
+DX polish (review P3): a bigint-safe JSON serializer + an `AnchorUID` brand.
+
+- **`efs.toJSON(value, space?)` + the exported `jsonReplacer`.** EFS result DTOs carry `bigint`s — `FileInfo.size`, `ListConfig.maxEntries`, the TAG weight reads, `WriteEstimate.gas`, the EAS `Attestation` time fields — and bare `JSON.stringify` THROWS on a bigint (`TypeError: Do not know how to serialize a BigInt`). That surprised devs the first time they logged a receipt, persisted a result, or handed a DTO across a serialization boundary (TanStack Query's cache, a Next.js Server→Client component prop, `res.json(...)`). `efs.toJSON` (and the lower-level `jsonReplacer`, a plain `JSON.stringify` replacer) render those bigints as decimal strings. Present on read-only clients too; pure + stateless. Documented round-trip caveat: serialization is lossy of the bigint TYPE — bigints come back as strings on `JSON.parse`, not bigints (there is no safe automatic reviver), so the consumer re-`BigInt(…)`s the fields it knows are numeric (same as viem/wagmi at the JSON boundary).
+
+- **`AnchorUID` brand.** A folder ANCHOR's UID is now branded distinctly from `DataUID` (review P3 / A11): `DirEntry`'s dir variant carries `anchorUID: AnchorUID`, its file variant carries `dataUID: DataUID`. Catches the wrong-UID-kind integration bug at the type level — passing a folder anchor where a file's DATA UID is expected. Both are `Hex` at runtime (zero cost); the distinction is type-only. `AnchorUID` is exported alongside `DataUID`.
+
+New exports: `toJSON`, `jsonReplacer`, `AnchorUID`. No runtime behavior change to existing verbs; no bundle-size-relevant code on the read/write hot paths.

.changeset/bound-cursors-remove-unknown-flag.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+Two follow-on corrections: (1) list-pagination cursors now BIND their offset to the attester whose listing they index (`<offset>:<attester>`): resuming re-aligns the selection to the bound attester (continuing that listing exactly — no skip, no duplicate — even when it is no longer the ranked leader), and a cursor whose attester left the candidate set is void, restarting the ranked walk at offset 0 instead of silently applying a foreign offset to the new winner. Legacy bare-numeric cursors still parse and apply to the current selection. (2) `redirects.remove` now threads `IndexSendUnknown` onto `IndexingIncomplete.indexBroadcastUnknown` like `set` does — the previous wave's edit script had crashed before applying the remove-branch change, so a lost-response `indexRevocation` send reported `indexBroadcastUnknown: false`, a provably incorrect outcome for the documented recovery field.

.changeset/bucket-check-solidity-slot-binding.md

@@ -0,0 +1,6 @@
+---
+"@efs/sdk": patch
+"@efs/solidity": patch
+---
+
+The placement-gate matrix completes: (1) the DATA-bucket check is now UNCONDITIONAL in the TS gates — the layered boundary and `pins.place` decode every placement anchor's `(name, forSchema)` payload and refuse anchors outside the DATA file bucket even on standalone plans with no requested slot (a generic-folder or PROPERTY-key ANCHOR passed the schema check but file resolution only discovers DATA-bucket terminals). (2) Solidity `writeFile` and the six-argument `placeExisting` bind reused anchors to the requested `(parent, fileName, DATA)` slot via the shared `_requireAnchorNamesSlot` (reverting the new `AnchorSlotMismatch`), and the standalone `place` enforces the DATA bucket (`NotFileBucketAnchor`) — a valid ANCHOR from another slot previously let the transaction and `EFSFileWritten` confirm while a different path was overwritten or nothing discoverable was placed.

.changeset/builder-uri-metadata-preflight.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+The exported graph builder gains the full byte-plan preflight: (1) every mirror URI is validated (`validateMirrorUri` — blank/oversized URIs previously encoded fine and reverted at the layer-2 MirrorResolver AFTER layer 1 mined, leaving a paid partial graph); (2) `contentHash` and `size` are verified against the supplied bytes before any layer is constructed — the `ContentHash` brand checks format only, so a stale hash from changed bytes persisted permanently and made every fail-closed read (`readText` etc.) reject forever, while a wrong size attested false metadata. `hashContent` is synchronous, so the builder stays pure and sync; the orchestrated `fs.write` path derives both values itself and is unaffected.

.changeset/canonical-anchor-segment-codec.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+Anchor segments are now canonically encoded per contracts specs/02 (NFC + uppercase percent-encoding of the reserved byte set), fixing the P1 where `fs.write('/Q&A: Episode 5/file.txt')` reverted at the ANCHOR layer after storage deployed and a decomposed-Unicode segment silently minted a different permanent slot. One codec module (`names/segment.ts`, new exports `encodeName`/`decodeName`/`isCanonicalName`/`asCanonicalName`/`CanonicalName`/`InvalidAnchorNameError`) mirrors `EFSIndexer._isValidAnchorName` byte-for-byte — including the over-escape rejection the contract enforces but the spec prose omits (flagged upstream). Public `fs.*` path strings and `props`/`fields` keys are HUMAN; encoding happens once at the resolution choke points (`splitPathToCanonical`, `resolvePathToAnchor`, `resolveOrPlanParents`, `readReservedProperty`, `props.set`), validated BEFORE any chain read or storage deploy. A raw string is never sniffed as canonical (provably ambiguous: `100%25` is both a legal human name and a legal canonical form) — the `CanonicalName` brand on `ParentPlan`/`FileWriteGraphInput`/`buildPropertyPlan` is the boundary, with a dev-guard in `buildFileWriteGraph`. Chain-out names decode back to human: `DirEntry.name` and `props.list()` keys now return the strings you wrote (fail-soft verbatim for non-canonical foreign data). BREAKING vs the unreleased scaffold: a pre-encoded segment passed as a path is now treated as human and double-encodes — callers holding canonical forms must `decodeName` first (or use the exported codec); `ParentPlan.fileName`/`missingSegments` are `CanonicalName`. New error code `InvalidAnchorName`. Spec vectors (`Q%26A%3A%20Episode%205`, composed/decomposed `é`, literal `%`, the full reserved-byte table) imported as tests.

.changeset/canonical-arweave-media-name-and-size.md

@@ -0,0 +1,11 @@
+---
+"@efs/sdk": patch
+---
+
+Three write-time validation fixes on values that become authoritative.
+
+Arweave transaction ids must now be canonical base64url. 43 base64url characters carry 258 bits but the id is a 32-byte hash, so the final character's low two bits are padding and must be zero — the length-and-alphabet screen accepted a non-canonical spelling that strict base64url and Arweave parsers reject, and `fs.write` could confirm it as a file's only mirror.
+
+`contentType` no longer accepts media RANGES. Both halves used the HTTP token grammar, which permits the wildcard character, so `text/` + wildcard passed — that is what a client sends in `Accept`, not what a file is, and stored as authoritative metadata it even reads as displayable text because `fs.overview()` keys on the `text/` prefix. Type and subtype now use the RFC 6838 restricted-name grammar; parameter names and values keep the token grammar.
+
+The reserved `size` property is now validated on the shared builder alongside `contentType` and `contentHash`. A malformed value does not degrade gracefully as it first appears: every reader's `parseSize` returns `undefined`, and in `reads/overview.ts` that `undefined` skips the documented pre-fetch `too-large` short-circuit entirely, so the overview attempts a fetch and fails at the render cap instead of returning `{kind: 'too-large'}` without touching the network. `fs.info()` simply omits the size. The canonical non-negative decimal form that file writes emit is required.

.changeset/canonical-schema-uids-lens-address-validation.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+Two boundary-validation fixes: (1) `resolveDeployment` now canonicalizes every schema UID on the returned record to `0x` + 64 lowercase hex (memoized copy; the source record is never mutated) and rejects values it cannot consume with a typed error — verification was already value-tolerant of how a custom record writes a UID (uppercase, leading-zero-shortened), but the non-canonical form then broke strict-equality consumers (the symlink walk reported valid redirect targets as dangling) and `bytes32` ABI encoding. (2) `resolveLens` validates every address at the common lens boundary with `isAddress` — a malformed template-compatible literal (`'0x1234'`) or a custom lens's bad output now fails immediately with a typed error instead of surfacing later as a generic ABI/RPC read failure.

.changeset/canonical-varints-and-strict-media-params.md

@@ -0,0 +1,9 @@
+---
+"@efs/sdk": patch
+---
+
+Two strictness fixes on values that reach the chain irreversibly.
+
+CID varints must now be minimally encoded. `unsigned-varint` requires the shortest form, but the decoder returned the numeric value without checking, so `81 00` and `01` both read as version 1 — meaning a valid CID with a redundant byte spliced in cleared the entire write preflight and could be minted as a file's only mirror, while strict CID parsers and gateways reject the locator outright.
+
+`contentType` parameters are now validated against the real RFC 9110 grammar. The quoted-value branch was `"[^"]*"`, which accepts raw control characters, and the separator used `\s*`, which admits CR and LF. A value like `text/plain; note="a<CR><LF>b"` therefore passed and was persisted as the authoritative PROPERTY and as the ERC-5219 store's reported MIME — a CRLF that any gateway echoing the header would emit verbatim. The quoted branch now spells out `qdtext` and `quoted-pair`, and whitespace is restricted to HTTP `OWS` (SP/HTAB). Legitimate quoted parameters, including escaped quotes, are unaffected.

.changeset/capabilities-live-chain-key.md

@@ -0,0 +1,12 @@
+---
+"@efs/sdk": patch
+---
+
+`efs.account.capabilities()` now keys the account probe by the LIVE provider chain
+instead of the construction-time `publicClient.chain.id`. The `getCode` classification
+and EIP-5792 `getCapabilities` already land on the provider's current chain, so a mutable
+EIP-1193 provider that switched networks after the client was built could mix new-chain
+bytecode/capabilities into an old-chain cache slot and return the wrong `kind`/gasless
+status. Querying `publicClient.getChainId()` for the cache key keeps detection consistent
+with the chain the reads actually hit — the last live-chain gap, matching the read and
+write paths.

.changeset/capabilities-refresh-nested-brand.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+Two review fixes: (1) `efs.account.capabilities()` accepts `{ refresh: true }` — the client-level invalidation lever for the capability-profile cache. The probed inputs are mutable on-chain state (a counterfactual smart-account deploy or an EIP-7702 delegation added/removed changes the account's code without changing the cache key), and provider-form callers cannot reach the internally-created wallet object that scopes the cache; the option evicts the live-chain cache entry and re-probes. (2) `parseWriteReceipt` now REBUILDS the nested `data` ref (validated fields + `__brand: 'DataRef'` + profile) instead of spreading the payload through — an external artifact could omit or forge the brand and violate the branded `WriteReceipt.data: DataRef` contract; the construction is shared with `parseDataRef` via one helper.

.changeset/chunk-send-unknown.md

@@ -0,0 +1,5 @@
+---
+"@efs/sdk": patch
+---
+
+The SSTORE2 chunk deploy gets the same send-outcome honesty as the manager leg and the layered submitter: a code-less transport failure during the chunk send (connection drop after the request may have reached the node) now throws the new `OnchainSendUnknown` — broadcast state unknown, the deploy may still mine and bill gas, no hash to reconcile by — instead of an ordinary classified error that invited a `fs.write` retry paying for duplicate storage. A refusal response (wallet/node error code, decoded revert) still propagates as the classified error, where a retry is clean.

.changeset/classify-onchain-storage-errors.md

@@ -0,0 +1,12 @@
+---
+"@efs/sdk": patch
+---
+
+The default `fs.write(path, bytes)` on-chain (SSTORE2) storage path now routes its
+wallet/RPC calls through the same `classifyError` funnel the submitter uses. A wallet
+rejection or RPC failure during the chunk deploy, manager deploy, or receipt wait now
+surfaces as the documented EFS error tree (`UserRejected` / `RpcError` / typed write
+errors) instead of a raw viem/provider error — so callers handling the EFS error tree no
+longer miss the common quickstart write path. Abort (`signal`) still propagates as the
+caller's `AbortError` (the pre-send checks stay outside the funnel), and typed errors like
+`MultiChunkUnsupported` pass through unchanged (the classifier is idempotent).

.changeset/concrete-anchor-validation.md

@@ -0,0 +1,6 @@
+---
+"@efs/sdk": patch
+"@efs/solidity": patch
+---
+
+Reused concrete file-ANCHORs are now validated before broadcast: (1) the builder stamps plans with `anchorSchemaUID` + `existingAnchorUID` when an overwrite/relink reuses a concrete anchor, and `submitLayeredTier1` verifies the reused definition IS an ANCHOR attestation (fail-closed on a missing stamp or a read-incapable context) — an arbitrary `existingFileAnchorUID` executed through the exported layered submitter previously skipped the anchor mint and could confirm a placement `fs.*` can never discover. (2) Solidity's six-argument `placeExisting` applies the same `NotAnchorUID` check to a nonzero reused anchor before attesting the PIN. For `fs.write` (which resolves the UID via `resolveAnchor` — an ANCHOR by construction) this is one extra defense-in-depth read per overwrite.

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/content-hash-multibase-multihash.md

@@ -0,0 +1,6 @@
+---
+"@efs/sdk": patch
+"@efs/solidity": patch
+---
+
+`contentHash` now conforms to the ratified v1 encoding (contracts specs/10, SDK ADR-0016 superseding ADR-0006). `hashContent` emits the canonical multibase-base16 multihash string — `f1220` + 64 lowercase sha2-256 hex chars (69 chars) — instead of a bare digest, and the `ContentHash` brand now means that canonical string. The read path gains an algorithm-aware accepted-form decoder (`decodeContentHash`, new export with `CONTENT_HASH_CODES`): `f`/base16 and `b`/base32 (RFC 4648 lowercase, no padding) forms of the two registered functions (`0x12` sha2-256 canonical, `0x1b` keccak-256 alternate) decode, and `verifyContent` compares at DIGEST level, so a base32 or keccak-alternate claim of matching content verifies `matches-author`. Bare digests (the old ADR-0006 form), `0x`-prefixed values, uppercase, and unregistered codes report `malformed-claim` — deliberately, with no bare-digest tolerance: no SDK-written durable data exists, and the only legacy Sepolia population (debug-UI `0x`-keccak values) already read `malformed-claim` before. The mirror engine's `statusFor` now delegates to `verifyContent` (one decode/verify implementation). `FileWriteGraphInput.contentHash` is typed as `ContentHash` so a non-canonical string cannot re-enter the non-revocable PROPERTY persistence path. specs/10 §7 conformance vectors imported as tests. `@efs/solidity`: `EFSLib.ReservedKey` doc updated to the canonical form (comment-only).

.changeset/decode-every-multibase-and-solidity-mirror-window.md

@@ -0,0 +1,6 @@
+---
+"@efs/sdk": patch
+"@efs/solidity": patch
+---
+
+Close the two gaps left by the previous mirror fixes. The IPFS CID check no longer has an alphabet-only path: every accepted multibase (base2/8/10/16/32 families, base36, base58btc, base58flickr) is really decoded and the bytes face the same version/codec/multihash parse, so `ipfs://k0000000000` — well-formed base36, not a CID — is refused. And the Solidity SDK's `_requireActiveMirror` now scans the newest 500 raw slots like the TypeScript reader and `EFSRouter`, instead of the oldest 500: an active mirror stranded below the readable window no longer lets a placement through, and one past the 500th slot no longer blocks a readable DATA.