You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hugegraph.apache.org by ji...@apache.org on 2026/09/25 00:28:33 UTC

(hugegraph-doc) branch oink-1.1 updated (014e01213 -> 7477493fe)

This is an automated email from the ASF dual-hosted git repository.

imbajin pushed a change to branch oink-1.1
in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git


    omit 014e01213 docs(goal): temporary handoff oink 1.1 website guide and illustrations
     new 7477493fe fix: address OINK upgrade review findings

This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version.  This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:

 * -- * -- B -- O -- O -- O   (014e01213)
            \
             N -- N -- N   refs/heads/oink-1.1 (7477493fe)

You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.

Any revisions marked "omit" are not gone; other references still
refer to them.  Any revisions marked "discard" are gone forever.

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .github/workflows/hugo.yml                         |   3 +
 .goal-task/oink-1.1-guide/handoff.md               |  29 -------
 .../oink-1.1-illustrations/01-build.png            | Bin 1670588 -> 0 bytes
 .../oink-1.1-illustrations/02-language-version.png | Bin 1388722 -> 0 bytes
 .../oink-1.1-illustrations/03-maintenance.png      | Bin 1976067 -> 0 bytes
 .../oink-1.1-illustrations/04-ai.png               | Bin 1758666 -> 0 bytes
 .../oink-1.1-illustrations/05-overview.png         | Bin 1547087 -> 0 bytes
 .../oink-1.1-illustrations/06-features.png         | Bin 1384330 -> 0 bytes
 .../oink-1.1-illustrations/07-publishing.png       | Bin 1819948 -> 0 bytes
 .../oink-1.1-illustrations/08-optional-ai.png      | Bin 1452188 -> 0 bytes
 .../oink-1.1-illustrations/final-prompts.md        |  27 -------
 .../oink-1.1-illustrations/general-prompts.md      |  24 ------
 .../oink-1.1-illustrations/prompts.md              |  16 ----
 .../oink-1.1-illustrations/style-a.png             | Bin 2335823 -> 0 bytes
 .../oink-1.1-illustrations/style-b.png             | Bin 1496773 -> 0 bytes
 .../oink-1.1-illustrations/style-c.png             | Bin 2212784 -> 0 bytes
 .../oink-1.1-guide/oink-1.1-website-guide.md       |  86 ---------------------
 assets/js/hugegraph-shell.js                       |  22 ++++--
 assets/js/kapa-adapter.js                          |  38 +++++++--
 scripts/oink-upgrade.md                            |  11 ++-
 scripts/oink_module.py                             |  49 ++++++++----
 scripts/test_oink_module.py                        |  67 +++++++++++++++-
 scripts/test_oink_upgrade.py                       |   6 +-
 scripts/test_update_oink.py                        |  82 ++++++++++++++++++++
 scripts/update_oink.py                             |  34 ++++++--
 scripts/versioning.py                              |  11 ++-
 tests/e2e/platform.spec.js                         |   4 +-
 tests/e2e/theme-upgrade.spec.js                    |  53 +++++++++++++
 tests/e2e/workflow-contract.test.cjs               |  10 +++
 tests/ui-ai/kapa-adapter.test.cjs                  |  80 +++++++++++++++++++
 tests/ui-ai/sidebar-persistence.test.cjs           |  51 ++++++++++--
 31 files changed, 463 insertions(+), 240 deletions(-)
 delete mode 100644 .goal-task/oink-1.1-guide/handoff.md
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/01-build.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/02-language-version.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/03-maintenance.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/04-ai.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/05-overview.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/06-features.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/07-publishing.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/08-optional-ai.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/final-prompts.md
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/general-prompts.md
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/prompts.md
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/style-a.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/style-b.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-illustrations/style-c.png
 delete mode 100644 .goal-task/oink-1.1-guide/oink-1.1-website-guide.md
 create mode 100644 scripts/test_update_oink.py


(hugegraph-doc) 01/01: fix: address OINK upgrade review findings

Posted by ji...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

imbajin pushed a commit to branch oink-1.1
in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git

commit 7477493fee518a93dcc166c6cda79f199a51eb73
Author: imbajin <ji...@apache.org>
AuthorDate: Fri Sep 25 08:28:26 2026 +0800

    fix: address OINK upgrade review findings
    
    - settle Kapa failures and activate the current search query
    - migrate sidebar preferences while preserving aside defaults
    - improve locked module diagnostics and resumable checksum cleanup
    - cover data overrides and retain workflow module graph checks
---
 .github/workflows/hugo.yml               |  3 ++
 assets/js/hugegraph-shell.js             | 22 ++++++---
 assets/js/kapa-adapter.js                | 38 +++++++++++----
 scripts/oink-upgrade.md                  | 11 ++++-
 scripts/oink_module.py                   | 49 ++++++++++++-------
 scripts/test_oink_module.py              | 67 ++++++++++++++++++++++++--
 scripts/test_oink_upgrade.py             |  6 +--
 scripts/test_update_oink.py              | 82 ++++++++++++++++++++++++++++++++
 scripts/update_oink.py                   | 34 ++++++++++---
 scripts/versioning.py                    | 11 +++--
 tests/e2e/platform.spec.js               |  4 +-
 tests/e2e/theme-upgrade.spec.js          | 53 +++++++++++++++++++++
 tests/e2e/workflow-contract.test.cjs     | 10 ++++
 tests/ui-ai/kapa-adapter.test.cjs        | 80 +++++++++++++++++++++++++++++++
 tests/ui-ai/sidebar-persistence.test.cjs | 51 ++++++++++++++++----
 15 files changed, 463 insertions(+), 58 deletions(-)

diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml
index 593a213ec..35e7af227 100644
--- a/.github/workflows/hugo.yml
+++ b/.github/workflows/hugo.yml
@@ -232,6 +232,9 @@ jobs:
           restore-keys: ${{ runner.os }}-hugo-${{ env.HUGO_VERSION }}-${{ matrix.version.id }}-
       - name: Verify pinned OINK module
         run: |
+          test "$(go list -m -f '{{ .Path }}')" = "github.com/apache/hugegraph-doc"
+          test "$(go list -m all | wc -l)" -eq 2
+          test -z "$(go list -m -f '{{ with .Replace }}{{ .Path }}{{ end }}' github.com/pgsty/oink)"
           python3 scripts/update_oink.py --check-baseline
       - name: Build isolated version artifact
         env:
diff --git a/assets/js/hugegraph-shell.js b/assets/js/hugegraph-shell.js
index f01ba349b..2cbf2e702 100644
--- a/assets/js/hugegraph-shell.js
+++ b/assets/js/hugegraph-shell.js
@@ -36,20 +36,26 @@
     if (!sidebar) return;
     return sidebar.ready.then(function () {
       var buttons = Array.prototype.slice.call(documentObject.querySelectorAll(
-        '#td-shell-sidebar [data-td-shell-tree-toggle][aria-controls]',
+        '#td-shell-sidebar [data-td-shell-tree-toggle][aria-controls], ' +
+        '[data-td-shell-aside] [data-td-shell-tree-toggle][aria-controls]',
       ));
       if (!buttons.length) return;
       var storage = safeStorage(windowObject);
-      var key = 'oink.sidebar.v2.' + String(config.version || 'latest') +
-        '.' + String(config.locale || 'en');
+      var scope = String(config.version || 'latest') + '.' + String(config.locale || 'en');
+      var key = 'oink.sidebar.v3.' + scope;
       var valid = new Set(buttons.map(function (button) {
         return button.getAttribute('aria-controls');
       }));
       var remembered = new Set();
       var hasSavedState = false;
+      var legacyState = false;
       if (storage) {
         try {
           var stored = storage.getItem(key);
+          if (stored === null) {
+            stored = storage.getItem('oink.sidebar.v2.' + scope);
+            legacyState = stored !== null;
+          }
           var parsed = JSON.parse(stored || '[]');
           if (Array.isArray(parsed)) {
             hasSavedState = stored !== null;
@@ -62,8 +68,12 @@
       var docsRoot = /(?:^|\/)(?:cn\/)?docs\/?$/.test(windowObject.location.pathname);
       buttons.forEach(function (button) {
         var id = button.getAttribute('aria-controls');
-        var defaultOpen = !hasSavedState && docsRoot &&
-          /_nav(?:start|components)-children$/.test(id);
+        var isAside = Boolean(button.closest('[data-td-shell-aside]'));
+        // v2 stored only the main tree: an absent aside id was not a choice
+        // to collapse it. v3 records both, including an explicitly empty set.
+        var defaultOpen = isAside
+          ? (!hasSavedState || legacyState) && sidebar.getState(id).expanded
+          : !hasSavedState && docsRoot && /_nav(?:start|components)-children$/.test(id);
         // OINK preserves the active path and owns DOM, inert and ARIA state.
         sidebar.setExpanded(id, remembered.has(id) || defaultOpen, { source: 'api' });
       });
@@ -82,7 +92,7 @@
       documentObject.addEventListener('oink:sidebar-disclosure', function (event) {
         if (event.detail && event.detail.source === 'user' && valid.has(event.detail.id)) persist();
       });
-      if (!hasSavedState) persist();
+      if (!hasSavedState || legacyState) persist();
     });
   }
 
diff --git a/assets/js/kapa-adapter.js b/assets/js/kapa-adapter.js
index 552ac9dfd..5e49fc8de 100644
--- a/assets/js/kapa-adapter.js
+++ b/assets/js/kapa-adapter.js
@@ -144,13 +144,19 @@
     }
 
     function openWidget(query, submit) {
-      invokeKapa(windowObject, 'setSourceGroupIDs', [config.sourceGroupId]);
-      invokeKapa(windowObject, 'open', {
-        mode: 'ai',
-        query: query,
-        submit: submit,
-      });
-      settle();
+      try {
+        invokeKapa(windowObject, 'setSourceGroupIDs', [config.sourceGroupId]);
+        invokeKapa(windowObject, 'open', {
+          mode: 'ai',
+          query: query,
+          submit: submit,
+        });
+        settle();
+      } catch (_) {
+        discardAttempt(attempt);
+        renderState('error', config.labels.error);
+        settle(new Error(config.labels.error));
+      }
     }
 
     function discardAttempt(serial) {
@@ -365,9 +371,25 @@
           }];
         },
         activate: function (_, context) {
+          // OINK debounces row rendering; Enter can activate an older row.
+          var input = documentObject.querySelector('#td-shell-search .td-shell-search__input');
+          var query = trimmedQuery(input ? input.value : context.query);
+          if (query !== context.query) {
+            // Refresh OINK's cancellation token as well as the submitted text;
+            // otherwise its pending render aborts a handoff for the old query.
+            var instance = palette.instance;
+            instance.render(query);
+            var rows = instance.rows();
+            var index = rows.findIndex(function (row) {
+              return row.type === 'extension' && row.owner.id === 'hugegraph-ai';
+            });
+            if (index >= 0) instance.activate(index);
+            return;
+          }
+          if (!query || query.charAt(0) === '>') return;
           // Search options are ephemeral and become hidden on handoff.
           var trigger = documentObject.querySelector('.hg-ask-ai-launcher');
-          return controller.activate(context.query, true, trigger, context);
+          return controller.activate(query, true, trigger, context);
         },
       });
     }
diff --git a/scripts/oink-upgrade.md b/scripts/oink-upgrade.md
index b2d39dbcd..66b58d36f 100644
--- a/scripts/oink-upgrade.md
+++ b/scripts/oink-upgrade.md
@@ -27,7 +27,8 @@ npm and Chromium. Local ports 4173 and 4174 must be available.
 scripts/update-oink.sh v1.1.0
 ```
 
-Use an explicit release tag. The command updates the lock files, validates module
+Use an explicit release tag. The command updates the lock files, removes old-version
+checksums from `go.sum`, validates module
 identity, reports upstream changes affecting customizations, then reuses the
 strict build, Python/link tests, all historical builds, aggregate validation
 (which validates each version artifact once),
@@ -86,12 +87,18 @@ git diff -- go.mod go.sum layouts assets scripts .github/workflows/hugo.yml
 | Brand and layout | `assets/scss/`, `data/`, `i18n/` | Bilingual desktop/mobile, dark/light and print captures |
 
 `scripts/oink-overrides.json` records upstream hashes, not copies of upstream
-code. The generated inventory covers same-name local layouts/assets/translations,
+code. The generated inventory covers same-name local layouts/assets/translations/data,
 the sidebar/search/surface interface files and upstream SCSS used by local CSS.
 New, removed or changed upstream files in that inventory require review. Site-only
 hooks are listed above; their behavior is checked by tests rather than inferred
 from matching filenames. Template hashes alone never prove full compatibility.
 
+Adding or removing a same-name local override changes the inventory even without
+a theme upgrade. The read-only `--check-baseline` diagnostic names added, removed,
+and changed paths. Review those changes, then run
+`scripts/update-oink.sh <pinned-version> --resume --accept-reviewed` to validate
+and record the revised inventory; use the version currently pinned in `go.mod`.
+
 For this initial 1.1 migration the baseline is generated after manual review and
 is accepted with the repository's full migration verification. Future runs update
 it only after the same automated gates pass.
diff --git a/scripts/oink_module.py b/scripts/oink_module.py
index 6bca61db4..01040cd8e 100644
--- a/scripts/oink_module.py
+++ b/scripts/oink_module.py
@@ -10,6 +10,7 @@ import json
 import os
 import re
 import subprocess
+import sys
 from pathlib import Path
 
 MODULE = "github.com/pgsty/oink"
@@ -17,49 +18,63 @@ SITE_MODULE = "github.com/apache/hugegraph-doc"
 VERSION = re.compile(r"v[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?")
 
 
-def command(args, root):
-    return subprocess.check_output([os.environ.get("GO_BIN", "go"), *args], cwd=root, text=True)
+def command(args, root, go_executable=None):
+    argv = [go_executable or os.environ.get("GO_BIN", "go"), *args]
+    try:
+        return subprocess.check_output(argv, cwd=root, text=True, stderr=subprocess.PIPE)
+    except subprocess.CalledProcessError as error:
+        detail = (error.stderr or error.output or "").strip()
+        raise ValueError(f"Go command {' '.join(argv)} failed ({error.returncode}): {detail}") from None
+    except OSError as error:
+        raise ValueError(f"Go executable is unavailable: {argv[0]} ({error})") from None
 
 
-def locked_version(root):
-    data = json.loads(command(["mod", "edit", "-json"], root))
+def locked_version(root, go_executable=None):
+    data = json.loads(command(["mod", "edit", "-json"], root, go_executable))
     requirements = data.get("Require") or []
     if (data.get("Module", {}).get("Path") != SITE_MODULE
             or data.get("Replace") or data.get("Exclude")
             or len(requirements) != 1 or requirements[0]["Path"] != MODULE):
-        raise ValueError("expected the HugeGraph module with only OINK and no replace/exclude directives")
+        raise ValueError(f"expected the HugeGraph module with only OINK and no replace/exclude directives; actual: {data!r}")
     version = requirements[0]["Version"]
     if not VERSION.fullmatch(version):
-        raise ValueError("OINK must be pinned to an explicit release version")
+        raise ValueError(f"OINK must be pinned to an explicit release version; actual: {version!r}")
     return version
 
 
-def download_locked(root):
+def download_locked(root, go_executable=None):
     root = Path(root)
-    version = locked_version(root)
+    version = locked_version(root, go_executable)
     sums = {}
     for line in (root / "go.sum").read_text().splitlines():
         if not line.strip():
             continue
         path, revision, digest = line.split()
+        if (path, revision) in sums:
+            raise ValueError(f"duplicate go.sum entry: {path} {revision}")
         sums[(path, revision)] = digest
     expected = [sums.get((MODULE, version)), sums.get((MODULE, version + "/go.mod"))]
     if not all(expected):
-        raise ValueError("OINK module and go.mod checksums must already exist in go.sum")
-    module = json.loads(command(["mod", "download", "-json", MODULE + "@" + version], root))
+        raise ValueError(f"expected checksums for {MODULE}@{version} and /go.mod in go.sum; actual entries: {list(sums)!r}")
+    if set(sums) != {(MODULE, version), (MODULE, version + "/go.mod")}:
+        raise ValueError(f"go.sum must contain only {MODULE}@{version} and /go.mod; actual entries: {list(sums)!r}")
+    module = json.loads(command(["mod", "download", "-json", MODULE + "@" + version], root, go_executable))
     if (module.get("Path") != MODULE or module.get("Version") != version
             or module.get("Sum") != expected[0] or module.get("GoModSum") != expected[1]
             or module.get("Error")):
-        raise ValueError("downloaded OINK identity or checksum differs from lock files")
-    resolved = json.loads(command(["list", "-m", "-json", MODULE], root))
+        raise ValueError(f"expected {MODULE}@{version} checksums {expected!r}; downloaded metadata: {module!r}")
+    resolved = json.loads(command(["list", "-m", "-json", MODULE], root, go_executable))
     if resolved.get("Replace") or resolved.get("Version") != version or resolved.get("Path") != MODULE:
-        raise ValueError("resolved OINK module differs from lock files")
-    graph = command(["list", "-m", "all"], root).splitlines()
+        raise ValueError(f"expected resolved {MODULE}@{version} without replacement; actual: {resolved!r}")
+    graph = command(["list", "-m", "all"], root, go_executable).splitlines()
     if graph != [SITE_MODULE, MODULE + " " + version]:
-        raise ValueError("module graph must contain only this site and the pinned OINK module")
-    command(["mod", "verify"], root)
+        raise ValueError(f"expected module graph {[SITE_MODULE, MODULE + ' ' + version]!r}; actual: {graph!r}")
+    command(["mod", "verify"], root, go_executable)
     return module
 
 
 if __name__ == "__main__":
-    print(json.dumps(download_locked(Path(__file__).resolve().parents[1]), indent=2))
+    try:
+        print(json.dumps(download_locked(Path(__file__).resolve().parents[1]), indent=2))
+    except (ValueError, OSError) as error:
+        sys.exit(f"OINK module verification failed: {error}")
diff --git a/scripts/test_oink_module.py b/scripts/test_oink_module.py
index 897d4691a..dd070bf8c 100644
--- a/scripts/test_oink_module.py
+++ b/scripts/test_oink_module.py
@@ -8,6 +8,8 @@
 import json
 from pathlib import Path
 import tempfile
+import subprocess
+import sys
 import unittest
 from unittest.mock import patch
 
@@ -15,11 +17,45 @@ import oink_module
 
 
 class ModuleLockTest(unittest.TestCase):
+    def test_build_resolves_relative_go_before_changing_directory(self):
+        import argparse
+        import os
+        import versioning
+        actual_run = subprocess.run
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            executable = root / "go"
+            executable.write_text("#!/bin/sh\nprintf 'resolved-go'\n")
+            executable.chmod(0o755)
+            relative = os.path.relpath(executable, Path.cwd())
+            entry = {"id": "latest", "archived": False, "publishPath": ""}
+            args = argparse.Namespace(manifest=root / "manifest", version="latest", sha="a" * 40,
+                                      output=root / "out", site_origin="https://example.org/",
+                                      historical_origin="https://example.org/")
+
+            def download(assembly, go):
+                self.assertEqual(go, str(executable.resolve()))
+                self.assertEqual(subprocess.check_output([go], cwd=assembly, text=True), "resolved-go")
+                raise ValueError("verified relative Go from assembly")
+
+            with patch.dict(os.environ, GO_BIN=relative), \
+                 patch.object(versioning, "load_manifest", return_value={"versions": [entry]}), \
+                 patch.object(versioning, "prepare_output_directory", return_value=args.output), \
+                 patch.object(versioning, "run"), \
+                 patch.object(versioning.subprocess, "run", side_effect=lambda argv, **kw:
+                              None if argv[0] == "git" else actual_run(argv, **kw)), \
+                 patch.object(versioning, "overlay_shell", side_effect=lambda assembly, **kw: assembly.mkdir()), \
+                 patch.object(versioning, "derived_version_config", return_value={}), \
+                 patch.object(versioning, "download_locked", side_effect=download) as resolve:
+                with self.assertRaisesRegex(SystemExit, "OINK module verification failed: verified relative Go"):
+                    versioning.build(args)
+                resolve.assert_called_once()
+
     def config(self, version="v1.0.0", **changes):
         return dict(Module={"Path": oink_module.SITE_MODULE},
                     Require=[{"Path": oink_module.MODULE, "Version": version}], **changes)
 
-    def download(self, version="v1.0.0", config=None, metadata=None, resolved=None, graph=None, sums=True):
+    def download(self, version="v1.0.0", config=None, metadata=None, resolved=None, graph=None, sums=True, extra=""):
         module = dict(Path=oink_module.MODULE, Version=version, Sum="h1:archive", GoModSum="h1:mod")
         resolution = dict(Path=oink_module.MODULE, Version=version)
         module.update(metadata or {})
@@ -29,12 +65,37 @@ class ModuleLockTest(unittest.TestCase):
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
             (root / "go.sum").write_text(
-                f"\n{oink_module.MODULE} {version} h1:archive\n\n{oink_module.MODULE} {version}/go.mod h1:mod\n" if sums else "")
+                (f"\n{oink_module.MODULE} {version} h1:archive\n\n{oink_module.MODULE} {version}/go.mod h1:mod\n" if sums else "") + extra)
             with patch.object(oink_module, "command", side_effect=replies) as command:
-                result = oink_module.download_locked(root)
+                result = oink_module.download_locked(root, "/verified/bin/go")
                 self.assertEqual(command.call_args.args[0], ["mod", "verify"])
+                self.assertTrue(all(call.args[2] == "/verified/bin/go" for call in command.call_args_list))
                 return result
 
+    def test_rejects_stale_and_duplicate_checksums(self):
+        for extra in [f"{oink_module.MODULE} v0.9.0 h1:stale\n",
+                      f"{oink_module.MODULE} v1.0.0 h1:duplicate\n"]:
+            with self.subTest(extra=extra), self.assertRaises(ValueError):
+                self.download(extra=extra)
+
+    def test_mismatch_diagnostic_has_expected_and_actual(self):
+        with self.assertRaisesRegex(ValueError, "h1:archive.*h1:wrong"):
+            self.download(metadata={"Sum": "h1:wrong"})
+
+    def test_failed_go_command_preserves_download_error(self):
+        failure = subprocess.CalledProcessError(1, ["go"], output='{"Error":"checksum mismatch"}')
+        with patch.object(oink_module.subprocess, "check_output", side_effect=failure):
+            with self.assertRaisesRegex(ValueError, "verified/bin/go.*checksum mismatch"):
+                oink_module.command(["mod", "download", "-json"], Path("."), "/verified/bin/go")
+
+    def test_cli_missing_go_has_no_traceback(self):
+        import os
+        result = subprocess.run([sys.executable, oink_module.__file__], text=True, capture_output=True,
+                                env=dict(os.environ, GO_BIN="/missing/oink-test-go"))
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("/missing/oink-test-go", result.stderr)
+        self.assertNotIn("Traceback", result.stderr)
+
     def test_accepts_each_locked_release(self):
         for version in ["v1.0.0", "v1.1.0"]:
             with self.subTest(version=version):
diff --git a/scripts/test_oink_upgrade.py b/scripts/test_oink_upgrade.py
index cb79eaf8d..c0af354cb 100644
--- a/scripts/test_oink_upgrade.py
+++ b/scripts/test_oink_upgrade.py
@@ -54,7 +54,7 @@ class UpgradeTest(unittest.TestCase):
             baseline = root / "baseline.json"
             original = json.dumps({"version": "v1.0.0", "files": {"a": "old"}})
             baseline.write_text(original)
-            with patch.object(update_oink, "BASELINE", baseline), patch.object(update_oink, "preflight"), \
+            with patch.object(update_oink, "BASELINE", baseline), patch.object(update_oink, "preflight"), patch.object(update_oink, "prune_checksums"), \
                  patch.object(update_oink, "download_locked", return_value={"Dir": d}), \
                  patch.object(update_oink, "snapshot", return_value={"a": "new"}), \
                  patch.object(update_oink.tempfile, "mkdtemp", return_value=d), \
@@ -68,7 +68,7 @@ class UpgradeTest(unittest.TestCase):
         with tempfile.TemporaryDirectory() as d:
             baseline = Path(d) / "baseline.json"
             baseline.write_text(json.dumps({"version": "v1.1.0", "files": {"a": "same"}}))
-            with patch.object(update_oink, "BASELINE", baseline), patch.object(update_oink, "preflight"), \
+            with patch.object(update_oink, "BASELINE", baseline), patch.object(update_oink, "preflight"), patch.object(update_oink, "prune_checksums"), \
                  patch.object(update_oink, "locked_version", return_value="v1.1.0"), \
                  patch.object(update_oink, "command") as command, \
                  patch.object(update_oink, "download_locked", return_value={"Dir": d}), \
@@ -86,7 +86,7 @@ class UpgradeTest(unittest.TestCase):
         with tempfile.TemporaryDirectory() as d:
             baseline = Path(d) / "baseline.json"
             baseline.write_text(json.dumps({"version": "v1.0.0", "files": {"a": "old"}}))
-            with patch.object(update_oink, "BASELINE", baseline), patch.object(update_oink, "preflight"), \
+            with patch.object(update_oink, "BASELINE", baseline), patch.object(update_oink, "preflight"), patch.object(update_oink, "prune_checksums"), \
                  patch.object(update_oink, "download_locked", return_value={"Dir": d}), \
                  patch.object(update_oink, "snapshot", return_value={"a": "new"}), \
                  patch.object(update_oink.tempfile, "mkdtemp", return_value=d), \
diff --git a/scripts/test_update_oink.py b/scripts/test_update_oink.py
new file mode 100644
index 000000000..8f0c02630
--- /dev/null
+++ b/scripts/test_update_oink.py
@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0.
+
+from pathlib import Path
+import tempfile
+import unittest
+import json
+from unittest.mock import patch
+
+import update_oink
+
+from oink_module import MODULE
+from update_oink import describe_changes, prune_checksums, snapshot
+
+
+class UpgradeInventoryTest(unittest.TestCase):
+    def test_resume_cleans_interrupted_upgrade_before_validation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            target = f"{MODULE} v1.1.0 h1:new\n{MODULE} v1.1.0/go.mod h1:newmod\n"
+            (root / "go.sum").write_text(f"{MODULE} v1.0.0 h1:old\n" + target)
+            baseline = root / "baseline.json"
+            baseline.write_text(json.dumps({"version": "v1.1.0", "files": {}}))
+
+            def download(path):
+                self.assertEqual((path / "go.sum").read_text(), target)
+                return {"Dir": str(root)}
+
+            with patch.object(update_oink, "ROOT", root), patch.object(update_oink, "BASELINE", baseline), \
+                 patch.object(update_oink, "locked_version", return_value="v1.1.0"), \
+                 patch.object(update_oink, "download_locked", side_effect=download), \
+                 patch.object(update_oink, "snapshot", return_value={}), \
+                 patch.object(update_oink, "validate") as validate, \
+                 patch.object(update_oink, "command") as command, \
+                 patch.object(update_oink.tempfile, "mkdtemp", return_value=directory), \
+                 patch("sys.argv", ["update", "v1.1.0", "--resume"]):
+                update_oink.main()
+                update_oink.main()
+                command.assert_not_called()
+                self.assertEqual(validate.call_count, 2)
+
+    def test_data_override_and_locale_inventory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root, upstream = Path(directory) / "site", Path(directory) / "theme"
+            for base, paths in [(root, ["data/brand.yaml", "data/site-only.yaml", "i18n/zh_CN.yaml"]),
+                                (upstream, ["data/brand.yaml", "data/upstream-only.yaml", "i18n/zh-cn.yaml"])]:
+                for name in paths:
+                    path = base / name
+                    path.parent.mkdir(parents=True, exist_ok=True)
+                    path.write_text("value")
+            result = snapshot(root, upstream)
+            self.assertIn("data/brand.yaml", result)
+            self.assertIn("i18n/zh-cn.yaml", result)
+            self.assertNotIn("data/site-only.yaml", result)
+            self.assertNotIn("data/upstream-only.yaml", result)
+            before = dict(result)
+            (root / "data/brand.yaml").unlink()
+            self.assertIn("removed: data/brand.yaml", describe_changes(before, snapshot(root, upstream)))
+
+    def test_change_diagnostics(self):
+        self.assertEqual(describe_changes({"b": "old", "c": "old"}, {"a": "new", "b": "new"}),
+                         ["added: a", "changed: b", "removed: c"])
+
+    def test_upgrade_removes_old_checksums(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            old = f"{MODULE} v1.0.0 h1:old\n{MODULE} v1.0.0/go.mod h1:oldmod\n"
+            new = f"{MODULE} v1.1.0 h1:new\n{MODULE} v1.1.0/go.mod h1:newmod\n"
+            (root / "go.sum").write_text(old + new)
+            prune_checksums(root, "v1.1.0")
+            self.assertEqual((root / "go.sum").read_text(), new)
+            with self.assertRaises(ValueError):
+                prune_checksums(root, "v9.0.0")
+            self.assertEqual((root / "go.sum").read_text(), new)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/update_oink.py b/scripts/update_oink.py
index 0847b48f0..a9d966d6c 100644
--- a/scripts/update_oink.py
+++ b/scripts/update_oink.py
@@ -33,7 +33,7 @@ def snapshot(root, upstream):
     paths = set(WATCH)
     # Project SCSS depends on upstream selectors even without a same-name override.
     paths.update(str(p.relative_to(upstream)) for p in (upstream / "assets/scss").rglob("*.scss"))
-    for folder in ("layouts", "assets", "i18n"):
+    for folder in ("layouts", "assets", "i18n", "data"):
         def key(relative):
             name = relative.as_posix()
             # Locale filenames are case-insensitive; record the upstream spelling
@@ -53,6 +53,21 @@ def changes(previous, current):
     return [p for p in sorted(previous.keys() | current.keys()) if previous.get(p) != current.get(p)]
 
 
+def describe_changes(previous, current):
+    return [f"{'added' if p not in previous else 'removed' if p not in current else 'changed'}: {p}"
+            for p in changes(previous, current)]
+
+
+def prune_checksums(root, version):
+    """Keep only target checksums after go get; do not use go mod tidy."""
+    path = root / "go.sum"
+    lines = [line for line in path.read_text().splitlines()
+             if line.split()[:2] in [[MODULE, version], [MODULE, version + "/go.mod"]]]
+    if len(lines) != 2 or len({line.split()[1] for line in lines}) != 2:
+        raise ValueError(f"expected both target checksums before cleanup: {MODULE}@{version}")
+    path.write_text("\n".join(lines) + "\n")
+
+
 def preflight(root, target, resume):
     if not VERSION.fullmatch(target):
         raise ValueError("use an explicit release such as v1.1.0; branches and latest are not accepted")
@@ -107,9 +122,12 @@ def main():
     if args.check_baseline:
         module = download_locked(ROOT)
         baseline = json.loads(BASELINE.read_text())
-        if (baseline["version"] != module["Version"]
-                or changes(baseline["files"], snapshot(ROOT, Path(module["Dir"])))):
-            raise ValueError("OINK upstream files differ from reviewed baseline; follow scripts/oink-upgrade.md")
+        changed = describe_changes(baseline["files"], snapshot(ROOT, Path(module["Dir"])))
+        if baseline["version"] != module["Version"] or changed:
+            detail = "; ".join(changed) or "no file changes"
+            raise ValueError(f"OINK baseline differs (reviewed {baseline['version']}, pinned {module['Version']}): "
+                             f"{detail}; local override additions/removals also require review; "
+                             "follow scripts/oink-upgrade.md")
         print("Reviewed OINK upstream baseline matches")
         return
     if args.version is None:
@@ -120,11 +138,14 @@ def main():
     print(f"Upgrade artifacts and review report: {work}", flush=True)
     if not args.resume and locked_version(ROOT) != args.version:
         command(["get", MODULE + "@" + args.version], ROOT)
+        prune_checksums(ROOT, args.version)
+    elif args.resume:
+        prune_checksums(ROOT, args.version)
     module = download_locked(ROOT)
     current = snapshot(ROOT, Path(module["Dir"]))
     changed = changes(previous["files"], current)
     report = {"from": previous["version"], "to": args.version, "reviewRequired": changed,
-              "scope": "same-name overrides, sidebar/search interfaces and upstream SCSS; not a full compatibility proof"}
+              "scope": "same-name layouts/assets/translations/data overrides, sidebar/search interfaces and upstream SCSS; not a full compatibility proof"}
     (work / "review.json").write_text(json.dumps(report, indent=2) + "\n")
     if changed and not args.accept_reviewed:
         raise ValueError(f"review required for {len(changed)} upstream files; inspect {work / 'review.json'}, adapt, then rerun with --resume --accept-reviewed")
@@ -137,5 +158,6 @@ if __name__ == "__main__":
     try:
         main()
     except (ValueError, subprocess.CalledProcessError) as error:
-        print(f"OINK upgrade incomplete: {error}. Changes and artifacts are retained.", file=sys.stderr)
+        print(f"OINK check failed: {error}" if "--check-baseline" in sys.argv else
+              f"OINK upgrade incomplete: {error}. Changes and artifacts are retained.", file=sys.stderr)
         sys.exit(1)
diff --git a/scripts/versioning.py b/scripts/versioning.py
index 987f740d6..56ff5ee46 100644
--- a/scripts/versioning.py
+++ b/scripts/versioning.py
@@ -4070,10 +4070,15 @@ def build(args: argparse.Namespace) -> None:
             json.dumps(override, ensure_ascii=False), encoding="utf-8"
         )
         hugo = os.environ.get("HUGO_BIN", "hugo")
-        go_executable = shutil.which(os.environ.get("GO_BIN", "go"))
+        go = os.environ.get("GO_BIN", "go")
+        go_executable = shutil.which(go)
         if go_executable is None:
-            fail("Go executable is unavailable")
-        module = download_locked(assembly)
+            fail(f"Go executable is unavailable: {go}")
+        go_executable = str(pathlib.Path(go_executable).resolve())
+        try:
+            module = download_locked(assembly, go_executable)
+        except (ValueError, OSError, subprocess.CalledProcessError) as error:
+            fail(f"OINK module verification failed: {error}")
         migration_script = pathlib.Path(module["Dir"]) / "bin/migrations/oink06.py"
         if not migration_script.is_file():
             fail(f"pinned OINK migration tool is absent: {migration_script}")
diff --git a/tests/e2e/platform.spec.js b/tests/e2e/platform.spec.js
index dfa338a6d..e5765d224 100644
--- a/tests/e2e/platform.spec.js
+++ b/tests/e2e/platform.spec.js
@@ -4,7 +4,7 @@ for (const locale of ["en", "cn"]) {
   const prefix = locale === "cn" ? "/cn" : "";
   test(`latest ${locale} sidebar persists and isolates collapse`, async ({ page }) => {
     await page.goto(`${prefix}/docs/introduction/`);
-    const key = `oink.sidebar.v2.latest.${locale}`;
+    const key = `oink.sidebar.v3.latest.${locale}`;
     await expect.poll(() => page.evaluate((name) => localStorage.getItem(name), key))
       .not.toBeNull();
     const toggle = page
@@ -63,7 +63,7 @@ for (const locale of ["en", "cn"]) {
 for (const locale of ["en", "cn"]) {
   const prefix = locale === "cn" ? "/cn" : "";
   test(`latest ${locale} docs home opens start and components by default`, async ({ page }) => {
-    const key = `oink.sidebar.v2.latest.${locale}`;
+    const key = `oink.sidebar.v3.latest.${locale}`;
     await page.goto(`${prefix}/docs/`);
     await page.evaluate((name) => localStorage.removeItem(name), key);
     await page.reload();
diff --git a/tests/e2e/theme-upgrade.spec.js b/tests/e2e/theme-upgrade.spec.js
index 5be2fe849..846d80037 100644
--- a/tests/e2e/theme-upgrade.spec.js
+++ b/tests/e2e/theme-upgrade.spec.js
@@ -40,3 +40,56 @@ test('blocked storage leaves active-path navigation usable', async ({ page }) =>
   await expect(active).toHaveAttribute('aria-expanded', 'true');
   await expect(page.locator('#td-shell-sidebar .td-shell-tree__link[aria-current="page"]')).toBeVisible();
 });
+
+test('aside TOC user preference persists across reload', async ({ page }) => {
+  await page.setViewportSize({ width: 1440, height: 1000 });
+  await page.addInitScript(() => localStorage.setItem('oink.sidebar.v2.latest.en', '[]'));
+  await page.goto('/docs/introduction/');
+  await page.evaluate(() => window.OinkSidebar.ready);
+  const toggle = page.locator('[data-td-shell-aside] [aria-controls="td-shell-aside-toc"]');
+  await expect(toggle).toBeVisible();
+  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  await toggle.click();
+  await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  await page.reload();
+  await page.evaluate(() => window.OinkSidebar.ready);
+  await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  await toggle.click();
+  await expect.poll(() => page.evaluate(() => JSON.parse(localStorage.getItem('oink.sidebar.v3.latest.en'))))
+    .toContain('td-shell-aside-toc');
+  await page.reload();
+  await page.evaluate(() => window.OinkSidebar.ready);
+  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+});
+
+test('AI activation uses live text within the palette debounce window', async ({ page }) => {
+  test.skip(!process.env.AI_SITE_ROOT, 'AI-enabled fixture was not built');
+  await page.goto('http://127.0.0.1:4174/docs/');
+  await page.locator('[data-td-shell-search-open]').first().click();
+  const input = page.locator('.td-shell-search__input');
+  await input.fill('zzzxqstalezzzxq');
+  const tail = page.getByRole('option').filter({ hasText: 'Ask AI:' });
+  await expect(tail).toBeVisible();
+  await expect(tail).toHaveAttribute('aria-selected', 'true');
+  // One browser task guarantees Enter precedes OINK's 80 ms render timer.
+  await input.evaluate(input => {
+    input.value = 'zzzxqfreshzzzxq';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+  });
+  await expect(page.locator('[data-hg-ai-consent]')).toBeVisible();
+  await page.route('https://widget.kapa.ai/kapa-widget.bundle.js*', route => route.fulfill({
+    contentType: 'text/javascript', body: `
+      var queued = window.Kapa.q.slice();
+      window.Kapa = function(method, value) {
+        if (method === 'render') value.onRender();
+        if (method === 'open') window.__submittedQuery = value.query;
+      };
+      queued.forEach(args => window.Kapa(...args));`,
+  }));
+  // Keep the consent open across the delayed render; it must not abort the handoff.
+  await page.waitForTimeout(160);
+  await expect(page.locator('[data-hg-ai-consent]')).toBeVisible();
+  await page.locator('[data-hg-ai-continue]').click();
+  await expect.poll(() => page.evaluate(() => window.__submittedQuery)).toBe('zzzxqfreshzzzxq');
+});
diff --git a/tests/e2e/workflow-contract.test.cjs b/tests/e2e/workflow-contract.test.cjs
index ba7799978..955007694 100644
--- a/tests/e2e/workflow-contract.test.cjs
+++ b/tests/e2e/workflow-contract.test.cjs
@@ -48,6 +48,16 @@ test("build consumers check out the immutable prepared source SHA", () => {
   assert.match(workflow, /test \"\$GITHUB_REF\" = \"refs\/heads\/master\"/);
 });
 
+test("trusted workflow bounds the candidate module graph without pinning its version", () => {
+  const step = workflow.split("      - name: Verify pinned OINK module\n")[1]
+    .split("      - name:")[0];
+  assert.match(step, /go list -m -f '\{\{ \.Path \}\}'.*github\.com\/apache\/hugegraph-doc/);
+  assert.match(step, /go list -m all \| wc -l.*-eq 2/);
+  assert.match(step, /test -z .*\.Replace.*github\.com\/pgsty\/oink/);
+  assert.doesNotMatch(step, /github\.com\/pgsty\/oink@v/);
+  assert.match(step, /python3 scripts\/update_oink\.py --check-baseline/);
+});
+
 test("dependency artifacts keep stable names across selective reruns", () => {
   assert.match(workflow, /name: resolved-versions-\$\{\{ github\.run_id \}\}/);
   assert.match(workflow, /name: \$\{\{ needs\.prepare\.outputs\.artifact_prefix \}\}-\$\{\{ matrix\.version\.id \}\}-\$\{\{ github\.run_id \}\}/);
diff --git a/tests/ui-ai/kapa-adapter.test.cjs b/tests/ui-ai/kapa-adapter.test.cjs
index 1b157f699..efef15c22 100644
--- a/tests/ui-ai/kapa-adapter.test.cjs
+++ b/tests/ui-ai/kapa-adapter.test.cjs
@@ -382,3 +382,83 @@ test('an aborted load retries with fresh callbacks and restores launcher focus o
   h.calls.filter(([method]) => method === 'onModalClose').at(-1)[1]();
   assert.equal(h.trigger.focused, true);
 });
+
+test('widget API failures settle palette activation and permit a fresh retry', async () => {
+  for (const failingMethod of ['setSourceGroupIDs', 'open']) {
+    for (const stage of ['initial load', 'ready reopen']) {
+      const h = harness();
+      const controller = adapter.createController(h.windowObject, h.documentObject, h.config);
+      if (stage === 'ready reopen') {
+        controller.activate('', false, h.trigger);
+        h.continueConsent();
+        h.scripts[0].fire('load');
+        h.fireRender();
+      }
+      const originalKapa = h.windowObject.Kapa;
+      h.windowObject.Kapa = (method, value) => {
+        if (method === failingMethod) throw new Error('vendor failure');
+        return originalKapa(method, value);
+      };
+      const abort = new AbortController();
+      const completion = controller.activate('failing', true, h.trigger, {
+        signal: abort.signal, handoff() { return true; },
+      });
+      if (stage === 'initial load') {
+        h.continueConsent();
+        h.scripts[0].fire('load');
+        h.fireRender();
+      }
+      await assert.rejects(completion, /unavailable/);
+      assert.equal(controller.getState(), 'error');
+      assert.equal(h.trigger.disabled, false);
+      assert.equal(h.scripts[0].removed, true);
+      // Settlement must release the old cancellation listener.
+      abort.abort();
+      assert.equal(controller.getState(), 'error');
+
+      const retry = controller.activate('recovered', true, h.trigger, {
+        signal: new AbortController().signal, handoff() { return true; },
+      });
+      h.installBundle();
+      h.scripts[1].fire('load');
+      h.fireRender();
+      await retry;
+      assert.equal(controller.getState(), 'ready');
+      assert.deepEqual(h.calls.at(-1), ['open', {
+        mode: 'ai', query: 'recovered', submit: true,
+      }]);
+    }
+  }
+});
+
+test('stale activation refreshes the palette query and cancellation context', () => {
+  for (const query of ['fresh question', '', '   ', '> theme']) {
+    const h = harness();
+    let extension;
+    const refreshed = [];
+    const activated = [];
+    h.windowObject.OinkCommandPalette = {
+      registerSearchTail(value) { extension = value; },
+      instance: {
+        render(value) { refreshed.push(value); },
+        rows() { return query === 'fresh question' ? [
+          { type: 'page' }, { type: 'extension', owner: { id: 'hugegraph-ai' } },
+        ] : []; },
+        activate(index) { activated.push(index); },
+      },
+    };
+    h.trigger.addEventListener = () => {};
+    h.documentObject.getElementById = () => ({ textContent: JSON.stringify(h.config) });
+    const originalQuery = h.documentObject.querySelector;
+    h.documentObject.querySelector = selector =>
+      selector === '#td-shell-search .td-shell-search__input' ? { value: query } : originalQuery(selector);
+    adapter.init(h.windowObject, h.documentObject);
+    extension.activate({}, {
+      query: 'stale question', signal: new AbortController().signal,
+      handoff() { assert.fail('stale context must not hand off'); },
+    });
+    assert.deepEqual(refreshed, [query.trim()]);
+    assert.deepEqual(activated, query === 'fresh question' ? [1] : []);
+    assert.equal(h.scripts.length, 0);
+  }
+});
diff --git a/tests/ui-ai/sidebar-persistence.test.cjs b/tests/ui-ai/sidebar-persistence.test.cjs
index 46833cb8d..bf1017443 100644
--- a/tests/ui-ai/sidebar-persistence.test.cjs
+++ b/tests/ui-ai/sidebar-persistence.test.cjs
@@ -2,11 +2,13 @@ const assert = require('node:assert/strict');
 const test = require('node:test');
 const shell = require('../../assets/js/hugegraph-shell.js');
 
-function fixture({ saved, blocked = false, pathname = '/docs/', version = 'latest', locale = 'en' } = {}) {
-  const key = `oink.sidebar.v2.${version}.${locale}`;
+function fixture({ saved, legacy, asideExpanded = false, blocked = false, pathname = '/docs/', version = 'latest', locale = 'en' } = {}) {
+  const key = `oink.sidebar.v3.${version}.${locale}`;
   const values = new Map(saved === undefined ? [] : [[key, saved]]);
-  const ids = ['root_navstart-children', 'root_navcomponents-children', 'root_navdevelop-children', 'active'];
+  if (legacy !== undefined) values.set(`oink.sidebar.v2.${version}.${locale}`, legacy);
+  const ids = ['root_navstart-children', 'root_navcomponents-children', 'root_navdevelop-children', 'active', 'aside-toc'];
   const states = new Map(ids.map(id => [id, false]));
+  states.set('aside-toc', asideExpanded);
   const calls = [];
   const listeners = new Map();
   let ready;
@@ -19,10 +21,14 @@ function fixture({ saved, blocked = false, pathname = '/docs/', version = 'lates
     getState(id) { return { id, expanded: states.get(id) }; },
   };
   const doc = {
-    querySelectorAll() {
-      return ids.map(id => ({
+    querySelectorAll(selector) {
+      const selected = ids.filter(id => id !== 'aside-toc' || selector.includes('[data-td-shell-aside]'));
+      return selected.map(id => ({
         getAttribute() { return id; },
-        closest() { return { classList: { contains() { return id === 'active'; } } }; },
+        closest(selector) {
+          if (selector === '[data-td-shell-aside]') return id === 'aside-toc' ? {} : null;
+          return { classList: { contains() { return id === 'active'; } } };
+        },
       }));
     },
     addEventListener(name, listener) { listeners.set(name, listener); },
@@ -66,7 +72,7 @@ test('preserves stored empty choices and ignores automatic and non-sidebar event
   assert.equal(f.states.get('root_navstart-children'), false);
   f.change('root_navdevelop-children', true, 'responsive');
   assert.equal(f.values.get(f.key), '[]');
-  f.change('aside-toc', true, 'user');
+  f.change('unrelated-disclosure', true, 'user');
   assert.equal(f.values.get(f.key), '[]');
   f.change('root_navdevelop-children', true, 'user');
   assert.deepEqual(JSON.parse(f.values.get(f.key)), ['root_navdevelop-children']);
@@ -80,7 +86,7 @@ test('restores compatible stored ids and discards stale ids', async () => {
   await f.initialized;
   assert.equal(f.states.get('root_navdevelop-children'), true);
   assert.equal(f.states.get('root_navstart-children'), false);
-  assert.equal(f.calls.length, 4);
+  assert.equal(f.calls.length, 5);
 });
 
 for (const options of [{ blocked: true }, { saved: '{bad' }, { saved: '{}' }]) {
@@ -93,3 +99,32 @@ for (const options of [{ blocked: true }, { saved: '{bad' }, { saved: '{}' }]) {
     assert.doesNotThrow(() => f.change('root_navdevelop-children', true, 'user'));
   });
 }
+
+test('restores and saves aside TOC disclosures through the same API', async () => {
+  const f = fixture({ saved: '["aside-toc"]', pathname: '/docs/introduction/' });
+  f.ready();
+  await f.initialized;
+  assert.equal(f.states.get('aside-toc'), true);
+  f.change('aside-toc', false, 'user');
+  assert.equal(f.values.get(f.key), '[]');
+  f.change('aside-toc', true, 'user');
+  assert.deepEqual(JSON.parse(f.values.get(f.key)), ['aside-toc']);
+});
+
+for (const legacy of ['[]', '["root_navdevelop-children"]']) {
+  test(`migrates main-tree v2 preferences without collapsing the aside: ${legacy}`, async () => {
+    const f = fixture({ legacy, asideExpanded: true });
+    f.ready();
+    await f.initialized;
+    assert.equal(f.states.get('aside-toc'), true);
+    assert.equal(f.states.get('root_navstart-children'), false);
+    assert.equal(f.states.get('root_navdevelop-children'), legacy !== '[]');
+    assert.deepEqual(JSON.parse(f.values.get(f.key)), [...JSON.parse(legacy), 'aside-toc']);
+    f.change('aside-toc', false, 'user');
+    const reloaded = fixture({ saved: f.values.get(f.key), legacy, asideExpanded: true });
+    reloaded.ready();
+    await reloaded.initialized;
+    assert.equal(reloaded.states.get('aside-toc'), false);
+    assert.equal(reloaded.states.get('root_navdevelop-children'), legacy !== '[]');
+  });
+}