vincs 0.1.0__py3-none-any.whl

vinc/__init__.py

@@ -0,0 +1,8 @@
+"""Vinc SDK. Framework dependencies are loaded only by their integration."""
+from .sdk import *  # noqa: F403
+from .sdk import AsyncVincClient, VincClient, __all__ as _sdk_exports
+
+__version__ = "0.1.0"
+Vinc = VincClient
+AsyncVinc = AsyncVincClient
+__all__ = [*_sdk_exports, "Vinc", "AsyncVinc"]

vinc/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

vinc/_runtime/api/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""Query API — read-only entry points over the memory store.
+
+Three entry points sit on top of the ingestion engines:
+    recall  : episodic memory retrieval (Episode nodes, time-ordered)
+    search  : hybrid vector + BM25 retrieval over Chunk nodes
+    decide  : decision support — graph traversal over policy/concept relations
+
+Each entry point builds a deterministic *query plan* (testable without a
+database) and, when a Neo4j driver is available, executes it.
+"""
+from __future__ import annotations
+
+from .query import QueryPlan, decide, recall, search
+
+__all__ = ["QueryPlan", "recall", "search", "decide"]

vinc/_runtime/api/activate.py

@@ -0,0 +1,226 @@
+# -*- coding: utf-8 -*-
+"""Activate — make a slice of owned memory *portable* to an external AI.
+
+P3 of the memory IA ("내 AI로 이식"). Given recall rows (owner-scoped, optionally
+preference-ranked), build a **context pack** in two portable shapes:
+
+  - a Markdown brief (``pack.md``) a human or any LLM can read directly;
+  - a structured JSON (``pack.json``) for programmatic ingestion;
+
+plus an **MCP resource manifest** (``mcp.json``) — the connector contract an MCP
+server (mounted by weg-9000-orchestration) serves so a foreign AI can pull these
+episodes as ``memory://{owner}/{id}`` resources.
+
+Builders are pure (no I/O, no wall clock — ``generated_at`` is injected) so the
+pack is deterministic and testable. ``activate`` orchestrates recall → pack and
+optionally writes the three files.
+
+    python -m api.cli activate --owner user:weg1456 --rank preference --out ./pack
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import query as q
+
+MCP_SCHEMA_VERSION = "2024-11-05"
+_URI_SCHEME = "memory"
+
+
+def _uri(owner: str, episode_id: str) -> str:
+    return f"{_URI_SCHEME}://{owner}/{episode_id}"
+
+
+@dataclass
+class ContextPack:
+    owner: str
+    query: str
+    generated_at: str | None
+    episodes: list[dict]
+    learner_model: list[dict] = field(default_factory=list)  # how this person learns (U-patterns)
+    theme_id: str | None = None
+    # 주제 어휘(선택) — **authored 만** 실린다. proposed(재가 전 잠정)는 팩·내보내기에
+    # 하중을 지지 않는다(THESIS §6 잠정상태 · D11-R2). activate() 가 필터해 넣어준다.
+    vocabulary: list[dict] = field(default_factory=list)
+
+    # ── JSON shape (programmatic ingestion) ──────────────────────────────────
+    def to_json(self) -> dict:
+        out = {
+            "kind": "weg-9000-memory/context-pack",
+            "owner": self.owner,
+            "query": self.query,
+            "generated_at": self.generated_at,
+            "episode_count": len(self.episodes),
+            "episodes": self.episodes,
+            "learner_model": self.learner_model,
+        }
+        if self.theme_id is not None:
+            out["theme"] = {"theme_id": self.theme_id, "vocabulary": self.vocabulary}
+        return out
+
+    def _learner_section(self) -> list[str]:
+        if not self.learner_model:
+            return []
+        out = [
+            "",
+            f"## 학습법 — how {self.owner} learns",
+            "",
+            "> 이 개인의 학습 방식(인지 지문). 외부 AI는 이 방식에 맞춰 나를 도와야 한다.",
+            "",
+        ]
+        for p in self.learner_model:
+            meta = []
+            if p.get("domain"):
+                meta.append(f"domain: {p['domain']}")
+            if p.get("observations") is not None:
+                meta.append(f"n={p['observations']}")
+            head = f"- **{p.get('code', '')} {p.get('name', '')}**".rstrip()
+            if meta:
+                head += f" ({' · '.join(meta)})"
+            out.append(head)
+            desc = (p.get("description") or "").strip()
+            if desc:
+                out.append(f"  - {desc}")
+        return out
+
+    # ── Markdown brief (human / LLM-readable) ────────────────────────────────
+    def to_markdown(self) -> str:
+        parts = [
+            f"# Memory Context Pack — {self.owner}",
+            "",
+            f"> query: \"{self.query}\" · generated: {self.generated_at or 'n/a'} "
+            f"· {len(self.episodes)} episode(s) · {len(self.learner_model)} learning-pattern(s)",
+            "> Portable memory brief for ingestion into an external AI. "
+            "Source: weg-9000-memory.",
+            "",
+        ]
+        if not self.episodes:
+            parts.append("_(no episodes in scope)_")
+        for ep in self.episodes:
+            pin = " 📌" if ep.get("pinned") else ""
+            tags = ep.get("tags") or []
+            meta = [f"date: {ep.get('date', 'n/a')}"]
+            if ep.get("domain"):
+                meta.append(f"domain: {ep['domain']}")
+            if tags:
+                meta.append("tags: " + ", ".join(tags))
+            if ep.get("score") is not None:
+                meta.append(f"score: {ep['score']}")
+            parts.append(f"## {ep.get('title') or ep.get('id', 'untitled')}{pin}")
+            parts.append("- " + " · ".join(meta))
+            summary = (ep.get("summary") or "").strip()
+            if summary:
+                parts += ["", summary]
+            parts += ["", "---", ""]
+        parts += self._learner_section()
+        return "\n".join(parts) + "\n"
+
+    # ── MCP resource manifest (connector contract) ───────────────────────────
+    def to_mcp_manifest(self) -> dict:
+        resources = [
+            {
+                "uri": _uri(self.owner, ep.get("id", "")),
+                "name": ep.get("title") or ep.get("id", ""),
+                "mimeType": "text/markdown",
+                "description": (ep.get("summary") or "")[:120],
+            }
+            for ep in self.episodes
+        ]
+        if self.learner_model:
+            resources.append({
+                "uri": _uri(self.owner, "_learner"),
+                "name": f"learning method ({self.owner})",
+                "mimeType": "text/markdown",
+                "description": f"{len(self.learner_model)} learning pattern(s) — how this person learns",
+            })
+        return {
+            "schemaVersion": MCP_SCHEMA_VERSION,
+            "owner": self.owner,
+            "generated_at": self.generated_at,
+            "resources": resources,
+            "pack": {
+                "uri": _uri(self.owner, "_pack"),
+                "name": f"context pack ({self.owner})",
+                "mimeType": "application/json",
+                "description": f"{len(self.episodes)} episode(s), query=\"{self.query}\"",
+            },
+        }
+
+
+def build_context_pack(rows: list[dict], *, owner: str, query: str = "",
+                       generated_at: str | None = None,
+                       learner_model: list[dict] | None = None,
+                       theme_id: str | None = None,
+                       vocabulary: list[dict] | None = None) -> ContextPack:
+    """Assemble a ContextPack from recall rows (pure). ``learner_model`` is the
+    person's LearnerPattern rows (how they learn) — carried so an export is "my
+    learning *and how I learn it*". ``vocabulary`` (authored 만) 은 주제 타입 어휘를
+    함께 이전한다 — 어휘는 소유·이전 단위(THESIS T4·D11-R2 §8)."""
+    episodes = [dict(r) for r in rows]
+    return ContextPack(owner=owner, query=query, generated_at=generated_at,
+                       episodes=episodes, learner_model=[dict(p) for p in (learner_model or [])],
+                       theme_id=theme_id, vocabulary=[dict(t) for t in (vocabulary or [])])
+
+
+def write_pack(pack: ContextPack, out_dir: str | Path) -> dict:
+    """Write pack.md / pack.json / mcp.json into ``out_dir``. Returns the paths."""
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    md_path = out / "pack.md"
+    json_path = out / "pack.json"
+    mcp_path = out / "mcp.json"
+    md_path.write_text(pack.to_markdown(), encoding="utf-8")
+    json_path.write_text(json.dumps(pack.to_json(), ensure_ascii=False, indent=2), encoding="utf-8")
+    mcp_path.write_text(json.dumps(pack.to_mcp_manifest(), ensure_ascii=False, indent=2), encoding="utf-8")
+    return {"markdown": str(md_path), "json": str(json_path), "mcp": str(mcp_path)}
+
+
+# ── Public entry point ───────────────────────────────────────────────────────
+
+def activate(query: str = "", *, owner: str, tenant: str | None = None,
+             domain: str | None = None, workspace: str | None = None,
+             tags: list[str] | None = None, rank: str = "preference", limit: int = 20,
+             include_model: bool = False,
+             generated_at: str | None = None, out_dir: str | Path | None = None,
+             theme_id: str | None = None, themes=None,
+             cfg=None, store=None) -> dict:
+    """Recall owner-scoped records and build a portable context pack.
+
+    ``domain`` (free, user-defined) optionally scopes the pack to one dataset
+    partition; omit to export across all of the owner's domains. Defaults to
+    ``rank="preference"`` — an export leads with the owner's preference signals.
+
+    ``include_model`` (**default False** — Vinc 기본 export 은 learner 섹션 부재:
+    설계 §13 D6 · WO §3 F6, 학습 프레이밍 미승계 §1). 마이그레이션(A+2, §10)의
+    무손실 이관 시에만 ``True`` 로 learner 신호(LearnerPattern)를 포함한다 — 이때만
+    pack 에 학습법 섹션이 실린다(D4 는 pack 이 신호를 담을 수 **있게** 하는 것이지
+    기본 노출이 아니다). Preference 신호(pinned/tags/access_count/last_access)는
+    rank 무관 항상 수록된다(§10·D4). Writes three files when ``out_dir`` given."""
+    res = q.recall(query, owner=owner, tenant=tenant, domain=domain,
+                   workspace=workspace, tags=tags, rank=rank, limit=limit, cfg=cfg, store=store)
+    model_rows = (q.learner_model(owner=owner, cfg=cfg, store=store).get("rows", [])
+                  if include_model else [])
+    # 주제 어휘 동봉(선택) — **authored 만**. proposed(재가 전)는 팩에 실리지 않는다
+    # (THESIS §6 잠정상태 · D11-R2 수용기준). 단일 필터 라인.
+    vocabulary = ([t for t in themes.list_types(theme_id) if t.get("status") == "authored"]
+                  if (theme_id and themes is not None) else None)
+    pack = build_context_pack(res.get("rows", []), owner=owner, query=query,
+                              generated_at=generated_at, learner_model=model_rows,
+                              theme_id=theme_id, vocabulary=vocabulary)
+    out: dict = {
+        "owner": owner,
+        "episode_count": len(pack.episodes),
+        "learner_pattern_count": len(pack.learner_model),
+        "executed": res.get("executed", False),
+    }
+    if out_dir is not None:
+        out["written"] = write_pack(pack, out_dir)
+    else:
+        out["pack"] = {
+            "markdown": pack.to_markdown(),
+            "json": pack.to_json(),
+            "mcp": pack.to_mcp_manifest(),
+        }
+    return out

vinc/_runtime/api/auth.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""로컬 로그인 코어 — 온보딩 프로필 + 세션 토큰(설계 [[vinc.spec.architecture §4]], F4).
+
+Vinc 는 단일 사용자·오프라인 앱이다. "로그인"은 외부 인증 서버 왕복이 아니라
+**로컬 자격 파일에 대한 패스프레이즈 검증**이다(F4 — 네트워크 왕복 없음). 검증에
+성공하면 사이드카가 임의 **세션 토큰**을 발급하고, 데스크톱 셸(Tauri)이 이후 모든
+HTTP 요청에 ``Authorization: Bearer <token>`` 로 실어 보낸다. 루프백 바인딩
+(127.0.0.1) + 토큰이 이중 방어다(§3-1).
+
+자격 해시는 **argon2id**(설계 §3-1 명시)로, ``argon2-cffi`` 옵션 extra(``vinc[server]``)
+에서 lazy-import 한다 — 코어는 의존성 0(F5: 키 없이 기동). 미설치 환경에선 온보딩·
+패스프레이즈 검증만 불가하고(명확한 오류) 앱 기동·조회는 그대로 동작한다.
+
+토큰 발급·검증은 stdlib ``secrets`` 만 쓴다(argon2 불요) — 어떤 경로도 소켓을 열지
+않는다(F4 실측: 소켓 차단 하에서도 동작).
+"""
+from __future__ import annotations
+
+import json
+import secrets
+from pathlib import Path
+
+# argon2id 파라미터(자격 파일 헤더에 함께 저장 — 재해시 없이 검증 가능).
+# 대화형 로그인 1회 검증 기준의 보수적 기본값. (RFC 9106 2nd 권장 근방.)
+_ARGON2_TIME_COST = 3
+_ARGON2_MEMORY_COST = 64 * 1024   # 64 MiB
+_ARGON2_PARALLELISM = 4
+
+_CRED_KIND = "vinc/local-credential"
+
+
+class AuthUnavailable(RuntimeError):
+    """argon2 extra 미설치 — 온보딩/패스프레이즈 검증 불가(``pip install vinc[server]``)."""
+
+
+def _argon2():
+    """argon2 PasswordHasher 를 lazy-import(코어 의존성 0 유지 — F5). 미설치 시
+    :class:`AuthUnavailable`."""
+    try:
+        from argon2 import PasswordHasher, Type
+    except ImportError as exc:   # pragma: no cover - 설치 여부에 따라
+        raise AuthUnavailable(
+            "argon2id 자격에는 'vinc[server]' extra 가 필요하다 "
+            "(pip install argon2-cffi). 코어·조회는 이것 없이 동작한다."
+        ) from exc
+    return PasswordHasher(time_cost=_ARGON2_TIME_COST, memory_cost=_ARGON2_MEMORY_COST,
+                          parallelism=_ARGON2_PARALLELISM, type=Type.ID)
+
+
+def cred_path(data_dir: str | Path) -> Path:
+    """자격 파일 경로. 데이터 디렉토리 옆 ``auth.json``(§3-2 — 데이터·설정 동거)."""
+    return Path(data_dir).parent / "auth.json"
+
+
+# ── 온보딩 / 검증 ────────────────────────────────────────────────────────────
+
+def create_profile(passphrase: str, *, path: str | Path, force: bool = False) -> dict:
+    """온보딩: 패스프레이즈를 argon2id 로 해시해 자격 파일을 만든다(1회). 이미
+    있으면 ``force`` 없이 덮어쓰지 않는다(계정 유실 방지)."""
+    p = Path(path)
+    if p.exists() and not force:
+        raise FileExistsError(f"자격 파일 이미 존재: {p} (재설정은 force=True)")
+    if not passphrase:
+        raise ValueError("빈 패스프레이즈 금지")
+    ph = _argon2()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"kind": _CRED_KIND, "algo": "argon2id", "hash": ph.hash(passphrase)}
+    p.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    # 자격 파일은 소유자만 읽도록(단일 사용자 데스크톱 — §3-3).
+    try:
+        p.chmod(0o600)
+    except OSError:
+        pass
+    return {"created": str(p), "algo": "argon2id"}
+
+
+def verify_passphrase(passphrase: str, *, path: str | Path) -> bool:
+    """패스프레이즈를 자격 파일과 대조(로컬만 — 네트워크 왕복 없음, F4). 파일
+    부재·불일치 시 False. argon2 미설치 시 :class:`AuthUnavailable`."""
+    p = Path(path)
+    if not p.exists():
+        return False
+    from argon2.exceptions import VerifyMismatchError  # lazy — extra 없으면 아래 _argon2 가 먼저 raise
+    ph = _argon2()
+    try:
+        stored = json.loads(p.read_text(encoding="utf-8")).get("hash", "")
+    except (OSError, ValueError):
+        return False
+    try:
+        return bool(ph.verify(stored, passphrase))
+    except VerifyMismatchError:
+        return False
+    except Exception:   # noqa: BLE001 - 손상 해시 등은 인증 실패로 취급
+        return False
+
+
+# ── 세션 토큰 ────────────────────────────────────────────────────────────────
+
+def issue_token(nbytes: int = 32) -> str:
+    """새 세션 토큰 발급(stdlib secrets — 소켓 없음, F4). 프로세스 수명 동안만 유효."""
+    return secrets.token_urlsafe(nbytes)
+
+
+class SessionAuth:
+    """사이드카 세션 토큰 보관·검증. 기동 시 1개 발급, 셸에 전달. 모든 요청의
+    ``Authorization: Bearer`` 헤더를 상수시간 비교한다."""
+
+    def __init__(self, token: str | None = None):
+        self.token = token or issue_token()
+
+    def check_header(self, header_value: str | None) -> bool:
+        """``Authorization`` 헤더 값이 세션 토큰과 일치하는지(Bearer 스킴). 상수시간
+        비교(secrets.compare_digest)로 타이밍 누출 방지."""
+        if not header_value:
+            return False
+        parts = header_value.split(None, 1)
+        if len(parts) != 2 or parts[0].lower() != "bearer":
+            return False
+        return secrets.compare_digest(parts[1], self.token)

vinc/_runtime/api/backup.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""일관 스냅샷 백업(설계 [[vinc.spec.architecture §5]], R9).
+
+``vinc backup`` 은 (1) 스토어 데이터 디렉토리의 일관 스냅샷 + (2) ``packs/``(내보낸
+컨텍스트 팩)·``profile.yml``(도메인 프로필) 을 한 아카이브 디렉토리에 모은다 —
+사용자가 자기 데이터를 통째로 이관·보존할 수 있는 단일 통로(R9).
+
+**쓰기 정지의 책임**: ``EmbeddedBackend.snapshot`` 은 데이터 디렉토리를 그대로
+복사할 뿐 쓰기를 멈추지 않는다. 일관성은 **잡 큐가 보장**한다 — backup 은 잡으로
+실행되고, 워커는 하나뿐이라 backup 이 도는 동안 다른 쓰기 잡을 처리하지 않는다
+(설계 §11 P2, `store.embedded_backend.snapshot` docstring). 그래서 이 함수는 반드시
+워커 스레드에서(=JobQueue 경유) 호출되어야 한다.
+
+stdlib 전용(``shutil``·``pathlib``).
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+def make_backup(store, out_dir: str | Path, *, packs_dir: str | Path | None = None,
+                profile_path: str | Path | None = None) -> dict:
+    """스토어 스냅샷 + packs·profile 을 ``out_dir`` 아래로 모은다. 반환은 포함 항목
+    경로 맵. **워커 스레드에서 호출**(쓰기 정지 보장 — 위 모듈 docstring)."""
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    # (1) 스토어 데이터 디렉토리 일관 스냅샷(§3-1-1). 쓰기 정지는 잡 큐가 보장.
+    store_dest = store.snapshot(str(out))
+
+    included: dict[str, str] = {"store": store_dest}
+
+    # (2) 내보낸 컨텍스트 팩 동봉(있으면).
+    if packs_dir is not None:
+        src = Path(packs_dir)
+        if src.is_dir():
+            dest = out / "packs"
+            shutil.copytree(src, dest, dirs_exist_ok=True)
+            included["packs"] = str(dest)
+
+    # (3) 도메인 프로필 동봉(있으면).
+    if profile_path is not None:
+        src = Path(profile_path)
+        if src.is_file():
+            dest = out / src.name
+            shutil.copy2(src, dest)
+            included["profile"] = str(dest)
+
+    return {"archive": str(out), "included": included}

vinc/_runtime/api/changes.py

@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""변경 표식 — 열린 화면이 "그 뒤로 이 그래프에 쓰기가 있었나"를 싸게 묻는 값(VIN-129).
+
+화면은 이 값을 몇 초마다 읽고, 지난번과 다르면 지금 보던 것을 다시 부른다. 그래서
+MCP 가 쓴 것이 갱신 버튼 없이 열린 View 에 나타난다(웹과 데스크톱 계정 모드 둘 다).
+
+**세는 곳은 사이드카의 쓰기 관문이다**(`api.server` 의 POST 처리). 이 값은 데이터가
+아니라 "쓰기 요청이 성공했다"를 센다:
+
+  - 소유자별이다. 허브는 모든 사람의 그래프를 한 프로세스에서 돌리므로, 전역 번호면
+    누가 쓰든 모든 열린 화면이 다시 그려진다.
+  - 메모리에만 있다. 읽기가 스토어를 전혀 안 건드리므로 폴링이 허브의 단일 writer 에
+    짐을 얹지 않는다. 값 앞에 프로세스마다 새로 뽑는 세대(epoch)를 붙여, 재시작하면
+    표식이 바뀐다. 재시작은 쓰기를 되감을 수 있으므로(스냅샷 창) 그때 다시 읽는 것이 맞다.
+  - 비교만 한다. 값의 크기나 차이에는 뜻이 없다. 같으면 그대로, 다르면 다시 읽는다.
+
+⚠ 여기서 멀티 레플리카를 가정하지 않는다. 임베디드 스토어는 단일 writer 라 쓰기를
+받는 프로세스가 하나뿐이고, 표식도 그 프로세스 하나가 센다.
+근거: [[record:the-change-marker-is-counted-at-the-sidecar-write-gate-2026-09-24]]
+"""
+from __future__ import annotations
+
+import secrets
+import threading
+from typing import Callable
+
+#: 소유자 없이 들어온 쓰기의 칸. 어느 소유자의 표식에도 더해진다: 누구의 것인지
+#: 모르는 쓰기를 한 사람에게만 알리면 나머지가 놓친다(더 자주 다시 읽는 편이 안전측).
+ANY = "*"
+
+
+class ChangeMarker:
+    """소유자별 쓰기 세대. 스레드 안전(HTTP 핸들러 스레드와 잡 워커가 같이 쓴다)."""
+
+    def __init__(self) -> None:
+        self._epoch = secrets.token_hex(4)
+        self._n: dict[str, int] = {}
+        self._pending: list = []   # (owner, Job, changed) — 끝나면 센다
+        self._lock = threading.Lock()
+
+    def bump(self, owner: str | None) -> None:
+        key = owner or ANY
+        with self._lock:
+            self._n[key] = self._n.get(key, 0) + 1
+
+    def bump_when_done(self, owner: str | None, job,
+                       changed: Callable[[dict], bool] | None = None) -> None:
+        """비동기 잡(202)은 **끝난 뒤에** 센다. 접수 때 세면 화면이 데이터가 들어오기
+        전에 다시 읽고, 그 뒤로 표식이 안 바뀌어 결과가 영영 안 나타난다.
+
+        ``changed`` 는 성공한 결과를 보고 셀지 정한다. 주기적으로 도는 잡(동기화)이
+        아무것도 안 받았을 때까지 세면, 열린 화면이 10분마다 까닭 없이 다시 그려진다.
+
+        스레드를 따로 두지 않는다. 표식을 읽을 때 끝난 잡을 걷어 센다(`read`)."""
+        if job is None:
+            return
+        with self._lock:
+            self._pending.append((owner or ANY, job, changed))
+
+    def _settle(self) -> None:
+        """끝난 잡을 센다. 호출부가 락을 쥔 상태여야 한다."""
+        if not self._pending:
+            return
+        keep = []
+        for owner, job, changed in self._pending:
+            done = getattr(job, "_done", None)
+            if done is None or not done.is_set():
+                keep.append((owner, job, changed))
+                continue
+            # 실패로 끝난 잡은 판정 없이 센다. 중간까지 쓰고 실패했을 수 있고, 다시
+            # 읽어서 손해 볼 것은 왕복 한 번이다. 판정이 터져도 같은 쪽으로 기운다.
+            count = True
+            if changed is not None and getattr(job, "status", "") != "error":
+                try:
+                    count = bool(changed(getattr(job, "result", None) or {}))
+                except Exception:   # noqa: BLE001
+                    count = True
+            if count:
+                self._n[owner] = self._n.get(owner, 0) + 1
+        self._pending = keep
+
+    def read(self, owner: str | None) -> str:
+        """이 소유자의 표식. 소유자 없는 쓰기(`ANY`)도 함께 센다."""
+        with self._lock:
+            self._settle()
+            n = self._n.get(owner or ANY, 0)
+            if owner and owner != ANY:
+                n += self._n.get(ANY, 0)
+            return f"{self._epoch}.{n}"
+
+
+#: 성공해도 **화면에 보이는 것을 바꾸지 않는** 쓰기. 여기 없는 쓰기는 전부 센다
+#: (새 라우트를 더하고 잊으면 한 번 더 다시 읽을 뿐이고, 반대로 빠뜨리면 화면이 낡는다).
+#:
+#:   /touch            조회 빈도 신호. 노드를 열 때마다 앱이 부른다. 세면 노드를 누를
+#:                     때마다 지도가 다시 그려진다
+#:   /doc/reembed      재임베딩 대기 표식만 세운다
+#:   /embed/apply      임베딩 워커의 결과. 허브에서 쉬지 않고 돈다
+#:   /node-mirror/rebuild  배포 경계의 색인 재구축(그때는 세대가 이미 바뀌었다)
+#:   /backup           파일을 만들 뿐이다
+#:   /sync/domains     동기화할 주제 선택. 그래프는 그대로다
+#:   /connect/start    기기 연결 논스
+#:   /space/proxy      계정으로 나가는 통과로. 이 스토어에 쓰지 않는다(표식은 계정 쪽
+#:                     허브가 센다)
+#:   /conventions/build  GRAPH.md 재생성. 그래프가 아니다
+QUIET_WRITES = frozenset({
+    "/touch", "/doc/reembed", "/embed/apply", "/node-mirror/rebuild", "/backup",
+    "/sync/domains", "/connect/start", "/space/proxy", "/conventions/build",
+    # 저장 설정(그래프 밖 파일)과 전량 올리기(이 스토어를 안 바꾼다), VIN-130.
+    "/config", "/sync/push-all", "/shutdown",
+})
+
+
+def counts(path: str) -> bool:
+    """이 POST 가 성공하면 표식을 올리는가."""
+    return path not in QUIET_WRITES
+
+
+def sync_brought_something(result: dict) -> bool:
+    """동기화 세션(`api.sync.run`)이 이 스토어에 무엇이든 들였는가. 올려 보내기만 한
+    세션은 이 기기의 그래프를 바꾸지 않는다."""
+    pull = result.get("pull") or {}
+    docs = result.get("docs_pull") or {}
+    moved = sum(int(pull.get(k) or 0) for k in ("applied", "deleted"))
+    moved += sum(int(docs.get(k) or 0) for k in ("applied", "updated", "deleted"))
+    return moved > 0 or bool(result.get("birth_resync")) \
+        or bool(result.get("account_switched"))