@inneranimalmedia/agentsam-sdk 1.7.0 → 1.9.0

package/python/agentsam_sdk/repository/inventory.py

@@ -0,0 +1,351 @@
+"""agentsam_sdk.repository.inventory — repo file counts + sizes by category.
+
+Port of the battle-tested scanner (formerly scripts/repo-size-inventory.py on
+main). Read-only. No secrets, no D1.
+
+JSON is jq-friendly. Examples (host `jq` required for the pipe examples):
+
+  agentsam repository inventory --repo-root .. --format json \\
+    | jq '.data.categories[] | select(.id==\"docs\")'
+
+  agentsam repository inventory --repo-root .. --output-dir /tmp/inv --format json
+  jq '.totals' /tmp/inv/repository-inventory.json
+"""
+from __future__ import annotations
+
+import json
+import os
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult, write_receipt, start_timer
+
+TOOL_NAME = "repository.inventory"
+
+DEFAULT_SKIP_DIR_NAMES = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".wrangler",
+        "dist",
+        "coverage",
+        "__pycache__",
+        ".venv",
+        "venv",
+        ".venv_agentsam",
+        ".turbo",
+        ".next",
+        ".cache",
+        ".scratch",
+        "build",
+    }
+)
+
+# First path segment → category id
+CATEGORY_RULES: list[tuple[str, tuple[str, ...]]] = [
+    ("worker_src", ("src",)),
+    ("dashboard", ("dashboard",)),
+    ("migrations", ("migrations",)),
+    ("docs", ("docs",)),
+    ("plans", ("plans",)),
+    ("scripts", ("scripts",)),
+    ("tests", ("tests", "test", "e2e")),
+    ("services", ("services",)),
+    ("supabase", ("supabase",)),
+    ("product_manifests", ("product-manifests",)),
+    ("static_assets", ("static", "public", "assets")),
+    ("artifacts", ("artifacts", ".scratch")),
+    ("vendor", ("vendor",)),
+    ("tools", ("tools",)),
+    ("local_venvs", (".venv_agentsam", ".venv", "venv")),
+    ("cms", ("cms-editor", "studio-cms")),
+    ("config_cursor", (".cursor", ".agents", ".claude", ".codex", ".githooks")),
+    ("ci", (".github",)),
+    ("agentsam_sdk_pkg", ("agentsam-sdk", "agentsam_sdk")),
+]
+
+CATEGORY_LABELS = {
+    "worker_src": "Worker src/",
+    "dashboard": "Dashboard SPA",
+    "migrations": "D1 migrations",
+    "docs": "Docs",
+    "plans": "Plans",
+    "scripts": "Scripts",
+    "tests": "Tests",
+    "services": "Services / satellites",
+    "supabase": "Supabase",
+    "product_manifests": "Product manifests",
+    "static_assets": "Static / public assets",
+    "artifacts": "Artifacts / scratch dumps",
+    "vendor": "Vendor copies",
+    "tools": "Tools / offline utilities",
+    "local_venvs": "Local Python venvs",
+    "cms": "CMS editor packages",
+    "config_cursor": "Cursor / agent config",
+    "ci": "CI (.github)",
+    "agentsam_sdk_pkg": "agentsam-sdk package",
+    "root_misc": "Repo root files",
+    "other": "Other paths",
+}
+
+
+@dataclass
+class Bucket:
+    id: str
+    label: str
+    file_count: int = 0
+    bytes: int = 0
+    top_files: list[dict] = field(default_factory=list)
+
+    def add(self, size: int) -> None:
+        self.file_count += 1
+        self.bytes += size
+
+
+def human_bytes(n: int) -> str:
+    if n < 1024:
+        return f"{n} B"
+    units = ["KiB", "MiB", "GiB", "TiB"]
+    x = float(n)
+    for u in units:
+        x /= 1024.0
+        if x < 1024.0:
+            return f"{x:.2f} {u}"
+    return f"{x:.2f} PiB"
+
+
+def categorize(rel: Path) -> str:
+    parts = rel.parts
+    if not parts:
+        return "root_misc"
+    first = parts[0]
+    for cat_id, prefixes in CATEGORY_RULES:
+        if first in prefixes:
+            return cat_id
+    if len(parts) == 1:
+        return "root_misc"
+    return "other"
+
+
+def should_skip_dir(name: str, skip_names: frozenset[str]) -> bool:
+    return name in skip_names or name.endswith(".bak")
+
+
+def iter_files(
+    root: Path,
+    skip_names: frozenset[str],
+    follow_symlinks: bool,
+) -> Iterable[tuple[Path, int]]:
+    for dirpath, dirnames, filenames in os.walk(
+        root, topdown=True, followlinks=follow_symlinks
+    ):
+        dirnames[:] = [d for d in dirnames if not should_skip_dir(d, skip_names)]
+        base = Path(dirpath)
+        for name in filenames:
+            if name.endswith(".bak") or name.endswith(".pyc"):
+                continue
+            path = base / name
+            try:
+                if path.is_symlink() and not follow_symlinks:
+                    continue
+                st = path.stat()
+            except (OSError, ValueError):
+                continue
+            if not path.is_file():
+                continue
+            yield path, int(st.st_size)
+
+
+def scan(
+    root: Path,
+    *,
+    skip_names: frozenset[str],
+    top_n: int,
+    min_bytes: int,
+    follow_symlinks: bool,
+    by_ext: bool,
+) -> dict[str, Any]:
+    buckets: dict[str, Bucket] = {}
+    ext_counts: Counter = Counter()
+    ext_bytes: dict[str, int] = defaultdict(int)
+    top_level: Counter = Counter()
+    largest: list[tuple[int, str, str]] = []
+
+    def bucket(cat_id: str) -> Bucket:
+        if cat_id not in buckets:
+            buckets[cat_id] = Bucket(
+                id=cat_id, label=CATEGORY_LABELS.get(cat_id, cat_id)
+            )
+        return buckets[cat_id]
+
+    file_total = 0
+    byte_total = 0
+
+    for path, size in iter_files(root, skip_names, follow_symlinks):
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            continue
+        cat = categorize(rel)
+        bucket(cat).add(size)
+        file_total += 1
+        byte_total += size
+
+        top = rel.parts[0] if rel.parts else "."
+        top_level[top] += 1
+
+        ext = path.suffix.lower() or "(none)"
+        ext_counts[ext] += 1
+        if by_ext:
+            ext_bytes[ext] += size
+
+        if size >= min_bytes:
+            largest.append((size, str(rel).replace("\\", "/"), cat))
+
+    largest.sort(key=lambda t: t[0], reverse=True)
+    top_files = [
+        {"path": p, "bytes": s, "human": human_bytes(s), "category": c}
+        for s, p, c in largest[: max(0, top_n)]
+    ]
+
+    cats = sorted(buckets.values(), key=lambda b: b.bytes, reverse=True)
+    categories = [
+        {
+            "id": b.id,
+            "label": b.label,
+            "file_count": b.file_count,
+            "bytes": b.bytes,
+            "human": human_bytes(b.bytes),
+            "pct_bytes": round(100.0 * b.bytes / byte_total, 2) if byte_total else 0.0,
+        }
+        for b in cats
+    ]
+
+    out: dict[str, Any] = {
+        "ok": True,
+        "tool": TOOL_NAME,
+        "repo_root": str(root),
+        "file_total": file_total,
+        "totals": {
+            "file_count": file_total,
+            "bytes": byte_total,
+            "human": human_bytes(byte_total),
+            "categories": len(categories),
+        },
+        "skipped_dir_names": sorted(skip_names),
+        "categories": categories,
+        "largest_files": top_files,
+        # Backward-compatible stub fields (counts only)
+        "by_extension": dict(ext_counts.most_common(40)),
+        "by_top_level_dir": dict(top_level.most_common(40)),
+    }
+    if by_ext:
+        out["by_extension_detail"] = [
+            {
+                "ext": k,
+                "file_count": ext_counts[k],
+                "bytes": ext_bytes[k],
+                "human": human_bytes(ext_bytes[k]),
+            }
+            for k in sorted(ext_bytes, key=lambda e: ext_bytes[e], reverse=True)
+        ]
+    return out
+
+
+def _markdown(report: dict[str, Any]) -> str:
+    lines = [
+        "# Repository inventory",
+        "",
+        f"- **repo_root:** `{report['repo_root']}`",
+        f"- **files:** {report['file_total']:,}",
+        f"- **bytes:** {report['totals']['human']} ({report['totals']['bytes']:,})",
+        "",
+        "## By category",
+        "",
+        "| Category | Files | Size | % |",
+        "|---|---:|---:|---:|",
+    ]
+    for c in report["categories"]:
+        lines.append(
+            f"| {c['label']} | {c['file_count']:,} | {c['human']} | {c['pct_bytes']:.1f}% |"
+        )
+    if report.get("largest_files"):
+        lines += ["", "## Largest files", ""]
+        for f in report["largest_files"]:
+            lines.append(f"- `{f['path']}` — {f['human']} (`{f['category']}`)")
+    lines += ["", "## By extension (top)", "", "| Ext | Count |", "|-----|-------|"]
+    for e, c in list(report.get("by_extension", {}).items())[:30]:
+        lines.append(f"| `{e}` | {c} |")
+    return "\n".join(lines) + "\n"
+
+
+def run(tool_input: ToolInput) -> ToolResult:
+    started = start_timer()
+    p = tool_input.params
+    repo_root = Path(p.get("repo_root", ".")).expanduser().resolve()
+    output_dir = tool_input.output_path()
+
+    if not repo_root.exists():
+        result = ToolResult(
+            ok=False,
+            tool=TOOL_NAME,
+            mode=tool_input.mode,
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary=f"repo_root does not exist: {repo_root}",
+            error="repo_root_not_found",
+        )
+        write_receipt(result, output_dir)
+        return result
+
+    skip = set(p.get("skip_dir_names") or DEFAULT_SKIP_DIR_NAMES)
+    if p.get("include_node_modules"):
+        skip.discard("node_modules")
+    if p.get("include_venvs"):
+        skip.discard(".venv")
+        skip.discard("venv")
+        skip.discard(".venv_agentsam")
+    if p.get("include_git"):
+        skip.discard(".git")
+    if p.get("include_dist"):
+        skip.discard("dist")
+        skip.discard(".wrangler")
+        skip.discard("build")
+
+    report = scan(
+        repo_root,
+        skip_names=frozenset(skip),
+        top_n=int(p.get("top", 20)),
+        min_bytes=int(p.get("min_bytes", 0)),
+        follow_symlinks=bool(p.get("follow_symlinks", False)),
+        by_ext=bool(p.get("by_ext", True)),
+    )
+
+    artifacts: list[str] = []
+    if output_dir:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        json_path = output_dir / "repository-inventory.json"
+        md_path = output_dir / "repository-inventory.md"
+        json_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+        md_path.write_text(_markdown(report), encoding="utf-8")
+        artifacts = [str(json_path), str(md_path)]
+
+    result = ToolResult(
+        ok=True,
+        tool=TOOL_NAME,
+        mode=tool_input.mode,
+        request_id=tool_input.request_id,
+        started_at=started,
+        finished_at=start_timer(),
+        summary=(
+            f"{report['file_total']} files · {report['totals']['human']} "
+            f"under {repo_root}"
+        ),
+        data=report,
+        artifacts=artifacts,
+    )
+    write_receipt(result, output_dir)
+    return result

package/python/agentsam_sdk/repository/scan_bloat.py

@@ -0,0 +1,173 @@
+"""agentsam_sdk.repository.scan_bloat — per-file source bloat inventory.
+
+Companion to repository.inventory (category rollups). This tool lists the
+largest runtime source files under a root (default: cwd) with size / lines /
+est. tokens — for refactor targeting and agent context budgeting.
+
+Read-only. No secrets, no D1.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult, write_receipt, start_timer
+
+TOOL_NAME = "repository.scan_bloat"
+
+DEFAULT_EXTS = frozenset({".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"})
+DEFAULT_EXCLUDE_DIRS = frozenset(
+    {
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        ".wrangler",
+        ".next",
+        ".turbo",
+        "coverage",
+        ".cache",
+        "out",
+        ".vercel",
+        "__pycache__",
+        ".venv",
+        "venv",
+    }
+)
+CHARS_PER_TOKEN = 3.7
+
+
+def scan(
+    root: str | Path,
+    *,
+    exts: set[str] | frozenset[str] = DEFAULT_EXTS,
+    exclude_dirs: set[str] | frozenset[str] = DEFAULT_EXCLUDE_DIRS,
+) -> list[dict[str, Any]]:
+    """Walk root and return file stats sorted by size_bytes desc."""
+    root_path = Path(root).resolve()
+    results: list[dict[str, Any]] = []
+    if root_path.is_file():
+        # Allow a single-file root for smoke tests
+        if root_path.suffix in exts:
+            results.append(_stat_file(root_path, root_path.parent))
+        return results
+
+    for dirpath, dirnames, filenames in os.walk(root_path):
+        dirnames[:] = [
+            d for d in dirnames if d not in exclude_dirs and not d.startswith(".")
+        ]
+        for fname in filenames:
+            ext = os.path.splitext(fname)[1]
+            if ext not in exts:
+                continue
+            fpath = Path(dirpath) / fname
+            try:
+                results.append(_stat_file(fpath, root_path))
+            except (OSError, UnicodeDecodeError):
+                continue
+    results.sort(key=lambda r: r["size_bytes"], reverse=True)
+    return results
+
+
+def _stat_file(fpath: Path, root: Path) -> dict[str, Any]:
+    size_bytes = fpath.stat().st_size
+    content = fpath.read_text(encoding="utf-8", errors="replace")
+    line_count = content.count("\n") + (1 if content else 0)
+    return {
+        "path": str(fpath.relative_to(root)),
+        "size_bytes": size_bytes,
+        "size_kb": round(size_bytes / 1024, 1),
+        "lines": line_count,
+        "est_tokens": round(size_bytes / CHARS_PER_TOKEN),
+        "bytes_per_line": round(size_bytes / line_count, 1) if line_count else 0,
+    }
+
+
+def human_table(files: list[dict[str, Any]], *, scanned: int, total_kb: float, total_tokens: int) -> str:
+    """Plain-text table for terminal / markdown CLI mode."""
+    if not files:
+        return "No files matched.\n"
+    path_w = min(max(len(r["path"]) for r in files), 70)
+    header = f"{'SIZE':>9}  {'LINES':>7}  {'~TOKENS':>8}  {'B/LINE':>7}  PATH"
+    lines = [header, "-" * len(header)]
+    for r in files:
+        path = r["path"] if len(r["path"]) <= path_w else "…" + r["path"][-(path_w - 1) :]
+        lines.append(
+            f"{r['size_kb']:>8.1f}KB  {r['lines']:>7}  {r['est_tokens']:>8}  "
+            f"{r['bytes_per_line']:>7}  {path}"
+        )
+    lines.append("-" * len(header))
+    lines.append(
+        f"Scanned {scanned} files, {total_kb:.1f}KB total, ~{total_tokens:,} est. tokens"
+    )
+    return "\n".join(lines) + "\n"
+
+
+def run(tool_input: ToolInput) -> ToolResult:
+    started = start_timer()
+    p = tool_input.params
+    root = str(p.get("root") or p.get("repo_root") or ".")
+    top = max(1, int(p.get("top", 30)))
+    min_kb = float(p.get("min_kb", 0) or 0)
+    ext_raw = p.get("ext") or ",".join(sorted(DEFAULT_EXTS))
+    exts = {
+        e if str(e).startswith(".") else f".{e}"
+        for e in str(ext_raw).split(",")
+        if str(e).strip()
+    }
+    exclude = set(DEFAULT_EXCLUDE_DIRS)
+    extra = p.get("exclude") or ""
+    if extra:
+        exclude |= {d.strip() for d in str(extra).split(",") if d.strip()}
+
+    try:
+        all_files = scan(root, exts=exts, exclude_dirs=exclude)
+        filtered = [r for r in all_files if r["size_kb"] >= min_kb][:top]
+        total_kb = round(sum(r["size_kb"] for r in all_files), 1)
+        total_tokens = sum(r["est_tokens"] for r in all_files)
+        data = {
+            "ok": True,
+            "root": str(Path(root).resolve()),
+            "file_count": len(all_files),
+            "total_kb": total_kb,
+            "total_est_tokens": total_tokens,
+            "files": filtered,
+        }
+        artifacts: list[str] = []
+        output_dir = tool_input.output_path()
+        if output_dir:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            out_json = output_dir / "scan-bloat.json"
+            out_json.write_text(json.dumps(data, indent=2), encoding="utf-8")
+            artifacts.append(str(out_json))
+
+        result = ToolResult(
+            ok=True,
+            tool=TOOL_NAME,
+            mode=tool_input.mode or "read-only",
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary=(
+                f"Scanned {len(all_files)} files, {total_kb}KB total, "
+                f"top {len(filtered)} ≥{min_kb}KB."
+            ),
+            data=data,
+            artifacts=artifacts,
+        )
+    except Exception as e:  # noqa: BLE001 — surfaced in ToolResult
+        result = ToolResult(
+            ok=False,
+            tool=TOOL_NAME,
+            mode=tool_input.mode or "read-only",
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary="scan_bloat failed",
+            error=str(e)[:500],
+        )
+
+    write_receipt(result, tool_input.output_path())
+    return result

package/python/agentsam_sdk/runtime/contract.py

@@ -0,0 +1,105 @@
+"""Shared tool contract: ToolInput / ToolResult / receipts.
+
+HARD LAW (see inneranimalmedia AGENTS.md): never hardcode identity, repo,
+workspace, or tenant values anywhere in this package -- not in shipped code,
+patches, examples, or fallback defaults. All identity-shaped values
+(database names, account ids, wrangler config paths) must come from the
+caller (CLI flag) or the environment. Generic placeholders only in examples
+(e.g. "owner/repo-name", "$D1_DATABASE_NAME").
+
+Every tool module in agentsam_sdk exposes a `run(tool_input: ToolInput) ->
+ToolResult` function (or is wrapped to look like one from cli.py). Modes are
+read-only by default -- any tool that can write must accept an explicit
+`write=True` and should say so loudly in its ToolResult.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Any, Optional
+
+
+HARD_LAW_NOTE = (
+    "Never hardcode identity/repo/workspace/tenant values. Use env vars or "
+    "explicit CLI args; fall back to generic placeholders only in docs."
+)
+
+
+@dataclass
+class ToolInput:
+    """Normalized input every agentsam_sdk tool accepts.
+
+    mode: tool-specific sub-mode (e.g. "quick" | "full" for d1_bloat)
+    params: tool-specific keyword args
+    output_dir: where json/markdown output + receipt get written
+    write: True only for tools that mutate state; default False (read-only)
+    """
+
+    mode: str = "default"
+    params: dict[str, Any] = field(default_factory=dict)
+    output_dir: Optional[str] = None
+    write: bool = False
+    request_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    def output_path(self) -> Optional[Path]:
+        return Path(self.output_dir) if self.output_dir else None
+
+
+@dataclass
+class ToolResult:
+    """Normalized output every agentsam_sdk tool returns."""
+
+    ok: bool
+    tool: str
+    mode: str
+    request_id: str
+    started_at: float
+    finished_at: float
+    summary: str
+    data: dict[str, Any] = field(default_factory=dict)
+    artifacts: list[str] = field(default_factory=list)
+    error: Optional[str] = None
+
+    @property
+    def duration_s(self) -> float:
+        return round(self.finished_at - self.started_at, 3)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["duration_s"] = self.duration_s
+        return d
+
+
+def new_receipt_path(output_dir: Path, tool: str, request_id: str) -> Path:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    return output_dir / f"receipt-{tool}-{request_id}.json"
+
+
+def write_receipt(result: ToolResult, output_dir: Optional[Path]) -> Optional[str]:
+    """Write a receipt (contract rule: every tool call gets one). Returns path or None."""
+    if output_dir is None:
+        return None
+    path = new_receipt_path(output_dir, result.tool, result.request_id)
+    payload = result.to_dict()
+    payload["written_at_unixepoch"] = int(time.time())
+    path.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")
+    return str(path)
+
+
+def require_env(*names: str) -> dict[str, str]:
+    """Fetch required env vars; raise with a clear message (never invent values)."""
+    missing = [n for n in names if not os.environ.get(n)]
+    if missing:
+        raise RuntimeError(
+            f"Missing required env var(s): {', '.join(missing)}. "
+            f"{HARD_LAW_NOTE}"
+        )
+    return {n: os.environ[n] for n in names}
+
+
+def start_timer() -> float:
+    return time.time()

package/python/docs/gaps.md

@@ -0,0 +1,63 @@
+# agentsam-sdk — D1 audit port: status
+
+Tracks the file list from `plans/active/CLAUDE-AGENTSAM-SDK-D1-AUDIT-PORT-HANDOFF-2026-08.md`.
+
+Context: `feature/agentsam-sdk-scaffold` had no `agentsam-sdk/` package at all
+when this pass started (no pyproject, no CLI, no docs/gaps.md) -- the
+handoff doc assumed a scaffold that hadn't actually landed. This pass builds
+the minimal scaffold from zero, then ports P0.
+
+Host tools (jq, wrangler, Python): see `docs/tooling.md` + `scripts/check-host-tooling.sh`.
+
+## P0 — whole-D1 / agentsam walkers
+
+| Legacy script | SDK target | Status |
+|---|---|---|
+| `scripts/d1_bloat_audit.py` | `agentsam_sdk.data.d1_bloat` | **Ported + aligned (2026-08).** Database-scoped: `--quick` = all tables COUNT(*); `--full` = text LENGTH + briefing. Removed `QUICK_TABLE_RE` / `SKIP_COL_RE` / `--count-only`. Deferred: `--email`/Resend (CLI/ops layer). |
+| `scripts/run-d1-bloat-audit.sh` | `agentsam data d1-bloat` via CLI | **Shimmed**, see below — legacy `npm run audit:d1-bloat*` scripts still work unchanged. GCP-fallback/nohup wrapper behavior not reimplemented in the SDK itself (that's operational, not tool logic); still available via the legacy `.sh`. |
+| `scripts/walk_agentsam_tables.py` | `agentsam_sdk.data.agentsam_walk` | **Ported, condensed.** Schema/indexes/FKs/row-count/freshness/capability-grouping all present. Not byte-for-byte: duplicate-table detection and some staleness heuristics from the 801-line original are deferred. |
+| `scripts/d1_schema_audit.py` | folded into `agentsam_walk` (schema slice) | **Partially folded.** The capability-grouping + schema dump is covered by `agentsam_walk`. NOT ported: the per-feature markdown chunking into 14 separate `db/agentsam-*.md` files, and the curated `TABLE_META` purpose annotations (760+ lines of hand-written table descriptions) -- that's product documentation content, not audit logic, and belongs in a follow-up pass, not this one. Also note: the legacy script hardcoded a D1 database id as a fallback default (`D1_DATABASE_ID = os.environ.get("D1_DATABASE_ID", "cf87b717-...")`) -- **do not carry that forward**; the new adapter has no such fallback (HARD LAW). |
+
+## P1 — agentsam quality / wiring (not started this pass)
+
+`audit_agentsam_full.py`, `agentsam_db_deep_audit.py`, `audit_agentsam_tables.py`,
+`audit_agentsam_schema.py`, `audit_agentsam_table_usage.py`,
+`agentsam_cms_d1_table_audit.py`, `agentsam_audit.py` — all deferred. Reason:
+scope boundary for this pass was P0 only, per the handoff doc's file list.
+
+## P2 — repository / history / readiness
+
+| Legacy script | SDK target | Status |
+|---|---|---|
+| `scripts/repo-size-inventory.py` (main) / `repo_inventory.py` | `agentsam_sdk.repository.inventory` | **Ported** (category + byte sizes + largest files + extension rollups; jq-friendly JSON; stub fields `by_extension` / `by_top_level_dir` retained). |
+| `tools/scan_bloat.py` (IAM shim) | `agentsam_sdk.repository.scan_bloat` | **Ported.** Per-file KB/lines/est. tokens; CLI `agentsam repository scan-bloat`. D1: `agentsam_scripts.slug=scan_bloat` (not `agentsam_commands`). |
+| `repo_cleanup_classify.py`, `repo-cleanup.py` | `agentsam_sdk.repository.cleanup_plan` | **Not started** |
+| `audit_dead_code.py` | `agentsam_sdk.repository.dead_paths` | **Not started** |
+| `audit_hardcoded_identity.py`, `guard-no-hardcoded-identity.sh` | `agentsam_sdk.readiness.boundaries` | **Not started** |
+| `audit_migration_chain.py` | `agentsam_sdk.history.timeline` / `.supersession` | **Not started** |
+| leftover `d1_*_audit.py` | `agentsam_sdk.data.d1` adapters | **Not started** |
+
+## Out of scope (per handoff doc, unchanged)
+
+`scripts/embed_*`, `scripts/ingest_*` (product Vectorize/pgvector pipelines);
+dashboard/Worker `client_fs`/ExecOS path-propose lane; inventing new D1
+tables for audit output (output stays json+markdown under `--output-dir`,
+R2 later if wanted).
+
+## Contract compliance
+
+- [x] `runtime/contract.py`: `ToolInput`/`ToolResult` + receipt, every tool call writes one.
+- [x] Read-only default; `ToolInput.write` exists but nothing in this pass sets it True — no silent production writes.
+- [x] D1 access only via `data/d1_adapter.py` (wraps `wrangler d1 execute`); no other module shells out to wrangler or hits the CF API directly.
+- [x] No hardcoded `au_*`/`ws_*`/`tenant_*`/database-id values anywhere — `D1Adapter.from_env` raises rather than guessing.
+- [x] Output: json + markdown from `d1_bloat`, `agentsam_walk`, and `repository.inventory`. No other formats claimed.
+- [x] Tests use fixtures/pure functions only — `python3 -m unittest discover -s tests` needs no live D1 or network.
+- [x] Receipts use `written_at_unixepoch` (unixepoch integer per AGENTS.md); tool-level timestamps otherwise use `time.time()` floats for duration math, not stored as durable rows.
+- [x] `scripts/run-d1-bloat-audit.sh` untouched and still works (legacy path preserved) — see shim note above.
+- [x] Host tooling documented: `docs/tooling.md` (jq + wrangler + env); `scripts/check-host-tooling.sh`.
+
+## Known limitations to fix before this is "done" for P0
+
+1. `agentsam_walk` is a condensed reimplementation, not byte-identical to the 801-line original — needs a side-by-side diff review against real D1 output before calling P0 fully closed.
+2. No live-D1 smoke test has been run yet in this pass (would need `AGENTSAM_D1_DB_NAME` + Cloudflare creds on the operator machine) — see README "D1 audits" section for the command to run one.
+3. `d1_schema_audit.py`'s curated `TABLE_META` prose (table-by-table purpose descriptions) is real, hand-maintained documentation value that this port does NOT carry over. Flagging so it isn't silently lost.