alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/adapters/household/workshop_tools/traits.py

@@ -0,0 +1,95 @@
+"""Workshop-tools trait band emitters (Eco-12).
+
+Trait floor (spec §3):
+
+* ``workshop_steward_active`` (boolean band)
+* ``focus_block_depth`` (banded: ``{shallow, moderate, deep, deeply-focused}``)
+* ``craft_breadth_band`` (banded: ``{single-tool, narrow-toolkit, broad-toolkit, wide-bench}``)
+
+Clause-4 banlist enforced at emit-time (spec §4):
+
+* ``workshop-affect``
+* ``craft-burnout``
+* ``focus-fatigue``
+* ``production-pressure``
+* ``flow-state-inference``
+* ``classroom-workshop-suitability``
+
+Any caller asking the trait emitter for one of these kinds is refused
+with :class:`BannedTraitKindError` before any persisted band is touched.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "CLAUSE_4_BANLIST",
+    "BannedTraitKindError",
+    "CraftBreadthBand",
+    "FocusBlockBand",
+    "WorkshopToolsTraits",
+    "WorkshopToolsTraitEmission",
+]
+
+logger = logging.getLogger("alter_runtime.adapters.household.workshop_tools.traits")
+
+#: Hard-coded refusal set per spec §4 + stub spec.  Frozenset so it
+#: cannot be mutated at runtime.
+CLAUSE_4_BANLIST: frozenset[str] = frozenset(
+    {
+        "workshop-affect",
+        "craft-burnout",
+        "focus-fatigue",
+        "production-pressure",
+        "flow-state-inference",
+        "classroom-workshop-suitability",
+    }
+)
+
+FocusBlockBand = Literal["shallow", "moderate", "deep", "deeply-focused"]
+CraftBreadthBand = Literal["single-tool", "narrow-toolkit", "broad-toolkit", "wide-bench"]
+
+
+class BannedTraitKindError(RuntimeError):
+    """Raised when a caller requests a Clause-4-banned trait kind."""
+
+
+class WorkshopToolsTraitEmission(BaseModel):
+    """One trait-band emission ready for the egress producer."""
+
+    kind: str = Field(description="Trait kind, e.g. 'focus_block_depth'")
+    band: str = Field(description="The banded label (never numeric)")
+    provenance: str = Field(default="passive_local_sensor")
+    stream: str = Field(default="workshop_tool")
+
+
+class WorkshopToolsTraits:
+    """Trait emitter with Clause-4 banlist enforcement."""
+
+    def emit(self, kind: str, band: str) -> WorkshopToolsTraitEmission:
+        """Emit a banded trait, refusing Clause-4-banned kinds outright."""
+        self._refuse_if_banned(kind)
+        # TODO(clause-3-identity-income): return/x402 hook attaches here per
+        #   D-PROV-1 + clause-3 ratification.  Each emission upward is the
+        #   point at which Identity-Income return-flow is metered.  Hook
+        #   implementation lives outside this scaffold pass.
+        return WorkshopToolsTraitEmission(kind=kind, band=band)
+
+    def emit_focus_block_depth(self, band: FocusBlockBand) -> WorkshopToolsTraitEmission:
+        return self.emit("focus_block_depth", band)
+
+    def emit_craft_breadth_band(self, band: CraftBreadthBand) -> WorkshopToolsTraitEmission:
+        return self.emit("craft_breadth_band", band)
+
+    def emit_workshop_steward_active(self, active: bool) -> WorkshopToolsTraitEmission:
+        return self.emit("workshop_steward_active", "active" if active else "inactive")
+
+    @staticmethod
+    def _refuse_if_banned(kind: str) -> None:
+        if kind in CLAUSE_4_BANLIST:
+            logger.warning("workshop_tools refusing Clause-4-banned trait kind=%s", kind)
+            raise BannedTraitKindError(f"trait kind {kind!r} is Clause-4 banned for workshop_tools")

alter_runtime/adapters/worktree_watcher.py

@@ -0,0 +1,378 @@
+"""WorktreeWatcher - ambient working-tree fs-watch for the Weave coordination plane.
+
+D-WEAVE-VC-2 §8 item 1 (b): plain-editor save tap. Observes one or more repo
+working trees and publishes ``local.signal`` events of kind ``"worktree_edit"``
+on every file save detected by watchdog. This covers non-CC editors (vim, vscode,
+etc.) as a coarse-grained second producer for the weave-intent stream.
+
+Signals
+-------
+
+* ``kind = "worktree_edit"`` - a working-tree file was saved. Payload::
+
+      {
+          "repo":      "/abs/path/to/repo",
+          "file_path": "/abs/path/to/repo/src/foo.py",
+          "rel_path":  "src/foo.py",
+          "ts":        "2026-05-21T12:34:56.789012+00:00",
+      }
+
+Published on the ``local.signal`` topic. ``WeaveIntentWriter`` subscribes and
+projects the event into ``weave-intent.jsonl`` as a coarse ``worktree_edit``
+record (D-WEAVE-VC-2 §3 degradation path — "dangling edge").
+
+Design notes
+------------
+
+* **Whole-tree watcher is MORE flood-exposed than GitWatcher.** The same
+  read-event filter from ``git_watcher.py`` is mandatory here and is applied
+  in every dispatch path — dropping ``FileOpenedEvent`` + ``FileClosedNoWriteEvent``
+  before they ever reach the asyncio loop.
+* **Debounce per path.** Within a 200 ms window, multiple watchdog events for
+  the same file path emit only one bus event. Each repo tracks a ``dict[str, float]``
+  of path → last-emit-time.
+* **gitignore + symlink guards.** Reuses the same patterns from GitWatcher:
+  refuse to watch a repo where ``.git`` is a symlink; skip symlinked files;
+  honour ``.gitignore`` by filtering against a cached ignore spec on each event.
+* **Thread boundary.** watchdog callbacks run on the observer's own thread.
+  Marshalled onto the asyncio loop via ``loop.call_soon_threadsafe`` before
+  publishing — the bus is not thread-safe.
+* **Autodetect CWD.** When ``repo_paths`` is empty and the CWD is a git repo,
+  the adapter watches the CWD. Same convention as GitWatcher.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from alter_runtime.config import DaemonConfig
+from alter_runtime.daemon import Component
+from alter_runtime.subscribers.bus import EventBus
+
+__all__ = ["WorktreeWatcher"]
+
+logger = logging.getLogger("alter_runtime.adapters.worktree_watcher")
+
+EGRESS_TOPIC: str = "local.signal"
+
+#: Debounce window in seconds — events within this window for the same path
+#: are collapsed to one emission.
+DEBOUNCE_SECONDS: float = 0.2
+
+#: Maximum number of paths tracked in the per-repo debounce dict. When
+#: exceeded, the oldest half is evicted to prevent unbounded growth on
+#: very active repos (monorepo with hundreds of simultaneous writes).
+MAX_DEBOUNCE_PATHS: int = 2048
+
+
+@dataclass
+class _WatchedRepo:
+    """Bookkeeping for one watched repository."""
+
+    path: Path
+    git_dir: Path
+    observer: Any | None = None
+    #: path string → last emit timestamp (monotonic)
+    _debounce: dict[str, float] = field(default_factory=dict)
+    #: Cached gitignore spec (pathspec.PathSpec | None). Populated lazily.
+    _ignore_spec: Any | None = None
+    _ignore_loaded: bool = False
+
+
+class WorktreeWatcher(Component):
+    """Watches working trees and publishes worktree_edit signals.
+
+    Parameters
+    ----------
+    config:
+        Loaded :class:`DaemonConfig`.
+    bus:
+        Shared :class:`EventBus` — signals are published on ``local.signal``.
+    repo_paths:
+        Explicit list of repository roots to watch. If empty, autodetects
+        from CWD (same convention as GitWatcher).
+    debounce_seconds:
+        Override the per-path debounce window (default 200 ms).
+    """
+
+    name = "worktree_watcher"
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        bus: EventBus,
+        repo_paths: list[Path] | None = None,
+        debounce_seconds: float = DEBOUNCE_SECONDS,
+    ) -> None:
+        self._config = config
+        self._bus = bus
+        self._explicit_paths = repo_paths
+        self._debounce_seconds = debounce_seconds
+        self._stop_event = asyncio.Event()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._repos: list[_WatchedRepo] = []
+
+    # ------------------------------------------------------------------
+    # Component lifecycle
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        self._loop = asyncio.get_running_loop()
+        repos = self._resolve_repos()
+        if not repos:
+            logger.info("worktree_watcher: no repositories to watch — idle")
+            await self._stop_event.wait()
+            return
+
+        try:
+            from watchdog.observers import Observer  # noqa: F401
+        except ImportError:
+            logger.warning("watchdog not installed — worktree_watcher disabled")
+            await self._stop_event.wait()
+            return
+
+        from watchdog.observers import Observer
+
+        for repo in repos:
+            observer = Observer()
+            handler = _WorktreeHandler(self, repo)
+            # Schedule on the repo root (recursive). We watch the working
+            # tree, NOT the .git dir — gitignore filter handles noise from
+            # .git/ appearing if the observer root is above it.
+            observer.schedule(handler, str(repo.path), recursive=True)
+            observer.daemon = True
+            observer.start()
+            repo.observer = observer
+            self._repos.append(repo)
+            logger.info(
+                "worktree_watcher observing repo=%s",
+                repo.path,
+            )
+
+        try:
+            await self._stop_event.wait()
+        finally:
+            for repo in self._repos:
+                if repo.observer is not None:
+                    with contextlib.suppress(Exception):
+                        repo.observer.stop()
+                        repo.observer.join(timeout=2.0)
+            logger.info("worktree_watcher stopped")
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    # ------------------------------------------------------------------
+    # Repo discovery
+    # ------------------------------------------------------------------
+
+    def _resolve_repos(self) -> list[_WatchedRepo]:
+        paths: list[Path] = []
+        if self._explicit_paths:
+            paths = [Path(p).expanduser().resolve() for p in self._explicit_paths]
+        else:
+            cwd = Path.cwd().resolve()
+            git_dir = cwd / ".git"
+            if git_dir.is_dir() or git_dir.is_file():
+                paths = [cwd]
+
+        repos: list[_WatchedRepo] = []
+        for path in paths:
+            git_dir = path / ".git"
+            # Pentest mirror from git_watcher.py: refuse symlinked .git.
+            if git_dir.is_symlink():
+                logger.warning(
+                    "worktree_watcher: refusing symlinked .git path=%s -> %s",
+                    git_dir,
+                    git_dir.resolve(strict=False),
+                )
+                continue
+            if not git_dir.exists():
+                logger.warning(
+                    "worktree_watcher: skipping non-repo path=%s",
+                    path,
+                )
+                continue
+            repos.append(_WatchedRepo(path=path, git_dir=git_dir))
+        return repos
+
+    # ------------------------------------------------------------------
+    # Watchdog callbacks (thread → asyncio bridge)
+    # ------------------------------------------------------------------
+
+    def _on_file_modified(self, repo: _WatchedRepo, abs_path: str) -> None:
+        """Called on the watchdog observer thread when a file write is detected."""
+        loop = self._loop
+        if loop is None or loop.is_closed():
+            return
+        loop.call_soon_threadsafe(
+            lambda: asyncio.create_task(self._handle_file_modified_async(repo, abs_path))
+        )
+
+    async def _handle_file_modified_async(self, repo: _WatchedRepo, abs_path: str) -> None:
+        """Runs on the asyncio loop — apply guards, debounce, and publish."""
+        try:
+            p = Path(abs_path)
+
+            # Skip symlinks (pentest pattern from git_watcher)
+            if p.is_symlink():
+                return
+
+            # Skip .git/ internals — we only care about working-tree files
+            try:
+                p.relative_to(repo.git_dir)
+                return  # inside .git — skip
+            except ValueError:
+                pass
+
+            # Skip gitignored paths
+            if self._is_ignored(repo, p):
+                return
+
+            # Debounce: collapse rapid writes to the same path
+            now = time.monotonic()
+            last = repo._debounce.get(abs_path, 0.0)
+            if now - last < self._debounce_seconds:
+                return
+
+            # Evict oldest if debounce dict is growing too large
+            if len(repo._debounce) >= MAX_DEBOUNCE_PATHS:
+                oldest_half = sorted(repo._debounce, key=lambda k: repo._debounce[k])[
+                    : MAX_DEBOUNCE_PATHS // 2
+                ]
+                for k in oldest_half:
+                    del repo._debounce[k]
+
+            repo._debounce[abs_path] = now
+
+            try:
+                rel_path = str(p.relative_to(repo.path))
+            except ValueError:
+                rel_path = abs_path
+
+            ts = datetime.now(timezone.utc).isoformat()
+            await self._publish(
+                repo,
+                {
+                    "repo": str(repo.path),
+                    "file_path": abs_path,
+                    "rel_path": rel_path,
+                    "ts": ts,
+                },
+            )
+
+        except Exception as exc:  # pragma: no cover
+            logger.warning("worktree_watcher: file modified handling failed: %s", exc)
+
+    async def _publish(self, repo: _WatchedRepo, payload: dict[str, Any]) -> None:
+        logger.debug(
+            "worktree_watcher publishing kind=worktree_edit repo=%s file=%s",
+            payload.get("repo"),
+            payload.get("rel_path"),
+        )
+        await self._bus.publish(
+            EGRESS_TOPIC,
+            {"kind": "worktree_edit", "payload": payload, "source": "worktree_watcher"},
+        )
+
+    # ------------------------------------------------------------------
+    # gitignore filtering
+    # ------------------------------------------------------------------
+
+    def _is_ignored(self, repo: _WatchedRepo, path: Path) -> bool:
+        """Return True if ``path`` is covered by the repo's .gitignore."""
+        if not repo._ignore_loaded:
+            repo._ignore_spec = _load_ignore_spec(repo.path)
+            repo._ignore_loaded = True
+
+        ignore_spec = repo._ignore_spec
+        if ignore_spec is None:
+            return False
+
+        try:
+            rel = path.relative_to(repo.path)
+            return bool(ignore_spec.match_file(str(rel)))
+        except (ValueError, Exception):
+            return False
+
+    # ------------------------------------------------------------------
+    # Test introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def watched_repos(self) -> list[_WatchedRepo]:
+        return list(self._repos)
+
+
+# ---------------------------------------------------------------------------
+# watchdog event handler
+# ---------------------------------------------------------------------------
+
+
+class _WorktreeHandler:
+    """Shims watchdog's FileSystemEventHandler without subclassing it.
+
+    Only write-class events (Modified, Created, Moved-dest) reach the watcher.
+    Read events (FileOpenedEvent, FileClosedNoWriteEvent) are dropped at this
+    level — the same filter documented in git_watcher.py that prevented the
+    ~10MB/s RSS flood from open-and-read bursts.
+    """
+
+    def __init__(self, watcher: WorktreeWatcher, repo: _WatchedRepo) -> None:
+        self._watcher = watcher
+        self._repo = repo
+        self._construct_thread = threading.get_ident()
+
+    def dispatch(self, event: Any) -> None:
+        if getattr(event, "is_directory", False):
+            return
+
+        # Read-event filter — critical for whole-tree watchers.
+        kind = type(event).__name__
+        if kind in ("FileOpenedEvent", "FileClosedNoWriteEvent"):
+            return
+
+        # For moves, use the destination path (the new file that now exists)
+        src = getattr(event, "src_path", None)
+        dest = getattr(event, "dest_path", None)
+        target = dest if dest and kind in ("FileMovedEvent",) else src
+        if not isinstance(target, str):
+            return
+
+        self._watcher._on_file_modified(self._repo, target)
+
+
+# ---------------------------------------------------------------------------
+# gitignore helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_ignore_spec(repo_root: Path) -> Any | None:
+    """Load a pathspec.PathSpec from the repo's .gitignore.
+
+    Returns ``None`` if pathspec is not installed or the .gitignore does not
+    exist — callers treat None as "nothing is ignored".
+    """
+    try:
+        import pathspec  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+
+    gitignore = repo_root / ".gitignore"
+    if not gitignore.exists():
+        return None
+
+    try:
+        lines = gitignore.read_text(encoding="utf-8", errors="replace").splitlines()
+        return pathspec.PathSpec.from_lines("gitwildmatch", lines)
+    except Exception as exc:
+        logger.debug("worktree_watcher: failed to load .gitignore at %s: %s", gitignore, exc)
+        return None

alter_runtime/atlas/__init__.py

@@ -0,0 +1,48 @@
+"""Atlas - substrate-recognition primitive.
+
+Post-Encounter depth surface that reads ambient device substrate (git, shell,
+vault, windows, downloads, calendar, notes, recents, aesthetic) and emits
+content-free 128-dim signature vectors. Content stays local forever; only
+derivative signature hashes cross the consent boundary, under per-stream
+Art-6(1)(a) consent.
+
+Spec: .repos/internal/02-Technical-Strategy/substrate-recognition-exploration-2026-04-17.md
+Plan: .repos/internal/02-Technical-Strategy/atlas-weekend-build-plan-2026-04-18.md
+DR candidate: D-VLT1 (Drew-gated).
+
+Honesty clause (spec §2): signatures are DERIVATIVE, not pseudonymous. A 128-dim
+vector over lifestyle substrates is richer than a browser fingerprint and is
+re-identifiable via membership inference at scale. The protection ladder for a
+server-bound signature is therefore legal + operational, not architectural.
+Any copy, schema comment, or consent UI string that claims "content-free" for
+server-crossing signatures is a regression.
+"""
+
+from alter_runtime.atlas.base import DryRunManifest, PathEntry, SubstrateAdapter
+from alter_runtime.atlas.ledger import Ledger, LedgerEntry
+from alter_runtime.atlas.observations import (
+    Observation,
+    lint_observation_line,
+    render_observations,
+)
+from alter_runtime.atlas.schema import (
+    ProvenanceClass,
+    Signature,
+    SignatureCoefficient,
+    SubstrateStream,
+)
+
+__all__ = [
+    "DryRunManifest",
+    "Ledger",
+    "LedgerEntry",
+    "Observation",
+    "PathEntry",
+    "ProvenanceClass",
+    "Signature",
+    "SignatureCoefficient",
+    "SubstrateAdapter",
+    "SubstrateStream",
+    "lint_observation_line",
+    "render_observations",
+]

alter_runtime/atlas/base.py

@@ -0,0 +1,102 @@
+"""SubstrateAdapter - base class for all Atlas adapters.
+
+Each adapter subclass reads one stream (git, shell, vault, ...) and produces a
+Signature. The contract is:
+
+  * ``dry_run(config)`` - enumerate what WOULD be read without reading. Returns
+    a DryRunManifest the user reviews before granting the read.
+  * ``extract(config)`` - perform the read, produce a Signature, discard content.
+  * ``supported_coefficients`` - class-level tuple of which slots this adapter
+    populates (used for Mirror citation templates + consent UI).
+
+Adapters NEVER write to the substrate, NEVER retain content, NEVER cross the
+network directly. Egress is the parent daemon's responsibility under per-stream
+consent.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from alter_runtime.atlas.schema import (
+    ProvenanceClass,
+    Signature,
+    SubstrateStream,
+)
+
+
+@dataclass(frozen=True)
+class PathEntry:
+    """One path the adapter would read, with byte budget."""
+
+    path: Path
+    bytes_to_read: int
+    purpose: str  # one-line description shown in consent UI
+
+
+@dataclass(frozen=True)
+class DryRunManifest:
+    """What an adapter WOULD read - shown to the user before any consent grant.
+
+    The user approves paths, not concepts. Consent UI renders this manifest
+    verbatim. Bytes_total is advisory; adapters are expected to be within 10%.
+    """
+
+    stream: SubstrateStream
+    entries: tuple[PathEntry, ...]
+    bytes_total: int
+    extraction_version: int
+    coefficients_populated: tuple[str, ...]  # names from schema
+    summary: str  # one-line pitch, e.g. "your git commit rhythm"
+
+    @classmethod
+    def empty(cls, stream: SubstrateStream, extraction_version: int) -> "DryRunManifest":
+        """Manifest for an adapter that found nothing to read on this device."""
+        return cls(
+            stream=stream,
+            entries=(),
+            bytes_total=0,
+            extraction_version=extraction_version,
+            coefficients_populated=(),
+            summary=f"no {stream.value} substrate found on this device",
+        )
+
+
+class SubstrateAdapter(ABC):
+    """Base for Atlas substrate adapters.
+
+    Subclass contract:
+      * class-level ``stream`` = SubstrateStream enum member
+      * class-level ``extraction_version`` = int, bumped on signature-changing
+        algorithm updates
+      * class-level ``supported_coefficients`` = tuple of coefficient names
+      * ``dry_run(config)`` returns a DryRunManifest
+      * ``extract(config)`` returns a Signature
+    """
+
+    stream: SubstrateStream
+    extraction_version: int = 1
+    supported_coefficients: tuple[str, ...] = ()
+
+    @abstractmethod
+    def dry_run(self, config: dict[str, Any]) -> DryRunManifest:
+        """Enumerate what WOULD be read. Pure - no side effects on substrate."""
+
+    @abstractmethod
+    def extract(self, config: dict[str, Any]) -> Signature:
+        """Perform the read + extract signature. Discard content before return.
+
+        Adapters MUST NOT retain substrate content beyond this method's scope.
+        Content lives in local memory during extraction and is released on
+        return; only the Signature crosses the method boundary.
+        """
+
+    def provenance(self, config: dict[str, Any]) -> ProvenanceClass:
+        """Classify this read per D-IaI-1.2. Override for passive subscribers.
+
+        Default: ACTIVE (user-initiated `alter atlas read`).
+        """
+        return ProvenanceClass.ACTIVE