corespine 0.0.1__tar.gz

corespine-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv (+ Python ${{ matrix.python-version }})
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (editable + dev)
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Typecheck (mypy --strict)
+        run: mypy
+
+      - name: Test (pytest)
+        run: pytest -q

corespine-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+*.pyc
+.pytest_cache/

corespine-0.0.1/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md — corespine(宪章)
+
+Spine 家族的 AI / 人类协作契约。先读家族 `../README.md` 与
+`../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md`,本文件是 corespine 的操作指南。
+
+## 这是什么
+
+**corespine —— Spine 家族的「薄」共享核**(ADR 0001 D3/D5)。只装 **domain-neutral 的底层原语**:
+那些**既不属于 RAG、也不属于 agent** 的稳定地基。它被 `ragspine` / `agentspine` 等兄弟包各自依赖,
+但**不**反向依赖任何一个,也**不**含任何它们的领域概念。
+
+## 宪章(不可违背)
+
+- **刻意地薄。** corespine 只放"极小且明显稳定"的原语。新增一块**必须先有证据**——
+  rule of three:当**两个以上**真实消费者都被证明在重复同一块稳定面,才把**恰好那块**提上来,
+  并记一条新 ADR。**痛了再抽,带着证据抽。** 不预先造大而全的框架。
+- **零领域泄漏。** 任何 RAG-特定(chunking / retrieval / anti-fabrication / provenance)或
+  agent-特定(MCP / A2A / 工具循环 / 编排)的代码**一律不准进**。判据:这段代码换到一个完全
+  不同的后端引擎里还成立吗?不成立就不属于 corespine。
+- **离线可跑、import-clean、零重依赖默认路径。** 核心只用标准库;真实后端(SDK / 数据库 / Redis)
+  经**可选 extra 延迟 import**,由各 app 在自己的缝里接,corespine 的 `dependencies` 永远为空。
+- **机制,不是保证。** corespine 只提供**机制**(conformance 基座、缝注册表、隐私 trace 形状);
+  具体**不变量由各 app 自己绑**(ADR 0001 D6)。这里不准出现任何具体业务不变量。
+
+## 缝的元模式(家族统一)
+
+每条缝都长一个样:**Protocol + 离线确定性默认 + `make_*` / Registry 工厂 + 参数化 conformance**。
+core 只 import Protocol,**绝不** import 任何 SDK。
+
+## 模块地图(按文件夹定位)
+
+```
+src/corespine/
+  seam/registry.py         Registry(name->factory) + make(spec) + entry-point 发现 + lazy_extra_import
+  observability/trace.py   TraceSink 协议 + InProcessPrivacyTraceSink(只记 code/计数/耗时,拒绝正文)
+  llm/provider.py          LLMProvider 协议 + 离线确定性 MockProvider
+  config/env.py            load_from_env:PREFIX_* env -> frozen dataclass(范式同 ragspine from_env)
+  queue/task_queue.py      TaskQueue 协议 + 同步内联 FakeQueue 默认
+  conformance/harness.py   ConformanceSuite × InvariantPack:实现 × 不变量 笛卡尔积(机制,无具体不变量)
+```
+
+## 跑(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q          # 期望 GREEN
+.venv/bin/python -c "import corespine"  # 期望 import-clean
+```
+
+## 约定
+
+- Python **3.10+** 类型注解;import 顺序 **stdlib > 三方 > 本地**;简体中文 docstring/注释,匹配家族风格。
+- **TDD**——测试即规格;**最小改动**——只改需求要求的部分。
+- **深层、按领域分组**的布局:文件路径先定位职责,再读文件名。

corespine-0.0.1/Makefile

@@ -0,0 +1,52 @@
+# corespine — 常用开发 / CI 命令。
+#
+# `make` 或 `make help` 列出全部目标。目标默认使用项目 venv(.venv);
+# 覆盖解释器:  make test PYTHON=python3.12
+#
+# 始终从包根运行。
+
+.DEFAULT_GOAL := help
+PYTHON ?= .venv/bin/python
+VENV   ?= .venv
+
+# ---- 环境 ----------------------------------------------------------------------------
+
+.PHONY: install
+install: ## 建 .venv(uv)并以 dev extra 可编辑安装(常规开发装法)
+	uv venv $(VENV)
+	VIRTUAL_ENV="$(CURDIR)/$(VENV)" uv pip install -e ".[dev]"
+
+# ---- 质量门 --------------------------------------------------------------------------
+
+.PHONY: ci
+ci: lint typecheck test ## 本地 CI 门:lint + 类型检查 + 测试(与 GitHub Actions 同形)
+
+.PHONY: test
+test: ## 跑测试套件
+	$(PYTHON) -m pytest -q
+
+.PHONY: lint
+lint: ## ruff 静态检查(风格 + import 顺序 + 死代码)
+	$(PYTHON) -m ruff check src tests
+
+.PHONY: typecheck
+typecheck: ## mypy --strict 类型检查(出货代码 src)
+	$(PYTHON) -m mypy
+
+.PHONY: fmt
+fmt: ## ruff 自动格式化(src / tests / examples)
+	$(PYTHON) -m ruff format src tests examples
+
+# ---- demo ----------------------------------------------------------------------------
+
+.PHONY: demo
+demo: ## 跑离线快速上手示例(期望末行 "corespine OK")
+	$(PYTHON) examples/quickstart.py
+
+# ---- meta ----------------------------------------------------------------------------
+
+.PHONY: help
+help: ## 列出可用目标
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| sort \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

corespine-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: corespine
+Version: 0.0.1
+Summary: Spine 家族的薄共享核:domain-neutral 底层原语(缝注册表 / observability / LLM 缝 / config / queue / conformance 基座)。
+Author: lin han
+License-Expression: Apache-2.0
+Keywords: conformance,framework-free,llm-provider,observability,offline,registry,seam,task-queue
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# corespine
+
+Spine 家族的**薄共享核**(见 [ADR 0001](../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md))。
+只装 **domain-neutral 的底层原语**——既不属于 RAG 也不属于 agent 的稳定地基,被 `ragspine` /
+`agentspine` 兄弟包各自依赖,**不**含任何它们的领域概念。
+
+> 刻意地薄。按证据(rule of three)增长,不预先造框架。详见 [`CLAUDE.md`](CLAUDE.md) 宪章。
+
+## 缝的元模式
+
+每条缝都长一个样,核心 import 零 SDK、离线可跑:
+
+**Protocol + 离线确定性默认 + `Registry` / `make_*` 工厂 + 参数化 conformance**
+
+## 里面有什么
+
+| 模块 | 原语 |
+|---|---|
+| `seam/registry.py` | `Registry`:name→factory 解析(大小写/留白/连字符不敏感)+ entry-point 自动发现(`corespine.<seam>` group)+ 未知 spec 列清可用名 + `lazy_extra_import`(缺 extra 给"pip install …"友好提示) |
+| `observability/trace.py` | `TraceSink` 协议 + `InProcessPrivacyTraceSink`:只记 code/计数/耗时,**拒绝**任何携带正文(answer/value/text/content…)的载荷 |
+| `llm/provider.py` | `LLMProvider` 协议 + 离线确定性 `MockProvider`(零网络、零 key、可复现) |
+| `config/env.py` | `load_from_env`:把 `PREFIX_*` 环境变量读进一个 frozen dataclass(范式同 ragspine `from_env`) |
+| `queue/task_queue.py` | `TaskQueue` 协议 + `FakeQueue`:同步内联执行 + 记录,离线/测试用 |
+| `conformance/harness.py` | `ConformanceSuite` × `InvariantPack`:把"实现 × 不变量"绑成笛卡尔积逐格执行(**机制**,具体不变量由各 app 自己绑) |
+
+## 本地开发(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -c "import corespine"
+```
+
+## 30 秒上手
+
+```python
+from corespine import Registry, MockProvider, InProcessPrivacyTraceSink, FakeQueue
+
+# 缝:一个 spec 选实现(大小写/留白不敏感;找不到列清可用名;还能 entry-point 自动发现)
+reg: Registry = Registry("llm")
+reg.register("mock", lambda **kw: MockProvider(**kw))
+provider = reg.make("  MOCK ")
+# OpenAI chat-completions 规范:messages 进,OpenAI 形状的 ChatCompletion 出(确定性可复现)
+out = provider.chat([{"role": "user", "content": "hello"}])
+print(out.choices[0].message.content)
+
+# 隐私 trace:只记元数据;塞正文会被直接拒绝(raise TraceError)
+sink = InProcessPrivacyTraceSink()
+sink.emit("retrieve", count=3, took_ms=12)
+
+# 任务队列:同步内联执行
+q = FakeQueue()
+jid = q.enqueue(lambda p: {"doubled": p["n"] * 2}, {"n": 21})
+print(q.get(jid).result)                 # {'doubled': 42}
+```

corespine-0.0.1/README.md

@@ -0,0 +1,56 @@
+# corespine
+
+Spine 家族的**薄共享核**(见 [ADR 0001](../docs/adr/0001-spine-family-boundaries-and-dependency-direction.md))。
+只装 **domain-neutral 的底层原语**——既不属于 RAG 也不属于 agent 的稳定地基,被 `ragspine` /
+`agentspine` 兄弟包各自依赖,**不**含任何它们的领域概念。
+
+> 刻意地薄。按证据(rule of three)增长,不预先造框架。详见 [`CLAUDE.md`](CLAUDE.md) 宪章。
+
+## 缝的元模式
+
+每条缝都长一个样,核心 import 零 SDK、离线可跑:
+
+**Protocol + 离线确定性默认 + `Registry` / `make_*` 工厂 + 参数化 conformance**
+
+## 里面有什么
+
+| 模块 | 原语 |
+|---|---|
+| `seam/registry.py` | `Registry`:name→factory 解析(大小写/留白/连字符不敏感)+ entry-point 自动发现(`corespine.<seam>` group)+ 未知 spec 列清可用名 + `lazy_extra_import`(缺 extra 给"pip install …"友好提示) |
+| `observability/trace.py` | `TraceSink` 协议 + `InProcessPrivacyTraceSink`:只记 code/计数/耗时,**拒绝**任何携带正文(answer/value/text/content…)的载荷 |
+| `llm/provider.py` | `LLMProvider` 协议 + 离线确定性 `MockProvider`(零网络、零 key、可复现) |
+| `config/env.py` | `load_from_env`:把 `PREFIX_*` 环境变量读进一个 frozen dataclass(范式同 ragspine `from_env`) |
+| `queue/task_queue.py` | `TaskQueue` 协议 + `FakeQueue`:同步内联执行 + 记录,离线/测试用 |
+| `conformance/harness.py` | `ConformanceSuite` × `InvariantPack`:把"实现 × 不变量"绑成笛卡尔积逐格执行(**机制**,具体不变量由各 app 自己绑) |
+
+## 本地开发(始终从包根)
+
+```bash
+uv venv .venv
+VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python -c "import corespine"
+```
+
+## 30 秒上手
+
+```python
+from corespine import Registry, MockProvider, InProcessPrivacyTraceSink, FakeQueue
+
+# 缝:一个 spec 选实现(大小写/留白不敏感;找不到列清可用名;还能 entry-point 自动发现)
+reg: Registry = Registry("llm")
+reg.register("mock", lambda **kw: MockProvider(**kw))
+provider = reg.make("  MOCK ")
+# OpenAI chat-completions 规范:messages 进,OpenAI 形状的 ChatCompletion 出(确定性可复现)
+out = provider.chat([{"role": "user", "content": "hello"}])
+print(out.choices[0].message.content)
+
+# 隐私 trace:只记元数据;塞正文会被直接拒绝(raise TraceError)
+sink = InProcessPrivacyTraceSink()
+sink.emit("retrieve", count=3, took_ms=12)
+
+# 任务队列:同步内联执行
+q = FakeQueue()
+jid = q.enqueue(lambda p: {"doubled": p["n"] * 2}, {"n": 21})
+print(q.get(jid).result)                 # {'doubled': 42}
+```

corespine-0.0.1/deploy/.dockerignore

@@ -0,0 +1,14 @@
+# 收窄构建上下文(上下文为仓库根)。Dockerfile 用显式 COPY,故镜像内容不依赖本文件;
+# 这里仅为减小上下文传输、加速构建。
+.git/
+.github/
+.venv/
+**/__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+deploy/

corespine-0.0.1/deploy/Dockerfile

@@ -0,0 +1,45 @@
+# corespine 可复现测试镜像 —— 多阶段、基于 uv。
+#
+# 一键容器:`docker build` 装好包 + dev,`docker run` 默认跑整套 pytest 自检。
+# 构建 / 运行命令见 deploy/README.md(构建上下文为仓库根)。
+
+# ---- builder:在独立 venv 里装入包 + dev ----------------------------------------------
+FROM python:3.12-slim AS builder
+
+# 从官方镜像拷入 uv 静态二进制(免装 pip,构建可复现)。
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+ENV UV_LINK_MODE=copy \
+    VIRTUAL_ENV=/opt/venv \
+    PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /app
+
+# 与宿主隔离的独立 venv。
+RUN uv venv /opt/venv
+
+# 先拷打包元数据 + 源码(可编辑安装需源码在场),再装 —— 与 `make install` 同形。
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN uv pip install -e ".[dev]"
+
+# ---- runtime:只带 venv + 跑测试 / demo 所需的源码 ------------------------------------
+FROM python:3.12-slim AS runtime
+
+ENV VIRTUAL_ENV=/opt/venv \
+    PATH="/opt/venv/bin:$PATH" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY --from=builder /opt/venv /opt/venv
+# 可编辑安装的 .pth 指向 /app/src,故运行阶段须保持同一绝对路径。
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY tests ./tests
+COPY examples ./examples
+
+# 默认 CMD:跑测试套件(一键自检)。
+# 改跑离线 demo:`docker run --rm corespine-test python examples/quickstart.py`
+CMD ["python", "-m", "pytest", "-q"]

corespine-0.0.1/deploy/README.md

@@ -0,0 +1,33 @@
+# deploy —— 一键测试容器
+
+一个多阶段、基于 uv 的可复现镜像:`docker build` 装好 `corespine` + dev 依赖,
+`docker run` 默认跑整套 `pytest` 自检。无需本机装 Python / uv。
+
+> 构建上下文是**仓库根**(`Dockerfile` 用显式 `COPY` 取 `pyproject.toml` / `README.md` /
+> `src` / `tests` / `examples`),`-f` 指到本目录的 Dockerfile。
+
+## 构建
+
+```bash
+# 从仓库根运行
+docker build -f deploy/Dockerfile -t corespine-test .
+```
+
+## 运行
+
+```bash
+# 默认 CMD:跑整套测试(一键自检)
+docker run --rm corespine-test
+
+# 改跑离线快速上手 demo(期望末行 "corespine OK")
+docker run --rm corespine-test python examples/quickstart.py
+```
+
+`docker build` + `docker run` 两条命令即完成"构建镜像 → 跑通测试套件"的一键闭环。
+
+## 说明
+
+- **多阶段**:builder 阶段在 `/opt/venv` 建独立 venv 并 `uv pip install -e ".[dev]"`;
+  runtime 阶段只拷该 venv 与跑测试所需源码,镜像更小。
+- 可编辑安装的链接指向 `/app/src`,故两个阶段都把源码放在同一绝对路径 `/app/src`。
+- `.dockerignore` 收窄上下文(加速构建);因 Dockerfile 用显式 `COPY`,镜像内容不依赖它。

corespine-0.0.1/docs/extending.md

@@ -0,0 +1,145 @@
+# 扩展 corespine(给消费者 / 第三方)
+
+> 本文是**操作指南**:第三方包如何在不改 corespine 一行代码的前提下,给某条缝补一个实现、
+> 接一个真实后端、绑自己的不变量。机制源码见 [`seam/registry.py`](../src/corespine/seam/registry.py)
+> 与 [`conformance/harness.py`](../src/corespine/conformance/harness.py);宪章见
+> [`../CLAUDE.md`](../CLAUDE.md),增长判据见 [`roadmap.md`](roadmap.md),现状见 [`prd.md`](prd.md)。
+
+corespine 只提供**机制**,扩展点全在缝上,三种方式互不耦合:
+
+| 扩展方式 | 解决什么 | 关键 API | 章节 |
+|---|---|---|---|
+| entry-point 扩展一条缝 | 第三方装包即被 `make` 发现,无需改核心 | `Registry.make` / group `corespine.<seam>` | [一](#一用-entry-point-扩展一条缝) |
+| 可选 extra + 延迟 import | 真实后端 SDK 只在选用时才 import,缺依赖给友好提示 | `lazy_extra_import` / `[project.optional-dependencies]` | [二](#二可选-extra-命名约定) |
+| 给一条缝绑 conformance 不变量 | app 用自己的不变量逮住坏实现 | `InvariantPack` / `ConformanceSuite` | [三](#三给一条缝绑-conformance-不变量) |
+
+## 一、用 entry-point 扩展一条缝
+
+每条缝是一个 `Registry("<seam>")` 实例;`make(spec)` 找不到内置名时,**回落到
+`importlib.metadata` 的 entry-point 自动发现**,group 命名固定为 **`corespine.<seam>`**。
+于是第三方只需在自己的 `pyproject.toml` 声明一个 entry point,**装包即扩展**,corespine
+核心一行不改。
+
+### 第三方包的 pyproject 片段
+
+假设某条缝叫 `vector_store`,你的包 `myadapter` 想注册一个名为 `pgvector` 的实现:
+
+```toml
+# myadapter/pyproject.toml
+[project.entry-points."corespine.vector_store"]
+# 名字(左) -> "模块:工厂可调用对象"(右);工厂签名为 (**kwargs) -> 实现实例
+pgvector = "myadapter.pg:make_pgvector"
+```
+
+```python
+# myadapter/pg.py
+def make_pgvector(**kwargs):
+    """工厂:返回一个实现该缝 Protocol 的实例(此处省略真实细节)。"""
+    return PgVectorStore(**kwargs)
+```
+
+### 装包后的调用示例
+
+```python
+from corespine import Registry
+
+# 同一条缝名 "vector_store" 必须与 entry-point group 后缀一致。
+registry: Registry = Registry("vector_store")
+
+# 内置名找不到 → 自动扫 group "corespine.vector_store" 发现 myadapter 的 pgvector。
+store = registry.make("pgvector", dsn="postgresql://...")
+
+# 解析大小写 / 连字符 / 留白不敏感:"PG-Vector" / " pgvector " 都解析到同一项。
+registry.names()  # 列出【内置 + entry-point 发现】的全部可用名(字典序、去重)
+```
+
+要点:
+
+- group 名**必须**是 `corespine.<seam>`,`<seam>` 与 `Registry("<seam>")` 的入参完全一致;
+- **内置注册优先于 entry-point**:同名时内置胜出(便于在测试里覆盖);
+- 发现是**延迟**的:只在 `make` / `names` 解析时才扫,不在 import 期付出代价;
+- 未知 spec 抛 `ValueError`,并**列清当前全部可用名**(绝不让人猜)。
+
+## 二、可选 extra 命名约定
+
+薄核宪章(ADR 0001 D5):核心 `dependencies` **永远为空**,默认路径零重依赖。真实后端的
+SDK(Redis / OpenAI / …)由各 app 在自己的缝里经**可选 extra** 声明,并用
+[`lazy_extra_import`](../src/corespine/seam/registry.py) **延迟 import** —— 选用该 adapter
+时才 import,没装就给出可直接照做的安装指引。
+
+### extra 命名约定
+
+| 约定 | 示例 | 说明 |
+|---|---|---|
+| 一个真实后端 → 一个 extra,**以后端命名** | `[redis]` / `[openai]` | 名字即"装哪个后端",直观可猜 |
+| extra 内只放该后端的 SDK | `redis = ["redis>=5"]` | 不夹带无关依赖,装得最小 |
+| `lazy_extra_import` 的 `extra=` 与之同名 | `extra="redis"` | 缺依赖时提示 `pip install <pkg>[redis]` 即可修 |
+
+```toml
+# 你的包 pyproject.toml:真实后端依赖声明为可选 extra(以后端命名)
+[project.optional-dependencies]
+redis = ["redis>=5"]
+openai = ["openai>=1.0"]
+```
+
+### lazy_extra_import 用法
+
+`lazy_extra_import(module, *, pkg, extra)` 把裸 `ImportError` 翻译成
+**"pip install <pkg>[<extra>]"** 的友好提示:
+
+```python
+from corespine import lazy_extra_import
+
+
+def make_redis_queue(**kwargs):
+    # 只在真正构造该 adapter 时才 import;没装 redis 不影响核心离线默认路径。
+    redis = lazy_extra_import("redis", pkg="myadapter", extra="redis")
+    client = redis.Redis(**kwargs)
+    return RedisQueue(client)
+```
+
+未装 `redis` 时调用 `make_redis_queue(...)` 会抛:
+
+```
+ImportError: 缺少可选依赖 'redis':请先 `pip install myadapter[redis]` 再重试。
+```
+
+—— 而不是让调用方对着 `ModuleNotFoundError: No module named 'redis'` 自己猜该装哪个 extra。
+
+## 三、给一条缝绑 conformance 不变量
+
+corespine 的 conformance 是**机制,非保证**:harness 只负责"跑 实现 × 不变量 的笛卡尔积 +
+报告哪个格子坏了",**具体不变量由各 app 自己绑**(ADR 0001 D6)。app 把自己的
+[`InvariantPack`](../src/corespine/conformance/harness.py) 喂进
+[`ConformanceSuite`](../src/corespine/conformance/harness.py) 即可。
+
+最小骨架(完整可跑范例见 [`../examples/conformance_usage.py`](../examples/conformance_usage.py)):
+
+```python
+from corespine import ConformanceSuite, InvariantPack
+
+# 1) 实现注册表:名字 -> 无参工厂(每格各新建实例,杜绝实现间状态串味)
+impls = {"counter": Counter, "broken": BrokenCounter}
+
+# 2) app 自己的不变量包(corespine 核心不含任何具体不变量)
+pack = (
+    InvariantPack("counter-contract")
+    .add("first-add-returns-n", lambda c: assert_eq(c.add(3), 3))
+    .add("accumulates", lambda c: assert_eq((c.add(2), c.add(5)), (2, 7)))
+)
+
+# 3) 绑成笛卡尔积,逐格跑
+suite = ConformanceSuite(impls, pack)
+for impl, invariant in suite.cases():
+    suite.check(impl, invariant)   # 失败即抛,定位到具体格子
+# 或:suite.run() 收集全部结果(不抛);suite.passed() 便捷判全过
+```
+
+要点:
+
+- 不变量 = `(实现实例) -> None`,**通过则正常返回、违反则抛异常**;只验外部可观测行为;
+- 每个格子都**新建实例**(工厂无参),杜绝实现间状态串味;
+- `cases()` 返回 `(实现名, 不变量名)` 列表,可直接喂 `pytest.mark.parametrize`;
+  `ids()` 给对齐的可读 id(形如 `impl/invariant`);
+- 这正是"敢放手让第三方填广度、却让脊柱不变量烂不掉"的落点:没过 conformance 的实现直接
+  CI 红,而非生产事故。

corespine-0.0.1/docs/prd.md

@@ -0,0 +1,70 @@
+# corespine PRD(现状与待做)
+
+> 本文记**现状清单 + 可执行的待做 backlog**;**方向与增长判据**见
+> [`roadmap.md`](roadmap.md),宪章见 [`../CLAUDE.md`](../CLAUDE.md)。
+> corespine 刻意地薄:多数"待做"被**有意推迟**,需满足 rule of three 才动手(见 roadmap 五问)。
+
+## 现状(已完成)
+
+六条缝 + errors 缝均已落地,各带 Protocol + 离线确定性默认 + 工厂 + 参数化 conformance;
+`make ci` 全绿(ruff + pytest)、import-clean、核心 `dependencies` 为空。
+
+| 缝 | 公开面 | 离线默认 | 状态 |
+|---|---|---|---|
+| seam/registry | `Registry` / `lazy_extra_import` | 内置注册 + entry-point 发现 | ✅ |
+| observability/trace | `TraceSink` / `TraceEvent` / `TraceError` / `FORBIDDEN_KEYS` | `InProcessPrivacyTraceSink`(拒正文) | ✅ |
+| llm/provider | `LLMProvider.chat`(OpenAI chat-completions 规范:messages+tools 进、`ChatCompletion` 出) | `MockProvider`(确定性,OpenAI 形状) | ✅ |
+| config/env | `load_from_env` / `env_key` | env→frozen dataclass(含 `X\|None`) | ✅ |
+| queue/task_queue | `TaskQueue` / `JobStatus` | `FakeQueue`(同步内联) | ✅ |
+| conformance/harness | `ConformanceSuite` / `InvariantPack` / `CaseResult` + `parametrize_kwargs` | 实现×不变量笛卡尔积 | ✅ |
+| errors | `CorespineError` / `error_to_dict` / `ConfigError` / `SeamError` | 统一基类 + 任意异常归一 dict | ✅ |
+
+测试覆盖含:解析归一、entry-point 发现、**内置优先于 entry-point**、未知名报错、缺 extra 友好提示、
+trace 拒正文、Mock 确定性、env 类型转换 / 可选 / 缺失校验、queue 终态 / 幂等、conformance 笛卡尔积、
+errors 基类 code / retryable / 归一 dict。`TraceError` 已改继承 `CorespineError`(code=`trace.forbidden`),
+家族异常统一基类。
+
+## 待做 backlog
+
+### A. 可立即做(纯增量,不需新证据,charter-safe)
+
+A 类已全部落地(✅),示例 / 文档见 `examples/` 与 `docs/`:
+
+| # | 项 | 内容 | 落点 | 状态 |
+|---|---|---|---|---|
+| A1 | entry-point 端到端示例 | 一个"第三方装包即扩展"的最小可跑 demo + 文档(`pyproject` entry-points → `Registry.make` 发现) | example / 文档 | ✅ |
+| A2 | 可选 extra 范式文档 | 把 `[redis]`/`[openai]` 等 extra 命名约定 + `lazy_extra_import` 用法写成一页 | 文档 | ✅ |
+| A3 | conformance 使用范例 | 展示 app 如何用 `InvariantPack` 给某缝绑自己的不变量(机制示范,不含具体业务不变量) | example / 文档 | ✅ |
+
+### B. 待证据(rule of three:≥2 个真实消费者重复同一稳定面才动)
+
+> **watch list(单一消费者证据,暂不实现):** `import_string`(字符串→对象解析)、
+> PEP 562 惰性子模块、并行 fan-out 执行器、资源限额——目前仅一个消费者出现过,证据不足
+> rule of three,只观察不动手。方向口径见 [`roadmap.md`](roadmap.md) 增长五问。
+
+| # | 项 | 触发条件 | 落点 | 状态 |
+|---|---|---|---|---|
+| B1 | trace 真实 sink(OTel 等) | ≥2 app 需要导出 trace | 可选 extra / contrib,**不进核心默认路径** | 待证据 |
+| B2 | llm streaming / 批量 / token 计量 | ≥2 app 在缝上重复同一形状 | 先扩 Protocol(最小),实现走 extra | 待证据 |
+| B3 | queue 真实后端 adapter(RQ/Celery)+ 重试/延迟 | ≥2 app 接同一类后端 | adapter 走 extra/contrib;协议扩不扩看证据 | 待证据 |
+| B4 | conformance × pytest 集成助手 | ragspine + agentspine 都在重复 `cases()`→`parametrize` 胶水 | `harness.parametrize_kwargs`(纯标准库胶水,不把 pytest 引进核心) | ✅ |
+| B5 | config 扩展转型(list / enum / 嵌套) | 出现真实通用配置项需要 | 核心(仅当确为通用) | 待证据 |
+| B6 | 统一异常基类 `CorespineError` | 多个 app 需统一 `catch` corespine 错误 | 核心(`errors.py`:基类 + `error_to_dict` + `ConfigError`/`SeamError`) | ✅ |
+| B7 | 稳定性契约(公开面冻结 / SemVer / deprecation) | 出现依赖其稳定性的外部消费者 | 流程 + 文档 | 待证据 |
+
+### C. 家族前置(最重要,解锁 B 类证据)
+
+| # | 项 | 说明 |
+|---|---|---|
+| C1 | ragspine / agentspine 真正依赖 corespine | rule-of-three 证据的**唯一来源**;在此之前 B 类多数不该动 |
+| C2 | 跨包 conformance 验证 | 多 app 各绑不变量时,验证现有机制是否够用,反推增强 |
+
+## 不做(护栏)
+
+RAG-/agent-特定概念(chunking / retrieval / provenance;MCP / A2A / 工具循环 / 编排)、
+预造框架、核心非空依赖、把具体业务不变量写进核心。详见 roadmap「明确不做」。
+
+## 跟踪
+
+- 每落一项 → 在家族 `docs/adr/` 记一条 ADR(编号接 0001),并回填本表状态。
+- A 类可随时排期;B 类须先在 PR / ADR 里附上"≥2 消费者重复"的证据;C 类是 B 类的前置。