vincs 0.1.0__tar.gz

vincs-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+# 예외: 디자인 허브 산출물은 **계약**이라 추적한다. 소비 리포의 사본
+# (app/src/tokens.*.css·theme.ts)이 커밋돼 있으므로 그 비교 대상도 리포에 있어야
+# `sync_out.py --check`(CI 드리프트 게이트)가 성립한다. 없으면 게이트가
+# "[MISSING·허브]" 로 죽는다 — 2026-08-08 CI 실패의 원인.
+!design-hub/dist/
+# 단, Claude Design 푸시 번들은 제외 — 업로드 직전에 만드는 임시 산출물이고
+# 대조할 커밋된 소비 사본이 없다(그쪽은 claude.ai 프로젝트에 산다).
+design-hub/dist/claude-design/
+build/
+*.egg-info/
+models/
+vinc_store
+*.lbug
+vinc_e2e/
+node_modules/
+app/src-tauri/target/
+app/src-tauri/binaries/
+app/src-tauri/gen/
+# .claude/ 는 기기별 설정(launch.json·ui-events.jsonl·worktrees)이라 **어느 깊이에서도**
+# 추적하지 않는다. 예외는 이제 없다. 역할 껍데기는 `agents/shells/` 에서 추적되고
+# (`agents_sync.py --check` 가 CI 에서 대조), 하네스가 읽는 사본은 리포 밖 워크스페이스
+# 루트에 `--install` 이 쓴다. 리포 안 `.claude/agents` 는 체크아웃의 브랜치를 따라
+# 수가 달라지는 두 번째 로스터였다.
+# ⚠ 전에는 루트의 `.claude/agents/` 만 되살리려고 네 줄을 겹쳐 썼다(한 줄로는 예외가
+# 사문이 되거나 `_migration/**/.claude/` 중첩본이 새어 나갔다, 2026-08-23 PR #69).
+# 예외가 사라졌으니 모든 깊이를 잡는 이 한 줄이면 된다.
+.claude/
+# 서명·접속 키 — 커밋되면 되돌릴 수 없다. 지금 키들은 리포 **바깥**(워크스페이스
+# 루트)에 있어 커밋된 적이 없지만, 누가 안으로 옮겨도 막히도록 패턴을 박아 둔다.
+# 업데이터 개인키를 잃으면 배포된 전 사용자가 자동 업데이트에서 영구 이탈한다
+# (복구 경로 없음 — DEPLOYMENT.md §1.6 백업 절차 참조).
+*.key
+*.pem
+*.p12
+*.pfx
+
+# uv 캐시 락파일 — 로컬 테스트 실행(`uv run`)이 만든다. 정본 의존성은
+# pyproject.toml 이고, 이 락은 기기별 파생물이라 추적하지 않는다.
+uv.lock
+
+# 평가·리허설 부산물 — 모델 가중치 수백 MB 가 여기 앉는다.
+# 이 워킹트리는 세션 공유라 남의 `git add -A` 가 이것을 집는다.
+.cache/
+work/
+
+# design-hub capture PNGs are build products of scripts/capture_*.mjs; the manifests are committed
+design-hub/reports/captures/**/*.png

vincs-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: vincs
+Version: 0.1.0
+Summary: Vinc Python SDK, framework integrations and terminal CLI
+Project-URL: Homepage, https://vincs.io
+Project-URL: Documentation, https://vincs.io/docs/
+Author: Vinculums
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: agent-framework
+Requires-Dist: agent-framework-core>=1.8.1; extra == 'agent-framework'
+Provides-Extra: all
+Requires-Dist: agent-framework-core>=1.8.1; extra == 'all'
+Requires-Dist: langchain-core>=1.0; extra == 'all'
+Requires-Dist: langchain>=1.0; extra == 'all'
+Requires-Dist: langgraph>=1.0; extra == 'all'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=1.0; extra == 'langgraph'
+Requires-Dist: langchain>=1.0; extra == 'langgraph'
+Requires-Dist: langgraph>=1.0; extra == 'langgraph'
+Provides-Extra: test
+Requires-Dist: anyio>=4; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Vinc for Python and the terminal
+
+Install the SDK and the `vinc` command together:
+
+```sh
+pip install vincs
+vinc --help
+vinc --version
+```
+
+Use the account graph from the terminal with a member key created in your Vinc
+account. Set `VINC_API_KEY` in your environment, then run:
+
+```sh
+vinc --target account whoami
+vinc --target account search --query "release checklist"
+```
+
+The account CLI uses the same commands and error handling as the desktop's CLI.
+This Python install does not bundle the native local database, extensions or
+embedding model. For a self-contained local CLI, use the signed terminal download
+from [the CLI installation guide](https://vincs.io/docs/cli/#install).
+
+```python
+from vinc import Vinc, AsyncVinc
+
+client = Vinc()  # reads VINC_API_KEY
+answer = client.brief("release checklist")
+```
+
+Choose integrations using one package name:
+
+```sh
+pip install "vincs[langgraph]"
+pip install "vincs[agent-framework]"
+pip install "vincs[all]"
+```
+
+```python
+from vinc.integrations.langgraph import get_vinc_context
+from vinc.integrations.agent_framework import VincContextProvider
+```
+
+These modules are built from the same source as `vinc-client`, `vinc-langgraph`
+and `vinc-agent-framework`. Existing installations and imports keep working;
+the unified package does not overwrite their files. Framework imports require
+the corresponding extra. Importing the base SDK does not load a framework or
+start a local database. No conversation is automatically written to Vinc.
+
+The Python distribution version is independent of the product version reported
+by `vinc --version`. See the [SDK guide](https://vincs.io/docs/frameworks/) for
+key types, read-only use and explicit writes.

vincs-0.1.0/README.md

@@ -0,0 +1,52 @@
+# Vinc for Python and the terminal
+
+Install the SDK and the `vinc` command together:
+
+```sh
+pip install vincs
+vinc --help
+vinc --version
+```
+
+Use the account graph from the terminal with a member key created in your Vinc
+account. Set `VINC_API_KEY` in your environment, then run:
+
+```sh
+vinc --target account whoami
+vinc --target account search --query "release checklist"
+```
+
+The account CLI uses the same commands and error handling as the desktop's CLI.
+This Python install does not bundle the native local database, extensions or
+embedding model. For a self-contained local CLI, use the signed terminal download
+from [the CLI installation guide](https://vincs.io/docs/cli/#install).
+
+```python
+from vinc import Vinc, AsyncVinc
+
+client = Vinc()  # reads VINC_API_KEY
+answer = client.brief("release checklist")
+```
+
+Choose integrations using one package name:
+
+```sh
+pip install "vincs[langgraph]"
+pip install "vincs[agent-framework]"
+pip install "vincs[all]"
+```
+
+```python
+from vinc.integrations.langgraph import get_vinc_context
+from vinc.integrations.agent_framework import VincContextProvider
+```
+
+These modules are built from the same source as `vinc-client`, `vinc-langgraph`
+and `vinc-agent-framework`. Existing installations and imports keep working;
+the unified package does not overwrite their files. Framework imports require
+the corresponding extra. Importing the base SDK does not load a framework or
+start a local database. No conversation is automatically written to Vinc.
+
+The Python distribution version is independent of the product version reported
+by `vinc --version`. See the [SDK guide](https://vincs.io/docs/frameworks/) for
+key types, read-only use and explicit writes.

vincs-0.1.0/hatch_build.py

@@ -0,0 +1,50 @@
+"""Assemble the unified distribution from the canonical repository packages."""
+from __future__ import annotations
+
+import re
+import tempfile
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        root = Path(self.root)
+        # sdist 에는 이미 조립된 소스가 있다. 저장소 밖에서 다시 빌드할 수 있어야 한다.
+        if (root / "src/vinc/sdk/client.py").is_file():
+            return
+        repo = root.parents[2]
+        sources = {
+            "sdk": repo / "integrations/client/python/src/vinc_client",
+            "integrations/langgraph": repo / "integrations/langgraph/python/src/vinc_langgraph",
+            "integrations/agent_framework": repo / "integrations/agent-framework/python/src/vinc_agent_framework",
+            **{f"_runtime/{name}": repo / name
+               for name in ("api", "store", "engines", "vinc_mcp", "vinc_rag")},
+        }
+        self._stage = tempfile.TemporaryDirectory(prefix="vincs-build-")
+        stage = Path(self._stage.name)
+        prefix = "src/vinc" if self.target_name == "sdist" else "vinc"
+        for destination, source in sources.items():
+            if not source.is_dir():
+                raise RuntimeError(f"canonical package source missing: {source}")
+            for path in sorted(source.rglob("*")):
+                if not path.is_file() or "__pycache__" in path.parts:
+                    continue
+                if path.suffix not in {".py", ".json"} and path.name != "py.typed":
+                    continue
+                relative = Path(destination) / path.relative_to(source)
+                target = stage / relative
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if path.suffix == ".py" and destination.startswith("integrations/"):
+                    # 별도 배포판의 파일을 덮어쓰지 않고 같은 SDK 소스에 연결한다.
+                    text = path.read_text(encoding="utf-8")
+                    text = re.sub(r"(?m)^(from\s+)vinc_client(?=[.\s])", r"\1vinc.sdk", text)
+                    target.write_text(text, encoding="utf-8")
+                else:
+                    target.write_bytes(path.read_bytes())
+                build_data["force_include"][str(target)] = f"{prefix}/{relative.as_posix()}"
+
+    def finalize(self, version, build_data, artifact_path):
+        if hasattr(self, "_stage"):
+            self._stage.cleanup()

vincs-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vincs"
+version = "0.1.0"
+description = "Vinc Python SDK, framework integrations and terminal CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Vinculums" }]
+dependencies = ["httpx>=0.27,<1", "pydantic>=2.7,<3"]
+
+[project.optional-dependencies]
+langgraph = ["langgraph>=1.0", "langchain-core>=1.0", "langchain>=1.0"]
+agent-framework = ["agent-framework-core>=1.8.1"]
+all = ["vincs[langgraph,agent-framework]"]
+test = ["pytest>=8", "anyio>=4"]
+
+[project.scripts]
+vinc = "vinc.cli:main"
+
+[project.urls]
+Homepage = "https://vincs.io"
+Documentation = "https://vincs.io/docs/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vinc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "pyproject.toml", "README.md", "hatch_build.py", "tests"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vincs-0.1.0/src/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"]

vincs-0.1.0/src/vinc/__main__.py

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

vincs-0.1.0/src/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"]

vincs-0.1.0/src/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

vincs-0.1.0/src/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)