flowforge-map 0.1.0__py3-none-any.whl

flowforge/flowmap/service.py

@@ -0,0 +1,379 @@
+"""The flow map's state (D17): the accepted Planner version, the user's edits on top, positions,
+re-checks and their diffs. The API is a thin layer over this.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from flowforge.connectors.models import Connector
+from flowforge.flowmap.diff import apply_choices, default_take, diff
+from flowforge.flowmap.models import (
+    CALL_KINDS,
+    CONNECTOR_TYPE,
+    Action,
+    Analysis,
+    Evidence,
+    Flow,
+    FlowEdge,
+    Override,
+    Trace,
+)
+from flowforge.flowmap.planner import NoFlow, Planner
+from flowforge.flowmap.validate import FlowError, actions_of, check, critical
+from flowforge.storage import FlowStore
+
+NOT_AVAILABLE = "No map yet. Scan a folder to draw what your app depends on."
+FIXED_KINDS = ("gate", "start", "end")
+
+
+class OverrideError(ValueError):
+    """An edit that isn't allowed. One plain sentence."""
+
+
+class VersionError(ValueError):
+    pass
+
+
+Edits = dict[str, list[dict[str, Any]]]
+
+
+def merge(flow: Flow, overrides: list[tuple[int, Override]]) -> tuple[Flow, Edits, list[dict[str, Any]]]:
+    """Apply the user's edits to a copy. Returns (flow, edits per block, hidden blocks).
+
+    Edits naming a block that no longer exists (after a re-check) are skipped, not errors.
+    """
+    flow = flow.model_copy(deep=True)
+    nodes = {n.id: n for n in flow.nodes}
+    edits: dict[str, list[dict[str, Any]]] = {}
+    hide: list[tuple[int, str]] = []
+
+    def note(node_id: str, oid: int, o: Override) -> None:
+        edits.setdefault(node_id, []).append({"id": oid, "op": o.op})
+
+    for oid, o in overrides:
+        if o.op == "add_node" and o.new_node is not None and o.new_node.id not in nodes:
+            node = o.new_node.model_copy(update={"added_by": "user", "status": "confirmed"})
+            flow.nodes.append(node)
+            nodes[node.id] = node
+            note(node.id, oid, o)
+        elif o.node not in nodes:
+            continue
+        elif o.op == "set_connector":
+            n = nodes[o.node]
+            n.connector = o.connector
+            if n.op is not None:
+                n.op = n.op.model_copy(update={"model": None})
+            note(o.node, oid, o)
+        elif o.op == "rename":
+            nodes[o.node].title = o.title or nodes[o.node].title
+            note(o.node, oid, o)
+        elif o.op == "confirm":
+            n = nodes[o.node]
+            n.status = "confirmed"
+            n.evidence = [*n.evidence, Evidence(type="user", text="Confirmed by you.")]
+            note(o.node, oid, o)
+        elif o.op == "add_edge" and o.source in nodes:
+            if not any(e.source == o.source and e.target == o.node for e in flow.edges):
+                flow.edges.append(FlowEdge(id=_edge_id(flow, f"user_{o.source}_{o.node}"), source=o.source,
+                                           target=o.node))
+            # the "Yours" mark goes on the step you added, not on the Planner's block it connects to
+            note(o.source if nodes[o.source].added_by == "user" else o.node, oid, o)
+        elif o.op == "hide":
+            hide.append((oid, o.node))
+
+    hidden: list[dict[str, Any]] = []
+    for oid, node_id in hide:
+        node = nodes.get(node_id)
+        if node is None or node.kind in FIXED_KINDS:
+            continue
+        ins = [e for e in flow.edges if e.target == node_id and e.kind != "retry"]
+        outs = [e for e in flow.edges if e.source == node_id and e.kind != "retry"]
+        flow.edges = [e for e in flow.edges if node_id not in (e.source, e.target)]
+        for a in ins:   # bypass the hidden block so the flow stays connected
+            for b in outs:
+                if not any(e.source == a.source and e.target == b.target for e in flow.edges):
+                    flow.edges.append(FlowEdge(id=_edge_id(flow, f"via_{a.source}_{b.target}"), source=a.source,
+                                               target=b.target, kind=a.kind, when=a.when))
+        flow.nodes = [n for n in flow.nodes if n.id != node_id]
+        del nodes[node_id]
+        hidden.append({"id": node_id, "title": node.title, "override": oid})
+    flow.suggestions = [s for s in flow.suggestions if s.node in nodes]
+    return flow, edits, hidden
+
+
+def _edge_id(flow: Flow, base: str) -> str:
+    base = base[:58]
+    taken = {e.id for e in flow.edges}
+    out, i = base, 2
+    while out in taken:
+        out, i = f"{base}_{i}", i + 1
+    return out
+
+
+class FlowService:
+    def __init__(self, store: FlowStore, connectors: Callable[[], dict[str, Connector]], planner: Planner | None):
+        self.store = store   # one map's versions, edits and positions (D21)
+        self.connectors = connectors
+        self.planner = planner
+        self.message: str | None = None   # why the Planner had nothing to draw (D25)
+
+    # --- reading ---------------------------------------------------------------------------------
+
+    def _base(self) -> tuple[dict[str, Any], Flow] | None:
+        row = self.store.latest_flow_version("accepted")
+        if row is None:
+            return None
+        return row, Flow.model_validate(row["flow"])
+
+    def planner_flow(self) -> Flow | None:
+        """The accepted Planner version, without the user's edits."""
+        base = self._base()
+        return base[1] if base else None
+
+    def overrides(self) -> list[tuple[int, Override]]:
+        return [(oid, Override.model_validate(data)) for oid, data in self.store.flow_overrides()]
+
+    def current(self, layer: str = "mine") -> dict[str, Any]:
+        base = self._base()
+        if base is None:
+            return {"available": False, "message": self.message or NOT_AVAILABLE}
+        row, flow = base
+        edits: dict[str, list[dict[str, Any]]] = {}
+        hidden: list[dict[str, Any]] = []
+        if layer == "mine":
+            flow, edits, hidden = merge(flow, self.overrides())
+        connectors = self.connectors()
+        flow = check(flow, connectors, strict=False)   # a deleted app shows as unconfirmed, not an error
+        cp = critical(flow)
+        analysis = Analysis.model_validate(row["analysis"] or {"stages": []})
+        on_path = set(cp.path)
+        cp_edges = set(zip(cp.path, cp.path[1:], strict=False))
+        planner_flow = Flow.model_validate(row["flow"])
+        planner_connector = {n.id: n.connector for n in planner_flow.nodes}
+        swapped = {node_id for node_id, items in edits.items() if any(i["op"] == "set_connector" for i in items)}
+        current_connector = {n.id: n.connector for n in flow.nodes}
+        tips = {s.node: s for s in flow.suggestions
+                if s.node not in swapped and s.connector != current_connector.get(s.node)}
+        nodes = []
+        for n in flow.nodes:
+            data = n.model_dump(mode="json")
+            stats = analysis.stats.get(n.id)
+            tip = tips.get(n.id)
+            data.update({
+                "yours": edits.get(n.id, []), "on_critical_path": n.id in on_path,
+                "stats": stats.model_dump(mode="json") if stats else None,
+                "tip": {"connector": tip.connector, "text": tip.text} if tip else None,
+                "planner_connector": planner_connector.get(n.id),
+            })
+            nodes.append(data)
+        edges = [{**e.model_dump(mode="json"), "on_critical_path": (e.source, e.target) in cp_edges}
+                 for e in flow.edges]
+        positions = {k: list(v) for k, v in analysis.positions.items()}
+        positions.update({k: list(v) for k, v in self.store.flow_positions().items()})
+        used = {n.connector for n in flow.nodes if n.connector}
+        apps = {cid: {"name": c.name, "type": c.type, "model": getattr(c.connection, "model", None)}
+                for cid, c in connectors.items() if cid in used}
+        pending = self.store.latest_flow_version("pending")
+        return {
+            "available": True, "kind": flow.kind, "source": flow.source, "version": row["version"],
+            "created_at": row["created_at"],
+            "advice": [a.model_dump(mode="json") for a in flow.advice], "written_ms": flow.written_ms,
+            "patterns": flow.patterns,
+            "actions": [a.model_dump(mode="json") for a in _actions(planner_flow, flow)], "layer": layer,
+            "fact_sheet_hash": row["fact_sheet_hash"], "nodes": nodes, "edges": edges, "hidden": hidden,
+            "critical_path": {"path": cp.path, "length_ms": cp.length_ms, "bottleneck": cp.bottleneck},
+            "positions": positions, "apps": apps,
+            "counts": {"steps": len(flow.nodes), "unconfirmed": sum(n.status == "unconfirmed" for n in flow.nodes),
+                       "gates": sum(n.kind == "gate" for n in flow.nodes), "edits": len(self.store.flow_overrides())},
+            "pending": pending["version"] if pending else None,
+        }
+
+    def trace(self) -> dict[str, Any] | None:
+        base = self._base()
+        if base is None or not base[0]["trace"]:
+            return None
+        return Trace.model_validate(base[0]["trace"]).model_dump(mode="json")
+
+    def analysis(self) -> dict[str, Any] | None:
+        base = self._base()
+        if base is None:
+            return None
+        data = Analysis.model_validate(base[0]["analysis"] or {"stages": []}).model_dump(mode="json")
+        data.pop("stats", None)
+        data.pop("positions", None)
+        return {**data, "version": base[0]["version"], "fact_sheet_hash": base[0]["fact_sheet_hash"]}
+
+    def versions(self) -> list[dict[str, Any]]:
+        return self.store.flow_versions()
+
+    # --- the first map ---------------------------------------------------------------------------
+
+    def has_map(self) -> bool:
+        return self.store.count_flow_versions() > 0
+
+    def map_folder(self, planner: Planner, fresh: bool) -> int | None:
+        """Point this map at a Planner (a scanned folder, D21) and draw its first map if there is none.
+        `fresh` forgets the old map first: its versions, edits and positions belong to another folder."""
+        if fresh:
+            self.store.clear()
+        self.planner = planner
+        return self.first_map()
+
+    def first_map(self) -> int | None:
+        """Draw the first map if there is none. Returns its version, or None without a Planner."""
+        if self.planner is None or self.store.count_flow_versions():
+            return None
+        try:
+            draft = self.planner.analyze(0)
+        except NoFlow as why:
+            self.message = str(why)
+            return None
+        self.message = None
+        check(draft.flow, self.connectors())   # the Planner's output must be a valid map
+        return self.store.add_flow_version("accepted", draft.flow.model_dump(mode="json"),
+                                             draft.trace.model_dump(mode="json") if draft.trace else None,
+                                             draft.analysis.model_dump(mode="json"), draft.fact_sheet_hash)
+
+    # --- edits -----------------------------------------------------------------------------------
+
+    def add_override(self, override: Override) -> dict[str, Any]:
+        base = self._base()
+        if base is None:
+            raise OverrideError("there is no map to edit yet")
+        _, flow = base
+        connectors = self.connectors()
+        merged = check(merge(flow, self.overrides())[0], connectors, strict=False)  # statuses as drawn
+        node = merged.node(override.node) if override.node else None
+        if override.op != "add_node" and node is None:
+            raise OverrideError(f"there is no block '{override.node}' on the map")
+        if override.op == "hide" and node is not None and node.kind in FIXED_KINDS:
+            raise OverrideError("gates, starts and ends can't be hidden; gates always stay (D14)")
+        if override.op == "set_connector" and node is not None:
+            if node.kind not in CALL_KINDS:
+                raise OverrideError(f"'{node.title}' doesn't call an app, so it has no app to swap")
+            _need_connector(override.connector, node.kind, connectors)
+        if override.op == "confirm" and node is not None and node.status != "unconfirmed":
+            raise OverrideError(f"'{node.title}' is already confirmed")
+        if override.op == "add_node" and override.new_node is not None:
+            new = override.new_node
+            if merged.node(new.id) is not None or any(n.id == new.id for n in flow.nodes):
+                raise OverrideError(f"there is already a block called '{new.id}'")
+            if new.kind not in CALL_KINDS | {"code"}:
+                raise OverrideError("you can add app calls and code steps; the Planner draws the rest")
+            if new.kind in CALL_KINDS and (flow.kind == "flow" or new.connector):
+                _need_connector(new.connector, new.kind, connectors)   # a dependency needs no connected app (D21)
+            override = override.model_copy(update={"new_node": new.model_copy(update={
+                "added_by": "user", "status": "confirmed",
+                "evidence": new.evidence or [Evidence(type="user", text="Added by you.")]})})
+        if override.op == "add_edge" and merged.node(override.source or "") is None:
+            raise OverrideError(f"there is no block '{override.source}' on the map")
+        trial, _, _ = merge(flow, [*self.overrides(), (0, override)])
+        try:
+            check(trial, connectors)
+        except FlowError as err:
+            raise OverrideError(str(err)) from None
+        oid = self.store.add_flow_override(override.model_dump(mode="json", exclude_none=True))
+        return {"id": oid, **override.model_dump(mode="json", exclude_none=True)}
+
+    def delete_override(self, oid: int) -> bool:
+        return self.store.delete_flow_overrides([oid]) > 0
+
+    def reset_node(self, node_id: str) -> int:
+        """Back to the Planner's version: drop every edit on this block (and a block you added, with its lines)."""
+        ids = []
+        for oid, o in self.overrides():
+            if o.node == node_id or (o.op == "add_node" and o.new_node is not None and o.new_node.id == node_id) \
+                    or (o.op == "add_edge" and o.source == node_id and self._user_added(node_id)):
+                ids.append(oid)
+        return self.store.delete_flow_overrides(ids)
+
+    def _user_added(self, node_id: str) -> bool:
+        return any(o.op == "add_node" and o.new_node is not None and o.new_node.id == node_id
+                   for _, o in self.overrides())
+
+    def set_positions(self, positions: dict[str, tuple[float, float]], replace: bool = False) -> None:
+        self.store.put_flow_positions(positions, replace=replace)
+
+    # --- re-check --------------------------------------------------------------------------------
+
+    def recheck(self) -> dict[str, Any]:
+        if self.planner is None:
+            raise VersionError(NOT_AVAILABLE)
+        base = self._base()
+        if base is None:
+            raise VersionError("there is no map to re-check yet")
+        row, old = base
+        try:
+            draft = self.planner.analyze(self.store.count_flow_versions())
+        except NoFlow as why:
+            raise VersionError(str(why)) from None
+        try:
+            check(draft.flow, self.connectors())
+        except FlowError as err:
+            raise VersionError(f"the Planner's new map isn't valid: {err}") from None
+        pending = self.store.latest_flow_version("pending")
+        if pending is not None:
+            self.store.update_flow_version(pending["version"], "discarded")
+        changes = diff(old, draft.flow, self.overrides(), draft.analysis.notes)
+        version = self.store.add_flow_version(
+            "pending", draft.flow.model_dump(mode="json"), draft.trace.model_dump(mode="json") if draft.trace else None,
+            draft.analysis.model_dump(mode="json"), draft.fact_sheet_hash, changes=changes)
+        return self.pending_view(version)
+
+    def pending_view(self, version: int) -> dict[str, Any]:
+        row = self.store.flow_version(version)
+        if row is None or row["status"] != "pending":
+            raise VersionError(f"version {version} is not waiting for a decision")
+        base = self._base()
+        new = Flow.model_validate(row["flow"])
+        return {"version": version, "base_version": base[0]["version"] if base else None,
+                "created_at": row["created_at"], "fact_sheet_hash": row["fact_sheet_hash"],
+                "changes": row["changes"] or [], "default_take": default_take(row["changes"] or []),
+                "nodes": [n.model_dump(mode="json") for n in new.nodes],
+                "edges": [e.model_dump(mode="json") for e in new.edges]}
+
+    def accept(self, version: int, take: dict[str, bool | str]) -> dict[str, Any]:
+        row = self.store.flow_version(version)
+        if row is None or row["status"] != "pending":
+            raise VersionError(f"version {version} is not waiting for a decision")
+        base = self._base()
+        if base is None:
+            raise VersionError("there is no map to update")
+        changes = row["changes"] or []
+        known = {c["id"] for c in changes}
+        unknown = sorted(set(take) - known)
+        if unknown:
+            raise VersionError(f"unknown change: {', '.join(unknown)}")
+        flow, drop_edits = apply_choices(base[1], Flow.model_validate(row["flow"]), changes, take)
+        try:
+            check(flow, self.connectors())
+        except FlowError as err:
+            raise VersionError(f"that mix of changes isn't a valid map: {err}") from None
+        self.store.update_flow_version(version, "accepted", flow.model_dump(mode="json"))
+        stale = [oid for oid, o in self.overrides() if o.node in drop_edits]
+        self.store.delete_flow_overrides(stale)
+        return self.current()
+
+    def discard(self, version: int) -> None:
+        row = self.store.flow_version(version)
+        if row is None or row["status"] != "pending":
+            raise VersionError(f"version {version} is not waiting for a decision")
+        self.store.update_flow_version(version, "discarded")
+
+
+def _need_connector(connector_id: str | None, kind: str, connectors: dict[str, Connector]) -> None:
+    if not connector_id or connector_id not in connectors:
+        raise OverrideError(f"'{connector_id}' isn't connected; add it from the catalog first")
+    want = CONNECTOR_TYPE[kind]
+    if connectors[connector_id].type != want:
+        raise OverrideError(f"'{connector_id}' is a {connectors[connector_id].type} app; this step needs a {want} app")
+
+
+def _actions(scanned: Flow, merged: Flow) -> list[Action]:
+    """Each action's numbers from the map as it is shown, your edits included (D33): a hidden call leaves its critical
+    path and "as written", and a group that runs together still counts at its slowest remaining call."""
+    if not scanned.actions:
+        return []
+    return actions_of(merged, {a.id: a.parts for a in scanned.actions if a.parts})

flowforge/flowmap/validate.py

@@ -0,0 +1,228 @@
+"""Checks on a flow map and the gating policy (D17, D14).
+
+`check()` runs on the Planner's output and again on the merged map after the user's edits, so
+no edit can open a path around a gate. Code decides what is side-effecting; the Planner can add
+gates but never remove one.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from flowforge.connectors.models import Connector
+from flowforge.flowmap.models import CALL_KINDS, CONNECTOR_TYPE, Action, Evidence, Flow, FlowEdge, FlowNode
+from flowforge.scheduler.critical_path import critical_path
+from flowforge.scheduler.graph import DAG, CycleError, topological_order
+
+# rough per-kind estimates (ms) when the Planner gives none (extends D1)
+DEFAULT_MS = {"llm": 2000.0, "api": 300.0, "mcp": 500.0, "local": 1000.0, "code": 50.0}
+# blocks that need evidence of their own; fork/join/gate/end get their meaning from the lines around them
+NEEDS_EVIDENCE = CALL_KINDS | {"code", "decision", "start"}
+POLICY_TEXT = "Side effects always wait for you (D14). Added by code, so no edit can remove it."
+
+
+class FlowError(ValueError):
+    """The map is structurally wrong. The message is one plain sentence naming the block."""
+
+
+def side_effecting(node: FlowNode) -> bool:
+    """D14 list, decided by code: non-GET HTTP, MCP tools not marked read-only, every local command.
+
+    D17 refinement: a GET to a payment API reads; only calls that move money or send are gated.
+    """
+    op = node.op
+    if node.kind == "local":
+        return True
+    if node.kind == "mcp":
+        return not (op is not None and op.read_only is True)
+    if node.kind == "api":
+        return op is None or op.method not in ("GET", "HEAD")
+    return False
+
+
+def code_writes(node: FlowNode) -> bool:
+    """D25, on a flow read from code: marked, never gated. An HTTP call other than GET or HEAD, or an MCP tool that
+    isn't read-only. A local program or a call with no method isn't claimed to write."""
+    op = node.op
+    if node.kind == "api":
+        return op is not None and op.method is not None and op.method.upper() not in ("GET", "HEAD")
+    return node.kind == "mcp" and op is not None and op.read_only is False
+
+
+def _dag(flow: Flow, kinds: set[str]) -> DAG:
+    nodes = [n.id for n in flow.nodes]
+    parents: dict[str, list[str]] = {n: [] for n in nodes}
+    children: dict[str, list[str]] = {n: [] for n in nodes}
+    for e in flow.edges:
+        if e.kind in kinds and e.source not in parents[e.target]:
+            parents[e.target].append(e.source)
+            children[e.source].append(e.target)
+    return DAG(nodes=nodes, parents=parents, children=children)
+
+
+def check(flow: Flow, connectors: Mapping[str, Connector], strict: bool = True) -> Flow:
+    """A checked copy: statuses and side effects set, unconfirmed lines marked, policy gates inserted.
+
+    Raises FlowError for a loop, a call with no app, an unknown app, a type mismatch or a decision
+    without two labelled branches. With `strict=False` (drawing the map) an app problem marks the
+    block unconfirmed instead, so deleting a connector never breaks the page.
+    """
+    flow = flow.model_copy(deep=True)
+    code = flow.source == "code"   # the app's own flow, read from its code: no connected apps, no gates (D25)
+    try:
+        topological_order(_dag(flow, {"flow", "branch", "fallback", "unconfirmed"}))
+    except CycleError as err:
+        raise FlowError(f"the map has a loop: {' → '.join(err.cycle)}") from None
+
+    for node in flow.nodes:
+        if node.kind in NEEDS_EVIDENCE and node.status == "confirmed" and node.added_by != "user" \
+                and not any(ev.confirms for ev in node.evidence):
+            node.status = "unconfirmed"
+        if node.kind in CALL_KINDS and ((flow.kind == "flow" and not code) or node.connector):
+            try:
+                _check_connector(node, connectors)   # a dependency needs no connected app (D21)
+            except FlowError as err:
+                if strict:
+                    raise
+                node.status = "unconfirmed"
+                node.evidence = [*node.evidence, Evidence(type="missing", text=str(err).capitalize() + ".")]
+        # gates belong to flow maps (D21); a flow read from code only marks its writes (D25)
+        node.side_effect = code_writes(node) if code else flow.kind == "flow" and side_effecting(node)
+        if node.kind == "decision":
+            whens = [e.when for e in flow.edges if e.source == node.id and e.kind == "branch"]
+            if len(set(whens)) < (1 if code else 2):   # code: an `if` with no else just carries on (D25)
+                raise FlowError(f"decision '{node.title}' needs two labelled branches (for example yes and no)")
+
+    unconfirmed = {n.id for n in flow.nodes if n.status == "unconfirmed"}
+    for e in flow.edges:
+        if e.kind != "retry" and e.target in unconfirmed:
+            e.kind = "unconfirmed"
+        elif e.kind == "unconfirmed":
+            e.kind = "flow"
+
+    if not code:
+        _insert_gates(flow)
+    return flow
+
+
+def _check_connector(node: FlowNode, connectors: Mapping[str, Connector]) -> None:
+    if not node.connector:
+        raise FlowError(f"block '{node.title}' is an app call but names no app")
+    connector = connectors.get(node.connector)
+    if connector is None:
+        if node.status == "unconfirmed":
+            return  # a hint may name an app nobody has connected yet
+        raise FlowError(f"block '{node.title}' uses '{node.connector}', which is not connected")
+    want = CONNECTOR_TYPE[node.kind]
+    if connector.type != want:
+        raise FlowError(f"block '{node.title}' is a {node.kind} call but '{node.connector}' is a {connector.type} app")
+
+
+def _insert_gates(flow: Flow) -> None:
+    """Every confirmed side-effecting block gets a gate in front of it unless every way in is a gate."""
+    kinds = {n.id: n.kind for n in flow.nodes}
+    for node in list(flow.nodes):
+        if not node.side_effect or node.status != "confirmed":
+            continue
+        incoming = [e for e in flow.edges if e.target == node.id and e.kind not in ("retry", "unconfirmed")]
+        if incoming and all(kinds[e.source] == "gate" for e in incoming):
+            continue
+        gate_id = _free_id({n.id for n in flow.nodes}, f"gate_{node.id}")
+        gate = FlowNode(id=gate_id, kind="gate", title=f"Approve: {node.title}"[:80], added_by="policy",
+                        what="This step changes something outside the app, so it waits for you.",
+                        evidence=[Evidence(type="policy", text=POLICY_TEXT)])
+        flow.nodes.insert(flow.nodes.index(node), gate)
+        kinds[gate_id] = "gate"
+        for e in incoming:
+            e.target = gate_id
+        flow.edges.append(FlowEdge(id=_free_id({e.id for e in flow.edges}, f"{gate_id}_to_{node.id}")[:64],
+                                   source=gate_id, target=node.id))
+
+
+def _free_id(taken: set[str], base: str) -> str:
+    base = base[:60]
+    if base not in taken:
+        return base
+    i = 2
+    while f"{base}_{i}" in taken:
+        i += 1
+    return f"{base}_{i}"
+
+
+@dataclass
+class Critical:
+    path: list[str] = field(default_factory=list)
+    length_ms: float = 0.0
+    bottleneck: str | None = None   # the slowest block on the path
+
+
+def weight(node: FlowNode) -> float:
+    if node.estimate_ms is not None:
+        return node.estimate_ms
+    return DEFAULT_MS.get(node.kind, 0.0)
+
+
+def critical(flow: Flow) -> Critical:
+    """The longest expected chain (D1, D5) through the app's own flow: normal and branch lines only.
+    Fallbacks, retries, unconfirmed blocks and steps the user added are not the expected path.
+    Gates weigh 0, as people are not a resource."""
+    if flow.kind == "dependencies":
+        return Critical()   # what the app uses has no order to be critical along (D21)
+    keep = {n.id for n in flow.nodes if n.status == "confirmed" and n.added_by != "user"}
+    lines = [e for e in flow.edges if e.kind in ("flow", "branch") and e.source in keep and e.target in keep]
+    # only blocks reachable from a start along normal lines (a fallback-only block is not the expected path)
+    roots = [n.id for n in flow.nodes if n.id in keep and n.kind == "start"] or \
+        [i for i in keep if not any(e.target == i for e in lines)]
+    reach, queue = set(roots), list(roots)
+    while queue:
+        here = queue.pop()
+        for e in lines:
+            if e.source == here and e.target not in reach:
+                reach.add(e.target)
+                queue.append(e.target)
+    sub = Flow(nodes=[n for n in flow.nodes if n.id in reach],
+               edges=[e for e in lines if e.source in reach and e.target in reach])
+    if not sub.nodes:
+        return Critical()
+    weights = {n.id: 0.0 if n.kind == "gate" else weight(n) for n in sub.nodes}
+    dag = _dag(sub, {"flow", "branch"})
+    cp = critical_path(dag, weights)
+    path = list(cp.path)
+    while path:  # carry on through zero-time blocks (an end, a join) so the chain reaches its end
+        nxt = next((c for c in dag.children[path[-1]] if weights[c] == 0 and c not in path), None)
+        if nxt is None:
+            break
+        path.append(nxt)
+    bottleneck = max(path, key=lambda i: weights[i]) if path else None
+    return Critical(path=path, length_ms=cp.length_ms, bottleneck=bottleneck)
+
+
+def reach(flow: Flow, start: str) -> set[str]:
+    """Everything a start block leads to."""
+    seen, queue = {start}, [start]
+    while queue:
+        here = queue.pop()
+        for e in flow.edges:
+            if e.source == here and e.target not in seen:
+                seen.add(e.target)
+                queue.append(e.target)
+    return seen
+
+
+def actions_of(flow: Flow, parts: dict[str, list[list[str]]]) -> list[Action]:
+    """Each entry point of a code flow on its own (D33): its time as written (from `parts`, by start id: its calls in
+    the groups the code runs them), could be, and the chain that sets it, slowest first. The service recomputes them
+    on the map as shown, so a hidden call leaves both times."""
+    weight = {n.id: n.estimate_ms or 0.0 for n in flow.nodes if n.kind in CALL_KINDS}
+    out = []
+    for start in (n for n in flow.nodes if n.kind == "start"):
+        ids = reach(flow, start.id)
+        sub = Flow(kind="flow", source="code", nodes=[n for n in flow.nodes if n.id in ids],
+                   edges=[e for e in flow.edges if e.source in ids and e.target in ids])
+        cp = critical(sub)
+        mine = parts.get(start.id, [[i] for i in ids if i in weight])
+        written = sum(max((weight[i] for i in p if i in weight), default=0.0) for p in mine)
+        out.append(Action(id=start.id, title=start.title, written_ms=round(written, 1), could_ms=round(cp.length_ms, 1),
+                          path=list(cp.path), calls=sum(1 for n in sub.nodes if n.kind in CALL_KINDS), parts=mine))
+    return sorted(out, key=lambda a: (-a.written_ms, a.title))

flowforge/home.py

@@ -0,0 +1,58 @@
+"""Where FlowForge's files are (D34): per-user state in FLOWFORGE_HOME (databases, artifacts, connectors.json), and
+the files it ships (the dashboard, the example app, sample workflows) inside the installed package, or in the
+checkout when run from source."""
+
+from __future__ import annotations
+
+import os
+import sys
+from importlib import metadata
+from pathlib import Path
+
+PACKAGE = Path(__file__).resolve().parent
+CHECKOUT = PACKAGE.parents[1]
+DIST_NAME = "flowforge-map"   # the name on PyPI (D34); the command and the import stay `flowforge`
+IN_CHECKOUT = (CHECKOUT / "pyproject.toml").is_file() and (CHECKOUT / "backend" / "flowforge").is_dir()
+
+# name -> (inside the package, in the checkout)
+_FILES = {
+    "dashboard": ("_dashboard", "frontend/dist"),
+    "example": ("_example/trip-planner", "examples/trip-planner"),
+    "workflows": ("_workflows", "backend/workflows"),
+    "classic": ("_classic.html", "frontend/classic.html"),
+}
+
+
+def resource(name: str, package: Path = PACKAGE, checkout: Path = CHECKOUT) -> Path:
+    """A shipped file or folder: the packaged copy when installed, else the checkout's."""
+    packaged, source = _FILES[name]
+    inside = package / packaged
+    return inside if inside.exists() else checkout / source
+
+
+def version() -> str:
+    try:
+        return metadata.version(DIST_NAME)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def install_kind() -> str:
+    """"checkout" (run from source), "uvx" (a throwaway environment uv made for one run) or "pip" (installed)."""
+    if IN_CHECKOUT:
+        return "checkout"
+    return "uvx" if "archive-v" in Path(sys.prefix).as_posix() else "pip"
+
+
+def flowforge_home() -> Path:
+    return Path(os.getenv("FLOWFORGE_HOME") or Path.home() / ".flowforge")
+
+
+def database_path(example: bool = False) -> Path:
+    """The SQLite file: FLOWFORGE_DB, else example.db in FLOWFORGE_HOME for example data, else flowforge.db next to
+    the checkout, or in FLOWFORGE_HOME when installed. The dashboard and the MCP server open the same one (D29)."""
+    if example:
+        default = flowforge_home() / "example.db"
+    else:
+        default = CHECKOUT / "flowforge.db" if IN_CHECKOUT else flowforge_home() / "flowforge.db"
+    return Path(os.getenv("FLOWFORGE_DB") or default)