kenning-continuity 0.1.0__py3-none-any.whl

kenning_continuity/__init__.py

@@ -0,0 +1,34 @@
+from . import server
+import asyncio
+import argparse
+import logging
+
+from .utils import process_config
+
+logger = logging.getLogger("kenning_continuity")
+logger.setLevel(logging.INFO)
+
+def main():
+    """Main entry point for the package."""
+    parser = argparse.ArgumentParser(description='Temporal Knowledge Substrate MCP Server')
+    parser.add_argument('--db-url', default=None, help='Neo4j connection URL')
+    parser.add_argument('--username', default=None, help='Neo4j username')
+    parser.add_argument('--password', default=None, help='Neo4j password')
+    parser.add_argument("--database", default=None, help="Neo4j database name")
+    parser.add_argument("--namespace", default=None, help="Tool namespace prefix")
+    parser.add_argument("--transport", default=None, help="Transport type (stdio, sse, http)")
+    parser.add_argument("--server-host", default=None, help="HTTP host (default: 127.0.0.1)")
+    parser.add_argument("--server-port", type=int, default=None, help="HTTP port (default: 8000)")
+    parser.add_argument("--server-path", default=None, help="HTTP path (default: /mcp/)")
+    parser.add_argument("--allow-origins", default=None, help="Comma-separated list of allowed CORS origins")
+    parser.add_argument("--allowed-hosts", default=None, help="Comma-separated list of allowed hosts for DNS rebinding protection")
+    parser.add_argument("--read-timeout", type=int, default=None, help="Read query timeout in seconds (default: 30)")
+
+    args = parser.parse_args()
+
+    config = process_config(args)
+    asyncio.run(server.main(**config))
+
+
+# Optionally expose other important items at package level
+__all__ = ["main", "server"]

kenning_continuity/_cypher/_resolve.md

@@ -0,0 +1,16 @@
+The canonical resolution of a knowledge entity by (name, domain).
+
+    MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)
+          -[:DISCOVERED]->(e:Knowledge {name: $name})
+    WHERE NOT (e)<-[:EVOLVED_FROM]-()
+
+`domain` is a query parameter, never a stored property. A knowledge entity is
+downstream of exactly one Domain by construction — every entity is discovered by
+at least one session (`@card(1..)` on `discovered:found`) and every session
+belongs to exactly one domain (`@card(1..1)` on `has-session:held`) — so the
+walk is total and unambiguous. Measured on the production graph: 3,101 of 3,101
+resolve to exactly one domain, none to zero and none to more.
+
+The property it replaces was a denormalization and had already drifted: 21
+entities carried a `domain` string naming a real Domain that had no path to them
+at all. A fact held as text beside a structure rather than by it.

kenning_continuity/_cypher/chain_history.cypher

@@ -0,0 +1,14 @@
+MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(head:Knowledge {name: $name})
+WHERE NOT (head)<-[:EVOLVED_FROM]-()
+WITH DISTINCT head
+MATCH path = (head)-[:EVOLVED_FROM*0..]->(n)
+WITH n, length(path) AS depth
+RETURN n.name AS name,
+       n.ont_type AS type,
+       labels(n) AS labels,
+       $domain AS domain,
+       n.description AS description,
+       n.t_created AS t_created,
+       depth
+ORDER BY n.t_created ASC

kenning_continuity/_cypher/domain_merge.cypher

@@ -0,0 +1,5 @@
+MERGE (d:Domain {name: $name})
+ON CREATE SET d.t_created = datetime(),
+              d.description = $description
+RETURN d.name AS name, d.description AS description,
+       d.t_created AS t_created

kenning_continuity/_cypher/domain_state.cypher

@@ -0,0 +1,38 @@
+// Current knowledge for a domain: head-of-chain entities, with their edges
+// resolved THROUGH the chain.
+//
+// An edge is authored on whichever node was head at the time. Reading edges
+// only between two head-of-chain nodes therefore strands every connection the
+// moment either endpoint evolves — not deleted, unreachable. Measured live:
+// 3,678 visible against 4,425 authored, so 737 were unreachable, and the
+// stranding is symmetric (either endpoint being evolved is enough).
+//
+// `types` and `limit` bound the payload. begin_session used to return this
+// whole thing inline: 498 heads and 600,820 characters on ServiceNow Docs,
+// ~150k tokens as the first act of a session. Truncating descriptions would
+// not have helped — they are uniformly long (p50 616 chars, p95 1,677, only
+// 11 over 5k) — so selection is the only remedy.
+//
+// Append-only has no retraction, so an edge absent from a later chain node is
+// not a retraction — every authored edge stays live. Dedup is by
+// (source head, target head, type); a pair connected by two types keeps both.
+// Entities are reached FROM the domain rather than filtered by a copy of its
+// name — see _resolve.md. A target's domain is walked the same way.
+MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)-[:DISCOVERED]->(e:Knowledge)
+WHERE NOT (e)<-[:EVOLVED_FROM]-()
+  AND ($types IS NULL OR e.ont_type IN $types OR any(l IN labels(e) WHERE l IN $types))
+WITH DISTINCT e
+ORDER BY e.t_created DESC
+__limit_clause__
+OPTIONAL MATCH (e)-[:EVOLVED_FROM*0..]->(anc)-[r]->(o:Knowledge)
+WHERE NOT type(r) IN $excluded
+OPTIONAL MATCH (target:Knowledge)-[:EVOLVED_FROM*0..]->(o)
+WHERE NOT (target)<-[:EVOLVED_FROM]-()
+RETURN e.name AS name, e.ont_type AS type, labels(e) AS labels,
+       __description_expr__ AS description, e.t_created AS t_created,
+       collect(DISTINCT {
+         target: target.name,
+         target_domain: [(td:Domain)-[:HAS_SESSION]->(:Session)
+                          -[:DISCOVERED]->(target) | td.name][0],
+         type: type(r)}) AS connections
+ORDER BY e.t_created DESC

kenning_continuity/_cypher/index_create.cypher

@@ -0,0 +1,3 @@
+CREATE FULLTEXT INDEX knowledge_index IF NOT EXISTS
+FOR (n:Actor|Structure|Artifact|Place|Event|Insight|Pattern|Challenge|Solution|Lesson|Rationale)
+ON EACH [n.name, n.description]

kenning_continuity/_cypher/knowledge_collision.cypher

@@ -0,0 +1,14 @@
+// What already occupies a (name, domain) that create_knowledge just refused.
+//
+// Runs only on the collision path. The refusal names three options — evolve,
+// confirm, rename — but choosing between them requires knowing what is there,
+// so before this the agent had to search, read, decide, then act: four calls
+// to make one decision. 89% of the production graph has never been evolved,
+// which is what a four-call decision produces.
+MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(existing:Knowledge {name: $name})
+WHERE NOT (existing)<-[:EVOLVED_FROM]-()
+RETURN DISTINCT existing.description AS description,
+       existing.ont_type AS ont_type,
+       labels(existing) AS labels,
+       toString(existing.t_created) AS t_created

kenning_continuity/_cypher/knowledge_confirm.cypher

@@ -0,0 +1,9 @@
+MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(e:Knowledge {name: $name})
+WHERE NOT (e)<-[:EVOLVED_FROM]-()
+WITH DISTINCT e
+MATCH (s:Session {session_id: $session_id})
+MERGE (s)-[c:CONFIRMED]->(e)
+ON CREATE SET c.t_created = datetime()
+RETURN e.name AS name, e.ont_type AS type, labels(e) AS labels,
+       $domain AS domain, e.description AS description

kenning_continuity/_cypher/knowledge_create.cypher

@@ -0,0 +1,18 @@
+// See _resolve.md — domain is a query parameter, resolved by walk.
+OPTIONAL MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)
+              -[:DISCOVERED]->(existing:Knowledge {name: $name})
+WHERE NOT (existing)<-[:EVOLVED_FROM]-()
+WITH existing
+WHERE existing IS NULL
+MATCH (s:Session {session_id: $session_id})
+CREATE (e:__labels__ {
+  name: $name,
+  description: $description,
+  ont_type: $ont_type,
+  t_created: datetime()
+})
+__sources_clause__
+__t_valid_clause__
+CREATE (s)-[d:DISCOVERED]->(e)
+__basis_clause__
+RETURN e.name AS name, e.ont_type AS type, labels(e) AS labels

kenning_continuity/_cypher/knowledge_evolve.cypher

@@ -0,0 +1,20 @@
+// The successor is discovered by the evolving session, which is what places it
+// in a domain. It inherits no domain property because there is none to inherit.
+MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(old:Knowledge:`__ont_label__` {name: $name})
+WHERE NOT (old)<-[:EVOLVED_FROM]-()
+WITH DISTINCT old
+MATCH (s:Session {session_id: $session_id})
+CREATE (new:__new_labels__ {
+  name: old.name,
+  description: $new_description,
+  ont_type: $ont_type,
+  t_created: datetime()
+})
+__sources_clause__
+__t_valid_clause__
+CREATE (new)-[:EVOLVED_FROM]->(old)
+CREATE (s)-[d:DISCOVERED]->(new)
+__basis_clause__
+RETURN new.name AS name, new.ont_type AS type, labels(new) AS labels,
+       new.description AS description, $domain AS domain

kenning_continuity/_cypher/referent_claim.cypher

@@ -0,0 +1,24 @@
+// A co-reference CLAIM between two knowledge-layer referents.
+//
+// Both endpoints are resolved by walking from their Domain — see _resolve.md —
+// so a name living in eleven domains cannot produce a cross product, and a
+// process node is unreachable by construction: a referent has no frame from
+// which to perform an act of reference.
+//
+// `session_id` rides on the edge because a claim with no author is precisely
+// what this edge exists to prevent — it is the vector that made the claim, not
+// derivable from the endpoints. The claim's TIME is not stored: it is the
+// session's timestamp, one hop away.
+MATCH (:Domain {name: $source_domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(source:Knowledge {name: $source})
+WHERE NOT (source)<-[:EVOLVED_FROM]-()
+MATCH (:Domain {name: $target_domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(target:Knowledge {name: $target})
+WHERE NOT (target)<-[:EVOLVED_FROM]-()
+WITH DISTINCT source, target
+MATCH (s:Session {session_id: $session_id})
+MERGE (source)-[c:REFERENT_CLAIM]->(target)
+SET c.resolution = $resolution, c.session_id = $session_id
+RETURN source.name AS source, $source_domain AS source_domain,
+       target.name AS target, $target_domain AS target_domain,
+       c.resolution AS resolution, c.session_id AS session_id

kenning_continuity/_cypher/search_connections.cypher

@@ -0,0 +1,32 @@
+// Connections between the entities a search actually returned.
+//
+// Matching is by NODE IDENTITY, not by name, and edges resolve THROUGH the
+// chain. The prior version matched `source.name IN $names AND target.name IN
+// $names` against head nodes only, which held three defects, all measured live:
+//   · no head-of-chain filter — a head shares its name with its own
+//     predecessors, so a chain's EVOLVED_FROM edges surfaced as self-loops
+//     (8 spurious rows on one `Dana Whitfield` search)
+//   · no domain scoping — an edge authored between two referents in one domain
+//     was reported between their same-named counterparts in another (9 live
+//     pairs, both directions)
+//   · no chain resolution — an edge authored before either endpoint evolved
+//     was unreachable (737 graph-wide)
+//
+// Cross-domain edges are NOT excluded: 138 are deliberately authored. The fix
+// is identity, not same-domain confinement.
+UNWIND $pairs AS pair
+MATCH (:Domain {name: pair.domain})-[:HAS_SESSION]->(:Session)
+     -[:DISCOVERED]->(n:Knowledge {name: pair.name})
+WHERE NOT (n)<-[:EVOLVED_FROM]-()
+WITH collect(DISTINCT n) AS nodes
+UNWIND nodes AS source
+MATCH (source)-[:EVOLVED_FROM*0..]->(anc)-[r]->(o)
+WHERE NOT type(r) IN $excluded
+MATCH (target)-[:EVOLVED_FROM*0..]->(o)
+WHERE NOT (target)<-[:EVOLVED_FROM]-()
+  AND target IN nodes
+RETURN DISTINCT source.name AS source,
+       [(sd:Domain)-[:HAS_SESSION]->(:Session)-[:DISCOVERED]->(source) | sd.name][0] AS source_domain,
+       target.name AS target,
+       [(td:Domain)-[:HAS_SESSION]->(:Session)-[:DISCOVERED]->(target) | td.name][0] AS target_domain,
+       type(r) AS connectionType

kenning_continuity/_cypher/search_knowledge.cypher

@@ -0,0 +1,11 @@
+CALL db.index.fulltext.queryNodes('knowledge_index', $query) YIELD node, score
+WHERE NOT (node)<-[:EVOLVED_FROM]-()
+WITH node, score,
+     [(d:Domain)-[:HAS_SESSION]->(:Session)-[:DISCOVERED]->(node) | d.name][0] AS domain
+WHERE ($domain IS NULL OR domain = $domain)
+WITH node, score, domain
+ORDER BY score DESC
+LIMIT $limit
+RETURN node.name AS name, node.ont_type AS type, labels(node) AS labels,
+       domain, node.description AS description,
+       score, node.t_created AS t_created

kenning_continuity/_cypher/session_create.cypher

@@ -0,0 +1,21 @@
+MERGE (p:Person {source_key: $director_key})
+ON CREATE SET p.name = $director
+WITH p
+CREATE (s:Session {
+  session_id: $session_id,
+  timestamp: datetime(), purpose: $purpose,
+  summary: '', status: $status
+})
+CREATE (p)-[:DIRECTED {method: 'platform-stated'}]->(s)
+WITH s, p
+MATCH (d:Domain {name: $domain})
+CREATE (d)-[:HAS_SESSION]->(s)
+WITH s, p
+OPTIONAL MATCH (:Domain {name: $domain})-[:HAS_SESSION]->(prev:Session)
+WHERE prev.session_id <> $session_id
+WITH s, p, prev ORDER BY prev.timestamp DESC LIMIT 1
+FOREACH (_ IN CASE WHEN prev IS NOT NULL THEN [1] ELSE [] END |
+    CREATE (prev)-[:NEXT_SESSION]->(s)
+)
+RETURN s.session_id AS session_id, s.timestamp AS timestamp,
+       p.name AS director, p.source_key AS director_key

kenning_continuity/_cypher/session_history.cypher

@@ -0,0 +1,15 @@
+MATCH (d:Domain {name: $domain})-[:HAS_SESSION]->(s:Session)
+WITH s ORDER BY s.timestamp ASC
+LIMIT $limit
+OPTIONAL MATCH (dir:Person)-[:DIRECTED]->(s)
+WITH s, dir
+OPTIONAL MATCH (s)-[:DISCOVERED]->(e)
+WITH s, dir, count(e) AS entities_discovered
+OPTIONAL MATCH (s)-[:CONFIRMED]->(c)
+WITH s, dir, entities_discovered, count(c) AS entities_confirmed
+RETURN s.session_id AS session_id,
+       dir.name AS director, dir.source_key AS director_key,
+       s.timestamp AS timestamp, s.purpose AS purpose,
+       s.summary AS summary, s.status AS status,
+       entities_discovered, entities_confirmed
+ORDER BY s.timestamp ASC

kenning_continuity/_migration/__init__.py

@@ -0,0 +1 @@
+"""Migration scripts for upgrading temporal knowledge graphs across versions."""

kenning_continuity/_migration/knowledge_focus.py

@@ -0,0 +1,259 @@
+"""Migration v0.6.x → v0.7.0.
+
+Run with:
+    python -m kenning_continuity._migration.knowledge_focus \\
+        --db-url bolt://localhost:7687 \\
+        --username neo4j --password ... \\
+        --database <database-name> \\
+        [--dry-run]
+
+`--database` is REQUIRED. Neo4j Desktop 2 hosts multiple named databases on
+a single instance; specifying the wrong one is destructive.
+
+Phases:
+  1. Backup advisory (out-of-band — script does NOT take a backup; you must)
+  2. Process layer rename (Run → Session, HAS_RUN → HAS_SESSION, etc.)
+  3. Knowledge layer label renames (Gotcha → Lesson, Change → Event)
+  4. Knowledge layer edge rename (RELATES_TO → ASSOCIATED_WITH)
+  5. Add ontological labels (Actor on Person/Organization; Structure on
+     System/Process/Configuration)
+  6. Add ont_type property to every knowledge node
+  7. Dependency reclassification (operator-assisted — prints helper query)
+  8. Fulltext index rebuild
+  9. Verification queries
+
+Each phase is independently reversible if the migration is wrong. Idempotent:
+re-running the script after a partial failure picks up where it left off
+(except Phase 1, which is advisory only).
+"""
+import argparse
+import asyncio
+import logging
+import sys
+from typing import Any
+
+from neo4j import AsyncGraphDatabase, RoutingControl
+
+
+logger = logging.getLogger("kenning_continuity._migration.knowledge_focus")
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+
+
+# Phase queries -------------------------------------------------------------
+
+PHASE_2_PROCESS_RENAMES = [
+    ("Session label", "MATCH (n:Run) REMOVE n:Run SET n:Session RETURN count(n) AS n"),
+    ("session_id property", "MATCH (n:Session) WHERE n.run_id IS NOT NULL "
+                            "SET n.session_id = n.run_id REMOVE n.run_id RETURN count(n) AS n"),
+    ("HAS_RUN → HAS_SESSION", "MATCH (a)-[r:HAS_RUN]->(b) "
+                              "MERGE (a)-[r2:HAS_SESSION]->(b) "
+                              "ON CREATE SET r2 = properties(r) "
+                              "DELETE r RETURN count(r2) AS n"),
+    ("NEXT_RUN → NEXT_SESSION", "MATCH (a)-[r:NEXT_RUN]->(b) "
+                                "MERGE (a)-[r2:NEXT_SESSION]->(b) "
+                                "ON CREATE SET r2 = properties(r) "
+                                "DELETE r RETURN count(r2) AS n"),
+]
+
+PHASE_3_KNOWLEDGE_LABEL_RENAMES = [
+    ("Gotcha → Lesson", "MATCH (n:Gotcha) REMOVE n:Gotcha SET n:Lesson RETURN count(n) AS n"),
+    ("Change → Event", "MATCH (n:Change) REMOVE n:Change SET n:Event RETURN count(n) AS n"),
+]
+
+PHASE_4_EDGE_RENAMES = [
+    ("RELATES_TO → ASSOCIATED_WITH", "MATCH (a)-[r:RELATES_TO]->(b) "
+                                     "MERGE (a)-[r2:ASSOCIATED_WITH]->(b) "
+                                     "ON CREATE SET r2 = properties(r) "
+                                     "DELETE r RETURN count(r2) AS n"),
+]
+
+PHASE_5_ONTOLOGICAL_LABELS = [
+    ("Actor (from Person/Organization)",
+     "MATCH (n) WHERE (n:Person OR n:Organization) AND NOT n:Actor "
+     "SET n:Actor RETURN count(n) AS n"),
+    ("Structure (from System/Process/Configuration)",
+     "MATCH (n) WHERE (n:System OR n:Process OR n:Configuration) AND NOT n:Structure "
+     "SET n:Structure RETURN count(n) AS n"),
+]
+
+PHASE_6_ONT_TYPE_PROPERTY = [
+    ("Actor", "MATCH (n:Actor) WHERE n.ont_type IS NULL SET n.ont_type = 'Actor' RETURN count(n) AS n"),
+    ("Structure", "MATCH (n:Structure) WHERE n.ont_type IS NULL SET n.ont_type = 'Structure' RETURN count(n) AS n"),
+    ("Artifact", "MATCH (n:Artifact) WHERE n.ont_type IS NULL SET n.ont_type = 'Artifact' RETURN count(n) AS n"),
+    ("Event", "MATCH (n:Event) WHERE n.ont_type IS NULL SET n.ont_type = 'Event' RETURN count(n) AS n"),
+    ("Insight", "MATCH (n:Insight) WHERE n.ont_type IS NULL SET n.ont_type = 'Insight' RETURN count(n) AS n"),
+    ("Pattern", "MATCH (n:Pattern) WHERE n.ont_type IS NULL SET n.ont_type = 'Pattern' RETURN count(n) AS n"),
+    ("Challenge", "MATCH (n:Challenge) WHERE n.ont_type IS NULL SET n.ont_type = 'Challenge' RETURN count(n) AS n"),
+    ("Solution", "MATCH (n:Solution) WHERE n.ont_type IS NULL SET n.ont_type = 'Solution' RETURN count(n) AS n"),
+    ("Lesson", "MATCH (n:Lesson) WHERE n.ont_type IS NULL SET n.ont_type = 'Lesson' RETURN count(n) AS n"),
+    ("Rationale", "MATCH (n:Rationale) WHERE n.ont_type IS NULL SET n.ont_type = 'Rationale' RETURN count(n) AS n"),
+]
+
+PHASE_7_DEPENDENCY_HELPER = (
+    "MATCH (d:Dependency) "
+    "OPTIONAL MATCH (d)-[r_out]->(out) "
+    "WHERE NOT type(r_out) IN ['DISCOVERED', 'CONFIRMED'] "
+    "OPTIONAL MATCH (in_node)-[r_in]->(d) "
+    "WHERE NOT type(r_in) IN ['DISCOVERED', 'CONFIRMED', 'HAS_SESSION', 'NEXT_SESSION'] "
+    "RETURN d.name AS name, d.domain AS domain, d.description AS description, "
+    "       collect(DISTINCT {dir: 'out', target: out.name, type: type(r_out)}) AS outgoing, "
+    "       collect(DISTINCT {dir: 'in', source: in_node.name, type: type(r_in)}) AS incoming"
+)
+
+PHASE_8_INDEX_REBUILD = [
+    ("Drop old fulltext index", "DROP INDEX knowledge_index IF EXISTS"),
+    ("Create new fulltext index",
+     "CREATE FULLTEXT INDEX knowledge_index IF NOT EXISTS "
+     "FOR (n:Actor|Structure|Artifact|Event|Insight|Pattern|Challenge|Solution|Lesson|Rationale) "
+     "ON EACH [n.name, n.description]"),
+]
+
+PHASE_9_VERIFICATION = [
+    ("Every knowledge node has exactly one ontological label",
+     "MATCH (n) WHERE n.ont_type IS NOT NULL "
+     "WITH n, [l IN labels(n) WHERE l IN ['Actor','Structure','Artifact','Event',"
+     "'Insight','Pattern','Challenge','Solution','Lesson','Rationale']] AS ont_labels "
+     "WHERE size(ont_labels) <> 1 "
+     "RETURN n.name AS name, n.domain AS domain, labels(n) AS labels, ont_labels"),
+    ("Every knowledge node's ont_type matches its ontological label",
+     "MATCH (n) WHERE n.ont_type IS NOT NULL "
+     "WITH n, [l IN labels(n) WHERE l = n.ont_type][0] AS match "
+     "WHERE match IS NULL "
+     "RETURN n.name AS name, n.domain AS domain, n.ont_type AS ont_type, labels(n) AS labels"),
+    ("No legacy labels remain (Run/Gotcha/Change)",
+     "MATCH (n) WHERE n:Run OR n:Gotcha OR n:Change "
+     "RETURN labels(n) AS labels, count(n) AS n"),
+    ("No legacy edge types remain (HAS_RUN/NEXT_RUN/RELATES_TO)",
+     "MATCH ()-[r:HAS_RUN|NEXT_RUN|RELATES_TO]->() "
+     "RETURN type(r) AS type, count(r) AS n"),
+    ("Dependency nodes remaining (operator must reclassify per Phase 7)",
+     "MATCH (n:Dependency) RETURN count(n) AS n"),
+]
+
+
+# Runner --------------------------------------------------------------------
+
+async def _run_phase(driver, name: str, queries: list[tuple[str, str]], dry_run: bool) -> None:
+    logger.info(f"=== {name} ===")
+    for label, query in queries:
+        if dry_run:
+            logger.info(f"  [DRY RUN] {label}: {query[:120]}{'…' if len(query) > 120 else ''}")
+            continue
+        try:
+            result = await driver.execute_query(query, routing_control=RoutingControl.WRITE)
+            if result.records:
+                count = result.records[0].get("n", "n/a")
+                logger.info(f"  {label}: {count} affected")
+            else:
+                logger.info(f"  {label}: no records returned")
+        except Exception as e:
+            logger.error(f"  {label}: FAILED — {e}")
+            raise
+
+
+async def _run_dependency_helper(driver, dry_run: bool) -> None:
+    logger.info("=== Phase 7: Dependency reclassification (operator-assisted) ===")
+    if dry_run:
+        logger.info(f"  [DRY RUN] Would query: {PHASE_7_DEPENDENCY_HELPER[:120]}…")
+        return
+    result = await driver.execute_query(PHASE_7_DEPENDENCY_HELPER, routing_control=RoutingControl.READ)
+    if not result.records:
+        logger.info("  No Dependency nodes found. Phase 7 complete.")
+        return
+    logger.warning(f"  Found {len(result.records)} Dependency nodes requiring operator review.")
+    logger.warning("  Reclassify each per the v0.7.0 plan:")
+    logger.warning("    REMOVE n:Dependency SET n:Structure:System SET n.ont_type = 'Structure'  // common case")
+    logger.warning("    REMOVE n:Dependency SET n:Actor:Organization SET n.ont_type = 'Actor'    // vendor case")
+    for record in result.records:
+        d: dict[str, Any] = dict(record)
+        logger.warning(f"    - {d.get('domain')!r}/{d.get('name')!r}: {d.get('description', '')[:80]}")
+
+
+async def _run_verification(driver) -> bool:
+    logger.info("=== Phase 9: Verification ===")
+    all_ok = True
+    for label, query in PHASE_9_VERIFICATION:
+        try:
+            result = await driver.execute_query(query, routing_control=RoutingControl.READ)
+            issues = result.records or []
+            if not issues:
+                logger.info(f"  {label}: OK")
+            else:
+                # The "Dependency nodes remaining" check returns one row with count=0 in success case
+                if "Dependency nodes remaining" in label:
+                    n = issues[0].get("n", 0) if issues else 0
+                    if n == 0:
+                        logger.info(f"  {label}: OK (0 remaining)")
+                    else:
+                        logger.warning(f"  {label}: {n} remain — Phase 7 incomplete")
+                else:
+                    logger.error(f"  {label}: {len(issues)} issue(s)")
+                    for issue in issues[:5]:
+                        logger.error(f"    {dict(issue)}")
+                    all_ok = False
+        except Exception as e:
+            logger.error(f"  {label}: query FAILED — {e}")
+            all_ok = False
+    return all_ok
+
+
+async def migrate(uri: str, user: str, password: str, database: str, dry_run: bool) -> int:
+    logger.warning("=" * 70)
+    logger.warning("Phase 1: BACKUP ADVISORY")
+    logger.warning("This script does NOT take a backup. Confirm you have one before continuing.")
+    logger.warning("Migration is destructive in spots. Press Ctrl+C now if unsure.")
+    logger.warning("=" * 70)
+
+    driver = AsyncGraphDatabase.driver(uri, auth=(user, password), database=database)
+    try:
+        if not dry_run:
+            await driver.verify_connectivity()
+            logger.info(f"Connected to Neo4j at {uri}")
+        else:
+            logger.info(f"[DRY RUN] Would connect to Neo4j at {uri}")
+
+        await _run_phase(driver, "Phase 2: Process layer rename", PHASE_2_PROCESS_RENAMES, dry_run)
+        await _run_phase(driver, "Phase 3: Knowledge label renames", PHASE_3_KNOWLEDGE_LABEL_RENAMES, dry_run)
+        await _run_phase(driver, "Phase 4: Edge rename (RELATES_TO → ASSOCIATED_WITH)", PHASE_4_EDGE_RENAMES, dry_run)
+        await _run_phase(driver, "Phase 5: Add ontological labels", PHASE_5_ONTOLOGICAL_LABELS, dry_run)
+        await _run_phase(driver, "Phase 6: Add ont_type property", PHASE_6_ONT_TYPE_PROPERTY, dry_run)
+        await _run_dependency_helper(driver, dry_run)
+        await _run_phase(driver, "Phase 8: Fulltext index rebuild", PHASE_8_INDEX_REBUILD, dry_run)
+
+        if dry_run:
+            logger.info("Dry run complete. No changes were made. Re-run without --dry-run to apply.")
+            return 0
+
+        ok = await _run_verification(driver)
+        if ok:
+            logger.info("Migration complete. v0.7.0 ready.")
+            return 0
+        else:
+            logger.error("Migration FAILED verification. Review issues above and address before using v0.7.0.")
+            return 2
+    finally:
+        await driver.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Migrate a temporal knowledge graph from v0.6.x to v0.7.0.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("--db-url", required=True, help="Neo4j bolt URL (e.g., bolt://localhost:7687)")
+    parser.add_argument("--username", default="neo4j", help="Neo4j username (default: neo4j)")
+    parser.add_argument("--password", required=True, help="Neo4j password")
+    parser.add_argument("--database", required=True, help="Neo4j database name (REQUIRED — Neo4j Desktop 2 hosts multiple named databases on one instance; running against the wrong one is destructive)")
+    parser.add_argument("--dry-run", action="store_true", help="Print phase queries without executing")
+    args = parser.parse_args()
+
+    rc = asyncio.run(migrate(
+        uri=args.db_url, user=args.username, password=args.password,
+        database=args.database, dry_run=args.dry_run,
+    ))
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()