decipherhub · 0xMuang · Aug 23, 2026 · Aug 23, 2026
diff --git a/FEATURES.md b/FEATURES.md
@@ -1725,6 +1725,36 @@ passing
 - completed plan: `docs/exec-plans/completed/SDK-002-standalone-integration-workflow.md`
 - production durable nonce와 service hardening은 #66/#67 module로 유지한다.
 
+## SDK-003 — Publishable Package Release Contract
+
+### Behavior
+
+- CLI, Toolkit과 RFQ SDK를 각각 npm tarball로 build/pack하고 저장소 밖 clean
+  project에서 설치한다.
+- Toolkit의 public CommonJS/types export와 기본 config simulation을 packed artifact
+  기준으로 검증한다.
+- package SemVer, schema/capability version 분리, release gate와 rollback 가능한
+  migration 절차를 문서화한다.
+- generated project의 RFQ conformance, CLI doctor/deploy dry-run과 packaged contract
+  build가 repository-relative package resolution 없이 통과해야 한다.
+
+### Verification
+
+- `npm test --prefix services/toolkit`
+- `npm test --prefix services/rfq`
+- `npm test --prefix services/cli`
+- `scripts/sdk-product-smoke.sh`
+- `git diff --check`
+
+### State
+
+passing
+
+### Notes
+
+- production npm registry publish와 release credential 사용은 이 저장소 검증 범위
+  밖이며, PR merge 후 별도 release 권한으로 수행한다.
+
 ## STUDIO-001 — Local Deployment Studio
 
 ### Behavior

diff --git a/PROGRESS.md b/PROGRESS.md
@@ -15,6 +15,19 @@ source of truth로 사용한다.
 
 ## Completed
 
+- `SDK-003 — Publishable Package Release Contract`: CLI, Toolkit과 RFQ SDK를
+  독립 npm tarball로 build/pack하고 Node 20 clean temporary projects에 설치하는
+  release gate를 완성했다. Toolkit packed export/config simulation, generated
+  RFQ module conformance, packaged CLI doctor/deploy dry-run과 contract bundle
+  Foundry build를 repository-relative package resolution 없이 검증한다. SemVer,
+  npm version과 persisted schema/capability version의 분리, release/rollback 및
+  immutable on-chain version migration 절차를 `docs/sdk-versioning.md`에 기록했다.
+  검증: Toolkit/RFQ/CLI package tests pass; Node 20
+  `scripts/sdk-product-smoke.sh` pass; Node 16 doctor fail-closed 확인;
+  `git diff --check` pass. `scripts/check.sh`는 실행했으나 G006과 무관한 기존
+  formatting drift(`script/DeployProductionCore.s.sol`,
+  `script/DemoScenarios.s.sol`)에서 중단됐다.
+
 - `CORE-005 — Compliance Core Production Hardening`: Compliance Core registry
   semantics were hardened for production onboarding. Element registration is now
   immutable per `elementId`, pins metadata/version hashes and records default

diff --git a/docs/README.md b/docs/README.md
@@ -18,6 +18,7 @@
 | [`rfq-demo-guide.md`](./rfq-demo-guide.md)           | RFQ-first MVP presenter guide | Current    |
 | [`showcase-runbook.md`](./showcase-runbook.md)       | production-core → local DEX handoff | Current |
 | [`sdk-integration.md`](./sdk-integration.md)         | modular SDK·scaffold·conformance | Current |
+| [`sdk-versioning.md`](./sdk-versioning.md)           | package semver·release·migration policy | Current |
 | [`deployment-studio.md`](./deployment-studio.md)     | local reference execution + production preflight/plan Studio | Current |
 | [`deployment-production.md`](./deployment-production.md) | production deployment runbook | Current |
 | [`testnet-deployment.md`](./testnet-deployment.md)       | public testnet RFQ reference deployment | Current |

diff --git a/docs/sdk-integration.md b/docs/sdk-integration.md
@@ -186,3 +186,8 @@ behavior.
 Passing conformance proves compatibility with the RFQ SDK contract. It does not
 certify a pricing model, risk policy, signer custody, persistence durability or
 legal compliance for production.
+
+Package compatibility, release sequencing and migration requirements are defined
+in [`sdk-versioning.md`](./sdk-versioning.md). The standalone product smoke packs
+and installs the CLI, Toolkit and RFQ packages into temporary clean projects; it
+must not resolve package code through repository-relative paths.
diff --git a/docs/sdk-versioning.md b/docs/sdk-versioning.md
@@ -0,0 +1,52 @@
+# SDK Package Versioning and Migration
+
+Corner Store publishes three independent npm package boundaries:
+
+| Package | Public contract |
+| --- | --- |
+| `@corner-store/cli` | project creation, doctor, deploy/verify and conformance commands |
+| `@corner-store/toolkit` | versioned configuration, onboarding plans and Safe exports |
+| `@corner-store/rfq-service` | RFQ types, modules, coordinator and conformance helpers |
+
+## Semantic Versioning
+
+All three packages use SemVer. A patch release may fix implementation defects
+without changing accepted inputs or observable output shapes. A minor release may
+add optional fields, exports or commands while preserving existing behavior. A
+major release is required for removed/renamed exports, newly required config,
+changed wire/calldata meaning, or stricter behavior that rejects previously valid
+inputs.
+
+Schema and capability versions are separate from npm versions. Changing a
+schema/capability requires an explicit parser or adapter and tests for both the old
+and new versions; an npm version bump alone must never reinterpret persisted data.
+CLI, Toolkit and RFQ releases are tested as a compatible set, but consumers may pin
+them independently when their declared schemas and capabilities match.
+
+## Release Gate
+
+Before publishing, run package tests and `scripts/sdk-product-smoke.sh`. The smoke
+test builds tarballs, installs all three packages in temporary clean projects,
+imports the Toolkit package, runs RFQ conformance through the generated project,
+executes CLI doctor/deploy dry-runs, and builds the packaged contract bundle. No
+step may resolve package code through a repository-relative path.
+
+## Migration Guide
+
+1. Pin current package versions and preserve the current config, integration and
+   deployment evidence files.
+2. Read the target release notes for npm, schema and capability version changes.
+3. Upgrade one package boundary at a time in a clean branch; do not edit persisted
+   schema numbers manually.
+4. Apply the documented config adapter or regenerate a project and transfer only
+   operator-owned values. Never copy secrets into generated files.
+5. Run package tests, `corner-store doctor`, RFQ module conformance and the SDK
+   product smoke before deployment planning.
+6. Compare generated calldata/Safe proposals and post-deployment expectations.
+   Governance review is required before submission.
+7. Roll back by restoring the pinned packages and preserved inputs. On-chain
+   registrations remain immutable and require a new version rather than rebinding.
+
+Version `0.x` packages remain pre-1.0: any incompatible public change still needs
+a documented migration and a minor-version bump at minimum. Production operators
+should pin exact versions and promote only artifacts that passed the release gate.
diff --git a/docs/testing.md b/docs/testing.md
@@ -86,7 +86,9 @@ gates, RFQ activation coherence, AMM-only coherent mode, read-only
 inventory stage, ACTIVE Manifest field verification, pause gate verification and
 pending-vs-active signer and safe-owner target owner mismatch/unavailable and operator role mismatch/unavailable fail-closed behavior를 포함한다. SDK-002 문서 또는 packaging 변경에서는 CLI help, `doctor`,
 dry-run `deploy`, `verify`/preflight와 `test-module` command path도 별도로
-확인한다.
+확인한다. `scripts/sdk-product-smoke.sh`는 CLI, Toolkit과 RFQ package를 모두
+tarball로 pack한 뒤 clean temporary project에 설치해야 하며 Toolkit public export,
+generated RFQ conformance, CLI doctor/deploy와 packaged contract build를 검증한다.
 
 Generated consumer projects should keep this local gate:
 

diff --git a/scripts/sdk-product-smoke.sh b/scripts/sdk-product-smoke.sh
@@ -24,8 +24,13 @@ CLI_TARBALL_NAME=$(
   cd "$ROOT_DIR"
   npm pack ./services/cli --pack-destination "$PACK_DIR" --silent | tail -n 1
 )
+TOOLKIT_TARBALL_NAME=$(
+  cd "$ROOT_DIR"
+  npm pack ./services/toolkit --pack-destination "$PACK_DIR" --silent | tail -n 1
+)
 RFQ_TARBALL="$PACK_DIR/$RFQ_TARBALL_NAME"
 CLI_TARBALL="$PACK_DIR/$CLI_TARBALL_NAME"
+TOOLKIT_TARBALL="$PACK_DIR/$TOOLKIT_TARBALL_NAME"
 
 node "$ROOT_DIR/services/cli/dist/cli/src/index.js" create "$LOCAL_TARGET_DIR" \
   --mode library-only \
@@ -39,7 +44,8 @@ node "$ROOT_DIR/services/cli/dist/cli/src/index.js" create "$LOCAL_TARGET_DIR" \
 (
   cd "$BOOT_DIR"
   npm init -y >/dev/null
-  npm install --prefer-offline --silent "$CLI_TARBALL"
+  npm install --prefer-offline --silent "$CLI_TARBALL" "$TOOLKIT_TARBALL"
+  node -e 'const t = require("@corner-store/toolkit"); const c = t.validateConfig(t.defaultConfig()); if (c.schemaVersion !== t.TOOLKIT_SCHEMA_VERSION || t.simulateConfig(c).venues.length === 0) process.exit(1)'
   ./node_modules/.bin/corner-store create "$TARGET_DIR" \
     --mode library-only \
     --sdk "file:$RFQ_TARBALL" \

diff --git a/services/toolkit/README.md b/services/toolkit/README.md
@@ -0,0 +1,18 @@
+# @corner-store/toolkit
+
+Versioned configuration, production onboarding planning, Safe proposal export and
+post-deployment verification helpers for Corner Store integrations.
+
+```ts
+import {defaultConfig, simulateConfig, validateConfig} from "@corner-store/toolkit";
+
+const config = validateConfig(defaultConfig());
+const simulation = simulateConfig(config);
+```
+
+The Toolkit prepares and verifies operator-owned deployment inputs. It never owns
+signer custody, submits Safe transactions, or treats ERC-3643/ONCHAINID evidence as
+trusted without the configured production checks.
+
+See `docs/sdk-integration.md` and `docs/sdk-versioning.md` in the Corner Store
+repository for integration, compatibility and migration policy.
diff --git a/services/toolkit/package.json b/services/toolkit/package.json
@@ -5,7 +5,8 @@
   "types": "dist/src/index.d.ts",
   "license": "GPL-3.0-or-later",
   "files": [
-    "dist/src"
+    "dist/src",
+    "README.md"
   ],
   "exports": {
     ".": {
@@ -25,6 +26,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
     "test": "npm run build && node dist/test/smoke.js"
   },
   "devDependencies": {