iCKB Stack rewrite: one SDK, single-turn actors, one interface

.dependency-cruiser.jsonc

@@ -0,0 +1,131 @@
+{
+  "extends": "dependency-cruiser/configs/recommended-strict",
+  "forbidden": [
+    {
+      "name": "no-orphans",
+      "from": {
+        "orphan": true,
+        "pathNot": [
+          "(^|/)\\.[^/]+\\.(js|cjs|mjs|ts|json)$",
+          "\\.d\\.(c|m)?ts$",
+          "(^|/)tsconfig\\.json$",
+          "(^|/)(?:babel|webpack)\\.config\\.(?:js|cjs|mjs|ts|json)$",
+          "^scripts/run-node-tests[.](?:mts|ts)$",
+          "^scripts/tooling/build/rewrite-dts-imports[.](?:mts|ts)$",
+          "^scripts/tooling/dead-members[.]ts$",
+          "^scripts/tooling/eslint/plugins[.]ts$",
+          "^scripts/test/.+[.](?:mts|ts)$",
+          "^sdk/node/test/.+[.]ts$",
+          "^(?:sdk|sdk/node|testkit|interface)/vitest[.]config[.]mts$",
+          "^interface/vite[.]config[.]ts$",
+          "^interface/eslint[.]config[.]mts$",
+        ],
+      },
+    },
+    {
+      "name": "not-prod-to-test-source",
+      "comment": "Production source must not import test-only files. Keep test fixtures behind test/ boundaries.",
+      "severity": "error",
+      "from": {
+        "path": "^(?:(?:sdk|sdk/node|testkit|interface)/src/|scripts/)",
+        "pathNot": [
+          "(?:^|/)test/",
+          "[.]test[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:Suite[0-9]*[.]test|Suite|Test(?:Assertions|CommandFixtures|Constants|Fixtures|ProcessFixtures|RunFixtures|Support)|TestFixtures|TestSupport)[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:Suite[0-9]*[.]test|Suite|Test(?:Assertions|CommandFixtures|Constants|Fixtures|ProcessFixtures|RunFixtures|Support)|TestFixtures|TestSupport)[.][^/]+[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:_test_|_test_constants[.]|_test_fixtures[.]|_test_support[.])[^/]*$",
+        ],
+      },
+      "to": {
+        "path": [
+          "(?:^|/)test/",
+          "[.]test[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:Suite[0-9]*[.]test|Suite|Test(?:Assertions|CommandFixtures|Constants|Fixtures|ProcessFixtures|RunFixtures|Support)|TestFixtures|TestSupport)[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:Suite[0-9]*[.]test|Suite|Test(?:Assertions|CommandFixtures|Constants|Fixtures|ProcessFixtures|RunFixtures|Support)|TestFixtures|TestSupport)[.][^/]+[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:_test_|_test_constants[.]|_test_fixtures[.]|_test_support[.])[^/]*$",
+        ],
+      },
+    },
+    {
+      "name": "not-prod-to-testkit",
+      "comment": "Production source must not import @ickb/testkit. Keep test harness dependencies under test/.",
+      "severity": "error",
+      "from": {
+        "path": "^(?:sdk|sdk/node|testkit|interface)/src/",
+        "pathNot": [
+          "^testkit/src/",
+          "(?:^|/)test/",
+          "[.]test[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:Suite[0-9]*[.]test|Suite|Test(?:Assertions|CommandFixtures|Constants|Fixtures|ProcessFixtures|RunFixtures|Support)|TestFixtures|TestSupport)[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:Suite[0-9]*[.]test|Suite|Test(?:Assertions|CommandFixtures|Constants|Fixtures|ProcessFixtures|RunFixtures|Support)|TestFixtures|TestSupport)[.][^/]+[.](?:mts|ts|tsx)$",
+          "(?:^|/)[^/]*(?:_test_|_test_constants[.]|_test_fixtures[.]|_test_support[.])[^/]*$",
+        ],
+      },
+      "to": {
+        "path": "^testkit/src/",
+      },
+    },
+    {
+      "name": "oracle-independent",
+      "comment": "The contract oracle imports nothing from the implementation it judges (amendment 44).",
+      "severity": "error",
+      "from": { "path": "^testkit/src/contract_oracle[.]ts$" },
+      "to": {},
+    },
+    {
+      "name": "node-actors-apart",
+      "comment": "The bot, the sampler, and the stimulus generator share only src/shared; they never import each other.",
+      "severity": "error",
+      "from": { "path": "^sdk/node/src/(bot|sampler|stimulus)/" },
+      "to": {
+        "path": "^sdk/node/src/(?:bot|sampler|stimulus)/",
+        "pathNot": "^sdk/node/src/$1/",
+      },
+    },
+    {
+      "name": "node-shared-neutral",
+      "comment": "src/shared serves every actor and depends on none of them.",
+      "severity": "error",
+      "from": { "path": "^sdk/node/src/shared/" },
+      "to": { "path": "^sdk/node/src/(?:bot|sampler|stimulus)" },
+    },
+    {
+      "name": "sdk-browser-safe",
+      "comment": "The SDK runs in the browser: no Node built-ins (decisions §1).",
+      "severity": "error",
+      "from": { "path": "^sdk/src/" },
+      "to": { "dependencyTypes": ["core"] },
+    },
+    {
+      "name": "sdk-not-node",
+      "comment": "The published SDK never imports the Node actors that live beside it (amendment 52).",
+      "severity": "error",
+      "from": { "path": "^sdk/src/" },
+      "to": { "path": "^sdk/node/" },
+    },
+    {
+      "name": "no-library-to-actor",
+      "comment": "The SDK and the test kit must not depend on the actors.",
+      "severity": "error",
+      "from": { "path": "^(?:sdk/src|testkit)/" },
+      "to": { "path": "^(?:interface|sdk/node)/" },
+    },
+    {
+      "name": "no-actor-to-actor",
+      "comment": "The interface and the Node actors must not depend on each other.",
+      "severity": "error",
+      "from": { "path": "^(interface|sdk/node)/" },
+      "to": { "path": "^(?:interface|sdk/node)/", "pathNot": "^$1/" },
+    },
+  ],
+  "options": {
+    "exclude": {
+      "path": "(?:^|/)(?:coverage|dist)/",
+    },
+    "includeOnly": "^(sdk|testkit|interface|scripts)/",
+    "tsConfig": {
+      "fileName": "tsconfig.json",
+    },
+    "tsPreCompilationDeps": "specify",
+  },
+}

.github/workflows/check.yaml

@@ -5,19 +5,91 @@ on:
   push:
     branches: [master]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
+    outputs:
+      interface: ${{ steps.releases.outputs.interface }}
+      sdk: ${{ steps.releases.outputs.sdk }}
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
         with:
-          node-version: 24
-      - uses: pnpm/action-setup@v4
-
-      - name: Install jq for fork bootstrap
-        run: sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends jq
+          persist-credentials: false
+          # The release rule below reads the previous commit.
+          fetch-depth: 2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          # The declared Node floor; the example units run the current release.
+          node-version: 22.19.0
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
+      - name: Install pinned dependencies
+        run: pnpm install --frozen-lockfile
       - name: Run pnpm check
         run: pnpm check
+
+      # A release is a push to the default branch whose commit changes a package's version
+      # field (decisions amendment 52(ad)). Every such push is one squash commit, so the
+      # previous commit is the comparison; a path absent there counts as changed.
+      - id: releases
+        if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+        run: |
+          released() {
+            now=$(node -p "require('./$1/package.json').version")
+            before=$(git show "HEAD^:$1/package.json" 2>/dev/null | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).version" 2>/dev/null || echo none)
+            if [ "$now" != "$before" ]; then echo true; else echo false; fi
+          }
+          echo "interface=$(released interface)" >> "$GITHUB_OUTPUT"
+          echo "sdk=$(released sdk)" >> "$GITHUB_OUTPUT"
+      - if: steps.releases.outputs.interface == 'true'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9
+        with:
+          path: interface/dist
+
+  # The interface bundle the gate just built goes live at ickb.org (decisions amendment
+  # 52(ab)); a failed run leaves the previous deployment live.
+  deploy:
+    needs: build
+    if: needs.build.outputs.interface == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346
+
+  # npm trusted publishing: the id token stands in for a registry token, and npm records
+  # the provenance of this run with the package (decisions amendment 52(ad)).
+  publish:
+    needs: build
+    if: needs.build.outputs.sdk == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 22.19.0
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
+
+      - name: Install pinned dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build the SDK
+        run: pnpm build
+      # The checkout is a detached commit, so pnpm's branch and remote checks do not apply.
+      - name: Publish @ickb/sdk
+        run: pnpm --filter @ickb/sdk publish --provenance --access public --no-git-checks

.gitignore

@@ -2,15 +2,9 @@
 **/node_modules/
 
 # Artifacts
+**/coverage/
 **/dist/
-log/
-apps/*/log_*.json
-
-# Local runtime config files
-config/
-
-# Local logs
-logs/
+**/*.tsbuildinfo
 
 # Local scratch files
-.scratch/
+/private/

.prettierignore

@@ -0,0 +1,6 @@
+**/node_modules/
+**/dist/
+**/*.tsbuildinfo
+coverage/
+.git/
+pnpm-lock.yaml