escrow-evidence 0.1.0__tar.gz

escrow_evidence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

escrow_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: escrow-evidence
+Version: 0.1.0
+Summary: A dead-man's-switch for cron/scheduled jobs: flags silence, not just failure -- the job that stopped running weeks ago that no alert ever caught.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/escrow
+Project-URL: Source, https://github.com/MaXiMo000/escrow
+Project-URL: Issues, https://github.com/MaXiMo000/escrow/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/escrow/releases
+Keywords: cron,monitoring,dead-mans-switch,heartbeat,evidence,reliability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# escrow
+
+[![ci](https://github.com/MaXiMo000/escrow/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/escrow/actions/workflows/ci.yml)
+
+**A dead-man's-switch for cron jobs, GitHub Actions schedules, and systemd
+timers: flags silence, not just failure.**
+
+A scheduled job that throws an exception gets logged, maybe alerted on.
+One that silently *stops running* — a cron entry removed by a bad deploy,
+a systemd timer disabled and forgotten, a token that expired weeks ago —
+produces nothing: no error, no log line, no exit code to check. "No
+alert" and "everything's fine" look identical to anything that only
+watches for failure. `escrow` watches for the third thing: quiet.
+
+```
+$ escrow check escrow.yaml
+[!!] 'nightly-backup' last pinged 1d ago, past its 26h interval
+[??] 'weekly-report' has never pinged in -- it may have never run, or is pinging under a different name
+
+0/2 ok, 2 need attention
+```
+
+(Real output. `nightly-backup` pinged in on time once, then its clock was
+wound forward 30 hours past its 26h interval; `weekly-report` never pinged
+at all.)
+
+## Install
+
+```
+pip install escrow-evidence   # the command it installs is `escrow`
+```
+
+(`escrow` was already taken on PyPI -- same story as every sibling in this
+portfolio.)
+
+## Use
+
+Declare what you're expecting, in `escrow.yaml`:
+
+```yaml
+jobs:
+  - name: nightly-backup
+    interval: 26h    # a daily job, with a few hours' slack
+  - name: weekly-report
+    interval: 8d
+```
+
+At the end of the actual job's script, record that it ran:
+
+```bash
+escrow ping nightly-backup
+```
+
+Separately -- on its own schedule, e.g. every 15 minutes -- check every
+declared job against what's actually been recorded:
+
+```bash
+escrow check escrow.yaml
+```
+
+`ping` and `check` share a small JSON state file (`escrow-state.json` by
+default, or `--state PATH`) -- `ping` writes to it, `check` reads it. They
+need to see the *same* file: the common shape is a single host (the job
+and the check both run there, e.g. two cron entries) or a shared
+filesystem mount. This is not a hosted, multi-machine service; see "What
+this does not do."
+
+## Three statuses, not two
+
+| Status | Meaning |
+|---|---|
+| `ok` | Pinged within its declared interval. |
+| `overdue` | Pinged before, but not recently enough -- **the job that used to run and stopped.** |
+| `never_seen` | Declared in `escrow.yaml`, never once recorded a ping -- **the job that never ran at all**, or a typo between the name in the config and the name in the script. |
+
+`overdue` and `never_seen` are deliberately different statuses, not one
+"bad" bucket: an operator debugs "this stopped" and "this never started"
+differently, and collapsing them would hide which one they're looking at.
+Jobs are declared in `escrow.yaml` up front, not discovered from whatever
+happens to have pinged -- a job that's only "known" because it once pinged
+would be exactly as invisible as before the first time it silently
+stopped, or if it never started.
+
+Exit code is `1` if anything is `overdue` or `never_seen`, `0` if every
+declared job is `ok`.
+
+## What this does NOT do
+
+- **No daemon, no background process.** There is no `escrow serve` or
+  `escrow watch`. `escrow check` is one CLI invocation that reads the
+  state file and exits; *you* supply the periodic trigger -- a cron
+  entry, a systemd timer, a scheduled GitHub Actions workflow. escrow
+  never runs unless something else runs it.
+- **No email, Slack, or webhook of its own.** The exit code is the
+  interface -- same convention [`receipt`](https://github.com/MaXiMo000/receipt),
+  [`invariant`](https://github.com/MaXiMo000/invariant), and
+  [`carabiner`](https://github.com/MaXiMo000/carabiner) already share.
+  Run `escrow check` as a step that fails loudly in whatever you already
+  have (a GitHub Actions job, a systemd `OnFailure=` unit, a cron entry
+  piped to your existing paging tool) rather than escrow adding its own
+  SMTP client or HTTP dependency for a notification path you may not want.
+- **Not a hosted or multi-machine service.** State is one JSON file; `ping`
+  and `check` need to see the same one. A fleet of machines all pinging a
+  shared endpoint needs a real datastore behind it, not a local file --
+  genuinely different scope, not built here.
+- **Not resilient to concurrent writers.** State is written to a temp file
+  and atomically renamed (a crash mid-write can't corrupt it), but two
+  `ping`s racing on the exact same job name on a network filesystem at the
+  same instant can still lose one update. Fine for the target use --one
+  job pings once per run-- not designed for high-frequency concurrent
+  writes.
+
+## Compared to a hosted dead-man's-switch
+
+[healthchecks.io](https://healthchecks.io), [Cronitor](https://cronitor.io),
+and [Dead Man's Snitch](https://deadmanssnitch.com) solve the same problem
+as a real, mature, hosted service: your job pings a URL over HTTPS, and
+their infrastructure -- not yours -- watches the clock and sends email/
+Slack/SMS/PagerDuty when a ping is late. If you want alerting that works
+without you also solving alerting, and don't mind a third party knowing
+when your jobs run, one of those is very likely the better choice --
+escrow doesn't compete with that and isn't trying to.
+
+escrow's tradeoff runs the other way, matching the same "stays on your
+machine" discipline as the rest of this portfolio: `ping` and `check` never
+leave the filesystem, there's no account, no third party ever learns your
+job names or schedule, and the whole state is one JSON file you can read,
+back up, or delete yourself. The cost of that is everything a hosted
+service gives you for free: no scheduling (see "no daemon," above) and no
+notification path of its own (see above) -- you supply both, from
+infrastructure you already have. Reach for escrow specifically when a
+third-party dependency for "is my cron job still running" is the wrong
+tradeoff for what the job actually does; reach for a hosted switch
+otherwise.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_duration.py   # "26h", "8d" -> seconds
+python tests/test_config.py     # escrow.yaml validation
+python tests/test_state.py      # the ping record: real files, real temp dirs
+python tests/test_check.py      # ok / overdue / never_seen classification
+python tests/test_cli.py        # the real CLI entry point, real files, real argv
+```
+
+41 tests. Two exist because testing an actual misconfigured `--state`
+(pointed at a directory instead of a file) found a real gap: `load_state`
+only caught `JSONDecodeError`, so `IsADirectoryError` -- also an `OSError`
+-- escaped as a raw traceback instead of the same graceful "nothing
+recorded yet" every other unreadable state file gets.
+
+MIT licensed.

escrow_evidence-0.1.0/README.md

@@ -0,0 +1,153 @@
+# escrow
+
+[![ci](https://github.com/MaXiMo000/escrow/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/escrow/actions/workflows/ci.yml)
+
+**A dead-man's-switch for cron jobs, GitHub Actions schedules, and systemd
+timers: flags silence, not just failure.**
+
+A scheduled job that throws an exception gets logged, maybe alerted on.
+One that silently *stops running* — a cron entry removed by a bad deploy,
+a systemd timer disabled and forgotten, a token that expired weeks ago —
+produces nothing: no error, no log line, no exit code to check. "No
+alert" and "everything's fine" look identical to anything that only
+watches for failure. `escrow` watches for the third thing: quiet.
+
+```
+$ escrow check escrow.yaml
+[!!] 'nightly-backup' last pinged 1d ago, past its 26h interval
+[??] 'weekly-report' has never pinged in -- it may have never run, or is pinging under a different name
+
+0/2 ok, 2 need attention
+```
+
+(Real output. `nightly-backup` pinged in on time once, then its clock was
+wound forward 30 hours past its 26h interval; `weekly-report` never pinged
+at all.)
+
+## Install
+
+```
+pip install escrow-evidence   # the command it installs is `escrow`
+```
+
+(`escrow` was already taken on PyPI -- same story as every sibling in this
+portfolio.)
+
+## Use
+
+Declare what you're expecting, in `escrow.yaml`:
+
+```yaml
+jobs:
+  - name: nightly-backup
+    interval: 26h    # a daily job, with a few hours' slack
+  - name: weekly-report
+    interval: 8d
+```
+
+At the end of the actual job's script, record that it ran:
+
+```bash
+escrow ping nightly-backup
+```
+
+Separately -- on its own schedule, e.g. every 15 minutes -- check every
+declared job against what's actually been recorded:
+
+```bash
+escrow check escrow.yaml
+```
+
+`ping` and `check` share a small JSON state file (`escrow-state.json` by
+default, or `--state PATH`) -- `ping` writes to it, `check` reads it. They
+need to see the *same* file: the common shape is a single host (the job
+and the check both run there, e.g. two cron entries) or a shared
+filesystem mount. This is not a hosted, multi-machine service; see "What
+this does not do."
+
+## Three statuses, not two
+
+| Status | Meaning |
+|---|---|
+| `ok` | Pinged within its declared interval. |
+| `overdue` | Pinged before, but not recently enough -- **the job that used to run and stopped.** |
+| `never_seen` | Declared in `escrow.yaml`, never once recorded a ping -- **the job that never ran at all**, or a typo between the name in the config and the name in the script. |
+
+`overdue` and `never_seen` are deliberately different statuses, not one
+"bad" bucket: an operator debugs "this stopped" and "this never started"
+differently, and collapsing them would hide which one they're looking at.
+Jobs are declared in `escrow.yaml` up front, not discovered from whatever
+happens to have pinged -- a job that's only "known" because it once pinged
+would be exactly as invisible as before the first time it silently
+stopped, or if it never started.
+
+Exit code is `1` if anything is `overdue` or `never_seen`, `0` if every
+declared job is `ok`.
+
+## What this does NOT do
+
+- **No daemon, no background process.** There is no `escrow serve` or
+  `escrow watch`. `escrow check` is one CLI invocation that reads the
+  state file and exits; *you* supply the periodic trigger -- a cron
+  entry, a systemd timer, a scheduled GitHub Actions workflow. escrow
+  never runs unless something else runs it.
+- **No email, Slack, or webhook of its own.** The exit code is the
+  interface -- same convention [`receipt`](https://github.com/MaXiMo000/receipt),
+  [`invariant`](https://github.com/MaXiMo000/invariant), and
+  [`carabiner`](https://github.com/MaXiMo000/carabiner) already share.
+  Run `escrow check` as a step that fails loudly in whatever you already
+  have (a GitHub Actions job, a systemd `OnFailure=` unit, a cron entry
+  piped to your existing paging tool) rather than escrow adding its own
+  SMTP client or HTTP dependency for a notification path you may not want.
+- **Not a hosted or multi-machine service.** State is one JSON file; `ping`
+  and `check` need to see the same one. A fleet of machines all pinging a
+  shared endpoint needs a real datastore behind it, not a local file --
+  genuinely different scope, not built here.
+- **Not resilient to concurrent writers.** State is written to a temp file
+  and atomically renamed (a crash mid-write can't corrupt it), but two
+  `ping`s racing on the exact same job name on a network filesystem at the
+  same instant can still lose one update. Fine for the target use --one
+  job pings once per run-- not designed for high-frequency concurrent
+  writes.
+
+## Compared to a hosted dead-man's-switch
+
+[healthchecks.io](https://healthchecks.io), [Cronitor](https://cronitor.io),
+and [Dead Man's Snitch](https://deadmanssnitch.com) solve the same problem
+as a real, mature, hosted service: your job pings a URL over HTTPS, and
+their infrastructure -- not yours -- watches the clock and sends email/
+Slack/SMS/PagerDuty when a ping is late. If you want alerting that works
+without you also solving alerting, and don't mind a third party knowing
+when your jobs run, one of those is very likely the better choice --
+escrow doesn't compete with that and isn't trying to.
+
+escrow's tradeoff runs the other way, matching the same "stays on your
+machine" discipline as the rest of this portfolio: `ping` and `check` never
+leave the filesystem, there's no account, no third party ever learns your
+job names or schedule, and the whole state is one JSON file you can read,
+back up, or delete yourself. The cost of that is everything a hosted
+service gives you for free: no scheduling (see "no daemon," above) and no
+notification path of its own (see above) -- you supply both, from
+infrastructure you already have. Reach for escrow specifically when a
+third-party dependency for "is my cron job still running" is the wrong
+tradeoff for what the job actually does; reach for a hosted switch
+otherwise.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_duration.py   # "26h", "8d" -> seconds
+python tests/test_config.py     # escrow.yaml validation
+python tests/test_state.py      # the ping record: real files, real temp dirs
+python tests/test_check.py      # ok / overdue / never_seen classification
+python tests/test_cli.py        # the real CLI entry point, real files, real argv
+```
+
+41 tests. Two exist because testing an actual misconfigured `--state`
+(pointed at a directory instead of a file) found a real gap: `load_state`
+only caught `JSONDecodeError`, so `IsADirectoryError` -- also an `OSError`
+-- escaped as a raw traceback instead of the same graceful "nothing
+recorded yet" every other unreadable state file gets.
+
+MIT licensed.

escrow_evidence-0.1.0/escrow/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

escrow_evidence-0.1.0/escrow/check.py

@@ -0,0 +1,53 @@
+"""Compare declared jobs against recorded pings: ok, overdue, or
+never_seen. Silence gets its own status, distinct from both -- the entire
+reason this tool exists is that "no alert" and "everything's fine" look
+identical to anything that only watches for a failure exit code.
+"""
+from __future__ import annotations
+
+OK, OVERDUE, NEVER_SEEN = "ok", "overdue", "never_seen"
+
+
+def _fmt(seconds: float) -> str:
+    seconds = int(seconds)
+    if seconds < 60:
+        return f"{seconds}s"
+    if seconds < 3600:
+        return f"{seconds // 60}m"
+    if seconds < 86400:
+        return f"{seconds // 3600}h"
+    return f"{seconds // 86400}d"
+
+
+def check_jobs(jobs: list[dict], state: dict, now: float) -> list[dict]:
+    results = []
+    for job in jobs:
+        name = job["name"]
+        record = state.get(name)
+
+        if record is None:
+            results.append({
+                "name": name, "status": NEVER_SEEN,
+                "detail": (f"'{name}' has never pinged in -- it may have never run, "
+                           "or is pinging under a different name"),
+                "last_seen": None, "overdue_by_seconds": None,
+            })
+            continue
+
+        last_seen = record["last_seen"]
+        age = now - last_seen
+        if age > job["interval_seconds"]:
+            results.append({
+                "name": name, "status": OVERDUE,
+                "detail": (f"'{name}' last pinged {_fmt(age)} ago, past its "
+                           f"{job['interval']} interval"),
+                "last_seen": last_seen,
+                "overdue_by_seconds": age - job["interval_seconds"],
+            })
+        else:
+            results.append({
+                "name": name, "status": OK,
+                "detail": f"'{name}' last pinged {_fmt(age)} ago, within its {job['interval']} interval",
+                "last_seen": last_seen, "overdue_by_seconds": None,
+            })
+    return results

escrow_evidence-0.1.0/escrow/cli.py

@@ -0,0 +1,77 @@
+"""escrow ping <job-name> [--state PATH]
+escrow check <config.yaml> [--state PATH] [--json]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from .check import NEVER_SEEN, OK, OVERDUE, check_jobs
+from .config import ConfigError, load_config
+from .state import load_state, record_ping
+
+DEFAULT_STATE = "escrow-state.json"
+_TAG = {OK: "OK", OVERDUE: "!!", NEVER_SEEN: "??"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="escrow")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    ping_p = sub.add_parser("ping", help="record that a job ran, right now")
+    ping_p.add_argument("job_name")
+    ping_p.add_argument("--state", default=DEFAULT_STATE,
+                         help=f"path to the state file (default: {DEFAULT_STATE})")
+
+    check_p = sub.add_parser(
+        "check", help="check every declared job against its recorded pings")
+    check_p.add_argument("config", help="escrow.yaml -- the declared jobs and intervals")
+    check_p.add_argument("--state", default=DEFAULT_STATE,
+                          help=f"path to the state file (default: {DEFAULT_STATE})")
+    check_p.add_argument("--json", action="store_true", help="print the full report as JSON")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "ping":
+        try:
+            record_ping(args.state, args.job_name, time.time())
+        except OSError as exc:
+            # --state pointed at something that can't be written (a
+            # directory, a read-only path) -- a wrong argument, not a
+            # crash. Silently swallowing this would be worse: it's the one
+            # write escrow makes, and its whole job is knowing whether that
+            # write actually happened.
+            sys.exit(f"escrow: could not record the ping: {exc}")
+        print(f"pinged '{args.job_name}'")
+        return 0
+
+    try:
+        jobs = load_config(args.config)
+    except ConfigError as exc:
+        sys.exit(f"escrow: {exc}")
+
+    state = load_state(args.state)
+    results = check_jobs(jobs, state, time.time())
+
+    if args.json:
+        print(json.dumps(results, indent=2))
+    else:
+        for r in results:
+            print(f"[{_TAG[r['status']]}] {r['detail']}")
+        n_bad = sum(1 for r in results if r["status"] != OK)
+        summary = f"{len(results) - n_bad}/{len(results)} ok"
+        if n_bad:
+            summary += f", {n_bad} need attention"
+        print(f"\n{summary}")
+
+    # Non-blocking by design: escrow reports, it doesn't page anyone --
+    # wire the exit code into whatever alerting already exists (a failing
+    # CI step, a systemd OnFailure= unit), the same "exit code is the
+    # interface" convention receipt/invariant/carabiner already share.
+    return 1 if any(r["status"] != OK for r in results) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

escrow_evidence-0.1.0/escrow/config.py

@@ -0,0 +1,62 @@
+"""Load and validate escrow.yaml: the jobs expected to ping in, and how
+often each one is allowed to go quiet before that's a problem.
+
+Jobs must be declared up front, in a file `check` reads -- a job that is
+only ever known because it once pinged would be exactly as invisible as
+before the first time it silently stopped running, or if it never started
+in the first place. Declaring first and checking reality against the
+declaration is the same discipline `invariant` already applies to
+database state, applied here to "did this job show up at all."
+"""
+from __future__ import annotations
+
+import yaml
+
+from .duration import DurationError, parse_duration
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def load_config(path: str) -> list[dict]:
+    try:
+        with open(path, encoding="utf-8") as f:
+            raw = yaml.safe_load(f)
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: not valid YAML ({exc})") from exc
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+
+    if not isinstance(raw, dict) or "jobs" not in raw:
+        raise ConfigError(f"{path}: must be a mapping with a top-level 'jobs' list")
+    jobs = raw["jobs"]
+    if not isinstance(jobs, list) or not jobs:
+        raise ConfigError(f"{path}: 'jobs' must be a non-empty list")
+
+    parsed = []
+    seen = set()
+    for i, job in enumerate(jobs):
+        if not isinstance(job, dict):
+            raise ConfigError(f"{path}: jobs[{i}] must be a mapping")
+        name = job.get("name")
+        if not name or not isinstance(name, str):
+            raise ConfigError(f"{path}: jobs[{i}] is missing a string 'name'")
+        if name in seen:
+            raise ConfigError(f"{path}: duplicate job name '{name}'")
+        seen.add(name)
+
+        interval = job.get("interval")
+        if not interval:
+            raise ConfigError(f"{path}: job '{name}' is missing 'interval'")
+        try:
+            interval_seconds = parse_duration(str(interval))
+        except DurationError as exc:
+            raise ConfigError(f"{path}: job '{name}': {exc}") from exc
+
+        parsed.append({
+            "name": name,
+            "interval": str(interval),
+            "interval_seconds": interval_seconds,
+        })
+    return parsed

escrow_evidence-0.1.0/escrow/duration.py

@@ -0,0 +1,31 @@
+"""Parse a human-friendly duration string ("26h", "8d", "45m", "2w") into
+seconds.
+
+Single unit only for v1 -- "1d12h" isn't supported; write "36h" instead.
+Combined-unit parsing is a real feature and not hard to add, but every
+config in escrow.yaml only ever needs "how long can this job go quiet
+before that's a problem," which a single unit answers just as well and
+without ambiguity about ordering (is "12h1d" valid? "1d 12h"?) that a
+combined format would have to define and test.
+"""
+from __future__ import annotations
+
+import re
+
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}
+_PATTERN = re.compile(r'^(\d+(?:\.\d+)?)([smhdw])$')
+
+
+class DurationError(ValueError):
+    pass
+
+
+def parse_duration(text: str) -> float:
+    m = _PATTERN.match(text.strip())
+    if not m:
+        raise DurationError(
+            f"'{text}' is not a duration escrow understands -- use a number "
+            f"followed by one unit: s, m, h, d, or w (e.g. '26h', '8d'). "
+            f"Combined units like '1d12h' aren't supported; write '36h'.")
+    value, unit = m.groups()
+    return float(value) * _UNIT_SECONDS[unit]

escrow_evidence-0.1.0/escrow/state.py

@@ -0,0 +1,54 @@
+"""Where each job's last ping is recorded: one small JSON file.
+
+Built for the common case -- a single host (or a shared filesystem both
+the job and the checker can see) -- not for concurrent writers racing on a
+network filesystem. A cron job and a monitoring check on the same box, or
+a NAS-mounted state file, are the target; a distributed fleet of machines
+all pinging the same file needs a real datastore, not this. Said plainly
+in README rather than silently outgrown.
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import tempfile
+
+
+def load_state(path: str) -> dict:
+    p = pathlib.Path(path)
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        # A corrupted state file, or --state pointed at something that
+        # isn't a plain file at all (a directory, a broken symlink), reads
+        # as "nothing has ever pinged," not a crash -- the next real ping
+        # repairs it, and in the meantime every job just reads as
+        # never_seen, which is honest: this file is exactly what would
+        # tell us otherwise, and it can't right now.
+        return {}
+
+
+def save_state(path: str, state: dict) -> None:
+    p = pathlib.Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # Write to a temp file in the same directory, then atomically rename --
+    # a crash mid-write leaves the previous, valid state file intact
+    # instead of a half-written, unparseable one.
+    fd, tmp_path = tempfile.mkstemp(dir=p.parent, prefix=".escrow-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2, sort_keys=True)
+        os.replace(tmp_path, p)
+    except BaseException:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+
+def record_ping(path: str, job_name: str, when: float) -> None:
+    state = load_state(path)
+    state[job_name] = {"last_seen": when}
+    save_state(path, state)

escrow_evidence-0.1.0/escrow_evidence.egg-info/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: escrow-evidence
+Version: 0.1.0
+Summary: A dead-man's-switch for cron/scheduled jobs: flags silence, not just failure -- the job that stopped running weeks ago that no alert ever caught.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/escrow
+Project-URL: Source, https://github.com/MaXiMo000/escrow
+Project-URL: Issues, https://github.com/MaXiMo000/escrow/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/escrow/releases
+Keywords: cron,monitoring,dead-mans-switch,heartbeat,evidence,reliability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# escrow
+
+[![ci](https://github.com/MaXiMo000/escrow/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/escrow/actions/workflows/ci.yml)
+
+**A dead-man's-switch for cron jobs, GitHub Actions schedules, and systemd
+timers: flags silence, not just failure.**
+
+A scheduled job that throws an exception gets logged, maybe alerted on.
+One that silently *stops running* — a cron entry removed by a bad deploy,
+a systemd timer disabled and forgotten, a token that expired weeks ago —
+produces nothing: no error, no log line, no exit code to check. "No
+alert" and "everything's fine" look identical to anything that only
+watches for failure. `escrow` watches for the third thing: quiet.
+
+```
+$ escrow check escrow.yaml
+[!!] 'nightly-backup' last pinged 1d ago, past its 26h interval
+[??] 'weekly-report' has never pinged in -- it may have never run, or is pinging under a different name
+
+0/2 ok, 2 need attention
+```
+
+(Real output. `nightly-backup` pinged in on time once, then its clock was
+wound forward 30 hours past its 26h interval; `weekly-report` never pinged
+at all.)
+
+## Install
+
+```
+pip install escrow-evidence   # the command it installs is `escrow`
+```
+
+(`escrow` was already taken on PyPI -- same story as every sibling in this
+portfolio.)
+
+## Use
+
+Declare what you're expecting, in `escrow.yaml`:
+
+```yaml
+jobs:
+  - name: nightly-backup
+    interval: 26h    # a daily job, with a few hours' slack
+  - name: weekly-report
+    interval: 8d
+```
+
+At the end of the actual job's script, record that it ran:
+
+```bash
+escrow ping nightly-backup
+```
+
+Separately -- on its own schedule, e.g. every 15 minutes -- check every
+declared job against what's actually been recorded:
+
+```bash
+escrow check escrow.yaml
+```
+
+`ping` and `check` share a small JSON state file (`escrow-state.json` by
+default, or `--state PATH`) -- `ping` writes to it, `check` reads it. They
+need to see the *same* file: the common shape is a single host (the job
+and the check both run there, e.g. two cron entries) or a shared
+filesystem mount. This is not a hosted, multi-machine service; see "What
+this does not do."
+
+## Three statuses, not two
+
+| Status | Meaning |
+|---|---|
+| `ok` | Pinged within its declared interval. |
+| `overdue` | Pinged before, but not recently enough -- **the job that used to run and stopped.** |
+| `never_seen` | Declared in `escrow.yaml`, never once recorded a ping -- **the job that never ran at all**, or a typo between the name in the config and the name in the script. |
+
+`overdue` and `never_seen` are deliberately different statuses, not one
+"bad" bucket: an operator debugs "this stopped" and "this never started"
+differently, and collapsing them would hide which one they're looking at.
+Jobs are declared in `escrow.yaml` up front, not discovered from whatever
+happens to have pinged -- a job that's only "known" because it once pinged
+would be exactly as invisible as before the first time it silently
+stopped, or if it never started.
+
+Exit code is `1` if anything is `overdue` or `never_seen`, `0` if every
+declared job is `ok`.
+
+## What this does NOT do
+
+- **No daemon, no background process.** There is no `escrow serve` or
+  `escrow watch`. `escrow check` is one CLI invocation that reads the
+  state file and exits; *you* supply the periodic trigger -- a cron
+  entry, a systemd timer, a scheduled GitHub Actions workflow. escrow
+  never runs unless something else runs it.
+- **No email, Slack, or webhook of its own.** The exit code is the
+  interface -- same convention [`receipt`](https://github.com/MaXiMo000/receipt),
+  [`invariant`](https://github.com/MaXiMo000/invariant), and
+  [`carabiner`](https://github.com/MaXiMo000/carabiner) already share.
+  Run `escrow check` as a step that fails loudly in whatever you already
+  have (a GitHub Actions job, a systemd `OnFailure=` unit, a cron entry
+  piped to your existing paging tool) rather than escrow adding its own
+  SMTP client or HTTP dependency for a notification path you may not want.
+- **Not a hosted or multi-machine service.** State is one JSON file; `ping`
+  and `check` need to see the same one. A fleet of machines all pinging a
+  shared endpoint needs a real datastore behind it, not a local file --
+  genuinely different scope, not built here.
+- **Not resilient to concurrent writers.** State is written to a temp file
+  and atomically renamed (a crash mid-write can't corrupt it), but two
+  `ping`s racing on the exact same job name on a network filesystem at the
+  same instant can still lose one update. Fine for the target use --one
+  job pings once per run-- not designed for high-frequency concurrent
+  writes.
+
+## Compared to a hosted dead-man's-switch
+
+[healthchecks.io](https://healthchecks.io), [Cronitor](https://cronitor.io),
+and [Dead Man's Snitch](https://deadmanssnitch.com) solve the same problem
+as a real, mature, hosted service: your job pings a URL over HTTPS, and
+their infrastructure -- not yours -- watches the clock and sends email/
+Slack/SMS/PagerDuty when a ping is late. If you want alerting that works
+without you also solving alerting, and don't mind a third party knowing
+when your jobs run, one of those is very likely the better choice --
+escrow doesn't compete with that and isn't trying to.
+
+escrow's tradeoff runs the other way, matching the same "stays on your
+machine" discipline as the rest of this portfolio: `ping` and `check` never
+leave the filesystem, there's no account, no third party ever learns your
+job names or schedule, and the whole state is one JSON file you can read,
+back up, or delete yourself. The cost of that is everything a hosted
+service gives you for free: no scheduling (see "no daemon," above) and no
+notification path of its own (see above) -- you supply both, from
+infrastructure you already have. Reach for escrow specifically when a
+third-party dependency for "is my cron job still running" is the wrong
+tradeoff for what the job actually does; reach for a hosted switch
+otherwise.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_duration.py   # "26h", "8d" -> seconds
+python tests/test_config.py     # escrow.yaml validation
+python tests/test_state.py      # the ping record: real files, real temp dirs
+python tests/test_check.py      # ok / overdue / never_seen classification
+python tests/test_cli.py        # the real CLI entry point, real files, real argv
+```
+
+41 tests. Two exist because testing an actual misconfigured `--state`
+(pointed at a directory instead of a file) found a real gap: `load_state`
+only caught `JSONDecodeError`, so `IsADirectoryError` -- also an `OSError`
+-- escaped as a raw traceback instead of the same graceful "nothing
+recorded yet" every other unreadable state file gets.
+
+MIT licensed.

escrow_evidence-0.1.0/escrow_evidence.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+escrow/__init__.py
+escrow/check.py
+escrow/cli.py
+escrow/config.py
+escrow/duration.py
+escrow/state.py
+escrow_evidence.egg-info/PKG-INFO
+escrow_evidence.egg-info/SOURCES.txt
+escrow_evidence.egg-info/dependency_links.txt
+escrow_evidence.egg-info/entry_points.txt
+escrow_evidence.egg-info/requires.txt
+escrow_evidence.egg-info/top_level.txt
+tests/test_check.py
+tests/test_cli.py
+tests/test_config.py
+tests/test_duration.py
+tests/test_state.py

escrow_evidence-0.1.0/escrow_evidence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

escrow_evidence-0.1.0/escrow_evidence.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+escrow = escrow.cli:main

escrow_evidence-0.1.0/escrow_evidence.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

escrow_evidence-0.1.0/escrow_evidence.egg-info/top_level.txt

@@ -0,0 +1 @@
+escrow

escrow_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+# "escrow" was already taken on PyPI, same story as every sibling in this
+# portfolio (checked, not assumed). The installed command stays the short
+# name -- python-dateutil installs `dateutil`, this installs `escrow`.
+name = "escrow-evidence"
+version = "0.1.0"
+description = "A dead-man's-switch for cron/scheduled jobs: flags silence, not just failure -- the job that stopped running weeks ago that no alert ever caught."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["cron", "monitoring", "dead-mans-switch", "heartbeat", "evidence", "reliability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+# PyYAML for escrow.yaml -- the same real dependency `invariant` already
+# uses elsewhere in this portfolio for its own config file, not a new
+# convention introduced here.
+dependencies = ["PyYAML>=6.0"]
+
+urls.Homepage = "https://github.com/MaXiMo000/escrow"
+urls.Source = "https://github.com/MaXiMo000/escrow"
+urls.Issues = "https://github.com/MaXiMo000/escrow/issues"
+urls.Changelog = "https://github.com/MaXiMo000/escrow/releases"
+
+[project.scripts]
+escrow = "escrow.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["escrow*"]

escrow_evidence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

escrow_evidence-0.1.0/tests/test_check.py

@@ -0,0 +1,66 @@
+"""Run: python tests/test_check.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from escrow.check import NEVER_SEEN, OK, OVERDUE, check_jobs
+
+
+def _job(name: str, interval: str, seconds: float) -> dict:
+    return {"name": name, "interval": interval, "interval_seconds": seconds}
+
+
+class TestCheckJobs(unittest.TestCase):
+    def test_recently_pinged_job_is_ok(self):
+        jobs = [_job("nightly-backup", "26h", 26 * 3600)]
+        state = {"nightly-backup": {"last_seen": 1000.0}}
+        results = check_jobs(jobs, state, now=1000.0 + 3600)  # 1h ago
+        self.assertEqual(results[0]["status"], OK)
+
+    def test_a_job_past_its_interval_is_overdue(self):
+        jobs = [_job("nightly-backup", "26h", 26 * 3600)]
+        state = {"nightly-backup": {"last_seen": 1000.0}}
+        results = check_jobs(jobs, state, now=1000.0 + 30 * 3600)  # 30h ago
+        self.assertEqual(results[0]["status"], OVERDUE)
+        self.assertGreater(results[0]["overdue_by_seconds"], 0)
+
+    def test_exactly_at_the_interval_boundary_is_still_ok(self):
+        """The whole point of an interval is 'up to and including this
+        long is fine' -- past it, not at it, is what makes something
+        overdue."""
+        jobs = [_job("x", "1h", 3600)]
+        state = {"x": {"last_seen": 1000.0}}
+        results = check_jobs(jobs, state, now=1000.0 + 3600)
+        self.assertEqual(results[0]["status"], OK)
+
+    def test_a_job_that_never_pinged_is_never_seen_not_overdue(self):
+        """A different status on purpose: 'stopped running' and 'never
+        started' are different facts an operator needs to act on
+        differently, and collapsing them into one status would hide that."""
+        jobs = [_job("weekly-report", "8d", 8 * 86400)]
+        results = check_jobs(jobs, state={}, now=1000.0)
+        self.assertEqual(results[0]["status"], NEVER_SEEN)
+        self.assertIsNone(results[0]["last_seen"])
+
+    def test_multiple_jobs_are_each_evaluated_independently(self):
+        jobs = [
+            _job("a", "1h", 3600),
+            _job("b", "1h", 3600),
+            _job("c", "1h", 3600),
+        ]
+        state = {
+            "a": {"last_seen": 1000.0},           # will be ok
+            "b": {"last_seen": 1000.0 - 10000},   # will be overdue
+            # "c" never pinged
+        }
+        results = check_jobs(jobs, state, now=1000.0)
+        statuses = {r["name"]: r["status"] for r in results}
+        self.assertEqual(statuses, {"a": OK, "b": OVERDUE, "c": NEVER_SEEN})
+
+
+if __name__ == "__main__":
+    unittest.main()

escrow_evidence-0.1.0/tests/test_cli.py

@@ -0,0 +1,89 @@
+"""Run: python tests/test_cli.py
+
+Exercises the real CLI entry point end to end -- real temp files, real
+argv, real stdout capture.
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import pathlib
+import sys
+import tempfile
+import time
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from escrow.cli import main
+
+
+class TestCli(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dir = pathlib.Path(self.tmp.name)
+        self.config = self.dir / "escrow.yaml"
+        self.state = self.dir / "state.json"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_ping_then_check_reads_ok(self):
+        self.config.write_text("jobs:\n  - name: nightly-backup\n    interval: 26h\n")
+        code = main(["ping", "nightly-backup", "--state", str(self.state)])
+        self.assertEqual(code, 0)
+
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", str(self.config), "--state", str(self.state)])
+        self.assertEqual(code, 0)
+        self.assertIn("[OK]", buf.getvalue())
+        self.assertIn("1/1 ok", buf.getvalue())
+
+    def test_never_pinged_job_fails_check(self):
+        self.config.write_text("jobs:\n  - name: weekly-report\n    interval: 8d\n")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", str(self.config), "--state", str(self.state)])
+        self.assertEqual(code, 1)
+        self.assertIn("[??]", buf.getvalue())
+        self.assertIn("need attention", buf.getvalue())
+
+    def test_overdue_job_fails_check(self):
+        self.config.write_text("jobs:\n  - name: nightly-backup\n    interval: 1h\n")
+        self.state.write_text(json.dumps({"nightly-backup": {"last_seen": time.time() - 7200}}))
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", str(self.config), "--state", str(self.state)])
+        self.assertEqual(code, 1)
+        self.assertIn("[!!]", buf.getvalue())
+
+    def test_state_path_that_is_a_directory_is_a_clean_error_on_ping(self):
+        """Found by testing an actual misconfigured --state: recording a
+        ping into a path that's a directory used to raise IsADirectoryError
+        straight out of main() as a traceback."""
+        state_dir = self.dir / "a_directory"
+        state_dir.mkdir()
+        with self.assertRaises(SystemExit) as ctx:
+            main(["ping", "x", "--state", str(state_dir)])
+        self.assertIn("escrow:", str(ctx.exception))
+
+    def test_bad_config_is_a_clean_error_not_a_traceback(self):
+        self.config.write_text("not: a valid escrow config\n")
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", str(self.config), "--state", str(self.state)])
+        self.assertIn("escrow:", str(ctx.exception))
+
+    def test_json_flag_prints_the_full_report(self):
+        self.config.write_text("jobs:\n  - name: x\n    interval: 1h\n")
+        main(["ping", "x", "--state", str(self.state)])
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            main(["check", str(self.config), "--state", str(self.state), "--json"])
+        report = json.loads(buf.getvalue())
+        self.assertEqual(report[0]["status"], "ok")
+
+
+if __name__ == "__main__":
+    unittest.main()

escrow_evidence-0.1.0/tests/test_config.py

@@ -0,0 +1,94 @@
+"""Run: python tests/test_config.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from escrow.config import ConfigError, load_config
+
+
+class TestLoadConfig(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.path = pathlib.Path(self.tmp.name) / "escrow.yaml"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _write(self, text: str) -> str:
+        self.path.write_text(text, encoding="utf-8")
+        return str(self.path)
+
+    def test_valid_config(self):
+        p = self._write("jobs:\n  - name: nightly-backup\n    interval: 26h\n")
+        jobs = load_config(p)
+        self.assertEqual(jobs, [{
+            "name": "nightly-backup", "interval": "26h", "interval_seconds": 26 * 3600,
+        }])
+
+    def test_multiple_jobs(self):
+        p = self._write(
+            "jobs:\n"
+            "  - name: nightly-backup\n    interval: 26h\n"
+            "  - name: weekly-report\n    interval: 8d\n"
+        )
+        jobs = load_config(p)
+        self.assertEqual([j["name"] for j in jobs], ["nightly-backup", "weekly-report"])
+
+    def test_missing_file_is_a_config_error_not_a_crash(self):
+        with self.assertRaises(ConfigError) as ctx:
+            load_config(str(self.path))  # never written
+        self.assertIn(str(self.path), str(ctx.exception))
+
+    def test_not_yaml_is_a_config_error(self):
+        p = self._write("not: valid: yaml: at: all:::")
+        with self.assertRaises(ConfigError):
+            load_config(p)
+
+    def test_missing_jobs_key_is_rejected(self):
+        p = self._write("something_else: true\n")
+        with self.assertRaises(ConfigError) as ctx:
+            load_config(p)
+        self.assertIn("jobs", str(ctx.exception))
+
+    def test_empty_jobs_list_is_rejected(self):
+        p = self._write("jobs: []\n")
+        with self.assertRaises(ConfigError):
+            load_config(p)
+
+    def test_job_missing_name_is_rejected(self):
+        p = self._write("jobs:\n  - interval: 1h\n")
+        with self.assertRaises(ConfigError) as ctx:
+            load_config(p)
+        self.assertIn("name", str(ctx.exception))
+
+    def test_job_missing_interval_is_rejected(self):
+        p = self._write("jobs:\n  - name: x\n")
+        with self.assertRaises(ConfigError) as ctx:
+            load_config(p)
+        self.assertIn("interval", str(ctx.exception))
+
+    def test_duplicate_job_names_are_rejected(self):
+        p = self._write("jobs:\n  - name: x\n    interval: 1h\n  - name: x\n    interval: 2h\n")
+        with self.assertRaises(ConfigError) as ctx:
+            load_config(p)
+        self.assertIn("duplicate", str(ctx.exception))
+
+    def test_invalid_interval_reports_which_job(self):
+        p = self._write("jobs:\n  - name: x\n    interval: not-a-duration\n")
+        with self.assertRaises(ConfigError) as ctx:
+            load_config(p)
+        self.assertIn("'x'", str(ctx.exception))
+
+    def test_top_level_list_instead_of_mapping_is_rejected(self):
+        p = self._write("- just\n- a\n- list\n")
+        with self.assertRaises(ConfigError):
+            load_config(p)
+
+
+if __name__ == "__main__":
+    unittest.main()

escrow_evidence-0.1.0/tests/test_duration.py

@@ -0,0 +1,55 @@
+"""Run: python tests/test_duration.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from escrow.duration import DurationError, parse_duration
+
+
+class TestParseDuration(unittest.TestCase):
+    def test_seconds(self):
+        self.assertEqual(parse_duration("30s"), 30)
+
+    def test_minutes(self):
+        self.assertEqual(parse_duration("45m"), 45 * 60)
+
+    def test_hours(self):
+        self.assertEqual(parse_duration("26h"), 26 * 3600)
+
+    def test_days(self):
+        self.assertEqual(parse_duration("8d"), 8 * 86400)
+
+    def test_weeks(self):
+        self.assertEqual(parse_duration("2w"), 2 * 604800)
+
+    def test_decimal_value(self):
+        self.assertEqual(parse_duration("1.5h"), 1.5 * 3600)
+
+    def test_whitespace_is_stripped(self):
+        self.assertEqual(parse_duration("  26h  "), 26 * 3600)
+
+    def test_combined_units_are_rejected_with_a_clear_message(self):
+        with self.assertRaises(DurationError) as ctx:
+            parse_duration("1d12h")
+        self.assertIn("not a duration", str(ctx.exception))
+        self.assertIn("36h", str(ctx.exception))  # the suggested workaround
+
+    def test_missing_unit_is_rejected(self):
+        with self.assertRaises(DurationError):
+            parse_duration("26")
+
+    def test_unknown_unit_is_rejected(self):
+        with self.assertRaises(DurationError):
+            parse_duration("26x")
+
+    def test_empty_string_is_rejected(self):
+        with self.assertRaises(DurationError):
+            parse_duration("")
+
+
+if __name__ == "__main__":
+    unittest.main()

escrow_evidence-0.1.0/tests/test_state.py

@@ -0,0 +1,67 @@
+"""Run: python tests/test_state.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from escrow.state import load_state, record_ping, save_state
+
+
+class TestState(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.path = str(pathlib.Path(self.tmp.name) / "state.json")
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_missing_state_file_is_empty_not_a_crash(self):
+        self.assertEqual(load_state(self.path), {})
+
+    def test_record_ping_creates_the_file(self):
+        record_ping(self.path, "nightly-backup", 1000.0)
+        state = load_state(self.path)
+        self.assertEqual(state["nightly-backup"]["last_seen"], 1000.0)
+
+    def test_second_ping_updates_the_same_job(self):
+        record_ping(self.path, "nightly-backup", 1000.0)
+        record_ping(self.path, "nightly-backup", 2000.0)
+        state = load_state(self.path)
+        self.assertEqual(len(state), 1)
+        self.assertEqual(state["nightly-backup"]["last_seen"], 2000.0)
+
+    def test_pinging_different_jobs_keeps_both(self):
+        record_ping(self.path, "a", 1000.0)
+        record_ping(self.path, "b", 2000.0)
+        state = load_state(self.path)
+        self.assertEqual(set(state), {"a", "b"})
+
+    def test_corrupted_state_file_reads_as_empty_not_a_crash(self):
+        pathlib.Path(self.path).write_text("not valid json {{{", encoding="utf-8")
+        self.assertEqual(load_state(self.path), {})
+
+    def test_state_path_that_is_a_directory_reads_as_empty_not_a_crash(self):
+        """Found by testing an actual misconfigured --state pointed at a
+        directory: load_state used to only catch JSONDecodeError, and
+        IsADirectoryError (also an OSError) escaped uncaught."""
+        dir_path = str(pathlib.Path(self.tmp.name) / "a_directory")
+        pathlib.Path(dir_path).mkdir()
+        self.assertEqual(load_state(dir_path), {})
+
+    def test_save_state_creates_parent_directories(self):
+        nested = str(pathlib.Path(self.tmp.name) / "a" / "b" / "state.json")
+        save_state(nested, {"x": {"last_seen": 1.0}})
+        self.assertEqual(load_state(nested), {"x": {"last_seen": 1.0}})
+
+    def test_no_leftover_temp_file_after_a_normal_save(self):
+        save_state(self.path, {"x": {"last_seen": 1.0}})
+        leftovers = list(pathlib.Path(self.tmp.name).glob(".escrow-*"))
+        self.assertEqual(leftovers, [])
+
+
+if __name__ == "__main__":
+    unittest.main()