@mi8y/cds-langgraph-persistence 0.0.1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

package/.changeset/bright-windows-leave.md

@@ -0,0 +1,5 @@
+---
+"@mi8y/cds-langgraph-persistence": patch
+---
+
+Initial project setup

package/.changeset/config.json

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

package/.github/dependabot.yml

@@ -0,0 +1,72 @@
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# and
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+
+    groups:
+      # Internal LangChain packages
+      langchain:
+        patterns:
+          - "@langchain/*"
+          - "langchain"
+
+      # Vite, Vitest, and build tools
+      vite-vitest-turbo:
+        patterns:
+          - "vite"
+          - "vite-*"
+          - "vitest"
+          - "vitest-*"
+          - "@vitest/*"
+          - "rollup"
+          - "esbuild"
+          - "esbuild-*"
+          - "turbo"
+
+      # TypeScript, ESLint, and formatting
+      typescript-eslint-prettier:
+        patterns:
+          - "typescript"
+          - "@typescript-eslint/*"
+          - "@tsconfig/*"
+          - "eslint"
+          - "eslint-*"
+          - "@eslint/*"
+          - "prettier"
+
+      # SAP
+      sap:
+        patterns:
+          - "@sap/*"
+          - "@cap-js/*"
+
+      # Maintenance
+      cli-tools:
+        patterns:
+          - "@changesets/*"
+
+      # Type definitions
+      types:
+        patterns:
+          - "@types/*"
+
+      # Everything else — minor and patch together, major separately
+      minor-and-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+      major:
+        patterns:
+          - "*"
+        update-types:
+          - "major"

package/.github/workflows/ci.yaml

@@ -0,0 +1,159 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: ci
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch: # Allows triggering the workflow manually in GitHub UI
+
+permissions:
+  contents: read
+
+# If another push to the same PR or branch happens while this workflow is still running,
+# cancel the earlier run in favor of the next run.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ===========================================
+  # Static checks + Build (all run in parallel)
+  # ===========================================
+  lint:
+    name: check linting
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check linting
+        run: pnpm lint:check
+
+  format:
+    name: check formatting
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm format:check
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Create build archive
+        run: tar -czf build-artifacts.tar.gz dist
+
+      - name: Publish to pkg.pr.new
+        if: ${{ github.event_name == 'pull_request' }}
+        run: pnpm dlx pkg-pr-new publish './*.tgz'
+        continue-on-error: true
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: build-artifacts
+          path: build-artifacts.tar.gz
+          retention-days: 1
+
+  # ============================================
+  # Stage 2: Tests (require build + all static checks to pass)
+  # ============================================
+  test:
+    name: unit tests
+    needs: [lint, format, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      code-quality: write
+      pull-requests: read
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: build-artifacts
+
+      - name: Extract build artifacts
+        run: tar -xzf build-artifacts.tar.gz
+        shell: bash
+
+      - name: Test
+        run: pnpm test
+
+      - name: Upload coverage report
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/upload-code-coverage@v1
+        with:
+          file: coverage/cobertura-coverage.xml
+          language: JavaScript
+          label: coverage

package/.github/workflows/pr-lint.yaml

@@ -0,0 +1,58 @@
+# Enforces Conventional Commits format for pull request titles.
+name: pr title lint
+
+permissions:
+  pull-requests: read
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  lint-pr-title:
+    name: validate title format
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Reject empty scope"
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          if [[ "$PR_TITLE" =~ ^[a-z]+\(\)[!]?: ]]; then
+            echo "::error::PR title has empty scope parentheses: '$PR_TITLE'"
+            echo "Either remove the parentheses or provide a scope (e.g., 'fix(langgraph): ...')."
+            exit 1
+          fi
+
+      - name: "Validate Conventional Commits format"
+        uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+            release
+            hotfix
+          scopes: |
+            cds-langgraph-persistence
+            docs
+            examples
+            internal
+            infra
+            deps
+            deps-dev
+          requireScope: false
+          disallowScopes: |
+            release
+            [A-Z]+
+          ignoreLabels: |
+            ignore-lint-pr-title

package/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: release to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v7
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm run version-packages
+          publish: pnpm run publish-packages
+          commit: "chore: version packages"
+          title: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: '' # # Use OIDC for npm authentication

package/AGENTS.md

@@ -0,0 +1,34 @@
+# CDS Persistence Plugin for LangGraph Checkpoint & Memory
+
+This project builds a CDS Plugin for SAP CAP applications to build LangGraph/LangChain/Deep Agents based applications with Checkpoint and Memory persistence. It provides necessary tooling as well as library support for agents built within SAP CAP applications.
+
+## Project Structure
+
+/
+├── package.json
+├── AGENTS.md <- You are here
+├── src
+│ ├── checkpoint
+│ │ ├── cds-checkpointer.ts
+│ │ └── index.ts
+│ └── memory
+│ ├── cds-memory.ts
+│ └── index.ts
+├── tests
+│ ├── checkpoint
+│ └── memory
+└── cds-plugin.js
+
+## Development
+
+- Project uses **`pnpm`** as package manager. `npm install -g pnpm` if not already installed.
+- `pnpm install` to install dependencies.
+
+## Testing
+
+- Uses Vitest framework and follows `*.test.ts` naming convention.
+- `pnpm test` to run tests
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md)

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Setup
+
+```sh
+pnpm install
+```
+
+## Scripts
+
+| Script              | Description                      |
+| ------------------- | -------------------------------- |
+| `pnpm test`         | Run the test suite               |
+| `pnpm lint:check`   | Run all linters without writing  |
+| `pnpm lint`         | Auto-fix lint issues             |
+| `pnpm format:check` | Check formatting without writing |
+| `pnpm format`       | Format source files              |
+| `pnpm changeset`    | Wizard-based changeset creation  |
+
+## Style Guides
+
+- While raising a pull-request, ensure that
+  - PR title follows the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
+  - Build is passing - `pnpm build` before committing.
+  - All tests are passing - `pnpm test` before committing.
+  - Code is formatted - `pnpm format` and linted - `pnpm lint` before committing.
+  - Ensure the code is well documented
+  - Ensure the code is well tested and test coverage is not reduced.
+  - _Optionally_, a changeset `pnpm changeset` is created . If you are unsure, you can skip this step and the maintainers will create a changeset for you.
+
+## Behaviour
+
+- The changeset bot will listen for pull requests being opened and pull requests that have been updated, upon which it will then scan through the files for a changeset that has been added. If not, it will comment on the pull request to remind the contributor to add a changeset.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mi8Y Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# CDS Plugin for LangGraph Checkpoint & Memory

package/eslint.config.mjs

@@ -0,0 +1,20 @@
+// @ts-check
+
+import js from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import tseslint from "typescript-eslint";
+import cds from "@sap/eslint-plugin-cds";
+
+export default defineConfig({
+  files: ["src/**/*.{js,ts}", "**/*.cds"],
+  extends: [
+    js.configs.recommended,
+    tseslint.configs.recommended,
+    cds.configs.recommended,
+    {
+      rules: {
+        "@typescript-eslint/no-unused-expressions": "off", // cds uses expressions for 'column' in queries
+      },
+    },
+  ],
+});

package/index.cds

@@ -0,0 +1,23 @@
+namespace plugin.langgraph.persistence;
+
+entity Checkpoints {
+    key id         : String(256) not null;
+    key namespace  : String(256) not null default '';
+    key threadId   : String(256) not null;
+        parentId   : String(256);
+        type       : String(64);
+        checkpoint : LargeString not null;
+        metadata   : LargeString;
+        createdAt  : Timestamp default $now;
+        writes     : Composition of many CheckpointWrites
+                         on writes.checkpoint = $self;
+}
+
+entity CheckpointWrites {
+    key checkpoint : Association to Checkpoints;
+    key taskId     : String(256) not null;
+    key idx        : Integer not null;
+        channel    : String(256) not null;
+        type       : String(64);
+        value      : LargeString;
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@mi8y/cds-langgraph-persistence",
+  "version": "0.0.1",
+  "description": "CDS Plugin for enabling persistence in LangGraph/LangChain/DeepAgents - Checkpoint & Memory",
+  "author": "Merbin J Anselm <merbin.j.anselm@mi8y.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mi8y/cds-langgraph-persistence.git"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/mi8y/cds-langgraph-persistence",
+  "bugs": {
+    "url": "https://github.com/mi8y/cds-langgraph-persistence/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@langchain/langgraph-checkpoint": "^1.1.3"
+  },
+  "devDependencies": {
+    "@cap-js/cds-typer": "^0.40.0",
+    "@cap-js/cds-types": "^0.18.0",
+    "@cap-js/sqlite": "^3.0.2",
+    "@changesets/cli": "^2.31.0",
+    "@eslint/js": "^10.0.1",
+    "@langchain/core": "^1.2.1",
+    "@langchain/langgraph-checkpoint-validation": "^1.1.0",
+    "@sap/eslint-plugin-cds": "^4.2.4",
+    "@tsconfig/recommended": "^1.0.13",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.6.0",
+    "prettier": "^3.9.4",
+    "shx": "^0.4.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1",
+    "vite": "^8.1.3",
+    "vite-plugin-dts": "^5.0.3",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@sap/cds": ">=8"
+  },
+  "scripts": {
+    "dev": "npm run build:cds-types && vite build --watch",
+    "build": "shx rm -rf dist && npm run build:cds-types && vite build",
+    "build:cds-types": "cds-typer index.cds",
+    "test": "vitest run --coverage",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint . --max-warnings 0",
+    "format": "prettier --write \"**/*.{json,ts,js,mjs,cjs,md}\"",
+    "format:check": "prettier --check \"**/*.{json,ts,js,mjs,cjs,md}\"",
+    "changeset": "changeset",
+    "version-packages": "changeset version && pnpm install --no-frozen-lockfile && pnpm run format",
+    "publish-packages": "changeset publish",
+    "clean": "shx rm -rf node_modules dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  tree-sitter: false
+  tree-sitter-java: false

package/src/checkpoint/cds-checkpointer.ts

@@ -0,0 +1,393 @@
+import {
+  Checkpoints,
+  CheckpointWrite,
+  CheckpointWrites,
+} from "#cds-models/plugin/langgraph/persistence";
+import { type RunnableConfig } from "@langchain/core/runnables";
+import {
+  BaseCheckpointSaver,
+  ChannelVersions,
+  Checkpoint,
+  CheckpointListOptions,
+  CheckpointMetadata,
+  CheckpointTuple,
+  copyCheckpoint,
+  maxChannelVersion,
+  PendingWrite,
+  SerializerProtocol,
+  TASKS,
+  WRITES_IDX_MAP,
+} from "@langchain/langgraph-checkpoint";
+
+export class CdsCheckpointSaver extends BaseCheckpointSaver {
+  constructor(serde?: SerializerProtocol) {
+    super(serde);
+  }
+
+  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+    if (!config.configurable) {
+      throw new Error(`Empty "config.configurable" supplied`);
+    }
+
+    const checkpointId: string | undefined = config.configurable.checkpoint_id;
+    const checkpointNamespace: string = config.configurable.checkpoint_ns ?? "";
+    const threadId: string | undefined = config.configurable.thread_id;
+    if (!threadId) {
+      return undefined;
+    }
+
+    let query = SELECT.one
+      .from(Checkpoints)
+      .columns((c) => {
+        (c.threadId,
+          c.namespace,
+          c.id,
+          c.parentId,
+          c.type,
+          c.checkpoint,
+          c.metadata,
+          c.writes((w) => {
+            (w.taskId, w.channel, w.type, w.value);
+          }));
+      })
+      .where({
+        threadId: threadId,
+        namespace: checkpointNamespace,
+        ...(checkpointId ? { id: checkpointId } : {}),
+      });
+
+    if (!checkpointId) {
+      query = query.orderBy("id desc").limit(1);
+    }
+
+    const resCheckpoint = await query;
+    if (!resCheckpoint) {
+      return undefined;
+    }
+
+    const checkpoint = (await this.serde.loadsTyped(
+      resCheckpoint.type ?? "json",
+      resCheckpoint.checkpoint ?? "",
+    )) as Checkpoint;
+
+    const metadata = (await this.serde.loadsTyped(
+      resCheckpoint.type ?? "json",
+      resCheckpoint.metadata ?? "",
+    )) as CheckpointMetadata;
+
+    const pendingWrites = await Promise.all(
+      (resCheckpoint.writes ?? []).map(async (w) => {
+        return [
+          w.taskId,
+          w.channel,
+          await this.serde.loadsTyped(w.type ?? "json", w.value ?? ""),
+        ] as [string, string, unknown];
+      }),
+    );
+
+    if (checkpoint.v < 4 && resCheckpoint.parentId) {
+      await this.migratePendingSends(
+        checkpoint,
+        resCheckpoint.threadId!,
+        resCheckpoint.parentId,
+      );
+    }
+
+    return {
+      checkpoint: checkpoint,
+      config: {
+        configurable: {
+          thread_id: resCheckpoint.threadId,
+          checkpoint_ns: resCheckpoint.namespace,
+          checkpoint_id: resCheckpoint.id,
+        },
+      },
+      parentConfig: resCheckpoint.parentId
+        ? {
+            configurable: {
+              thread_id: resCheckpoint.threadId,
+              checkpoint_ns: resCheckpoint.namespace,
+              checkpoint_id: resCheckpoint.parentId,
+            },
+          }
+        : undefined,
+      metadata: metadata,
+      pendingWrites: pendingWrites,
+    };
+  }
+
+  async *list(
+    config: RunnableConfig,
+    options?: CheckpointListOptions,
+  ): AsyncGenerator<CheckpointTuple> {
+    const { limit, before, filter } = options ?? {};
+
+    const threadId: string | undefined = config.configurable?.thread_id;
+    const checkpointNamespace: string | undefined =
+      config.configurable?.checkpoint_ns;
+
+    let query = SELECT.from(Checkpoints)
+      .columns((c) => {
+        (c.threadId,
+          c.namespace,
+          c.id,
+          c.parentId,
+          c.type,
+          c.checkpoint,
+          c.metadata,
+          c.writes((w) => {
+            (w.taskId, w.channel, w.type, w.value);
+          }));
+      })
+      .orderBy("id desc");
+
+    if (threadId !== undefined) {
+      query = query.where({ threadId: threadId });
+    }
+
+    if (checkpointNamespace !== undefined && checkpointNamespace !== null) {
+      query = query.where({ namespace: checkpointNamespace });
+    }
+
+    if (before?.configurable?.checkpoint_id !== undefined) {
+      query = query.where({ id: { "<": before.configurable.checkpoint_id } });
+    }
+
+    // CAP CDS does not support native JSON operations - so we filter them in memory after fetching the results
+    const sanitizedFilter = Object.fromEntries(
+      Object.entries(filter ?? {}).filter(([, value]) => value !== undefined),
+    );
+    const hasFilter = Object.keys(sanitizedFilter).length > 0;
+
+    if (limit !== undefined && !hasFilter) {
+      query = query.limit(limit);
+    }
+
+    const resCheckpoints = await query;
+    if (!resCheckpoints) {
+      return;
+    }
+
+    let yielded = 0;
+    for (const checkpointState of resCheckpoints) {
+      if (limit !== undefined && yielded >= limit) {
+        break;
+      }
+
+      const deserializedMetadata = (await this.serde.loadsTyped(
+        checkpointState.type ?? "json",
+        checkpointState.metadata ?? "",
+      )) as CheckpointMetadata & Record<string, unknown>;
+
+      if (hasFilter) {
+        // since not filtered in the query, we filter in memory
+        const matchesFilter = Object.entries(sanitizedFilter).every(
+          ([key, value]) => deserializedMetadata[key] === value,
+        );
+        if (!matchesFilter) {
+          continue;
+        }
+      }
+
+      const checkpoint = (await this.serde.loadsTyped(
+        checkpointState.type ?? "json",
+        checkpointState.checkpoint ?? "",
+      )) as Checkpoint;
+
+      const pendingWrites = await Promise.all(
+        (checkpointState.writes ?? []).map(async (w) => {
+          return [
+            w.taskId,
+            w.channel,
+            await this.serde.loadsTyped(w.type ?? "json", w.value ?? ""),
+          ] as [string, string, unknown];
+        }),
+      );
+
+      if (checkpoint.v < 4 && checkpointState.parentId) {
+        await this.migratePendingSends(
+          checkpoint,
+          checkpointState.threadId!,
+          checkpointState.parentId,
+        );
+      }
+
+      yield {
+        config: {
+          configurable: {
+            thread_id: checkpointState.threadId,
+            checkpoint_ns: checkpointState.namespace,
+            checkpoint_id: checkpointState.id,
+          },
+        },
+        checkpoint: checkpoint,
+        parentConfig: checkpointState.parentId
+          ? {
+              configurable: {
+                thread_id: checkpointState.threadId,
+                checkpoint_ns: checkpointState.namespace,
+                checkpoint_id: checkpointState.parentId,
+              },
+            }
+          : undefined,
+        metadata: deserializedMetadata,
+        pendingWrites: pendingWrites,
+      };
+
+      yielded++;
+    }
+  }
+
+  async put(
+    config: RunnableConfig,
+    checkpoint: Checkpoint,
+    metadata: CheckpointMetadata,
+    newVersions: ChannelVersions,
+  ): Promise<RunnableConfig> {
+    if (!config.configurable) {
+      throw new Error(`Empty "config.configurable" supplied`);
+    }
+
+    const checkpointNamespace: string = config.configurable.checkpoint_ns ?? "";
+    const parentCheckpointId: string | undefined =
+      config.configurable.checkpoint_id;
+    const threadId: string | undefined = config.configurable.thread_id;
+    if (!threadId) {
+      throw new Error(
+        `Missing "thread_id" field in passed in "config.configurable"`,
+      );
+    }
+
+    const newChannelValues = Object.fromEntries(
+      Object.entries(checkpoint.channel_values).filter(
+        ([key]) => key in newVersions,
+      ),
+    );
+    const newChannelVersions = Object.fromEntries(
+      Object.entries(checkpoint.channel_versions).filter(
+        ([key]) => key in newVersions,
+      ),
+    );
+
+    const filteredCheckpoint = {
+      ...checkpoint,
+      channel_values: newChannelValues,
+      channel_versions: newChannelVersions,
+    };
+
+    const preparedCheckpoint: Partial<Checkpoint> =
+      copyCheckpoint(filteredCheckpoint);
+
+    const [[type1, serializedCheckpoint], [type2, serializedMetadata]] =
+      await Promise.all([
+        this.serde.dumpsTyped(preparedCheckpoint),
+        this.serde.dumpsTyped(metadata),
+      ]);
+    if (type1 !== type2) {
+      throw new Error(
+        "Failed to serialized checkpoint and metadata to the same type.",
+      );
+    }
+
+    const valueDecoder = new TextDecoder("utf-8");
+    await UPSERT.into(Checkpoints).entries({
+      id: checkpoint.id,
+      namespace: checkpointNamespace,
+      threadId: threadId,
+      parentId: parentCheckpointId,
+      type: type1,
+      checkpoint: valueDecoder.decode(serializedCheckpoint),
+      metadata: valueDecoder.decode(serializedMetadata),
+    });
+
+    return {
+      configurable: {
+        thread_id: threadId,
+        checkpoint_ns: checkpointNamespace,
+        checkpoint_id: checkpoint.id,
+      },
+    };
+  }
+
+  async putWrites(
+    config: RunnableConfig,
+    writes: PendingWrite[],
+    taskId: string,
+  ): Promise<void> {
+    if (!config.configurable) {
+      throw new Error(`Empty "config.configurable" supplied`);
+    }
+
+    const checkpointNamespace: string = config.configurable.checkpoint_ns ?? "";
+    const checkpointId: string | undefined = config.configurable.checkpoint_id;
+    if (!checkpointId) {
+      throw new Error(
+        `Missing "checkpoint_id" field in passed in "config.configurable"`,
+      );
+    }
+    const threadId: string | undefined = config.configurable.thread_id;
+    if (!threadId) {
+      throw new Error(
+        `Missing "thread_id" field in passed in "config.configurable"`,
+      );
+    }
+
+    const pendingWrites: CheckpointWrite[] = await Promise.all(
+      writes.map(async (write, idx) => {
+        const [type, serializedValue] = await this.serde.dumpsTyped(write[1]);
+        const valueDecoder = new TextDecoder("utf-8");
+        return {
+          threadId: threadId,
+          checkpoint_id: checkpointId,
+          checkpoint_namespace: checkpointNamespace,
+          checkpoint_threadId: threadId,
+          taskId: taskId,
+          // Special channels are stored at fixed negative indices so they
+          // never collide with regular per-step writes (whose `idx` is the
+          // ordinal within `writes`).
+          idx: WRITES_IDX_MAP[write[0]] ?? idx,
+          channel: write[0],
+          type: type,
+          value: valueDecoder.decode(serializedValue),
+        };
+      }),
+    );
+
+    await UPSERT.into(CheckpointWrites).entries(pendingWrites);
+  }
+
+  async deleteThread(threadId: string): Promise<void> {
+    await DELETE.from(CheckpointWrites).where({
+      checkpoint_threadId: threadId,
+    });
+    await DELETE.from(Checkpoints).where({ threadId: threadId });
+  }
+
+  protected async migratePendingSends(
+    checkpoint: Checkpoint,
+    threadId: string,
+    parentId: string,
+  ) {
+    const parentWrites = await SELECT.from(CheckpointWrites)
+      .where({
+        checkpoint_threadId: threadId,
+        checkpoint_id: parentId,
+        channel: TASKS,
+      })
+      .orderBy("taskId", "idx");
+
+    if (parentWrites === undefined || parentWrites.length === 0) {
+      return;
+    }
+
+    checkpoint.channel_values[TASKS] = await Promise.all(
+      parentWrites.map((w) =>
+        this.serde.loadsTyped(w.type ?? "json", w.value ?? ""),
+      ),
+    );
+    checkpoint.channel_versions[TASKS] =
+      Object.keys(checkpoint.channel_versions).length > 0
+        ? maxChannelVersion(...Object.values(checkpoint.channel_versions))
+        : this.getNextVersion(undefined);
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { CdsCheckpointSaver } from "@/checkpoint/cds-checkpointer";

package/tests/checkpoint/cds-checkpointer.test.ts

@@ -0,0 +1,47 @@
+import {
+  Checkpoints,
+  CheckpointWrites,
+} from "#cds-models/plugin/langgraph/persistence";
+import { CdsCheckpointSaver } from "@/index";
+import {
+  CheckpointSaverTestInitializer,
+  validate,
+} from "@langchain/langgraph-checkpoint-validation";
+import cds from "@sap/cds";
+
+export const cdsCheckpointSaverTestInitializer: CheckpointSaverTestInitializer<CdsCheckpointSaver> =
+  {
+    checkpointerName: "@langchain/langgraph-checkpoint-cds",
+
+    async beforeAll() {
+      const csn = await cds.load("index.cds").then(cds.minify);
+      cds.model = cds.compile.for.nodejs(csn);
+
+      cds.requires.db = {
+        kind: "sqlite",
+        impl: "@cap-js/sqlite",
+        credentials: { url: ":memory:" },
+      };
+
+      cds.db = await cds.connect.to("db");
+
+      // @ts-ignore
+      await cds.deploy("index.cds", {}).to(cds.db);
+    },
+
+    async afterAll() {
+      // @ts-ignore
+      await cds.db.disconnect?.();
+    },
+
+    async createCheckpointer() {
+      return new CdsCheckpointSaver();
+    },
+
+    async destroyCheckpointer() {
+      await DELETE.from(CheckpointWrites);
+      await DELETE.from(Checkpoints);
+    },
+  };
+
+validate(cdsCheckpointSaverTestInitializer);

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@tsconfig/recommended",
+  "compilerOptions": {
+    "rootDir": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@sap/cds": ["./node_modules/@cap-js/cds-types"],
+      "#cds-models/*": ["./@cds-models/*"]
+    }
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist", "@cds-models"]
+}

package/vite.config.ts

@@ -0,0 +1,50 @@
+/// <reference types="vitest/config" />
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+import tsconfigPaths from "vite-tsconfig-paths";
+import { builtinModules } from "module";
+import pkg from "./package.json";
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths(),
+    dts({
+      insertTypesEntry: true, // Automatically links types in package.json
+      include: ["src"],
+    }),
+  ],
+
+  // Build Configuration
+  build: {
+    minify: false, // disable since this is a node library
+    lib: {
+      entry: "src/index.ts",
+      name: "@mi8y/cds-langgraph-persistence",
+      fileName: "index",
+      formats: ["es", "cjs"],
+    },
+    sourcemap: true,
+    rolldownOptions: {
+      external: [
+        // ignore dependencies when bundling
+        ...builtinModules,
+        ...builtinModules.map((m) => `node:${m}`),
+        ...Object.keys(pkg.dependencies || {}),
+        ...Object.keys(pkg.peerDependencies || {}),
+      ],
+    },
+  },
+
+  // Testing Configuration (Vitest)
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/**/*.ts"],
+    coverage: {
+      provider: "v8",
+      exclude: ["@cds-models/"],
+      reporter: ["cobertura"],
+      reportsDirectory: "coverage",
+    },
+  },
+});