defmodule CMDCMemoryPg do
  @moduledoc """
  CMDC PostgreSQL backend — Checkpoint + EpisodicMemory 持久化。

  v0.1.0 **严控范围二件套**：

  1. **`CMDCMemoryPg.CheckpointBackend`** — 实现 `CMDC.Checkpoint.Backend` 4 callback,
     存储 Agent 会话快照到 `cmdc_checkpoints` 表
  2. **`CMDCMemoryPg.EpisodicMemoryBackend`** — 实现 `CMDC.Memory` 5 callback,
     按 user_id namespace 存储情景记忆到 `cmdc_episodic_memories` 表

  > **v0.1 明示不含**：pgvector 检索 / 3-tier Memory（Working / Semantic / Procedural）/
  > Composite 路由 / KV jsonb backend / Cloak encryption 强制集成。这些留 v0.2+
  > 实施。

  ## 安装

      defp deps do
        [
          {:cmdc, "~> 0.5"},
          {:cmdc_memory_pg, "~> 0.1"}
        ]
      end

  ## 配置

      # config/runtime.exs
      config :cmdc_memory_pg, CMDCMemoryPg.Repo,
        database: "cmdc_prod",
        username: System.fetch_env!("PGUSER"),
        password: System.fetch_env!("PGPASSWORD"),
        hostname: System.get_env("PGHOST", "localhost"),
        port: String.to_integer(System.get_env("PGPORT", "5432")),
        pool_size: 10

      # 启动应用 supervisor
      def start(_type, _args) do
        children = [
          CMDCMemoryPg.Repo
        ]

        Supervisor.start_link(children, strategy: :one_for_one)
      end

      # 启动后跑 migration
      $ mix ecto.migrate

      # 设为 CMDC.Checkpoint 默认 backend
      config :cmdc, :checkpoint_backend, CMDCMemoryPg.CheckpointBackend

  ## 与 Cloak 集成（可选 encryption at rest）

      def save(session_id, snapshot, opts) do
        sanitized = CMDC.Checkpoint.Snapshot.redact(snapshot, &MyApp.Vault.encrypt/1)
        # ... 写入 PG
      end

  详见 `CMDCMemoryPg.CheckpointBackend` moduledoc。
  """

  @doc "返回 cmdc_memory_pg 当前版本号。"
  @spec version() :: String.t()
  def version, do: Mix.Project.config()[:version] || "0.1.0"
end