compartment 2__tar.gz → 2.2__tar.gz

{compartment-2 → compartment-2.2}/PKG-INFO

@@ -1,7 +1,30 @@
 Metadata-Version: 2.4
 Name: compartment
-Version: 2
+Version: 2.2
 Summary: Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)
+Project-URL: Homepage, https://github.com/MaxFreedomPollard/Compartment
+Project-URL: Source, https://github.com/MaxFreedomPollard/Compartment
+Project-URL: Issues, https://github.com/MaxFreedomPollard/Compartment/issues
+Project-URL: Changelog, https://github.com/MaxFreedomPollard/Compartment/releases
+Project-URL: Documentation, https://github.com/MaxFreedomPollard/Compartment#readme
+Project-URL: Security, https://github.com/MaxFreedomPollard/Compartment/blob/main/SECURITY.md
+Keywords: mcp,model-context-protocol,memory,agent-memory,vector-database,semantic-search,encryption,offline,local-first,claude,claude-code,privacy,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: pynacl>=1.5

{compartment-2 → compartment-2.2}/pyproject.toml

@@ -4,10 +4,31 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compartment"
-version = "2"
+version = "2.2"
 description = "Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)"
 readme = "README.md"
 requires-python = ">=3.11"
+keywords = ["mcp", "model-context-protocol", "memory", "agent-memory",
+            "vector-database", "semantic-search", "encryption", "offline",
+            "local-first", "claude", "claude-code", "privacy", "rag"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Operating System :: OS Independent",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Database :: Database Engines/Servers",
+    "Typing :: Typed",
+]
 dependencies = [
     "pynacl>=1.5",
     "argon2-cffi>=23.1",
@@ -17,6 +38,18 @@ dependencies = [
     "mcp>=1.0",
 ]
 
+# PyPI is the repo's declared homepage, so it is a real front door - and
+# without these it is a dead end: no Source link, no Issues link, nothing
+# carrying a reader back to GitHub. Directories that scrape PyPI were
+# producing a listing with no repository link at all.
+[project.urls]
+Homepage = "https://github.com/MaxFreedomPollard/Compartment"
+Source = "https://github.com/MaxFreedomPollard/Compartment"
+Issues = "https://github.com/MaxFreedomPollard/Compartment/issues"
+Changelog = "https://github.com/MaxFreedomPollard/Compartment/releases"
+Documentation = "https://github.com/MaxFreedomPollard/Compartment#readme"
+Security = "https://github.com/MaxFreedomPollard/Compartment/blob/main/SECURITY.md"
+
 [project.scripts]
 compartment = "compartment.cli:main"
 cmpt = "compartment.cli:main"

{compartment-2 → compartment-2.2}/src/compartment/__init__.py

@@ -1,6 +1,6 @@
 """Compartment - high-security, fully offline, encrypted vector memory for AI agents."""
 
-__version__ = "2"
+__version__ = "2.2"
 
 from . import offline_guard as _og
 

{compartment-2 → compartment-2.2}/src/compartment/crypto.py

@@ -19,6 +19,8 @@ from nacl.bindings import (
     crypto_aead_xchacha20poly1305_ietf_encrypt,
 )
 
+from . import wire
+
 KEY_LEN = 32
 NONCE_LEN = 24
 
@@ -81,6 +83,35 @@ def unseal(key: bytes, blob: bytes, aad: bytes = b"") -> bytes:
         ) from exc
 
 
+def unseal_which(key: bytes, blob: bytes, aad: bytes,
+                 legacy: tuple[bytes, ...] = ()) -> tuple[bytes, bytes]:
+    """unseal(), accepting associated data written by an older build.
+
+    Returns (plaintext, the aad that actually authenticated), so a caller can
+    tell a migrated blob from one still carrying a legacy label and rewrite it.
+
+    The current spelling is tried first, so anything already migrated costs
+    exactly one AEAD open. Legacy spellings are tried in order only after that
+    fails, which is what lets a pre-rename vault open at all. If none of them
+    authenticate the data really is tampered with, or the key really is wrong,
+    and the original error is raised."""
+    try:
+        return unseal(key, blob, aad=aad), aad
+    except TamperError:
+        for old in legacy:
+            try:
+                return unseal(key, blob, aad=old), old
+            except TamperError:
+                continue
+        raise
+
+
+def unseal_any(key: bytes, blob: bytes, aad: bytes,
+               legacy: tuple[bytes, ...] = ()) -> bytes:
+    """unseal_which() when the caller does not care which label was used."""
+    return unseal_which(key, blob, aad, legacy)[0]
+
+
 def wipe(buf: bytearray) -> None:
     """Best-effort zeroization (Python cannot guarantee no copies exist)."""
     for i in range(len(buf)):
@@ -99,7 +130,7 @@ def make_passphrase_slot(master_key: bytes, passphrase: str, kdf: dict | None =
         "type": "passphrase",
         "kdf": kdf,
         "salt": salt.hex(),
-        "wrapped": seal(wrap_key, master_key, aad=b"engram-keyslot").hex(),
+        "wrapped": seal(wrap_key, master_key, aad=wire.KEYSLOT).hex(),
     }
 
 
@@ -118,7 +149,7 @@ def make_recovery_slot(master_key: bytes, kdf: dict | None = None) -> tuple[dict
 # Domain separator between the knowledge factor (passphrase) and the
 # possession factor (keyfile bytes) before the KDF. Both factors feed
 # Argon2id, so two-factor unlock is enforced by arithmetic, not policy.
-KEYFILE_SEP = b"\x1f engram-2fa \x1f"
+KEYFILE_SEP = wire.KEYFILE_SEP
 KEYFILE_LEN = 32
 
 
@@ -137,19 +168,57 @@ def make_keyfile_slot(master_key: bytes, passphrase: str, keyfile: bytes,
         "kdf": kdf,
         "salt": salt.hex(),
         "keyfile_id": sha256(keyfile)[:16],   # UX only: detect the WRONG file
-        "wrapped": seal(wrap_key, master_key, aad=b"engram-keyslot").hex(),
+        "wrapped": seal(wrap_key, master_key, aad=wire.KEYSLOT).hex(),
     }
 
 
-def open_slot(slot: dict, secret: str, keyfile: bytes | None = None) -> bytes:
-    """Unwrap the master key from one slot."""
+def _slot_secrets(slot: dict, secret: str, keyfile: bytes | None) -> list[bytes]:
+    """The KDF inputs worth trying for this slot, current spelling first.
+
+    Only a two-factor slot has more than one. Its separator is a KDF input
+    rather than associated data, so an older separator derives a different
+    wrap key and can only be ruled out by deriving again."""
     raw = secret.encode("utf-8")
-    if slot["type"] == "passphrase+keyfile":
-        if keyfile is None:
-            raise CryptoError("This keyslot requires a keyfile")
-        raw = raw + KEYFILE_SEP + keyfile
-    wrap_key = derive_key(raw, bytes.fromhex(slot["salt"]), slot["kdf"])
-    return unseal(wrap_key, bytes.fromhex(slot["wrapped"]), aad=b"engram-keyslot")
+    if slot["type"] != "passphrase+keyfile":
+        return [raw]
+    if keyfile is None:
+        raise CryptoError("This keyslot requires a keyfile")
+    return [raw + sep + keyfile
+            for sep in (wire.KEYFILE_SEP, *wire.KEYFILE_SEP_LEGACY)]
+
+
+def open_slot(slot: dict, secret: str, keyfile: bytes | None = None) -> bytes:
+    """Unwrap the master key from one slot.
+
+    A slot written before 2.2 carries the legacy associated data, and a
+    two-factor one the legacy keyfile separator. Both still open. The slot is
+    then rewritten in place under the current spelling, so it migrates the
+    first time its credential is used; the caller persists that by saving the
+    header. Re-sealing only happens when something was actually legacy, or
+    every unlock would dirty the header and force a needless vault rewrite."""
+    salt, kdf = bytes.fromhex(slot["salt"]), slot["kdf"]
+    wrapped = bytes.fromhex(slot["wrapped"])
+    failure: TamperError | None = None
+    for i, raw in enumerate(_slot_secrets(slot, secret, keyfile)):
+        wrap_key = derive_key(raw, salt, kdf)
+        try:
+            master, used = unseal_which(wrap_key, wrapped, wire.KEYSLOT,
+                                        wire.KEYSLOT_LEGACY)
+        except TamperError as exc:
+            failure = exc
+            continue
+        if i:
+            # legacy separator: the wrap key itself is stale, so the slot has
+            # to be built again from scratch (a second Argon2id pass, once).
+            fresh = make_keyfile_slot(master, secret, keyfile, kdf)
+            fresh["type"] = slot["type"]
+            slot.clear()
+            slot.update(fresh)
+        elif used != wire.KEYSLOT:
+            # same wrap key, only the associated data moves. Free.
+            slot["wrapped"] = seal(wrap_key, master, aad=wire.KEYSLOT).hex()
+        return master
+    raise failure if failure is not None else TamperError("Keyslot did not open")
 
 
 def unwrap_master(keyslots: list[dict], secret: str,
@@ -190,16 +259,20 @@ def normalize_recovery(text: str) -> str:
 # Per-record keys → crypto-shred
 # ---------------------------------------------------------------------------
 
+def wrap_record_key(master_key: bytes, record_id: str, record_key: bytes) -> bytes:
+    aad, _ = wire.record_key(record_id)
+    return seal(master_key, record_key, aad=aad)
+
+
 def new_record_key(master_key: bytes, record_id: str) -> tuple[bytes, bytes]:
     """Returns (record_key, wrapped_record_key). Destroying the wrapped key
     makes the record's ciphertext permanently undecryptable (crypto-shred)."""
     rk = new_key()
-    wrapped = seal(master_key, rk, aad=b"engram-record:" + record_id.encode())
-    return rk, wrapped
+    return rk, wrap_record_key(master_key, record_id, rk)
 
 
 def unwrap_record_key(master_key: bytes, record_id: str, wrapped: bytes) -> bytes:
-    return unseal(master_key, wrapped, aad=b"engram-record:" + record_id.encode())
+    return unseal_any(master_key, wrapped, *wire.record_key(record_id))
 
 
 # 256 short, common, distinct words for recovery phrases (16 words = 128 bits).

{compartment-2 → compartment-2.2}/src/compartment/menubar.py

@@ -396,6 +396,8 @@ def run(vault: str | None = None, show: bool = False,
                             NSRunningApplication,
                             NSFont, NSImage, NSMakeRect, NSMenu, NSMenuItem,
                             NSPanel, NSPopover, NSScreen, NSSegmentedControl,
+                            NSClipView, NSScrollView,
+                            NSBitmapImageRep, NSGraphicsContext,
                             NSSecureTextField, NSStackView, NSStatusBar,
                             NSSwitch, NSTextField,
                             NSButton, NSView, NSViewController,
@@ -468,6 +470,17 @@ def run(vault: str | None = None, show: bool = False,
             CONTENT_WIDTH).setActive_(True)
         return b
 
+    class TopClip(NSClipView):
+        """A clip view whose origin is its top left corner.
+
+        AppKit's default is the bottom left, which inside a scroll view means
+        the panel opens showing its last line, with the title somewhere above
+        the fold. Flipping it makes "scrolled to the top" the resting state.
+        """
+
+        def isFlipped(self):
+            return True
+
     class Controller(NSObject):
         def init(self):
             self = objc.super(Controller, self).init()
@@ -485,8 +498,78 @@ def run(vault: str | None = None, show: bool = False,
             return self
 
         # ---- building the popover contents -----------------------------
+        @objc.python_method
+        def _finish(self, views):
+            stack = NSStackView.stackViewWithViews_(views)
+            stack.setOrientation_(_VERTICAL)
+            stack.setAlignment_(_LEADING)
+            stack.setSpacing_(6)
+            stack.setEdgeInsets_((CONTENT_INSET, CONTENT_INSET,
+                                  CONTENT_INSET, CONTENT_INSET))
+            stack.layoutSubtreeIfNeeded()
+            fit = stack.fittingSize()
+            stack.setFrameSize_((POPOVER_WIDTH, fit.height))
+            if fit.height <= POPOVER_MAX_HEIGHT:
+                return stack
+
+            # Taller than a popover is allowed to be. Scroll it. What this
+            # did before was cut the overflow off and say nothing, so the
+            # buttons below the fold were not merely out of reach - there
+            # was no sign they existed. That is how the passphrase form
+            # came to show one box out of two.
+            stack.setTranslatesAutoresizingMaskIntoConstraints_(True)
+            box = NSMakeRect(0, 0, POPOVER_WIDTH, POPOVER_MAX_HEIGHT)
+            scroll = NSScrollView.alloc().initWithFrame_(box)
+            scroll.setContentView_(TopClip.alloc().initWithFrame_(box))
+            scroll.setHasVerticalScroller_(True)
+            scroll.setDrawsBackground_(False)
+            scroll.setDocumentView_(stack)
+            return scroll
+
+        @objc.python_method
+        def buildChangeBody(self, st):
+            """Changing the passphrase gets the whole panel to itself.
+
+            The ordinary panel already fills POPOVER_MAX_HEIGHT, and this
+            popover clips instead of scrolling. Appending the fields to the
+            bottom of it put the second box, Save, and the error note below
+            the visible edge: you saw one box, pressed Return, and the save
+            failed its repeat check against an empty field you could neither
+            fill nor read the complaint about. A focused view cannot overflow.
+            """
+            def secure(placeholder):
+                f = NSSecureTextField.alloc().initWithFrame_(
+                    NSMakeRect(0, 0, CONTENT_WIDTH, 24))
+                f.setPlaceholderString_(placeholder)
+                f.setTarget_(self)
+                f.setAction_("saveChangePw:")     # Return saves
+                return f
+
+            self.pw_new = secure("New passphrase")
+            self.pw_repeat = secure("Repeat it")
+            views = [row(label("Change password", 15, bold=True), _spacer()),
+                     label(summarise(st), 11, secondary=True),
+                     divider(),
+                     row(self.pw_new),
+                     row(self.pw_repeat)]
+            if self.change_note:
+                views.append(label(self.change_note, 11, secondary=True,
+                                   wrap=True))
+            views.append(label("Both boxes must match. There is no recovery "
+                               "phrase - if you forget this, the memories are "
+                               "unrecoverable.", 10, secondary=True, wrap=True))
+            save_b = NSButton.buttonWithTitle_target_action_("Save", self,
+                                                             "saveChangePw:")
+            save_b.setKeyEquivalent_("\r")
+            cancel_b = NSButton.buttonWithTitle_target_action_(
+                "Cancel", self, "cancelChangePw:")
+            views.append(row(save_b, cancel_b, _spacer()))
+            return self._finish(views)
+
         def buildBody(self):
             st = self.state
+            if self.changing_pw and st["exists"] and not st["locked"]:
+                return self.buildChangeBody(st)
             views = []
             title = row(label("Compartment", 15, bold=True),
                         label("locked" if st["locked"] else "unlocked", 11,
@@ -516,33 +599,11 @@ def run(vault: str | None = None, show: bool = False,
                 views.append(label("Stays unlocked until restart or Lock",
                                    10, secondary=True))
 
-            # Changing the passphrase needs the vault open, because rekey
-            # re-wraps a master key it can only hold while unlocked.
+            # Changing the passphrase is a separate view: see buildChangeBody.
             self.pw_new = self.pw_repeat = None
-            if st["exists"] and not st["locked"] and self.changing_pw:
-                def secure(placeholder):
-                    f = NSSecureTextField.alloc().initWithFrame_(
-                        NSMakeRect(0, 0, CONTENT_WIDTH - 92, 24))
-                    f.setPlaceholderString_(placeholder)
-                    f.setTarget_(self)
-                    f.setAction_("saveChangePw:")     # Return saves
-                    return f
-
-                self.pw_new = secure("New passphrase")
-                self.pw_repeat = secure("Repeat it")
-                save_b = NSButton.buttonWithTitle_target_action_(
-                    "Save", self, "saveChangePw:")
-                cancel_b = NSButton.buttonWithTitle_target_action_(
-                    "Cancel", self, "cancelChangePw:")
-                views.append(self.pw_new)
-                views.append(row(self.pw_repeat, save_b))
-                views.append(row(cancel_b, _spacer()))
-                if self.change_note:
-                    views.append(label(self.change_note, 11, secondary=True,
-                                       wrap=True))
-                views.append(label("There is no recovery phrase. If you forget "
-                                   "this, the memories are unrecoverable.",
-                                   10, secondary=True, wrap=True))
+            if self.change_note:
+                views.append(label(self.change_note, 11, secondary=True,
+                                   wrap=True))
             views.append(divider())
 
             views.append(label("SETTINGS", 10, bold=True, secondary=True))
@@ -613,17 +674,7 @@ def run(vault: str | None = None, show: bool = False,
             else:
                 views.append(row(refresh, _spacer(), quit_b))
 
-            stack = NSStackView.stackViewWithViews_(views)
-            stack.setOrientation_(_VERTICAL)
-            stack.setAlignment_(_LEADING)
-            stack.setSpacing_(6)
-            stack.setEdgeInsets_((CONTENT_INSET, CONTENT_INSET,
-                                  CONTENT_INSET, CONTENT_INSET))
-            stack.layoutSubtreeIfNeeded()
-            fit = stack.fittingSize()
-            stack.setFrameSize_((POPOVER_WIDTH,
-                                 min(fit.height, POPOVER_MAX_HEIGHT)))
-            return stack
+            return self._finish(views)
 
         # Not an action: PyObjC infers a selector from the method name, and
         # a name with no trailing underscores means "takes no arguments".
@@ -802,14 +853,33 @@ def run(vault: str | None = None, show: bool = False,
     _d("controller ready")
 
     if render_to:
-        # app.run() normally does this; without it the text system is not up
-        # and the snapshot comes out with controls but no glyphs at all.
+        # app.run() normally does this; without it the text system is not up.
         app.finishLaunching()
         body = ctrl.buildBody()
         body.layoutSubtreeIfNeeded()
         bounds = body.bounds()
-        rep = body.bitmapImageRepForCachingDisplayInRect_(bounds)
-        body.cacheDisplayInRect_toBitmapImageRep_(bounds, rep)
+        # Render through PDF, not cacheDisplayInRect. Caching a view that
+        # belongs to no window gives you the switches and the segmented
+        # control and not one glyph of text, because there is no window
+        # backing store for the text system to lay glyphs into. Ordering an
+        # offscreen window in does not help either: it draws as an inactive
+        # window, so even the controls lose their tint. The PDF path records
+        # glyphs vectorially with their fonts embedded and needs no window at
+        # all, so it captures the panel exactly as designed. Rasterise at 2x
+        # for a Retina-sharp asset.
+        pdf = body.dataWithPDFInsideRect_(bounds)
+        w, h = bounds.size.width, bounds.size.height
+        image = NSImage.alloc().initWithData_(pdf)
+        rep = (NSBitmapImageRep.alloc()
+               .initWithBitmapDataPlanes_pixelsWide_pixelsHigh_bitsPerSample_samplesPerPixel_hasAlpha_isPlanar_colorSpaceName_bytesPerRow_bitsPerPixel_(
+                   None, int(w * 2), int(h * 2), 8, 4, True, False,
+                   "NSCalibratedRGBColorSpace", 0, 0))
+        rep.setSize_((w, h))
+        NSGraphicsContext.saveGraphicsState()
+        NSGraphicsContext.setCurrentContext_(
+            NSGraphicsContext.graphicsContextWithBitmapImageRep_(rep))
+        image.drawInRect_(NSMakeRect(0, 0, w, h))
+        NSGraphicsContext.restoreGraphicsState()
         png = rep.representationUsingType_properties_(4, {})   # 4 = PNG
         ok = png.writeToFile_atomically_(render_to, True)
         print(f"rendered popover -> {render_to}" if ok

{compartment-2 → compartment-2.2}/src/compartment/packs.py

@@ -20,7 +20,7 @@ import struct
 import numpy as np
 from nacl.signing import SigningKey, VerifyKey
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError, TamperError
 from .vaultfile import pack_sections, unpack_sections
 
@@ -71,7 +71,7 @@ def build_pack(*, name: str, version: str, description: str, records: list[dict]
     if passphrase is not None:
         salt = secrets.token_bytes(16)
         key = crypto.derive_key(passphrase.encode(), salt)
-        body = crypto.seal(key, body, aad=b"engram-pack:" + name.encode())
+        body = crypto.seal(key, body, aad=wire.pack(name)[0])
         header["kdf"] = crypto.DEFAULT_KDF
         header["salt"] = salt.hex()
     header["content_sha256"] = crypto.sha256(body)
@@ -119,7 +119,7 @@ def read_pack(blob: bytes, passphrase: str | None = None
             raise PackError(f"Pack {header['name']!r} is encrypted; passphrase required")
         key = crypto.derive_key(passphrase.encode(), bytes.fromhex(header["salt"]),
                                 header["kdf"])
-        body = crypto.unseal(key, body, aad=b"engram-pack:" + header["name"].encode())
+        body = crypto.unseal_any(key, body, *wire.pack(header["name"]))
 
     sections = unpack_sections(body)
     records = [json.loads(l) for l in

{compartment-2 → compartment-2.2}/src/compartment/session.py

@@ -25,7 +25,7 @@ import os
 import stat
 from pathlib import Path
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError, TamperError
 from .platforms import boot_time, machine_id
 
@@ -49,17 +49,16 @@ def _uid() -> str:
     return str(getuid()) if getuid else os.environ.get("USERNAME", "user")
 
 
-def _boot_key() -> bytes:
+def _boot_key(token: str = wire.SESSION_TOKEN) -> bytes:
     """Wrap key valid only for this boot session of this user on this
     machine. Uses the stable hardware machine id, NOT the hostname -
     macOS renames the host per network, which must not relock the vault."""
-    token = "|".join((
-        "engram-session-v2",
+    return hashlib.sha256("|".join((
+        token,
         _boot_time(),
         _uid(),
         machine_id(),
-    ))
-    return hashlib.sha256(token.encode()).digest()
+    )).encode()).digest()
 
 
 def _canon(vault_path: str) -> str:
@@ -83,7 +82,7 @@ def store(vault_path: str, master_key: bytes) -> Path:
     """Persist a boot-bound unlock credential for this vault."""
     p = _file_for(vault_path)
     blob = crypto.seal(_boot_key(), master_key,
-                       aad=b"engram-session:" + _canon(vault_path).encode())
+                       aad=wire.session(_canon(vault_path))[0])
     p.write_text(json.dumps({"vault": _canon(vault_path),
                              "wrapped": blob.hex()}), encoding="utf-8")
     os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)  # 0600
@@ -92,15 +91,29 @@ def store(vault_path: str, master_key: bytes) -> Path:
 
 def get(vault_path: str) -> bytes | None:
     """Return the master key if a credential exists AND we are still in the
-    same boot session; otherwise remove the stale file and return None."""
+    same boot session; otherwise remove the stale file and return None.
+
+    A credential written before 2.2 is bound to the older token and sealed
+    under the older associated data. It is accepted and then rewritten in the
+    current form, so upgrading Compartment does not relock a vault that was
+    already open."""
     p = _file_for(vault_path)
     if not p.is_file():
         return None
+    canon = _canon(vault_path)
+    aad, legacy_aad = wire.session(canon)
     try:
-        data = json.loads(p.read_text(encoding="utf-8"))
-        return crypto.unseal(
-            _boot_key(), bytes.fromhex(data["wrapped"]),
-            aad=b"engram-session:" + _canon(vault_path).encode())
+        blob = bytes.fromhex(json.loads(p.read_text(encoding="utf-8"))["wrapped"])
+        for token in (wire.SESSION_TOKEN, *wire.SESSION_TOKEN_LEGACY):
+            try:
+                key, used = crypto.unseal_which(_boot_key(token), blob,
+                                                aad, legacy_aad)
+            except TamperError:
+                continue
+            if token != wire.SESSION_TOKEN or used != aad:
+                store(vault_path, key)
+            return key
+        raise TamperError("No boot-session token opened the credential")
     except (TamperError, CryptoError, ValueError, KeyError, OSError):
         # different boot (restart/power loss) or corrupt file → locked
         try:

{compartment-2 → compartment-2.2}/src/compartment/store.py

@@ -14,7 +14,7 @@ import uuid
 
 import numpy as np
 
-from . import crypto
+from . import crypto, wire
 from .crypto import CryptoError
 
 SCHEMA = """
@@ -110,7 +110,7 @@ class Store:
         rid = record_id or uuid.uuid4().hex
         rk, wrapped = crypto.new_record_key(master_key, rid)
         ct = crypto.seal(rk, crypto.canonical_json({"text": text}),
-                         aad=b"engram-record-body:" + rid.encode())
+                         aad=wire.record_body(rid)[0])
         now = time.time()
         self.conn.execute(
             "INSERT INTO records (id, ikey, ns, ct, key_wrapped, vec, dim, tags, importance,"
@@ -129,9 +129,35 @@ class Store:
 
     def decrypt_text(self, row: sqlite3.Row, master_key: bytes) -> str:
         rk = crypto.unwrap_record_key(master_key, row["id"], row["key_wrapped"])
-        body = crypto.unseal(rk, row["ct"], aad=b"engram-record-body:" + row["id"].encode())
+        body = crypto.unseal_any(rk, row["ct"], *wire.record_body(row["id"]))
         return json.loads(body)["text"]
 
+    def migrate_wire(self, master_key: bytes) -> int:
+        """Rewrite every record under the current associated data.
+
+        Records are the one place the labels do not migrate for free: a row's
+        key wrap and ciphertext are written on insert and never touched again,
+        so without this pass every read of every pre-2.2 record would pay a
+        failed AEAD open before the one that works, forever. Vault.unlock
+        calls this once and records it in the header.
+
+        The record key is kept and re-wrapped rather than rotated, so the
+        plaintext is the only thing that round-trips. Nothing is written to
+        disk here: this mutates the in-memory database, and the caller's
+        save() is what makes it real, atomically. If any row fails to decrypt
+        the error propagates and no save happens, so a vault is never left
+        half-converted."""
+        rows = self.conn.execute("SELECT id, ct, key_wrapped FROM records").fetchall()
+        for row in rows:
+            rid = row["id"]
+            rk = crypto.unwrap_record_key(master_key, rid, row["key_wrapped"])
+            body = crypto.unseal_any(rk, row["ct"], *wire.record_body(rid))
+            self.conn.execute(
+                "UPDATE records SET ct = ?, key_wrapped = ? WHERE id = ?",
+                (crypto.seal(rk, body, aad=wire.record_body(rid)[0]),
+                 crypto.wrap_record_key(master_key, rid, rk), rid))
+        return len(rows)
+
     def delete(self, record_id: str, shred: bool) -> bool:
         """Delete a record. shred=True also VACUUMs so the content (including
         FTS tokens and freed pages) is gone from the next serialized image,