storepy 3.0.0__tar.gz → 3.2.0__tar.gz

{storepy-3.0.0/src/storepy.egg-info → storepy-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 3.0.0
+Version: 3.2.0
 Summary: Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control
 Author-email: leo <coen_ddt@qq.com>
 License-Expression: MIT
@@ -24,7 +24,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pymongo>=4.9
-Requires-Dist: rust-store-py<4.0.0,>=3.0.0
+Requires-Dist: rust-store-py<4.0.0,>=3.2.0
 Provides-Extra: mysql
 Requires-Dist: asyncmy>=0.2.9; extra == "mysql"
 Provides-Extra: postgres

{storepy-3.0.0 → storepy-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "storepy"
-version = "3.0.0"
+version = "3.2.0"
 description = "Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,7 +25,7 @@ authors = [
 ]
 dependencies = [
   "pymongo>=4.9",
-  "rust-store-py>=3.0.0,<4.0.0",
+  "rust-store-py>=3.2.0,<4.0.0",
 ]
 classifiers = [
   "Development Status :: 4 - Beta",

{storepy-3.0.0 → storepy-3.2.0}/src/py_store/__init__.py

@@ -30,6 +30,7 @@ from . import (
     datasource,
     ddl,
     feedback,
+    metadef,
     permission,
     schema,
     workflow,
@@ -195,10 +196,64 @@ class Store:
         """从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6）"""
         return ddl.generate(backend, names)
 
+    # ── meta-store 定义控制面（定义持久化与版本化；见 metadef.py）──
+    async def persistDef(self, defn: dict, opts: dict | None = None) -> dict:
+        """持久化定义（同名同形幂等，异形 version+1；A1/A2）"""
+        return await metadef.persist_def(self, defn, opts)
+
+    async def listDefs(self, opts: dict | None = None) -> list[dict]:
+        """列定义行（按 version desc；name 缺省列全部）"""
+        return await metadef.list_defs(self, opts or {})
+
+    async def loadDefs(self, opts: dict | None = None) -> list[dict]:
+        """各 name 的最新 active 行"""
+        return await metadef.load_defs(self, opts or {})
+
+    async def restoreDefs(self, opts: dict | None = None) -> dict:
+        """从持久化定义重建注册表：schema + workflow 两类（网关 reload 重装配前调用）"""
+        base = opts or {}
+        s = await metadef.restore_defs(self, {**base, 'kind': 'schema'})
+        w = await metadef.restore_defs(self, {**base, 'kind': 'workflow'})
+        return {'total': s['total'] + w['total'], 'applied': s['applied'] + w['applied']}
+
+    async def rollbackTo(self, opts: dict) -> dict:
+        """回滚到历史版本（追加式，重新 register 该版本 defn）"""
+        return await metadef.rollback_to(self, opts)
+
+    # 定义控制面：workflow 定义（kind=workflow；见 metadef.py）
+    async def persistWorkflowDef(self, defn: dict, opts: dict | None = None) -> dict:
+        """持久化 workflow 定义（同名同形幂等，异形 version+1）"""
+        return await metadef.persist_def(self, defn, {**(opts or {}), 'kind': 'workflow'})
+
+    async def listWorkflowDefs(self, opts: dict | None = None) -> list[dict]:
+        """列 workflow 定义行（按 version desc；name 缺省列全部）"""
+        return await metadef.list_defs(self, {**(opts or {}), 'kind': 'workflow'})
+
+    async def loadWorkflowDefs(self, opts: dict | None = None) -> list[dict]:
+        """各 name 的最新 active workflow 定义行"""
+        return await metadef.load_defs(self, {**(opts or {}), 'kind': 'workflow'})
+
+    async def rollbackWorkflowTo(self, opts: dict) -> dict:
+        """回滚 workflow 定义到历史版本（追加式）"""
+        return await metadef.rollback_to(self, {**(opts or {}), 'kind': 'workflow'})
+
+    def ensureBuiltins(self) -> None:
+        """自举内建定义表 __schemaDef/__workflowDef（幂等）"""
+        return metadef.ensure_builtins()
+
+    # ── 反馈事件落库（A6；见 feedback.py）──
+    def enableFeedbackTable(self):
+        """一键接线：注册内建 __feedback 并把 sink 指向落库；返回 disposer（恢复原 sink）"""
+        return feedback.enable_feedback_table(self)
+
+    def setFeedbackMeta(self, tenant: str = '', env: str = '') -> None:
+        """注入进程级 ns 标签（tenant/env），供落库事件附加（进程级隔离下天然单 ns）"""
+        feedback.set_meta({'tenant': tenant, 'env': env})
+
     # ── 工作流编排（首批：线性 + when 守卫 + fail-fast；见 workflow.py 与设计文档）──
-    def registerWorkflow(self, defn: dict) -> dict:
-        """注册工作流定义（注册即静态校验，白名单外显式 Err 含 WORKFLOW_UNSUPPORTED）"""
-        return workflow.register(defn)
+    def registerWorkflow(self, defn: dict, ctx: dict | None = None) -> dict:
+        """注册工作流定义（可选 ``ctx`` 过定义层门禁；默认 Open。白名单外显式 Err 含 WORKFLOW_UNSUPPORTED）"""
+        return workflow.register(defn, ctx)
 
     def workflows(self, ctx: dict | None = None) -> list[str]:
         """全部可见工作流名（read 白名单过滤）"""
@@ -239,6 +294,19 @@ class Store:
     register_workflow = registerWorkflow
     run_workflow = runWorkflow
     get_workflow = getWorkflow
+    # 定义控制面（蛇形别名与上方驼峰同实现）
+    persist_def = persistDef
+    list_defs = listDefs
+    load_defs = loadDefs
+    restore_defs = restoreDefs
+    rollback_to = rollbackTo
+    persist_workflow_def = persistWorkflowDef
+    list_workflow_defs = listWorkflowDefs
+    load_workflow_defs = loadWorkflowDefs
+    rollback_workflow_to = rollbackWorkflowTo
+    ensure_builtins = ensureBuiltins
+    enable_feedback_table = enableFeedbackTable
+    set_feedback_meta = setFeedbackMeta
 
     # ── 其余 API 显式绑定（staticmethod：避免实例化后 self 注入）──
     # Schema 管理
@@ -288,6 +356,9 @@ class Store:
     set_deny_write_roles = staticmethod(permission.set_deny_write_roles)
     setUnconfiguredPolicy = staticmethod(permission.set_unconfigured_policy)
     set_unconfigured_policy = staticmethod(permission.set_unconfigured_policy)
+    # 定义层门禁策略（判决唯一在 core）：closed 时仅 internal/白名单可注册或覆盖
+    setMetaPolicy = staticmethod(schema.set_meta_policy)
+    set_meta_policy = staticmethod(schema.set_meta_policy)
     # 查询档位（判决唯一在 core）：standard 默认放开 / text2query 功能收缩
     # 进入档即等效强制 ctx；未知档由 core 抛 ValueError 上抛（禁静默回落默认档）
     setProfile = staticmethod(schema.set_profile)

storepy-3.2.0/src/py_store/feedback.py

@@ -0,0 +1,102 @@
+"""反馈事件通道 —— 兜底/降级/拦截触发的统一出口
+
+事件形状（对齐 rust-store 联邦 degraded 契约）::
+
+    {type, code, layer, message, hint, ...}
+      - type  : 事件类别（federation_degraded / sql_pushdown_unsupported ...）
+      - code  : 机器可读代码（crossSourceSort / pushdownUnsupported ...）
+      - layer : 命中的防护层（federation / dialect ...）
+      - message: 人可读描述
+      - hint  : 修复指引（供上游排查/加固）
+
+默认无 sink 时打 stderr（向后兼容）；宿主可 ``set_sink(fn)`` 接管，
+接入自动反馈闭环（允许被拦截，禁止静默失守）。
+"""
+
+import asyncio
+import sys
+import time
+
+_sink = None
+
+# 进程级 ns 标签（进程级隔离下天然单 ns；由宿主 set_meta 注入）
+_meta = {'tenant': '', 'env': ''}
+
+# 落库失败累计计数（进程级；>0 表示有事件未入表——可观测，不静默）
+_fail_count = 0
+
+
+def get_sink():
+    """当前 sink（None = 默认 stderr 行为）；供接管方保存原值、退出时恢复（token-set/reset 同构）"""
+    return _sink
+
+
+def set_sink(fn):
+    """注册反馈事件回调 ``fn(event: dict)``；传 None 恢复默认 stderr 行为"""
+    global _sink
+    _sink = fn
+
+
+def set_meta(meta):
+    """注入进程级 ns 标签（tenant/env），供落库 sink 附加到事件"""
+    global _meta
+    _meta = {**_meta, **(meta or {})}
+
+
+def fail_count():
+    """落库失败累计计数（进程级；>0 表示有事件未入表——可观测，不静默）"""
+    return _fail_count
+
+
+def _fail(msg):
+    global _fail_count
+    _fail_count += 1
+    print(f'[py-store][feedback] {msg}', file=sys.stderr)
+
+
+async def _write_feedback(store, row):
+    """落库（internal 上下文——__feedback write 空名单仅放行 internal/admin）；失败不静默、不抛回 emit"""
+    from . import metadef as _metadef
+    try:
+        with _metadef._internal_ctx():
+            await store.insert('__feedback', row)
+    except Exception as e:  # 落库失败：stderr + 计数，绝不抛回 emit（不破坏主链路）
+        _fail(f'__feedback 落库失败: {e}')
+
+
+def enable_feedback_table(store):
+    """一键接线：注册内建 ``__feedback`` 并把 sink 指向落库；返回 disposer（恢复原 sink）
+
+    落库为异步 fire-and-forget（有运行中事件循环时 ``create_task``）；失败走 stderr + 计数，
+    绝不抛回 ``emit``。未调用本函数时 ``emit`` 保持原 stderr 行为（不改变默认语义）。
+    """
+    from . import metadef as _metadef
+    _metadef.ensure_builtins()  # 幂等（含 __feedback）
+    prev = get_sink()
+
+    def _sink(event):
+        row = {**(event or {}), 'tenant': _meta.get('tenant', ''),
+               'env': _meta.get('env', ''), 'now': int(time.time() * 1000)}
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+        if loop is not None:
+            loop.create_task(_write_feedback(store, row))
+        else:
+            _fail('无运行中事件循环，__feedback 事件未落库')
+
+    set_sink(_sink)
+    return lambda: set_sink(prev)
+
+
+def emit(event):
+    """产出一条反馈事件：有 sink 回调之；否则打印 stderr（允许拦截，禁止静默）"""
+    if _sink is not None:
+        _sink(event)
+        return
+    print(
+        f"[py-store][{event.get('layer', '?')}/{event.get('code', '?')}] "
+        f"{event.get('message', '')}（hint: {event.get('hint', '-')}）",
+        file=sys.stderr,
+    )

storepy-3.2.0/src/py_store/metadef.py

@@ -0,0 +1,272 @@
+"""meta-store 定义持久化与版本化（宿主层；core 无 IO 铁律）
+
+设计见 doc/execution/2026/10/meta-store定义控制面-01（A1/A2/A3）。三条契约：
+  - 定义落库为内建 schema ``__schemaDef``（tenant/env/name/version/defn 五要素）；
+  - 同名同形幂等不新增行，异形 version+1；
+  - 版本历史可列（append-only），``rollbackTo`` 以历史 defn **追加新版本**（跨进程经 ``restore_defs`` 对协议面可见）。
+
+对齐 ``nodejs-store/src/metadef.js``（双宿主流库行内容逐字节一致由对拍脚本守护）。
+存储是 IO，故落宿主层，core 零改动。
+"""
+
+import json
+from contextlib import contextmanager
+
+from . import permission as _permission
+from .schema import _to_core_defn
+from .schema import has as _schema_has
+from .schema import register as _schema_register
+from .workflow import register as _register_workflow
+
+# 内建定义表名（``__`` 前缀为内建保留名，对齐 workflow 的 name.startswith('__') 校验）
+_SCHEMA_DEF = '__schemaDef'
+_WORKFLOW_DEF = '__workflowDef'
+_FEEDBACK = '__feedback'
+# 读取投影（双端一致；对拍比较用）
+_DEF_FIELDS = '_id, tenant, env, name, version, defn, status, createdBy'
+
+# 定义类型（kind）→ 内建表名 / 注册函数（缺省 schema，保既有调用零变更）
+_TABLES = {'schema': _SCHEMA_DEF, 'workflow': _WORKFLOW_DEF}
+# 注册函数：(defn, internal) → 注册到对应注册表；internal 仅供系统重建（restore）使用
+_REGISTRARS = {
+    'schema': lambda defn, internal=False: _schema_register(defn, {'internal': True} if internal else None),
+    'workflow': lambda defn, internal=False: _register_workflow(defn, {'internal': True} if internal else None),
+}
+
+
+def _kind_of(opts):
+    """解析 kind → ``(kind, table)``；未知 kind 显式 Err（不兜底）"""
+    kind = (opts or {}).get('kind') or 'schema'
+    table = _TABLES.get(kind)
+    if not table:
+        raise MetaDefError(f'metadef: 未知定义类型 {kind!r}')
+    return kind, table
+
+
+def _def_model(name, id_prefix):
+    """内建定义表 schema（write 显式空名单：普通角色禁写，防篡改定义审计）
+
+    不声明 indexes：内建表随宿主注册表进入 `ddl.generate()`，而场景 harness 会对全部
+    注册表执行其中的 CREATE INDEX（建表仅限业务表）——为内建表加索引会令其对未建的
+    内建表建索引而报错。版本唯一性改由行自然键 ``_id``（见 ``def_id``，D2）在**存储层**
+    保证：并发写同版本必触发唯一键冲突，按 §4.4 显式上抛（不重试、不吞）。
+    """
+    return {
+        'name': name,
+        'system': True,
+        'collection': name,
+        'idPrefix': id_prefix,
+        'write': [],
+        'fields': {
+            '_id': {'type': 'string'},
+            'tenant': {'type': 'string'},
+            'env': {'type': 'string'},
+            'name': {'type': 'string'},
+            'version': {'type': 'int'},
+            'defn': {'type': 'object'},
+            'status': {'type': 'string'},
+            'createdBy': {'type': 'string'},
+        },
+    }
+
+
+_SCHEMA_DEF_MODEL = _def_model(_SCHEMA_DEF, 'sdef')
+_WORKFLOW_DEF_MODEL = _def_model(_WORKFLOW_DEF, 'wdef')
+
+# 内建反馈事件表（05）：承载结构化降级/拦截事件（write 空名单——普通角色禁写，事件审计）
+_FEEDBACK_MODEL = {
+    'name': _FEEDBACK,
+    'system': True,
+    'collection': _FEEDBACK,
+    'idPrefix': 'fdbk',
+    'write': [],
+    'fields': {
+        '_id': {'type': 'string'},
+        'type': {'type': 'string'},
+        'code': {'type': 'string'},
+        'layer': {'type': 'string'},
+        'message': {'type': 'string'},
+        'hint': {'type': 'string'},
+        'tenant': {'type': 'string'},
+        'env': {'type': 'string'},
+        'now': {'type': 'number'},
+    },
+}
+
+
+def ensure_builtins():
+    """注册内建 ``__schemaDef``/``__workflowDef``/``__feedback``（幂等；core 对重复三元组显式报错，故先 has 守卫）"""
+    if not _schema_has(_SCHEMA_DEF):
+        _schema_register(_SCHEMA_DEF_MODEL)
+    if not _schema_has(_WORKFLOW_DEF):
+        _schema_register(_WORKFLOW_DEF_MODEL)
+    if not _schema_has(_FEEDBACK):
+        _schema_register(_FEEDBACK_MODEL)
+
+
+class MetaDefError(ValueError):
+    """metadef 契约失败（defn.name 缺失 / 版本不存在 / 唯一冲突）"""
+
+
+# ─── 纯逻辑（双端逐字节等价；parity 锚） ───────────────────────
+
+def stable_stringify(value):
+    """稳定序列化（键序无关）：与 node ``_stableStringify`` 逐字节等价"""
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
+
+
+def same_defn(a, b):
+    """两 defn 是否同形（深比较；键序无关）"""
+    return stable_stringify(a) == stable_stringify(b)
+
+
+def next_version(rows):
+    """由既有行推下一个版本号（无行 → 1）"""
+    return (max(r['version'] for r in rows) + 1) if rows else 1
+
+
+def build_def_row(defn, opts, version):
+    """构造待插入行（纯函数，便于双端对拍）。键序与 node ``buildDefRow`` 一致"""
+    opts = opts or {}
+    return {
+        'tenant': opts.get('tenant'),
+        'env': opts.get('env'),
+        'name': defn['name'],
+        'version': version,
+        'defn': defn,
+        'status': 'active',
+        'createdBy': opts.get('actor') or '',
+    }
+
+
+def def_id(tenant, env, name, version):
+    """定义行自然键 ``_id`` = ``(tenant, env, name, version)``（D2；对齐 node ``defId``）。
+
+    作为存储层主键，同 ``(tenant,env,name,version)`` 二次写入必触发唯一键冲突
+    （SQLite UNIQUE / Mongo E11000），使「读最新行 +1」的并发窗口在存储层收口 ——
+    并发写同版本时后到者显式报错（控制面映射 409 CONFLICT），不产重复 version。
+    分隔符用 US（``\\u001f``）：schema name 不含该控制字符，拼接无歧义。
+    """
+    t = '' if tenant is None else str(tenant)
+    e = '' if env is None else str(env)
+    return f'{t}\u001f{e}\u001f{name}\u001f{version}'
+
+
+@contextmanager
+def _internal_ctx():
+    """干净 internal 上下文（{internal: True}，丢弃触发者 roles）
+
+    内建表 write 显式空名单仅放行 internal/admin；写入身份与触发者权限解耦，
+    对齐 ``workflow._internal_ctx`` 的 __workflowRun 写入约束。
+    """
+    token = _permission._ctx.set({'internal': True})
+    try:
+        yield
+    finally:
+        _permission._ctx.reset(token)
+
+
+# ─── IO（经传入的 store 面，避免包内循环依赖） ─────────────────
+
+async def list_defs(store, opts):
+    """列定义行（按 version desc；name 缺省列全部）"""
+    opts = opts or {}
+    _, table = _kind_of(opts)
+    condition = {'tenant': opts.get('tenant'), 'env': opts.get('env')}
+    if opts.get('name') is not None:
+        condition['name'] = opts['name']
+    gql = f'{table}($condition:@c0, $sort:@s0){{{_DEF_FIELDS}}}'
+    return await store.query(gql, {'c0': condition, 's0': {'version': -1}})
+
+
+async def load_defs(store, opts):
+    """各 name 的**最新 active** 行（每 name 取 version 最大者；version desc 后首见即最新）"""
+    opts = opts or {}
+    _, table = _kind_of(opts)
+    gql = f'{table}($condition:@c0, $sort:@s0){{{_DEF_FIELDS}}}'
+    rows = await store.query(gql, {
+        'c0': {'tenant': opts.get('tenant'), 'env': opts.get('env'), 'status': 'active'},
+        's0': {'version': -1},
+    })
+    out = []
+    seen = set()
+    for r in rows:
+        if r.get('name') in seen:
+            continue
+        seen.add(r['name'])
+        out.append(r)
+    return out
+
+
+async def persist_def(store, defn, opts):
+    """持久化定义：同名同形返回原行不插入；异形插入 version+1"""
+    if not isinstance(defn, dict) or not defn.get('name'):
+        raise MetaDefError('metadef: defn.name 必填')
+    opts = opts or {}
+    _, table = _kind_of(opts)
+    name = defn['name']
+    rows = await list_defs(store, {'tenant': opts.get('tenant'), 'env': opts.get('env'),
+                                   'name': name, 'kind': opts.get('kind')})
+    latest = rows[0] if rows else None
+    core_defn = _to_core_defn(defn)  # 函数值剔除（纯 JSON 入库，A3 前提）
+    if latest is not None and same_defn(latest.get('defn'), core_defn):
+        return latest
+    version = next_version(rows)
+    row = build_def_row(core_defn, opts, version)
+    # 自然键 `_id`（D2）：同版本并发写必冲突 → 存储层保证 version 唯一
+    row['_id'] = def_id(opts.get('tenant'), opts.get('env'), core_defn['name'], version)
+    with _internal_ctx():
+        return await store.insert(table, row)
+
+
+# 已重建进注册表的定义自然键（进程级；同名同版本只注册一次，避免每次 reload 全量覆盖）
+_applied: set = set()
+
+
+async def restore_defs(store, opts):
+    """从持久化定义重建注册表（D1 闭环桥）：``load_defs`` → 逐条 ``register(defn, internal)``。
+
+    网关 reload 在重装配前调用本函数，使「控制面 publish（写库）」与「协议面可见（注册）」
+    经 reload 衔接。已注册过的同版本跳过（幂等）；版本变化时以新 defn 覆盖注册。
+    注册走 internal 上下文：属系统重建动作，不受业务定义层门禁（MetaPolicy）影响。
+    返回 ``{'total': 库内最新 active 行数, 'applied': 本次新注册数}``。
+    """
+    opts = opts or {}
+    kind, _ = _kind_of(opts)
+    rows = await load_defs(store, opts)
+    applied = 0
+    for r in rows:
+        key = f"{kind}\u001f{def_id(opts.get('tenant'), opts.get('env'), r['name'], r['version'])}"
+        if key in _applied:
+            continue
+        _REGISTRARS[kind](r['defn'], True)
+        _applied.add(key)
+        applied += 1
+    return {'total': len(rows), 'applied': applied}
+
+
+async def rollback_to(store, opts):
+    """回滚到历史版本（追加式）：取历史行 defn → 作为新版本再发布 → 本进程 register → 返回落库行。
+
+    D21 跨进程闭环：回滚不再「原地重注册」，而是复用 ``persist_def`` 把历史 defn 落成一条
+    **新版本行**（同名同形幂等 → 返回当前最新行）。``load_defs`` 取「最新 active」故必然返回
+    该行，网关 ``restore_defs`` hydrate 即按回滚后的 defn 装配 —— 回滚对协议面可见。
+    历史保持 append-only：目标历史行不被改写。
+    """
+    opts = opts or {}
+    kind, _ = _kind_of(opts)
+    rows = await list_defs(store, {'tenant': opts.get('tenant'), 'env': opts.get('env'),
+                                   'name': opts.get('name'), 'kind': opts.get('kind')})
+    version = opts.get('version')
+    row = next((r for r in rows if r.get('version') == version), None)
+    if row is None:
+        raise MetaDefError(f"metadef: 版本不存在 {opts.get('name')}@{version}")
+    # 追加式回滚：以历史 defn 走 persist 语义（异形 → version+1；同形 → 返回当前最新）
+    persisted = await persist_def(store, row['defn'], opts)
+    # 系统重建动作：workflow 走 internal；schema 维持既有调用形态（False = 无 ctx，门禁行为零变更）
+    _REGISTRARS[kind](row['defn'], kind == 'workflow')
+    return persisted
+
+
+# 模块导入即自举内建定义表（幂等；零配置）
+ensure_builtins()

{storepy-3.0.0 → storepy-3.2.0}/src/py_store/schema.py

@@ -77,15 +77,19 @@ def _to_core_defn(defn):
     return walk(defn)
 
 
-def register(defn):
+def register(defn, ctx=None):
     """注册一个 schema（core 注册 + Host 侧元数据镜像）
 
+    ``ctx``：可选定义层门禁上下文（``{'userId','roles',...}`` 或 ``{'internal': True}``）。
+    返回 ``None`` 兼容既有调用；门禁策略由 ``set_meta_policy`` 配置，默认 Open（全放行）。
+    判决唯一在 core（拒绝抛 ``ERR_PERMISSION:`` 前缀错误，定义不变）。
+
     归档表 `<Name>Deleted` 由 core 在 register 内**自动派生并注册**
-    （rust-store/core/src/schema/registry.rs:52-55）；Host 只补 Host 侧镜像，
+    （rust-store/core/src/schema/registry.rs）；Host 只补 Host 侧镜像，
     **不再调用 core.register** —— 否则同名条目二次进入 core.order，使 list()/
     generate_ddl() 出现重复表（基线实测 list=['User','UserDeleted','UserDeleted']）。
     """
-    core.register(_to_core_defn(defn))
+    core.register_with_ctx(_to_core_defn(defn), ctx)
 
     # 计算列回调：fn → core 回调桥；asyncFn → Host 侧映射
     computes = {}
@@ -228,6 +232,14 @@ def set_unconfigured_policy(policy):
     core.set_unconfigured_policy(policy)
 
 
+def set_meta_policy(closed, roles):
+    """定义层门禁策略：`closed=True` 时仅 internal 或 `roles` 白名单可注册/覆盖。
+
+    判决唯一在 core；默认 Open（`register` 无 ctx 亦放行，保既有兼容）。
+    """
+    core.set_meta_policy(bool(closed), roles)
+
+
 def require_context():
     """「上下文强制」开关当前值"""
     return core.require_context()

{storepy-3.0.0 → storepy-3.2.0}/src/py_store/workflow.py

@@ -300,12 +300,20 @@ def _validate_when(when, errors, where):
 _workflows: dict = {}
 
 
-def register(defn):
+def register(defn, ctx=None):
     """注册工作流定义（注册即静态校验，白名单外显式 Err；name 全局唯一）。
 
+    ``ctx``：可选定义层门禁上下文（``{'internal': True}`` / ``{'roles': [...]}``）。
+    判决唯一在 core（``_core.can_register``，与 ``schema.register`` 同一 MetaPolicy）；
+    默认 Open → 全放行。Closed 且 ctx 不过 → 抛 ``ERR_PERMISSION:``（定义不写入）。
+
     同名同形重复注册幂等通过（对齐 core schema.register 的复跑语义——场景 harness
     每后端复跑同一批用例时必须可重入）；同名异形显式 Err（禁止静默覆盖已注册定义）。
     """
+    # 定义层门禁：判决先于静态校验（拒绝即返回，零副作用；与 schema.register 同序）
+    if not _core.can_register(ctx):
+        name = defn.get('name') if isinstance(defn, dict) else ''
+        raise WorkflowError(f'ERR_PERMISSION: 无权注册或覆盖工作流定义 {name or ""}')
     errors = validate_defn(defn)
     if errors:
         raise WorkflowError('WORKFLOW_UNSUPPORTED: ' + '；'.join(errors))

{storepy-3.0.0 → storepy-3.2.0/src/storepy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 3.0.0
+Version: 3.2.0
 Summary: Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control
 Author-email: leo <coen_ddt@qq.com>
 License-Expression: MIT
@@ -24,7 +24,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pymongo>=4.9
-Requires-Dist: rust-store-py<4.0.0,>=3.0.0
+Requires-Dist: rust-store-py<4.0.0,>=3.2.0
 Provides-Extra: mysql
 Requires-Dist: asyncmy>=0.2.9; extra == "mysql"
 Provides-Extra: postgres

{storepy-3.0.0 → storepy-3.2.0}/src/storepy.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/py_store/datasource.py
 src/py_store/ddl.py
 src/py_store/feedback.py
 src/py_store/llm.py
+src/py_store/metadef.py
 src/py_store/permission.py
 src/py_store/schema.py
 src/py_store/sync.py
@@ -39,6 +40,7 @@ tests/test_coverage_margin.py
 tests/test_federation_e2e.py
 tests/test_host_contract.py
 tests/test_host_paths.py
+tests/test_metadef.py
 tests/test_migration.py
 tests/test_mongo_executor.py
 tests/test_mongo_session.py

{storepy-3.0.0 → storepy-3.2.0}/src/storepy.egg-info/requires.txt

@@ -1,5 +1,5 @@
 pymongo>=4.9
-rust-store-py<4.0.0,>=3.0.0
+rust-store-py<4.0.0,>=3.2.0
 
 [dev]
 pytest>=8

storepy-3.2.0/tests/test_metadef.py

@@ -0,0 +1,366 @@
+"""meta-store 定义持久化与版本化单测：A1（落库幂等）/ A2（版本化与回滚）+ 纯函数锚。
+
+parity 锚：纯函数输出与 nodejs-store 侧同输入同输出（对拍脚本 + metadef.js 守护）。
+运行：$env:LOCAL_CORE='1'; $env:PYTHONPATH='py-store/src'; python -m pytest py-store/tests/test_metadef.py -q
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'src'))
+
+from py_store import metadef as md
+from py_store.metadef import MetaDefError
+
+
+def _register_test_schemas():
+    """conftest 清场后恢复内建定义表（幂等自举）"""
+    md.ensure_builtins()
+
+
+# ─── 纯函数（双端逐字节等价锚） ────────────────────────────────
+
+def test_same_defn_key_order_insensitive():
+    assert md.same_defn({'a': 1, 'b': 2}, {'b': 2, 'a': 1})
+    assert not md.same_defn({'a': 1}, {'a': 2})
+    assert md.same_defn({'x': [1, {'k': 'v'}]}, {'x': [1, {'k': 'v'}]})
+
+
+def test_next_version():
+    assert md.next_version([]) == 1
+    assert md.next_version([{'version': 1}, {'version': 3}]) == 4
+
+
+def test_build_def_row_shape_and_key_order():
+    row = md.build_def_row({'name': 'Item'}, {'tenant': 't1', 'env': 'dev', 'actor': 'u1'}, 2)
+    assert row == {'tenant': 't1', 'env': 'dev', 'name': 'Item', 'version': 2,
+                   'defn': {'name': 'Item'}, 'status': 'active', 'createdBy': 'u1'}
+    # 键序与 node buildDefRow 一致（对拍逐字节）
+    assert list(row) == ['tenant', 'env', 'name', 'version', 'defn', 'status', 'createdBy']
+
+
+def test_build_def_row_actor_defaults_empty():
+    row = md.build_def_row({'name': 'Item'}, {'tenant': 't', 'env': 'e'}, 1)
+    assert row['createdBy'] == ''
+
+
+# ─── A1 / A2：真实 sqlite 落库闭环 ─────────────────────────────
+
+def _run_in_sqlite(body, tables=('__schemaDef',)):
+    """建 sqlite 内存库 → 建内建表（默认 __schemaDef）→ init → 执行业务协程
+
+    进程级连接映射是全局单例：用前快照、用后还原，避免把「已关闭的库」留给后续测试文件
+    （对齐 conftest 的注册表隔离思路）。
+    """
+
+    async def _main():
+        import aiosqlite
+
+        from py_store import datasource as _ds
+        from py_store import ddl as ddl_mod
+        from py_store import executors, init, store
+        md.ensure_builtins()
+        prev = dict(_ds._connections)
+        db = await aiosqlite.connect(':memory:')
+        ddl = str(ddl_mod.generate('sqlite', list(tables)))
+        for stmt in ddl.split('\n\n'):
+            if stmt.strip():
+                await db.execute(stmt.strip())
+        await db.commit()
+        await init({'default': executors.create_connection('sqlite', db)})
+        try:
+            return await body(store)
+        finally:
+            await db.close()
+            _ds._connections = prev
+
+    return asyncio.new_event_loop().run_until_complete(_main())
+
+
+def _wf_defn(name, gql='Item(){ _id }'):
+    """最小合法 workflow defn（注册期白名单通过；gql 内容不参与注册期校验）"""
+    return {'name': name, 'steps': [{'op': 'query', 'as': 'a', 'gql': gql}]}
+
+
+def test_a1_persist_one_row_and_idempotent():
+    """A1：register 后 __schemaDef 出现 1 行（五要素）；同名同形重复不新增行"""
+
+    async def _run(store):
+        defn = {'name': 'Item', 'fields': {'_id': {'type': 'string'}, 'title': {'type': 'string'}}}
+        r1 = await md.persist_def(store, defn, {'tenant': 't1', 'env': 'dev', 'actor': 'u1'})
+        # 五要素 (tenant, env, name, version, defn)
+        assert r1['tenant'] == 't1' and r1['env'] == 'dev' and r1['name'] == 'Item'
+        assert r1['version'] == 1 and r1['defn'] == defn
+        assert r1['status'] == 'active' and r1['createdBy'] == 'u1'
+        rows = await md.list_defs(store, {'tenant': 't1', 'env': 'dev', 'name': 'Item'})
+        assert len(rows) == 1
+        # 同名同形重复注册 → 返回原行、不新增
+        r2 = await md.persist_def(store, defn, {'tenant': 't1', 'env': 'dev', 'actor': 'u2'})
+        assert r2['_id'] == r1['_id'] and r2['version'] == 1
+        rows2 = await md.list_defs(store, {'tenant': 't1', 'env': 'dev', 'name': 'Item'})
+        assert len(rows2) == 1
+
+    _run_in_sqlite(_run)
+
+
+def test_a2_versioning_history_and_rollback():
+    """A2：变更 defn → 新增 version+1；可列全部历史；rollbackTo(v) 后生效 defn = 历史 v"""
+
+    async def _run(store):
+        v1 = {'name': 'Item', 'fields': {'_id': {'type': 'string'}, 'title': {'type': 'string'}}}
+        v2 = {'name': 'Item', 'fields': {'_id': {'type': 'string'}, 'title': {'type': 'string'},
+                                         'price': {'type': 'number'}}}
+        r1 = await md.persist_def(store, v1, {'tenant': 't1', 'env': 'dev'})
+        r2 = await md.persist_def(store, v2, {'tenant': 't1', 'env': 'dev'})
+        assert r1['version'] == 1 and r2['version'] == 2
+        hist = await md.list_defs(store, {'tenant': 't1', 'env': 'dev', 'name': 'Item'})
+        assert [r['version'] for r in hist] == [2, 1]  # version desc
+        # loadDefs：各 name 最新 active
+        latest = await md.load_defs(store, {'tenant': 't1', 'env': 'dev'})
+        assert len(latest) == 1 and latest[0]['version'] == 2
+        # 回滚到 v1（追加式）→ 以 v1 defn 追加新版本行；本进程 register → 生效 defn = v1
+        rb = await md.rollback_to(store, {'tenant': 't1', 'env': 'dev', 'name': 'Item', 'version': 1})
+        assert rb['version'] == 3            # 追加式：回滚 = 以 v1 defn 追加 v3（非原地改 v1）
+        assert rb['defn'] == v1
+        assert store.get('Item')['fields'] == v1['fields']
+        assert 'price' not in store.get('Item')['fields']
+        # 历史 append-only：目标行未被改写
+        hist2 = await md.list_defs(store, {'tenant': 't1', 'env': 'dev', 'name': 'Item'})
+        assert [r['version'] for r in hist2] == [3, 2, 1]
+        # 跨进程闭环锚：网关 hydrate 读 load_defs → 现返回回滚后的最新行（defn=v1）
+        latest2 = await md.load_defs(store, {'tenant': 't1', 'env': 'dev'})
+        assert len(latest2) == 1 and latest2[0]['version'] == 3
+        assert latest2[0]['defn'] == v1
+
+    _run_in_sqlite(_run)
+
+
+def test_rollback_missing_version_raises():
+    async def _run(store):
+        with pytest.raises(MetaDefError):
+            await md.rollback_to(store, {'tenant': 't1', 'env': 'dev', 'name': 'Ghost', 'version': 9})
+
+    _run_in_sqlite(_run)
+
+
+def test_persist_missing_name_raises():
+    async def _run(store):
+        with pytest.raises(MetaDefError):
+            await md.persist_def(store, {'fields': {}}, {'tenant': 't1', 'env': 'dev'})
+
+    _run_in_sqlite(_run)
+
+
+# ─── D2：版本唯一性（行自然键 _id） ────────────────────────────
+
+def test_def_id_natural_key_shape():
+    assert md.def_id('t1', 'dev', 'Item', 2) == 't1\u001fdev\u001fItem\u001f2'
+    assert md.def_id(None, None, 'Item', 1) == '\u001f\u001fItem\u001f1'
+
+
+def test_d2_persist_writes_natural_id_and_version_unique():
+    """D2：persist 落行带自然键 _id；同版本二次写入 → 存储层唯一键冲突（显式上抛）"""
+
+    async def _run(store):
+        defn = {'name': 'UniqItem', 'fields': {'_id': {'type': 'string'}}}
+        r1 = await md.persist_def(store, defn, {'tenant': 't2', 'env': 'dev'})
+        assert r1['_id'] == md.def_id('t2', 'dev', 'UniqItem', 1)
+        # 并发写同版本的最小复现：绕过「读最新行 +1」直插同版本行
+        dup = md.build_def_row(defn, {'tenant': 't2', 'env': 'dev'}, 1)
+        dup['_id'] = md.def_id('t2', 'dev', 'UniqItem', 1)
+        with pytest.raises(Exception) as ei:
+            with md._internal_ctx():
+                await store.insert('__schemaDef', dup)
+        assert 'unique' in str(ei.value).lower()
+
+    _run_in_sqlite(_run)
+
+
+# ─── D1：从持久化定义重建注册表（发布闭环桥） ────────────────
+
+def test_d1_restore_defs_rebuilds_registry():
+    """D1：persist 只落库不注册；restore_defs 从库重建注册表（同版本幂等）"""
+
+    async def _run(store):
+        md._applied.clear()
+        defn = {'name': 'RestoredItem',
+                'fields': {'_id': {'type': 'string'}, 'title': {'type': 'string'}}}
+        await md.persist_def(store, defn, {'tenant': 't3', 'env': 'dev'})
+        assert not store.has('RestoredItem')  # 原缺口：落库后协议面不可见
+        out = await md.restore_defs(store, {'tenant': 't3', 'env': 'dev'})
+        assert out['applied'] == 1
+        assert store.has('RestoredItem')      # 重建后即可见
+        out2 = await md.restore_defs(store, {'tenant': 't3', 'env': 'dev'})
+        assert out2['applied'] == 0           # 同版本幂等：不重复注册
+
+    _run_in_sqlite(_run)
+
+
+# ─── D21：回滚跨进程闭环（rollback → reload hydrate → 按历史 defn 装配） ────
+
+def test_d21_rollback_visible_via_restore_defs():
+    """D21：rollback 以历史 defn 追加新版本 → restore_defs（网关 hydrate 路径）按历史 defn 装配
+
+    复现原缺口：若回滚只原地重注册、不落新行，load_defs 仍返回被回滚掉的旧版本，
+    网关 hydrate 后协议面仍是旧版本 —— 跨进程回滚不闭环。追加式回滚后 load_defs 返回
+    回滚后的新行（新自然键），restore_defs 必然 applied。
+    """
+
+    async def _run(store):
+        md._applied.clear()
+        v1 = {'name': 'RbItem', 'fields': {'_id': {'type': 'string'}, 'title': {'type': 'string'}}}
+        v2 = {'name': 'RbItem', 'fields': {'_id': {'type': 'string'}, 'title': {'type': 'string'},
+                                           'price': {'type': 'number'}}}
+        o = {'tenant': 't5', 'env': 'dev'}
+        await md.persist_def(store, v1, o)
+        await md.restore_defs(store, o)                       # 网关首次 hydrate → v1
+        await md.persist_def(store, v2, o)
+        await md.restore_defs(store, o)                       # 网关再次 hydrate → v2
+        assert 'price' in store.get('RbItem')['fields']
+        # 控制面回滚到 v1
+        await md.rollback_to(store, {'tenant': 't5', 'env': 'dev', 'name': 'RbItem', 'version': 1})
+        # 网关新一次 reload：load_defs 应返回回滚后的最新行（defn=v1），新键 → applied
+        latest = await md.load_defs(store, o)
+        assert len(latest) == 1 and latest[0]['version'] == 3 and latest[0]['defn'] == v1
+        out = await md.restore_defs(store, o)
+        assert out['applied'] == 1
+        assert 'price' not in store.get('RbItem')['fields']   # 协议面按历史 defn 装配
+
+    _run_in_sqlite(_run)
+
+
+# ─── workflow 定义持久化（kind=workflow，落 __workflowDef；审计 §8 N1）───────
+
+def test_wf_persist_idempotent_versioning_and_list():
+    """workflow：persist 同名同形幂等 + 异形 version+1 + list version desc"""
+
+    async def _run(store):
+        o = {'tenant': 't6', 'env': 'dev', 'kind': 'workflow'}
+        w1 = _wf_defn('WfPersist')
+        w2 = _wf_defn('WfPersist', 'Item(){ _id title }')
+        r1 = await md.persist_def(store, w1, o)
+        assert r1['version'] == 1
+        assert (await md.persist_def(store, w1, o))['version'] == 1   # 同名同形幂等
+        r2 = await md.persist_def(store, w2, o)
+        assert r2['version'] == 2                                     # 异形 version+1
+        rows = await md.list_defs(store, {'tenant': 't6', 'env': 'dev',
+                                          'name': 'WfPersist', 'kind': 'workflow'})
+        assert [r['version'] for r in rows] == [2, 1]                 # version desc
+        assert rows[0]['_id'] == md.def_id('t6', 'dev', 'WfPersist', 2)
+
+    _run_in_sqlite(_run, ('__workflowDef',))
+
+
+def test_wf_load_defs_latest_active():
+    """workflow：load_defs 取各 name 最新 active"""
+
+    async def _run(store):
+        o = {'tenant': 't7', 'env': 'dev', 'kind': 'workflow'}
+        await md.persist_def(store, _wf_defn('WfLoad'), o)
+        await md.persist_def(store, _wf_defn('WfLoad', 'Item(){ _id title }'), o)
+        await md.persist_def(store, {'name': 'WfOther', 'steps': [{'op': 'fail', 'message': 'x'}]}, o)
+        rows = await md.load_defs(store, o)
+        assert {r['name']: r['version'] for r in rows} == {'WfLoad': 2, 'WfOther': 1}
+
+    _run_in_sqlite(_run, ('__workflowDef',))
+
+
+def test_wf_restore_defs_rebuilds_workflow_registry():
+    """workflow：restore_defs(kind=workflow) 重建 workflow 注册表（幂等）"""
+
+    async def _run(store):
+        md._applied.clear()
+        o = {'tenant': 't8', 'env': 'dev'}
+        await md.persist_def(store, _wf_defn('WfRestore'), {**o, 'kind': 'workflow'})
+        assert 'WfRestore' not in store.workflows()          # 落库未注册
+        out = await md.restore_defs(store, {**o, 'kind': 'workflow'})
+        assert out['applied'] == 1
+        assert 'WfRestore' in store.workflows()              # 重建后可见
+        assert (await md.restore_defs(store, {**o, 'kind': 'workflow'}))['applied'] == 0
+
+    _run_in_sqlite(_run, ('__workflowDef',))
+
+
+def test_wf_rollback_append_only_and_reload():
+    """workflow：rollback 追加式 → load_defs 按历史 defn，本进程重注册"""
+
+    async def _run(store):
+        md._applied.clear()
+        o = {'tenant': 't10', 'env': 'dev', 'kind': 'workflow'}
+        v1 = _wf_defn('WfRb')
+        v2 = _wf_defn('WfRb', 'Item(){ _id title }')
+        await md.persist_def(store, v1, o)
+        await md.persist_def(store, v2, o)
+        rb = await md.rollback_to(store, {'tenant': 't10', 'env': 'dev',
+                                          'name': 'WfRb', 'version': 1, 'kind': 'workflow'})
+        assert rb['version'] == 3 and rb['defn'] == v1       # 追加式
+        latest = await md.load_defs(store, o)
+        assert latest[0]['version'] == 3 and latest[0]['defn'] == v1
+        assert store.get_workflow('WfRb')['steps'][0]['gql'] == 'Item(){ _id }'  # 本进程重注册
+
+    _run_in_sqlite(_run, ('__workflowDef',))
+
+
+def test_a3_host_restore_defs_both_kinds():
+    """宿主 restore_defs 同时重建 schema 与 workflow 两类（一次调用闭环）"""
+
+    async def _run(store):
+        md._applied.clear()
+        o = {'tenant': 't9', 'env': 'dev'}
+        await store.persist_def({'name': 'HostItem', 'fields': {'_id': {'type': 'string'}}}, o)
+        await store.persist_workflow_def(_wf_defn('HostWf'), o)
+        assert not store.has('HostItem')
+        assert 'HostWf' not in store.workflows()
+        out = await store.restore_defs(o)
+        assert out['applied'] == 2                            # 一次调用重建两类
+        assert store.has('HostItem')
+        assert 'HostWf' in store.workflows()
+
+    _run_in_sqlite(_run, ('__schemaDef', '__workflowDef'))
+
+
+def test_wf_restore_under_closed_meta_policy():
+    """Closed 定义层门禁下 restore_defs 仍以 internal 重建 workflow 定义"""
+
+    async def _run(store):
+        from py_store import schema as sc
+        from py_store import workflow as wf
+        md._applied.clear()
+        o = {'tenant': 't11', 'env': 'dev', 'kind': 'workflow'}
+        await md.persist_def(store, _wf_defn('WfRestoreGate'), o)
+        sc.set_meta_policy(True, [])
+        try:
+            out = await md.restore_defs(store, dict(o))
+            assert out['applied'] == 1
+            assert 'WfRestoreGate' in store.workflows()      # Closed 下仍重建（internal）
+        finally:
+            sc.set_meta_policy(False, [])
+            wf._workflows.pop('WfRestoreGate', None)
+
+    _run_in_sqlite(_run, ('__workflowDef',))
+
+
+def test_wf_rollback_under_closed_meta_policy():
+    """Closed 定义层门禁下 rollback_to 仍以 internal 重建 workflow 定义"""
+
+    async def _run(store):
+        from py_store import schema as sc
+        from py_store import workflow as wf
+        md._applied.clear()
+        o = {'tenant': 't11', 'env': 'dev', 'kind': 'workflow'}
+        await md.persist_def(store, _wf_defn('WfRbGate'), o)
+        await md.persist_def(store, _wf_defn('WfRbGate', 'Item(){ _id title }'), o)
+        sc.set_meta_policy(True, [])
+        try:
+            rb = await md.rollback_to(store, {'tenant': 't11', 'env': 'dev',
+                                              'name': 'WfRbGate', 'version': 1, 'kind': 'workflow'})
+            assert rb['version'] == 3                        # 追加式
+            assert store.get_workflow('WfRbGate')['steps'][0]['gql'] == 'Item(){ _id }'  # Closed 下仍重建
+        finally:
+            sc.set_meta_policy(False, [])
+            wf._workflows.pop('WfRbGate', None)
+
+    _run_in_sqlite(_run, ('__workflowDef',))

{storepy-3.0.0 → storepy-3.2.0}/tests/test_workflow.py

@@ -134,6 +134,31 @@ def test_register_and_read_filter():
         wf._workflows.pop(GOOD['name'], None)
 
 
+def test_register_meta_gate():
+    from py_store import schema as sc
+
+    gate = {'name': 'gateWf', 'steps': [{'op': 'fail', 'message': 'x'}]}
+    wf._workflows.pop('gateWf', None)
+    try:
+        # Open（缺省）：无 ctx 放行
+        sc.set_meta_policy(False, [])
+        wf.register(gate)
+        wf._workflows.pop('gateWf', None)
+
+        # Closed：无 ctx → 显式 ERR_PERMISSION，且定义不写入
+        sc.set_meta_policy(True, [])
+        with pytest.raises(WorkflowError, match='ERR_PERMISSION:'):
+            wf.register(gate)
+        assert 'gateWf' not in wf._workflows
+
+        # Closed：internal 放行
+        wf.register(gate, {'internal': True})
+        assert 'gateWf' in wf._workflows
+    finally:
+        wf._workflows.pop('gateWf', None)
+        sc.set_meta_policy(False, [])  # 复位，防污染后续用例
+
+
 # ─── parity 锚：占位符解析 ───────────────────────────────────
 
 _RESOLVE_CTX = {'inv': {'_id': 'inv1', 'stock': 100}}

storepy-3.0.0/src/py_store/feedback.py

@@ -1,41 +0,0 @@
-"""反馈事件通道 —— 兜底/降级/拦截触发的统一出口
-
-事件形状（对齐 rust-store 联邦 degraded 契约）::
-
-    {type, code, layer, message, hint, ...}
-      - type  : 事件类别（federation_degraded / sql_pushdown_unsupported ...）
-      - code  : 机器可读代码（crossSourceSort / pushdownUnsupported ...）
-      - layer : 命中的防护层（federation / dialect ...）
-      - message: 人可读描述
-      - hint  : 修复指引（供上游排查/加固）
-
-默认无 sink 时打 stderr（向后兼容）；宿主可 ``set_sink(fn)`` 接管，
-接入自动反馈闭环（允许被拦截，禁止静默失守）。
-"""
-
-import sys
-
-_sink = None
-
-
-def get_sink():
-    """当前 sink（None = 默认 stderr 行为）；供接管方保存原值、退出时恢复（token-set/reset 同构）"""
-    return _sink
-
-
-def set_sink(fn):
-    """注册反馈事件回调 ``fn(event: dict)``；传 None 恢复默认 stderr 行为"""
-    global _sink
-    _sink = fn
-
-
-def emit(event):
-    """产出一条反馈事件：有 sink 回调之；否则打印 stderr（允许拦截，禁止静默）"""
-    if _sink is not None:
-        _sink(event)
-        return
-    print(
-        f"[py-store][{event.get('layer', '?')}/{event.get('code', '?')}] "
-        f"{event.get('message', '')}（hint: {event.get('hint', '-')}）",
-        file=sys.stderr,
-    )