alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/atlas/ledger.py

@@ -0,0 +1,196 @@
+"""Append-only read ledger for Atlas substrate reads.
+
+Every adapter read (or dry-run) emits a ``LedgerEntry`` to the JSONL file at
+``~/.local/state/alter/atlas/reads.jsonl``. The ledger records *what was read,
+when, under which consent grant, and the content-free hash of the resulting
+signature*. It is the local surface the user can inspect with ``alter atlas
+show`` and the source the Mirror renderer cites for observation timestamps.
+
+Honesty clause - this ledger is a SOFT SIGNAL, not a cryptographic audit.
+
+Per substrate spec §4.3: the egress-capable parent daemon writes this ledger.
+When the parent daemon is the attacker, the ledger is an honest-witness weakness
+- the daemon can simply omit or rewrite entries. Meaningful external auditing
+arrives when ``alter-ebpf`` (Patent M) ships on-user-device and can witness
+``bprm_check_security`` + network syscalls sourced from the daemon UID from
+outside the daemon's control boundary.
+
+Until then the ledger is "tell me when I'm lying" telemetry - useful for
+honest operation and revoke-and-shred bookkeeping, NOT a tamper-evident proof.
+Do not describe it as audit-grade, cryptographic, or anti-forgery anywhere.
+
+The ledger also supports per-stream shred: revoking a stream (per D-CGT1
+revocability) rewrites the JSONL with stream entries removed. This mirrors
+the revoke-and-shred behaviour described in spec §4.4.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterator, Literal
+
+from alter_runtime.atlas.schema import ProvenanceClass, SubstrateStream, utcnow
+
+LedgerAction = Literal["dry_run", "read", "shredded"]
+
+DEFAULT_LEDGER_PATH = Path.home() / ".local" / "state" / "alter" / "atlas" / "reads.jsonl"
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """One row of the read ledger.
+
+    Fields are named for JSONL stability - bumps add fields, never rename.
+    """
+
+    action: LedgerAction
+    stream: SubstrateStream
+    provenance: ProvenanceClass
+    extraction_version: int
+    at: datetime
+    consent_grant_id: str | None
+    manifest_hash: str | None
+    signature_hash: str | None
+    bytes_read: int
+    note: str = ""
+    schema_version: int = 1
+
+    def to_json(self) -> str:
+        payload = asdict(self)
+        payload["stream"] = self.stream.value
+        payload["provenance"] = self.provenance.value
+        payload["at"] = self.at.astimezone(timezone.utc).isoformat()
+        return json.dumps(payload, separators=(",", ":"), sort_keys=True)
+
+    @classmethod
+    def from_json(cls, line: str) -> "LedgerEntry":
+        raw = json.loads(line)
+        return cls(
+            action=raw["action"],
+            stream=SubstrateStream(raw["stream"]),
+            provenance=ProvenanceClass(raw["provenance"]),
+            extraction_version=int(raw["extraction_version"]),
+            at=datetime.fromisoformat(raw["at"]),
+            consent_grant_id=raw.get("consent_grant_id"),
+            manifest_hash=raw.get("manifest_hash"),
+            signature_hash=raw.get("signature_hash"),
+            bytes_read=int(raw.get("bytes_read", 0)),
+            note=raw.get("note", ""),
+            schema_version=int(raw.get("schema_version", 1)),
+        )
+
+
+class Ledger:
+    """Append-only JSONL read ledger.
+
+    Soft-signal, local-only. See module docstring for the honesty clause.
+    """
+
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or DEFAULT_LEDGER_PATH
+
+    def _ensure_parent(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, entry: LedgerEntry) -> None:
+        """Atomically append one entry.
+
+        POSIX guarantees ``write()`` of <= PIPE_BUF bytes with ``O_APPEND`` is
+        atomic against concurrent writers. A JSONL row is well below PIPE_BUF
+        (4096 on Linux) for these fixed-size fields, so we rely on that
+        without explicit locking.
+        """
+        self._ensure_parent()
+        fd = os.open(self.path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+        try:
+            os.write(fd, (entry.to_json() + "\n").encode("utf-8"))
+        finally:
+            os.close(fd)
+
+    def read_all(self) -> Iterator[LedgerEntry]:
+        if not self.path.exists():
+            return
+        with self.path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                yield LedgerEntry.from_json(line)
+
+    def read_stream(self, stream: SubstrateStream) -> list[LedgerEntry]:
+        return [e for e in self.read_all() if e.stream == stream]
+
+    def latest_for_stream(self, stream: SubstrateStream) -> LedgerEntry | None:
+        latest: LedgerEntry | None = None
+        for entry in self.read_stream(stream):
+            if latest is None or entry.at > latest.at:
+                latest = entry
+        return latest
+
+    def shred_stream(self, stream: SubstrateStream, reason: str = "user_revoke") -> int:
+        """Remove all entries for ``stream`` and append a single shred marker.
+
+        Returns the number of entries removed. The marker entry preserves
+        provenance that a shred happened (for dashboard display) without
+        retaining the shredded content hashes.
+        """
+        if not self.path.exists():
+            return 0
+        kept: list[str] = []
+        removed = 0
+        with self.path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                try:
+                    entry = LedgerEntry.from_json(stripped)
+                except (KeyError, ValueError):
+                    kept.append(line.rstrip("\n"))
+                    continue
+                if entry.stream == stream:
+                    removed += 1
+                    continue
+                kept.append(stripped)
+
+        self._ensure_parent()
+        tmp_fd, tmp_path = tempfile.mkstemp(
+            prefix="reads.", suffix=".jsonl.tmp", dir=self.path.parent
+        )
+        try:
+            with os.fdopen(tmp_fd, "w", encoding="utf-8") as tmp:
+                for row in kept:
+                    tmp.write(row + "\n")
+                marker = LedgerEntry(
+                    action="shredded",
+                    stream=stream,
+                    provenance=ProvenanceClass.ACTIVE,
+                    extraction_version=0,
+                    at=utcnow(),
+                    consent_grant_id=None,
+                    manifest_hash=None,
+                    signature_hash=None,
+                    bytes_read=0,
+                    note=reason,
+                )
+                tmp.write(marker.to_json() + "\n")
+            os.chmod(tmp_path, 0o600)
+            os.replace(tmp_path, self.path)
+        except Exception:
+            with suppress_errors():
+                os.unlink(tmp_path)
+            raise
+        return removed
+
+
+class suppress_errors:
+    def __enter__(self) -> "suppress_errors":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        return True

alter_runtime/atlas/observations.py

@@ -0,0 +1,136 @@
+"""Observation renderer - local-only citation list from one or more Signatures.
+
+The observation surface is NOT a dashboard, NOT a reading in the tarot sense,
+NOT a therapy session. It is a citation list: specific observations tied to
+specific counts, rendered on-device with zero network round-trip.
+
+Tone discipline - OBSERVATION, never INTERPRETATION (spec §6).
+
+The cringe kill-zone is any line where Alter names a pattern FOR the user,
+reads meaning into content, or delivers an aphorism. PKM-native users have
+finely-tuned detectors for exactly this move ("you've built a slip-box",
+"you don't want Spanish, you want the version of you that speaks Spanish").
+
+The renderer's voice: numbers, timestamps, paths - then stop. User supplies
+meaning. Marcus Aurelius plus an engineer.
+
+This module exposes:
+
+- ``Observation`` - one line of output carried alongside its slot citations
+  (so the user can trace each line back to the exact coefficient).
+- ``render_observations(...)`` - compose header + body from a list of observations.
+- ``lint_observation_line(line)`` - soft-lint for known interpretive phrases.
+  Returns a list of reasons the line is likely regressive (adapter-side tests
+  can raise on non-empty; CI honesty-clause audit uses the same list).
+
+Adapters own the observation templates (they know what their coefficients
+mean); this module only enforces rendering shape + the lint floor.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Sequence
+
+from alter_runtime.atlas.schema import Signature
+
+OBSERVATION_PREFIX = "- "  # em-dash + space, per spec §6 example
+
+
+@dataclass(frozen=True)
+class Observation:
+    """One rendered observation line.
+
+    ``citations`` lists coefficient names from the signature this line reads
+    - used for dashboard trace-back ("this line came from which numbers?")
+    and for the post-render smoke-test that every observation can be cited.
+    """
+
+    line: str
+    citations: tuple[str, ...] = ()
+
+
+FORBIDDEN_PHRASES: tuple[str, ...] = (
+    "you've built",
+    "you have built",
+    "you're a",
+    "you are a",
+    "what you really want",
+    "what you truly want",
+    "the version of you",
+    "deep down",
+    "slip-box",
+    "zettelkasten",
+    "second brain",
+    "night owl",
+    "early bird",
+    "ghost ambitions",
+    "shadow self",
+    "your archetype",
+    "your type",
+)
+
+
+def lint_observation_line(line: str) -> list[str]:
+    """Return reasons this line likely violates §6 observation-only discipline.
+
+    This is a soft lint - it does not catch every regression (novel
+    interpretive phrasings will slip past) but it catches the spec-named
+    kill-zone phrases and common second-person verdict openers. Adapter
+    tests should assert this returns ``[]`` for every shipped template.
+    """
+    reasons: list[str] = []
+    lower = line.lower()
+    for phrase in FORBIDDEN_PHRASES:
+        if phrase in lower:
+            reasons.append(f"forbidden phrase: {phrase!r}")
+    stripped = lower.lstrip("- -")
+    for opener in ("you've ", "you are ", "you're "):
+        if stripped.startswith(opener):
+            reasons.append(
+                f"second-person verdict opener: {opener!r} - prefer counts/timestamps/paths"
+            )
+            break
+    return reasons
+
+
+def render_observations(
+    handle: str,
+    signatures: Sequence[Signature],
+    observations: Sequence[Observation],
+    rendered_at: datetime | None = None,
+) -> str:
+    """Compose the observation text.
+
+    Output shape (spec §6 example):
+
+        Atlas / ~blake / 2026-04-17
+
+        - 47 of your 83 commits this year landed between 23:00 and 02:00
+        - You commit on Tuesday (19) and Sunday (14) more than any other day
+        - Your commit verbs: feat 31 · fix 22 · refactor 14 · chore 9 · docs 7
+
+    The header uses the ``~handle`` form per D-ID1–ID8 namespace convention.
+    Observations render in the order supplied - adapters are expected to
+    pre-order by most to least surprising count.
+
+    This function does not enforce ``lint_observation_line`` - that is the
+    adapter's responsibility in its unit test. Render-time failures in prod
+    would block the observation surface for a user whose machine produced an
+    edge-case template; soft-lint at test time, not runtime.
+    """
+    handle_display = handle if handle.startswith("~") else f"~{handle}"
+    when = rendered_at or datetime.now(timezone.utc)
+    date_line = when.strftime("%Y-%m-%d")
+
+    streams = "·".join(sorted({s.stream.value for s in signatures}))
+    # Streams line only renders when more than one stream is cited - keeps
+    # single-adapter output (T0 git-only) matching the spec example verbatim.
+    header_lines = [f"Atlas / {handle_display} / {date_line}"]
+    if streams and len(signatures) > 1:
+        header_lines.append(f"streams: {streams}")
+
+    body_lines = [f"{OBSERVATION_PREFIX}{obs.line}" for obs in observations]
+
+    return "\n".join(header_lines + [""] + body_lines) + "\n"

alter_runtime/atlas/schema.py

@@ -0,0 +1,106 @@
+"""Atlas signature schema - the derivative vector shape.
+
+A Signature is the output of one adapter reading one substrate once. It carries:
+  * a 128-dim coefficient vector (padded with NaN for adapter-specific shorter
+    outputs - each adapter documents which slots it populates)
+  * provenance metadata (which stream, which extraction version, when)
+  * a content-free hash for server-crossing under depth-fork consent
+
+Per spec §2 honesty clause: the hash is NOT a pseudonymisation guarantee. It is
+re-identifiable via membership inference at scale. Protection is legal (per-stream
+Art-6(1)(a) consent + audit) + operational (no-cross-join policy) - not
+architectural.
+"""
+
+from __future__ import annotations
+
+import enum
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+SIGNATURE_DIM: int = 128
+SIGNATURE_SCHEMA_VERSION: int = 1
+
+
+class SubstrateStream(str, enum.Enum):
+    """Enumeration of shipped + parked substrate streams.
+
+    Each stream is gated independently for consent per D-IaI-1.5.
+    """
+
+    GIT = "git"
+    SHELL = "shell"
+    VAULT = "vault"
+    WINDOWS = "windows"
+    DOWNLOADS = "downloads"
+    CALENDAR = "calendar"
+    NOTES = "notes"
+    RECENTS = "recents"
+    AESTHETIC = "aesthetic"
+    MUSIC = "music"  # Phase 2 - Drew-gated E-tier firewall DR required
+
+
+class ProvenanceClass(str, enum.Enum):
+    """D-IaI-1.2 provenance classes - gate consent by (stream × provenance)."""
+
+    ACTIVE = "active"  # user-initiated read (`alter atlas read`)
+    PASSIVE_LOCAL = "passive_local"  # daemon subscription, LOCAL-ONLY
+    PASSIVE_AGGREGATE = "passive_aggregate"  # k>=1000 population observation
+
+
+@dataclass(frozen=True)
+class SignatureCoefficient:
+    """One named slot in the 128-dim vector.
+
+    Adapters declare which coefficients they populate; unpopulated slots stay
+    NaN. The name is canonical across versions - schema bumps add coefficients,
+    never rename.
+    """
+
+    slot: int
+    name: str
+    value: float
+    unit: str | None = None
+
+
+@dataclass(frozen=True)
+class Signature:
+    """One adapter's read of one substrate at one moment."""
+
+    stream: SubstrateStream
+    provenance: ProvenanceClass
+    extracted_at: datetime
+    extraction_version: int
+    coefficients: tuple[SignatureCoefficient, ...]
+    schema_version: int = SIGNATURE_SCHEMA_VERSION
+
+    def to_vector(self) -> list[float]:
+        """Dense 128-dim vector with NaN for unpopulated slots."""
+        vec = [float("nan")] * SIGNATURE_DIM
+        for coeff in self.coefficients:
+            if 0 <= coeff.slot < SIGNATURE_DIM:
+                vec[coeff.slot] = coeff.value
+        return vec
+
+    def content_free_hash(self) -> str:
+        """BLAKE3-ish stable hash over (stream, version, sorted coefficients).
+
+        Uses sha256 for stdlib availability; BLAKE3 is a post-launch upgrade.
+        This hash is re-identifiable at scale (spec §2 honesty clause) - do
+        not treat as pseudonymisation.
+        """
+        h = hashlib.sha256()
+        h.update(self.stream.value.encode())
+        h.update(self.schema_version.to_bytes(4, "big"))
+        h.update(self.extraction_version.to_bytes(4, "big"))
+        for coeff in sorted(self.coefficients, key=lambda c: c.slot):
+            h.update(coeff.slot.to_bytes(2, "big"))
+            h.update(coeff.name.encode())
+            # Fixed-width float repr so hash is stable across Python versions.
+            h.update(f"{coeff.value:.9e}".encode())
+        return h.hexdigest()
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)