footprinter-cli 1.0.5__tar.gz → 1.1.1__tar.gz

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: footprinter-cli
-Version: 1.0.5
+Version: 1.1.1
 Summary: A local context layer for your files, browser history, chats, and email — searchable, user-owned, MCP-served.
 Author: SwellCity Group
 License: MIT
@@ -59,6 +59,12 @@ Requires-Dist: httpx<1.0,>=0.27.0; extra == "dev"
 
 **A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**
 
+> ⚠️ **Install with `pipx`, not `pip`.** `pipx` puts the `fp` command on your PATH automatically; bare `pip` often doesn't — which leaves you with `fp: command not found` even though the install succeeded.
+
+```bash
+pipx install footprinter-cli
+```
+
 Your work lives across filesystems, browsers, inboxes, chat histories, and other tools. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings you define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
 
 ## Install
@@ -100,6 +106,8 @@ To install with extras: use the [full install script](https://raw.githubusercont
 
 **ChromaDB telemetry:** Footprinter sets `anonymized_telemetry=False`. ChromaDB also removed product telemetry in v1.5.4. See [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss).
 
+**Apple Silicon (Rosetta):** If `fp doctor` warns about x86_64 Python on arm64 hardware, recreate the venv with a native interpreter: `pipx reinstall footprinter-cli --python /opt/homebrew/bin/python3`. This avoids compatibility issues with native-extension dependencies.
+
 </details>
 
 ### Uninstall
@@ -182,7 +190,7 @@ Sources are scanned into SQLite with bidirectional links connecting local files
 - [Data Model](https://github.com/harringjohn/footprinter-cli/blob/main/reference/data-model.md) — database schema
 - [Pipeline](https://github.com/harringjohn/footprinter-cli/blob/main/reference/pipeline.md) — indexing stages and configuration
 - [Content Storage](https://github.com/harringjohn/footprinter-cli/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
-- [Access Control](https://github.com/harringjohn/footprinter-cli/blob/main/reference/mcp-access-control.md) — MCP security model
+- [Permission Policies and Access Control](https://github.com/harringjohn/footprinter-cli/blob/main/reference/permission-policies-and-access-control.md) — permission policies and access control
 
 ## Contributing
 

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/README.md

@@ -5,6 +5,12 @@
 
 **A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**
 
+> ⚠️ **Install with `pipx`, not `pip`.** `pipx` puts the `fp` command on your PATH automatically; bare `pip` often doesn't — which leaves you with `fp: command not found` even though the install succeeded.
+
+```bash
+pipx install footprinter-cli
+```
+
 Your work lives across filesystems, browsers, inboxes, chat histories, and other tools. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings you define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
 
 ## Install
@@ -46,6 +52,8 @@ To install with extras: use the [full install script](https://raw.githubusercont
 
 **ChromaDB telemetry:** Footprinter sets `anonymized_telemetry=False`. ChromaDB also removed product telemetry in v1.5.4. See [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss).
 
+**Apple Silicon (Rosetta):** If `fp doctor` warns about x86_64 Python on arm64 hardware, recreate the venv with a native interpreter: `pipx reinstall footprinter-cli --python /opt/homebrew/bin/python3`. This avoids compatibility issues with native-extension dependencies.
+
 </details>
 
 ### Uninstall
@@ -128,7 +136,7 @@ Sources are scanned into SQLite with bidirectional links connecting local files
 - [Data Model](https://github.com/harringjohn/footprinter-cli/blob/main/reference/data-model.md) — database schema
 - [Pipeline](https://github.com/harringjohn/footprinter-cli/blob/main/reference/pipeline.md) — indexing stages and configuration
 - [Content Storage](https://github.com/harringjohn/footprinter-cli/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
-- [Access Control](https://github.com/harringjohn/footprinter-cli/blob/main/reference/mcp-access-control.md) — MCP security model
+- [Permission Policies and Access Control](https://github.com/harringjohn/footprinter-cli/blob/main/reference/permission-policies-and-access-control.md) — permission policies and access control
 
 ## Contributing
 

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/footprinter/access_stamper.py

@@ -353,18 +353,26 @@ def count_affected_entities(conn: sqlite3.Connection, scope: str) -> dict[str, i
     return {etype: len(ids) for etype, ids in _get_ids_for_scope(conn, scope).items() if ids}
 
 
-def stamp_entities(conn: sqlite3.Connection, ids_by_type: dict[str, list[int]]) -> dict[str, int]:
+def stamp_entities(
+    conn: sqlite3.Connection,
+    ids_by_type: dict[str, list[int]],
+    *,
+    commit: bool = True,
+) -> dict[str, int]:
     """Resolve and write visibility + permissions for the given entity IDs.
 
     Used by ``recalculate_access`` (full scope resolution) and the incremental
     pipeline path in ``processing.run_access_resolution``.  The batched variant
     (``recalculate_access_batched``) uses its own loop for per-chunk commits.
 
-    Always commits before returning, even when *ids_by_type* is empty.
+    Commits before returning by default, even when *ids_by_type* is empty.
+    When *commit* is False the caller is responsible for committing the
+    transaction.
 
     Args:
         conn: SQLite connection with row_factory = sqlite3.Row
         ids_by_type: Mapping of entity type to list of row IDs to stamp.
+        commit: If False, skip the final ``conn.commit()``.
 
     Returns:
         Dict mapping entity type to count of rows stamped.
@@ -387,22 +395,26 @@ def stamp_entities(conn: sqlite3.Connection, ids_by_type: dict[str, list[int]])
 
         stats[entity_type] = len(ids)
 
-    conn.commit()
+    if commit:
+        conn.commit()
     return stats
 
 
-def recalculate_access(conn: sqlite3.Connection, scope: str) -> dict[str, int]:
+def recalculate_access(
+    conn: sqlite3.Connection, scope: str, *, commit: bool = True,
+) -> dict[str, int]:
     """Recalculate visibility and permissions for all entities affected by *scope*.
 
     Args:
         conn: SQLite connection with row_factory = sqlite3.Row
         scope: Policy scope string (e.g. "global", "project:3", "folder:~/Work/")
+        commit: If False, skip committing — caller manages the transaction.
 
     Returns:
         Dict mapping entity type to count of rows updated.
     """
     ids_by_type = _get_ids_for_scope(conn, scope)
-    return stamp_entities(conn, ids_by_type)
+    return stamp_entities(conn, ids_by_type, commit=commit)
 
 
 def recalculate_access_batched(
@@ -411,18 +423,24 @@ def recalculate_access_batched(
     *,
     batch_size: int = 5000,
     on_batch: Callable[[int], None] | None = None,
+    commit: bool = True,
 ) -> dict[str, int]:
     """Recalculate visibility and permissions in batches with progress callback.
 
     Same semantics as ``recalculate_access()`` but commits after each batch
-    and calls *on_batch* with the count of entities processed per chunk.
-    Designed for large scopes where a progress bar is needed.
+    (when *commit* is True) and calls *on_batch* with the count of entities
+    processed per chunk.  Designed for large scopes where a progress bar is
+    needed.
 
     Args:
         conn: SQLite connection with row_factory = sqlite3.Row
         scope: Policy scope string (e.g. "global", "folder:~/Work/")
         batch_size: Number of entity IDs per chunk (default 5000)
         on_batch: Optional callback receiving the count processed per chunk
+        commit: If False, skip per-batch commits — all batches accumulate
+            in the caller's transaction.  This trades incremental commit
+            boundaries for atomicity; the caller is responsible for the
+            final commit.
 
     Returns:
         Dict mapping entity type to total count of rows updated.
@@ -446,7 +464,8 @@ def recalculate_access_batched(
                 perm_results = batch_resolve_permissions(conn, entity_type, chunk)
                 _write_back_permissions(conn, entity_type, perm_results)
 
-            conn.commit()
+            if commit:
+                conn.commit()
 
             if on_batch is not None:
                 on_batch(len(chunk))

footprinter_cli-1.1.1/footprinter/api/__init__.py

@@ -0,0 +1,19 @@
+"""Footprinter HTTP API — FastAPI routers calling the service layer."""
+
+import logging
+
+_logger = logging.getLogger(__name__)
+
+
+def _get_api_max_limit() -> int:
+    try:
+        from footprinter.source_registry import get_config
+
+        return get_config().get("limits", {}).get("api_max_limit", 200)
+    except Exception:
+        _logger.debug("Config unavailable for api_max_limit, using default 200")
+        return 200
+
+
+MAX_LIMIT = _get_api_max_limit()
+"""Upper bound for `limit` query params on HTTP list/search endpoints."""

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/footprinter/bundled/config.example.yaml

@@ -33,7 +33,7 @@ exclusions:
     - ".*/\\.venv/.*"            # Python virtualenvs (hidden)
     - ".*/site-packages/.*"      # Python packages
     - ".*\\.pyc$"                # Python compiled files
-    - ".*/\\.vscode/extensions/.*"  # VS Code extensions (reinstallable)
+    - ".*/\\.vscode/.*"             # VS Code config and extensions
     - ".*/\\.npm/.*"             # npm cache
     - ".*/\\.nvm/.*"             # Node version manager
     - ".*/\\.cache/.*"           # Generic caches
@@ -44,6 +44,13 @@ exclusions:
     - ".*/\\.browser_state/.*"   # Playwright/Puppeteer browser state
     - ".*/\\.context/.*"         # IDE/agent context directories
     - ".*/\\.ai-dev/.*"          # AI dev tool scratch dirs
+    # Build output and tool config dot-folders (no archival value)
+    - ".*/\\.next/.*"             # Next.js build output
+    - ".*/\\.husky/.*"            # Git hooks manager
+    - ".*/\\.astro/.*"            # Astro build cache
+    - ".*/\\.githooks/.*"         # Custom git hooks
+    - ".*/\\.aesthetic/.*"        # Aesthetic tool config
+    - ".*/\\.users/.*"            # IDE user preferences
     # Home-level Claude dirs only (keep .claude within Work/Personal)
     - "^~/\\.claude/.*"           # Home-level .claude (includes session-env snapshots)
     - "^~/\\.claude-worktrees/.*" # Home-level .claude-worktrees
@@ -79,8 +86,27 @@ exclusions:
 indexing:
   supported_extensions: []  # Empty = index ALL file types
   max_file_size_mb: 50      # MB; 0 = no size limit. 50 is generous for prose/docs.
+  # Cap on how many bytes the MCP read path (footprinter_read) pulls from a local
+  # file before decode/extraction. MB; 0 = no cap (read the whole file).
+  # Default 10 MB closes the old 500 KB silent-truncation gap so the read tool can
+  # return content the index already holds.
+  # The returned content is ALWAYS bounded to a payload-safe size regardless of
+  # this cap: a single MCP tool result has a ~1 MB protocol payload ceiling, so an
+  # oversized read returns a marked, in-budget slice (output_truncated) plus a
+  # pointer to semantic/keyword search — never a hard failure. That bound is a
+  # UTF-8 BYTE budget (sliced on a code-point boundary) sized under the ~1 MB JSON
+  # wall with headroom for JSON-escape expansion of multibyte content (CJK/emoji)
+  # and the result envelope — not a character count, so non-Latin scripts stay
+  # safe. Raise this cap to read more bytes from large files; for large documents,
+  # prefer search.
+  max_read_size_mb: 10
   lookback_days: 14         # Browser history window (days back to index)
-  content_snippets: false   # Extract file/email content previews for keyword search
+  # Opt-in (default off). When true, ingest reads each file/email and stores a
+  # short preview (~1000 chars/file) so keyword search matches file content, not
+  # just names. Cost: extra read work during ingest + the stored preview in SQLite.
+  # Enabling this after the first ingest backfills already-indexed files only on
+  # the next `fp ingest` run; new ingests populate previews automatically.
+  content_snippets: false
 
 # Semantic search — stores content as embeddings in a local ChromaDB database
 # Enables finding files and chats by meaning, not just keywords
@@ -88,6 +114,21 @@ indexing:
 semantic:
   file_vectorization: false
   chat_vectorization: false
+  # File statuses eligible for vectorization. Default: [listed].
+  # Add 'unlisted' to also embed hidden/dot-files.
+  # vectorize_statuses:
+  #   - listed
+  # Semantic file results — how much matched content to return per result.
+  # A chunk is ~1000 chars ≈ 250 tokens. Payload size ≈ max_chunks_per_file ×
+  # max_chunk_chars, so raise these for more context at higher token cost.
+  # Max characters of each matched chunk to return. Default 1000. 0 = no cap
+  # (return the whole chunk).
+  max_chunk_chars: 1000
+  # How many matched chunks to return per file, best-relevance first. Default 3.
+  # Clamped to [1, 20] — values above the cap are bounded to keep payloads sane.
+  # The per-result `chunks` list is returned only on the vector (semantic) path;
+  # the FTS5 keyword fallback (used when semantic search is unavailable) omits it.
+  max_chunks_per_file: 3
 
 # Vectorization — controls what gets embedded for semantic search
 # Requires semantic.file_vectorization: true to take effect for files
@@ -137,6 +178,21 @@ vectorization:
     - "**/.github/**"                       # GitHub workflow files (FTS-only)
     - "**/.ai-dev/**"                       # AI dev tool scratch dirs
 
+# Operational limits — tune for your data volume
+# All values have sensible defaults; omit the section entirely to use them.
+limits:
+  # Zip upload safety checks (chat imports via fp upload)
+  zip:
+    max_decompressed_size_mb: 2048    # 2 GB; raise for very large exports
+    max_entries: 10000                # Maximum files in a zip archive
+    max_compression_ratio: 100        # Ratio ceiling (100:1) for zip bomb detection
+  # HTTP API pagination cap — requires server restart to take effect
+  api_max_limit: 200
+  # MCP search result cap per source (protocol payload limit)
+  mcp_search_limit_cap: 200
+  # Embedding batch size for vector rebuild
+  vector_batch_size: 100
+
 # Source registry seeds — loaded into the sources table on init
 # Connector sources added by: fp connect install <name>
 source_seeds:

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/footprinter/cli/__init__.py

@@ -133,7 +133,10 @@ def main(argv=None) -> None:
     from footprinter.cli._prompt import PromptCancelled
 
     try:
-        args.func(args)
+        # A handler may signal its exit status by returning an int; None means
+        # success. This complements the raise SystemExit(n) pattern used
+        # elsewhere — those bubble out before the wrapper here ever runs.
+        raise SystemExit(args.func(args) or 0)
     except _ConfigError as e:
         print(str(e), file=_sys.stderr)
         _sys.exit(1)

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/footprinter/cli/_common.py

@@ -16,6 +16,7 @@ from rich.console import Console
 
 from footprinter.db.clients import VALID_STATUSES as VALID_CLIENT_STATUSES
 from footprinter.db.projects import VALID_STATUSES as VALID_PROJECT_STATUSES
+from footprinter.db_base import get_connection
 from footprinter.services import access_service as _access
 from footprinter.services.access_service import (
     resolve_inherit_permission,
@@ -70,17 +71,13 @@ ALLOWED_COLUMNS = frozenset({"name"})
 def connect_db(db_path: Union[str, Path]) -> Optional[sqlite3.Connection]:
     """Open a read/write connection to the Footprinter database.
 
-    Returns None if the database file does not exist. Sets row_factory
-    and busy_timeout so callers don't need to repeat boilerplate.
+    Returns None if the database file does not exist. Delegates to
+    :func:`~footprinter.db_base.get_connection` for PRAGMA setup.
     """
     db_path = Path(db_path)
     if not db_path.exists():
         return None
-    conn = sqlite3.connect(str(db_path), timeout=10)
-    conn.row_factory = sqlite3.Row
-    conn.execute("PRAGMA busy_timeout=5000")
-    conn.execute("PRAGMA foreign_keys=ON")
-    return conn
+    return get_connection(db_path)
 
 
 @contextmanager

{footprinter_cli-1.0.5 → footprinter_cli-1.1.1}/footprinter/cli/_policy_helpers.py

@@ -52,18 +52,24 @@ def confirm_recalculation(conn: sqlite3.Connection, scope: str, *, yes: bool = F
 # ---------------------------------------------------------------------------
 
 
-def recalculate_with_progress(conn: sqlite3.Connection, scope: str) -> dict[str, int]:
+def recalculate_with_progress(
+    conn: sqlite3.Connection, scope: str, *, commit: bool = True,
+) -> dict[str, int]:
     """Recalculate access with a Rich progress bar for large scopes.
 
     If total affected entities <= CONFIRM_THRESHOLD, runs the fast unbatched
-    path and prints a one-line summary. Otherwise shows a Rich progress bar
-    with per-batch updates.
+    path.  Otherwise shows a Rich progress bar with per-batch progress
+    updates.
+
+    When *commit* is False, no commits are issued (including per-batch
+    commits in the batched path) — the caller manages the transaction
+    boundary.
     """
     counts = count_affected_entities(conn, scope)
     total = sum(counts.values())
 
     if total <= CONFIRM_THRESHOLD:
-        return recalculate_access(conn, scope)
+        return recalculate_access(conn, scope, commit=commit)
 
     from rich.progress import Progress
 
@@ -73,6 +79,7 @@ def recalculate_with_progress(conn: sqlite3.Connection, scope: str) -> dict[str,
             conn,
             scope,
             on_batch=lambda n: progress.advance(task, advance=n),
+            commit=commit,
         )
     return stats
 
@@ -102,6 +109,39 @@ def normalize_path(path: str) -> str:
     return normalized
 
 
+# ---------------------------------------------------------------------------
+# Numeric ID resolution helpers
+# ---------------------------------------------------------------------------
+
+
+def resolve_file_id(conn: sqlite3.Connection, file_id: int) -> str | None:
+    """Resolve a numeric file ID to its path, or None on failure."""
+    row = conn.execute(
+        "SELECT path, status FROM files WHERE id = ?", (file_id,),
+    ).fetchone()
+    if not row:
+        console.print(f"[red]File not found:[/red] id={file_id}")
+        return None
+    if row["status"] != "listed":
+        console.print(
+            f"[red]File id={file_id} has status '{row['status']}'.[/red]\n"
+            "  Only listed files are checked."
+        )
+        return None
+    return row["path"]
+
+
+def resolve_folder_id(conn: sqlite3.Connection, folder_id: int) -> str | None:
+    """Resolve a numeric folder ID to its path, or None on failure."""
+    row = conn.execute(
+        "SELECT path FROM folders WHERE id = ?", (folder_id,),
+    ).fetchone()
+    if not row:
+        console.print(f"[red]Folder not found:[/red] id={folder_id}")
+        return None
+    return row["path"]
+
+
 # ---------------------------------------------------------------------------
 # Single-path check helpers
 # ---------------------------------------------------------------------------
@@ -168,7 +208,7 @@ def check_file_path(conn: sqlite3.Connection, path: str, json_output: bool, verb
         console.print(f"\nAccess Check: [bold]{display_path}[/bold]")
         if not found:
             console.print("  [dim]Not found in files or folders — resolving from policy chain[/dim]")
-            console.print("  [dim]Tip: Use --folder for directory aggregate, --project for project ID[/dim]")
+            console.print("  [dim]Tip: Use folder:<path> for a directory aggregate, project:<id> for a project[/dim]")
         console.print()
         console.print(f"  Permission: [bold]{perm_str}[/bold]   (from {perm_src})")
         console.print(f"  Visibility: [bold]{vis_val}[/bold]   (from {vis_src})")
@@ -484,7 +524,150 @@ def check_client(
 
 
 # ---------------------------------------------------------------------------
-# Policy chain / simulation
+# Single-entity check helper (email, chat, visit)
+# ---------------------------------------------------------------------------
+
+_ENTITY_QUERIES: dict[str, tuple[str, str]] = {
+    "email": (
+        "SELECT id, subject, account, project_id, client_id FROM emails WHERE id = ?",
+        "subject",
+    ),
+    "chat": (
+        "SELECT id, title, account, project_id, client_id FROM chats WHERE id = ?",
+        "title",
+    ),
+    "visit": (
+        "SELECT id, title, url FROM visits WHERE id = ?",
+        "title",
+    ),
+}
+
+_SOURCE_TYPE: dict[str, str] = {
+    "email": "emails",
+    "chat": "chats",
+    "visit": "browser",
+}
+
+
+def check_entity(
+    conn: sqlite3.Connection,
+    entity_type: str,
+    entity_id: int,
+    json_output: bool,
+    verbose: bool = False,
+) -> int:
+    """Check resolved access for a single entity (email, chat, or visit) by ID."""
+    from footprinter.permissions import resolve_permission_with_source
+    from footprinter.visibility import resolve_visibility_with_source
+
+    query, name_col = _ENTITY_QUERIES[entity_type]
+    row = conn.execute(query, (entity_id,)).fetchone()
+
+    if not row:
+        console.print(f"[red]{entity_type.title()} not found:[/red] id={entity_id}")
+        return 1
+
+    display_name = row[name_col] or (row["url"] if entity_type == "visit" else f"(no {name_col})")
+
+    perm_val, perm_src = resolve_permission_with_source(conn, entity_type, entity_id)
+    vis_val, vis_src = resolve_visibility_with_source(conn, entity_type, entity_id)
+    perm_str = "allow" if perm_val else "deny"
+
+    chain = build_entity_policy_chain(
+        conn,
+        entity_type,
+        entity_id,
+        project_id=row["project_id"] if "project_id" in row.keys() else None,
+        client_id=row["client_id"] if "client_id" in row.keys() else None,
+        account=row["account"] if "account" in row.keys() else None,
+    )
+
+    if json_output:
+        data = {
+            "entity_type": entity_type,
+            "entity_id": entity_id,
+            "display_name": display_name,
+            "permission": {"resolved": perm_str, "source": perm_src},
+            "visibility": {"resolved": vis_val, "source": vis_src},
+            "chain": chain,
+        }
+        if verbose:
+            data["verbose_note"] = "single-entity output already includes the full policy chain"
+        output_json(data)
+    else:
+        console.print(f"\n{entity_type.title()} Check: [bold]{display_name}[/bold]  (id={entity_id})")
+        console.print()
+        console.print(f"  Permission: [bold]{perm_str}[/bold]   (from {perm_src})")
+        console.print(f"  Visibility: [bold]{vis_val}[/bold]   (from {vis_src})")
+        if chain:
+            console.print()
+            print_policy_chain(chain)
+        if verbose:
+            console.print(
+                "  [dim](--verbose adds no additional detail — single-entity output "
+                "already includes the full policy chain)[/dim]"
+            )
+
+    return 0
+
+
+def _lookup_scope_policy(conn: sqlite3.Connection, scope: str) -> dict:
+    """Look up permission and visibility policy for a single scope string."""
+    perm = conn.execute(
+        "SELECT setting FROM permission_policies WHERE scope = ?", (scope,),
+    ).fetchone()
+    vis = conn.execute(
+        "SELECT setting FROM visibility_policies WHERE scope = ?", (scope,),
+    ).fetchone()
+    return {
+        "scope": scope,
+        "permission": perm["setting"] if perm else None,
+        "visibility": vis["setting"] if vis else None,
+    }
+
+
+def build_entity_policy_chain(
+    conn: sqlite3.Connection,
+    entity_type: str,
+    entity_id: int,
+    project_id: int | None,
+    client_id: int | None,
+    account: str | None,
+) -> list[dict]:
+    """Build diagnostic policy chain for an entity (email/chat/visit)."""
+    from footprinter.permissions import BASELINE_PERMISSION
+    from footprinter.visibility import BASELINE_VISIBILITY
+
+    chain: list[dict] = []
+
+    if entity_type != "visit":
+        chain.append(_lookup_scope_policy(conn, f"{entity_type}:{entity_id}"))
+
+    if project_id is not None:
+        chain.append(_lookup_scope_policy(conn, f"project:{project_id}"))
+
+    if client_id is not None:
+        chain.append(_lookup_scope_policy(conn, f"client:{client_id}"))
+
+    if account is not None:
+        chain.append(_lookup_scope_policy(conn, f"account:{account}"))
+
+    source_type = _SOURCE_TYPE[entity_type]
+    chain.append(_lookup_scope_policy(conn, f"source:{source_type}"))
+
+    chain.append(_lookup_scope_policy(conn, "global"))
+
+    chain.append({
+        "scope": "baseline",
+        "permission": "allow" if BASELINE_PERMISSION else "deny",
+        "visibility": BASELINE_VISIBILITY,
+    })
+
+    return chain
+
+
+# ---------------------------------------------------------------------------
+# Policy chain / simulation (file-path specific)
 # ---------------------------------------------------------------------------
 
 
@@ -503,21 +686,7 @@ def build_policy_chain(
 
     # 1. File-level
     if file_id is not None:
-        perm = conn.execute(
-            "SELECT setting FROM permission_policies WHERE scope = ?",
-            (f"file:{file_id}",),
-        ).fetchone()
-        vis = conn.execute(
-            "SELECT setting FROM visibility_policies WHERE scope = ?",
-            (f"file:{file_id}",),
-        ).fetchone()
-        chain.append(
-            {
-                "scope": f"file:{file_id}",
-                "permission": perm["setting"] if perm else None,
-                "visibility": vis["setting"] if vis else None,
-            }
-        )
+        chain.append(_lookup_scope_policy(conn, f"file:{file_id}"))
 
     # 2. Folder prefix policies (longest first)
     if path:
@@ -550,61 +719,17 @@ def build_policy_chain(
 
     # 3. Project-level
     if project_id is not None:
-        perm = conn.execute(
-            "SELECT setting FROM permission_policies WHERE scope = ?",
-            (f"project:{project_id}",),
-        ).fetchone()
-        vis = conn.execute(
-            "SELECT setting FROM visibility_policies WHERE scope = ?",
-            (f"project:{project_id}",),
-        ).fetchone()
-        chain.append(
-            {
-                "scope": f"project:{project_id}",
-                "permission": perm["setting"] if perm else None,
-                "visibility": vis["setting"] if vis else None,
-            }
-        )
+        chain.append(_lookup_scope_policy(conn, f"project:{project_id}"))
 
     # 4. Client-level
     if client_id is not None:
-        perm = conn.execute(
-            "SELECT setting FROM permission_policies WHERE scope = ?",
-            (f"client:{client_id}",),
-        ).fetchone()
-        vis = conn.execute(
-            "SELECT setting FROM visibility_policies WHERE scope = ?",
-            (f"client:{client_id}",),
-        ).fetchone()
-        chain.append(
-            {
-                "scope": f"client:{client_id}",
-                "permission": perm["setting"] if perm else None,
-                "visibility": vis["setting"] if vis else None,
-            }
-        )
+        chain.append(_lookup_scope_policy(conn, f"client:{client_id}"))
 
     # 5. Source: files
-    src_perm = conn.execute("SELECT setting FROM permission_policies WHERE scope = 'source:files'").fetchone()
-    src_vis = conn.execute("SELECT setting FROM visibility_policies WHERE scope = 'source:files'").fetchone()
-    chain.append(
-        {
-            "scope": "source:files",
-            "permission": src_perm["setting"] if src_perm else None,
-            "visibility": src_vis["setting"] if src_vis else None,
-        }
-    )
+    chain.append(_lookup_scope_policy(conn, "source:files"))
 
     # 6. Global
-    global_perm = conn.execute("SELECT setting FROM permission_policies WHERE scope = 'global'").fetchone()
-    global_vis = conn.execute("SELECT setting FROM visibility_policies WHERE scope = 'global'").fetchone()
-    chain.append(
-        {
-            "scope": "global",
-            "permission": global_perm["setting"] if global_perm else None,
-            "visibility": global_vis["setting"] if global_vis else None,
-        }
-    )
+    chain.append(_lookup_scope_policy(conn, "global"))
 
     # 7. Baseline
     chain.append(