feat(synapse): run local client using synapse as library

.github/workflows/ci_run.yml

@@ -126,7 +126,7 @@ jobs:
     - name: "EXEC: {Setup Node.js}, independent"
       uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
       with:
-        node-version: 'lts/*'
+        node-version: '24.x'
         check-latest: true
 
     - name: "CHECK: {Resolve dependency profile}"

README.md

@@ -98,10 +98,18 @@ This will:
 
 ### Step 4: Use the Network
 
-After startup, `USER_1` is fully configured for FOC: USDFC deposited into FilecoinPay and FWSS approved as an operator. You can use it immediately with synapse-sdk:
+After startup, `USER_1` is fully configured for FOC: USDFC deposited into FilecoinPay and FWSS approved as an operator. Use the network immediately with Synapse, filecoin-pin, or other compatible FOC client software:
 
 ```bash
+# From a synapse-sdk checkout
 NETWORK=devnet node utils/example-storage-e2e.js <file>
+
+# With filecoin-pin
+filecoin-pin add <file> --network devnet
+# Equivalent: NETWORK=devnet filecoin-pin add <file>
+
+# Exercise foc-devnet's full Synapse-driven system scenario
+python3 scenarios/test_synapse_e2e.py
 ```
 
 All connection details (contract addresses, user keys, SP endpoints) are exported to `devnet-info.json`:

ci/README.md

@@ -162,6 +162,10 @@ The `version` field can also be an npm dist-tag:
 The resolver records the concrete package version selected at resolution time
 and npm `gitHead` when available.
 
+For `synapse-sdk`, npm resolution also records exact compatible versions of
+`@filoz/synapse-core` and the `viem` peer dependency. The scenario installs that
+set into a temporary consumer project.
+
 ## Overrides
 
 Some profile selections can include an optional `overrides` object. Each entry
@@ -170,8 +174,8 @@ exists:
 
 ```json
 {
-  "strategy": "git_tag",
-  "tag": "synapse-sdk-v1.0.1",
+  "strategy": "npm_version",
+  "version": "1.1.1",
   "overrides": {
     "nanoid": {
       "version": "3.3.13",
@@ -186,18 +190,12 @@ non-empty strings; the resolver rejects any override missing either field, so an
 override cannot be added without documenting why. The reason is logged when the
 override is applied. The resolver does not infer overrides from package metadata.
 
-Overrides are currently allowed only for:
-
-- `synapse-sdk`, because scenario setup controls its pnpm install.
-- `filecoin-pin` selections using `npm_version`, because those install into a
-  temporary npm project controlled by the scenario.
-
-Current consumers:
+Overrides are currently allowed only for npm-installed `synapse-sdk` and
+`filecoin-pin` selections. They are written to the temporary consumer
+`package.json`; source profiles use the checkout's committed lockfile.
 
-- `synapse-sdk` writes overrides to the root `pnpm-workspace.yaml` before
-  running `pnpm install`.
-- npm-installed `filecoin-pin` writes overrides to the temporary npm
-  `package.json` used by the scenario.
+Current consumers write npm overrides to the temporary `package.json` used by
+their scenario.
 
 ## Current Boundary
 
@@ -208,7 +206,7 @@ Installation currently lives in three places (which consume the resolved
 metadata):
 
 - `foc-devnet init`: Lotus, Curio, filecoin-services, and optionally PDP.
-- `scenarios/synapse.py`: Synapse SDK scenario dependency.
+- `scenarios/synapse_runtime.py`: published or source Synapse scenario runtime.
 - `scenarios/test_multi_copy_upload.py`: filecoin-pin scenario dependency.
 
 This split is intentional, but it is not necessarily the final shape. Resolution

ci/dependency-profiles.json

@@ -98,12 +98,12 @@
       "repository": "https://github.com/FilOzone/synapse-sdk.git",
       "npm_package": "@filoz/synapse-sdk",
       "default": {
-        "strategy": "git_tag",
-        "tag": "synapse-sdk-v1.1.1"
+        "strategy": "npm_version",
+        "version": "1.1.1"
       },
       "stability": {
-        "strategy": "git_tag",
-        "tag": "synapse-sdk-v*"
+        "strategy": "npm_version",
+        "version": "latest"
       },
       "frontier": {
         "strategy": "git_branch",

renovate.json

@@ -21,20 +21,19 @@
         "/^ci/dependency-profiles\\.json$/"
       ],
       "matchStrings": [
-        "\"tag\":\\s*\"synapse-sdk-v(?<currentValue>[0-9][^\"]*)\""
+        "\"synapse-sdk\":\\s*\\{[\\s\\S]{0,500}?\"default\":\\s*\\{\\s*\"strategy\":\\s*\"npm_version\",\\s*\"version\":\\s*\"(?<currentValue>[0-9][^\"]*)\""
       ],
-      "depNameTemplate": "FilOzone/synapse-sdk",
-      "datasourceTemplate": "github-tags",
-      "extractVersionTemplate": "^synapse-sdk-v(?<version>.+)$",
-      "versioningTemplate": "semver"
+      "depNameTemplate": "@filoz/synapse-sdk",
+      "datasourceTemplate": "npm",
+      "versioningTemplate": "npm"
     },
     {
       "customType": "regex",
       "managerFilePatterns": [
         "/^ci/dependency-profiles\\.json$/"
       ],
       "matchStrings": [
-        "\"strategy\":\\s*\"npm_version\",\\s*\"version\":\\s*\"(?<currentValue>[0-9][^\"]*)\""
+        "\"filecoin-pin\":\\s*\\{[\\s\\S]{0,500}?\"default\":\\s*\\{\\s*\"strategy\":\\s*\"npm_version\",\\s*\"version\":\\s*\"(?<currentValue>[0-9][^\"]*)\""
       ],
       "depNameTemplate": "filecoin-pin",
       "datasourceTemplate": "npm",

scenarios/helpers.py

@@ -12,12 +12,19 @@
 _fail = 0
 _log_lines: list = []
 
+BASE_DIR = Path(os.environ.get("FOC_DEVNET_BASEDIR", Path.home() / ".foc-devnet"))
 DEVNET_INFO = os.environ.get(
-    "DEVNET_INFO", os.path.expanduser("~/.foc-devnet/state/latest/devnet-info.json")
+    "DEVNET_INFO", str(BASE_DIR / "state" / "latest" / "devnet-info.json")
+)
+FOUNDRY_BIN = BASE_DIR / "artifacts" / "foundry" / "bin"
+CAST_ARTIFACT = FOUNDRY_BIN / "cast"
+FORGE_ARTIFACT = FOUNDRY_BIN / "forge"
+CAST = os.environ.get("CAST") or str(
+    CAST_ARTIFACT if os.access(CAST_ARTIFACT, os.X_OK) else "cast"
+)
+FORGE = os.environ.get("FORGE") or str(
+    FORGE_ARTIFACT if os.access(FORGE_ARTIFACT, os.X_OK) else "forge"
 )
-FOUNDRY_BIN = Path.home() / ".foc-devnet" / "artifacts" / "foundry" / "bin"
-CAST = str(FOUNDRY_BIN / "cast")
-FORGE = str(FOUNDRY_BIN / "forge")
 
 # ── Logging ──────────────────────────────────────────────────
 

scenarios/run.py

@@ -30,7 +30,7 @@
     ("test_basic_balances", 10),
     # Allows setup plus five 280s Node attempts and retry delays.
     ("test_create_dataset_smoke", CREATE_DATASET_SMOKE_TIMEOUT_SECS),
-    ("test_storage_e2e", 200),
+    ("test_synapse_e2e", 600),
     ("test_multi_copy_upload", 600),
     ("test_caching_subsystem", 200),
 ]