@jaguilar87/gaia 5.1.0 → 5.1.1

package/gaia/store/writer.py

@@ -46,6 +46,7 @@ _KNOWN_TABLES = {
     "libraries",
     "services",
     "features",
+    "project_facets",
     "tf_modules",
     "tf_live",
     "releases",
@@ -59,7 +60,7 @@ _KNOWN_TABLES = {
 
 
 # ---------------------------------------------------------------------------
-# Semantic-grant lifetime (Brief 71, Change 3a)
+# Semantic-grant lifetime (approvals redesign, M1)
 # ---------------------------------------------------------------------------
 #
 # APPROVAL_GRANT_TTL_MINUTES is the default lifetime of an ACTIVE semantic grant
@@ -71,21 +72,23 @@ _KNOWN_TABLES = {
 # 24h), which is how long an UNANSWERED approval waits for the user. The two must
 # not be conflated: a 24h pending window lets a human come back the next day,
 # while the grant window is the short, post-approval execution horizon. Collapsing
-# them would either shrink the approval wait to 1h (a regression) or stretch the
+# them would either shrink the approval wait to 5m (a regression) or stretch the
 # grant lifetime to 24h (a security weakening). See the regression guards in
 # tests/hooks/test_pending_scanner_cleanup.py::TestTTLConstants.
 #
-# The value moved 5 -> 60 (Change 3a) so that a human-in-the-loop approval which
-# crosses a session boundary (block under the subagent session, approve under the
-# orchestrator, retry under the subagent) does not silently expire before it can
-# be consumed. 60 aligns with the 1-hour staleness horizon.
+# The value is 5 minutes (approvals redesign, M1). The grant is consumed AT THE
+# MATCH (bash_validator flips the row PENDING->CONSUMED when it authorizes the
+# command in PreToolUse, before execution), so this short window only needs to
+# cover the block -> approve -> retry round trip; a grant that is never presented
+# to a matching retry simply expires. Replay protection comes from consume-at-
+# match plus this short TTL, not from a long-lived grant.
 #
 # It lives HERE, in gaia.store.writer, because writer is the dependency leaf of
 # the approval planes: gaia.approvals.store already imports from this module
 # (_connect) and the hooks approval_grants module already imports
 # insert_semantic_grant from here, while writer imports neither -- so any consumer
 # can read this constant without a circular import.
-APPROVAL_GRANT_TTL_MINUTES = 60
+APPROVAL_GRANT_TTL_MINUTES = 5
 
 
 # ---------------------------------------------------------------------------
@@ -171,20 +174,31 @@ def _applied(extra: dict | None = None) -> dict:
 # ---------------------------------------------------------------------------
 
 def _resolve_identity(workspace: str, workspace_path: Path | None = None) -> str:
-    """Resolve workspace identity.
+    """Resolve workspace identity -- REMOTE-derived, read directly (M2-T7).
 
-    Rule (post-fix):
+    Rule:
       * If ``workspace_path`` is provided AND ``workspace_path / .git`` exists
         (the workspace root is itself a git project), resolve identity from
-        the git remote of that directory via ``gaia.project.current``.
+        the git remote of that directory, read DIRECTLY via
+        ``gaia.project._git_remote_origin`` + ``_normalize_remote``.
       * Otherwise (organizational workspace -- no .git at the root), the
         identity IS the workspace name. We do NOT leak the remote of a child
         project up to the workspace row.
 
-    This prevents the historical contamination where a workspace like ``me``
-    received the identity of its first scanned child project.
+    This deliberately does NOT go through ``gaia.project.current()``. As of
+    M2-T7 (AC-9) ``current()`` is PATH-based (it answers "which workspace am I
+    in" by disk location, not by remote). The ``workspaces.identity`` column,
+    however, must remain the normalized git remote (``host/owner/repo``) so two
+    clones of the same remote collapse to the same identity row (the B0 design
+    in ``tools/scan/store_populator.py``). Reading the remote directly here
+    decouples the identity column from ``current()``'s path-first behavior and
+    preserves the remote-derived semantic.
 
-    Falls back to the workspace string itself when path resolution fails.
+    This also prevents the historical contamination where a workspace like
+    ``me`` received the identity of its first scanned child project.
+
+    Falls back to the workspace string itself when path resolution fails or no
+    remote is configured.
 
     Args:
         workspace:      Workspace name used as the fallback / organizational identity.
@@ -200,10 +214,12 @@ def _resolve_identity(workspace: str, workspace_path: Path | None = None) -> str
     try:
         if not (workspace_path / ".git").is_dir():
             return workspace.lower()
-        from gaia.project import current as _project_current
-        ident = _project_current(cwd=workspace_path)
-        if ident and ident != "global":
-            return ident
+        from gaia.project import _git_remote_origin, _normalize_remote
+        remote = _git_remote_origin(workspace_path)
+        if remote:
+            ident = _normalize_remote(remote)
+            if ident:
+                return ident
     except Exception:
         pass
     return workspace.lower()
@@ -348,11 +364,185 @@ def mark_workspace_demoted(
         con.close()
 
 
+# ---------------------------------------------------------------------------
+# Column ownership map (coalesce-or-omit + agent-owned protection)
+# ---------------------------------------------------------------------------
+#
+# Ported from tools/scan/orchestrator.py's SCANNER_OWNED_TOP_LEVEL /
+# AGENT_ENRICHED_SECTIONS split (the retired project-context.json ownership
+# model) down to the DB write path (workspace-identity brief, M1-T2).
+#
+# Semantics:
+#   * Coalesce-or-omit: a column is only written when its key is PRESENT in
+#     the caller's `fields` mapping (even when the value is explicitly None,
+#     e.g. ``missing_since=None`` to reactivate a project). A key ABSENT from
+#     `fields` is left OUT of the INSERT/UPDATE entirely -- the column keeps
+#     its current value instead of being forced to NULL just because a given
+#     scan run's payload did not mention it. This is the fix for the
+#     "columns go NULL when a rescan omits them" clobber.
+#   * Agent-owned protection: a column named in the table's `_AGENT_OWNED`
+#     set is stripped from `fields` before the coalesce-or-omit step
+#     whenever the caller passes ``strip_agent_owned=True`` -- the scan path
+#     (bulk_upsert's projects/apps branches, populate_project) always does.
+#     A direct caller that does NOT set ``strip_agent_owned`` (tests, or any
+#     future agent-driven write) keeps full write access -- the flag gates
+#     the SCAN PATH specifically, not the column in the abstract.
+#
+# M3/T9: `description` is agent-owned (schema v23, scripts/migrations/
+# v22_to_v23.sql). The scan path (strip_agent_owned=True) can never write it,
+# regardless of what a caller's `fields` dict happens to contain -- it is
+# stripped by _present_fields before the coalesce-or-omit step, same
+# mechanism already proven for apps.description/status in M1.
+_PROJECTS_AGENT_OWNED: frozenset = frozenset({"description"})
+# NOTE: `role` is NOT agent-owned here (M1-T3): it is auto-detected by
+# tools/scan/role_detector.py and refreshed on every scan, so it belongs to
+# the scanner. See schema.sql's `role` column comment for the same note.
+_APPS_AGENT_OWNED: frozenset = frozenset({"description", "status"})
+
+
+def _present_fields(
+    fields: Mapping[str, Any],
+    recognized: Sequence[str],
+    *,
+    strip: frozenset = frozenset(),
+) -> dict:
+    """Return the subset of `recognized` keys actually supplied in `fields`.
+
+    Powers coalesce-or-omit: building the INSERT/UPDATE column list from this
+    dict's keys means an omitted scanner-owned column is never forced to NULL,
+    and (when `strip` names the table's agent-owned columns) the scan path can
+    never write agent-owned data regardless of what its payload happens to
+    include.
+    """
+    return {k: fields[k] for k in recognized if k in fields and k not in strip}
+
+
+def _find_collision_free_name(
+    con: sqlite3.Connection,
+    workspace: str,
+    name: str,
+    project_identity: str | None,
+) -> str:
+    """Return a `projects.name` guaranteed not to collide with a DIFFERENT
+    physical repo already occupying ``(workspace, name)``.
+
+    Two distinct repos (distinct ``project_identity``) can legitimately share
+    a basename under the same workspace (e.g. two "foo" repos nested under
+    different containers). Without this guard, upserting the second one would
+    silently overwrite the first via the ``(workspace, name)`` UNIQUE
+    constraint -- the collision-key defect (workspace-identity brief, AC-2).
+
+    Read-only (issues no writes) so it is safe to call from a dry-run preview
+    as well as from inside upsert_project's write transaction. When the
+    existing occupant shares the SAME identity (or the slot is free, or the
+    slot's identity is unset/legacy), the name is returned unchanged --
+    disambiguation only fires for a CONFIRMED different physical repo.
+
+    Args:
+        con: Open connection (used read-only here).
+        workspace: Workspace name.
+        name: Candidate project name.
+        project_identity: The NEW row's stable identity, or None/empty (in
+            which case no collision can be detected and `name` is returned
+            unchanged).
+
+    Returns:
+        `name` unchanged, or `name` suffixed with `-2`, `-3`, ... until a free
+        (or same-identity) slot is found.
+    """
+    if not project_identity:
+        return name
+
+    def _occupied_by_other(candidate: str) -> bool:
+        row = con.execute(
+            "SELECT project_identity FROM projects WHERE workspace = ? AND name = ?",
+            (workspace, candidate),
+        ).fetchone()
+        existing_identity = row["project_identity"] if row else None
+        return bool(existing_identity) and existing_identity != project_identity
+
+    if not _occupied_by_other(name):
+        return name
+
+    suffix = 2
+    while True:
+        candidate = f"{name}-{suffix}"
+        if not _occupied_by_other(candidate):
+            return candidate
+        suffix += 1
+
+
+def preview_project_name(
+    workspace: str,
+    name: str,
+    project_identity: str | None,
+    *,
+    db_path: Path | None = None,
+    extra_claimed: Mapping[str, str] | None = None,
+) -> str:
+    """Read-only preview of the name :func:`upsert_project` would actually use.
+
+    Lets a dry-run report the REAL, collision-free name without writing
+    anything. ``extra_claimed`` lets a caller iterating a batch of repos in
+    one pass (e.g. ``tools/scan/classify.py::scan``) fold in names already
+    "claimed" earlier in the SAME batch -- names that a real ``apply=True``
+    run would already have committed to the DB by the time a later repo in
+    the batch is processed (commits are sequential), but that a dry-run,
+    which writes nothing, cannot see via the DB alone.
+
+    Args:
+        workspace: Workspace name.
+        name: Candidate project name.
+        project_identity: The repo's stable identity, or None/empty.
+        db_path: Optional explicit DB path (used by tests).
+        extra_claimed: Optional ``{name: project_identity}`` map of names
+            already claimed earlier in the same in-progress batch.
+
+    Returns:
+        The name that would be used, disambiguated if needed.
+    """
+    if not project_identity:
+        return name
+    if extra_claimed and name in extra_claimed:
+        if extra_claimed[name] == project_identity:
+            return name
+        # In-memory collision against an earlier repo in this same batch --
+        # resolve purely in-memory first (no DB round trip needed to know
+        # this slot is taken), then fall through to the DB-aware resolver
+        # starting from the first candidate suffix.
+        suffix = 2
+        while True:
+            candidate = f"{name}-{suffix}"
+            claimed_identity = extra_claimed.get(candidate)
+            if claimed_identity is None:
+                break
+            if claimed_identity == project_identity:
+                return candidate
+            suffix += 1
+        name = candidate
+
+    # Dry-run touches-nothing guarantee: never let a PREVIEW materialize the
+    # DB. `_connect()` runs schema.sql when the file is absent, which would
+    # create the data dir during a --dry-run scan (regression caught by
+    # tests/cli/test_scan.py::test_dry_run_does_not_touch_db). A DB that does
+    # not yet exist has zero rows to collide with, so the in-memory
+    # `extra_claimed` resolution above is already the complete answer.
+    resolved = db_path if db_path is not None else _db_path()
+    if not resolved.exists():
+        return name
+
+    con = _connect(resolved)
+    try:
+        return _find_collision_free_name(con, workspace, name, project_identity)
+    finally:
+        con.close()
+
+
 # ---------------------------------------------------------------------------
 # Public API: upsert_project
 # ---------------------------------------------------------------------------
 
-_PROJECT_FIELDS = ("role", "remote_url", "platform", "primary_language", "group_name", "path", "status", "missing_since", "project_identity")
+_PROJECT_FIELDS = ("role", "remote_url", "platform", "primary_language", "group_name", "path", "status", "missing_since", "project_identity", "description")
 
 
 def _projects_has_identity_column(con: sqlite3.Connection) -> bool:
@@ -376,6 +566,7 @@ def upsert_project(
     *,
     db_path: Path | None = None,
     workspace_path: Path | None = None,
+    strip_agent_owned: bool = False,
 ) -> dict:
     """Upsert a projects row, enforcing per-agent write permission.
 
@@ -385,26 +576,39 @@ def upsert_project(
         fields: Dict of column->value pairs. Recognized keys:
             ``role``, ``remote_url``, ``platform``, ``primary_language``,
             ``group_name``, ``path``, ``status``, ``missing_since``,
-            ``project_identity``. When ``project_identity`` is non-null and the
-            live schema carries the column (v18+), the UPSERT collapses on that
-            stable identity: the SAME physical repo scanned from different
-            workspaces/roots updates the existing row IN PLACE (preserving its
-            original (workspace, name) PK) instead of inserting a duplicate.
-            ``status`` defaults to 'active' when not provided. ``missing_since``
-            defaults to NULL. On re-upsert of a live project (status='active')
-            the scanner should pass status='active' and missing_since=None to
-            reactivate a previously-missing project; default values handle this
-            when the caller omits both fields.
+            ``project_identity``. A key ABSENT from `fields` is coalesce-or-
+            omit: the column keeps its current value instead of being forced
+            to NULL (see the ownership map above `_PROJECTS_AGENT_OWNED`). A
+            key present with value None (e.g. ``missing_since=None``) is an
+            explicit write -- this is how the scanner reactivates a
+            previously-missing project (pass status='active' and
+            missing_since=None together). When ``project_identity`` is
+            non-null and the live schema carries the column (v18+), the
+            UPSERT collapses on that stable identity: the SAME physical repo
+            scanned from different workspaces/roots updates the existing row
+            IN PLACE (preserving its original (workspace, name) PK) instead
+            of inserting a duplicate. ``status`` defaults to 'active' when
+            not provided (or explicitly None).
         agent: Agent name. Must have allow_write=1 for table 'projects' in
             agent_permissions.
-        topic_key: Optional dimension key.
+        topic_key: Optional dimension key. Coalesced: an explicit value
+            overwrites; omitting it (None) preserves the existing value
+            instead of nulling it on every rescan.
         db_path: Optional explicit DB path (used by tests).
         workspace_path: Directory whose git remote supplies the workspaces.identity
             value. Pass ``project_path`` from the scanner for correct
             multi-workspace ingestion.
+        strip_agent_owned: When True (the scan path -- bulk_upsert's
+            projects branch, populate_project), any key in
+            ``_PROJECTS_AGENT_OWNED`` is dropped from `fields` before the
+            coalesce-or-omit step, regardless of what the caller supplied.
+            Direct callers (tests, future agent-driven writes) leave this
+            False and keep full write access.
 
     Returns:
-        {"status": "applied"} on success.
+        {"status": "applied", "name": <final name used, disambiguated if a
+        genuine repo-name collision was detected -- see
+        :func:`_find_collision_free_name`>} on success.
         {"status": "rejected", "reason": "not_authorized"} if the agent lacks
         write permission for the 'projects' table.
     """
@@ -416,13 +620,19 @@ def upsert_project(
         con.execute("BEGIN")
         try:
             _ensure_workspace_row(con, workspace, workspace_path)
-            data = {k: fields.get(k) for k in _PROJECT_FIELDS}
-            # Default status to 'active' when not explicitly provided.
-            # This ensures newly-inserted rows and re-upserted live projects
-            # always carry an explicit status value.
-            status_val = data["status"] if data["status"] is not None else "active"
+
+            present = _present_fields(
+                fields, _PROJECT_FIELDS,
+                strip=_PROJECTS_AGENT_OWNED if strip_agent_owned else frozenset(),
+            )
+            # Default status to 'active' when not explicitly provided (or
+            # explicitly None). Newly-inserted rows and re-upserted live
+            # projects always carry an explicit status value -- unchanged
+            # historical default.
+            if present.get("status") is None:
+                present["status"] = "active"
             now = _now_iso()
-            project_identity = data["project_identity"]
+            project_identity = present.get("project_identity")
 
             # Identity-collapse path (M1-T2): when a stable project_identity is
             # supplied AND the live schema carries the column, the SAME physical
@@ -432,102 +642,74 @@ def upsert_project(
             # one) and UPDATE it IN PLACE, preserving its original (workspace,
             # name) PK -- the first-seen vantage wins, later scans only refresh
             # the row's scanner-owned columns. This is what makes the
-            # "same repo from two roots -> 0 duplicates" query hold.
+            # "same repo from two roots -> 0 duplicates" query hold. Only the
+            # columns actually PRESENT in `fields` are updated (coalesce-or-
+            # omit); scanner-owned columns this call didn't mention keep their
+            # current value instead of being nulled.
             if has_identity_col and project_identity:
                 existing = con.execute(
                     "SELECT workspace, name FROM projects WHERE project_identity = ?",
                     (project_identity,),
                 ).fetchone()
                 if existing is not None:
+                    set_parts = [f"{c} = ?" for c in present.keys()]
+                    set_parts += ["scanner_ts = ?", "topic_key = COALESCE(?, topic_key)"]
+                    params = list(present.values()) + [now, topic_key]
                     con.execute(
-                        """
-                        UPDATE projects SET
-                            role = ?,
-                            remote_url = ?,
-                            platform = ?,
-                            primary_language = ?,
-                            scanner_ts = ?,
-                            topic_key = ?,
-                            group_name = ?,
-                            path = ?,
-                            status = ?,
-                            missing_since = ?,
-                            project_identity = ?
-                        WHERE workspace = ? AND name = ?
-                        """,
-                        (
-                            data["role"], data["remote_url"], data["platform"],
-                            data["primary_language"], now, topic_key,
-                            data["group_name"], data["path"],
-                            status_val, data["missing_since"], project_identity,
-                            existing["workspace"], existing["name"],
-                        ),
+                        f"UPDATE projects SET {', '.join(set_parts)} "
+                        f"WHERE workspace = ? AND name = ?",
+                        (*params, existing["workspace"], existing["name"]),
                     )
                     con.commit()
-                    return _applied()
+                    return _applied({"name": existing["name"]})
+
+            # No identity match -- this is a NEW row (or a legacy DB with no
+            # identity column). Resolve a collision-free name so a DIFFERENT
+            # physical repo sharing this basename never silently overwrites
+            # an existing, unrelated row (AC-2).
+            final_name = name
+            if has_identity_col and project_identity:
+                final_name = _find_collision_free_name(con, workspace, name, project_identity)
 
             if has_identity_col:
+                insert_cols = ["workspace", "name"] + list(present.keys()) + ["scanner_ts", "topic_key"]
+                insert_vals = [workspace, final_name] + list(present.values()) + [now, topic_key]
+                update_clause_parts = [f"{c} = excluded.{c}" for c in present.keys()]
+                update_clause_parts += [
+                    "scanner_ts = excluded.scanner_ts",
+                    "topic_key = COALESCE(excluded.topic_key, topic_key)",
+                ]
                 con.execute(
-                    """
-                    INSERT INTO projects (workspace, name, role, remote_url, platform,
-                                          primary_language, scanner_ts, topic_key,
-                                          group_name, path, status, missing_since,
-                                          project_identity)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    ON CONFLICT(workspace, name) DO UPDATE SET
-                        role = excluded.role,
-                        remote_url = excluded.remote_url,
-                        platform = excluded.platform,
-                        primary_language = excluded.primary_language,
-                        scanner_ts = excluded.scanner_ts,
-                        topic_key = excluded.topic_key,
-                        group_name = excluded.group_name,
-                        path = excluded.path,
-                        status = excluded.status,
-                        missing_since = excluded.missing_since,
-                        project_identity = excluded.project_identity
-                    """,
-                    (
-                        workspace, name,
-                        data["role"], data["remote_url"], data["platform"],
-                        data["primary_language"], now, topic_key,
-                        data["group_name"], data["path"],
-                        status_val, data["missing_since"], project_identity,
-                    ),
+                    f"INSERT INTO projects ({', '.join(insert_cols)}) "
+                    f"VALUES ({', '.join(['?'] * len(insert_cols))}) "
+                    f"ON CONFLICT(workspace, name) DO UPDATE SET {', '.join(update_clause_parts)}",
+                    insert_vals,
                 )
             else:
                 # Backward-compat: un-migrated DB without project_identity.
+                # No collision-free naming is possible without an identity
+                # signal -- degrades to the historical (workspace, name) key.
+                # Drop `project_identity` from `present`: the legacy schema
+                # does not carry that column at all.
+                legacy_present = {k: v for k, v in present.items() if k != "project_identity"}
+                insert_cols = ["workspace", "name"] + list(legacy_present.keys()) + ["scanner_ts", "topic_key"]
+                insert_vals = [workspace, final_name] + list(legacy_present.values()) + [now, topic_key]
+                update_clause_parts = [f"{c} = excluded.{c}" for c in legacy_present.keys()]
+                update_clause_parts += [
+                    "scanner_ts = excluded.scanner_ts",
+                    "topic_key = COALESCE(excluded.topic_key, topic_key)",
+                ]
                 con.execute(
-                    """
-                    INSERT INTO projects (workspace, name, role, remote_url, platform,
-                                          primary_language, scanner_ts, topic_key,
-                                          group_name, path, status, missing_since)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    ON CONFLICT(workspace, name) DO UPDATE SET
-                        role = excluded.role,
-                        remote_url = excluded.remote_url,
-                        platform = excluded.platform,
-                        primary_language = excluded.primary_language,
-                        scanner_ts = excluded.scanner_ts,
-                        topic_key = excluded.topic_key,
-                        group_name = excluded.group_name,
-                        path = excluded.path,
-                        status = excluded.status,
-                        missing_since = excluded.missing_since
-                    """,
-                    (
-                        workspace, name,
-                        data["role"], data["remote_url"], data["platform"],
-                        data["primary_language"], now, topic_key,
-                        data["group_name"], data["path"],
-                        status_val, data["missing_since"],
-                    ),
+                    f"INSERT INTO projects ({', '.join(insert_cols)}) "
+                    f"VALUES ({', '.join(['?'] * len(insert_cols))}) "
+                    f"ON CONFLICT(workspace, name) DO UPDATE SET {', '.join(update_clause_parts)}",
+                    insert_vals,
                 )
             con.commit()
         except Exception:
             con.rollback()
             raise
-        return _applied()
+        return _applied({"name": final_name})
     finally:
         con.close()
 
@@ -548,6 +730,7 @@ def upsert_app(
     topic_key: str | None = None,
     *,
     db_path: Path | None = None,
+    strip_agent_owned: bool = False,
 ) -> dict:
     """Upsert an apps row, enforcing per-agent write permission.
 
@@ -557,9 +740,19 @@ def upsert_app(
                  ``projects`` table).
         name: App name.
         fields: Dict with optional keys ``kind``, ``description``, ``status``.
+            A key ABSENT from `fields` is coalesce-or-omit: the column keeps
+            its current value instead of being forced to NULL. A key present
+            (even with value None) is an explicit write.
         agent: Agent name. Requires allow_write=1 for table 'apps'.
-        topic_key: Optional dimension key.
+        topic_key: Optional dimension key. Coalesced: an explicit value
+            overwrites; omitting it (None) preserves the existing value.
         db_path: Optional explicit DB path (used by tests).
+        strip_agent_owned: When True (the scan path -- bulk_upsert's apps
+            branch), ``description`` and ``status`` (``_APPS_AGENT_OWNED``)
+            are dropped from `fields` before the coalesce-or-omit step,
+            regardless of what the caller supplied. Direct callers (tests,
+            future agent-driven writes) leave this False and keep full
+            write access.
 
     Returns:
         {"status": "applied"} on success.
@@ -582,24 +775,23 @@ def upsert_app(
                     "INSERT INTO projects (workspace, name, scanner_ts) VALUES (?, ?, ?)",
                     (workspace, project, _now_iso()),
                 )
-            data = {k: fields.get(k) for k in _APP_FIELDS}
+            present = _present_fields(
+                fields, _APP_FIELDS,
+                strip=_APPS_AGENT_OWNED if strip_agent_owned else frozenset(),
+            )
+            now = _now_iso()
+            insert_cols = ["workspace", "project", "name"] + list(present.keys()) + ["topic_key", "scanner_ts"]
+            insert_vals = [workspace, project, name] + list(present.values()) + [topic_key, now]
+            update_clause_parts = [f"{c} = excluded.{c}" for c in present.keys()]
+            update_clause_parts += [
+                "topic_key = COALESCE(excluded.topic_key, topic_key)",
+                "scanner_ts = excluded.scanner_ts",
+            ]
             con.execute(
-                """
-                INSERT INTO apps (workspace, project, name, kind, description, status,
-                                  topic_key, scanner_ts)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-                ON CONFLICT(workspace, project, name) DO UPDATE SET
-                    kind = excluded.kind,
-                    description = excluded.description,
-                    status = excluded.status,
-                    topic_key = excluded.topic_key,
-                    scanner_ts = excluded.scanner_ts
-                """,
-                (
-                    workspace, project, name,
-                    data["kind"], data["description"], data["status"],
-                    topic_key, _now_iso(),
-                ),
+                f"INSERT INTO apps ({', '.join(insert_cols)}) "
+                f"VALUES ({', '.join(['?'] * len(insert_cols))}) "
+                f"ON CONFLICT(workspace, project, name) DO UPDATE SET {', '.join(update_clause_parts)}",
+                insert_vals,
             )
             con.commit()
         except Exception:
@@ -653,6 +845,7 @@ def delete_missing_in(
                 "libraries": ("project", "name"),
                 "services": ("project", "name"),
                 "features": ("project", "name"),
+                "project_facets": ("project", "scope", "key"),
                 "tf_modules": ("project", "name"),
                 "tf_live": ("project", "name"),
                 "releases": ("project", "name"),
@@ -799,6 +992,10 @@ def bulk_upsert(
     applied = 0
     rejected = 0
     if table == "projects":
+        # bulk_upsert is exclusively the scan path's batch writer (see the
+        # module docstring: "populators NEVER touch agent-owned columns") --
+        # strip_agent_owned=True enforces that structurally, regardless of
+        # what a row dict happens to include.
         for r in rows_list:
             res = upsert_project(
                 workspace,
@@ -807,6 +1004,7 @@ def bulk_upsert(
                 agent,
                 topic_key=r.get("topic_key"),
                 db_path=db_path,
+                strip_agent_owned=True,
             )
             if res.get("status") == "applied":
                 applied += 1
@@ -824,6 +1022,7 @@ def bulk_upsert(
                 agent,
                 topic_key=r.get("topic_key"),
                 db_path=db_path,
+                strip_agent_owned=True,
             )
             if res.get("status") == "applied":
                 applied += 1
@@ -840,6 +1039,7 @@ def bulk_upsert(
         "libraries": ("project", "name"),
         "services": ("project", "name"),
         "features": ("project", "name"),
+        "project_facets": ("project", "scope", "key"),
         "tf_modules": ("project", "name"),
         "tf_live": ("project", "name"),
         "releases": ("project", "name"),
@@ -1134,6 +1334,74 @@ def _validate_curated_slug(name: str, type: str) -> None:
             )
 
 
+def resolve_project_ref(
+    workspace: str,
+    project_name: str,
+    *,
+    db_path: Path | None = None,
+) -> str:
+    """Resolve a ``projects.name`` within ``workspace`` to its stable
+    ``project_identity`` anchor -- the value ``upsert_memory(project_ref=...)``
+    expects (N3 forward-only anchoring).
+
+    Looks up the exact ``(workspace, project_name)`` row -- the same lookup
+    documented as the manual convention in ``skills/memory/SKILL.md`` before
+    this function existed (``SELECT project_identity FROM projects WHERE
+    workspace=? AND name=?``). Never guesses: raises ``ValueError`` with an
+    actionable message when the project does not exist, when more than one
+    row matches (structurally guarded against by the ``(workspace, name)``
+    primary key, but checked defensively), or when the matching row has not
+    yet been assigned a ``project_identity`` (e.g. a legacy pre-v18 row, or a
+    project scanned before the identity column was populated) -- anchoring to
+    an absent identity would be a guess, not a resolution.
+
+    Args:
+        workspace: Workspace name (matches ``projects.workspace``).
+        project_name: Project basename (matches ``projects.name``).
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        The resolved ``project_identity`` string.
+
+    Raises:
+        ValueError: project not found, ambiguous, or has no project_identity.
+    """
+    con = _connect(db_path)
+    try:
+        rows = con.execute(
+            "SELECT project_identity FROM projects WHERE workspace = ? AND name = ?",
+            (workspace, project_name),
+        ).fetchall()
+    finally:
+        con.close()
+
+    if not rows:
+        raise ValueError(
+            f"project {project_name!r} not found in workspace {workspace!r}; "
+            f"cannot anchor memory to it. Check the name with "
+            f"`gaia context query \"SELECT name FROM projects WHERE "
+            f"workspace='{workspace}'\"`."
+        )
+    if len(rows) > 1:
+        # Structurally unreachable today ((workspace, name) is the projects
+        # PK), kept as a defensive guard against a future schema change that
+        # relaxes that constraint -- "never guess" applies here too.
+        raise ValueError(
+            f"project {project_name!r} is ambiguous in workspace {workspace!r} "
+            f"({len(rows)} matching rows); cannot anchor memory to a single "
+            f"identity without guessing."
+        )
+    identity = rows[0]["project_identity"]
+    if not identity:
+        raise ValueError(
+            f"project {project_name!r} in workspace {workspace!r} has no "
+            f"project_identity yet (legacy row, or not yet scanned); "
+            f"cannot anchor memory to it without guessing. Run `gaia scan` "
+            f"first."
+        )
+    return identity
+
+
 def upsert_memory(
     workspace: str,
     name: str,
@@ -1142,10 +1410,46 @@ def upsert_memory(
     body: str,
     description: str | None = None,
     origin_session_id: str | None = None,
+    project_ref: str | None = None,
     db_path: Path | None = None,
     workspace_path: Path | None = None,
 ) -> dict:
     """Upsert a curated-memory row in the ``memory`` table.
+
+    Archive-on-upsert (scan-v2 SV3): when this overwrites an existing row, the
+    ``memory_au``... no -- the ``trg_memory_history`` AFTER UPDATE trigger fires
+    on the ON CONFLICT DO UPDATE below and archives the PREVIOUS ``body`` (and
+    workspace/type/description/status/deleted_at) into ``memory_history`` before
+    the new value lands. The prior version is never lost; no explicit archival
+    code is needed here because the guarantee is enforced at the SQL layer for
+    every write path, not just this one.
+
+    Resurrection: re-adding a slug that was soft-deleted clears ``deleted_at``
+    (the row returns to the live set). The clearing is captured by the same
+    history trigger.
+
+    ``project_ref`` -- forward-only remote-stable project anchor (N3, scan-v2
+    SV3 follow-up). The v25/v26 columns/migration exist, but the automatic
+    backfill in ``scripts/migrations/v25_to_v26.sql`` (guarded on "workspace
+    hosts exactly one active project") is a one-time, already-applied
+    historical statement that populated 0 rows in practice -- the
+    memory-row-to-project mapping is ambiguous whenever a workspace hosts more
+    than one project, and NEVER guessed. There is no live code that re-runs or
+    depends on that guard; going forward, ``project_ref`` is anchored
+    explicitly, at write time, by whoever calls this function knowing which
+    project a ``project``-type row is about (see ``gaia memory add --project``
+    in ``bin/cli/memory.py``, which resolves a project name to its
+    ``projects.project_identity`` via :func:`resolve_project_ref` before
+    calling here).
+
+    Coalesce-or-omit (same discipline as ``topic_key`` elsewhere in this
+    module): ``project_ref=None`` (the default) never touches an existing
+    anchor -- an update that does not mention the project leaves a
+    previously-set anchor intact instead of clobbering it back to NULL. Pass
+    an explicit identity string to set or overwrite it. There is no "clear"
+    sentinel; once anchored, forward-only re-anchoring is the only write path
+    (matches the existing ``topic_key`` COALESCE convention -- no precedent in
+    this module for an explicit-NULL clear on a coalesced column).
     """
     _assert_dispatch_can_write_memory()
 
@@ -1178,17 +1482,19 @@ def upsert_memory(
             con.execute(
                 """
                 INSERT INTO memory (workspace, name, type, description, body,
-                                    origin_session_id, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?)
+                                    project_ref, origin_session_id, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT(workspace, name) DO UPDATE SET
                     type              = excluded.type,
                     description       = excluded.description,
                     body              = excluded.body,
+                    project_ref       = COALESCE(excluded.project_ref, project_ref),
                     origin_session_id = excluded.origin_session_id,
-                    updated_at        = excluded.updated_at
+                    updated_at        = excluded.updated_at,
+                    deleted_at        = NULL
                 """,
                 (workspace, name, type, description, body,
-                 origin_session_id, now),
+                 project_ref, origin_session_id, now),
             )
             con.commit()
             return {
@@ -1215,15 +1521,49 @@ def delete_memory(
     workspace: str,
     name: str,
     *,
+    hard: bool = False,
     db_path: Path | None = None,
 ) -> bool:
-    """Hard-delete a curated memory row."""
+    """Soft-delete (tombstone) a curated memory row -- scan-v2 SV3.
+
+    By default this is a SOFT delete: the row's ``deleted_at`` column is stamped
+    with the current UTC timestamp instead of the row being physically removed.
+    The row and its ``body`` survive (recoverable, and re-addable via
+    :func:`upsert_memory`, which clears the tombstone). The ``trg_memory_history``
+    trigger records the tombstone transition (before_deleted_at NULL -> after
+    non-NULL). All read paths filter ``deleted_at IS NULL`` so a tombstoned row
+    is invisible to normal queries.
+
+    A tombstone is idempotent: calling delete_memory on an already-tombstoned
+    row is a no-op (the row is not re-stamped and no new history row is written).
+
+    ``hard=True`` performs the real physical DELETE. This is the ONLY path that
+    destroys the row and its body, and it exists exclusively for explicit human
+    curation ("never hard-delete curated memory except by explicit human
+    curation" -- decision_scan_v2_memory_loss_vectors). The CLI surfaces it via
+    ``gaia memory delete --hard`` behind the existing confirmation prompt.
+
+    Returns True when a row was affected (tombstoned or hard-deleted), False
+    when no live row matched (already tombstoned, or absent).
+    """
     _assert_dispatch_can_write_memory()
     con = _connect(db_path)
     try:
+        if hard:
+            cur = con.execute(
+                "DELETE FROM memory WHERE workspace = ? AND name = ?",
+                (workspace, name),
+            )
+            con.commit()
+            return cur.rowcount > 0
+        # Soft delete: stamp deleted_at only on a currently-live row. The
+        # `deleted_at IS NULL` guard makes a repeated tombstone a no-op (no
+        # spurious history row, no timestamp churn).
+        now = _now_iso()
         cur = con.execute(
-            "DELETE FROM memory WHERE workspace = ? AND name = ?",
-            (workspace, name),
+            "UPDATE memory SET deleted_at = ?, updated_at = ? "
+            "WHERE workspace = ? AND name = ? AND deleted_at IS NULL",
+            (now, now, workspace, name),
         )
         con.commit()
         return cur.rowcount > 0
@@ -1708,6 +2048,7 @@ def search_memory_curated(
             JOIN memory m ON m.rowid = memory_fts.rowid
             WHERE memory_fts MATCH ?
               AND m.workspace = ?
+              AND m.deleted_at IS NULL
             ORDER BY rank
             LIMIT ?
             """,
@@ -1735,17 +2076,26 @@ def get_memory(
     workspace: str,
     name: str,
     *,
+    include_deleted: bool = False,
     db_path: Path | None = None,
 ) -> dict | None:
-    """Return a curated memory row as a dict, or ``None`` when missing."""
+    """Return a curated memory row as a dict, or ``None`` when missing.
+
+    Tombstoned rows (``deleted_at`` non-NULL, scan-v2 SV3) are excluded by
+    default so a soft-deleted memory reads as absent. Pass
+    ``include_deleted=True`` to reach a tombstoned row (e.g. for an explicit
+    hard-delete or a recovery inspection).
+    """
     con = _connect(db_path)
     try:
-        row = con.execute(
-            "SELECT workspace, name, type, description, body, "
-            "       origin_session_id, updated_at "
-            "FROM memory WHERE workspace = ? AND name = ?",
-            (workspace, name),
-        ).fetchone()
+        sql = (
+            "SELECT workspace, name, type, description, body, project_ref, "
+            "       origin_session_id, updated_at, deleted_at "
+            "FROM memory WHERE workspace = ? AND name = ?"
+        )
+        if not include_deleted:
+            sql += " AND deleted_at IS NULL"
+        row = con.execute(sql, (workspace, name)).fetchone()
         if row is None:
             return None
         return {k: row[k] for k in row.keys()}
@@ -1757,23 +2107,28 @@ def list_memory(
     workspace: str,
     *,
     type: str | None = None,
+    include_deleted: bool = False,
     db_path: Path | None = None,
 ) -> list[dict]:
-    """List curated memory rows, optionally filtered by ``type``."""
+    """List curated memory rows, optionally filtered by ``type``.
+
+    Tombstoned rows (``deleted_at`` non-NULL, scan-v2 SV3) are excluded by
+    default; pass ``include_deleted=True`` to include them.
+    """
     con = _connect(db_path)
     try:
-        if type is None:
-            rows = con.execute(
-                "SELECT name, type, description, updated_at "
-                "FROM memory WHERE workspace = ? ORDER BY name",
-                (workspace,),
-            ).fetchall()
-        else:
-            rows = con.execute(
-                "SELECT name, type, description, updated_at "
-                "FROM memory WHERE workspace = ? AND type = ? ORDER BY name",
-                (workspace, type),
-            ).fetchall()
+        where = ["workspace = ?"]
+        params: list = [workspace]
+        if type is not None:
+            where.append("type = ?")
+            params.append(type)
+        if not include_deleted:
+            where.append("deleted_at IS NULL")
+        sql = (
+            "SELECT name, type, description, updated_at "
+            "FROM memory WHERE " + " AND ".join(where) + " ORDER BY name"
+        )
+        rows = con.execute(sql, params).fetchall()
         return [dict(r) for r in rows]
     finally:
         con.close()
@@ -2620,15 +2975,629 @@ def reorder_tasks(
 # Public API: wipe_workspace
 # ---------------------------------------------------------------------------
 
-def wipe_workspace(workspace: str, *, db_path: Path | None = None) -> None:
+def _reinsert_row(con: sqlite3.Connection, table: str, row: sqlite3.Row) -> None:
+    """Re-INSERT a captured ``sqlite3.Row`` back into ``table`` verbatim.
+
+    Column list is derived from the row's own keys, so the helper survives
+    schema evolution without hard-coding column names. Used by
+    :func:`wipe_workspace` to restore memory / memory_links / the workspaces row
+    after a CASCADE wipe.
+    """
+    cols = list(row.keys())
+    placeholders = ", ".join("?" for _ in cols)
+    col_list = ", ".join(cols)
+    con.execute(
+        f"INSERT INTO {table} ({col_list}) VALUES ({placeholders})",
+        tuple(row[c] for c in cols),
+    )
+
+
+def wipe_workspace(
+    workspace: str,
+    *,
+    preserve_memory: bool = True,
+    db_path: Path | None = None,
+) -> None:
     """Delete the workspaces row for `workspace`. FK CASCADE removes all
     child rows (projects, apps, integrations, etc.) automatically.
+
+    Memory preservation (scan-v2 SV3, Vector 4)
+    -------------------------------------------
+    ``memory`` and ``memory_links`` are FK'd to ``workspaces`` with ON DELETE
+    CASCADE, so a naive workspace delete DESTROYS all curated memory for the
+    workspace. That is the loss vector `migrate_workspace.py` triggered on every
+    re-scan. This function now DECOUPLES memory from the CASCADE at the app
+    layer -- the safer of the two options (the alternative, changing the FK to
+    ON DELETE SET NULL / RESTRICT, would require a full ``memory`` table rebuild
+    per the v21->v22 precedent).
+
+    With ``preserve_memory=True`` (the DEFAULT): inside a single transaction the
+    memory rows, memory_links rows, and the workspaces row itself are captured
+    BEFORE the delete; the CASCADE then fires as normal; and the workspaces row
+    (with its identity / created_at / status preserved) plus every memory /
+    memory_links row is re-inserted. Net effect: projects and all scannable
+    children are cleared (what a re-scan wants), while curated memory survives
+    untouched. The memory_ai / memory_links insert triggers keep the FTS mirror
+    consistent.
+
+    ``preserve_memory=False`` performs the original full CASCADE (memory
+    destroyed). This exists ONLY for explicit human curation -- e.g.
+    ``gaia context wipe --purge-memory`` behind its confirmation prompt --
+    honouring "never hard-delete curated memory except by explicit human
+    curation".
+    """
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            if preserve_memory:
+                ws_row = con.execute(
+                    "SELECT * FROM workspaces WHERE name = ?", (workspace,)
+                ).fetchone()
+                mem_rows = con.execute(
+                    "SELECT * FROM memory WHERE workspace = ?", (workspace,)
+                ).fetchall()
+                link_rows = con.execute(
+                    "SELECT * FROM memory_links WHERE workspace = ?", (workspace,)
+                ).fetchall()
+
+                con.execute("DELETE FROM workspaces WHERE name = ?", (workspace,))
+
+                # Restore the workspaces row (only when it existed) so the FK
+                # target for the re-inserted memory is present again, then the
+                # memory + links. If the workspace had no row, there was nothing
+                # to preserve and the delete was a no-op.
+                if ws_row is not None:
+                    _reinsert_row(con, "workspaces", ws_row)
+                    for r in mem_rows:
+                        _reinsert_row(con, "memory", r)
+                    for r in link_rows:
+                        _reinsert_row(con, "memory_links", r)
+            else:
+                con.execute("DELETE FROM workspaces WHERE name = ?", (workspace,))
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+    finally:
+        con.close()
+
+
+# ---------------------------------------------------------------------------
+# Surgical reconciliation helpers (workspace-identity brief, M4/T10)
+# ---------------------------------------------------------------------------
+#
+# `gaia scan` reconciles the `projects` table workspace-by-workspace: it
+# upserts the repos it finds under the SCANNED workspace and prunes
+# (mark_missing_in / delete_missing_in) only WITHIN that same workspace. Two
+# consequences make a plain rescan unable to repair historical drift:
+#
+#   1. A stale row with project_identity=NULL living under a DIFFERENT
+#      workspace than the one being scanned is never collapsed (the identity-
+#      collapse path in upsert_project only fires for a non-null identity) and
+#      never pruned (prune is scoped to the scanned workspace) -- so a rescan
+#      RESURRECTS the repo as a fresh duplicate row and leaves the stale row
+#      ORPHANED under its old workspace.
+#   2. project_context_contracts is not touched by scan at all, so a contract
+#      written under the wrong workspace can only be corrected by moving it.
+#
+# wipe_workspace is too blunt for a LIVE workspace: it CASCADE-deletes the
+# workspaces row and EVERY child (projects, memory, briefs, episodes, PCC).
+# The helper below is the surgical, workspace-preserving primitive that
+# repairs drift without destroying collateral:
+#
+#   relocate_contracts -- re-key project_context_contracts rows between
+#                         workspaces (the only correction path for mis-keyed PCC).
+#
+# NOTE: a `delete_projects` sibling (targeted deletion of `projects` rows)
+# existed here as a one-time reconciliation tool (workspace-identity brief
+# M4/T10) and was removed in scan-v2 SV4 -- agents must never hold the power
+# to hard-delete project rows; `mark_missing_in` (soft-delete, scanner-owned)
+# and the resolve-move adjudication (re-key + tombstone, see
+# `resolve_move_candidate` below) are the only sanctioned paths that touch a
+# project row's lifecycle.
+# ---------------------------------------------------------------------------
+
+
+def relocate_contracts(
+    from_workspace: str,
+    to_workspace: str,
+    contracts: Sequence[str],
+    *,
+    on_conflict: str = "error",
+    dry_run: bool = False,
+    db_path: Path | None = None,
+) -> dict:
+    """Re-key ``project_context_contracts`` rows from one workspace to another.
+
+    `gaia scan` never touches project_context_contracts, so a contract written
+    under the wrong workspace (e.g. AOS project context mis-keyed to the 'me'
+    workspace) can only be corrected by moving the row. This re-keys the named
+    contracts by UPDATEing the ``workspace`` PK column IN PLACE -- payload,
+    metadata and updated_at are preserved, and the ``trg_pcc_history`` AFTER
+    UPDATE trigger records the move in project_context_contracts_history.
+
+    ``to_workspace`` must satisfy the FK to workspaces(name); it is created via
+    :func:`_ensure_workspace_row` when absent. The PK is
+    (workspace, contract_name), so if (to_workspace, contract) ALREADY exists
+    ``on_conflict`` decides:
+
+        'error'     -- raise ValueError, move nothing (default; never clobber)
+        'skip'      -- leave both rows; report the contract under 'skipped'
+        'overwrite' -- delete the target row first, then move the source row
+
+    Idempotent: a contract already absent from ``from_workspace`` is reported
+    under 'missing' and is a no-op, so re-running after a partial apply is safe.
+
+    Args:
+        from_workspace: Source workspace (current, wrong key).
+        to_workspace: Destination workspace (correct key).
+        contracts: Contract names to move (project_context_contracts.contract_name).
+        on_conflict: 'error' | 'skip' | 'overwrite' (see above).
+        dry_run: When True, mutate nothing; report the classification only.
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        {"status": "applied"|"preview", "from": ..., "to": ...,
+         "moved": [...], "skipped": [...], "missing": [...], "overwritten": [...]}.
+
+    Raises:
+        ValueError: on invalid on_conflict, empty contracts, from==to, or an
+            unresolved PK conflict when on_conflict='error'.
+    """
+    if on_conflict not in ("error", "skip", "overwrite"):
+        raise ValueError(
+            f"relocate_contracts: invalid on_conflict {on_conflict!r}; "
+            f"must be 'error', 'skip', or 'overwrite'"
+        )
+    contract_list = list(contracts)
+    if not contract_list:
+        raise ValueError("relocate_contracts: at least one contract is required")
+    if from_workspace == to_workspace:
+        raise ValueError(
+            "relocate_contracts: from_workspace and to_workspace are identical"
+        )
+
+    moved: list[str] = []
+    skipped: list[str] = []
+    missing: list[str] = []
+    overwritten: list[str] = []
+
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            if not dry_run:
+                _ensure_workspace_row(con, to_workspace)
+
+            for name in contract_list:
+                src = con.execute(
+                    "SELECT 1 FROM project_context_contracts "
+                    "WHERE workspace = ? AND contract_name = ?",
+                    (from_workspace, name),
+                ).fetchone()
+                if src is None:
+                    missing.append(name)
+                    continue
+
+                dst = con.execute(
+                    "SELECT 1 FROM project_context_contracts "
+                    "WHERE workspace = ? AND contract_name = ?",
+                    (to_workspace, name),
+                ).fetchone()
+                if dst is not None:
+                    if on_conflict == "error":
+                        raise ValueError(
+                            f"relocate_contracts: target already has contract "
+                            f"{name!r} under workspace {to_workspace!r} "
+                            f"(on_conflict='error')"
+                        )
+                    if on_conflict == "skip":
+                        skipped.append(name)
+                        continue
+                    # overwrite
+                    if not dry_run:
+                        con.execute(
+                            "DELETE FROM project_context_contracts "
+                            "WHERE workspace = ? AND contract_name = ?",
+                            (to_workspace, name),
+                        )
+                    overwritten.append(name)
+
+                if not dry_run:
+                    con.execute(
+                        "UPDATE project_context_contracts SET workspace = ? "
+                        "WHERE workspace = ? AND contract_name = ?",
+                        (to_workspace, from_workspace, name),
+                    )
+                moved.append(name)
+
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+    finally:
+        con.close()
+
+    return {
+        "status": "preview" if dry_run else "applied",
+        "from": from_workspace,
+        "to": to_workspace,
+        "moved": moved,
+        "skipped": skipped,
+        "missing": missing,
+        "overwritten": overwritten,
+    }
+
+
+def relocate_memory(
+    from_workspace: str,
+    to_workspace: str,
+    names: Sequence[str],
+    *,
+    on_conflict: str = "error",
+    dry_run: bool = False,
+    db_path: Path | None = None,
+) -> dict:
+    """Re-key curated ``memory`` rows (and their intra-set ``memory_links``)
+    between workspaces -- the mirror of :func:`relocate_contracts` for the
+    curated memory table.
+
+    `gaia scan` never touches ``memory``, so a memory row written under the
+    wrong workspace (e.g. the 'project_gaia_roadmap' / 'user_blog_articles'
+    notes mis-keyed to the 'rnd' workspace but belonging to 'me') can only be
+    corrected by moving the row. This re-keys the named rows by UPDATEing the
+    ``workspace`` PK column IN PLACE: every other column (type, description,
+    body, origin_session_id, updated_at, class, status) is preserved untouched,
+    and the ``memory_au`` AFTER UPDATE trigger keeps the ``memory_fts`` mirror
+    in sync (workspace is an FTS column, so the mirror row is rewritten).
+
+    memory_links follow the notes: a link under ``from_workspace`` whose BOTH
+    endpoints are in the moved set is re-keyed to ``to_workspace`` (the edge
+    travels with the pair). A link with only ONE endpoint in the moved set
+    cannot stay consistent under the single-workspace link model -- scan-v2 SV3
+    DELETES that now-dangling edge (its endpoint left the workspace) and reports
+    it under 'partial_links'. The link is derived graph metadata, not curated
+    memory: both endpoint rows survive untouched; only the broken edge is
+    removed, so nothing is lost silently and no dangling reference is left
+    behind.
+
+    Provenance (scan-v2 SV3): the workspace re-key UPDATE fires the
+    ``trg_memory_history`` trigger, which records before_workspace ->
+    after_workspace for each moved row -- the origin of every move is preserved
+    in ``memory_history`` automatically, no explicit trace-write needed.
+
+    ``to_workspace`` must satisfy the FK to workspaces(name); it is created via
+    :func:`_ensure_workspace_row` when absent. PK is (workspace, name); on a
+    (to_workspace, name) collision ``on_conflict`` decides:
+
+        'error'     -- raise ValueError, move nothing (default; never clobber)
+        'skip'      -- leave both rows; report the name under 'skipped'
+        'overwrite' -- delete the target row first, then move the source row
+
+    Idempotent: a name already absent from ``from_workspace`` is reported under
+    'missing' and is a no-op, so re-running after a partial apply is safe.
+
+    Subject to the curated-memory write guard
+    (:func:`_assert_dispatch_can_write_memory`): like every other memory
+    mutator, this refuses writes from a NON-curator subagent dispatch. Run it
+    from a human shell or the orchestrator/operator context.
+
+    Returns:
+        {"status": "applied"|"preview", "from": ..., "to": ...,
+         "moved": [...], "skipped": [...], "missing": [...],
+         "overwritten": [...],
+         "links_moved": [{"src","dst","kind"}...],
+         "partial_links": [{"src","dst","kind"}...]}.
+
+    Raises:
+        ValueError: invalid on_conflict, empty names, from==to, or an
+            unresolved PK conflict when on_conflict='error'.
+        MemoryWriteForbidden: when GAIA_DISPATCH_AGENT names a non-curator.
+    """
+    _assert_dispatch_can_write_memory()
+
+    if on_conflict not in ("error", "skip", "overwrite"):
+        raise ValueError(
+            f"relocate_memory: invalid on_conflict {on_conflict!r}; "
+            f"must be 'error', 'skip', or 'overwrite'"
+        )
+    name_list = list(names)
+    if not name_list:
+        raise ValueError("relocate_memory: at least one name is required")
+    if from_workspace == to_workspace:
+        raise ValueError(
+            "relocate_memory: from_workspace and to_workspace are identical"
+        )
+
+    moved: list[str] = []
+    skipped: list[str] = []
+    missing: list[str] = []
+    overwritten: list[str] = []
+    links_moved: list[dict] = []
+    partial_links: list[dict] = []
+
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            if not dry_run:
+                _ensure_workspace_row(con, to_workspace)
+
+            for name in name_list:
+                src = con.execute(
+                    "SELECT 1 FROM memory WHERE workspace = ? AND name = ?",
+                    (from_workspace, name),
+                ).fetchone()
+                if src is None:
+                    missing.append(name)
+                    continue
+
+                dst = con.execute(
+                    "SELECT 1 FROM memory WHERE workspace = ? AND name = ?",
+                    (to_workspace, name),
+                ).fetchone()
+                if dst is not None:
+                    if on_conflict == "error":
+                        raise ValueError(
+                            f"relocate_memory: target already has memory "
+                            f"{name!r} under workspace {to_workspace!r} "
+                            f"(on_conflict='error')"
+                        )
+                    if on_conflict == "skip":
+                        skipped.append(name)
+                        continue
+                    # overwrite: drop the target row first (memory_ad keeps FTS
+                    # in sync); its own links under `to` are left as-is.
+                    if not dry_run:
+                        con.execute(
+                            "DELETE FROM memory WHERE workspace = ? AND name = ?",
+                            (to_workspace, name),
+                        )
+                    overwritten.append(name)
+
+                if not dry_run:
+                    con.execute(
+                        "UPDATE memory SET workspace = ? "
+                        "WHERE workspace = ? AND name = ?",
+                        (to_workspace, from_workspace, name),
+                    )
+                moved.append(name)
+
+            # Re-key links that live entirely within the moved set.
+            moved_set = set(moved)
+            if moved_set:
+                link_rows = con.execute(
+                    "SELECT src_name, dst_name, kind FROM memory_links "
+                    "WHERE workspace = ?",
+                    (from_workspace,),
+                ).fetchall()
+                for lr in link_rows:
+                    src_in = lr["src_name"] in moved_set
+                    dst_in = lr["dst_name"] in moved_set
+                    if not (src_in or dst_in):
+                        continue
+                    entry = {
+                        "src": lr["src_name"],
+                        "dst": lr["dst_name"],
+                        "kind": lr["kind"],
+                    }
+                    if src_in and dst_in:
+                        if not dry_run:
+                            con.execute(
+                                "UPDATE memory_links SET workspace = ? "
+                                "WHERE workspace = ? AND src_name = ? "
+                                "AND dst_name = ? AND kind = ?",
+                                (to_workspace, from_workspace,
+                                 lr["src_name"], lr["dst_name"], lr["kind"]),
+                            )
+                        links_moved.append(entry)
+                    else:
+                        # Only one endpoint moved. Under the single-workspace
+                        # link model this edge is now referentially dangling:
+                        # one of its endpoints no longer exists under
+                        # ``from_workspace`` and cannot be re-homed to
+                        # ``to_workspace`` (the other endpoint stayed). Leaving
+                        # it in place is silent corruption -- scan-v2 SV3 removes
+                        # the dangling edge and reports it under 'partial_links'
+                        # so nothing is lost silently. A link is derived graph
+                        # metadata, not curated memory: both endpoint rows (the
+                        # data) survive untouched; only the broken edge is
+                        # dropped. Never touches memory rows.
+                        if not dry_run:
+                            con.execute(
+                                "DELETE FROM memory_links "
+                                "WHERE workspace = ? AND src_name = ? "
+                                "AND dst_name = ? AND kind = ?",
+                                (from_workspace, lr["src_name"],
+                                 lr["dst_name"], lr["kind"]),
+                            )
+                        partial_links.append(entry)
+
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+    finally:
+        con.close()
+
+    return {
+        "status": "preview" if dry_run else "applied",
+        "from": from_workspace,
+        "to": to_workspace,
+        "moved": moved,
+        "skipped": skipped,
+        "missing": missing,
+        "overwritten": overwritten,
+        "links_moved": links_moved,
+        "partial_links": partial_links,
+    }
+
+
+# ---------------------------------------------------------------------------
+# scan-v2 SV4: move-candidate adjudication (superseded_by write / re-key).
+#
+# `gaia scan` (SV2) only DETECTS and REPORTS a move -- it pairs a project that
+# vanished from one workspace 1:1 (by normalized remote) with a project that
+# appeared in another, and emits a `move_candidate`. It never mutates the
+# lineage. A human then adjudicates each candidate; `resolve_move_candidate`
+# below is the write path that EXECUTES an adjudicated 'movido' decision.
+#
+# Post-scan, a detected move leaves TWO rows in `projects`:
+#   * the OLD row (the `from` side): now status='missing' (soft-deleted by the
+#     reconcile pass), still carrying the pre-move project_identity (its
+#     git-common-dir at the old location) and any agent-owned `description`.
+#   * the NEW row (the `to` side): freshly upserted, status='active', carrying
+#     a DIFFERENT project_identity (the git-common-dir changed when the repo
+#     physically moved). This is the successor.
+#
+# The 'movido' adjudication links the two WITHOUT ever hard-deleting either:
+#   * When the successor row ALREADY exists (the realistic post-scan state, and
+#     the only state a move_candidate is ever emitted from): the old row is
+#     tombstoned (status='missing') and its `superseded_by` column is set to the
+#     successor's project_identity -- the forward link that records "this row's
+#     project moved to the row bearing identity X". Both rows survive; the
+#     successor stays the active canonical at the new (workspace, name). A
+#     merge/re-key of the old row ONTO the successor slot is impossible without
+#     destroying the successor row (a hard delete), which the no-hard-delete
+#     principle forbids -- so the link, not a key rewrite, is the mechanism.
+#   * When the successor row does NOT exist (defensive path, e.g. adjudicating
+#     from a cross-DB or dry-run report where the new location was never
+#     scanned into its own row): the OLD row is RE-KEYED in place -- its
+#     (workspace, name) is updated to the successor location and status flipped
+#     back to 'active'. The row (identity, description, remote) travels intact;
+#     the re-key preserves the data.
+#
+# Agent-authored collateral (curated `memory`, `project_context_contracts`) is
+# NEVER auto-moved here -- it is only PROPOSED. The human relocates it
+# deliberately via `gaia context move-memory` / `move-contracts` once the move
+# is confirmed. This function touches only the `projects` lineage.
+#
+# 'duplicado' / 'worktree' decisions are a structural no-op: both rows are
+# legitimately independent and are left exactly as they are (see the CLI
+# `--decision` handling; this writer is only invoked for 'movido').
+# ---------------------------------------------------------------------------
+
+def resolve_move_candidate(
+    from_workspace: str,
+    from_name: str,
+    to_workspace: str,
+    to_name: str,
+    *,
+    dry_run: bool = False,
+    db_path: Path | None = None,
+) -> dict:
+    """Execute a 'movido' adjudication of a scan-v2 move_candidate.
+
+    Links the OLD (``from``) project row to its successor (``to``) without ever
+    hard-deleting a row. Two branches (see the module comment above):
+
+      * successor row EXISTS  -> tombstone the old row (status='missing') and
+        write ``superseded_by`` = successor.project_identity on it. Both rows
+        survive; the successor stays the active canonical. action='superseded'.
+      * successor row ABSENT  -> re-key the old row in place: update its
+        (workspace, name) to the successor location, flip status back to
+        'active', clear missing_since. The row's data travels intact.
+        action='rekeyed'.
+
+    Curated memory / PCC are NOT moved here -- they are proposed for a separate
+    `move-memory` / `move-contracts` step. This function only touches the
+    `projects` lineage.
+
+    Args:
+        from_workspace: Old row workspace (move_candidate ``from.workspace``).
+        from_name: Old row name (move_candidate ``from.project``).
+        to_workspace: Successor workspace (move_candidate ``to.workspace``).
+        to_name: Successor name (move_candidate ``to.project``).
+        dry_run: When True, mutate nothing; report the branch + successor
+            identity that WOULD be written.
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        {"status": "applied"|"preview", "action": "superseded"|"rekeyed",
+         "from": {"workspace","name"}, "to": {"workspace","name"},
+         "superseded_by": <successor project_identity or None>,
+         "proposed_relocations": {"memory": <n>, "contracts": <n>}}.
+
+    Raises:
+        ValueError: when the old row does not exist, or from == to.
     """
+    if not from_workspace or not from_name:
+        raise ValueError("resolve_move_candidate: from_workspace and from_name are required")
+    if not to_workspace or not to_name:
+        raise ValueError("resolve_move_candidate: to_workspace and to_name are required")
+    if (from_workspace, from_name) == (to_workspace, to_name):
+        raise ValueError(
+            "resolve_move_candidate: from and to are identical -- nothing to resolve"
+        )
+
     con = _connect(db_path)
     try:
         con.execute("BEGIN")
         try:
-            con.execute("DELETE FROM workspaces WHERE name = ?", (workspace,))
+            old = con.execute(
+                "SELECT workspace, name, project_identity, status "
+                "FROM projects WHERE workspace = ? AND name = ?",
+                (from_workspace, from_name),
+            ).fetchone()
+            if old is None:
+                raise ValueError(
+                    f"resolve_move_candidate: old row "
+                    f"({from_workspace!r}, {from_name!r}) not found"
+                )
+
+            successor = con.execute(
+                "SELECT workspace, name, project_identity, status "
+                "FROM projects WHERE workspace = ? AND name = ?",
+                (to_workspace, to_name),
+            ).fetchone()
+
+            # Count agent-authored collateral still keyed to the OLD workspace,
+            # so the caller can PROPOSE (never auto-execute) its relocation.
+            proposed_memory = con.execute(
+                "SELECT COUNT(*) FROM memory WHERE workspace = ? "
+                "AND deleted_at IS NULL",
+                (from_workspace,),
+            ).fetchone()[0]
+            proposed_contracts = con.execute(
+                "SELECT COUNT(*) FROM project_context_contracts WHERE workspace = ?",
+                (from_workspace,),
+            ).fetchone()[0]
+
+            now = _now_iso()
+
+            if successor is not None:
+                # Realistic post-scan state: two rows. Tombstone the old row and
+                # link it forward to the successor identity. Never hard-delete.
+                action = "superseded"
+                superseded_by = successor["project_identity"]
+                if not dry_run:
+                    con.execute(
+                        "UPDATE projects SET status = 'missing', "
+                        "missing_since = COALESCE(missing_since, ?), "
+                        "superseded_by = ? "
+                        "WHERE workspace = ? AND name = ?",
+                        (now, superseded_by, from_workspace, from_name),
+                    )
+                    # Ensure the successor is the active canonical row.
+                    con.execute(
+                        "UPDATE projects SET status = 'active', missing_since = NULL "
+                        "WHERE workspace = ? AND name = ?",
+                        (to_workspace, to_name),
+                    )
+            else:
+                # Successor slot is free: re-key the old row in place. The row's
+                # identity + description + remote travel with it (data preserved).
+                action = "rekeyed"
+                superseded_by = old["project_identity"]
+                if not dry_run:
+                    con.execute(
+                        "UPDATE projects SET workspace = ?, name = ?, "
+                        "status = 'active', missing_since = NULL "
+                        "WHERE workspace = ? AND name = ?",
+                        (to_workspace, to_name, from_workspace, from_name),
+                    )
+
             con.commit()
         except Exception:
             con.rollback()
@@ -2636,6 +3605,18 @@ def wipe_workspace(workspace: str, *, db_path: Path | None = None) -> None:
     finally:
         con.close()
 
+    return {
+        "status": "preview" if dry_run else "applied",
+        "action": action,
+        "from": {"workspace": from_workspace, "name": from_name},
+        "to": {"workspace": to_workspace, "name": to_name},
+        "superseded_by": superseded_by,
+        "proposed_relocations": {
+            "memory": proposed_memory,
+            "contracts": proposed_contracts,
+        },
+    }
+
 
 # ---------------------------------------------------------------------------
 # Public API: approval_grants (DB-backed command_set grant store, M3)
@@ -3009,10 +3990,10 @@ def insert_semantic_grant(
             Retained for audit only -- check_db_semantic_grant() matches
             cross-session (Brief 71), so this is NOT used to scope lookup.
         ttl_minutes: Grant lifetime in minutes. Defaults to
-            APPROVAL_GRANT_TTL_MINUTES (60), aligning the grant lifetime with the
-            1-hour staleness horizon so a human-in-the-loop approval crossing a
-            session boundary does not silently expire before the subagent can
-            consume it. This is the GRANT window, distinct from the 24h pending
+            APPROVAL_GRANT_TTL_MINUTES (5). The grant is consumed AT THE MATCH,
+            so this short window only needs to cover the block -> approve ->
+            retry round trip; a grant never presented to a matching retry simply
+            expires. This is the GRANT window, distinct from the 24h pending
             window (DEFAULT_PENDING_TTL_MINUTES).
         db_path: Optional explicit DB path (used by tests).
 
@@ -3517,9 +4498,9 @@ def consume_db_file_path_grant(
 # ---------------------------------------------------------------------------
 #
 # Foundation scaffolding for the grant-lifecycle FS-to-DB migration (v20).
-# These helpers are called by the upcoming confirm_grant and
-# consume_session_grants migration; callers are NOT wired yet -- only the DB
-# write path is provided here.
+# confirm_db_grant() backs the confirm_grant flow. (The former
+# consume_session_grants SubagentStop sweep was removed in the approvals
+# redesign M1 -- grants are consumed at the match and expire on their short TTL.)
 #
 #   confirm_db_grant()          -- sets confirmed=1 on a PENDING grant row;
 #                                  used when the user explicitly confirms a