owfadev 0.3.1 → 0.4.0

package/{.meta → .owfa}/scripts/pipeline.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 """Derived-layer post-write pipeline: index / tags / hot / log / verify.
 
-Positioning (.meta/protocol/actions.md execution principles): deterministic structural
+Positioning (.owfa/protocol/actions.md execution principles): deterministic structural
 operations go to this script; semantic judgment goes to the LLM. Rebuild and rolling
 rules and window parameters are governed by this file's source (the script source is
 the rule list); PLUGIN.md keeps the semantic explanation; commands uniformly end by
@@ -11,11 +11,11 @@ post-write self-attestation (the minimal attester form): the LLM executes, the s
 certifies.
 
 Usage:
-  python .meta/scripts/pipeline.py index              # rebuild indexes (overflow-offloading scheme, idempotent; includes deleting surplus indexes after merging back)
-  python .meta/scripts/pipeline.py tags               # rebuild wiki/tags.md (idempotent)
-  python .meta/scripts/pipeline.py hot <type> <one-liner>   # evict out-of-window entries + prepend a hot-cache entry
-  python .meta/scripts/pipeline.py log <type> <one-liner> [--domain domain]   # capacity archive + prepend a log line (domain tag optional — domainless transactions)
-  python .meta/scripts/pipeline.py verify             # post-write self-attestation: attached audits + derived-area drift check
+  python .owfa/scripts/pipeline.py index              # rebuild indexes (overflow-offloading scheme, idempotent; includes deleting surplus indexes after merging back)
+  python .owfa/scripts/pipeline.py tags               # rebuild wiki/tags.md (idempotent)
+  python .owfa/scripts/pipeline.py hot <type> <one-liner>   # evict out-of-window entries + prepend a hot-cache entry
+  python .owfa/scripts/pipeline.py log <type> <one-liner> [--domain domain]   # capacity archive + prepend a log line (domain tag optional — domainless transactions)
+  python .owfa/scripts/pipeline.py verify             # post-write self-attestation: attached audits + derived-area drift check
 
 Type enumeration: map / save / query / check / plugin / todo / profile / other (the log plugin).
 Concept-page determination (what enters the index): all .md under wiki/, excluding —
@@ -54,9 +54,9 @@ LOG_MAX_ENTRIES = 100
 INDEX_MAX_ENTRIES = 25  # single index-list window (page entries + directory entries; overflow-offloading split basis)
 TYPE_ORDER = ["map", "save", "query", "check", "plugin", "todo", "profile", "other"]
 HOT_HEADER = ("# 热缓存\n\n> 最近变更摘要；≤25 条且 <5 日，窗外即删；可整体再生。"
-              "规则见 `.meta/plugins/hot/`，写走 `pipeline.py hot`。\n")
+              "规则见 `.owfa/plugins/hot/`，写走 `pipeline.py hot`。\n")
 LOG_HEADER = ("# 运行日志\n\n> 置顶追加、只增不删；条目 = `- YYYY-MM-DD <类型> [<域>]：一句话`（域标可缺省——无域事务，log 桥）。"
-              "规则见 `.meta/plugins/log/`，写走 `pipeline.py log`。\n")
+              "规则见 `.owfa/plugins/log/`，写走 `pipeline.py log`。\n")
 DATE_RE = re.compile(r"^- (\d{4}-\d{2}-\d{2}) ")
 
 
@@ -391,7 +391,7 @@ def do_log(kind, text, domain=None):
 def do_verify():
     ok = True
     r = subprocess.run(
-        [sys.executable, os.path.join(os.path.dirname(os.path.abspath(__file__)), "wiki_plugin_kernel.py"), "audit"])
+        [sys.executable, os.path.join(os.path.dirname(os.path.abspath(__file__)), "owfa_kernel.py"), "audit"])
     if r.returncode != 0:
         ok = False
         print("[verify] plugin audit has errors")

package/.owfa/scripts/wiki_plugin_kernel.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Deprecation shim: the kernel was renamed owfa_kernel.py (0.4 layout).
+
+Keeps 0.3-era paths and muscle memory working through the 0.4 cycle; the shim
+is scheduled for removal in 0.5. The real entry is owfa_kernel.py next to it.
+"""
+import os
+import runpy
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+print("[deprecated] wiki_plugin_kernel.py -> owfa_kernel.py (shim retires in 0.5)", file=sys.stderr)
+sys.argv[0] = os.path.join(_HERE, "owfa_kernel.py")
+runpy.run_path(os.path.join(_HERE, "owfa_kernel.py"), run_name="__main__")

package/{.meta → .owfa}/scripts/wikilib.py

@@ -3,9 +3,9 @@
 """Wiki page-service load-bearing piece: frontmatter parsing and page traversal, assembled into ctx for the attached-audit runtime.
 
 Plugin attached-audit scripts do not import this module themselves —
-wiki_plugin_kernel.audit scans wiki/ in a single pass and puts the (relative path,
+owfa_kernel.audit scans wiki/ in a single pass and puts the (relative path,
 frontmatter, body) list into ctx.pages for everyone to share (frugal invocation).
-The same minimal YAML subset as wiki_plugin_kernel.parse_manifest, but with a
+The same minimal YAML subset as owfa_kernel.parse_manifest, but with a
 different tolerance policy: manifests fail loudly (protocol artifacts), page
 frontmatter skips bad lines (user content must not crash attached audits over
 format blemishes). Keys are lenient (anything non-blank and colon-free):

package/.owfa/tests/test_capabilities.py

@@ -0,0 +1,311 @@
+"""v0.4 capability (needs/provides) + suite-kind + INDEX-extension unit tests.
+
+Synthetic packages and disposable instances only; registry-channel cases use a
+local git repo + a local ROOT/INDEX.yaml (load_index reads the local file first,
+so no network is ever touched).
+
+Run: python -m unittest discover -s .owfa/tests -p test_capabilities.py -v
+"""
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+FRAMEWORK = Path(__file__).resolve().parents[2]
+
+
+class CapabilityTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory(prefix="kernel-cap-test-")
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name) / "instance"
+        self.root.mkdir()
+        for directory in (".owfa", ".agents"):
+            shutil.copytree(FRAMEWORK / directory, self.root / directory,
+                            ignore=shutil.ignore_patterns("__pycache__", "tests", "smoke-tmp"))
+        (self.root / "AGENTS.md").write_text(
+            "# Synthetic instance\n<!-- wiki-inject:start -->\n<!-- wiki-inject:end -->\n",
+            encoding="utf-8")
+        self.source = Path(self.temp.name) / "source"
+        self.source.mkdir()
+        self.env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1", PYTHONIOENCODING="utf-8")
+        self.env.pop("PYTHONPATH", None)
+        # v0.4 final shape: the framework tree ships no plugins — the synthetic
+        # instances bootstrap exactly like a real init (embedded personal suite)
+        result = self.run_kernel("install", "personal", "--path", str(FRAMEWORK / "payloads" / "personal"))
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        result = self.run_kernel("all")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def run_kernel(self, *args):
+        return subprocess.run(
+            [sys.executable, str(self.root / ".owfa/scripts/owfa_kernel.py"), *args],
+            cwd=self.root, env=self.env, capture_output=True, text=True, encoding="utf-8")
+
+    # ---- synthetic package builders ----
+
+    def manifest(self, name, inject, depends="[domain, wiki, trust, log]", parent=None):
+        directory = (parent or self.source) / name
+        directory.mkdir(parents=True, exist_ok=True)
+        dependencies = "".join(f"  - {item.strip()}\n" for item in depends.strip("[]").split(","))
+        (directory / "PLUGIN.yaml").write_text(
+            f"id: {name}\nschema_version: 1\nversion: 0.1\nupdated: 2026-11-12\n"
+            f"depends:\n{dependencies}attachment: []\nfields:\n"
+            f"inject: {json.dumps(inject, ensure_ascii=False)}\n", encoding="utf-8")
+        (directory / "PLUGIN.md").write_text("# Synthetic test plugin\n", encoding="utf-8")
+
+    def pkg_dir(self, pid, caps="", version="0.1"):
+        """A package root self.source/<pid>pkg/ holding PKG.yaml + the member dir."""
+        directory = self.source / f"{pid}pkg"
+        if not (directory / pid).exists():
+            self.manifest(pid, f"{pid} synthetic member", parent=directory)
+        lines = ["schema_version: 1", f"id: {pid}", f"version: {version}", "compat: '>= 0.3'",
+                 f"members: [{pid}]", "depends: [framework]"]
+        lines += [l for l in caps.splitlines() if l.strip()]
+        (directory / "PKG.yaml").write_text("\n".join(lines) + "\n", encoding="utf-8")
+        return directory
+
+    def install_path(self, pid, *extra):
+        return self.run_kernel("install", pid, "--path", str(self.source / f"{pid}pkg"), *extra)
+
+    def git_pkg(self, pid, version, provides=None, needs=None):
+        """A local git repo package (registry-channel source) + tags; returns the repo path."""
+        repo = Path(self.temp.name) / "git" / pid
+        if repo.exists():
+            shutil.rmtree(repo)
+        repo.mkdir(parents=True)
+        self.manifest(pid, f"{pid} registry member", parent=repo)
+        lines = ["schema_version: 1", f"id: {pid}", f"version: {version}", "compat: '>= 0.3'",
+                 f"members: [{pid}]", "depends: [framework]"]
+        if provides:
+            lines.append(f"provides: [{', '.join(provides)}]")
+        if needs:
+            lines.append(f"needs: [{', '.join(needs)}]")
+        (repo / "PKG.yaml").write_text("\n".join(lines) + "\n", encoding="utf-8")
+        self.git(repo, "init", "-q")
+        self.git(repo, "add", "-A")
+        self.git(repo, "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "pkg")
+        self.git(repo, "tag", f"{pid}-v{version}")
+        return repo
+
+    def git(self, repo, *args):
+        r = subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        return r
+
+    def git_head(self, repo):
+        return subprocess.run(["git", "-C", str(repo), "rev-parse", "HEAD"],
+                              capture_output=True, text=True).stdout.strip()
+
+    def index(self, rows):
+        lines = ["packages:"] + [f"  {name}: {{{body}}}" for name, body in rows]
+        (self.root / "INDEX.yaml").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    # ---- grammar / prefix ----
+
+    def test_grammar_and_prefix_rule(self):
+        self.pkg_dir("probe", caps="needs: [Bad.Cap]\nprovides: [other.org.v1]")
+        result = self.install_path("probe")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("fails the capability grammar", result.stdout)
+        self.assertIn("first name segment must equal the package id", result.stdout)
+        self.assertFalse((self.root / ".owfa/plugins/domains/probe").exists())
+        # the prefix message and the grammar message are both reported (one per entry)
+
+    def test_owfa_prefix_and_own_namespace_pass_grammar(self):
+        # owfa.* is the framework-owned namespace; a non-owfa capability named after
+        # the declaring package is the legal third-party form — both pass grammar
+        self.pkg_dir("probe", caps="provides: [probe.transport.v1, owfa.net.v1]")
+        result = self.install_path("probe")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    # ---- exact-name matching ----
+
+    def test_v2_gap_is_reported_as_different_version(self):
+        self.pkg_dir("prov", caps="provides: [owfa.org.v1]")
+        self.assertEqual(self.install_path("prov").returncode, 0)
+        self.pkg_dir("needr", caps="needs: [owfa.org.v2]")
+        result = self.install_path("needr")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("present at different version", result.stdout)
+        self.assertIn("exact-name", result.stdout)
+
+    def test_unknown_capability_is_missing_entirely(self):
+        self.pkg_dir("needr", caps="needs: [owfa.im.v1]")
+        result = self.install_path("needr")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("capability missing entirely", result.stdout)
+        self.assertNotIn("different version", result.stdout)
+
+    # ---- exclusive slot ----
+
+    def test_exclusive_slot_refuses_second_provider(self):
+        self.pkg_dir("alpha", caps="provides: [owfa.org.v1]")
+        self.assertEqual(self.install_path("alpha").returncode, 0)
+        self.pkg_dir("beta", caps="provides: [owfa.org.v1]")
+        result = self.install_path("beta")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("exclusive", result.stdout)
+        self.assertIn("alpha", result.stdout)
+        self.assertIn("beta", result.stdout)
+        self.assertFalse((self.root / ".owfa/plugins/domains/beta").exists())
+
+    # ---- trust gate ----
+
+    def test_unverified_provider_needs_yes_and_journals(self):
+        # provider installed via --path (no INDEX row): provides are unverified
+        self.pkg_dir("prov", caps="provides: [owfa.org.v1]")
+        self.assertEqual(self.install_path("prov").returncode, 0)
+        self.pkg_dir("needr", caps="needs: [owfa.org.v1]")
+        result = self.install_path("needr")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("unverified trust", result.stdout)
+        journal = (self.root / ".owfa/kernel-journal.log").read_text(encoding="utf-8")
+        self.assertNotIn("trust-override", journal)
+        result = self.install_path("needr", "--yes")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        journal = (self.root / ".owfa/kernel-journal.log").read_text(encoding="utf-8")
+        self.assertIn("trust-override needr", journal)
+
+    def test_reviewed_registry_provider_satisfies_needs(self):
+        repo = self.git_pkg("prov", "0.1", provides=["owfa.org.v1"])
+        self.index([("prov", f"repo: {repo}, version: 0.1, trust: reviewed-3rd-party, members: prov")])
+        self.assertEqual(self.run_kernel("install", "prov").returncode, 0)
+        self.pkg_dir("needr", caps="needs: [owfa.org.v1]")
+        result = self.install_path("needr")  # no --yes: the trusted provider satisfies
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    # ---- prospective set (upgrade sole provider) ----
+
+    def test_upgrade_of_sole_provider_passes_prospective_preflight(self):
+        repo = self.git_pkg("prov", "0.1", provides=["owfa.org.v1"])
+        self.index([("prov", f"repo: {repo}, version: 0.1, trust: reviewed-3rd-party, members: prov")])
+        self.assertEqual(self.run_kernel("install", "prov").returncode, 0)
+        self.pkg_dir("needr", caps="needs: [owfa.org.v1]")
+        self.assertEqual(self.install_path("needr").returncode, 0)
+        # bump the provider: v0.2 still provides owfa.org.v1
+        lines = (repo / "PKG.yaml").read_text(encoding="utf-8").replace("version: 0.1", "version: 0.2")
+        (repo / "PKG.yaml").write_text(lines, encoding="utf-8")
+        self.git(repo, "add", "-A")
+        self.git(repo, "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "bump")
+        self.git(repo, "tag", "prov-v0.2")
+        self.index([("prov", f"repo: {repo}, version: 0.2, trust: reviewed-3rd-party, members: prov")])
+        # mid-upgrade the disk briefly lacks the sole provider — the prospective
+        # board (installed − old provides + new provides) must let it through
+        result = self.run_kernel("upgrade", "prov", "--yes")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("0.1 -> v0.2", result.stdout)
+        self.assertEqual(self.run_kernel("validate").returncode, 0)
+
+    # ---- INDEX extension ----
+
+    def test_index_parses_needs_provides_commit_and_strips_single_quotes(self):
+        self.index([
+            ("prov", "repo: 'https://x/y.git', version: 0.1, trust: 'reviewed-3rd-party', "
+                     "members: a/b, needs: owfa.org.v1/qq.im.v1, provides: prov.org.v1/owfa.net.v1, commit: 'ABC123'"),
+            ("bare", 'repo: "https://x/z.git", version: 0.2, trust: framework-bundled, members: z'),
+        ])
+        prefix = "import sys; sys.path.insert(0, '.owfa/scripts'); import owfa_kernel as k; "
+        code = ("e,s=k.load_index([]); import json; "
+                "print(json.dumps({'trust': e['prov']['trust'], 'commit': e['prov'].get('commit'), "
+                "'needs': k._cap_list(e['prov'].get('needs')), "
+                "'provides': k._cap_list(e['prov'].get('provides')), "
+                "'bare_needs': k._cap_list(e['bare'].get('needs')), "
+                "'bare_commit': e['bare'].get('commit')}))")
+        r = subprocess.run([sys.executable, "-c", prefix + code], cwd=self.root,
+                           env=self.env, capture_output=True, text=True, encoding="utf-8")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        data = json.loads(r.stdout)
+        self.assertEqual(data["trust"], "reviewed-3rd-party")  # single quotes stripped
+        self.assertEqual(data["commit"], "ABC123")
+        self.assertEqual(data["needs"], ["owfa.org.v1", "qq.im.v1"])  # '/'-separated
+        self.assertEqual(data["provides"], ["prov.org.v1", "owfa.net.v1"])
+        self.assertEqual(data["bare_needs"], [])                    # absent = empty set
+        self.assertIsNone(data["bare_commit"])                     # absent = no pin
+
+    def test_commit_pin_mismatch_is_refused(self):
+        repo = self.git_pkg("prov", "0.1", provides=["owfa.org.v1"])
+        self.index([("prov", f"repo: {repo}, version: 0.1, trust: reviewed-3rd-party, members: prov, "
+                             f"commit: {'0' * 40}")])
+        result = self.run_kernel("install", "prov")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("commit pin mismatch", result.stdout)
+        self.assertFalse((self.root / ".owfa/plugins/domains/probe").exists())
+
+    def test_commit_pin_match_installs(self):
+        repo = self.git_pkg("prov", "0.1", provides=["owfa.org.v1"])
+        self.index([("prov", f"repo: {repo}, version: 0.1, trust: reviewed-3rd-party, members: prov, "
+                             f"commit: {self.git_head(repo)}")])
+        result = self.run_kernel("install", "prov")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    # ---- suite kind ----
+
+    def test_rootless_suite_validates_green(self):
+        # rootless suite: parallel members, no root plugin — family-root/closure
+        # laws must not apply (the owfa-personal shape; id "synth" — the real
+        # "personal" suite is already installed by the v0.4 bootstrap setUp)
+        suite = self.source / "synthpkg"
+        suite.mkdir()
+        for name, deps in (("swiki", "[]"), ("slog", "[swiki]")):
+            member = suite / name
+            member.mkdir()
+            dependencies = ("depends: []\n" if deps == "[]" else "depends:\n  - swiki\n")
+            (member / "PLUGIN.yaml").write_text(
+                f"id: {name}\nschema_version: 1\nversion: 0.1\nupdated: 2026-11-12\n"
+                f"{dependencies}attachment: []\nfields:\n"
+                f'inject: "{name} suite member (synthetic)"\n', encoding="utf-8")
+            (member / "PLUGIN.md").write_text("# member\n", encoding="utf-8")
+        (suite / "PKG.yaml").write_text(
+            "id: synth\nkind: suite\nversion: 0.1.0\ncompat: '>= 0.3'\n"
+            "members: [swiki, slog]\ndepends: [framework]\n", encoding="utf-8")
+        result = self.run_kernel("install", "synth", "--path", str(suite))
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertEqual(self.run_kernel("validate").returncode, 0)
+        # the same roster WITHOUT kind: suite must fail the family-root laws
+        (suite / "PKG.yaml").write_text(
+            "id: synth\nversion: 0.1.0\ncompat: '>= 0.3'\n"
+            "members: [swiki, slog]\ndepends: [framework]\n", encoding="utf-8")
+        self.run_kernel("uninstall", "synth", "--yes")
+        result = self.run_kernel("install", "synth", "--path", str(suite))
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("family root synth must be a member", result.stdout)
+
+    def test_unknown_kind_is_rejected(self):
+        suite = self.source / "weirdpkg"
+        suite.mkdir()
+        self.manifest("weird", "weird member", parent=suite)
+        (suite / "PKG.yaml").write_text(
+            "id: weird\nkind: platform\nversion: 0.1\ncompat: '>= 0.3'\n"
+            "members: [weird]\ndepends: [framework]\n", encoding="utf-8")
+        result = self.run_kernel("install", "weird", "--path", str(suite))
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("kind (platform) must be 'suite' or 'domain-family'", result.stdout)
+
+    # ---- provides command (instance view) ----
+
+    def test_kernel_provides_reports_satisfaction(self):
+        self.pkg_dir("prov", caps="provides: [owfa.org.v1, prov.util.v1]")
+        self.assertEqual(self.install_path("prov").returncode, 0)
+        self.pkg_dir("needr", caps="needs: [owfa.org.v1]")
+        self.assertEqual(self.install_path("needr", "--yes").returncode, 0)
+        result = self.run_kernel("provides")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("pkg prov: provides owfa.org.v1, prov.util.v1", result.stdout)
+        # unverified (--path) provides are annotated as such
+        self.assertIn("trust: unknown — unverified provides", result.stdout)
+        self.assertIn("needs owfa.org.v1 — satisfied by UNVERIFIED provides", result.stdout)
+        # uninstall is not a capability convergence point: the need goes unsatisfied
+        # (red validate) while the uninstall itself succeeds — the instance view reports it
+        self.assertEqual(self.run_kernel("uninstall", "prov", "--yes").returncode, 0)
+        result = self.run_kernel("provides")
+        self.assertIn("needs owfa.org.v1 — NOT satisfied: capability missing entirely", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/{.meta → .owfa}/tests/test_install_preflight.py

@@ -1,6 +1,6 @@
 """Offline install regressions; synthetic packages and disposable instances only.
 
-Run: python -m unittest discover -s .meta/tests -p test_install_preflight.py -v
+Run: python -m unittest discover -s .owfa/tests -p test_install_preflight.py -v
 """
 import hashlib
 import json
@@ -22,7 +22,7 @@ class InstallPreflightTests(unittest.TestCase):
         self.addCleanup(self.temp.cleanup)
         self.root = Path(self.temp.name) / "instance"
         self.root.mkdir()
-        for directory in (".meta", ".agents"):
+        for directory in (".owfa", ".agents"):
             shutil.copytree(FRAMEWORK / directory, self.root / directory,
                             ignore=shutil.ignore_patterns("__pycache__", "tests", "smoke-tmp"))
         (self.root / "AGENTS.md").write_text(
@@ -32,16 +32,20 @@ class InstallPreflightTests(unittest.TestCase):
         self.source.mkdir()
         self.env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1", PYTHONIOENCODING="utf-8")
         self.env.pop("PYTHONPATH", None)
+        # v0.4 final shape: the framework tree ships no plugins — the synthetic
+        # instances bootstrap exactly like a real init (embedded personal suite)
+        result = self.run_kernel("install", "personal", "--path", str(FRAMEWORK / "payloads" / "personal"))
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
         result = self.run_kernel("all")
         self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
 
     def run_kernel(self, *args):
         return subprocess.run(
-            [sys.executable, str(self.root / ".meta/scripts/wiki_plugin_kernel.py"), *args],
+            [sys.executable, str(self.root / ".owfa/scripts/owfa_kernel.py"), *args],
             cwd=self.root, env=self.env, capture_output=True, text=True, encoding="utf-8")
 
     def run_code(self, code):
-        prefix = "import sys; sys.path.insert(0, '.meta/scripts'); import wiki_plugin_kernel as k; "
+        prefix = "import sys; sys.path.insert(0, '.owfa/scripts'); import owfa_kernel as k; "
         return subprocess.run([sys.executable, "-c", prefix + code], cwd=self.root,
                               env=self.env, capture_output=True, text=True, encoding="utf-8")
 
@@ -87,7 +91,7 @@ class InstallPreflightTests(unittest.TestCase):
             path = self.source / relative
             path.parent.mkdir(parents=True, exist_ok=True)
             path.write_text("Synthetic payload", encoding="utf-8")
-        ledger = self.root / ".meta/migrations/pending.json"
+        ledger = self.root / ".owfa/migrations/pending.json"
         ledger.parent.mkdir(exist_ok=True)
         ledger.write_text(json.dumps({"probe": {"kind": "teardown", "items": []}}), encoding="utf-8")
         before = self.snapshot()
@@ -112,7 +116,7 @@ class InstallPreflightTests(unittest.TestCase):
         self.manifest("child", "界" * 6000, depends="[optional]")
         result = self.install("--without", "optional")
         self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-        installed = self.root / ".meta/plugins/domains/probe"
+        installed = self.root / ".owfa/plugins/domains/probe"
         self.assertFalse((installed / "optional").exists())
         self.assertFalse((installed / "child").exists())
         self.assertEqual(self.run_kernel("validate").returncode, 0)
@@ -141,7 +145,7 @@ class InstallPreflightTests(unittest.TestCase):
         self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
         self.assertIn("install incomplete", result.stdout)
         self.assertIn("missing command", result.stdout)
-        self.assertTrue((self.root / ".meta/plugins/domains/probe/PKG.yaml").exists())
+        self.assertTrue((self.root / ".owfa/plugins/domains/probe/PKG.yaml").exists())
 
     def test_projection_failure_returns_nonzero(self):
         self.package()

package/.owfa/tests/test_owfa_home.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""owfa_home unit tests: resolution order, bind/unbind, exclusivity, stale, migration.
+
+Run: python3 .owfa/tests/test_owfa_home.py  (pure stdlib; OWFA_HOME pointed at a temp dir)
+"""
+import contextlib
+import io
+import os
+import stat
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts"))
+import owfa_home as h  # noqa: E402
+
+
+class OwfaHomeTests(unittest.TestCase):
+    def setUp(self):
+        self._cwd = os.getcwd()
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        os.environ["OWFA_HOME"] = str(self.root / "machine")
+        self.ws1 = self._ws("ws1")
+        self.ws2 = self._ws("ws2")
+        os.environ.pop("OWFA_ROOT", None)
+
+    def tearDown(self):
+        # tests chdir into the temp workspace; TemporaryDirectory.cleanup()
+        # cannot delete the cwd, so restore first (review P3, PR #57 round 2)
+        os.chdir(self._cwd)
+        self.tmp.cleanup()
+        os.environ.pop("OWFA_HOME", None)
+        os.environ.pop("OWFA_ROOT", None)
+
+    def _ws(self, name):
+        p = self.root / name
+        p.mkdir(parents=True)
+        return str(p)
+
+    def test_unmatched_cwd_on_multi_binding_machine_is_loud(self):
+        # review round 3: falling back to homes/default silently on a
+        # multi-binding machine invents an unregistered home two unmatched
+        # workspaces could share — still served (degraded-but-healthy), but loud
+        h.bind("qq", self.ws1, "alpha")
+        h.bind("qq", self.ws2, "beta")
+        os.chdir(self._ws("ws3"))
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            home = h.resolve_home("qq")
+        self.assertEqual(home, h.home_dir("qq", "default"))
+        self.assertIn("matches none", err.getvalue())
+
+    @unittest.skipIf(sys.platform == "win32", "mkdir mode is a POSIX no-op on Windows")
+    def test_bind_home_dir_is_0700(self):
+        # review round 3: docs/home.md promises 0600/0700 for connector homes
+        entry = h.bind("qq", self.ws1, "alpha")
+        self.assertEqual(stat.S_IMODE(os.stat(entry["home"]).st_mode), 0o700)
+
+    def test_default_home_is_zero_config(self):
+        os.chdir(self.ws1)
+        home = h.resolve_home("qq-cli")
+        self.assertEqual(home, self.root / "machine" / "connectors" / "qq-cli" / "homes" / "default")
+
+    def test_explicit_root_binding_wins(self):
+        os.chdir(self.ws1)
+        h.bind("qq-cli", self.ws1, "personal", bot="appid-1")
+        self.assertEqual(h.resolve_home("qq-cli"), Path(h.home_dir("qq-cli", "personal")))
+        entry = h.load_bindings("qq-cli")[0]
+        self.assertEqual(entry["bot"], "appid-1")
+        self.assertTrue(os.path.isdir(entry["home"]), "bind must create the home dir")
+
+    def test_resolution_order_env_then_cwd(self):
+        h.bind("qq-cli", self.ws1, "a")
+        h.bind("qq-cli", self.ws2, "b")
+        os.environ["OWFA_ROOT"] = self.ws2
+        self.assertEqual(h.resolve_home("qq-cli"), Path(h.home_dir("qq-cli", "b")))
+        os.environ.pop("OWFA_ROOT", None)
+        os.chdir(self.ws1)
+        self.assertEqual(h.resolve_home("qq-cli"), Path(h.home_dir("qq-cli", "a")))  # cwd lookup
+        self.assertEqual(h.resolve_home("qq-cli", explicit_root=self.ws2), Path(h.home_dir("qq-cli", "b")))  # explicit wins
+
+    def test_rebind_same_root_replaces(self):
+        h.bind("qq-cli", self.ws1, "first")
+        h.bind("qq-cli", self.ws1)  # no id: re-binds under the existing id for this root
+        bindings = h.load_bindings("qq-cli")
+        self.assertEqual(len(bindings), 1)
+        self.assertEqual(bindings[0]["id"], "first")
+
+    def test_unbind_detaches_but_keeps_home(self):
+        b = h.bind("qq-cli", self.ws1, "keep-data")
+        h.unbind("qq-cli", "keep-data")
+        self.assertEqual(h.load_bindings("qq-cli"), [])
+        self.assertTrue(os.path.isdir(b["home"]), "unbind must not delete home data")
+
+    def test_exclusivity_violation_detected(self):
+        home = h.home_dir("qq-cli", "shared")
+        for ws, bid in ((self.ws1, "one"), (self.ws2, "two")):
+            b = h.bind("qq-cli", ws, bid)
+            b["home"] = str(home)  # force two bindings onto one home
+            h.save_bindings("qq-cli", [x for x in h.load_bindings("qq-cli") if x["id"] != bid] + [b])
+        v = h.exclusivity_violations("qq-cli")
+        self.assertEqual(len(v), 1)
+        self.assertEqual(sorted(v[0]["bindings"]), ["one", "two"])
+
+    def test_stale_bindings_reported(self):
+        gone = self._ws("gone")
+        h.bind("qq-cli", gone, "dying")
+        os.rmdir(gone)
+        stale = h.stale_bindings("qq-cli")
+        self.assertEqual([s["id"] for s in stale], ["dying"])
+
+    def test_migrate_moves_and_symlinks(self):
+        legacy = Path(self._ws("legacy-home"))
+        (legacy / "credentials.json").write_text("{}", encoding="utf-8")
+        os.chdir(self.ws1)
+        entry = h.migrate_legacy_home("qq-cli", str(legacy), "default", root=self.ws1)
+        self.assertFalse(legacy.exists() and not legacy.is_symlink(), "legacy dir must move, not copy")
+        self.assertTrue((Path(entry["home"]) / "credentials.json").exists(), "contents must land in the new home")
+        self.assertTrue(legacy.is_symlink() and os.path.realpath(legacy) == os.path.realpath(entry["home"]))
+        self.assertEqual(os.path.basename(os.path.realpath(legacy)), "default")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/.owfa/tests/test_version_scheme.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Version-scheme unit tests (versioning scheme, 0.4): three-part anchor parse,
+B-line extraction, and the migration staging range [prev_line, new_line).
+
+Run: python3 -m unittest discover -s .owfa/tests -p test_version_scheme.py
+"""
+import os
+import re
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts"))
+import owfa_kernel as k  # noqa: E402
+
+
+class VersionSchemeTests(unittest.TestCase):
+    def test_framework_version_parses_three_part_anchor(self):
+        # the repo's own VERSION is the full release version now
+        self.assertEqual(k.framework_version(), (0, 4, 0))
+
+    def test_framework_version_tolerates_legacy_two_part(self):
+        import tempfile
+        vpath = os.path.join(k.ROOT, ".owfa", "VERSION")
+        original = open(vpath, encoding="utf-8").read()
+        try:
+            open(vpath, "w", encoding="utf-8").write("0.3\n")
+            self.assertEqual(k.framework_version(), (0, 3))
+        finally:
+            open(vpath, "w", encoding="utf-8").write(original)
+
+    def test_vline_extracts_major_minor(self):
+        self.assertEqual(k._vline("0.3.0"), (0, 3))
+        self.assertEqual(k._vline("0.3.11"), (0, 3))
+        self.assertEqual(k._vline("0.2"), (0, 2))
+
+    def test_compat_floor_tuple_semantics(self):
+        fw = k.framework_version()  # (0, 4, 0)
+        self.assertFalse((0, 3) > fw)     # floor below the line passes
+        self.assertFalse((0, 4) > fw)     # floor at the line passes
+        self.assertFalse((0, 4, 0) > fw)  # floor equal to the release passes
+        self.assertTrue((0, 4, 1) > fw)   # floor demanding a later patch refuses
+        self.assertTrue((0, 5) > fw)      # floor above the line refuses
+
+    def test_staging_line_range(self):
+        # mirror of the _stage_migrations predicate: stage when prev_line <= from_line < new_line
+        def stages(name, prev, new):
+            m = re.fullmatch(r"(\d+\.\d+)-to-(\d+\.\d+)\.md", name)
+            if not m:
+                return False
+            prev_line, new_line = k._vline(prev), k._vline(new)
+            return prev_line <= k._vt(m.group(1)) < new_line
+
+        self.assertTrue(stages("0.3-to-0.4.md", "0.3.2", "0.4.0"))   # line crossing stages
+        self.assertTrue(stages("0.3-to-0.4.md", "0.3", "0.4.0"))     # legacy two-part prev works
+        self.assertTrue(stages("0.2-to-0.3.md", "0.2", "0.4.0"))     # chained crossings stage together
+        self.assertFalse(stages("0.3-to-0.4.md", "0.3.1", "0.3.2"))  # same-line C update stages nothing
+        self.assertFalse(stages("0.2-to-0.3.md", "0.3", "0.4.0"))    # already past does not re-stage
+        self.assertFalse(stages("0.4-to-0.5.md", "0.3", "0.4.0"))    # future lines do not stage
+
+
+if __name__ == "__main__":
+    unittest.main()