cf-workspace-store 0.1.0__tar.gz

cf_workspace_store-0.1.0/CMakeLists.txt

@@ -0,0 +1,6 @@
+cmake_minimum_required(VERSION 3.20)
+project(cf_workspace_store LANGUAGES CXX)
+
+add_subdirectory(src/cf_workspace_store/native)
+
+install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/src/cf_workspace_store/provider_descriptor.v1.json DESTINATION cf_workspace_store)

cf_workspace_store-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.2
+Name: cf-workspace-store
+Version: 0.1.0
+Summary: Embedded workspace store provider for Cogniflow
+Requires-Python: >=3.11
+Requires-Dist: duckdb<2.0,>=0.10
+Requires-Dist: cf-package-contracts>=0.1.0
+Requires-Dist: cf-service-contracts>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest<9.0,>=8.0; extra == "test"
+Description-Content-Type: text/markdown
+
+# cf_workspace_store
+
+`cf_workspace_store` owns the embedded workspace-store infrastructure surface for Cogniflow.
+
+It provides:
+
+- a Python API for opening the runtime-state named store plus ephemeral sessions
+- a native `CfWorkspaceStoreContractV1` provider for other native packages
+
+DuckDB is the first backend implementation, but DuckDB-specific handles and types stay internal to this package.
+
+`pipeline_states` is the only public named store surface.
+Productive RDF semantics should use `ProviderKey.SEMANTICS_STORE`; old RDF DuckDB files are cleanup-only internals.

cf_workspace_store-0.1.0/README.md

@@ -0,0 +1,13 @@
+# cf_workspace_store
+
+`cf_workspace_store` owns the embedded workspace-store infrastructure surface for Cogniflow.
+
+It provides:
+
+- a Python API for opening the runtime-state named store plus ephemeral sessions
+- a native `CfWorkspaceStoreContractV1` provider for other native packages
+
+DuckDB is the first backend implementation, but DuckDB-specific handles and types stay internal to this package.
+
+`pipeline_states` is the only public named store surface.
+Productive RDF semantics should use `ProviderKey.SEMANTICS_STORE`; old RDF DuckDB files are cleanup-only internals.

cf_workspace_store-0.1.0/cf-package.yaml

@@ -0,0 +1,40 @@
+schema_version: 1
+package_id: cf-workspace-store
+defaults:
+  owner: cf-team
+  last_reviewed: '2026-03-30'
+files:
+  entries:
+  - path: CMakeLists.txt
+    status: current
+    purpose: build
+  - path: README.md
+    status: current
+    purpose: docs
+  - path: pyproject.toml
+    status: current
+    purpose: build
+  - path: src/cf_workspace_store/__init__.py
+    status: current
+    purpose: source
+  - path: src/cf_workspace_store/paths.py
+    status: current
+    purpose: source
+  - path: src/cf_workspace_store/store.py
+    status: current
+    purpose: source
+  - path: src/cf_workspace_store/provider_descriptor.v1.json
+    status: current
+    purpose: runtime
+  - path: src/cf_workspace_store/native/CMakeLists.txt
+    status: current
+    purpose: build
+  - path: src/cf_workspace_store/native/workspace_store_contract_provider.cpp
+    status: current
+    purpose: source
+  - path: tests/test_install_surface.py
+    status: current
+    purpose: test
+  - path: tests/test_store.py
+    status: current
+    purpose: test

cf_workspace_store-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = [
+  "scikit-build-core>=0.9",
+  "cf-package-contracts>=0.1.0",
+]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "cf-workspace-store"
+version = "0.1.0"
+description = "Embedded workspace store provider for Cogniflow"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "duckdb>=0.10,<2.0",
+  "cf-package-contracts>=0.1.0",
+  "cf-service-contracts>=0.1.0",
+]
+
+[project.entry-points."cogniflow.service_providers"]
+workspace_store = "cf_workspace_store.service_contract_provider:provide_workspace_store_contract"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0,<9.0",
+]
+
+[tool.scikit-build]
+wheel.packages = ["src/cf_workspace_store"]
+build-dir = "../../.native_deps/scikit-build/cf-workspace-store"
+
+[tool.scikit-build.sdist]
+include = [
+  "CMakeLists.txt",
+  "README.md",
+  "cf-package.yaml",
+  "src/cf_workspace_store/**",
+  "tests/**"
+]

cf_workspace_store-0.1.0/src/cf_workspace_store/__init__.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from importlib import metadata
+from pathlib import Path
+
+from .paths import (
+    DEFAULT_SEMANTICS_DB_FILES,
+    WorkspaceStoreKind,
+    WorkspaceStorePaths,
+    find_repo_root,
+    resolve_named_store_path,
+    resolve_semantics_dir,
+    resolve_workspace_dir,
+    resolve_workspace_store_paths,
+)
+from .store import (
+    ConstraintException,
+    WorkspaceQueryResult,
+    WorkspaceStore,
+    WorkspaceStoreSession,
+    open_ephemeral,
+    open_named,
+    open_path,
+)
+
+__version__ = "0.1.0"
+
+
+def _locate_distribution_file(*relative_candidates: str) -> Path:
+    distribution = metadata.distribution("cf-workspace-store")
+    files = distribution.files or []
+    for candidate in relative_candidates:
+        for entry in files:
+            if entry.as_posix() == candidate:
+                return Path(distribution.locate_file(entry)).resolve()
+    raise FileNotFoundError(
+        f"Could not locate any of {relative_candidates!r} in cf-workspace-store distribution files."
+    )
+
+
+def _native_root() -> Path:
+    try:
+        return _locate_distribution_file(
+            "cf_workspace_store/native/bin/cf_workspace_store_provider.dll",
+            "cf_workspace_store/native/bin/libcf_workspace_store_provider.dll",
+            "cf_workspace_store/native/lib/libcf_workspace_store_provider.so",
+            "cf_workspace_store/native/lib/libcf_workspace_store_provider.dylib",
+        ).parents[1]
+    except Exception:
+        return Path(__file__).resolve().parent / "native"
+
+
+def cf_workspace_store_provider_path() -> str:
+    native_root = _native_root()
+    candidates = [
+        native_root / "bin" / "cf_workspace_store_provider.dll",
+        native_root / "bin" / "libcf_workspace_store_provider.dll",
+        native_root / "lib" / "libcf_workspace_store_provider.so",
+        native_root / "lib" / "libcf_workspace_store_provider.dylib",
+        native_root / "lib" / "cf_workspace_store_provider.dll",
+        native_root / "lib" / "libcf_workspace_store_provider.dll",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return str(candidate)
+    raise FileNotFoundError("Packaged cf_workspace_store provider library not found.")
+
+
+def cf_workspace_store_provider_descriptor_path() -> str:
+    try:
+        return str(_locate_distribution_file("cf_workspace_store/provider_descriptor.v1.json"))
+    except Exception:
+        return str(Path(__file__).resolve().parent / "provider_descriptor.v1.json")
+
+
+__all__ = [
+    "__version__",
+    "DEFAULT_SEMANTICS_DB_FILES",
+    "WorkspaceQueryResult",
+    "WorkspaceStore",
+    "WorkspaceStoreKind",
+    "WorkspaceStorePaths",
+    "WorkspaceStoreSession",
+    "ConstraintException",
+    "cf_workspace_store_provider_descriptor_path",
+    "cf_workspace_store_provider_path",
+    "find_repo_root",
+    "open_ephemeral",
+    "open_named",
+    "open_path",
+    "resolve_named_store_path",
+    "resolve_semantics_dir",
+    "resolve_workspace_dir",
+    "resolve_workspace_store_paths",
+]

cf_workspace_store-0.1.0/src/cf_workspace_store/native/CMakeLists.txt

@@ -0,0 +1,194 @@
+cmake_minimum_required(VERSION 3.20)
+project(cf_workspace_store_provider LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+include(GNUInstallDirs)
+
+function(_cf_workspace_store_first_existing_path out_var)
+  foreach(_candidate IN LISTS ARGN)
+    if (NOT _candidate STREQUAL "" AND EXISTS "${_candidate}")
+      set(${out_var} "${_candidate}" PARENT_SCOPE)
+      return()
+    endif()
+  endforeach()
+  set(${out_var} "" PARENT_SCOPE)
+endfunction()
+
+function(_cf_workspace_store_find_repo_native_duckdb_root out_var)
+  set(_search_roots
+    "${CMAKE_SOURCE_DIR}"
+    "${PROJECT_SOURCE_DIR}"
+    "${CMAKE_CURRENT_SOURCE_DIR}"
+  )
+
+  foreach(_search_root IN LISTS _search_roots)
+    if (_search_root STREQUAL "" OR NOT IS_DIRECTORY "${_search_root}")
+      continue()
+    endif()
+
+    set(_cursor "${_search_root}")
+    while (TRUE)
+      set(_candidate "${_cursor}/.native_deps/duckdb")
+      if (EXISTS "${_candidate}")
+        set(${out_var} "${_candidate}" PARENT_SCOPE)
+        return()
+      endif()
+
+      get_filename_component(_parent "${_cursor}" DIRECTORY)
+      if (_parent STREQUAL "${_cursor}")
+        break()
+      endif()
+      set(_cursor "${_parent}")
+    endwhile()
+  endforeach()
+
+  set(${out_var} "" PARENT_SCOPE)
+endfunction()
+
+function(_cf_workspace_store_find_cache_native_duckdb_root out_var)
+  set(_version_candidates "")
+  if (NOT "$ENV{DUCKDB_VERSION}" STREQUAL "")
+    list(APPEND _version_candidates "$ENV{DUCKDB_VERSION}")
+  endif()
+  list(APPEND _version_candidates "1.4.2")
+  list(REMOVE_DUPLICATES _version_candidates)
+
+  set(_triplet_candidates
+    "x64-windows-static"
+    "x64-windows"
+  )
+
+  set(_cache_roots
+    "$ENV{CF_NATIVE_CACHE_DIR}/duckdb"
+    "$ENV{USERPROFILE}/.cogniflow/cache/native/duckdb"
+    "$ENV{HOME}/.cogniflow/cache/native/duckdb"
+  )
+
+  foreach(_cache_root IN LISTS _cache_roots)
+    if (_cache_root STREQUAL "" OR NOT IS_DIRECTORY "${_cache_root}")
+      continue()
+    endif()
+
+    foreach(_version IN LISTS _version_candidates)
+      foreach(_triplet IN LISTS _triplet_candidates)
+        set(_candidate "${_cache_root}/${_version}/${_triplet}")
+        if (EXISTS "${_candidate}")
+          set(${out_var} "${_candidate}" PARENT_SCOPE)
+          return()
+        endif()
+      endforeach()
+    endforeach()
+
+    file(GLOB _cache_version_dirs LIST_DIRECTORIES true "${_cache_root}/*")
+    list(SORT _cache_version_dirs COMPARE NATURAL ORDER DESCENDING)
+    foreach(_version_dir IN LISTS _cache_version_dirs)
+      if (NOT IS_DIRECTORY "${_version_dir}")
+        continue()
+      endif()
+      foreach(_triplet IN LISTS _triplet_candidates)
+        set(_candidate "${_version_dir}/${_triplet}")
+        if (EXISTS "${_candidate}")
+          set(${out_var} "${_candidate}" PARENT_SCOPE)
+          return()
+        endif()
+      endforeach()
+    endforeach()
+  endforeach()
+
+  set(${out_var} "" PARENT_SCOPE)
+endfunction()
+
+get_filename_component(_CF_REPO_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../../.." ABSOLUTE)
+include("${_CF_REPO_ROOT}/tools/cmake/cf_contracts_include.cmake")
+set(CF_SDK_INCLUDE "${CF_CONTRACTS_INCLUDE}")
+
+set(_native_duckdb_root "$ENV{CF_WORKSPACE_STORE_DUCKDB_ROOT}")
+if (_native_duckdb_root STREQUAL "")
+  _cf_workspace_store_find_cache_native_duckdb_root(_native_duckdb_root)
+endif()
+if (_native_duckdb_root STREQUAL "")
+  _cf_workspace_store_find_repo_native_duckdb_root(_native_duckdb_root)
+endif()
+if (_native_duckdb_root STREQUAL "")
+  set(_native_duckdb_root "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../.native_deps/duckdb")
+endif()
+file(TO_CMAKE_PATH "${_native_duckdb_root}" _native_duckdb_root)
+
+set(_native_duckdb_include "${_native_duckdb_root}/include")
+set(_native_duckdb_include_flat "${_native_duckdb_root}")
+set(_native_duckdb_src "${_native_duckdb_root}/src")
+set(_native_duckdb_lib_win "${_native_duckdb_root}/lib/duckdb.lib")
+set(_native_duckdb_lib_mingw "${_native_duckdb_root}/lib/libduckdb.a")
+set(_native_duckdb_lib_flat "${_native_duckdb_root}/duckdb.lib")
+set(_native_duckdb_src_cpp "${_native_duckdb_src}/duckdb.cpp")
+set(_native_duckdb_runtime_dll "${_native_duckdb_root}/bin/duckdb.dll")
+
+set(_duckdb_include_candidates
+  "$ENV{CF_WORKSPACE_STORE_DUCKDB_INCLUDE}"
+  "$ENV{CF_DATAHIVE_CPP_DUCKDB_INCLUDE}"
+  "${_native_duckdb_src}"
+  "${_native_duckdb_include}"
+  "${_native_duckdb_include_flat}"
+)
+_cf_workspace_store_first_existing_path(
+  CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR
+  ${_duckdb_include_candidates}
+)
+if (NOT CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR STREQUAL "")
+  file(TO_CMAKE_PATH "${CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR}" CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR)
+endif()
+
+set(_duckdb_library_candidates
+  "$ENV{CF_WORKSPACE_STORE_DUCKDB_LIBRARY}"
+  "$ENV{CF_WORKSPACE_STORE_DUCKDB_LIB}"
+  "$ENV{CF_DATAHIVE_CPP_DUCKDB_LIB}"
+  "${_native_duckdb_lib_win}"
+  "${_native_duckdb_lib_mingw}"
+  "${_native_duckdb_lib_flat}"
+)
+_cf_workspace_store_first_existing_path(
+  CF_WORKSPACE_STORE_DUCKDB_LIBRARY
+  ${_duckdb_library_candidates}
+)
+if (NOT CF_WORKSPACE_STORE_DUCKDB_LIBRARY STREQUAL "")
+  file(TO_CMAKE_PATH "${CF_WORKSPACE_STORE_DUCKDB_LIBRARY}" CF_WORKSPACE_STORE_DUCKDB_LIBRARY)
+endif()
+
+if (NOT _native_duckdb_runtime_dll STREQUAL "")
+  file(TO_CMAKE_PATH "${_native_duckdb_runtime_dll}" _native_duckdb_runtime_dll)
+endif()
+
+if (CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR STREQUAL "" OR NOT EXISTS "${CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR}/duckdb.h")
+  message(FATAL_ERROR "DuckDB headers not found. Resolved root='${_native_duckdb_root}', include='${CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR}'.")
+endif()
+
+if (CF_WORKSPACE_STORE_DUCKDB_LIBRARY STREQUAL "" OR NOT EXISTS "${CF_WORKSPACE_STORE_DUCKDB_LIBRARY}")
+  message(FATAL_ERROR "DuckDB library not found. Resolved root='${_native_duckdb_root}', library='${CF_WORKSPACE_STORE_DUCKDB_LIBRARY}'.")
+endif()
+
+add_library(cf_workspace_store_provider SHARED
+  workspace_store_contract_provider.cpp
+)
+
+target_compile_definitions(cf_workspace_store_provider PRIVATE CF_STEP_ABI_EXPORTS)
+target_include_directories(cf_workspace_store_provider PRIVATE
+  ${CF_SDK_INCLUDE}
+  ${CF_WORKSPACE_STORE_DUCKDB_INCLUDE_DIR}
+)
+target_link_libraries(cf_workspace_store_provider PRIVATE
+  ${CF_WORKSPACE_STORE_DUCKDB_LIBRARY}
+)
+set_target_properties(cf_workspace_store_provider PROPERTIES
+  PREFIX ""
+)
+
+install(TARGETS cf_workspace_store_provider
+  RUNTIME DESTINATION cf_workspace_store/native/bin
+  LIBRARY DESTINATION cf_workspace_store/native/lib
+)
+
+if (WIN32 AND EXISTS "${_native_duckdb_runtime_dll}")
+  install(FILES ${_native_duckdb_runtime_dll} DESTINATION cf_workspace_store/native/bin)
+endif()

cf_workspace_store-0.1.0/src/cf_workspace_store/native/workspace_store_contract_provider.cpp

@@ -0,0 +1,309 @@
+#include "cf_step_abi.h"
+
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <filesystem>
+#include <memory>
+#include <optional>
+#include <random>
+#include <string>
+
+#include "duckdb.h"
+
+namespace {
+
+struct StoreHandle {
+  duckdb_database db = nullptr;
+  duckdb_connection conn = nullptr;
+
+  ~StoreHandle() {
+    if (conn != nullptr) {
+      duckdb_disconnect(&conn);
+    }
+    if (db != nullptr) {
+      duckdb_close(&db);
+    }
+  }
+};
+
+std::string copy_text(const char* value, size_t size) {
+  if (value == nullptr || size == 0) {
+    return {};
+  }
+  return std::string(value, size);
+}
+
+CfStatusCode alloc_text(CfExecutionContext* ctx, const std::string& text, const char** out_text, size_t* out_size) {
+  if (out_text == nullptr || out_size == nullptr || ctx == nullptr || ctx->allocator == nullptr || ctx->allocator->alloc == nullptr) {
+    return CF_STATUS_ERROR;
+  }
+  *out_size = text.size();
+  if (text.empty()) {
+    *out_text = nullptr;
+    return CF_STATUS_OK;
+  }
+  char* buffer = static_cast<char*>(ctx->allocator->alloc(text.size() + 1u, ctx->allocator->user_data));
+  if (buffer == nullptr) {
+    return CF_STATUS_ERROR;
+  }
+  std::memcpy(buffer, text.data(), text.size());
+  buffer[text.size()] = '\0';
+  *out_text = buffer;
+  return CF_STATUS_OK;
+}
+
+std::filesystem::path resolve_named_path(const CfWorkspaceStoreOpenRequestV1& request) {
+  std::filesystem::path semantics_dir;
+  const std::string explicit_semantics_dir = copy_text(request.semantics_dir, request.semantics_dir_size);
+  if (!explicit_semantics_dir.empty()) {
+    semantics_dir = explicit_semantics_dir;
+  } else {
+    std::filesystem::path workspace_root;
+    const std::string explicit_workspace_root = copy_text(request.workspace_root, request.workspace_root_size);
+    if (!explicit_workspace_root.empty()) {
+      workspace_root = explicit_workspace_root;
+    } else {
+      workspace_root = std::filesystem::current_path() / "workspace";
+    }
+    semantics_dir = workspace_root / "semantics";
+  }
+
+  const std::string kind = copy_text(request.store_kind, request.store_kind_size);
+  if (kind != "pipeline_states") {
+    return {};
+  }
+  return semantics_dir / "cf-pipeline-states.store.db";
+}
+
+std::string escape_sql_literal(const std::string& value) {
+  std::string escaped;
+  escaped.reserve(value.size() + 8u);
+  for (char ch : value) {
+    escaped.push_back(ch);
+    if (ch == '\'') {
+      escaped.push_back('\'');
+    }
+  }
+  return escaped;
+}
+
+CfStatusCode write_error(CfExecutionContext* ctx, const std::string& text, const char** out_error, size_t* out_error_size) {
+  if (out_error == nullptr || out_error_size == nullptr) {
+    return CF_STATUS_ERROR;
+  }
+  return alloc_text(ctx, text, out_error, out_error_size);
+}
+
+StoreHandle* unwrap(void* raw_handle) {
+  return static_cast<StoreHandle*>(raw_handle);
+}
+
+CfStatusCode open_store_at_path(
+  CfExecutionContext* ctx,
+  const std::filesystem::path& path,
+  int read_only,
+  void** out_store,
+  const char** out_error,
+  size_t* out_error_size) {
+  if (out_store == nullptr) {
+    return CF_STATUS_INVALID;
+  }
+  *out_store = nullptr;
+  if (!read_only) {
+    std::error_code ec;
+    std::filesystem::create_directories(path.parent_path(), ec);
+    if (ec) {
+      write_error(ctx, "failed to create workspace store directory", out_error, out_error_size);
+      return CF_STATUS_ERROR;
+    }
+  }
+
+  std::unique_ptr<StoreHandle> handle(new StoreHandle());
+  duckdb_config config = nullptr;
+  if (duckdb_create_config(&config) != DuckDBSuccess) {
+    write_error(ctx, "duckdb_create_config failed for workspace store", out_error, out_error_size);
+    return CF_STATUS_ERROR;
+  }
+  if (read_only) {
+    duckdb_set_config(config, "access_mode", "READ_ONLY");
+  }
+  if (duckdb_open_ext(path.string().c_str(), &handle->db, config, nullptr) != DuckDBSuccess) {
+    duckdb_destroy_config(&config);
+    write_error(ctx, "duckdb_open failed for workspace store", out_error, out_error_size);
+    return CF_STATUS_ERROR;
+  }
+  duckdb_destroy_config(&config);
+  if (duckdb_connect(handle->db, &handle->conn) != DuckDBSuccess) {
+    write_error(ctx, "duckdb_connect failed for workspace store", out_error, out_error_size);
+    return CF_STATUS_ERROR;
+  }
+  if (read_only) {
+    duckdb_result result {};
+    duckdb_query(handle->conn, "PRAGMA disable_checkpoint_on_shutdown", &result);
+    duckdb_destroy_result(&result);
+  }
+  *out_store = handle.release();
+  return CF_STATUS_OK;
+}
+
+CfStatusCode open_named_store(
+  CfExecutionContext* ctx,
+  const CfWorkspaceStoreOpenRequestV1* request,
+  void** out_store,
+  const char** out_error,
+  size_t* out_error_size) {
+  if (request == nullptr || request->version != 1u) {
+    return CF_STATUS_INVALID;
+  }
+  const std::string kind = copy_text(request->store_kind, request->store_kind_size);
+  if (kind != "pipeline_states") {
+    write_error(ctx, "unsupported named workspace store kind", out_error, out_error_size);
+    return CF_STATUS_INVALID;
+  }
+  return open_store_at_path(ctx, resolve_named_path(*request), request->read_only, out_store, out_error, out_error_size);
+}
+
+CfStatusCode open_ephemeral_store(
+  CfExecutionContext* ctx,
+  const CfWorkspaceStoreOpenRequestV1* request,
+  void** out_store,
+  const char** out_error,
+  size_t* out_error_size) {
+  std::mt19937_64 rng(std::random_device{}());
+  std::uniform_int_distribution<uint64_t> dist;
+  const auto temp_dir =
+    std::filesystem::temp_directory_path() /
+    std::filesystem::path("cf_workspace_store_ephemeral_" + std::to_string(dist(rng)) + ".db");
+  const int read_only = request != nullptr ? request->read_only : 0;
+  return open_store_at_path(ctx, temp_dir, read_only, out_store, out_error, out_error_size);
+}
+
+CfStatusCode close_store(CfExecutionContext*, void* store_handle) {
+  delete unwrap(store_handle);
+  return CF_STATUS_OK;
+}
+
+CfStatusCode exec_sql(
+  CfExecutionContext* ctx,
+  const CfWorkspaceStoreExecRequestV1* request,
+  const char** out_error,
+  size_t* out_error_size) {
+  if (request == nullptr || request->version != 1u || request->store_handle == nullptr) {
+    return CF_STATUS_INVALID;
+  }
+  duckdb_result result {};
+  const std::string sql = copy_text(request->sql, request->sql_size);
+  if (duckdb_query(unwrap(request->store_handle)->conn, sql.c_str(), &result) != DuckDBSuccess) {
+    const char* detail = duckdb_result_error(&result);
+    std::string error = "workspace store query failed";
+    if (detail != nullptr && detail[0] != '\0') {
+      error += ": ";
+      error += detail;
+    }
+    duckdb_destroy_result(&result);
+    write_error(ctx, error, out_error, out_error_size);
+    return CF_STATUS_ERROR;
+  }
+  duckdb_destroy_result(&result);
+  return CF_STATUS_OK;
+}
+
+CfStatusCode query_scalar_text(
+  CfExecutionContext* ctx,
+  const CfWorkspaceStoreScalarTextRequestV1* request,
+  const char** out_text,
+  size_t* out_size,
+  const char** out_error,
+  size_t* out_error_size) {
+  if (request == nullptr || request->version != 1u || request->store_handle == nullptr) {
+    return CF_STATUS_INVALID;
+  }
+  duckdb_result result {};
+  const std::string sql = copy_text(request->sql, request->sql_size);
+  if (duckdb_query(unwrap(request->store_handle)->conn, sql.c_str(), &result) != DuckDBSuccess) {
+    const char* detail = duckdb_result_error(&result);
+    std::string error = "workspace store scalar text query failed";
+    if (detail != nullptr && detail[0] != '\0') {
+      error += ": ";
+      error += detail;
+    }
+    duckdb_destroy_result(&result);
+    write_error(ctx, error, out_error, out_error_size);
+    return CF_STATUS_ERROR;
+  }
+  if (duckdb_row_count(&result) == 0 || duckdb_column_count(&result) == 0) {
+    duckdb_destroy_result(&result);
+    return alloc_text(ctx, "", out_text, out_size);
+  }
+  const char* value = duckdb_value_varchar(&result, 0, 0);
+  const std::string text = value != nullptr ? value : "";
+  duckdb_free(const_cast<char*>(value));
+  duckdb_destroy_result(&result);
+  return alloc_text(ctx, text, out_text, out_size);
+}
+
+CfStatusCode query_scalar_i64(
+  CfExecutionContext*,
+  const CfWorkspaceStoreScalarI64RequestV1* request,
+  int64_t* out_value,
+  const char**,
+  size_t*) {
+  if (request == nullptr || request->version != 1u || request->store_handle == nullptr || out_value == nullptr) {
+    return CF_STATUS_INVALID;
+  }
+  duckdb_result result {};
+  const std::string sql = copy_text(request->sql, request->sql_size);
+  if (duckdb_query(unwrap(request->store_handle)->conn, sql.c_str(), &result) != DuckDBSuccess) {
+    duckdb_destroy_result(&result);
+    return CF_STATUS_ERROR;
+  }
+  *out_value = (duckdb_row_count(&result) == 0 || duckdb_column_count(&result) == 0) ? 0 : duckdb_value_int64(&result, 0, 0);
+  duckdb_destroy_result(&result);
+  return CF_STATUS_OK;
+}
+
+CfStatusCode export_query_to_parquet(
+  CfExecutionContext* ctx,
+  const CfWorkspaceStoreExportParquetRequestV1* request,
+  const char** out_error,
+  size_t* out_error_size) {
+  if (request == nullptr || request->version != 1u || request->store_handle == nullptr) {
+    return CF_STATUS_INVALID;
+  }
+  const std::string sql = copy_text(request->sql, request->sql_size);
+  const std::string output_path = copy_text(request->output_path, request->output_path_size);
+  const std::string command = "COPY (" + sql + ") TO '" + escape_sql_literal(output_path) + "' (FORMAT PARQUET)";
+  duckdb_result result {};
+  if (duckdb_query(unwrap(request->store_handle)->conn, command.c_str(), &result) != DuckDBSuccess) {
+    const char* detail = duckdb_result_error(&result);
+    std::string error = "workspace store parquet export failed";
+    if (detail != nullptr && detail[0] != '\0') {
+      error += ": ";
+      error += detail;
+    }
+    duckdb_destroy_result(&result);
+    write_error(ctx, error, out_error, out_error_size);
+    return CF_STATUS_ERROR;
+  }
+  duckdb_destroy_result(&result);
+  return CF_STATUS_OK;
+}
+
+const CfWorkspaceStoreContractV1 kWorkspaceStoreContractV1 = {
+  1u,
+  0u,
+  open_named_store,
+  open_ephemeral_store,
+  close_store,
+  exec_sql,
+  query_scalar_text,
+  query_scalar_i64,
+  export_query_to_parquet,
+};
+
+}  // namespace
+
+extern "C" CF_EXPORT const CfWorkspaceStoreContractV1* cf_get_workspace_store_contract_v1() {
+  return &kWorkspaceStoreContractV1;
+}

cf_workspace_store-0.1.0/src/cf_workspace_store/paths.py

@@ -0,0 +1,61 @@
+"""Workspace-local embedded store path helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional
+
+from cf_service_contracts.cogniflow_paths import resolve_workspace_dir
+
+
+WorkspaceStoreKind = Literal["pipeline_states"]
+
+DEFAULT_SEMANTICS_DB_FILES: dict[WorkspaceStoreKind, str] = {
+    "pipeline_states": "cf-pipeline-states.store.db",
+}
+
+
+@dataclass(frozen=True)
+class WorkspaceStorePaths:
+    pipeline_states: Path
+
+    def as_dict(self) -> dict[str, Path]:
+        return {
+            "pipeline_states": self.pipeline_states,
+        }
+
+
+def find_repo_root(start: Optional[Path] = None) -> Optional[Path]:
+    probe = (start or Path.cwd()).resolve()
+    for candidate in (probe, *probe.parents):
+        if (candidate / ".git").exists():
+            return candidate
+        if (candidate / "sandcastle").is_dir() and (candidate / ".github").is_dir():
+            return candidate
+    return None
+
+
+def resolve_semantics_dir() -> Path:
+    return (resolve_workspace_dir() / "semantics").resolve()
+
+
+def resolve_named_store_path(
+    kind: WorkspaceStoreKind,
+    semantics_dir: Optional[Path] = None,
+) -> Path:
+    if str(kind) != "pipeline_states":
+        raise ValueError(
+            f"Named workspace store kind '{kind}' is not supported. Only 'pipeline_states' remains public."
+        )
+    base = semantics_dir or resolve_semantics_dir()
+    return base / DEFAULT_SEMANTICS_DB_FILES[kind]
+
+
+def resolve_workspace_store_paths(
+    semantics_dir: Optional[Path] = None,
+) -> WorkspaceStorePaths:
+    base = semantics_dir or resolve_semantics_dir()
+    return WorkspaceStorePaths(
+        pipeline_states=base / DEFAULT_SEMANTICS_DB_FILES["pipeline_states"],
+    )

cf_workspace_store-0.1.0/src/cf_workspace_store/provider_descriptor.v1.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": "provider_descriptor.v1",
+  "provider_key": "workspace_store",
+  "contract_symbol": "cf_get_workspace_store_contract_v1",
+  "contract_version": 1,
+  "library_candidates": [
+    "cf_workspace_store/native/bin/cf_workspace_store_provider.dll",
+    "cf_workspace_store/native/bin/libcf_workspace_store_provider.dll",
+    "cf_workspace_store/native/lib/cf_workspace_store_provider.dll",
+    "cf_workspace_store/native/lib/libcf_workspace_store_provider.dll",
+    "cf_workspace_store/native/lib/libcf_workspace_store_provider.so",
+    "cf_workspace_store/native/lib/libcf_workspace_store_provider.dylib"
+  ],
+  "runtime_dir_candidates": [
+    "cf_workspace_store/native/bin",
+    "cf_workspace_store/native/lib"
+  ]
+}

cf_workspace_store-0.1.0/src/cf_workspace_store/service_contract_provider.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .paths import resolve_named_store_path, resolve_semantics_dir, resolve_workspace_dir, resolve_workspace_store_paths
+from .store import ConstraintException, open_named, open_path
+
+
+class WorkspaceStoreProvider:
+    def resolve_semantics_dir(self) -> Path:
+        return resolve_semantics_dir()
+
+    def resolve_workspace_dir(self) -> Path:
+        return resolve_workspace_dir()
+
+    def resolve_named_store_path(self, kind: str, *, semantics_dir: Any = None) -> Path:
+        """Resolve the public named embedded store path.
+
+        Only `pipeline_states` remains a supported named store surface.
+        """
+        return resolve_named_store_path(kind, semantics_dir=semantics_dir)
+
+    def resolve_workspace_store_paths(self, *, semantics_dir: Any = None):
+        return resolve_workspace_store_paths(semantics_dir=semantics_dir)
+
+    def open_named(self, kind: str, *, semantics_dir: Any = None, read_only: bool):
+        """Open the supported named embedded store session.
+
+        Only `pipeline_states` remains a supported named store surface.
+        """
+        return open_named(kind, semantics_dir=semantics_dir, read_only=read_only)
+
+    def open_path(self, path: Any, *, read_only: bool):
+        return open_path(path, read_only=read_only)
+
+    @property
+    def constraint_exception(self) -> type[Exception]:
+        return ConstraintException
+
+
+def provide_workspace_store_contract() -> WorkspaceStoreProvider:
+    return WorkspaceStoreProvider()

cf_workspace_store-0.1.0/src/cf_workspace_store/store.py

@@ -0,0 +1,142 @@
+"""DuckDB-backed embedded workspace store facade."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Optional, Sequence
+import tempfile
+
+import duckdb
+
+from .paths import WorkspaceStoreKind, resolve_named_store_path, resolve_semantics_dir
+
+ConstraintException = duckdb.ConstraintException
+
+
+def _normalize_params(params: Optional[Sequence[object]]) -> list[object]:
+    if params is None:
+        return []
+    return list(params)
+
+
+@dataclass
+class WorkspaceQueryResult:
+    _cursor: Any
+
+    @property
+    def description(self) -> Any:
+        return getattr(self._cursor, "description", None)
+
+    def fetchone(self) -> Any:
+        return self._cursor.fetchone()
+
+    def fetchall(self) -> list[Any]:
+        return list(self._cursor.fetchall())
+
+
+class WorkspaceStoreSession:
+    def __init__(self, connection: Any, *, db_path: Optional[Path]) -> None:
+        self._connection = connection
+        self.db_path = db_path
+
+    def execute(
+        self,
+        sql: str,
+        params: Optional[Sequence[object]] = None,
+    ) -> WorkspaceQueryResult:
+        return WorkspaceQueryResult(self._connection.execute(sql, _normalize_params(params)))
+
+    def fetch_one(
+        self,
+        sql: str,
+        params: Optional[Sequence[object]] = None,
+    ) -> Any:
+        return self._connection.execute(sql, _normalize_params(params)).fetchone()
+
+    def fetch_all(
+        self,
+        sql: str,
+        params: Optional[Sequence[object]] = None,
+    ) -> list[Any]:
+        return list(self._connection.execute(sql, _normalize_params(params)).fetchall())
+
+    def executemany(
+        self,
+        sql: str,
+        params_seq: Iterable[Sequence[object]],
+    ) -> None:
+        self._connection.executemany(sql, list(params_seq))
+
+    def export_query_to_parquet(
+        self,
+        sql: str,
+        output_path: str | Path,
+        params: Optional[Sequence[object]] = None,
+    ) -> None:
+        target = Path(output_path).expanduser().resolve()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        escaped = str(target).replace("\\", "\\\\").replace("'", "''")
+        if params:
+            raise ValueError("export_query_to_parquet does not support bound parameters")
+        self._connection.execute(f"COPY ({sql}) TO '{escaped}' (FORMAT PARQUET)")
+
+    def close(self) -> None:
+        self._connection.close()
+
+    def __enter__(self) -> "WorkspaceStoreSession":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+class WorkspaceStore:
+    def __init__(self, *, semantics_dir: Optional[Path] = None) -> None:
+        self._semantics_dir = (semantics_dir or resolve_semantics_dir()).resolve()
+
+    @property
+    def semantics_dir(self) -> Path:
+        return self._semantics_dir
+
+    def open_named(
+        self,
+        kind: WorkspaceStoreKind,
+        *,
+        read_only: bool = False,
+    ) -> WorkspaceStoreSession:
+        if str(kind) != "pipeline_states":
+            raise ValueError(
+                f"Named workspace store kind '{kind}' is not supported. Only 'pipeline_states' remains public."
+            )
+        db_path = resolve_named_store_path(kind, self._semantics_dir)
+        if not read_only:
+            db_path.parent.mkdir(parents=True, exist_ok=True)
+        connection = duckdb.connect(str(db_path), read_only=bool(read_only))
+        return WorkspaceStoreSession(connection, db_path=db_path)
+
+    def open_ephemeral(self) -> WorkspaceStoreSession:
+        temp_dir = Path(tempfile.mkdtemp(prefix="cf_workspace_store_"))
+        db_path = temp_dir / "ephemeral.store.db"
+        return open_path(db_path, read_only=False)
+
+
+def open_named(
+    kind: WorkspaceStoreKind,
+    *,
+    read_only: bool = False,
+    semantics_dir: Optional[Path] = None,
+) -> WorkspaceStoreSession:
+    return WorkspaceStore(semantics_dir=semantics_dir).open_named(kind, read_only=read_only)
+
+
+def open_ephemeral(*, semantics_dir: Optional[Path] = None) -> WorkspaceStoreSession:
+    return WorkspaceStore(semantics_dir=semantics_dir).open_ephemeral()
+
+
+def open_path(db_path: str | Path, *, read_only: bool = False) -> WorkspaceStoreSession:
+    path = Path(db_path).expanduser().resolve()
+    if not read_only:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    connection = duckdb.connect(str(path), read_only=bool(read_only))
+    return WorkspaceStoreSession(connection, db_path=path)

cf_workspace_store-0.1.0/tests/test_install_surface.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import cf_workspace_store
+
+
+def test_provider_surface_is_exported() -> None:
+    assert cf_workspace_store.cf_workspace_store_provider_descriptor_path()
+    assert "cf_workspace_store_provider_path" in cf_workspace_store.__all__
+
+
+def test_provider_descriptor_is_packaged() -> None:
+    descriptor_path = Path(cf_workspace_store.cf_workspace_store_provider_descriptor_path())
+    assert descriptor_path.is_file()

cf_workspace_store-0.1.0/tests/test_store.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+import warnings
+
+import pytest
+
+from cf_workspace_store import WorkspaceStore, resolve_workspace_store_paths
+
+
+def test_named_store_uses_pipeline_state_store_name(tmp_path: Path) -> None:
+    store = WorkspaceStore(semantics_dir=tmp_path)
+    paths = resolve_workspace_store_paths(tmp_path)
+
+    with store.open_named("pipeline_states") as session:
+        session.execute("CREATE TABLE IF NOT EXISTS demo(value INTEGER)")
+
+    assert paths.pipeline_states.name == "cf-pipeline-states.store.db"
+    assert paths.pipeline_states.is_file()
+
+
+def test_pipeline_state_store_does_not_warn(tmp_path: Path) -> None:
+    store = WorkspaceStore(semantics_dir=tmp_path)
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        with store.open_named("pipeline_states") as session:
+            session.execute("CREATE TABLE IF NOT EXISTS demo(value INTEGER)")
+
+    assert caught == []
+
+
+def test_open_named_rejects_removed_legacy_store_kinds(tmp_path: Path) -> None:
+    store = WorkspaceStore(semantics_dir=tmp_path)
+
+    with pytest.raises(ValueError, match="Only 'pipeline_states' remains public"):
+        store.open_named("pipelines")
+
+
+def test_ephemeral_store_supports_basic_sql(tmp_path: Path) -> None:
+    store = WorkspaceStore(semantics_dir=tmp_path)
+    with store.open_ephemeral() as session:
+        session.execute("CREATE TABLE demo(value INTEGER)")
+        session.execute("INSERT INTO demo VALUES (7)")
+        row = session.fetch_one("SELECT value FROM demo")
+    assert row == (7,)