Scaffold the EFS SDK monorepo

[JamesCarnley]

Initial scaffold of the EFS SDK monorepo, set up from best-practice research + multiple expert-subagent review passes.

What's here

• pnpm + Turborepo + Changesets workspace, two independently-versioned packages:
  • @efs/sdk — TypeScript SDK (tsup dual ESM/CJS, viem-native, vitest)
  • @efs/solidity — compile-in Solidity library (Foundry, ships .sol source)
• ADR system mirrored from the contracts repo but lighter (MADR-style, no freeze ceremony): ADR-0001 layout, 0002 viem-only, 0003 compile-in Solidity.
• Top-level docs (README, CONTRIBUTING, AGENTS.md), CI, scaffolded public API shapes reflecting the planning design (identity seam, static-vs-dynamic refs).

Verified

• TS: build (dual ESM/CJS + types), typecheck, test (2 passing), lint — all green.
• Solidity: wired for forge build/test/fmt, CI-verified.

Notes for review

• npm scope is @efs (org needs claiming on npm before first publish; one-line revert to @efs-project if taken).
• Method bodies are stubs (NotImplemented) — this is structure + decisions, not implementation.
• Cross-cutting design stays in the planning vault (sdk-architecture.md); ADRs here implement slices of it.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8e5a19b20

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7994df5334

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eadb898eab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d1e88d32fa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 39653f6167

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5e92a8d0f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 145e590697

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4017c175b9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e9adb0f964

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[JamesCarnley]

Re-reviewed latest head e9adb0f.

The newest write-guard commits look good: standalone planning reads are guarded before they feed plans, file-write planning reads are guarded before parent/tag/transport reads, and receipt waits are guarded after broadcast while preserving the outcome-unknown recovery shape. Local verification passed on this head: git diff --check origin/main...HEAD, pnpm --filter @efs/sdk typecheck, pnpm --filter @efs/sdk test (563 passed, 3 skipped), pnpm --filter @efs/sdk build, pnpm lint, and pnpm --filter @efs/solidity test (53 passed). GitHub CI is green and merge state is clean.

One non-blocking coverage note: lists.remove(entryUID, { listUID }) now guards the advisory config read, but I only see tests for the existing append-only/list-not-found/revocable behavior, not the new WrongChain/no-read/no-revoke case. I would not block on that because the path is advisory and the revoke itself is already chain-guarded.

The merge-blocking release/docs issue is still present: .changeset/escape-hatches-raw-eas-decode.md and packages/sdk/src/raw/contracts.ts still say efs.raw.* instances re-resolve deployment lazily so chain changes are reflected. Current code and the later raw-surface changeset describe the actual contract: raw instances are bound to construction-chain deployment addresses and fail closed with WrongChain on live chain drift. Please update those stale docs before merge so the release notes/source docs do not promise raw chain-switch re-resolution.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 040b374b73

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[JamesCarnley]

Re-reviewed latest head dd5de95.

Local verification passed on this head: git diff --check origin/main...HEAD, pnpm --filter @efs/sdk typecheck, pnpm --filter @efs/sdk test (573 passed, 3 skipped), pnpm --filter @efs/sdk build, pnpm lint, and pnpm --filter @efs/solidity test (53 passed). GitHub CI is green and merge state is clean.

The newest write-planning guards look good: setOverview and mirrors.add now guard before the planning reads that feed their plans, and the tests cover the important no-read/no-submit ordering. I did not find a code blocker there.

I do still see merge-blocking docs/API-truth issues:

1. The prior raw docs/release-note blocker remains. .changeset/escape-hatches-raw-eas-decode.md and packages/sdk/src/raw/contracts.ts still say raw contract instances re-resolve deployment lazily so chain changes are reflected. Current code and the later raw-surface changeset describe the real contract: raw instances are bound to construction-chain deployment addresses and fail closed with WrongChain on live-chain drift.

2. docs/adr/0015-read-trust-provenance.md reads like the trust field lands now: it says EfsFile, FileInfo, and ReadResult carry required trust, and that reads stamp { freshness:'current', source:'live' }. But the current types do not include trust; the changeset and TrustDescriptor comment correctly describe it as reserved for a later behavioral slice. Please soften the ADR language so it does not claim current result shapes already include trust.

3. docs/adr/0014-pluggable-read-source-and-chain-as-data.md says chainless clients work / the chainless-client rejection is superseded, but createEfsClient still rejects chainless ViemConfig.publicClient at construction. viemReadSource(client, { chainId }) supports chain-as-data, but it is not wired into createEfsClient yet. Please make the ADR match this phase.

4. snapshotReadSource advertises supportsGetCode / supportsEns from snap.code / snap.ens, but getCode currently returns undefined and getEnsAddress is absent even when ENS data is present. Either implement those optional lookups or advertise the capabilities as false until the stub can actually serve them.

Once those docs/capability-truth issues are corrected, the verified code paths look very close.

[JamesCarnley]

Re-reviewed latest head 0fc48eb.

The new read-path TOCTOU guard looks good: readContext now resolves the live deployment, then gives the read engines a public client guarded against that resolved deployment.chainId; the guard also covers getCode for web3:// reads while leaving ENS unguarded as documented. Local verification passed on this head: git diff --check origin/main...HEAD, pnpm --filter @efs/sdk typecheck, pnpm --filter @efs/sdk test (574 passed, 3 skipped), pnpm --filter @efs/sdk build, pnpm lint, and pnpm --filter @efs/solidity test (53 passed). GitHub CI is green and merge state is clean.

The merge-blocking docs/capability issues from the previous review still appear unresolved:

1. .changeset/escape-hatches-raw-eas-decode.md and packages/sdk/src/raw/contracts.ts still claim raw contract instances re-resolve deployment lazily so chain changes are reflected, while the actual contract is fail-closed WrongChain on live-chain drift.
2. docs/adr/0015-read-trust-provenance.md still reads as though EfsFile, FileInfo, and ReadResult already carry required trust, but this PR only reserves TrustDescriptor; current result types do not include trust yet.
3. docs/adr/0014-pluggable-read-source-and-chain-as-data.md still says chainless clients work / the chainless-client rejection is superseded, but createEfsClient still rejects chainless ViemConfig.publicClient; only viemReadSource(client, { chainId }) supports chain-as-data today.
4. snapshotReadSource still advertises supportsGetCode / supportsEns based on supplied snapshot data, but the stub does not actually serve those lookups (getCode returns undefined; getEnsAddress is absent).

Code-path hardening continues to look solid; the remaining blockers are docs/release/capability truth issues that would mislead callers if this merged as-is.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0fc48eb632

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5d44417a23

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[JamesCarnley]

Reviewed current head 5d44417a23 in a clean detached worktree. CI is green and local verification passed (git diff --check origin/main...HEAD, pnpm --filter @efs/sdk typecheck, pnpm --filter @efs/sdk test, pnpm --filter @efs/sdk build, pnpm lint, pnpm --filter @efs/solidity test). Still not merge-ready; these blockers remain:

1. props.list still escapes the new pinned-chain read guard. It resolves dep and creates guarded pc, but the anchor-name decode pass still reads with unguarded deps.publicClient (packages/sdk/src/writes/props.ts:191) and the value pass calls deps.readContext() (packages/sdk/src/writes/props.ts:203), which can re-resolve a different live chain mid-method. A provider switch after the first guarded page read can still mix chains or avoid the intended WrongChain fail-closed behavior. Please keep the later reads pinned to the same dep/guarded client and add a direct props.list regression; the new test name mentions props but currently exercises only mirrors.list.

2. ADR-0015 still promises required read-trust fields that the public API does not carry. The ADR says EfsFile, FileInfo, and ReadResult carry required trust: TrustDescriptor plus requireTrust/StaleTrust sugar gating, but the current exported types omit trust (packages/sdk/src/types.ts:543, :749, :773) and returned files are built without it. Either land the behavioral slice now or revise the ADR/changeset language so PR #1 honestly reserves the shape instead of claiming it is present.

3. ADR-0014 still says chainless createEfsClient works in PR #1, but createEfsClient continues to throw InvalidArgument when publicClient.chain?.id is absent (packages/sdk/src/index.ts:633), and the tests assert that rejection. Please make the docs match the shipped behavior, or actually route read-only chainless clients through the viemReadSource(client, { chainId }) path.

4. The raw-contract docs and release note still overclaim live chain rebinding. packages/sdk/src/raw/contracts.ts and .changeset/escape-hatches-raw-eas-decode.md say lazy raw access reflects a chain change, while the implementation is construction-chain bound and guarded to fail closed with WrongChain on live-chain drift. The docs should say that exactly.

5. snapshotReadSource still advertises capabilities it does not implement. With snap.code, it sets supportsGetCode: true but getCode always returns undefined; with snap.ens, it sets supportsEns: true but installs no getEnsAddress. Because ReadSourceCapabilities are meant to be branch-before-call flags, these need to be honest (implement the map lookups or advertise false until the stub is real).

6. Minor docs drift: .changeset/foundational-read-source-scaffolding.md still describes the old TrustDescriptor shape as source/existence/revocation; the exported type is now the freshness discriminated union.

[JamesCarnley]

Re-reviewed current head 4363d015b6b71d4dc1b0b106c156c51b38601ec1 in a clean detached worktree.

The newest code fixes look good:

• The previous props.list TOCTOU blocker is addressed. props.list now resolves one deployment, derives one guarded read client, and uses that same pinned client for anchor enumeration, anchor-name getAttestation, and per-key value reads. Focused subagent review found no issue in this slice.
• The new lists.has ADDR-width validation also looks correct. The false-positive was real for 32-byte values that already matched the right-aligned address membership key; valid 20-byte addresses remain accepted. Focused subagent review found no issue in this slice.

Fresh verification passed on this head:

• git diff --check origin/main...HEAD
• pnpm --filter @efs/sdk typecheck
• pnpm --filter @efs/sdk test (583 passed, 3 skipped)
• pnpm --filter @efs/sdk build
• pnpm lint
• pnpm --filter @efs/solidity test (53 passed)

GitHub CI is green, merge state is clean, and there are no unresolved review threads. This head is still not merge-ready because the remaining docs/capability-truth blockers from the previous review are still current:

1. ADR-0015 still reads as though EfsFile, FileInfo, and ReadResult already carry required trust: TrustDescriptor plus requireTrust/StaleTrust gating, but the current exported result types do not include trust yet. Please make the ADR/changeset language explicit that this PR reserves the shape rather than shipping the behavioral result fields.

2. ADR-0014 still says chainless createEfsClient works / the chainless-client rejection is superseded in PR #1, while createEfsClient still rejects a chainless ViemConfig.publicClient. viemReadSource(client, { chainId }) supports chain-as-data, but that is not wired through createEfsClient yet. Please make the ADR match this phase.

3. The raw-contract docs/release note still overclaim live chain rebinding. .changeset/escape-hatches-raw-eas-decode.md, packages/sdk/src/raw/contracts.ts, and the matching packages/sdk/src/index.ts comments still say raw instances re-resolve deployment lazily so chain changes are reflected. The actual contract is construction-chain-bound raw instances guarded with WrongChain on live-chain drift. Please update the stale wording.

4. snapshotReadSource still advertises capabilities it does not implement. With snap.code, it sets supportsGetCode: true but getCode returns undefined; with snap.ens, it sets supportsEns: true but no getEnsAddress is installed. Since these are branch-before-call capability flags, either implement those lookups or advertise false until the stub can serve them.

5. Minor release-note drift: .changeset/foundational-read-source-scaffolding.md still describes the old TrustDescriptor shape as source/existence/revocation; the exported type is now the freshness discriminated union.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4363d015b6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16bf2c92fa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[JamesCarnley]

Re-reviewed current head e1d1de67be7541ae0827c6df9b37c9b25c787993 in a clean detached worktree.

The two newest code commits look good:

• 16bf2c92 fixes empty-file reads (size attested 0) without weakening the positive fetch cap behavior, and attestationsFor now hydrates DTOs that carry only top-level dataUID / anchorUID / ref.uid. Focused review found no issue.
• e1d1de6 fixes efs.raw.verifyDeployment() TOCTOU by resolving the deployment once and probing through a client guarded to that resolved chain. Deployment overrides still flow through the same resolver, and the new drift regression covers the intended WrongChain fail-closed path. Focused review found no issue.

Fresh verification passed on this head:

• git diff --check origin/main...HEAD
• pnpm --filter @efs/sdk typecheck
• pnpm --filter @efs/sdk test (586 passed, 3 skipped)
• pnpm --filter @efs/sdk build
• pnpm lint
• pnpm --filter @efs/solidity test (53 passed)

GitHub CI is green, merge state is clean, and there are no unresolved review threads. Still not merge-ready because the docs/capability-truth blockers remain in the current tree:

1. ADR-0015 still reads as though EfsFile, FileInfo, and ReadResult already carry required trust: TrustDescriptor plus requireTrust/StaleTrust gating, but current exported result types do not include trust yet. Please make the ADR/changeset language explicit that this PR reserves the shape rather than shipping those behavioral fields.

2. ADR-0014 still says chainless createEfsClient works / the chainless-client rejection is superseded in PR #1, while createEfsClient still rejects a chainless ViemConfig.publicClient. viemReadSource(client, { chainId }) supports chain-as-data, but that is not wired through createEfsClient yet. Please make the ADR match this phase.

3. The raw-contract docs/release note still overclaim live chain rebinding. .changeset/escape-hatches-raw-eas-decode.md, packages/sdk/src/raw/contracts.ts, and matching comments in packages/sdk/src/index.ts still say raw instances re-resolve deployment lazily so chain changes are reflected. The actual contract is construction-chain-bound raw instances guarded with WrongChain on live-chain drift. Please update the stale wording.

4. snapshotReadSource still advertises capabilities it does not implement. With snap.code, it sets supportsGetCode: true but getCode returns undefined; with snap.ens, it sets supportsEns: true but no getEnsAddress is installed. Since these are branch-before-call capability flags, either implement those lookups or advertise false until the stub can serve them.

5. Minor release-note drift: .changeset/foundational-read-source-scaffolding.md still describes the old TrustDescriptor shape as source/existence/revocation; the exported type is now the freshness discriminated union.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e1d1de67be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 95c8c956db

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[JamesCarnley]

Re-reviewed current head 87e4ca84f166b201dab0c573ba65925cb53e8058.

The newest fixes look good: the mid-write abort path now preserves partial-write recovery context, and the wallet-scoped capability cache avoids cross-connector reuse. I also had two focused subagent passes check those slices independently, and both came back clean.

Local verification passed on the current head:

• git diff --check origin/main...HEAD
• pnpm --filter @efs/sdk typecheck
• pnpm --filter @efs/sdk test (591 passed, 3 skipped)
• pnpm --filter @efs/sdk build
• pnpm lint
• pnpm --filter @efs/solidity test (53 passed)

GitHub status is also green right now, with clean merge state and no unresolved review threads. I still do not think this PR is merge-ready yet, because these blockers remain:

1. expand: ["attestations.schema"] / withSchema can still swallow systemic chain drift. attestationFor() calls schemaRecordFor(), and schemaRecordFor() catches every getSchema() failure and returns undefined. That means a WrongChain raised while hydrating schema data fulfills as an attestation missing schemaRecord, so the new rejection scan in attestationsForUIDs() never sees it. Please let systemic WrongChain escape from schemaRecordFor() while preserving ordinary per-schema degradation if that is intentional. Relevant area: packages/sdk/src/reads/attestations.ts:81-107.

2. ADR-0015 still says EfsFile, FileInfo, and ReadResult carry required trust descriptors and documents requireTrust / StaleTrust, but the current public SDK types do not expose that contract yet. The docs are ahead of the implementation.

3. ADR-0014 still says chainless SDK construction lands in PR #1 and that rejecting chainless ViemConfig.publicClient was superseded, but createEfsClient() still rejects chainless public clients. Either the behavior or the ADR needs to change before merge.

4. The raw contract escape-hatch docs/release note still claim raw instances re-resolve deployment info and reflect wallet chain changes, while the implementation is construction-chain-bound and reports WrongChain on drift. That mismatch will mislead downstream callers.

5. snapshotReadSource() still advertises supportsGetCode / supportsEns from snapshot contents even though getCode() returns undefined and no ENS resolver is installed. Capability metadata should describe callable behavior, not stored snapshot presence.

6. .changeset/foundational-read-source-scaffolding.md still describes the old TrustDescriptor shape as source / existence / revocation, but the exported SDK type uses the current freshness union shape.

Once those are corrected, the current write-path fixes themselves look ready from my pass.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 87e4ca84f1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[JamesCarnley]

Re-reviewed current head 5e6d64dfaad90e65e29c783d139f7884840ec333.

The newest commit looks good. The redirect hop-cap fix now accepts a chain that terminates exactly at the cap while still failing closed on a genuine extra followable hop/cycle, and the read-only client type now exposes only the wallet-free read namespaces. I checked those locally and had two focused subagent passes review the same delta; both came back clean.

Local verification on this head passed:

• git diff --check origin/main...HEAD
• pnpm --filter @efs/sdk typecheck
• pnpm --filter @efs/sdk test -- redirects.test.ts index.test.ts (45 passed)
• pnpm --filter @efs/sdk test (593 passed, 3 skipped)
• pnpm --filter @efs/sdk build
• pnpm lint
• pnpm --filter @efs/solidity test (53 passed)

GitHub CI is green, merge state is clean, and there are no unresolved review threads. I still do not think this PR is merge-ready, because the previous merge blockers remain on this head:

1. expand: ["attestations.schema"] / withSchema can still swallow systemic chain drift. schemaRecordFor() catches every getSchema() failure and returns undefined, so a WrongChain during schema hydration fulfills as an attestation missing schemaRecord instead of escaping as a systemic failure. Relevant area: packages/sdk/src/reads/attestations.ts:81-107.

2. ADR-0015 still says EfsFile, FileInfo, and ReadResult carry required trust descriptors plus requireTrust / StaleTrust, but the current exported SDK surface does not implement that contract.

3. ADR-0014 still says chainless SDK construction lands in PR #1 and that the chainless ViemConfig.publicClient rejection was superseded, while createEfsClient() still rejects chainless public clients.

4. The raw contract escape-hatch docs/release note still claim raw instances re-resolve deployment info and reflect wallet/provider chain changes, while the implementation is construction-chain-bound and reports WrongChain on drift.

5. snapshotReadSource() still advertises supportsGetCode / supportsEns from snapshot contents even though getCode() returns undefined and no ENS resolver is installed.

6. .changeset/foundational-read-source-scaffolding.md still describes the old TrustDescriptor shape (source / existence / revocation) instead of the exported freshness union shape.

So: the latest addressed areas are verified, but these blockers still need one more pass before merge.