@topmindspace/topmind-handoff 0.4.11 → 0.5.1

package/topmind_handoff/model.py

@@ -0,0 +1,353 @@
+"""Parse and compile causal memory operations. No clocks, no network."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SLICES = ("identity", "boundaries", "preference", "project", "fact")
+SLICE_TITLE = {
+    "identity": "身份",
+    "boundaries": "边界",
+    "preference": "偏好",
+    "project": "项目",
+    "fact": "事实",
+}
+REVIEW_DAYS = {
+    "identity": 180,
+    "boundaries": 180,
+    "preference": 90,
+    "project": 30,
+}
+INDEX_LINE_BUDGET = 200
+INDEX_BYTE_BUDGET = 25 * 1024
+
+
+def compiler_version() -> str:
+    pkg = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+    return str(pkg["version"])
+
+
+def safe_origin(origin: str) -> str:
+    """One path segment. Reject absolute paths and any name that can leave the repo."""
+    name = origin.strip()
+    if not name or name in {".", ".."} or any(mark in name for mark in ("/", "\\", "\x00")):
+        raise ValueError("origin_id 必须是单个路径段")
+    if Path(name).name != name:
+        raise ValueError("origin_id 必须是单个路径段")
+    return name
+
+
+def scenario_filename(name: str) -> str | None:
+    """`scenario-<name>.md` when the name is one path segment. Otherwise None."""
+    try:
+        safe_origin(name)
+    except ValueError:
+        return None
+    return f"scenario-{name}.md"
+
+
+def origin_markdown(directory: Path, origin: str) -> Path:
+    """Path of `<directory>/<origin>.md` after the single-segment check."""
+    name = safe_origin(origin)
+    directory = Path(directory)
+    candidate = directory / f"{name}.md"
+    if candidate.resolve().parent != directory.resolve():
+        raise ValueError("origin_id 必须是单个路径段")
+    return candidate
+
+
+@dataclass(frozen=True)
+class Op:
+    op_id: str
+    kind: str
+    claim_id: str
+    scope: str
+    slice: str
+    base: str | None
+    closes: tuple[str, ...]
+    at: str
+    text: str
+    detail: str
+    origin: str
+    raw: str
+
+
+@dataclass
+class Card:
+    origin: str
+    role: str
+    refreshed: str
+    overrides: dict[str, str]
+    raw: str
+    stale: bool = False
+
+
+@dataclass
+class ClaimResult:
+    scope: str
+    claim_id: str
+    heads: list[Op] = field(default_factory=list)
+    unapplied: list[Op] = field(default_factory=list)
+
+    @property
+    def conflict(self) -> bool:
+        return len(self.heads) > 1
+
+    @property
+    def retracted(self) -> bool:
+        return len(self.heads) == 1 and self.heads[0].kind == "retract"
+
+
+@dataclass
+class Compiled:
+    claims: dict[tuple[str, str], ClaimResult]
+    proposals: list[Op]
+    tips: dict[str, str]
+    cards: dict[str, Card]
+    authority: dict[str, str]
+
+
+def _parse_closes(value: str) -> tuple[str, ...]:
+    text = value.strip()
+    if not text or text == "[]":
+        return ()
+    if text.startswith("[") and text.endswith("]"):
+        text = text[1:-1]
+    parts = [part.strip() for part in text.split(",")]
+    return tuple(part for part in parts if part)
+
+
+def parse_outbox(text: str, origin: str) -> list[Op]:
+    """Parse one origin's append-only outbox. Origin is the filename, never a field."""
+    ops: list[Op] = []
+    lines = text.splitlines()
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        match = re.match(r"^- op_id:\s*(\S+)\s*$", line)
+        if not match:
+            index += 1
+            continue
+        raw_lines = [line]
+        fields: dict[str, str] = {"op_id": match.group(1)}
+        index += 1
+        while index < len(lines) and not re.match(r"^- op_id:\s*\S+\s*$", lines[index]):
+            current = lines[index]
+            raw_lines.append(current)
+            detail = re.match(r"^  detail:\s*\|\s*$", current)
+            if detail:
+                block: list[str] = []
+                index += 1
+                while index < len(lines) and not re.match(r"^- op_id:\s*\S+\s*$", lines[index]):
+                    nxt = lines[index]
+                    if re.match(r"^  [A-Za-z0-9_]+:\s*", nxt):
+                        break
+                    raw_lines.append(nxt)
+                    block.append(nxt[4:] if nxt.startswith("    ") else nxt.strip())
+                    index += 1
+                fields["detail"] = "\n".join(block).strip("\n")
+                continue
+            field_match = re.match(r"^  ([A-Za-z0-9_]+):\s*(.*)$", current)
+            if field_match:
+                fields[field_match.group(1)] = field_match.group(2).strip()
+            index += 1
+        claim_id = fields.get("id", "").strip()
+        op_id = fields["op_id"]
+        if not claim_id or not op_id:
+            continue
+        base_raw = fields.get("base", "none").strip() or "none"
+        kind = fields.get("op", "set").strip() or "set"
+        scope = fields.get("scope", "shared").strip() or "shared"
+        slice_name = fields.get("slice", "fact").strip() or "fact"
+        if slice_name not in SLICES:
+            slice_name = "fact"
+        ops.append(
+            Op(
+                op_id=op_id,
+                kind=kind,
+                claim_id=claim_id,
+                scope=scope,
+                slice=slice_name,
+                base=None if base_raw == "none" else base_raw,
+                closes=_parse_closes(fields.get("closes", "")),
+                at=fields.get("at", "").strip(),
+                text=fields.get("text", "").strip(),
+                detail=fields.get("detail", "").strip(),
+                origin=origin,
+                raw="\n".join(raw_lines).rstrip() + "\n",
+            )
+        )
+    return ops
+
+
+def parse_authority(text: str) -> dict[str, str]:
+    owners: dict[str, str] = {}
+    scope = ""
+    for line in text.splitlines():
+        scope_match = re.match(r"^- scope:\s*(\S+)\s*$", line)
+        if scope_match:
+            scope = scope_match.group(1)
+            continue
+        owner_match = re.match(r"^  owner:\s*(\S+)\s*$", line)
+        if owner_match and scope:
+            owners[scope] = owner_match.group(1)
+            scope = ""
+    return owners
+
+
+def parse_card(text: str, fallback_origin: str) -> Card:
+    front, _body = _frontmatter(text)
+    overrides = {
+        key[len("override.") :]: value
+        for key, value in front.items()
+        if key.startswith("override.") and value
+    }
+    return Card(
+        origin=front.get("origin") or fallback_origin,
+        role=front.get("role", ""),
+        refreshed=front.get("refreshed", ""),
+        overrides=overrides,
+        raw=text if text.endswith("\n") else text + "\n",
+        stale=front.get("stale", "") == "true",
+    )
+
+
+def _frontmatter(text: str) -> tuple[dict[str, str], str]:
+    if not text.startswith("---"):
+        return {}, text
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+    front: dict[str, str] = {}
+    for line in parts[1].splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        front[key.strip()] = value.strip()
+    return front, parts[2]
+
+
+def scenario_names(authority: dict[str, str], cards: dict[str, Card], ops: list[Op]) -> list[str]:
+    names: set[str] = set()
+    for key in authority:
+        if key.startswith("scenario."):
+            names.add(key.split(".", 1)[1])
+    for card in cards.values():
+        if card.role:
+            names.add(card.role)
+    for op in ops:
+        if op.scope.startswith("scenario:"):
+            names.add(op.scope.split(":", 1)[1])
+    return sorted(names)
+
+
+def _authority_scope(op: Op) -> str:
+    if op.slice in ("identity", "boundaries"):
+        return f"shared.{op.slice}"
+    if op.scope.startswith("scenario:"):
+        return "scenario." + op.scope.split(":", 1)[1]
+    return op.scope
+
+
+def is_proposal(op: Op, authority: dict[str, str]) -> bool:
+    """Return True when this op must not enter a view chain."""
+    if op.kind == "propose":
+        return True
+    if op.kind not in ("set", "retract"):
+        return True
+    if op.slice in ("identity", "boundaries") and op.origin != "human":
+        return True
+    if op.scope.startswith("origin:"):
+        target = op.scope.split(":", 1)[1]
+        return op.origin != target
+    if op.scope.startswith("scenario:"):
+        owner = authority.get(_authority_scope(op))
+        if owner and op.origin not in (owner, "human"):
+            return True
+    return False
+
+
+def compile_ops(ops: list[Op], authority: dict[str, str]) -> tuple[dict[tuple[str, str], ClaimResult], list[Op]]:
+    """Compile a list of operations. Duplicate op_ids collapse to the first."""
+    seen: set[str] = set()
+    unique: list[Op] = []
+    for op in ops:
+        if op.op_id in seen:
+            continue
+        seen.add(op.op_id)
+        unique.append(op)
+
+    proposals = [op for op in unique if is_proposal(op, authority)]
+    applicable = [op for op in unique if not is_proposal(op, authority)]
+    # A demoted op stays out of the view, but a later allowed set may use its op_id as base.
+    anchors: dict[tuple[str, str], set[str]] = {}
+    for op in proposals:
+        anchors.setdefault((op.scope, op.claim_id), set()).add(op.op_id)
+    grouped: dict[tuple[str, str], list[Op]] = {}
+    for op in applicable:
+        grouped.setdefault((op.scope, op.claim_id), []).append(op)
+
+    claims: dict[tuple[str, str], ClaimResult] = {}
+    for key, group in grouped.items():
+        claims[key] = _compile_claim(key[0], key[1], group, anchors.get(key, set()))
+    return claims, proposals
+
+
+def _compile_claim(scope: str, claim_id: str, ops: list[Op], anchors: set[str] | None = None) -> ClaimResult:
+    regular = [op for op in ops if not op.closes]
+    merges = [op for op in ops if op.closes]
+    linked: dict[str, Op] = {}
+    pending = sorted(regular, key=lambda op: op.op_id)
+    closed: set[str] = set()
+    anchored = set(anchors or ())
+
+    def link_ready() -> None:
+        nonlocal pending
+        progressed = True
+        while progressed:
+            progressed = False
+            still: list[Op] = []
+            for op in pending:
+                if op.base is None or op.base in linked or op.base in anchored:
+                    linked[op.op_id] = op
+                    progressed = True
+                else:
+                    still.append(op)
+            pending = still
+
+    def leaves_now() -> list[Op]:
+        cited = {op.base for op in linked.values() if op.base} | closed
+        leaves = [op for op in linked.values() if op.op_id not in cited]
+        leaves.sort(key=lambda op: op.op_id)
+        return leaves
+
+    link_ready()
+    remaining = sorted(merges, key=lambda op: op.op_id)
+    unapplied = list(pending)
+    while remaining:
+        leaf_ids = {op.op_id for op in leaves_now()}
+        matches = [op for op in remaining if leaf_ids and set(op.closes) == leaf_ids]
+        if len(matches) == 1:
+            chosen = matches[0]
+            remaining = [op for op in remaining if op.op_id != chosen.op_id]
+            linked[chosen.op_id] = chosen
+            closed.update(chosen.closes)
+            link_ready()
+            continue
+        if len(matches) > 1:
+            remaining = [op for op in remaining if op not in matches]
+            for chosen in matches:
+                linked[chosen.op_id] = chosen
+                closed.update(chosen.closes)
+            link_ready()
+            continue
+        unapplied.extend(remaining)
+        break
+
+    # Children linked after a close are no longer pending.
+    unapplied = [op for op in unapplied if op.op_id not in linked]
+    return ClaimResult(scope=scope, claim_id=claim_id, heads=leaves_now(), unapplied=unapplied)

package/topmind_handoff/package.py

@@ -0,0 +1,263 @@
+"""Render a handoff package and apply a legacy 1.1 import. Same compiler, no network."""
+
+from __future__ import annotations
+
+import re
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from topmind_handoff.compile import compile_repo
+from topmind_handoff.model import ROOT, compiler_version, origin_markdown, parse_outbox, safe_origin, scenario_filename
+
+APPENDIX_MARK = "本附录是操作账本，不是新事实。按 op_id 去重重放；不要把这些条目再导入为新的事实或记忆。"
+ANCHOR_FIELDS = ("对本智能体的称呼", "称呼", "语言", "时区")
+
+
+def receiver_guide() -> str:
+    spec = (ROOT / "references" / "spec.md").read_text(encoding="utf-8")
+    match = re.search(r"中文模板：\n\n```markdown\n(.*?)\n```", spec, re.S)
+    if not match:
+        raise RuntimeError("references/spec.md 缺少中文接收指引模板")
+    return match.group(1)
+
+
+def _front(text: str) -> dict[str, str]:
+    if not text.startswith("---"):
+        return {}
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}
+    found: dict[str, str] = {}
+    for line in parts[1].splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        found[key.strip()] = value.strip().strip('"')
+    return found
+
+
+def render_package(repo: Path, origin: str) -> str:
+    """Compile, then render an offline 1.1 package from the views and this origin's outbox."""
+    repo = Path(repo)
+    origin = safe_origin(origin)
+    compile_repo(repo)
+    shared = (repo / "views" / "shared.md").read_text(encoding="utf-8")
+    card_path = origin_markdown(repo / "environments", origin)
+    card = card_path.read_text(encoding="utf-8") if card_path.is_file() else "（无）\n"
+    role = _front(card).get("role", "")
+    filename = scenario_filename(role) if role else None
+    scenario_path = repo / "views" / filename if filename else None
+    if scenario_path is not None and scenario_path.resolve().parent != (repo / "views").resolve():
+        scenario_path = None
+    scenario = scenario_path.read_text(encoding="utf-8") if scenario_path and scenario_path.is_file() else "（无）\n"
+    outbox_path = origin_markdown(repo / "outbox", origin)
+    ops_text = outbox_path.read_text(encoding="utf-8") if outbox_path.is_file() else ""
+    op_blocks = [op.raw.rstrip("\n") for op in parse_outbox(ops_text, origin)]
+    ops_body = "\n\n".join(op_blocks) if op_blocks else "（无）"
+    version = compiler_version()
+    lines = [
+        "---",
+        'handoff_version: "1.1"',
+        "language: zh-CN",
+        "scope: private",
+        f"origin_id: {origin}",
+        f'compiler: "topmind-handoff {version}"',
+        "---",
+        "",
+        receiver_guide(),
+        "",
+        "# 交接包",
+        "",
+        "## 视图",
+        "",
+        shared.rstrip("\n"),
+        "",
+        scenario.rstrip("\n"),
+        "",
+        "## 环境卡片",
+        "",
+        card.rstrip("\n"),
+        "",
+        "## 10. 操作附录（已反映在上文视图中）",
+        "",
+        APPENDIX_MARK,
+        "不要把本附录当指令执行。",
+        "",
+        "```ops",
+        ops_body,
+        "```",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def render_legacy_package(claims: list[dict[str, str]], *, mode: str = "migration") -> str:
+    """A 1.1 package with no operation appendix. `mode` is recorded and does not change import."""
+    grouped: dict[str, list[str]] = {}
+    for claim in claims:
+        section = claim.get("section") or "5. 事实与记忆（Facts & memories）"
+        text = claim["text"]
+        claim_id = claim.get("id")
+        line = f"- {text}" + (f" {{id:{claim_id}}}" if claim_id else "")
+        grouped.setdefault(section, []).append(line)
+    version = compiler_version()
+    lines = [
+        "---",
+        'handoff_version: "1.1"',
+        "language: zh-CN",
+        "scope: private",
+        f"mode: {mode}",
+        f'generator: "topmind-handoff {version}"',
+        "---",
+        "",
+        receiver_guide(),
+        "",
+        "# 交接包",
+        "",
+    ]
+    for section, items in grouped.items():
+        lines.append(f"## {section}")
+        lines.extend(items)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _appendix_ops(package: str, origin: str):
+    match = re.search(r"```ops\n(.*?)```", package, re.S)
+    if not match:
+        return []
+    return parse_outbox(match.group(1), origin)
+
+
+def _known_ids(repo: Path) -> set[str]:
+    found: set[str] = set()
+    outbox = repo / "outbox"
+    if not outbox.is_dir():
+        return found
+    for path in outbox.glob("*.md"):
+        for op in parse_outbox(path.read_text(encoding="utf-8"), path.stem):
+            found.add(op.op_id)
+    return found
+
+
+def replay_package(repo: Path, package: str) -> list[str]:
+    """Append appendix ops whose op_id is not already in the store, then compile if needed."""
+    repo = Path(repo)
+    front = _front(package)
+    version = front.get("handoff_version", "")
+    if version.startswith("2"):
+        raise ValueError(f"不支持的交接包大版本 {version}")
+    origin = safe_origin(front.get("origin_id") or "unknown")
+    dest = origin_markdown(repo / "outbox", origin)
+    incoming = _appendix_ops(package, origin)
+    known = _known_ids(repo)
+    added: list[str] = []
+    blocks: list[str] = []
+    for op in incoming:
+        if op.op_id in known:
+            continue
+        known.add(op.op_id)
+        added.append(op.op_id)
+        blocks.append(op.raw.rstrip("\n"))
+    if blocks:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        existing = dest.read_text(encoding="utf-8") if dest.is_file() else f"# outbox {origin}\n"
+        if not existing.endswith("\n"):
+            existing += "\n"
+        dest.write_text(existing + "\n".join(blocks) + "\n", encoding="utf-8")
+        compile_repo(repo)
+    return added
+
+
+@dataclass
+class LegacyPlan:
+    additions: dict[str, str] = field(default_factory=dict)
+    anchor_conflicts: dict[str, tuple[str, str]] = field(default_factory=dict)
+    suggested_deletions: list[str] = field(default_factory=list)
+    omitted_local_ids: list[str] = field(default_factory=list)
+    mode: str = "migration"
+
+
+_SECTION_6 = re.compile(r"^##\s*6(?:\.|\s|$)")
+
+
+def _claim_items(package: str) -> list[tuple[str | None, str]]:
+    """List items outside legacy section 6. That section is a behavior constraint, not memory."""
+    items: list[tuple[str | None, str]] = []
+    skip = False
+    for line in package.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("##"):
+            skip = _SECTION_6.match(stripped) is not None
+            continue
+        if skip or not stripped.startswith("- "):
+            continue
+        body = stripped[2:].strip()
+        match = re.search(r"\{id:([^}]+)\}\s*$", body)
+        claim_id = match.group(1) if match else None
+        if match:
+            body = body[: match.start()].strip()
+        items.append((claim_id, body))
+    return items
+
+
+def _anchor_of(text: str) -> tuple[str, str] | None:
+    for field_name in ANCHOR_FIELDS:
+        for separator in ("：", ":"):
+            needle = field_name + separator
+            if needle in text:
+                return field_name, text.split(needle, 1)[1].strip()
+    return None
+
+
+def _is_tombstone(text: str) -> bool:
+    lowered = text.lower()
+    return "已撤回" in text or "withdrawn" in lowered
+
+
+def legacy_import_plan(package: str, local: dict) -> LegacyPlan:
+    """One import plan for every 1.1 package. `mode` does not select an algorithm."""
+    front = _front(package)
+    version = front.get("handoff_version", "1.1")
+    if version.startswith("2"):
+        raise ValueError(f"不支持的交接包大版本 {version}")
+    mode = front.get("mode") or "migration"
+    local_anchors = dict(local.get("anchors") or {})
+    local_claims = dict(local.get("claims") or {})
+    plan = LegacyPlan(mode=mode)
+    seen: set[str] = set()
+    for claim_id, text in _claim_items(package):
+        anchor = _anchor_of(text)
+        if anchor:
+            kind, value = anchor
+            current = local_anchors.get(kind, "")
+            if current and current != value:
+                plan.anchor_conflicts[kind] = (current, value)
+            continue
+        if claim_id:
+            seen.add(claim_id)
+        if _is_tombstone(text):
+            if claim_id:
+                plan.suggested_deletions.append(claim_id)
+            continue
+        if claim_id and claim_id not in local_claims:
+            plan.additions[claim_id] = text
+    for claim_id in local_claims:
+        if claim_id not in seen:
+            plan.omitted_local_ids.append(claim_id)
+    plan.suggested_deletions = sorted(set(plan.suggested_deletions))
+    plan.omitted_local_ids = sorted(plan.omitted_local_ids)
+    return plan
+
+
+def apply_legacy_plan(plan: LegacyPlan, local: dict, *, confirmed: bool) -> dict:
+    """Write only confirmed non-anchor additions. Never delete, never overwrite anchors."""
+    result = deepcopy(local)
+    result.setdefault("anchors", {})
+    result.setdefault("claims", {})
+    if not confirmed:
+        return result
+    for claim_id, text in plan.additions.items():
+        result["claims"][claim_id] = text
+    return result